diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md
new file mode 100644
index 0000000000..e1110a3b33
--- /dev/null
+++ b/PR_DESCRIPTION.md
@@ -0,0 +1,124 @@
+# [Design] Self-Healing Locators for Datagrok UI Tests
+
+> **Status:** Design proposal. No executable code in this PR.
+> **Goal:** Get reviewer alignment on architecture, fingerprint schema, prompt
+> contract, healing policy, and rollout plan **before** any code is written.
+
+## TL;DR
+
+UI tests in Datagrok (package tests on Puppeteer, plus a growing Playwright E2E
+suite) break when the DOM, CSS, or labels shift. This proposal introduces a
+two-phase **self-healing locator** system:
+
+- **Runtime fallback** (library, no LLM): when a selector misses, a
+  deterministic resolver walks a 4-tier priority hierarchy (semantic IDs →
+  stable structural → text content → visual/positional) using a
+  **fingerprint** captured during green test runs. A confidence score gates
+  the outcome: high → heal silently, mid → heal + flag for review, low →
+  fail the test.
+- **Offline maintenance** (CLI, uses Claude API): low-confidence and
+  unresolved cases land in a queue. A separate tool prompts Claude with the
+  fingerprint + accessibility tree, validates each proposed selector against
+  a live page in headless Puppeteer/Playwright, and opens a follow-up PR
+  with codemod'd test source updates.
+
+The two phases share one fingerprint schema, one confidence model, and one
+audit log format. The LLM is the **last resort**, not the first move.
+
+## What's in this PR (design only)
+
+```
+libraries/self-healing-locators/
+  README.md
+  docs/
+    01-design.md                 [FULL]
+    02-fingerprint-spec.md       [FULL]
+    03-confidence-model.md       [FULL]
+    04-runtime-flow.md           [FULL]
+    05-offline-flow.md           [FULL]
+    06-datagrok-integration.md   [COMPACT]
+    07-policy.md                 [FULL]
+    08-review-process.md         [COMPACT]
+    09-eval-and-rollout.md       [COMPACT]
+  prompts/
+    system.md                    [FULL]
+    user-template.md             [FULL]
+    examples/
+      01-testid-rename.md
+      02-aria-label-change.md
+      03-structural-refactor.md
+  schemas/
+    fingerprint.schema.json
+    healing-event.schema.json
+    tool-response.schema.json
+  api/
+    healing-api.md               [FULL]
+
+tools/self-healing-cli/
+  README.md
+  docs/
+    cli-overview.md              [COMPACT]
+```
+
+## Decisions baked into this proposal
+
+| Decision | Choice | Where it's discussed |
+|---|---|---|
+| Project location | `libraries/self-healing-locators` + `tools/self-healing-cli` | `01-design.md` |
+| Healing mode | Hybrid: runtime fallback + offline source updates | `04-runtime-flow.md`, `05-offline-flow.md` |
+| LLM provider | Anthropic Claude API | `05-offline-flow.md` |
+| Model strategy | Tiered: Haiku → Sonnet → Opus | `05-offline-flow.md` § "Model selection" |
+| Fingerprint storage | Centralized JSON registry under `libraries/self-healing-locators/registry/` (not in this PR) | `02-fingerprint-spec.md` § "Storage" |
+| Fingerprint capture | Passive (auto-update on green runs) + explicit (`healing.anchor()` API) | `api/healing-api.md` |
+| Screenshots | Feature-flagged, off by default | `02-fingerprint-spec.md` § "Visual layer" |
+| LLM in runtime | **No.** Runtime is deterministic and fast. | `04-runtime-flow.md` |
+| Source code mutation | Offline only, via codemod, gated by PR review | `05-offline-flow.md` § "Codemod & PR" |
+
+## Review focus
+
+Please read in this order — each doc is short and self-contained:
+
+1. **`01-design.md`** — confirm overall shape and component boundaries
+2. **`07-policy.md`** — confirm the "what we heal vs what we let fail" boundary
+3. **`02-fingerprint-spec.md`** — confirm the schema before we lock it in
+4. **`prompts/system.md` + `prompts/user-template.md`** — confirm the contract with Claude
+5. **`03-confidence-model.md`** — confirm the weights and thresholds (these are calibratable, not hardcoded forever)
+6. The rest — orientation only
+
+## Explicit non-goals
+
+- We do **not** propose changes to the Datagrok platform itself in this PR.
+  Any `getWidgetStatus()` extensions or new `data-testid` conventions are
+  noted as recommendations in `06-datagrok-integration.md`, to be addressed
+  separately.
+- We do **not** heal anything beyond locators. Assertions, timing, navigation,
+  and test logic are out of scope. See `07-policy.md` for the rationale.
+- We do **not** mutate test source files automatically without a PR.
+
+## Open questions (please flag in review)
+
+1. **Registry location** — should fingerprints live next to tests, in a
+   sibling directory, or in a single central registry? See
+   `02-fingerprint-spec.md` § "Storage" for trade-offs.
+2. **Failure budget** — what's the acceptable number of LLM-suggested heals
+   per week before we treat it as a signal that the platform needs more
+   stable test IDs?
+3. **PR ownership** — when the offline tool opens a PR, who is the default
+   reviewer? Test author? QA team? Code owners of the affected package?
+4. **Cost ceiling** — concrete dollar limit per offline run before the tool
+   pauses and asks for human approval.
+
+## After this PR is approved
+
+- Iterate on review comments until docs are signed off.
+- Open implementation PRs in this order:
+  1. `libraries/self-healing-locators` core types + fingerprint capture
+  2. Runtime resolver + confidence scorer (no LLM)
+  3. Audit log + healing queue writer
+  4. `tools/self-healing-cli` skeleton + Claude client
+  5. Prompt + tool_use response validation
+  6. Candidate validator (headless browser)
+  7. Codemod + PR opener
+  8. Eval harness + first 30-50 fixtures
+
+Each step is independently reviewable and shippable behind a feature flag.
diff --git a/libraries/self-healing-locators/README.md b/libraries/self-healing-locators/README.md
new file mode 100644
index 0000000000..d62a8384eb
--- /dev/null
+++ b/libraries/self-healing-locators/README.md
@@ -0,0 +1,52 @@
+# @datagrok-libraries/self-healing-locators
+
+Resilient UI element discovery for Datagrok tests. When a primary selector
+breaks because of a UI change, this library finds the same element through
+alternative signals and reports its confidence in the match.
+
+## Status
+
+**Design phase.** This directory currently contains design docs, schemas, and
+prompt specs only. No runtime code has been written yet. See
+[`docs/01-design.md`](./docs/01-design.md) for the proposed architecture and
+[`PR_DESCRIPTION.md`](../../PR_DESCRIPTION.md) at the repo root for the rollout
+plan.
+
+## What this library does (when implemented)
+
+- Captures **fingerprints** of UI elements during green test runs — semantic
+  IDs, ARIA roles, stable classes, parent chain, visible text, optional
+  visual hash, and Datagrok widget metadata via `getWidgetStatus()`.
+- At runtime, when a primary selector misses, walks a 4-tier priority
+  hierarchy (semantic → structural → text → visual) to relocate the
+  element, **without calling an LLM**.
+- Computes a **confidence score** for the match. High confidence heals
+  silently; mid-confidence heals but flags for review; low confidence fails
+  the test and queues the case for offline analysis.
+- Writes an **audit log** for every healing decision.
+
+The companion CLI in [`tools/self-healing-cli`](../../tools/self-healing-cli)
+handles offline maintenance: it consumes the queue, calls Claude to propose
+new selectors for hard cases, validates them against a live page, and opens
+a PR with updated test sources.
+
+## What this library does **not** do
+
+- Does not call any LLM at runtime. Tests stay fast and offline-capable.
+- Does not heal assertions, timing, or test logic. Locators only.
+- Does not mutate test source files. Source edits happen via codemod in the
+  offline CLI, behind a PR.
+
+## Quick links
+
+- [Architecture overview](./docs/01-design.md)
+- [Fingerprint schema](./docs/02-fingerprint-spec.md)
+- [Confidence model](./docs/03-confidence-model.md)
+- [Runtime flow](./docs/04-runtime-flow.md)
+- [Offline flow](./docs/05-offline-flow.md)
+- [Healing policy](./docs/07-policy.md)
+- [Public API](./api/healing-api.md)
+
+## License
+
+Same as the parent repository.
diff --git a/libraries/self-healing-locators/api/healing-api.md b/libraries/self-healing-locators/api/healing-api.md
new file mode 100644
index 0000000000..54331afa2d
--- /dev/null
+++ b/libraries/self-healing-locators/api/healing-api.md
@@ -0,0 +1,194 @@
+# Healing API
+
+> Status: full detail. This is the surface test authors see and depend on.
+
+## Module
+
+```ts
+import * as healing from '@datagrok-libraries/self-healing-locators';
+```
+
+The library is framework-agnostic at the type level. Concrete adapters
+ship for Puppeteer (used by Datagrok package tests) and Playwright
+(used by the standalone E2E suite). The core API works the same way
+through either adapter.
+
+## Configuration
+
+Done once per test process, typically in a global setup file.
+
+```ts
+healing.configure({
+  registryPath: 'libraries/self-healing-locators/registry/v1',
+  auditLogPath: 'test-output/self-healing/locator-events.jsonl',
+  queuePath:    'test-output/self-healing/healing-queue.jsonl',
+  thresholds: { high: 0.80, mid: 0.55 },
+  enableScreenshots: false,
+  enableTier4Visual: false,
+  primarySelectorTimeoutMs: 1000,
+  perTierBudgetMs: { tier1: 200, tier2: 300, tier3: 200, tier4: 500 },
+  // Optional overrides; see docs/03-confidence-model.md for defaults
+  weights: undefined,
+});
+```
+
+`configure()` is idempotent. Calling it twice with identical options is
+a no-op. Calling it with conflicting options throws — config is global
+state, but it's not mutable global state.
+
+## Core: `resolve()`
+
+The drop-in replacement for `page.locator(selector)`.
+
+```ts
+const element = await healing.resolve(page, '[data-testid="submit"]', {
+  anchorName?: string;          // explicit name; auto-derived otherwise
+  action?: 'click' | 'type' | 'assert' | 'read' | 'hover';
+  purpose?: 'normal' | 'destructive' | 'auth';  // policy hint
+});
+```
+
+Returns the framework's element handle (Puppeteer `ElementHandle`,
+Playwright `Locator`). Callers use it normally — `await element.click()`,
+etc.
+
+Behavior:
+
+1. Tries the primary selector (with the configured timeout).
+2. On miss, runs the resolver chain.
+3. Returns the resolved element on HIGH or MID; throws on LOW or fail.
+4. Writes one audit event per call (success or fail).
+
+If the primary selector hits, `resolve()` is just a passive
+fingerprint-refresh wrapper with negligible overhead.
+
+## Explicit anchors: `anchor()`
+
+Preferred for critical paths. Forces an explicit name and surfaces
+metadata into the fingerprint.
+
+```ts
+const submit = await healing.anchor(page, 'login-submit', {
+  selector: '[data-testid="submit"]',
+  action: 'click',
+  purpose: 'auth',
+});
+await submit.click();
+```
+
+Equivalent to `resolve()` with `anchorName: 'login-submit'`, but:
+
+- The `anchorName` is required, not derived. Renames go through a
+  deprecation path (see § "Renaming anchors").
+- The `purpose` field is recorded in the fingerprint and influences
+  the policy gates (e.g. `auth` requires explicit anchors; the policy
+  refuses to heal auto-derived anchors on auth flows).
+- The library can attach optional fingerprint hints
+  (`hints.elementIsInsideViewer`) without the author having to compute
+  them.
+
+## Renaming anchors
+
+Anchor names are part of the contract between tests and the registry.
+A rename is a deliberate refactor, not a silent fix.
+
+```ts
+healing.deprecateAnchor('old-name', { until: '2026-09-01' });
+const submit = await healing.anchor(page, 'new-name', { ... });
+```
+
+The library:
+
+- Loads both fingerprints; new anchor inherits from old until the
+  deadline.
+- Writes a warning to the audit log on each use of the old name.
+- After the deadline, the old anchor is pruned by `grok-heal registry prune`.
+
+## Reading the audit log
+
+For dashboards, custom reporters, or test-time introspection.
+
+```ts
+const events = await healing.audit.read({ since: '2026-04-01' });
+const counters = healing.audit.snapshot();
+// counters: { total_resolves, primary_hits, tier1_hits, ..., failed }
+```
+
+The audit log is jsonl, append-only. The library exposes a streaming
+reader so consumers do not have to parse it themselves.
+
+## Marking review decisions
+
+After a healing PR is reviewed, decisions feed back to the offline tool
+so it doesn't re-propose the same heal next run.
+
+```ts
+// Programmatic alternative to `grok-heal mark`
+await healing.audit.markCase(caseId, {
+  decision: 'accepted' | 'rejected',
+  reason?: string,
+});
+```
+
+Programmatic marking is mostly for the CLI; humans typically use
+`grok-heal mark` from the command line.
+
+## Error types
+
+```ts
+class HealingError extends Error {
+  caseId: string;
+  reason:
+    | 'no_fingerprint'
+    | 'all_tiers_missed'
+    | 'ambiguous_candidates'
+    | 'low_confidence'
+    | 'platform_version_skew'
+    | 'registry_corrupt'
+    | 'unhealable_destructive'
+    | 'unhealable_auth';
+  details: { /* per-reason fields */ };
+}
+```
+
+`HealingError` extends `Error` so existing test reporters render it
+sensibly. The `caseId` lets a developer pull up the audit entry directly
+from the failure message.
+
+## What the API never does
+
+- **Never returns null silently.** Either resolves to an element or
+  throws. There is no in-band "didn't find it" sentinel.
+- **Never retries on transient failures.** That's the test framework's
+  job. Self-healing fixes locator drift, not flakiness.
+- **Never logs to stdout.** All logging goes through the audit log or
+  a configurable logger callback.
+- **Never makes network calls.** No metrics services, no telemetry, no
+  Anthropic SDK in this package.
+
+## Adapter packages
+
+The core library exposes interfaces; adapters implement them.
+
+```
+@datagrok-libraries/self-healing-locators                  // core
+@datagrok-libraries/self-healing-locators-puppeteer        // adapter
+@datagrok-libraries/self-healing-locators-playwright       // adapter
+```
+
+Adapters are thin: they translate between core types and the
+framework's element/page types, and they implement the framework-specific
+parts of fingerprint capture (taking a screenshot, reading the
+accessibility tree, etc.).
+
+The Datagrok Puppeteer test framework uses the Puppeteer adapter. The
+Playwright E2E suite uses the Playwright adapter. The core API surface
+is identical from the test author's perspective.
+
+## API stability
+
+- `1.0` is the first stable release; signatures above ship as is.
+- Pre-1.0 versions may evolve based on early-adopter feedback from the
+  volunteer package(s) in Stage 2 of the rollout.
+- Breaking changes after 1.0 follow standard semver and require a
+  deprecation window of at least one minor version.
diff --git a/libraries/self-healing-locators/docs/01-design.md b/libraries/self-healing-locators/docs/01-design.md
new file mode 100644
index 0000000000..80093d48fa
--- /dev/null
+++ b/libraries/self-healing-locators/docs/01-design.md
@@ -0,0 +1,300 @@
+# 01 — Design Overview
+
+> Status: full detail. This is one of the documents to read carefully.
+
+## 1. Problem statement
+
+Datagrok UI tests — both the package tests on the Puppeteer-based framework
+and the growing Playwright E2E suite — fail when the DOM, CSS classes, ARIA
+labels, or text content shift between releases. The failures are not real
+regressions; they are locator drift. Today the cost of locator drift is paid
+by humans who hand-edit tests after each platform or package release.
+
+The goal of this proposal is to absorb routine drift automatically while
+preserving the ability of tests to fail loudly when something genuinely
+broke in the product.
+
+## 2. Design principles
+
+These are the non-negotiables. Every detail downstream serves them.
+
+**P1. The LLM is the last resort, not the first move.** Most drift is
+trivial: a class renamed, a `data-testid` updated, a wrapper added. A
+deterministic resolver that walks a priority hierarchy resolves the vast
+majority of cases at zero cost and with no nondeterminism. Only what cannot
+be resolved deterministically gets escalated to Claude, and only offline.
+
+**P2. Real bugs must surface.** Self-healing must never mask a regression.
+If a button is gone or its semantics changed, the test fails. The
+confidence model is the gatekeeper here — it is computed from objective
+matches against a fingerprint captured when the test last passed, not from
+an LLM's self-reported confidence.
+
+**P3. Every heal is auditable.** Every decision — resolved by which tier,
+what matched, what didn't, what the resulting confidence was, who or what
+approved it — is written to a structured log. Without this, the system
+becomes a black box that quietly hides failures.
+
+**P4. Source code mutation is gated by a human.** The offline tool produces
+a PR. It does not commit directly to a branch that anything depends on. A
+human reviews the diff and merges.
+
+**P5. Runtime is fast and offline-capable.** No network calls, no LLM, no
+external services in the runtime path. Everything required at runtime ships
+with the library and the fingerprint registry.
+
+**P6. The system is calibratable, not hardcoded.** Weights, thresholds,
+model selection rules, and prompt templates are configuration, not code.
+Teams can tune them without forking the library.
+
+## 3. High-level architecture
+
+```
+                     ┌──────────────────────────────┐
+                     │  Test Authoring / Recording  │
+                     │                              │
+                     │  Fingerprints captured       │
+                     │  during green runs and via   │
+                     │  explicit healing.anchor()   │
+                     └──────────────┬───────────────┘
+                                    │
+                                    ▼
+                     ┌──────────────────────────────┐
+                     │   Fingerprint Registry       │
+                     │   (versioned JSON files)     │
+                     └──────────────┬───────────────┘
+                                    │
+                ┌───────────────────┴────────────────────┐
+                │                                        │
+                ▼                                        ▼
+   ┌───────────────────────────┐         ┌──────────────────────────────┐
+   │  RUNTIME (library)        │         │  OFFLINE (CLI tool)          │
+   │                           │         │                              │
+   │  ┌─────────────────────┐  │         │  ┌────────────────────────┐  │
+   │  │  Locator Resolver   │  │         │  │  Queue Reader          │  │
+   │  │  Tier 1: semantic   │  │         │  │  (low-conf + failed    │  │
+   │  │  Tier 2: structural │  │         │  │   runtime cases)       │  │
+   │  │  Tier 3: text       │  │         │  └──────────┬─────────────┘  │
+   │  │  Tier 4: visual     │  │         │             ▼                │
+   │  └──────────┬──────────┘  │         │  ┌────────────────────────┐  │
+   │             ▼             │         │  │  Prompt Builder        │  │
+   │  ┌─────────────────────┐  │         │  │  (fingerprint + a11y   │  │
+   │  │  Confidence Scorer  │  │         │  │   tree + optional img) │  │
+   │  └──────────┬──────────┘  │         │  └──────────┬─────────────┘  │
+   │             ▼             │         │             ▼                │
+   │  ┌─────────────────────┐  │         │  ┌────────────────────────┐  │
+   │  │  Decision Gate      │  │         │  │  Claude Client         │  │
+   │  │  HIGH → heal        │  │         │  │  (Haiku → Sonnet →     │  │
+   │  │  MID  → heal+flag   │  │         │  │   Opus, tool_use)      │  │
+   │  │  LOW  → fail+queue  │  │         │  └──────────┬─────────────┘  │
+   │  └──────────┬──────────┘  │         │             ▼                │
+   │             ▼             │         │  ┌────────────────────────┐  │
+   │  ┌─────────────────────┐  │         │  │  Candidate Validator   │  │
+   │  │  Audit Log Writer   │  │         │  │  (headless browser,    │  │
+   │  └─────────────────────┘  │         │  │   re-scores via the    │  │
+   │             │             │         │  │   same scorer)         │  │
+   └─────────────┼─────────────┘         │  └──────────┬─────────────┘  │
+                 │                       │             ▼                │
+                 │                       │  ┌────────────────────────┐  │
+                 │                       │  │  Codemod + PR Opener   │  │
+                 │                       │  └────────────────────────┘  │
+                 │                       └──────────────┬───────────────┘
+                 │                                      │
+                 ▼                                      ▼
+   ┌──────────────────────────────────────────────────────────────────┐
+   │  Audit log (locator-events.jsonl)                                │
+   │  Healing queue (healing-queue.jsonl)                             │
+   │  Review dashboard (out of scope for this PR)                     │
+   └──────────────────────────────────────────────────────────────────┘
+```
+
+The two columns share three things:
+1. **The fingerprint schema** (`schemas/fingerprint.schema.json`).
+2. **The confidence scorer** — same code, same weights. The offline tool
+   re-scores Claude's proposals using the runtime scorer; Claude does not
+   get to vote on its own confidence.
+3. **The audit log format** (`schemas/healing-event.schema.json`).
+
+## 4. Component boundaries
+
+### 4.1 `libraries/self-healing-locators` (runtime library)
+
+A `@datagrok-libraries/*` package consumed by:
+- Datagrok package tests (Puppeteer-based)
+- Standalone Playwright projects (E2E suite)
+
+Exports:
+- `healing.anchor(name, element)` — explicit fingerprint capture
+- `healing.resolve(selector, options)` — drop-in replacement for
+  `page.$(selector)` / `page.locator(selector)` that triggers the resolver
+  on miss
+- `healing.configure(opts)` — thresholds, registry path, audit log path,
+  feature flags
+- `healing.audit` — read-side API for tools and dashboards
+
+No dependency on the Anthropic SDK. No network code at all.
+
+See [`api/healing-api.md`](../api/healing-api.md) for the full surface.
+
+### 4.2 `tools/self-healing-cli` (offline CLI)
+
+A `tools/*` package, in line with `datagrok-tools`. Distributed as an npm
+binary. Depends on:
+- `@datagrok-libraries/self-healing-locators` (for the shared scorer,
+  schemas, and registry I/O)
+- `@anthropic-ai/sdk` (Claude API client)
+- `puppeteer` or `playwright` for candidate validation
+
+Commands (sketch — finalized in `tools/self-healing-cli/docs/cli-overview.md`):
+
+```
+grok-heal queue              # show pending cases
+grok-heal run [--model auto] # process the queue
+grok-heal validate <case-id> # dry-run a single case
+grok-heal pr                 # open a PR with codemod'd changes
+grok-heal eval               # run the regression eval suite
+```
+
+The CLI is invoked from CI on a schedule (e.g. nightly) or manually after
+a release that produced runtime-queued cases.
+
+### 4.3 Fingerprint registry
+
+A versioned directory (location decided in this PR — see
+`02-fingerprint-spec.md` § "Storage") holding one JSON file per logical
+test or per package, depending on the chosen layout. Committed to git.
+Updates flow through normal review; the offline CLI does not bypass review.
+
+## 5. Data flow scenarios
+
+### Scenario A — Trivial drift, runtime resolves it
+
+1. Test calls `healing.resolve('[data-testid="submit"]')`.
+2. Selector misses (the platform renamed the testid to `submit-btn`).
+3. Resolver loads the fingerprint for that anchor.
+4. Tier 1 finds an element matching the recorded `ariaLabel + ariaRole`
+   pair. The fallback `testId` candidate `submit-btn` also matches the
+   same element.
+5. Scorer computes confidence ≥ HIGH.
+6. Decision gate heals silently. Test continues.
+7. Audit log records: `tier=1, confidence=0.92, matched=[ariaLabel,
+   ariaRole, testId-fuzzy], healed_selector='[data-testid="submit-btn"]'`.
+
+No LLM, no human involvement. Cost: a few milliseconds and one log line.
+
+### Scenario B — Structural change, runtime escalates
+
+1. The submit button is now nested inside a new `<form-actions>` wrapper
+   and its `data-testid` is gone.
+2. Tier 1 misses. Tier 2 finds an element matching tag, stable classes,
+   and one of three parent-chain levels — but the chain is shifted by one.
+3. Tier 3 matches on visible text "Submit". Tier 4 finds three elements
+   with similar bounding boxes; the right one is among them.
+4. Scorer computes confidence in the MID band: 0.62.
+5. Decision gate heals (test continues) but flags the case.
+6. Audit log records `flag=review`. The case is also written to
+   `healing-queue.jsonl` for offline analysis.
+7. Next nightly CLI run: Claude sees the fingerprint, the new a11y tree,
+   and proposes 3 candidate selectors. The validator confirms 1 of them
+   matches a single element with confidence ≥ HIGH under the runtime
+   scorer.
+8. CLI opens a PR updating the test source to use the new selector. A
+   human reviews and merges.
+
+### Scenario C — Real bug, system fails loudly
+
+1. The submit button was removed from the page entirely (refactor mistake).
+2. All four tiers miss or return only weak partial matches.
+3. Confidence < LOW threshold.
+4. Decision gate fails the test. The case is queued.
+5. CLI runs, Claude proposes selectors that the validator finds either
+   missing or pointing to different semantic elements (e.g. a "Cancel"
+   button in the same position).
+6. CLI marks the case `unable_to_heal` with reason
+   `no_semantic_match_in_dom`. No PR opened. The case is escalated to a
+   human via the review dashboard.
+
+This scenario is the entire point of P2. The system must produce this
+outcome reliably.
+
+## 6. What we deliberately keep out
+
+- **In-test LLM calls.** Latency, cost, nondeterminism. Forbidden.
+- **Auto-merge of healing PRs.** Even high-confidence offline heals get a
+  human reviewer, at least until the eval suite has earned trust.
+- **A separate ML model.** A scoring formula with calibrated weights is
+  enough for the deterministic tiers. If we later need a learned model,
+  we can swap the scorer; the architecture supports it.
+- **Healing of non-locator failures.** Timing flakes, network errors,
+  state-leak failures — different problems, different solutions. Mixing
+  them with locator healing dilutes both.
+- **A custom format for fingerprints.** Plain JSON, schema-validated. No
+  protobuf, no SQLite, no embeddings (yet).
+
+## 7. What is calibratable vs hardcoded
+
+| Calibratable (config) | Hardcoded (code) |
+|---|---|
+| Tier weights | Tier order |
+| Confidence thresholds (HIGH/MID/LOW) | Scoring formula shape |
+| Model selection rules | tool_use response schema |
+| Prompt templates | Audit log schema |
+| Feature flags (screenshots, etc.) | Public API surface |
+| Per-package overrides | Registry layout |
+
+Anything calibratable lives in `self-healing.config.json` next to the
+registry. Defaults ship with the library.
+
+## 8. Dependencies on the platform
+
+We rely on three platform capabilities. Two exist; one is a recommendation.
+
+**Exists:** `Widget.getWidgetStatus()` returns a runtime structure intended
+specifically for automated testing and introspection (per the JS API docs).
+We use this in Tier 1 as a Datagrok-specific semantic anchor.
+
+**Exists:** the Inspector tool (`Alt + I`) exposes the registered widget
+tree. The fingerprint capture utility taps into the same data source so
+fingerprints reflect the platform's own model of the page.
+
+**Recommended (not blocking):** a convention for `data-testid` attributes
+on common UI primitives (`ui.button`, `ui.input.*`, dialog headers,
+ribbon items). Without this, semantic Tier 1 match is weaker and we lean
+harder on text and structure. See
+[`06-datagrok-integration.md`](./06-datagrok-integration.md) for the
+specific suggestions.
+
+## 9. Failure modes we explicitly handle
+
+| Failure mode | Handling |
+|---|---|
+| Registry file missing | Treat as fresh capture; record for next green run |
+| Registry file stale (schema version mismatch) | Migration script; fail closed if migration is ambiguous |
+| All tiers miss with non-zero partial scores | Confidence < LOW → fail + queue |
+| Multiple candidates tied at HIGH | Fail closed, queue for offline disambiguation. Never guess. |
+| LLM API down | Offline CLI exits cleanly, queue persists |
+| LLM proposes selector that matches multiple elements | Validator rejects, marks as `ambiguous_match` |
+| LLM proposes selector that matches a different semantic element | Validator computes runtime score; if < HIGH, reject |
+| Codemod conflicts with concurrent edits | Skip case, requeue, notify in PR description |
+
+## 10. Why this shape
+
+We considered three alternatives and rejected them:
+
+**A. Pure runtime LLM healing.** Rejected: violates P1, P5, and creates a
+hard dependency on network availability for tests. Also: the audit story is
+weak because LLM reasoning isn't reliably reproducible.
+
+**B. Pure offline LLM rewriting (no runtime resolver).** Rejected: every
+trivial drift becomes a Claude call and a PR. Noise overwhelms signal,
+costs balloon, and the team starts ignoring PRs.
+
+**C. Visual-only matching (image diff + perceptual hash).** Rejected as a
+primary mechanism: too brittle for SPAs that re-render frequently, fails
+on dynamic content, and offers no semantic explanation when it errs.
+Visual signals stay as Tier 4 for cases where they genuinely help.
+
+The hybrid two-phase design absorbs trivial drift cheaply at runtime and
+escalates only what is genuinely hard. The LLM does what it's good at
+(reasoning over messy structure) without doing what it's bad at (being
+the source of truth for production-critical decisions).
diff --git a/libraries/self-healing-locators/docs/02-fingerprint-spec.md b/libraries/self-healing-locators/docs/02-fingerprint-spec.md
new file mode 100644
index 0000000000..535c07c53a
--- /dev/null
+++ b/libraries/self-healing-locators/docs/02-fingerprint-spec.md
@@ -0,0 +1,333 @@
+# 02 — Fingerprint Specification
+
+> Status: full detail. The fingerprint schema is the contract between
+> capture, runtime resolution, and the offline LLM. Lock this carefully.
+
+## 1. What a fingerprint is
+
+A fingerprint is a structured snapshot of an element captured when a test
+last passed. It contains enough orthogonal signals that, when the primary
+selector breaks, we can re-identify the same element through a different
+combination of signals — and quantify our confidence in the match.
+
+A fingerprint is not a CSS selector. It is the **evidence** we use to find
+or generate a working selector.
+
+## 2. Schema (informal)
+
+The formal JSON Schema lives in
+[`schemas/fingerprint.schema.json`](../schemas/fingerprint.schema.json).
+Here is the human-readable form, with rationale per field.
+
+```ts
+interface ElementFingerprint {
+  // Identity
+  schemaVersion: '1';
+  anchorName: string;            // logical name from healing.anchor()
+                                 // or auto-derived from selector + test
+  capturedAt: string;            // ISO 8601
+  capturedBy: 'auto' | 'explicit';
+  testRef: {
+    file: string;                // path relative to repo root
+    suite?: string;
+    test: string;
+    selectorAtCapture: string;   // the selector that worked
+  };
+
+  // Tier 1 — semantic
+  semantic: {
+    testId?: string;             // data-testid value, if any
+    domId?: string;              // id, only if it passes stability filter
+    ariaLabel?: string;
+    ariaRole?: string;           // button, dialog, tab, ...
+    name?: string;               // accessible name (from a11y tree)
+    dgWidgetType?: string;       // from getWidgetStatus(), e.g. 'Viewer'
+    dgViewerType?: string;       // e.g. 'scatter-plot', 'grid'
+  };
+
+  // Tier 2 — stable structural
+  structural: {
+    tagName: string;
+    stableClasses: string[];     // post-filter (see § 4)
+    parentChain: ParentLink[];   // up to 3 levels, see below
+    indexInParent?: number;      // last-resort sibling index
+  };
+
+  // Tier 3 — text content
+  text: {
+    visibleText?: string;        // normalized, trimmed, length-capped
+    placeholder?: string;
+    title?: string;
+    valueAtCapture?: string;     // for inputs, only if not sensitive
+  };
+
+  // Tier 4 — visual / positional
+  visual: {
+    boundingBox?: {              // viewport-relative at capture
+      x: number; y: number;
+      width: number; height: number;
+    };
+    viewportSize?: { w: number; h: number };
+    visualHash?: string;         // pHash; only when feature flag enabled
+    screenshotRef?: string;      // file path under registry, optional
+  };
+
+  // Stability hints discovered at capture time
+  hints: {
+    domIdLooksStable: boolean;   // see filter logic § 4
+    classesAreCssInJs: boolean;
+    textIsLikelyDynamic: boolean; // detected via heuristics, e.g. "Hello, $user"
+    elementIsInsideViewer?: string; // viewer type if applicable
+  };
+
+  // For the LLM and for debugging
+  contextSnippet: {
+    accessibilityNode?: object;  // a11y subtree at this element, depth 2
+    htmlSnippet?: string;        // sanitized outerHTML, truncated
+  };
+}
+
+interface ParentLink {
+  tagName: string;
+  testId?: string;
+  ariaRole?: string;
+  dgWidgetType?: string;
+  stableClasses?: string[];      // already filtered
+}
+```
+
+## 3. Why these fields and not others
+
+Every field justifies its weight in the scoring formula. We omit:
+
+- **XPath of the element.** Too brittle, encodes everything that drifts.
+  We reconstruct an XPath at runtime if needed; we never store one as
+  ground truth.
+- **Full outer HTML.** Heavy, leaky, encourages bad matching. We keep a
+  truncated snippet only as context for Claude in the offline phase.
+- **Computed styles.** Volatile across themes and platform versions.
+- **Event listeners.** Not observable reliably in headless contexts.
+- **Embeddings.** Not yet. Adds infrastructure and explainability cost
+  without a clear win at our current failure rates. Revisit after the
+  eval suite has data.
+
+We include:
+
+- **`name` from the accessibility tree** even when it duplicates `ariaLabel`
+  or `visibleText`. The a11y tree resolves these per the platform's
+  algorithm, which is what assistive tech and Playwright `getByRole` use.
+  Storing it makes Tier 1 matches more robust.
+- **`dgWidgetType` and `dgViewerType`** because Datagrok has a layer of
+  semantics above the DOM that most SPAs lack. Using it gives us a stable
+  anchor that survives many DOM-level changes.
+- **`hints`** because they are computed once at capture and used by both
+  the runtime resolver and the offline prompt. Storing them avoids
+  recomputation and ensures the LLM and the resolver see the same view.
+
+## 4. Normalization rules
+
+At capture, raw values pass through normalizers. Both capture and
+resolution use the same normalizers — the registry stores the **post-
+normalization** form. Normalizers are part of the library's public API
+because tests may need to reproduce them.
+
+### 4.1 `domId` stability filter
+
+A `domId` is recorded only if it passes all of:
+
+- length between 2 and 64
+- contains at least one lowercase letter
+- does not match a UUID-like pattern (`/^[0-9a-f-]{12,}$/i`)
+- does not match a hash-like pattern (`/^[a-zA-Z0-9_-]{6}$/` with high
+  entropy by Shannon estimate ≥ 4.5 bits/char)
+- is unique on the page at capture time
+
+If filtered, `domId` is `undefined` and `hints.domIdLooksStable = false`.
+
+### 4.2 Class filter
+
+A class survives into `stableClasses` only if:
+
+- it is not in the configured CSS-in-JS pattern list (default:
+  `/^css-[a-z0-9]{4,}$/`, `/^_[a-zA-Z0-9_]{6,}$/`,
+  Material/Emotion-style hash patterns)
+- it is not transient: not in `is-active`, `is-hover`, `is-focused`,
+  `is-selected`, etc. (configurable list)
+- it appears on at most 100 elements at capture time (uniqueness signal;
+  configurable threshold)
+
+The full filtered set is preserved in `hints.classesAreCssInJs` so we
+know whether class-based matching is even worth attempting.
+
+### 4.3 Text normalization
+
+- Trim and collapse whitespace.
+- Truncate to 200 characters; original length stored separately.
+- Detect dynamic patterns (interpolation markers, dates, counts,
+  user-specific strings) and set `hints.textIsLikelyDynamic`. The
+  detector is heuristic — see `prompts/examples/` for cases.
+
+### 4.4 Parent chain
+
+We store **at most 3 levels up**, stopping at:
+
+- the test view root (Datagrok view boundary)
+- a `<body>` or document root
+- a parent we can already identify uniquely by `testId` or `dgWidgetType`
+
+Storing more is wasteful; storing fewer makes structural matching too
+weak in deeply nested viewers.
+
+## 5. Visual layer (feature-flagged)
+
+By default the visual layer is **off**. Reasons:
+
+- Doubles capture time (screenshot + hash) on every green run.
+- Increases registry size by 1–10 KB per element when screenshots are
+  retained, plus the visual hash itself.
+- Per-deployment privacy considerations may apply to screenshot content.
+
+When the `screenshots` feature flag is on:
+
+- `visual.boundingBox` and `visual.viewportSize` are always captured
+  (cheap, no image content).
+- `visual.visualHash` is a perceptual hash (default: pHash) of the
+  element-only screenshot, computed locally. No image data leaves the
+  test machine if screenshots themselves are not retained.
+- `visual.screenshotRef` is set only when image retention is enabled,
+  pointing to a file under `registry/screenshots/<hash>.webp`.
+
+The offline prompt **may** include a screenshot as an `image` content
+block when the flag is on; the prompt template handles the absence
+gracefully.
+
+## 6. Storage
+
+The registry is a **versioned directory of JSON files**. Recommended layout:
+
+```
+libraries/self-healing-locators/registry/
+  v1/
+    packages/
+      <PackageName>/
+        <test-file-id>.fingerprints.json   # all anchors for one test file
+    e2e/
+      <suite-name>/
+        <test-id>.fingerprints.json
+    screenshots/                            # only if flag on
+      <hash>.webp
+  config/
+    self-healing.config.json
+    css-in-js-patterns.json
+```
+
+### 6.1 Why a central registry, not co-located files
+
+We considered three options:
+
+- **Option A — co-located** (`my.spec.ts` + `my.fingerprints.json` next to it).
+  Pros: discoverability, atomic moves with tests.
+  Cons: every test directory grows; harder to scan all fingerprints across
+  the repo for migrations or audits; spreads test concerns into product
+  package directories.
+
+- **Option B — central registry** (this proposal).
+  Pros: clear ownership boundary; bulk operations possible; schema
+  migrations live in one place; offline tools have a single source.
+  Cons: rename-a-test requires updating two places; PRs that touch many
+  tests touch the registry.
+
+- **Option C — Datagrok entity** (store in the platform itself).
+  Pros: collaboration features, sharing, history.
+  Cons: tests need to talk to the platform to read fingerprints, breaking
+  P5 (offline-capable). Also creates a circular dependency: platform tests
+  depend on the platform being up.
+
+We choose **B**. The registry is a sibling under
+`libraries/self-healing-locators/registry/` so the library and its data
+ship together. This is one of the open questions in the PR description —
+reviewers may push for co-location, in which case we adapt.
+
+### 6.2 File granularity
+
+One JSON file per **test file**, not per test or per anchor. This balances:
+
+- not too coarse (one giant file per package → merge conflicts)
+- not too fine (one file per anchor → thousands of tiny files)
+
+Within the file, anchors are keyed by `anchorName`. The capture API
+guarantees stable names; see `api/healing-api.md`.
+
+### 6.3 Versioning
+
+Schema version is in every file. The library's loader checks the version
+on read. Mismatch behavior:
+
+- Older version, known migration → migrate in memory, log a warning, write
+  back on next capture.
+- Older version, no migration → fail closed. Manual intervention required.
+- Newer version than library knows → fail closed. Library is too old.
+
+## 7. Capture lifecycle
+
+Two capture modes coexist; both produce identically-shaped fingerprints.
+
+### 7.1 Passive (auto-capture on green runs)
+
+When a test calls `healing.resolve(selector)` and the primary selector
+**works** (no fallback needed), the resolver records or refreshes the
+fingerprint for that anchor. Cost: a few milliseconds per call.
+
+Auto-derived `anchorName`: `<testFile>::<selector>`. Stable across runs
+of the same test, brittle if the test author changes the selector string
+(this is fine — that's a deliberate change).
+
+### 7.2 Explicit (`healing.anchor()`)
+
+```ts
+const submit = await healing.anchor('login-submit', page.locator('#submit'));
+await submit.click();
+```
+
+The author commits to a name. Renaming is a deliberate refactor with a
+deprecation path (see `api/healing-api.md`).
+
+Use explicit anchors for:
+
+- Critical-path elements where heal decisions need extra scrutiny.
+- Elements whose default auto-derived name would be ambiguous (selectors
+  built dynamically).
+- Elements where the author wants to attach metadata (`role`, `purpose`)
+  that informs the offline prompt.
+
+### 7.3 What we never do at capture
+
+- Capture during a flaky run. The library refuses to update a fingerprint
+  if the runtime resolver had to fall back to any tier beyond Tier 0
+  (primary selector worked exactly).
+- Capture sensitive content. The text normalizer has a configurable
+  redaction list; values matching it are stored as `<redacted>` and the
+  fingerprint records `text.valueAtCapture` only if the field is
+  whitelisted (e.g. button labels, never password fields).
+
+## 8. Lifecycle: when fingerprints are deleted
+
+- When a test is deleted (CI hook prunes orphaned anchors, opens
+  cleanup PR).
+- When `anchorName` changes (old entry kept for one minor version with
+  `deprecated: true` flag, then pruned).
+- Manually, via `grok-heal registry prune` for stale or known-broken
+  entries.
+
+The registry is not write-only. It must be maintainable.
+
+## 9. Open questions for review
+
+1. **Storage location** — central under the library, or co-located with
+   tests? See § 6.1.
+2. **Per-anchor TTL** — should fingerprints captured before a known
+   platform breaking-change release auto-expire?
+3. **Sensitive value handling** — is the redaction list approach enough,
+   or do we need a per-test opt-in for `valueAtCapture`?
+4. **Screenshot retention** — if the flag is on, do we store images in
+   the registry (large, slow) or only ephemerally during one CI run?
diff --git a/libraries/self-healing-locators/docs/03-confidence-model.md b/libraries/self-healing-locators/docs/03-confidence-model.md
new file mode 100644
index 0000000000..6af3429714
--- /dev/null
+++ b/libraries/self-healing-locators/docs/03-confidence-model.md
@@ -0,0 +1,204 @@
+# 03 — Confidence Model
+
+> Status: full detail. The confidence formula gates every healing decision.
+> Weights are calibratable; the formula's shape is not.
+
+## 1. What the confidence score is — and isn't
+
+It is: a number in `[0, 1]` indicating how strongly the candidate element
+matches the recorded fingerprint, computed from objective feature
+overlaps.
+
+It is not: an estimate from a language model. Claude does not produce a
+confidence number that we use directly. When the offline tool processes
+LLM proposals, the same scorer that runs at runtime re-scores each
+proposal against the live page. This is intentional — it puts the LLM
+and the runtime in the same evaluative frame and prevents the LLM from
+"talking itself" into a heal.
+
+## 2. Formula
+
+For a candidate element matched against a stored fingerprint:
+
+```
+score = sum_over_features( w_i * m_i ) / sum_over_features( w_i )
+
+where:
+  w_i = configured weight for feature i
+  m_i = match value in [0, 1] for feature i (0 if feature is absent
+        in either the candidate or the fingerprint)
+```
+
+This is a **weighted Jaccard-style ratio**, not an unbounded sum.
+Properties we get for free:
+
+- Score stays in `[0, 1]`. No artificial caps or normalizations later.
+- Missing features on either side don't penalize disproportionately —
+  they just don't contribute weight.
+- Adding new features changes the denominator too, so an existing
+  fingerprint with a missing new feature isn't suddenly downscored.
+
+## 3. Default weights
+
+Default weights, by tier. These are **starting values**. The eval suite
+will calibrate them on real Datagrok cases before the system is trusted
+in production.
+
+### Tier 1 — semantic
+
+| Feature | Weight | Match function |
+|---|---|---|
+| `testId` exact | 1.00 | binary |
+| `domId` exact (passes stability filter) | 0.90 | binary |
+| `ariaLabel` exact | 0.85 | binary |
+| `ariaRole` + accessible `name` exact | 0.85 | binary |
+| `dgWidgetType` + `dgViewerType` exact | 0.80 | binary |
+| `ariaLabel` fuzzy (Levenshtein ≥ 0.85) | 0.55 | proportional to similarity |
+
+### Tier 2 — structural
+
+| Feature | Weight | Match function |
+|---|---|---|
+| `tagName` exact | 0.20 | binary |
+| `stableClasses` Jaccard | 0.40 | size-of-intersection / size-of-union |
+| `parentChain` match (any depth) | 0.35 | per-link partial credit |
+| `indexInParent` match | 0.10 | binary, last resort |
+
+### Tier 3 — text
+
+| Feature | Weight | Match function |
+|---|---|---|
+| `visibleText` exact (after normalization) | 0.70 | binary |
+| `visibleText` fuzzy (Levenshtein ≥ 0.85) | 0.45 | proportional |
+| `placeholder` exact | 0.40 | binary |
+| `title` exact | 0.30 | binary |
+
+When `hints.textIsLikelyDynamic` is true, these weights are halved. We
+do not trust dynamic text as a strong identifier.
+
+### Tier 4 — visual / positional
+
+| Feature | Weight | Match function |
+|---|---|---|
+| `boundingBox` IoU | 0.25 | Intersection-over-Union ratio |
+| `visualHash` similarity | 0.20 | Hamming distance to similarity, threshold ≥ 0.9 |
+
+When the screenshot feature flag is off, the visual layer contributes
+nothing. The denominator shrinks accordingly.
+
+## 4. Thresholds
+
+The decision gate has three bands:
+
+| Band | Range | Action |
+|---|---|---|
+| HIGH | `score ≥ 0.80` | Heal silently. Audit log, no flag. |
+| MID | `0.55 ≤ score < 0.80` | Heal AND flag for human review. Queue offline. |
+| LOW | `score < 0.55` | Fail the test. Queue offline. |
+
+Additional gates that override the band (these are hard rules, not score
+adjustments):
+
+- **Ambiguity rule.** If two candidates score within 0.10 of each other
+  in HIGH or MID, demote both to LOW. We never silently pick between
+  near-tied candidates.
+- **Semantic mismatch.** If `ariaRole` of the candidate differs from the
+  fingerprint's `ariaRole` (e.g. fingerprint says `button`, candidate is
+  `link`), demote the candidate by one band. This catches "found
+  something that looks similar but is the wrong kind of thing."
+- **Action mismatch.** If the test action is `click` and the candidate
+  is not interactive (no `tabindex`, no `onclick`, not a focusable role),
+  demote by one band.
+- **Datagrok widget mismatch.** If `dgWidgetType` is recorded and the
+  candidate's widget type differs, demote by one band. The platform's
+  semantic layer is too informative to ignore.
+
+## 5. Why these defaults
+
+A few non-obvious choices:
+
+**Tier 1 dominates.** If `testId` matches, the score is ≥ 1.00 / (sum of
+present features), which alone is enough for HIGH on a typical
+fingerprint. This is the right outcome — when a stable semantic anchor
+matches, we should be highly confident regardless of structural drift.
+
+**Structural is the smallest tier in aggregate.** Sum of structural
+weights ≈ 1.05. Structure is a tiebreaker, not a primary signal. SPAs
+restructure constantly.
+
+**Text is heavier than structure but conditional.** Strong when stable;
+halved when dynamic. The conditional logic prevents
+`visibleText='Welcome, Alice'` from anchoring a test that runs as Bob.
+
+**Visual is the lightest.** Visual signals are noisy (rendering,
+fonts, themes, viewport sizes vary). They're a sanity check, not a
+foundation.
+
+## 6. Calibration
+
+Defaults will be calibrated against the eval fixtures (see
+[`09-eval-and-rollout.md`](./09-eval-and-rollout.md)). The calibration
+target: maximize true heals at HIGH while keeping false heals at HIGH
+below a configured budget (proposal: < 1%).
+
+The eval suite reports per-tier contribution, so we can see whether,
+say, `dgWidgetType` is overweighted in practice or whether
+`stableClasses` is doing nothing useful and can be deprioritized.
+
+Weights live in `self-healing.config.json`; calibration changes ship as
+config commits, not code commits.
+
+## 7. Why a formula and not a model
+
+We considered training a small classifier or learned reranker. Rejected
+for now because:
+
+- We don't have labeled data yet.
+- Explainability matters: a reviewer asking "why did this heal?" gets a
+  per-feature breakdown from the formula. A learned model would need
+  separate explainability tooling.
+- The formula has fewer than 15 numbers to tune. A model would have many
+  more, with attendant overfitting risk on a small corpus.
+- If the eval suite shows the formula is fundamentally inadequate, we
+  swap the scorer behind the same `Scorer` interface. The architecture
+  permits this.
+
+## 8. How the offline tool uses the same scorer
+
+The offline CLI processes a queued case as follows (full details in
+[`05-offline-flow.md`](./05-offline-flow.md)):
+
+1. Load the fingerprint and the live page (via headless browser).
+2. Ask Claude for up to 5 candidate selectors.
+3. For each candidate, find the element on the page.
+4. **Re-score the candidate using the runtime scorer** against the
+   fingerprint.
+5. Rank candidates by their runtime score, not by Claude's preference
+   order.
+6. Apply the same band gates as runtime.
+
+This means a "great" Claude proposal that scores LOW under our scorer
+gets rejected. A "weak-looking" Claude proposal that, on inspection,
+recovers Tier 1 features the resolver missed gets accepted. The scorer
+is the source of truth.
+
+## 9. Audit log fields related to scoring
+
+Every heal event includes:
+
+```json
+{
+  "score": 0.83,
+  "band": "HIGH",
+  "matched_features": [
+    {"name": "ariaLabel", "weight": 0.85, "match": 1.0},
+    {"name": "ariaRole+name", "weight": 0.85, "match": 1.0},
+    {"name": "stableClasses", "weight": 0.40, "match": 0.66}
+  ],
+  "absent_features": ["testId", "domId", "dgWidgetType"],
+  "demotions_applied": [],
+  "ambiguity_check": "passed"
+}
+```
+
+Reviewers can reconstruct the decision exactly. No black box.
diff --git a/libraries/self-healing-locators/docs/04-runtime-flow.md b/libraries/self-healing-locators/docs/04-runtime-flow.md
new file mode 100644
index 0000000000..1059b7695e
--- /dev/null
+++ b/libraries/self-healing-locators/docs/04-runtime-flow.md
@@ -0,0 +1,251 @@
+# 04 — Runtime Flow
+
+> Status: full detail. This describes what happens during a single test
+> run, step by step, with timing and failure modes.
+
+## 1. Entry point
+
+A test calls `healing.resolve(selector, options?)` instead of, or as a
+wrapper around, `page.locator(selector)`. The resolve function is the
+only public entry point that triggers the resolver chain.
+
+```ts
+// Drop-in for Playwright
+const submit = await healing.resolve(page, '[data-testid="submit"]', {
+  anchorName: 'login-submit',  // optional; auto-derived if absent
+  action: 'click',             // hint for the action-mismatch gate
+});
+await submit.click();
+```
+
+The `healing.anchor()` helper (see `api/healing-api.md`) is a thinner
+wrapper that always enforces an explicit name and is preferred for
+critical-path elements.
+
+## 2. Step-by-step flow
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ 0. Try the primary selector with a short timeout (default 1s).    │
+│                                                                   │
+│    Hit  → record a passive fingerprint refresh, return element.   │
+│    Miss → enter the resolver.                                     │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 1. Load fingerprint for `anchorName` from the registry.           │
+│                                                                   │
+│    Found     → continue.                                          │
+│    Not found → fail loudly. Self-healing requires a fingerprint;  │
+│                  we never invent one from a missing selector.     │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 2. Run Tier 1 (semantic).                                         │
+│                                                                   │
+│    Build candidate selectors from the fingerprint:                │
+│      - [data-testid="<testId>"]  (if recorded)                    │
+│      - #<domId>                  (if hint says stable)            │
+│      - [role="<role>"][aria-label="<label>"]                      │
+│      - getByRole(role, { name })  via a11y tree                   │
+│      - dg-widget-type lookup via getWidgetStatus()                │
+│                                                                   │
+│    For each that resolves to ≥1 element, evaluate against the     │
+│    full fingerprint with the scorer. Keep all results.            │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 3. Run Tier 2 (structural) only if Tier 1 best score < HIGH.      │
+│                                                                   │
+│    Build candidates from:                                         │
+│      - tag + stableClasses intersection on the page               │
+│      - parent-chain anchors found in Tier 1 (their descendants)   │
+│      - sibling index within identified parent                     │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 4. Run Tier 3 (text) only if best score still < HIGH.             │
+│                                                                   │
+│    Build candidates from:                                         │
+│      - getByText(visibleText)                                     │
+│      - getByPlaceholder(placeholder)                              │
+│      - getByTitle(title)                                          │
+│                                                                   │
+│    Skip text matching when hints.textIsLikelyDynamic.             │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 5. Run Tier 4 (visual) only if visual flag enabled and best score │
+│    still < HIGH.                                                  │
+│                                                                   │
+│    Build candidates from:                                         │
+│      - elements whose bounding box has IoU ≥ 0.5 with stored box  │
+│      - elements whose visualHash is within Hamming threshold      │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 6. Apply hard gates:                                              │
+│      - ambiguity (top two within 0.10) → demote                   │
+│      - semantic mismatch (role differs) → demote                  │
+│      - action mismatch (non-interactive for click) → demote       │
+│      - dgWidgetType mismatch → demote                             │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 7. Decide:                                                        │
+│      score ≥ HIGH → heal silently, return element                 │
+│      MID ≤ score  → heal, return element, write 'review' flag    │
+│                       to audit log AND queue for offline          │
+│      score < MID  → throw, queue for offline                      │
+└───────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 8. Write to audit log (jsonl). Always.                            │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+## 3. Why short-circuit between tiers
+
+We could compute every tier's contribution always, then sum. Instead we
+short-circuit on HIGH. Reasons:
+
+- Performance. Tier 4 (visual hashing) is by far the slowest. Skipping
+  when not needed keeps the median runtime cost in the sub-100ms range
+  for healed cases.
+- Tier 1 hits should not need cross-tier corroboration. If `testId`
+  matches and `ariaRole` matches, we don't need to also ask about the
+  bounding box.
+
+For LOW-confidence runs (score < HIGH after Tier 1), we proceed through
+all enabled tiers because we genuinely need more evidence.
+
+## 4. Performance budget
+
+Default budget per `resolve()` call:
+
+| Phase | Budget |
+|---|---|
+| Primary selector attempt | 1000 ms (configurable) |
+| Tier 1 (semantic) | 200 ms |
+| Tier 2 (structural) | 300 ms |
+| Tier 3 (text) | 200 ms |
+| Tier 4 (visual, if on) | 500 ms |
+| Scorer + decision | 50 ms |
+| **Total ceiling** | **~2.25 s** when all tiers run |
+
+If a resolver phase exceeds its budget, it returns its best partial
+result and continues. We never block a test indefinitely; tests time out
+faster than humans do.
+
+For the green-path (primary selector works), overhead is one fingerprint
+write to memory + a deferred flush — under 5 ms typical.
+
+## 5. The audit log
+
+Path is configurable; default
+`<test-output-dir>/self-healing/locator-events.jsonl`. One JSON line per
+event. Schema in `schemas/healing-event.schema.json`. Fields:
+
+- `eventId` (UUID)
+- `timestamp`
+- `testRef` (file, suite, test name)
+- `anchorName`
+- `originalSelector`
+- `resolvedSelector` (the selector that actually worked, if any)
+- `tierUsed` (1–4 or `primary` or `failed`)
+- `score`, `band`
+- `matched_features`, `absent_features`, `demotions_applied`
+- `ambiguity_check`
+- `flagForReview` (boolean)
+- `queuedOffline` (boolean)
+- `error` (only on failure)
+
+The audit log is **append-only** during the run. CI uploads it as a
+build artifact and merges it into the central healing queue if any
+events have `queuedOffline: true`.
+
+## 6. The healing queue
+
+Path: `<central-location>/self-healing/healing-queue.jsonl`. Same fields
+as the audit log, plus:
+
+- `domSnapshotPath` — path to a sanitized DOM snapshot taken at the moment
+  of the failure. Used by the offline tool to reproduce the page state.
+- `accessibilitySnapshotPath` — path to the accessibility tree snapshot.
+- `screenshotPath` — only if the visual flag is on.
+- `runMetadata` — branch, commit, CI run ID, browser, viewport.
+
+Snapshots are written next to the queue entry. They're necessary because
+the offline tool runs **after** the test, against a fresh page that may
+already have moved on. We need the page state at the moment of failure.
+
+Snapshot retention: configurable, default 30 days, then pruned. Pruning
+also closes any queue entries that have not been resolved offline within
+the retention window — they are escalated to a human dashboard with
+status `expired`.
+
+## 7. Concurrency and parallel runs
+
+Datagrok packages are tested in parallel (CI runs many packages
+simultaneously). Several concerns:
+
+- **Audit log writes.** Each test process writes its own `.jsonl` file
+  in its own output directory. CI aggregates after the run. No locking.
+- **Fingerprint registry reads.** Read-only at runtime. Safe.
+- **Fingerprint registry writes.** Passive auto-capture in green runs
+  could race. We use atomic file replacement (write to `.tmp` then
+  rename) and last-writer-wins. Fingerprint capture is idempotent for
+  unchanged elements, so collisions are usually no-ops.
+- **Healing queue writes.** Each test process appends to its own file;
+  CI merges. Even if an unrelated test fails the same anchor at the
+  same time, both events survive — the offline tool dedupes.
+
+## 8. Failure modes and behaviors
+
+| Situation | Behavior |
+|---|---|
+| Primary selector works, fingerprint missing | Capture passively. Test passes. |
+| Primary selector works, fingerprint stale | Refresh. Test passes. |
+| Primary selector fails, fingerprint missing | **Fail the test loudly.** Surface a clear error: "no fingerprint to heal from." This is a setup error, not a drift case. |
+| All tiers run, all miss | Fail. Queue with `tierUsed: failed`. |
+| All tiers run, ambiguity gate fires | Fail. Queue with reason `ambiguous`. |
+| Resolver itself throws | Fail with the original selector error wrapped. Never silently swallow. |
+| Registry file corrupt | Fail with a setup error. Do not attempt heuristic recovery. |
+| Audit log path not writable | Log a warning; do not fail the test. The audit log is best-effort from the test's perspective; missing audit data is a CI infrastructure problem. |
+
+## 9. What the resolver does **not** do at runtime
+
+- Does not call any LLM.
+- Does not write to the registry on a non-green run.
+- Does not retry the test action. If the heal succeeds and the click
+  later fails for another reason, that's a real test failure.
+- Does not modify test source.
+- Does not skip assertions. If a heal returns the wrong element and an
+  assertion catches it, the assertion failure stands; the audit log
+  shows the heal that led to it. This is exactly what we want — a way
+  to investigate when self-healing made a mistake.
+
+## 10. Observability
+
+In addition to the per-event audit log, the runtime exposes counters
+through `healing.audit.snapshot()`:
+
+- `total_resolves`
+- `primary_hits` / `tier1_hits` / `tier2_hits` / `tier3_hits` / `tier4_hits`
+- `flagged_for_review`
+- `queued_offline`
+- `failed`
+
+CI publishes these to the standard test reporter. Sustained increases in
+`tier3_hits` or `flagged_for_review` are signals worth investigating —
+they mean the platform is drifting in ways our deterministic tiers
+struggle with, which may justify a `data-testid` campaign or a config
+tune.
diff --git a/libraries/self-healing-locators/docs/05-offline-flow.md b/libraries/self-healing-locators/docs/05-offline-flow.md
new file mode 100644
index 0000000000..5a82e81c87
--- /dev/null
+++ b/libraries/self-healing-locators/docs/05-offline-flow.md
@@ -0,0 +1,362 @@
+# 05 — Offline Flow
+
+> Status: full detail. This is the LLM-facing half of the system.
+
+## 1. When the offline tool runs
+
+Three triggers:
+
+- **Scheduled.** Nightly CI job: `grok-heal run`. Processes the merged
+  healing queue from the day's runs.
+- **On-demand after a release.** A platform release touching UI is
+  expected to produce queued cases; QA runs the tool to surface them
+  early.
+- **Manually for a single case.** During investigation:
+  `grok-heal validate <case-id>` reproduces one case end-to-end without
+  opening a PR.
+
+The CLI lives in `tools/self-healing-cli`. It depends on the runtime
+library for the schemas and the scorer.
+
+## 2. Inputs and outputs
+
+**Inputs:**
+
+- The merged healing queue (`healing-queue.jsonl`).
+- DOM snapshots, accessibility tree snapshots, and optionally screenshots
+  associated with each entry.
+- The fingerprint registry (read-only).
+- A configuration file (model selection rules, thresholds, cost
+  ceilings, prompt template paths).
+
+**Outputs:**
+
+- A processing report (`healing-report-<run-id>.json`) — what was
+  attempted, what succeeded, what failed, with cost breakdown.
+- Per-case results in `healing-results/<case-id>.json` containing the
+  Claude proposals, the validator's per-candidate scores, and the
+  chosen winner if any.
+- One PR per package (or one combined PR, configurable) with codemod'd
+  test source updates.
+
+The CLI never writes to the fingerprint registry directly — registry
+updates flow through the runtime, on green runs, after the PR merges.
+
+## 3. End-to-end pipeline
+
+```
+healing-queue.jsonl
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 1. Queue Reader   │ -> │ Group entries by (testFile, anchor)  │
+│                   │    │ Dedupe; pick the freshest snapshot.  │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 2. Triage         │ -> │ For each case, decide:               │
+│                   │    │  - retry deterministic resolver on   │
+│                   │    │    the snapshot (registry may have   │
+│                   │    │    been updated since the failure)   │
+│                   │    │  - if it now resolves at HIGH, mark  │
+│                   │    │    as 'self-resolved', skip LLM      │
+│                   │    │  - else proceed                      │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 3. Model Selector │ -> │ Pick Haiku / Sonnet / Opus per the   │
+│                   │    │ rules in § 5.                        │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 4. Prompt Builder │ -> │ Render system + user template with   │
+│                   │    │ fingerprint, a11y tree, optional     │
+│                   │    │ screenshot, action hint.             │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 5. Claude Client  │ -> │ Call /v1/messages with tool_use       │
+│                   │    │ forcing the response schema. Retry   │
+│                   │    │ on schema violation (max 2).         │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 6. Validator      │ -> │ Spin up headless browser. Load page  │
+│                   │    │ at the failing point (via test       │
+│                   │    │ replay or DOM snapshot serving).     │
+│                   │    │ For each candidate, find element,    │
+│                   │    │ score with the runtime scorer,       │
+│                   │    │ apply hard gates.                    │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 7. Decision       │ -> │ best_score ≥ HIGH    → propose heal  │
+│                   │    │ MID ≤ best_score     → propose heal  │
+│                   │    │                       w/ review flag │
+│                   │    │ best_score < MID     → mark unhealed │
+│                   │    │ all candidates fail  → mark unhealed │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 8. Codemod        │ -> │ Locate the call site in the test     │
+│                   │    │ source. Replace selector. If the     │
+│                   │    │ test uses healing.anchor(), update   │
+│                   │    │ the selector argument only.          │
+└───────┬───────────┘    └──────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────┐    ┌──────────────────────────────────────┐
+│ 9. PR Opener      │ -> │ One PR per package. Body includes    │
+│                   │    │ per-case scores, audit refs, cost,   │
+│                   │    │ unresolved cases.                    │
+└───────────────────┘    └──────────────────────────────────────┘
+```
+
+## 4. Reproducing the failing page state
+
+Step 6 (validator) requires the page in roughly the state it was in when
+the test failed. Three approaches, in priority order:
+
+1. **Replay the test up to the failing step.** Most reliable. The test
+   harness exposes a `replay` mode that runs the original test and stops
+   just before `healing.resolve()` is called for the queued case. The
+   validator then evaluates each candidate against the live page.
+2. **Serve the DOM snapshot.** Faster, less reliable. The CLI starts a
+   tiny static server with the captured `domSnapshotPath`. Limitations:
+   no JS state, no event handlers — fine for static element lookup,
+   wrong for interactive validation.
+3. **Use the snapshot for selector lookup only**, with a notice that
+   interactive features were not exercised.
+
+The CLI prefers (1) and falls back to (2) with a warning. (3) is for
+cases where the source test cannot be replayed (e.g. external
+preconditions are no longer satisfiable).
+
+## 5. Model selection
+
+Tiered by case complexity, biased toward the cheapest model that
+produces accurate-enough output. The selector is rule-based — no LLM
+deciding which LLM to call.
+
+**Default rule:**
+
+```
+Estimated input size (a11y tree nodes + parent chain depth):
+   < 50 nodes,  no structural shift          → claude-haiku-4-5
+   < 200 nodes, simple drift signals         → claude-haiku-4-5
+   200–800 nodes, structural shift           → claude-sonnet-4-6
+   > 800 nodes OR retry after Haiku failure  → claude-sonnet-4-6
+   second retry / explicit escalation flag   → claude-opus-4-7
+```
+
+"Drift signals" come from comparing fingerprint to live a11y tree:
+
+- testId/domId disappeared → simple
+- ariaRole or accessible name changed → moderate
+- parent chain depth changed by ≥ 2 → structural
+- multiple semantic features changed at once → structural
+
+A run starts with Haiku for each case unless the case is pre-classified
+as structural. If Haiku produces no candidate that survives validation,
+the case auto-retries on Sonnet. Opus is reserved for explicit
+escalation (`grok-heal run --case <id> --escalate`).
+
+The model used is recorded per case in the report.
+
+## 6. Prompt construction
+
+System prompt: `prompts/system.md`. User message template:
+`prompts/user-template.md`. Few-shot examples in
+`prompts/examples/`.
+
+The user message is composed from:
+
+1. **Fingerprint** — the JSON object, but with `contextSnippet` removed
+   to avoid duplicating data we provide elsewhere.
+2. **Failed selector** — the original string and the action hint.
+3. **Current accessibility tree** — pruned to a depth window centered on
+   the most plausible region (parent chain match → expand 2 levels
+   around the best candidate; otherwise the current view's a11y root).
+4. **Optional HTML snippet** — included only when the a11y tree is
+   insufficient (e.g. the element role is `generic`).
+5. **Optional screenshot** — only when the feature flag is on, and only
+   when the case classification is "structural" or worse.
+6. **Negative constraints** — explicit list of selectors the resolver
+   already tried that did not work, so the LLM does not propose them.
+
+Token budget targets:
+
+- Haiku calls: prompt ≤ 8k tokens
+- Sonnet calls: prompt ≤ 32k tokens
+- Opus calls: prompt ≤ 64k tokens
+
+If a case exceeds the budget, the a11y tree is pruned harder (depth and
+breadth). We never silently drop the fingerprint or the negative
+constraints.
+
+## 7. Tool use schema
+
+We use Claude's `tool_use` to force structured output. The tool is
+declared with strict JSON Schema (in `schemas/tool-response.schema.json`).
+A summary:
+
+```json
+{
+  "name": "propose_locators",
+  "description": "Propose CSS/XPath selectors for the missing element.",
+  "input_schema": {
+    "type": "object",
+    "required": ["candidates", "unable_to_match"],
+    "properties": {
+      "candidates": {
+        "type": "array",
+        "minItems": 0,
+        "maxItems": 5,
+        "items": {
+          "type": "object",
+          "required": ["selector", "selector_type", "matched_attributes", "rationale"],
+          "properties": {
+            "selector": { "type": "string" },
+            "selector_type": {
+              "type": "string",
+              "enum": ["css", "xpath", "role", "testid", "text"]
+            },
+            "matched_attributes": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Subset of fingerprint feature names that this selector relies on. Must come from the documented feature vocabulary."
+            },
+            "rationale": { "type": "string", "maxLength": 400 },
+            "risk_notes": { "type": "string", "maxLength": 400 }
+          }
+        }
+      },
+      "unable_to_match": { "type": "boolean" },
+      "unable_reason": {
+        "type": "string",
+        "enum": [
+          "no_semantic_match_in_dom",
+          "ambiguous_candidates",
+          "page_state_mismatch",
+          "insufficient_context",
+          "other"
+        ]
+      },
+      "unable_reason_detail": { "type": "string", "maxLength": 400 }
+    }
+  }
+}
+```
+
+Note what is **not** in the schema:
+
+- No `confidence` field. The runtime scorer assigns confidence; the LLM
+  doesn't get to vote.
+- No free-form output. If `unable_to_match` is `true`, `candidates`
+  must be empty; the validator enforces this.
+- No instruction to "explain in detail." `rationale` is capped because
+  long rationales waste tokens and tend to drift toward unfounded
+  certainty.
+
+## 8. Validation
+
+For each returned candidate:
+
+1. Find element(s) on the live page using `selector` and `selector_type`.
+2. If zero elements: reject (`reason: not_found`).
+3. If multiple elements: reject (`reason: ambiguous`).
+4. If exactly one element: build a candidate fingerprint from it, run the
+   runtime scorer against the stored fingerprint.
+5. Apply hard gates (semantic mismatch, action mismatch, dgWidgetType
+   mismatch).
+6. Final score → band → decision.
+
+The winning candidate is the highest-scoring one that passes all gates.
+Ties at HIGH within 0.10 → demote both (per § 3 of the confidence model).
+
+## 9. Codemod and PR
+
+The codemod is conservative:
+
+- Locates the call site by `testRef.file` + `anchorName` + line range
+  recorded at capture.
+- Replaces only the selector argument. Never reformats surrounding code.
+- If the test passes a selector built dynamically (template literal,
+  variable), the codemod skips and the case is reported as "needs human
+  rewrite" with the proposed selector in the PR body.
+
+The PR title and body convention:
+
+```
+title: chore(self-healing): heal locators in <package> (<N> cases)
+
+body:
+  ## Summary
+  <N> selectors auto-healed by the offline maintenance tool.
+
+  | Test | Anchor | Old | New | Score | Tier |
+  |---|---|---|---|---|---|
+  ...
+
+  ## Unhealed cases
+  ...
+
+  ## Cost
+  $X.XX (Haiku: A, Sonnet: B, Opus: C)
+
+  ## Audit references
+  - run-id: ...
+  - artifacts: ...
+```
+
+Reviewer (default `CODEOWNERS` of the affected package) is automatically
+requested.
+
+## 10. Cost controls
+
+- **Per-run cap.** Configured dollar limit. The tool tracks cumulative
+  cost; on cap reached, it processes remaining cases as `deferred` and
+  exits. The cap is enforced before each call, not after.
+- **Per-case retry cap.** Max 2 retries per case (Haiku → Sonnet → stop).
+  Opus only on manual escalation.
+- **Caching.** Identical (fingerprint hash, page snapshot hash) inputs
+  reuse a cached response. Cache TTL: 7 days. This matters for a
+  flapping case that gets re-queued from multiple test runs against the
+  same page state.
+- **Batching.** Cases targeting the same page snapshot can share a
+  single `messages` request — multiple anchors in one prompt — but only
+  when the input remains within the model's prompt budget. The default
+  is one anchor per request; batching is opt-in.
+
+## 11. Failure modes specific to offline
+
+| Situation | Behavior |
+|---|---|
+| Anthropic API returns 5xx | Exponential backoff up to 3 attempts, then mark case as `transient_error`, requeue. |
+| `tool_use` response invalid against schema | One retry with the schema appended to the user message. Then mark `schema_violation`, do not heal. |
+| All candidates fail validation | Mark `no_valid_candidate`. Record proposals for human review. |
+| Validator cannot reach the page | Mark `replay_failed`. Human intervention. |
+| Codemod cannot locate the call site | Mark `codemod_failed`, include proposed selector in the PR body for manual application. |
+| Concurrent edits to the same test file | Skip case; requeue for the next run. |
+| Cost cap reached mid-run | Process remaining as `deferred`. Surface in the report. |
+
+Every failure mode produces an entry in the report so the next human
+looking at the dashboard sees what happened, not just that something
+"didn't heal."
+
+## 12. What the offline tool does not do
+
+- Does not commit directly to a long-lived branch. Always a PR.
+- Does not modify the fingerprint registry. Fingerprints are
+  capture-side, not heal-side.
+- Does not run on every CI run. It's a maintenance tool, not a build
+  step.
+- Does not call Claude with raw test source code. The prompt sees
+  fingerprints and DOM, not test logic.
diff --git a/libraries/self-healing-locators/docs/06-datagrok-integration.md b/libraries/self-healing-locators/docs/06-datagrok-integration.md
new file mode 100644
index 0000000000..8ec5a771da
--- /dev/null
+++ b/libraries/self-healing-locators/docs/06-datagrok-integration.md
@@ -0,0 +1,71 @@
+# 06 — Datagrok Platform Integration
+
+> Status: compact. Captures specifically what we use from the platform
+> and what we recommend changing in the platform.
+
+## What we use from the platform today
+
+**`Widget.getWidgetStatus()`.** Returns the widget's runtime structure
+intended for automated testing and introspection (per the JS API). We
+read `status.widgetType` and, where applicable, `status.viewerType` into
+the fingerprint. This survives DOM-level reorganization because it
+reflects the platform's own model of the page.
+
+**The accessibility tree.** Datagrok's UI primitives (`ui.button`,
+`ui.input.*`, `ui.dialog`, ribbon items, etc.) emit standard ARIA roles
+and accessible names. We read these via the test driver's a11y APIs
+(Puppeteer `page.accessibility.snapshot()`, Playwright's `getByRole`).
+
+**Inspector data source.** The Inspector tool (`Alt + I`) exposes the
+registered widget tree. Our capture utility taps the same data source
+where possible so fingerprints reflect the platform's model rather than
+just the DOM.
+
+## What we recommend (separate, non-blocking work)
+
+These are not required for the system to work. They make it work better.
+
+1. **`data-testid` convention on `ui.*` primitives.** When the caller
+   passes a logical name (`ui.button('Run analysis', ...)`), the
+   primitive should set `data-testid="ui-button-run-analysis"` (slugified)
+   by default. Skippable via opt-out. This gives us strong Tier 1
+   anchors without authors thinking about it.
+2. **Stable role/name on dynamic UI.** Dialog headers, viewer toolbars,
+   ribbon items — anywhere the visible text doubles as the accessible
+   name, ensure both are set explicitly. Our resolver will benefit;
+   accessibility users will also benefit.
+3. **`getWidgetStatus()` for non-viewer widgets.** Currently most
+   reliable on viewers. Extending to dialogs, ribbon panels, and toolbox
+   items would give us additional Datagrok-specific anchors.
+4. **A `Test ID` mode in the Inspector.** A toggle that overlays
+   suggested anchor names on the page would help test authors choose
+   good explicit anchors and would let our capture tool offer them
+   automatically.
+
+These recommendations should be tracked separately. Any of them landing
+makes the deterministic resolver better; none of them is required for
+the v1 of this library.
+
+## Constraints we accept from the platform
+
+- **The library is a downstream consumer.** We do not assume the platform
+  will change for us. Recommendations above are nice-to-have.
+- **Tests run against a live platform instance.** Snapshots are what we
+  capture, not what we control. The platform owns the source of truth
+  about UI semantics; we just observe it.
+
+## API touchpoints
+
+| Use case | Platform API | Notes |
+|---|---|---|
+| Read widget type from element | `DG.Widget.fromRoot(el).getWidgetStatus()` | |
+| Read accessibility tree | driver-native (Puppeteer/Playwright) | |
+| Identify view boundary | `grok.shell.v` (current view) | Used as parent-chain stop |
+| Read viewer type | `viewer.type` | When element is inside a viewer |
+| Detect dialog containment | climb to nearest `[role="dialog"]` | |
+
+If any of these become unstable across platform versions, the capture
+utility records the platform version in the fingerprint
+(`runMetadata.platformVersion` in the queue, separately in the
+fingerprint via `hints.platformVersion`) so the offline tool can detect
+incompatibilities and skip rather than guess.
diff --git a/libraries/self-healing-locators/docs/07-policy.md b/libraries/self-healing-locators/docs/07-policy.md
new file mode 100644
index 0000000000..475a080f72
--- /dev/null
+++ b/libraries/self-healing-locators/docs/07-policy.md
@@ -0,0 +1,216 @@
+# 07 — Healing Policy
+
+> Status: full detail. This document defines the boundary between
+> "drift we heal" and "real change we let fail." Reviewers, please
+> scrutinize the examples — they encode our editorial judgment.
+
+## 1. The principle
+
+Self-healing repairs **how** a test finds an element. It does not repair
+**what** the test asserts about that element. If the element is gone, or
+its role has changed in a way that breaks the test's intent, the test
+should fail. The system's job is to remove the noise of locator drift,
+not to keep the test green at any cost.
+
+This document is the answer to "what counts as drift, and what counts as
+a real change?" We answer it concretely, with examples.
+
+## 2. What we heal (drift)
+
+A change qualifies as drift when **all** of the following are true:
+
+1. The user-visible behavior the test is exercising is unchanged.
+2. The element fulfilling that behavior still exists, with the same
+   semantic role.
+3. The change is in the locator path: id renamed, classes hashed
+   differently, structural wrapper added, accessible name normalized,
+   etc.
+4. The fingerprint can be re-attached to a single element on the new
+   page with confidence ≥ MID.
+
+If any of those is false, we don't heal.
+
+### Examples we heal
+
+| Change | Why we heal |
+|---|---|
+| `data-testid="submit"` → `data-testid="submit-btn"` | Same role, same name, same position. Pure renaming. |
+| Class `.btn-primary` replaced by `.css-1a2b3c4` | CSS-in-JS migration. Stable classes filtered out; semantic match remains. |
+| Button moved into a new `<form-actions>` wrapper | Structural shift. Tier 2 finds it via the parent chain shifted by one. |
+| `aria-label="Submit form"` → `aria-label="Submit"` | Fuzzy match within Levenshtein threshold; role unchanged. |
+| Viewer's toolbar reordered | bounding box changed, but `dgWidgetType + dgViewerType + accessible name` still match. |
+| `<button>` replaced by `<div role="button">` | Role match still works; tag mismatch is small structural penalty. |
+| Two scrollable panes swap order | Tier 2 finds the matching pane by stable classes + parent chain. |
+
+### Examples we heal **with a flag** for review
+
+When confidence lands in the MID band, we heal but ask a human to
+double-check. Examples that typically land here:
+
+- Multiple structural changes at once (wrapper added AND class hash
+  changed AND parent chain depth changed).
+- The Levenshtein-fuzzy text match was the deciding factor.
+- The accessible name changed from a verb to a synonym ("Submit" →
+  "Send"). The role is the same; the wording shift is small but real.
+- The visual hash similarity carried weight (visual layer activated
+  because semantic and structural were inconclusive).
+
+Flagging is the explicit acknowledgment that this is a judgment call
+and a human should rubber-stamp it.
+
+## 3. What we do not heal (real changes)
+
+A change is real, and the test must fail, when **any** of the following
+is true:
+
+1. The element no longer exists on the page in any form the resolver
+   can match with confidence ≥ MID.
+2. The semantic role of the element changed (`button` → `link`,
+   `dialog` → `popover`).
+3. The Datagrok widget type changed (`Viewer` → `Dialog`,
+   `scatter-plot` → `bar-chart`).
+4. The element's intent changed: button label "Submit" became "Delete"
+   (text similarity will not save this — semantic mismatch is too
+   large, and the action mismatch gate may also fire).
+5. Multiple top candidates are tied within the ambiguity threshold and
+   we cannot pick safely.
+
+### Examples we do not heal
+
+| Change | Why we let the test fail |
+|---|---|
+| Submit button removed (refactor mistake) | Element absent. Fail. |
+| "Submit" button became "Delete" | Same role and position, but the test's intent doesn't survive. The visible-text mismatch + the fingerprint's `purpose` (if explicitly set) drive this to LOW. |
+| Login dialog became a fullscreen view | Widget type changed. Fail. |
+| The "Run" button is now disabled by default | Element exists, but action mismatch (test does click; element is non-interactive) fires. Fail. |
+| Two identical "Save" buttons appear (one in toolbar, one in dialog) | Ambiguity gate fires. Fail rather than guess. |
+
+## 4. The gray zones we have to call
+
+Not everything is clean. We make the following editorial choices and
+document them so the team is aligned.
+
+### 4.1 Synonym wording changes
+
+"Submit" → "Send", "Apply" → "Save", "OK" → "Confirm". These pass our
+fuzzy-match threshold sometimes and not others depending on the rest of
+the fingerprint. Our policy: when text is the **deciding** signal, we
+flag for review. We never silently heal a wording change.
+
+### 4.2 Role normalization
+
+Sometimes a `<div onclick>` becomes a `<button>`. The role changes from
+implicit to explicit, but the user experience is unchanged or improved.
+Our policy: heal at HIGH if `accessible name + position` match strongly
+and the role change is a **strengthening** (less semantic to more
+semantic). The reverse — `<button>` becoming `<div onclick>` — flags
+for review because it suggests an accessibility regression worth
+noticing.
+
+### 4.3 Viewer rendering changes
+
+Viewers (scatter plot, grid, bar chart) re-render frequently. A test
+clicking a specific bar in a chart should not be a self-healing target
+in the first place — those tests should use the viewer's API
+(`viewer.dataFrame.currentRow = N`), not raw clicks. Our policy: if a
+fingerprint sits **inside** a viewer at a deep level, we heal at the
+viewer boundary (the toolbar, the title, the tab) but **refuse** to
+heal at the rendered-data level. The fingerprint capture utility warns
+when an anchor sits below the viewer rendering boundary.
+
+### 4.4 Dynamic content
+
+A heading "Welcome, Alice" tested from a session that runs as Alice. If
+the test reruns as Bob, the text is "Welcome, Bob." Our policy: detect
+dynamic patterns at capture (`hints.textIsLikelyDynamic`), halve the
+text feature weights at scoring time, and rely on role + position. If
+the test author wrote a fragile assertion, we don't fix that — the
+assertion itself will catch the mismatch.
+
+### 4.5 i18n
+
+A button labeled "Submit" in en-US, "Senden" in de-DE. The test's locale
+is fixed per run, so the fingerprint matches its locale. If the test
+is parameterized over locales, the test author should use the
+non-text features as anchors (role, testid, structural). If they
+haven't, locale changes look like text drift. Our policy: detect
+mismatched language between fingerprint and live page (via simple
+language ID) and **fail** rather than heal — this is almost always a
+test setup issue, not drift.
+
+## 5. Hard rules (regardless of confidence)
+
+These bypass the score entirely:
+
+1. **No heal across widget type boundaries.** If a fingerprint says
+   "button inside viewer X" and the candidate is "button inside dialog
+   Y", do not heal even at HIGH score.
+2. **No heal of destructive-action elements without a flag.** Anchors
+   tagged `purpose: 'destructive'` (delete, drop, remove, etc.) always
+   flag for review even at HIGH score. The cost of healing wrongly is
+   higher.
+3. **No heal of authentication-related elements without an explicit
+   anchor.** Auto-derived anchors on login/auth flows are too risky.
+   The library refuses to heal these unless the test author committed
+   to an explicit `healing.anchor()`.
+4. **No heal when running against an unfamiliar platform version.** If
+   `runMetadata.platformVersion` is more than two minor versions ahead
+   of the fingerprint's platform version, the resolver returns LOW
+   automatically. The platform is allowed major UI overhauls between
+   minor versions, and healing across them risks masking redesigns.
+
+These rules are encoded as code, not config, because they are safety
+properties — turning them off changes the system's character, not its
+tuning.
+
+## 6. What the policy implies for test authors
+
+Authors are still responsible for:
+
+- Writing meaningful assertions. We don't heal those.
+- Choosing semantic selectors when possible. Tier 1 is most reliable.
+- Marking destructive actions with `purpose: 'destructive'` so the policy
+  applies.
+- Using `healing.anchor()` for auth flows and other high-risk paths.
+
+The library does not absolve authors of these responsibilities. It
+absorbs the parts of test maintenance that don't add information.
+
+## 7. What the policy implies for reviewers
+
+When a healing PR lands in your queue:
+
+- Each row in the table is one healed selector. The score and tier tell
+  you how strong the evidence was. HIGH is "I would have done the same
+  rename;" MID is "the system thought this was right but please look."
+- The audit references in the PR body link to per-case detail. You can
+  see the fingerprint, the proposed candidates, and which one won.
+- If you disagree with a heal: revert the line, mark the case as
+  `human-rejected` via `grok-heal mark`, and the case won't be
+  proposed again until the fingerprint or page state changes.
+- If you see patterns of bad heals: that's signal worth raising. The
+  weights or thresholds may need tuning, or the platform may need
+  better test IDs.
+
+## 8. What the policy implies for the platform team
+
+The cleanest lever the platform team has to reduce false heals is
+**stable test IDs on UI primitives** (see `06-datagrok-integration.md`).
+Every `data-testid` we get for free in the platform is one less case
+the resolver has to reason about structurally.
+
+The system will work without it; it will work better with it.
+
+## 9. Open policy questions (please weigh in during review)
+
+1. **MID-band default.** Heal-and-flag, or fail-and-flag? We propose
+   heal-and-flag because the test exercising the rest of the flow is
+   valuable even if the locator is uncertain. Reviewers may prefer
+   fail-and-flag for higher safety.
+2. **Auto-rejection memory.** When a reviewer rejects a heal, how long
+   do we remember it? Until the fingerprint changes? Until the page
+   snapshot changes? Forever? We propose: until fingerprint OR page
+   snapshot hash changes.
+3. **Bulk approvals.** If a release introduces 50 heals across 10
+   packages, do we open one PR or ten? We propose ten (per package,
+   per CODEOWNERS), but reviewers may prefer one mega-PR for visibility.
diff --git a/libraries/self-healing-locators/docs/08-review-process.md b/libraries/self-healing-locators/docs/08-review-process.md
new file mode 100644
index 0000000000..cf482cc081
--- /dev/null
+++ b/libraries/self-healing-locators/docs/08-review-process.md
@@ -0,0 +1,56 @@
+# 08 — Review Process
+
+> Status: compact. The audit log and PR conventions are spelled out in
+> earlier docs; this document just orients reviewers and authors.
+
+## Two review surfaces
+
+**1. Healing PRs** opened by `tools/self-healing-cli`. One per package,
+auto-assigned to the package's CODEOWNERS. Body includes a per-case
+table (test, anchor, old → new selector, score, tier), unhealed cases,
+cost, and audit references.
+
+**2. Review queue.** A separate listing of MID-band runtime heals
+(healed but flagged) and offline cases the tool couldn't heal. Renders
+from the merged audit log and the offline report. **Out of scope for
+this PR**; design proposed here as a placeholder so we can cross-link.
+
+## What a reviewer does on a healing PR
+
+- Skim the table. Anything in the MID band gets a closer look.
+- Click through to the audit reference for a case where the heal feels
+  wrong. The audit has the fingerprint, the candidates Claude proposed,
+  the runtime scorer's per-feature breakdown, and the winner.
+- Approve, request changes, or reject specific lines.
+- If a heal is wrong, revert the line and run
+  `grok-heal mark <case-id> --rejected` to remember.
+
+## What a reviewer should NOT do
+
+- Do not approve the PR without skimming MID-band rows.
+- Do not assume HIGH-band rows are always correct — they almost always
+  are, but the audit is short and worth a glance for any visually
+  surprising selector change.
+- Do not merge a healing PR while a related platform release is mid-flight.
+  Wait for the platform to settle, run the tool again, then merge.
+
+## When to escalate
+
+- Sustained increases in MID-band heals across releases → tune weights
+  or push for `data-testid` adoption in the platform.
+- A specific test consistently produces low-confidence heals → that
+  test's anchors are likely too weak. Add explicit `healing.anchor()`
+  with stronger fingerprint hints.
+- Claude proposes implausible candidates repeatedly → the prompt or
+  examples need work; raise an issue against the prompt files.
+
+## Ownership
+
+- **Library code:** owners of `libraries/self-healing-locators`.
+- **CLI code:** owners of `tools/self-healing-cli`.
+- **Healing PRs:** package CODEOWNERS by default, configurable.
+- **Prompt files:** the same owners as the library, with QA team as
+  required reviewer (so prompt changes get more eyes than code changes
+  on the library internals).
+- **Confidence weights and thresholds:** library owners + QA team
+  required reviewer.
diff --git a/libraries/self-healing-locators/docs/09-eval-and-rollout.md b/libraries/self-healing-locators/docs/09-eval-and-rollout.md
new file mode 100644
index 0000000000..cf5d35bdde
--- /dev/null
+++ b/libraries/self-healing-locators/docs/09-eval-and-rollout.md
@@ -0,0 +1,131 @@
+# 09 — Evaluation and Rollout
+
+> Status: compact. How we test the harness itself, and how we ship it
+> without breaking existing tests.
+
+## Evaluating the system
+
+The library and the CLI both have to pass a regression eval before
+changes to weights, thresholds, prompts, or models ship.
+
+### Eval fixtures
+
+Pairs of (page-before, page-after, expected-element). Initial target:
+30–50 fixtures covering:
+
+- Pure renames (`data-testid` updated)
+- Class hash churn (CSS-in-JS deploys)
+- Structural wrappers added or removed
+- Accessible name changes (synonyms, normalizations)
+- Datagrok widget reorganizations (toolbar, ribbon, dialog)
+- Negative cases: element removed, role changed, semantic mismatch
+- Adversarial: two near-identical candidates
+
+Fixtures live in `libraries/self-healing-locators/eval/fixtures/`. Each
+fixture is a small directory: `before.html`, `after.html`,
+`fingerprint.json`, `expected.json` (with one of: `winner_selector`,
+`unable_to_heal`, `flag_for_review`).
+
+### Eval metrics
+
+Per run of the eval:
+
+- **True heal rate** at HIGH band (target: ≥ 95% on positive fixtures)
+- **False heal rate** at HIGH band (target: < 1% on negative fixtures)
+- **Flag rate** at MID band (target: positive fixtures land here only
+  when intentionally ambiguous)
+- **Correct fail rate** on negative fixtures (target: ≥ 99%)
+- **LLM cost per case** (offline only; tracked, not gated)
+- **Latency p50/p95** for runtime resolution
+
+Eval runs both the runtime resolver alone (no LLM) and the offline
+pipeline (with LLM). Both have separate gates.
+
+### When eval runs
+
+- On every PR that touches the library, the CLI, prompts, weights, or
+  thresholds.
+- Nightly against `master` to catch regressions from dependency drift.
+- Manually before any model rollout (e.g. trying `claude-haiku-4-5` →
+  `claude-haiku-5` whenever that lands).
+
+## Rolling out the system
+
+We ship in stages. Each stage has a clear gate.
+
+### Stage 0 — Land the design (this PR)
+
+Get reviewer alignment on docs, schema, prompt, policy. No code yet.
+
+### Stage 1 — Library skeleton
+
+Types, schemas, registry I/O, capture API. No resolver chain, no scorer.
+Tests pass. Library publishes but no consumer uses it.
+
+### Stage 2 — Capture and fingerprint registry
+
+Passive capture in green runs, explicit `healing.anchor()`. One
+volunteer package opts in; we collect a few weeks of fingerprints in a
+real environment to validate the schema. **No healing happens yet** —
+even when the primary selector misses, the resolver throws.
+
+### Stage 3 — Runtime resolver (deterministic only)
+
+Tiers 1–3 (visual stays off by default). Scorer. Decision gate. Audit
+log. Healing queue writer. The volunteer package starts seeing heals.
+We watch the audit log for false heals. No source mutation.
+
+### Stage 4 — Offline CLI without source mutation
+
+Triage, prompt, validator, report. The CLI runs in dry-run mode: it
+produces a healing report but does not open PRs. We review reports
+manually for a few iterations and tune.
+
+### Stage 5 — Offline CLI opens PRs
+
+Codemod and PR opener enabled. PRs require human approval (no
+auto-merge ever). We start with one package, expand as we gain
+confidence.
+
+### Stage 6 — Visual layer (optional)
+
+Visual hashing as Tier 4 enabled where it adds signal. Per-package opt-in.
+
+### Stage 7 — Broad rollout
+
+All packages opt-in. Documentation updated. Training / runbook for
+package maintainers.
+
+Each stage is gated by:
+
+- Eval suite green.
+- No regression in volunteer package's primary CI signal.
+- Sign-off from QA and from the package's CODEOWNERS.
+
+## What success looks like, six months in
+
+- Median package test run produces zero MID-band flags after a typical
+  platform release.
+- Healing PRs land within 24 hours of a release that produces drift,
+  with > 90% of cases auto-resolved at HIGH and the rest cleanly
+  flagged.
+- Eval suite catches at least one regression before merge, demonstrating
+  it earns its keep.
+- LLM cost per release is bounded by the configured cap and well below
+  it on average.
+
+## What failure looks like, and what we'd do
+
+- Reviewers ignoring healing PRs because they're noisy → reduce the
+  volume by raising HIGH threshold and pushing more cases to MID-with-flag.
+- Specific test or package contributing disproportionate cases →
+  invest in better explicit anchors there, or recommend platform-side
+  test ID work.
+- LLM cost spiking → tighten model selection rules, increase caching
+  TTL, batch more aggressively, or move to a smaller model.
+- False heals causing prod escapes → tighten the policy and the
+  scoring; consider raising default thresholds; add the failure to the
+  eval suite as a permanent fixture.
+
+The system is meant to be tunable. Failures get fed back into
+calibration, not papered over.
diff --git a/libraries/self-healing-locators/prompts/examples/01-testid-rename.md b/libraries/self-healing-locators/prompts/examples/01-testid-rename.md
new file mode 100644
index 0000000000..062f4fca1e
--- /dev/null
+++ b/libraries/self-healing-locators/prompts/examples/01-testid-rename.md
@@ -0,0 +1,91 @@
+# Example 01 — `data-testid` Rename
+
+A common, easy case. The platform team renamed `data-testid="submit"`
+to `data-testid="submit-btn"` for consistency. Everything else is
+unchanged.
+
+## Input
+
+### Fingerprint
+```json
+{
+  "schemaVersion": "1",
+  "anchorName": "login-submit",
+  "semantic": {
+    "testId": "submit",
+    "ariaLabel": "Submit",
+    "ariaRole": "button",
+    "name": "Submit"
+  },
+  "structural": {
+    "tagName": "button",
+    "stableClasses": ["primary-action"],
+    "parentChain": [
+      { "tagName": "div", "stableClasses": ["form-actions"] },
+      { "tagName": "form", "ariaRole": "form" }
+    ]
+  },
+  "text": { "visibleText": "Submit" },
+  "hints": {
+    "domIdLooksStable": false,
+    "classesAreCssInJs": false,
+    "textIsLikelyDynamic": false
+  }
+}
+```
+
+### Failed selector
+`[data-testid="submit"]`
+
+### Already tried
+- `[data-testid="submit"]`
+- `#submit`
+- `[role="button"][aria-label="Submit"]`
+
+(In practice, Tier 1 of the resolver would have found this case via
+`getByRole('button', { name: 'Submit' })`. The example assumes that
+hit was somehow weak — perhaps another `Submit` exists on the page.)
+
+### Accessibility tree (excerpt)
+```
+[role="form"]
+  [role="group" name="form-actions"]
+    [role="button" name="Submit" testid="submit-btn"]
+    [role="button" name="Cancel" testid="cancel-btn"]
+[role="navigation"]
+  [role="button" name="Submit feedback"]
+```
+
+## Expected response
+
+```json
+{
+  "candidates": [
+    {
+      "selector": "[data-testid=\"submit-btn\"]",
+      "selector_type": "testid",
+      "matched_attributes": ["testId"],
+      "rationale": "Same role and name; testid renamed from 'submit' to 'submit-btn'. Unique under form-actions group.",
+      "risk_notes": "Note that 'Submit feedback' button exists in nav; this selector avoids it via the testid."
+    },
+    {
+      "selector": "form [role=\"button\"][aria-label=\"Submit\"]",
+      "selector_type": "role",
+      "matched_attributes": ["ariaLabel", "ariaRole", "parentChain"],
+      "rationale": "Backup using the form scope and accessible name. Does not depend on testid stability."
+    }
+  ],
+  "unable_to_match": false
+}
+```
+
+## What the validator does next
+
+1. `[data-testid="submit-btn"]` → exactly one match → score ~0.92
+   (testId 1.0, ariaLabel 1.0, ariaRole+name 1.0, stableClasses 0.66,
+   parentChain 1.0). HIGH band. Heal.
+2. The second candidate is also strong but not picked because the first
+   one wins.
+
+Outcome: PR opens with `[data-testid="submit"]` →
+`[data-testid="submit-btn"]`.
diff --git a/libraries/self-healing-locators/prompts/examples/02-aria-label-change.md b/libraries/self-healing-locators/prompts/examples/02-aria-label-change.md
new file mode 100644
index 0000000000..1547e60e60
--- /dev/null
+++ b/libraries/self-healing-locators/prompts/examples/02-aria-label-change.md
@@ -0,0 +1,93 @@
+# Example 02 — Accessible Name Change (MID band)
+
+The platform changed the accessible name on the dialog OK button from
+"OK" to "Confirm". No other changes. The system should heal but flag.
+
+## Input
+
+### Fingerprint
+```json
+{
+  "schemaVersion": "1",
+  "anchorName": "delete-confirm-ok",
+  "semantic": {
+    "ariaLabel": "OK",
+    "ariaRole": "button",
+    "name": "OK",
+    "dgWidgetType": "Dialog"
+  },
+  "structural": {
+    "tagName": "button",
+    "stableClasses": ["dlg-button", "dlg-button-default"],
+    "parentChain": [
+      { "tagName": "div", "stableClasses": ["dlg-buttons"] },
+      { "tagName": "div", "ariaRole": "dialog", "dgWidgetType": "Dialog" }
+    ]
+  },
+  "text": { "visibleText": "OK" },
+  "hints": {
+    "textIsLikelyDynamic": false
+  }
+}
+```
+
+### Failed selector
+`[aria-label="OK"]`
+
+### Already tried
+- `[aria-label="OK"]`
+- `text="OK"`
+
+### Accessibility tree (excerpt)
+```
+[role="dialog" dg-widget-type="Dialog" name="Delete project?"]
+  [role="heading" level=1 name="Delete project?"]
+  [role="button" name="Confirm"]
+  [role="button" name="Cancel"]
+```
+
+## Expected response
+
+```json
+{
+  "candidates": [
+    {
+      "selector": "role=dialog >> role=button[name=\"Confirm\"]",
+      "selector_type": "role",
+      "matched_attributes": ["ariaRole", "dgWidgetType", "parentChain"],
+      "rationale": "Same dialog (dgWidgetType + structural parent), button role preserved, accessible name changed from 'OK' to 'Confirm'. The default action button position in the dialog matches.",
+      "risk_notes": "Name changed; flag for review. Verify this is the intended affirmative button and not a different action."
+    },
+    {
+      "selector": ".dlg-buttons > .dlg-button-default",
+      "selector_type": "css",
+      "matched_attributes": ["stableClasses", "parentChain"],
+      "rationale": "Backup using the default-button class which has historically tracked the affirmative action across renamings.",
+      "risk_notes": "Class-only fallback — weaker than role-based."
+    }
+  ],
+  "unable_to_match": false
+}
+```
+
+## What the validator does next
+
+1. The `role=dialog >> role=button[name="Confirm"]` candidate matches
+   one element. Runtime scorer:
+   - `ariaRole` match: 0.85
+   - `dgWidgetType` match: 0.80
+   - `parentChain` match: 1.00 (depth 2)
+   - `stableClasses` match: 0.66 (`dlg-button` matches, `dlg-button-default`
+     matches → 2/2 = 1.0; minus mild penalty if stableClasses semantics
+     in the tool consider both equally weighted; let's say full)
+   - `ariaLabel` mismatch (OK vs Confirm): 0
+   - `name` mismatch: 0
+   - `visibleText` mismatch: 0
+
+   Composite score lands around 0.62 — MID band.
+2. Decision: heal AND flag.
+3. The healing PR row reads `score=0.62, band=MID, flag=review`. The
+   reviewer sees the rationale and confirms the rename was intentional.
+
+This is the exact case where the policy doc § 4.1 ("synonym wording
+changes") applies: text was decisive, so we flag.
diff --git a/libraries/self-healing-locators/prompts/examples/03-structural-refactor.md b/libraries/self-healing-locators/prompts/examples/03-structural-refactor.md
new file mode 100644
index 0000000000..e9c6570d4b
--- /dev/null
+++ b/libraries/self-healing-locators/prompts/examples/03-structural-refactor.md
@@ -0,0 +1,124 @@
+# Example 03 — Structural Refactor
+
+The viewer toolbar was wrapped in a new container, classes were
+re-hashed, and `data-testid` was lost in the migration. The accessible
+name and role remain.
+
+## Input
+
+### Fingerprint
+```json
+{
+  "schemaVersion": "1",
+  "anchorName": "scatter-toolbar-settings",
+  "semantic": {
+    "testId": "scatter-toolbar-settings",
+    "ariaLabel": "Settings",
+    "ariaRole": "button",
+    "name": "Settings",
+    "dgWidgetType": "Viewer",
+    "dgViewerType": "scatter-plot"
+  },
+  "structural": {
+    "tagName": "button",
+    "stableClasses": ["toolbar-button", "icon-cog"],
+    "parentChain": [
+      { "tagName": "div", "stableClasses": ["viewer-toolbar"] },
+      { "tagName": "div", "dgWidgetType": "Viewer" }
+    ]
+  },
+  "text": { "title": "Settings" },
+  "visual": {
+    "boundingBox": { "x": 1180, "y": 60, "width": 28, "height": 28 },
+    "viewportSize": { "w": 1440, "h": 900 }
+  },
+  "hints": {
+    "textIsLikelyDynamic": false
+  }
+}
+```
+
+### Failed selector
+`[data-testid="scatter-toolbar-settings"]`
+
+### Already tried
+- `[data-testid="scatter-toolbar-settings"]`
+- `.toolbar-button.icon-cog`
+- `[role="button"][aria-label="Settings"]`
+
+(Tier 3 found three "Settings" buttons on the page — the scatter
+toolbar, the bar chart toolbar, and the page-level settings menu — so
+ambiguity demoted it to LOW. Hence the case is here.)
+
+### Accessibility tree (excerpt)
+```
+[dg-widget-type="Viewer" dg-viewer-type="scatter-plot" name="Scatter plot"]
+  [role="toolbar" name="Scatter plot toolbar"]
+    [class="vtb-controls"]
+      [role="button" name="Settings"]
+      [role="button" name="Properties"]
+      [role="button" name="Close"]
+
+[dg-widget-type="Viewer" dg-viewer-type="bar-chart"]
+  [role="toolbar"]
+    [role="button" name="Settings"]
+    ...
+
+[role="navigation"]
+  [role="button" name="Settings"]
+```
+
+## Expected response
+
+```json
+{
+  "candidates": [
+    {
+      "selector": "[dg-viewer-type=\"scatter-plot\"] [role=\"toolbar\"] [role=\"button\"][aria-label=\"Settings\"]",
+      "selector_type": "css",
+      "matched_attributes": [
+        "dgWidgetType",
+        "dgViewerType",
+        "ariaRole",
+        "ariaLabel",
+        "parentChain"
+      ],
+      "rationale": "Scopes by dgViewerType to disambiguate the three 'Settings' buttons on the page. Role and accessible name are preserved.",
+      "risk_notes": "If the toolbar role is dropped in a future change, this would break; consider adding a stable testid in the platform."
+    },
+    {
+      "selector": "[dg-viewer-type=\"scatter-plot\"] .vtb-controls [role=\"button\"][aria-label=\"Settings\"]",
+      "selector_type": "css",
+      "matched_attributes": [
+        "dgViewerType",
+        "stableClasses",
+        "ariaRole",
+        "ariaLabel",
+        "parentChain"
+      ],
+      "rationale": "Adds the inner controls class as additional structural scoping. Slightly more specific than the toolbar-role version."
+    }
+  ],
+  "unable_to_match": false
+}
+```
+
+## What the validator does next
+
+1. First candidate: matches one element. Runtime scorer:
+   - `dgWidgetType` + `dgViewerType` match: 0.80
+   - `ariaRole` match: combined into role+name 0.85
+   - `name` match: contributes via role+name
+   - `ariaLabel` match: 0.85
+   - `parentChain` match: 1.0 (rooted on viewer)
+   - testId absent on both sides: doesn't contribute either way
+   - visual: bounding box close enough → 0.25 if visual layer enabled
+   - Composite ~0.86 → HIGH band.
+2. Decision: heal silently.
+3. Note the second candidate's rationale mentions `vtb-controls` — the
+   validator would check whether that class survived. If it did and
+   the score is similar, the first candidate still wins on simplicity.
+
+This is a typical "structural refactor" case. Without `dgViewerType` as
+a Datagrok-specific anchor, the resolver would have failed at LOW. The
+platform's semantic layer is what makes this case healable.
diff --git a/libraries/self-healing-locators/prompts/system.md b/libraries/self-healing-locators/prompts/system.md
new file mode 100644
index 0000000000..3253f392e0
--- /dev/null
+++ b/libraries/self-healing-locators/prompts/system.md
@@ -0,0 +1,143 @@
+# System Prompt — Self-Healing Locators
+
+> The text below is the system prompt sent to Claude in the offline
+> healing tool. It is intentionally short and structured. Every line
+> earns its place; please review for ambiguity or missing constraints.
+>
+> When this prompt is shipped, the library reads from this file and
+> sends its content as the `system` field of the Anthropic Messages API
+> call. Treat changes to this file as code changes — they go through
+> the eval suite.
+
+---
+
+You are a test-maintenance assistant for the Datagrok platform. Your job
+is to propose CSS, XPath, role-based, or test-id selectors that locate
+the element a UI test originally targeted, given a recorded fingerprint
+of that element and the current state of the page.
+
+You are one stage of a larger pipeline. A deterministic resolver has
+already tried the obvious selectors and failed. Whatever you propose
+will be validated against a live page by an automated scorer. The
+scorer has the final say on whether your proposals are accepted.
+
+## What you receive
+
+- A fingerprint of the element captured the last time the test passed.
+  It contains semantic attributes (`testId`, `domId`, `ariaLabel`,
+  `ariaRole`, `name`, Datagrok widget metadata), structural information
+  (`tagName`, `stableClasses`, parent chain), text content, and
+  optionally visual properties.
+- A pruned accessibility tree of the page in roughly the state where
+  the test failed.
+- The selector the test originally used, and the action it intended
+  (click, type, assert, etc.).
+- A list of selectors that the deterministic resolver already tried
+  and that did not work — do not propose any of these.
+- Optionally: a screenshot of the page region.
+
+## What you produce
+
+Use the `propose_locators` tool to return a structured response. Do not
+emit free-form text. The schema requires:
+
+- `candidates` — zero to five proposed selectors, ranked by your
+  estimate of stability. Each candidate has:
+  - `selector` — the selector string itself.
+  - `selector_type` — one of `css`, `xpath`, `role`, `testid`, `text`.
+  - `matched_attributes` — the names of fingerprint features your
+    selector relies on, drawn from the documented vocabulary.
+  - `rationale` — at most 400 characters, explaining briefly which
+    fingerprint features back this selector.
+  - `risk_notes` — at most 400 characters, optional, flagging anything
+    that could go wrong.
+- `unable_to_match` — true if you cannot propose any candidate you
+  consider plausible. In this case, `candidates` must be empty.
+- `unable_reason` — required when `unable_to_match` is true.
+
+## Priorities
+
+When you have multiple options, prefer in this order:
+
+1. `data-testid` if a stable one is present in both the fingerprint and
+   the live page (or close to it).
+2. `id` if it is present and looks stable (not a UUID, not a hash).
+3. `role` + accessible `name` (Playwright `getByRole(role, { name })`
+   form, or equivalent). The accessibility tree is usually more stable
+   than the DOM.
+4. Datagrok widget type (`dg-widget-type` attribute or equivalent
+   hook). Use this when the element belongs to a Datagrok widget and
+   the fingerprint records its type.
+5. Visible text (`getByText`, `getByPlaceholder`, `getByTitle`) — only
+   when the fingerprint indicates the text is not dynamic.
+6. Structural selectors (tag + stable classes + parent chain). These
+   are the weakest; use as a last resort and only when the parent
+   chain is anchored on a stable parent.
+
+## Hard constraints
+
+- Do not propose selectors that rely on CSS-in-JS hash classes
+  (e.g. `.css-1a2b3c4`, `._abcd1234`). The fingerprint will have
+  filtered these out; if you see them in the live tree, ignore them.
+- Do not propose selectors that match more than one element on the
+  page. If you cannot avoid ambiguity, set `unable_to_match` to true
+  with reason `ambiguous_candidates`.
+- Do not propose selectors using transient state classes
+  (`is-active`, `is-hover`, `is-focused`, `is-selected`, etc.).
+- Do not include the selectors listed as already-tried.
+- Do not propose selectors based on numeric `nth-child` indices unless
+  every other approach has failed and the index is anchored under a
+  uniquely-identified parent.
+- Do not return any candidates whose role differs from the fingerprint's
+  recorded role unless the change is a strengthening (implicit role
+  becoming explicit, e.g. `<div onclick>` → `<button>`). If the role
+  weakened or changed kind (`button` → `link`, `dialog` → `popover`),
+  set `unable_to_match` to true with reason `no_semantic_match_in_dom`.
+- Do not invent attributes that are not present on the live page. Only
+  use what the accessibility tree or HTML actually contains.
+
+## When to give up
+
+Set `unable_to_match: true` and choose the appropriate `unable_reason`
+when:
+
+- The element appears to be removed entirely (`no_semantic_match_in_dom`).
+- Multiple plausible candidates exist and you cannot disambiguate
+  (`ambiguous_candidates`).
+- The page state in the snapshot looks wrong — for instance, a modal
+  is open that wouldn't be at this point in the test
+  (`page_state_mismatch`).
+- The information you were given is not enough to decide
+  (`insufficient_context`).
+- Anything else that doesn't fit the categories above (`other`, with
+  `unable_reason_detail` filled in).
+
+Giving up cleanly is better than guessing. The pipeline has a path for
+human review of cases you cannot heal; it does not have a way to undo
+a heal that was based on a confident-sounding hallucination.
+
+## What you do not do
+
+- You do not estimate confidence numerically. The downstream scorer
+  computes confidence from objective feature matches against the
+  fingerprint.
+- You do not modify test logic, assertions, timing, or navigation.
+- You do not propose changes to the platform or the test framework.
+- You do not infer user intent beyond what the fingerprint records.
+  If the fingerprint says `purpose: 'destructive'` and the candidate
+  feels safer, that is not your call.
+- You do not apologize, restate the task, or describe your process.
+  Just call the tool.
+
+## Vocabulary for `matched_attributes`
+
+Use only these names. Spelling must match exactly.
+
+- Semantic: `testId`, `domId`, `ariaLabel`, `ariaRole`, `name`,
+  `dgWidgetType`, `dgViewerType`
+- Structural: `tagName`, `stableClasses`, `parentChain`
+- Text: `visibleText`, `placeholder`, `title`
+- Visual: `boundingBox`, `visualHash`
+
+If your selector relies on a feature not listed, your selector is
+probably not what we want. Reconsider, or set `unable_to_match`.
diff --git a/libraries/self-healing-locators/prompts/user-template.md b/libraries/self-healing-locators/prompts/user-template.md
new file mode 100644
index 0000000000..0cf04337ac
--- /dev/null
+++ b/libraries/self-healing-locators/prompts/user-template.md
@@ -0,0 +1,148 @@
+# User Message Template — Self-Healing Locators
+
+> The runtime renders this template into the `messages[0].content` of
+> the Anthropic API call. Sections wrapped in `{{...}}` are
+> substituted; everything else is literal. The template is intended to
+> be deterministic — same inputs yield byte-identical prompts so
+> caching works.
+
+---
+
+```
+<task>
+A UI test selector failed. The deterministic resolver tried the
+strategies it can attempt automatically and either could not find a
+unique element or found one with low confidence. Propose alternative
+selectors using the `propose_locators` tool.
+</task>
+
+<test_action>
+{{action}}
+</test_action>
+
+<failed_selector>
+{{originalSelector}}
+</failed_selector>
+
+<already_tried>
+{{#each alreadyTriedSelectors}}
+- {{this}}
+{{/each}}
+</already_tried>
+
+<fingerprint>
+{{fingerprintJson}}
+</fingerprint>
+
+<accessibility_tree>
+{{accessibilityTreeText}}
+</accessibility_tree>
+
+{{#if includeHtmlSnippet}}
+<html_snippet>
+{{htmlSnippet}}
+</html_snippet>
+{{/if}}
+
+{{#if includeScreenshot}}
+<note>
+A screenshot of the page region is attached as an image content block.
+Use it only as a sanity check; the accessibility tree is the primary
+source of truth.
+</note>
+{{/if}}
+
+<negative_constraints>
+- Selectors listed in <already_tried> have been verified to NOT work.
+  Do not propose them again or trivial variations of them.
+- The fingerprint reflects the element when the test last passed. The
+  accessibility tree above reflects the page now. Differences between
+  them are exactly what you are reasoning about.
+- The platform is Datagrok. Common UI primitives (`ui.button`,
+  `ui.input.*`, `ui.dialog`) typically expose ARIA roles and accessible
+  names; viewers expose `dg-widget-type` markers. Prefer these over
+  raw DOM selectors.
+- The test action is "{{action}}". If a candidate element cannot
+  receive this action (e.g. a static `<span>` for a click action),
+  do not propose it.
+</negative_constraints>
+
+<output_instructions>
+Call the `propose_locators` tool with up to 5 candidates ranked by
+your estimate of stability. If you cannot propose any plausible
+candidate, set `unable_to_match: true` with the appropriate
+`unable_reason`. Do not write any text outside the tool call.
+</output_instructions>
+```
+
+---
+
+## Substitution variables
+
+| Variable | Source | Notes |
+|---|---|---|
+| `action` | `healing.resolve()` options | One of `click`, `type`, `assert`, `read`, `hover`, etc. |
+| `originalSelector` | failed call site | The exact selector string that the test passed in. |
+| `alreadyTriedSelectors` | runtime resolver | Each candidate the deterministic tiers attempted, in order. Truncated to 20 entries — beyond that is noise. |
+| `fingerprintJson` | registry | The fingerprint object, with `contextSnippet` stripped to avoid duplication. JSON.stringify with 2-space indent. |
+| `accessibilityTreeText` | snapshot | A YAML-like flattening of the a11y tree, pruned per § "Pruning". |
+| `includeHtmlSnippet` | feature flag | True when the a11y tree alone is judged insufficient (e.g. dominant role is `generic`). |
+| `htmlSnippet` | snapshot | Sanitized outerHTML of the candidate region, truncated to 4 KB. Inline event handlers and data-* attributes preserved; class hashes left in (the LLM is told to ignore them). |
+| `includeScreenshot` | feature flag + classification | True only when screenshots are enabled AND case is classified structural-or-worse. |
+
+## Pruning rules for the accessibility tree
+
+We do not send the entire a11y tree. The pruner walks the tree once
+and keeps:
+
+1. The current view's accessibility root.
+2. All nodes whose `role` matches the fingerprint's `ariaRole`.
+3. All nodes whose `name` is within Levenshtein distance 0.7 of the
+   fingerprint's `name`, `ariaLabel`, or `visibleText`.
+4. The 2-level neighborhood around each kept node.
+5. Nodes whose `dg-widget-type` matches the fingerprint's
+   `dgWidgetType`.
+
+Output format is a stable, indented text representation:
+
+```
+[role="dialog" name="Confirm" dg-widget-type="Dialog"]
+  [role="heading" level=1 name="Confirm"]
+  [role="button" name="OK" testid="dlg-ok"]
+  [role="button" name="Cancel" testid="dlg-cancel"]
+```
+
+The format is deterministic so prompts are reproducible and the
+response cache works.
+
+## Token-budget guards
+
+Before sending, the prompt builder verifies:
+
+- Total estimated tokens ≤ the model's budget for this case.
+- If over budget, prune in this order: drop screenshot → drop HTML
+  snippet → reduce a11y tree depth → reduce a11y tree breadth.
+- Never drop the fingerprint or the negative constraints. Never
+  drop the `already_tried` list (the LLM will repeat itself otherwise).
+
+## Why this template shape
+
+- **XML-style tags.** Claude follows these reliably for structure;
+  reduces "the LLM ignored part of the message" failures.
+- **No prose preamble.** "Hello, please consider this carefully" wastes
+  tokens and changes nothing about output quality.
+- **Negative constraints inline rather than in system.** Some
+  constraints are case-specific (the already-tried list). System stays
+  stable and cacheable; per-case detail goes here.
+- **Output instructions repeated.** The system prompt sets the contract;
+  the user message reinforces it. Helps when the prompt is long and
+  attention drifts.
+
+## What changes per call vs per case
+
+Per call (system + user template structure): **stable**. Cacheable on
+the Anthropic side via prompt caching.
+
+Per case (variables): **changes**. Constitutes the cache miss
+boundary. The case-id hash is also a cache key for our own
+deduplication layer in the CLI.
diff --git a/libraries/self-healing-locators/schemas/fingerprint.schema.json b/libraries/self-healing-locators/schemas/fingerprint.schema.json
new file mode 100644
index 0000000000..2ae878c3fd
--- /dev/null
+++ b/libraries/self-healing-locators/schemas/fingerprint.schema.json
@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://datagrok.ai/schemas/self-healing-locators/fingerprint-v1.json",
+  "title": "ElementFingerprint",
+  "description": "Captured evidence about a UI element used by self-healing locators. See docs/02-fingerprint-spec.md.",
+  "type": "object",
+  "required": ["schemaVersion", "anchorName", "capturedAt", "capturedBy", "testRef", "semantic", "structural", "text", "visual", "hints"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1" },
+    "anchorName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Logical name from healing.anchor() or auto-derived from selector + test."
+    },
+    "capturedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "capturedBy": {
+      "enum": ["auto", "explicit"]
+    },
+    "testRef": {
+      "type": "object",
+      "required": ["file", "test", "selectorAtCapture"],
+      "additionalProperties": false,
+      "properties": {
+        "file": { "type": "string" },
+        "suite": { "type": "string" },
+        "test": { "type": "string" },
+        "selectorAtCapture": { "type": "string" }
+      }
+    },
+    "semantic": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "testId": { "type": "string" },
+        "domId": { "type": "string" },
+        "ariaLabel": { "type": "string" },
+        "ariaRole": { "type": "string" },
+        "name": { "type": "string" },
+        "dgWidgetType": { "type": "string" },
+        "dgViewerType": { "type": "string" }
+      }
+    },
+    "structural": {
+      "type": "object",
+      "required": ["tagName", "stableClasses", "parentChain"],
+      "additionalProperties": false,
+      "properties": {
+        "tagName": { "type": "string" },
+        "stableClasses": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
+        "parentChain": {
+          "type": "array",
+          "maxItems": 3,
+          "items": {
+            "type": "object",
+            "required": ["tagName"],
+            "additionalProperties": false,
+            "properties": {
+              "tagName": { "type": "string" },
+              "testId": { "type": "string" },
+              "ariaRole": { "type": "string" },
+              "dgWidgetType": { "type": "string" },
+              "stableClasses": {
+                "type": "array",
+                "items": { "type": "string" },
+                "uniqueItems": true
+              }
+            }
+          }
+        },
+        "indexInParent": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "text": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "visibleText": { "type": "string", "maxLength": 200 },
+        "placeholder": { "type": "string", "maxLength": 200 },
+        "title": { "type": "string", "maxLength": 200 },
+        "valueAtCapture": { "type": "string" }
+      }
+    },
+    "visual": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "boundingBox": {
+          "type": "object",
+          "required": ["x", "y", "width", "height"],
+          "additionalProperties": false,
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" },
+            "width": { "type": "number" },
+            "height": { "type": "number" }
+          }
+        },
+        "viewportSize": {
+          "type": "object",
+          "required": ["w", "h"],
+          "additionalProperties": false,
+          "properties": {
+            "w": { "type": "number" },
+            "h": { "type": "number" }
+          }
+        },
+        "visualHash": {
+          "type": "string",
+          "description": "Perceptual hash of the element-only screenshot. Present only when the screenshots feature flag is on."
+        },
+        "screenshotRef": {
+          "type": "string",
+          "description": "Path under registry/screenshots/. Present only when image retention is enabled."
+        }
+      }
+    },
+    "hints": {
+      "type": "object",
+      "required": ["domIdLooksStable", "classesAreCssInJs", "textIsLikelyDynamic"],
+      "additionalProperties": false,
+      "properties": {
+        "domIdLooksStable": { "type": "boolean" },
+        "classesAreCssInJs": { "type": "boolean" },
+        "textIsLikelyDynamic": { "type": "boolean" },
+        "elementIsInsideViewer": { "type": "string" },
+        "platformVersion": { "type": "string" }
+      }
+    },
+    "contextSnippet": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "accessibilityNode": { "type": "object" },
+        "htmlSnippet": { "type": "string", "maxLength": 4096 }
+      }
+    },
+    "purpose": {
+      "type": "string",
+      "enum": ["normal", "destructive", "auth"],
+      "description": "Optional severity tag set via healing.anchor() that influences the policy gates."
+    },
+    "deprecated": {
+      "type": "boolean",
+      "description": "Marked true when an anchor name is being phased out; pruned after one minor version."
+    }
+  }
+}
diff --git a/libraries/self-healing-locators/schemas/healing-event.schema.json b/libraries/self-healing-locators/schemas/healing-event.schema.json
new file mode 100644
index 0000000000..eb7e70709c
--- /dev/null
+++ b/libraries/self-healing-locators/schemas/healing-event.schema.json
@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://datagrok.ai/schemas/self-healing-locators/healing-event-v1.json",
+  "title": "HealingEvent",
+  "description": "One audit-log entry. See docs/04-runtime-flow.md § 5.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "eventId",
+    "timestamp",
+    "testRef",
+    "anchorName",
+    "originalSelector",
+    "tierUsed",
+    "score",
+    "band",
+    "matched_features",
+    "absent_features",
+    "demotions_applied",
+    "ambiguity_check",
+    "flagForReview",
+    "queuedOffline"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1" },
+    "eventId": { "type": "string", "format": "uuid" },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "testRef": {
+      "type": "object",
+      "required": ["file", "test"],
+      "properties": {
+        "file": { "type": "string" },
+        "suite": { "type": "string" },
+        "test": { "type": "string" }
+      }
+    },
+    "anchorName": { "type": "string" },
+    "originalSelector": { "type": "string" },
+    "resolvedSelector": {
+      "type": ["string", "null"],
+      "description": "The selector that actually worked, if any. Null on failure."
+    },
+    "tierUsed": {
+      "enum": ["primary", "tier1", "tier2", "tier3", "tier4", "failed"]
+    },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "band": {
+      "enum": ["HIGH", "MID", "LOW", "FAIL"]
+    },
+    "matched_features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "weight", "match"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "weight": { "type": "number" },
+          "match": { "type": "number", "minimum": 0, "maximum": 1 }
+        }
+      }
+    },
+    "absent_features": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "demotions_applied": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "ambiguity",
+          "semantic_mismatch",
+          "action_mismatch",
+          "dg_widget_mismatch",
+          "platform_version_skew"
+        ]
+      }
+    },
+    "ambiguity_check": {
+      "enum": ["passed", "failed"]
+    },
+    "flagForReview": { "type": "boolean" },
+    "queuedOffline": { "type": "boolean" },
+    "error": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Present only on failure."
+    },
+    "runMetadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}
diff --git a/libraries/self-healing-locators/schemas/tool-response.schema.json b/libraries/self-healing-locators/schemas/tool-response.schema.json
new file mode 100644
index 0000000000..052afedefa
--- /dev/null
+++ b/libraries/self-healing-locators/schemas/tool-response.schema.json
@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://datagrok.ai/schemas/self-healing-locators/tool-response-v1.json",
+  "title": "ProposeLocatorsResponse",
+  "description": "Schema enforced on Claude's tool_use response. See docs/05-offline-flow.md § 7.",
+  "type": "object",
+  "required": ["candidates", "unable_to_match"],
+  "additionalProperties": false,
+  "properties": {
+    "candidates": {
+      "type": "array",
+      "minItems": 0,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "required": ["selector", "selector_type", "matched_attributes", "rationale"],
+        "additionalProperties": false,
+        "properties": {
+          "selector": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "selector_type": {
+            "enum": ["css", "xpath", "role", "testid", "text"]
+          },
+          "matched_attributes": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "enum": [
+                "testId",
+                "domId",
+                "ariaLabel",
+                "ariaRole",
+                "name",
+                "dgWidgetType",
+                "dgViewerType",
+                "tagName",
+                "stableClasses",
+                "parentChain",
+                "visibleText",
+                "placeholder",
+                "title",
+                "boundingBox",
+                "visualHash"
+              ]
+            },
+            "minItems": 1,
+            "description": "Subset of fingerprint feature names that this selector relies on. Vocabulary is fixed."
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 400
+          },
+          "risk_notes": {
+            "type": "string",
+            "maxLength": 400
+          }
+        }
+      }
+    },
+    "unable_to_match": { "type": "boolean" },
+    "unable_reason": {
+      "enum": [
+        "no_semantic_match_in_dom",
+        "ambiguous_candidates",
+        "page_state_mismatch",
+        "insufficient_context",
+        "other"
+      ]
+    },
+    "unable_reason_detail": {
+      "type": "string",
+      "maxLength": 400
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "unable_to_match": { "const": true } } },
+      "then": {
+        "required": ["unable_reason"],
+        "properties": {
+          "candidates": { "maxItems": 0 }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "unable_to_match": { "const": false } } },
+      "then": {
+        "properties": {
+          "candidates": { "minItems": 1 }
+        }
+      }
+    }
+  ]
+}
diff --git a/tools/self-healing-cli/README.md b/tools/self-healing-cli/README.md
new file mode 100644
index 0000000000..16f2ab560c
--- /dev/null
+++ b/tools/self-healing-cli/README.md
@@ -0,0 +1,66 @@
+# grok-heal — Self-Healing Maintenance CLI
+
+Offline companion to `@datagrok-libraries/self-healing-locators`. Reads
+the healing queue produced by failed runtime resolutions, asks Claude
+to propose new selectors for cases the deterministic resolver couldn't
+handle, validates each proposal against a live page, and opens a PR
+with codemod'd test source updates.
+
+## Status
+
+**Design phase.** This directory currently contains design docs only.
+See [`docs/cli-overview.md`](./docs/cli-overview.md) and the library's
+[offline flow doc](../../libraries/self-healing-locators/docs/05-offline-flow.md)
+for the proposed behavior.
+
+## Commands (planned)
+
+```
+grok-heal queue              List cases waiting for offline processing.
+grok-heal run [--model auto] Process the queue end to end.
+grok-heal validate <case-id> Dry-run a single case (no PR).
+grok-heal pr                 Open or update healing PR(s).
+grok-heal mark <case-id>     Record a review decision on a case.
+grok-heal eval               Run the regression eval suite.
+grok-heal registry prune     Clean up stale fingerprints.
+```
+
+## Configuration
+
+Per-repository config lives at
+`tools/self-healing-cli/config.json` and may be overridden by env vars:
+
+```json
+{
+  "model_selection": {
+    "default": "claude-haiku-4-5",
+    "structural": "claude-sonnet-4-6",
+    "escalation": "claude-opus-4-7"
+  },
+  "cost_cap_usd_per_run": 10.0,
+  "case_retry_limit": 2,
+  "cache_ttl_days": 7,
+  "pr_grouping": "per-package",
+  "pr_default_reviewer": "CODEOWNERS",
+  "browser_engine": "playwright",
+  "headless": true,
+  "registry_path": "../../libraries/self-healing-locators/registry/v1",
+  "queue_path": "test-output/self-healing/healing-queue.jsonl"
+}
+```
+
+The Anthropic API key is read from `ANTHROPIC_API_KEY`. The CLI fails
+loudly if it isn't set; it never falls back to a different provider.
+
+## Out-of-scope (and intentionally so)
+
+- Mutating the fingerprint registry. Fingerprint updates are a
+  capture-time concern handled by the runtime library.
+- Modifying tests outside of the selector argument at the recorded
+  call site.
+- Auto-merging PRs.
+- Calling any LLM other than Claude.
+
+## License
+
+Same as the parent repository.
diff --git a/tools/self-healing-cli/docs/cli-overview.md b/tools/self-healing-cli/docs/cli-overview.md
new file mode 100644
index 0000000000..c9cdbc97b4
--- /dev/null
+++ b/tools/self-healing-cli/docs/cli-overview.md
@@ -0,0 +1,111 @@
+# CLI Overview
+
+> Status: compact. Detailed pipeline lives in
+> `libraries/self-healing-locators/docs/05-offline-flow.md`.
+
+## What `grok-heal` is
+
+The offline maintenance binary for the self-healing system. It consumes
+the healing queue, calls Claude on cases the deterministic runtime
+resolver couldn't heal, validates proposals against a live page, and
+opens a PR with the resulting selector changes.
+
+## Where it runs
+
+- **CI (scheduled).** Nightly job after the day's test runs settle.
+  Best for steady-state maintenance.
+- **CI (post-release).** Triggered after a platform release that
+  produces queued cases.
+- **Locally.** Engineers can run a single case through the pipeline
+  during investigation: `grok-heal validate <case-id>`.
+
+## Commands
+
+### `grok-heal queue [--filter ...]`
+
+Prints pending cases. Filters: `--package`, `--anchor`, `--since`,
+`--band` (mid|low|fail). No side effects.
+
+### `grok-heal run`
+
+End-to-end processing of the queue. Honors the cost cap. Produces a
+report and (unless `--dry-run`) opens PR(s).
+
+Flags:
+- `--dry-run` — skip codemod and PR opening.
+- `--cost-cap-usd <N>` — override config.
+- `--model auto|haiku|sonnet|opus` — force a specific model. Default `auto`
+  uses the rules in the offline-flow doc § 5.
+- `--package <name>` — restrict to one package's cases.
+
+### `grok-heal validate <case-id>`
+
+Reproduces one case end-to-end. Prints the Claude proposals, the
+validator's per-candidate scores, the chosen winner if any, and the
+diff that would be applied. Never mutates anything. Used during
+investigation and during eval calibration.
+
+### `grok-heal pr [--package <name>]`
+
+Opens or updates the healing PR(s). Idempotent: if a PR already exists
+for the package and the new content is unchanged, no action.
+
+### `grok-heal mark <case-id> --accepted|--rejected [--reason <text>]`
+
+Records a review decision. `--rejected` cases are remembered until
+either the fingerprint or the page snapshot hash changes; the same
+heal will not be re-proposed in the meantime.
+
+### `grok-heal eval [--fixtures <path>]`
+
+Runs the regression eval. Used in CI to gate changes to the library,
+the prompt, the weights, or the model selection rules. Reports per-tier
+contribution and per-band metrics; see
+`libraries/self-healing-locators/docs/09-eval-and-rollout.md`.
+
+### `grok-heal registry prune`
+
+Removes orphaned fingerprints (anchors no longer used by any test) and
+deprecated anchors past their deadline. Opens a cleanup PR.
+
+## Outputs
+
+Per run:
+
+- `tools/self-healing-cli/output/healing-report-<run-id>.json` —
+  summary, costs, per-case status.
+- `tools/self-healing-cli/output/healing-results/<case-id>.json` —
+  Claude proposals + validator scores + decision.
+- One PR per package (or one combined PR per `pr_grouping` config),
+  with the table of heals in the body.
+
+## Cost control
+
+- Hard per-run cap from config; checked before each Claude call.
+- Per-case retry cap of 2 (Haiku → Sonnet → stop).
+- Response cache keyed on `(fingerprint hash, page snapshot hash, model)`,
+  TTL 7 days by default.
+- Cases over the cap are deferred to the next run.
+
+## Failure modes
+
+The CLI exits non-zero only on infrastructure failures (cannot read
+queue, cannot write report, cannot reach git remote). Per-case failures
+land in the report with structured reasons; a queue with all cases
+failing produces a `0` exit and a report describing why. CI dashboards
+read the report, not the exit code.
+
+## Dependencies
+
+Runtime library (`@datagrok-libraries/self-healing-locators`) — for
+schemas, scorer, registry I/O.
+
+Anthropic SDK (`@anthropic-ai/sdk`) — Claude client. The only LLM
+provider the CLI supports.
+
+`playwright` (or `puppeteer`, depending on which adapter the package
+uses for tests) — for candidate validation against a live page.
+
+`jscodeshift` or equivalent — for the codemod step.
+
+`@octokit/*` (or platform-equivalent) — for opening PRs.