From ece04b3661cadde973b440f619030a1d727ee9fe Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 10:38:04 -0500
Subject: [PATCH 01/10] checkpoint: monorepo enscli+ensskills, fix pnpm
 warnings

---
 .gitignore     | 3 +++
 package.json   | 6 +++++-
 pnpm-lock.yaml | 9 +++++++++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 898696d363..13ffe429e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,3 +46,6 @@ apps/ensrainbow/test-*
 apps/fallback-ensapi/dist
 
 
+
+# Agent skills from npm packages (managed by skills-npm)
+**/skills/npm-*
diff --git a/package.json b/package.json
index 3bfddad501..25a9cf666c 100644
--- a/package.json
+++ b/package.json
@@ -33,16 +33,20 @@
     "generate": "pnpm run -w \"/^generate:.*/\"",
     "generate:openapi": "pnpm -r generate:openapi",
     "generate:gqlschema": "pnpm -r generate:gqlschema",
-    "generate:skills": "pnpm -F ensskills generate"
+    "generate:skills": "pnpm -F ensskills generate",
+    "prepare": "skills-npm --cwd ."
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.1",
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
     "@typescript/native-preview": "7.0.0-dev.20260128.1",
+    "enscli": "workspace:*",
+    "ensskills": "workspace:*",
     "jsdom": "^27.0.1",
     "prettier": "catalog:",
     "prettier-plugin-astro": "catalog:",
+    "skills-npm": "^1",
     "tsup": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1472d8e993..25d1c6cd2a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -177,6 +177,12 @@ importers:
       '@typescript/native-preview':
         specifier: 7.0.0-dev.20260128.1
         version: 7.0.0-dev.20260128.1
+      enscli:
+        specifier: workspace:*
+        version: link:packages/enscli
+      ensskills:
+        specifier: workspace:*
+        version: link:packages/ensskills
       jsdom:
         specifier: ^27.0.1
         version: 27.0.1(postcss@8.5.12)
@@ -186,6 +192,9 @@ importers:
       prettier-plugin-astro:
         specifier: 'catalog:'
         version: 0.14.1
+      skills-npm:
+        specifier: ^1
+        version: 1.1.1
       tsup:
         specifier: 'catalog:'
         version: 8.5.0(jiti@2.6.1)(postcss@8.5.12)(tsx@4.22.3)(typescript@5.9.3)(yaml@2.8.3)

From f2e6cb937f5579dfb949ce8a6e697bd62cd714e0 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 10:47:05 -0500
Subject: [PATCH 02/10] minimize pnpm, commit shared agents folder

---
 .agents/skills/fix-audit/SKILL.md | 108 ++++++++++++++++++++++++++++++
 package.json                      |  43 ++++++------
 pnpm-lock.yaml                    |  47 ++++---------
 3 files changed, 140 insertions(+), 58 deletions(-)
 create mode 100644 .agents/skills/fix-audit/SKILL.md

diff --git a/.agents/skills/fix-audit/SKILL.md b/.agents/skills/fix-audit/SKILL.md
new file mode 100644
index 0000000000..0fd78a47cc
--- /dev/null
+++ b/.agents/skills/fix-audit/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: fix-audit
+description: >
+  Fix security vulnerabilities found by pnpm audit using a git worktree off of `main`.
+  Also use to maintain `pnpm.overrides` hygiene: prune overrides that are no longer
+  necessary and scope overrides so they don't rewrite peerDependency ranges.
+---
+
+# Fix Audit
+
+Fix security vulnerabilities reported by `pnpm audit` / `pnpm audit:osv`, keeping
+`pnpm.overrides` minimal and scoped.
+
+## Steps
+
+1. Create a git worktree off of `main` (branch `fix/deps`).
+2. Run `pnpm audit` and `pnpm audit:osv` to identify vulnerabilities.
+3. For each vulnerability, trace who pulls it in: `pnpm why -r <pkg>`.
+   - If a direct dependency: bump to the fixed version using a caret range (e.g. `^1.2.3`).
+   - If transitive: try bumping the parent direct dependency first.
+   - If the parent can't be bumped: add a `pnpm.overrides` entry (see format below).
+4. Run `pnpm install` and read the output — new "unmet peer" or "deprecated" warnings
+   mean an override is too broad (see Peer-range rewriting below).
+5. Re-run the audits to verify; repeat until clean.
+6. Prune obsolete overrides (see below) while you're here.
+7. Validate from the repo root: `pnpm lint`, `pnpm typecheck`, `pnpm test`.
+8. Propose a PR using lite /pr-notes.
+
+## Override format
+
+Use a ranged selector key that names the vulnerable range, and a caret target. This
+self-documents what the override guards and makes obsolescence checkable later:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "vulnerable-package@<1.2.3": "^1.2.3"
+    }
+  }
+}
+```
+
+## Peer-range rewriting: prefer scoped overrides
+
+pnpm applies range-selector overrides to **peerDependency ranges too**. A global
+override like `"vite@>=5.0.0 <=6.4.1": "^6.4.2"` rewrites every package's
+`vite` peer range that intersects the selector (e.g. `^6 || ^7 || ^8` becomes
+`^6.4.2`), producing false "unmet peer" warnings and duplicate installs across
+the workspace.
+
+If only one dependency subtree pulls the vulnerable version, scope the override
+to that parent instead:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "ponder>vite": "^6.4.2",
+      "vite-node>vite": "^6.4.2"
+    }
+  }
+}
+```
+
+Find the subtree(s) with `pnpm why -r <pkg>` before choosing global vs scoped.
+
+## Pruning obsolete overrides
+
+An override is obsolete when natural resolution no longer lands in the vulnerable
+range (dependents widened their ranges, or a fixed version is now latest-in-range).
+To check all overrides in one pass:
+
+1. Back up `package.json` and `pnpm-lock.yaml`.
+2. Set `pnpm.overrides` to `{}` and run `pnpm install --lockfile-only`.
+3. For each override selector `pkg@<range>`, check whether any resolved version of
+   `pkg` in the regenerated lockfile satisfies the vulnerable range
+   (`semver.satisfies` against versions grepped from the lockfile's `packages:` section).
+   - No match → override is unnecessary; remove it.
+   - Match → still load-bearing; keep it.
+4. Restore the backups, apply the pruning, and run `pnpm install`.
+
+Expect the final lockfile diff to contain **no resolved-version changes** for pruned
+overrides — pruning only removes override metadata. If versions change, the override
+was still doing work; re-check.
+
+## Unfixable warnings
+
+- Deprecated transitive deps with no fixed upstream release (check
+  `npm view <pkg>@<version> deprecated` and whether the parent has a newer version):
+  acknowledge them in `pnpm.allowedDeprecatedVersions`, pinned to the exact current
+  version so a future, different deprecated version still warns.
+- Genuinely unmet peers that work in practice (e.g. an unmaintained package peering
+  on an old major): acknowledge in `pnpm.peerDependencyRules.allowedVersions`, scoped
+  as `"parent>peer": "^N"`.
+- Verify suppressions under a *fresh* resolution (warnings only print when resolution
+  runs): back up the lockfile, delete it, `pnpm install --lockfile-only`, read the
+  output, restore the lockfile.
+
+## Rules
+
+- ALWAYS use caret ranges (`^x.y.z`) for override targets, never bare `>=`, to prevent
+  accidental major version bumps.
+- Prefer bumping direct dependencies over adding overrides; prefer scoped overrides
+  over global ones.
+- Group related changes logically.
+- If a fix requires a major version bump, warn me before proceeding.
+- If a vulnerability cannot be fixed (no patched version available), report it at the end.
diff --git a/package.json b/package.json
index 25a9cf666c..e11010555d 100644
--- a/package.json
+++ b/package.json
@@ -58,40 +58,35 @@
     "overrides": {
       "@adraffy/ens-normalize": "catalog:",
       "esbuild@<=0.24.2": ">=0.25.0",
-      "lodash@>=4.0.0 <=4.17.23": "^4.18.0",
-      "lodash-es@>=4.0.0 <=4.17.23": "^4.18.0",
-      "markdown-it@>=14.0.0 <14.1.1": ">=14.1.1",
       "tar@<=7.5.10": "^7.5.11",
       "ajv@<8.18.0": ">=8.18.0",
       "minimatch@<10.2.3": ">=10.2.3",
-      "rollup@>=4.0.0 <4.59.0": ">=4.59.0",
-      "svgo@>=3.0.0 <3.3.3": "^3.3.3",
       "ponder>@hono/node-server@<1.19.13": "catalog:",
-      "devalue@<5.8.1": "^5.8.1",
-      "undici@>=7.0.0 <7.24.0": "^7.24.0",
-      "undici@>=6.0.0 <6.24.0": "^6.24.0",
       "yauzl@<3.2.1": "^3.2.1",
       "fast-xml-parser@>=5.0.0 <5.7.0": ">=5.7.0",
       "kysely@>=0.26.0 <0.28.17": "0.28.17",
-      "h3@<1.15.9": ">=1.15.9",
       "yaml@>=2.0.0 <2.8.3": ">=2.8.3",
-      "picomatch@<2.3.2": "^2.3.2",
-      "picomatch@>=4.0.0 <4.0.4": ">=4.0.4",
-      "smol-toml@<1.6.1": ">=1.6.1",
-      "brace-expansion@>=4.0.0 <5.0.6": ">=5.0.6",
-      "defu@<=6.1.4": "^6.1.5",
-      "vite@>=5.0.0 <=6.4.1": "^6.4.2",
-      "axios@<1.15.2": "^1.15.2",
-      "follow-redirects@<1.16.0": "^1.16.0",
+      "ponder>vite": "^6.4.2",
+      "vite-node>vite": "^6.4.2",
       "dompurify@<3.4.0": "^3.4.0",
-      "protobufjs@>=7.0.0 <7.5.8": "7.5.8",
       "protobufjs@>=8.0.0 <8.3.0": "8.3.0",
-      "postcss@>=8.0.0 <8.5.12": "^8.5.12",
-      "uuid@>=10.0.0 <11.1.1": "^11.1.1",
-      "fast-uri@<3.1.2": "^3.1.2",
-      "fast-xml-builder@<1.1.7": "^1.1.7",
-      "ws@<8.20.1": "^8.20.1",
-      "shell-quote@<1.8.4": "^1.8.4"
+      "postcss@>=8.0.0 <8.5.12": "^8.5.12"
+    },
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "graphiql-explorer>graphql": "^16",
+        "graphiql-explorer>react": "^19",
+        "graphiql-explorer>react-dom": "^19",
+        "abitype>zod": "^4",
+        "@scalar/astro>astro": "^6"
+      }
+    },
+    "allowedDeprecatedVersions": {
+      "@esbuild-kit/core-utils": "3.3.2",
+      "@esbuild-kit/esm-loader": "2.6.5",
+      "glob": "10.5.0",
+      "source-map": "0.8.0-beta.0",
+      "whatwg-encoding": "3.1.1"
     },
     "ignoredBuiltDependencies": [
       "bun"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 25d1c6cd2a..c3c64ada02 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -112,40 +112,19 @@ catalogs:
 overrides:
   '@adraffy/ens-normalize': 1.11.1
   esbuild@<=0.24.2: '>=0.25.0'
-  lodash@>=4.0.0 <=4.17.23: ^4.18.0
-  lodash-es@>=4.0.0 <=4.17.23: ^4.18.0
-  markdown-it@>=14.0.0 <14.1.1: '>=14.1.1'
   tar@<=7.5.10: ^7.5.11
   ajv@<8.18.0: '>=8.18.0'
   minimatch@<10.2.3: '>=10.2.3'
-  rollup@>=4.0.0 <4.59.0: '>=4.59.0'
-  svgo@>=3.0.0 <3.3.3: ^3.3.3
   ponder>@hono/node-server@<1.19.13: ^1.19.13
-  devalue@<5.8.1: ^5.8.1
-  undici@>=7.0.0 <7.24.0: ^7.24.0
-  undici@>=6.0.0 <6.24.0: ^6.24.0
   yauzl@<3.2.1: ^3.2.1
   fast-xml-parser@>=5.0.0 <5.7.0: '>=5.7.0'
   kysely@>=0.26.0 <0.28.17: 0.28.17
-  h3@<1.15.9: '>=1.15.9'
   yaml@>=2.0.0 <2.8.3: '>=2.8.3'
-  picomatch@<2.3.2: ^2.3.2
-  picomatch@>=4.0.0 <4.0.4: '>=4.0.4'
-  smol-toml@<1.6.1: '>=1.6.1'
-  brace-expansion@>=4.0.0 <5.0.6: '>=5.0.6'
-  defu@<=6.1.4: ^6.1.5
-  vite@>=5.0.0 <=6.4.1: ^6.4.2
-  axios@<1.15.2: ^1.15.2
-  follow-redirects@<1.16.0: ^1.16.0
+  ponder>vite: ^6.4.2
+  vite-node>vite: ^6.4.2
   dompurify@<3.4.0: ^3.4.0
-  protobufjs@>=7.0.0 <7.5.8: 7.5.8
   protobufjs@>=8.0.0 <8.3.0: 8.3.0
   postcss@>=8.0.0 <8.5.12: ^8.5.12
-  uuid@>=10.0.0 <11.1.1: ^11.1.1
-  fast-uri@<3.1.2: ^3.1.2
-  fast-xml-builder@<1.1.7: ^1.1.7
-  ws@<8.20.1: ^8.20.1
-  shell-quote@<1.8.4: ^1.8.4
 
 patchedDependencies:
   '@changesets/assemble-release-plan@6.0.9':
@@ -4380,7 +4359,7 @@ packages:
     resolution: {integrity: sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      rollup: '>=4.59.0'
+      rollup: ^1.20.0||^2.0.0||^3.0.0||^4.0.0
     peerDependenciesMeta:
       rollup:
         optional: true
@@ -5060,7 +5039,7 @@ packages:
   '@tailwindcss/vite@4.3.0':
     resolution: {integrity: sha512-t6J3OrB5Fc0ExuhohouH0fWUGMYL6PTLhW+E7zIk/pdbnJARZDCwjBznFnkh5ynRnIRSI4YjtTH0t6USjJISrw==}
     peerDependencies:
-      vite: ^6.4.2
+      vite: ^5.2.0 || ^6 || ^7 || ^8
 
   '@tanstack/query-core@5.90.5':
     resolution: {integrity: sha512-wLamYp7FaDq6ZnNehypKI5fNvxHPfTYylE0m/ZpuuzJfJqhR5Pxg9gvGBHZx4n7J+V5Rg5mZxHHTlv25Zt5u+w==}
@@ -5399,13 +5378,13 @@ packages:
     resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
     engines: {node: ^14.18.0 || >=16.0.0}
     peerDependencies:
-      vite: ^6.4.2
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
   '@vitejs/plugin-react@5.2.0':
     resolution: {integrity: sha512-YmKkfhOAi3wsB1PhJq5Scj3GXMn3WvtQ/JC0xoopuHoXSdmtdStOpFrYaT1kie2YgFBcIe64ROzMYRjCrYOdYw==}
     engines: {node: ^20.19.0 || >=22.12.0}
     peerDependencies:
-      vite: ^6.4.2
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
 
   '@vitest/expect@4.1.8':
     resolution: {integrity: sha512-h3nDO677RDLEGlBxyQ5CW8RlMThSKSRLUePLOx09gNIWRL40edgA1GCZSZgf1W55MFAG6/Sw14KeaAnqv0NKdQ==}
@@ -5414,7 +5393,7 @@ packages:
     resolution: {integrity: sha512-LEiN/xe4OSIbKe9HQIp5OC24agGD9J5CnmMgsLohVVoOPWL9a2sBoR6VBx43jQZb7Kr1l4RCuyCJzcAa0+dojw==}
     peerDependencies:
       msw: ^2.4.9
-      vite: ^6.4.2
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
     peerDependenciesMeta:
       msw:
         optional: true
@@ -5521,7 +5500,7 @@ packages:
     resolution: {integrity: sha512-SDobKBbPIOe0cVL7QxMzGkuUGHvWTdihi9zOrrWaWUgFKe15cwEcwfWmgrcNzjT6kHnNmWuTajPHoIzUjYNYYQ==}
     peerDependencies:
       async-validator: ^4
-      axios: ^1.15.2
+      axios: ^1
       change-case: ^5
       drauu: ^0.4
       focus-trap: ^7
@@ -7029,7 +7008,7 @@ packages:
     resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
     engines: {node: '>=12.0.0'}
     peerDependencies:
-      picomatch: '>=4.0.4'
+      picomatch: ^3 || ^4
     peerDependenciesMeta:
       picomatch:
         optional: true
@@ -7630,7 +7609,7 @@ packages:
   isows@1.0.7:
     resolution: {integrity: sha512-I1fSfDCZL5P0v33sVqeTDSpcstAg/N+wF5HS033mogOVIp4B+oHC7oOCsA3axAbBSGTJ8QubbNmnIRN/h8U7hg==}
     peerDependencies:
-      ws: ^8.20.1
+      ws: '*'
 
   jackspeak@3.4.3:
     resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
@@ -10127,7 +10106,7 @@ packages:
   vite-tsconfig-paths@4.3.1:
     resolution: {integrity: sha512-cfgJwcGOsIxXOLU/nELPny2/LUD/lcf1IbfyeKTv2bsupVbTH/xpFtdQlBmIP1GEK2CjjLxYhFfB+QODFAx5aw==}
     peerDependencies:
-      vite: ^6.4.2
+      vite: '*'
     peerDependenciesMeta:
       vite:
         optional: true
@@ -10215,7 +10194,7 @@ packages:
   vitefu@1.1.3:
     resolution: {integrity: sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg==}
     peerDependencies:
-      vite: ^6.4.2
+      vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
     peerDependenciesMeta:
       vite:
         optional: true
@@ -10236,7 +10215,7 @@ packages:
       '@vitest/ui': 4.1.8
       happy-dom: '*'
       jsdom: '*'
-      vite: ^6.4.2
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
     peerDependenciesMeta:
       '@edge-runtime/vm':
         optional: true

From 8c579f8cbc621593327f2c421a3987d4bf605934 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 11:32:42 -0500
Subject: [PATCH 03/10] feat: agent overhaul

---
 .agents/skills/edit-ponder-sync/SKILL.md      | 206 +++++++++++++
 .../skills/ensindexer-perf-testing/SKILL.md   | 285 ++++++++++++++++++
 .agents/skills/fix-audit/SKILL.md             |   2 +-
 ...omnigraph-skill-acceleration-and-status.md |   5 +
 .gitignore                                    |   2 +-
 .mcp.json                                     |   8 +
 AGENTS.md                                     |  89 ++++--
 apps/ensadmin/AGENTS.md                       |  32 ++
 apps/ensadmin/CLAUDE.md                       |   1 +
 apps/ensapi/AGENTS.md                         |  48 +++
 apps/ensapi/CLAUDE.md                         |   1 +
 apps/ensindexer/AGENTS.md                     |  57 ++++
 apps/ensindexer/CLAUDE.md                     |   1 +
 apps/ensindexer/src/lib/graphnode-helpers.ts  |   4 +
 apps/ensrainbow/AGENTS.md                     |  42 +++
 apps/ensrainbow/CLAUDE.md                     |   1 +
 apps/fallback-ensapi/AGENTS.md                |  31 ++
 apps/fallback-ensapi/CLAUDE.md                |   1 +
 context7.json                                 |  12 +-
 docs/ensnode.io/AGENTS.md                     |  42 +++
 docs/ensnode.io/CLAUDE.md                     |   1 +
 package.json                                  |   2 +-
 packages/datasources/AGENTS.md                |  26 ++
 packages/datasources/CLAUDE.md                |   1 +
 .../ensskills/skills/ens-protocol/SKILL.md    |  16 +-
 .../references/ensv1-and-ensv2.md             |   4 +
 packages/ensskills/skills/omnigraph/SKILL.md  |   8 +
 packages/integration-test-env/AGENTS.md       |  33 ++
 packages/integration-test-env/CLAUDE.md       |   1 +
 scripts/link-local-skills.mjs                 |  39 +++
 skills-npm.config.ts                          |   7 +
 31 files changed, 965 insertions(+), 43 deletions(-)
 create mode 100644 .agents/skills/edit-ponder-sync/SKILL.md
 create mode 100644 .agents/skills/ensindexer-perf-testing/SKILL.md
 create mode 100644 .changeset/omnigraph-skill-acceleration-and-status.md
 create mode 100644 .mcp.json
 create mode 100644 apps/ensadmin/AGENTS.md
 create mode 120000 apps/ensadmin/CLAUDE.md
 create mode 100644 apps/ensapi/AGENTS.md
 create mode 120000 apps/ensapi/CLAUDE.md
 create mode 100644 apps/ensindexer/AGENTS.md
 create mode 120000 apps/ensindexer/CLAUDE.md
 create mode 100644 apps/ensrainbow/AGENTS.md
 create mode 120000 apps/ensrainbow/CLAUDE.md
 create mode 100644 apps/fallback-ensapi/AGENTS.md
 create mode 120000 apps/fallback-ensapi/CLAUDE.md
 create mode 100644 docs/ensnode.io/AGENTS.md
 create mode 120000 docs/ensnode.io/CLAUDE.md
 create mode 100644 packages/datasources/AGENTS.md
 create mode 120000 packages/datasources/CLAUDE.md
 create mode 100644 packages/integration-test-env/AGENTS.md
 create mode 120000 packages/integration-test-env/CLAUDE.md
 create mode 100644 scripts/link-local-skills.mjs
 create mode 100644 skills-npm.config.ts

diff --git a/.agents/skills/edit-ponder-sync/SKILL.md b/.agents/skills/edit-ponder-sync/SKILL.md
new file mode 100644
index 0000000000..7646f3f913
--- /dev/null
+++ b/.agents/skills/edit-ponder-sync/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: edit-ponder-sync
+description: >
+  Inspect and surgically edit Ponder's RPC sync cache (the `ponder_sync` Postgres schema):
+  understand what's cached, diagnose stale/contaminated cache (e.g. a restarted ens-test-env
+  devnet reusing chain id 31337), and clip/purge a block range so Ponder re-fetches it cleanly
+  without re-syncing the whole chain. Use when a handler throws RecordNotFoundError on an entity
+  that should exist, when cached block hashes diverge from the live chain, or when splicing one
+  chain's sync data into another (upstream chain → a fork of it).
+---
+
+# Editing Ponder Sync (`ponder_sync`)
+
+`ponder_sync` is Ponder's **RPC cache** — blocks, logs, transactions, receipts, traces, and the
+per-filter "what ranges have I synced" bookkeeping. It is separate from the **entity** schema
+(`ENSINDEXER_SCHEMA_NAME`, e.g. `ensindexer_temp_dev`) which holds the indexed app data (`domains`,
+`registries`, …) plus Ponder's `_ponder_checkpoint` / `_ponder_meta`.
+
+Editing `ponder_sync` is the right tool when the cache is **wrong or contaminated** and you want
+Ponder to re-fetch a range from the RPC. It is reversible (anything deleted is re-fetchable), but
+you must keep the `intervals` table consistent with the row tables or Ponder will trust a hole.
+
+Local Postgres in this repo: `postgresql://postgres@localhost:5432/ponder`. Always scope edits by `chain_id`.
+
+## Schema cheat-sheet
+
+```
+ponder_sync.blocks                -- one row per CACHED block. KEY COLUMN: number (NOT block_number).
+                                  --   columns: number, hash, parent_hash, timestamp, chain_id, …
+ponder_sync.logs                  -- block_number, log_index, address, topic0..3, block_hash, data, …
+ponder_sync.transactions          -- block_number, hash, from, to, …
+ponder_sync.transaction_receipts  -- block_number, transaction_hash, status, …  (often empty: Ponder
+                                  --   only fetches receipts when a handler/config needs them)
+ponder_sync.traces                -- block_number, trace_index, …                (often empty)
+ponder_sync.rpc_request_results   -- block_number (nullable), request_hash, result -- cached eth_call etc.
+ponder_sync.intervals             -- THE SOURCE OF TRUTH for "synced". fragment_id (PK), chain_id,
+                                  --   blocks (nummultirange).
+ponder_sync.factories /           -- factory-pattern (CREATE2 child) address discovery. Children
+ponder_sync.factory_addresses     --   discovered above a fork are valid current-chain data.
+```
+
+Gotchas that will bite you:
+
+- **`address`, `hash`, `topic*` are stored as TEXT** (`0x…` lowercase strings), **not bytea**.
+  `WHERE address = '\x0000…'` silently matches nothing and returns count 0. Use
+  `WHERE address = '0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e'`.
+- **`blocks` is sparse.** Ponder only caches blocks that contain a matching log (plus interval
+  boundaries / finalized blocks). Most heights have no row — a missing block in `blocks` is normal,
+  not a gap. Don't infer sync coverage from `blocks`; infer it from `intervals`.
+- **`blocks` uses `number`; every other table uses `block_number`.**
+- A row existing in `logs`/`blocks` does **not** mean Ponder will use it. Ponder decides what to
+  fetch/replay from `intervals`. If an interval says a range is synced, Ponder trusts the cache and
+  will **not** re-fetch — even if the cached blocks are stale.
+
+## How `intervals` works
+
+One row per **filter fragment** — a specific (chain, address, topic0, …) combination Ponder syncs.
+`fragment_id` looks like:
+
+```
+log_<chainId>_<address|null>_<topic0|null>_<topic1>_<topic2>_<topic3>_<n>
+```
+
+`blocks` is a Postgres `nummultirange` of the synced ranges, e.g.
+`{[3702728,10770756],[10887910,10888672]}`. A **gap** between segments = unsynced → Ponder
+re-fetches it. A continuous range = fully trusted cache.
+
+**Bounds must be inclusive `[a,b]`.** `nummultirange` is over `numeric`, which (unlike
+`int8range`) does **not** canonicalize `[)` → `[]`. If you intersect with a default-bound range you
+get a half-open `[a,b)` that Ponder mis-reads. Always force the inclusive upper bound:
+
+```sql
+-- WRONG: leaves an exclusive upper bound [3702728,10770757)
+blocks * nummultirange(numrange(NULL, 10770757))
+-- RIGHT: yields inclusive [3702728,10770756]
+blocks * nummultirange(numrange(NULL, 10770756, '(]'))
+```
+
+Sanity check after any interval edit — this must return 0:
+
+```sql
+SELECT count(*) FROM ponder_sync.intervals
+WHERE chain_id = <chain> AND blocks::text LIKE '%)%';
+```
+
+## Recipe: purge a chain wholesale (devnet restart)
+
+The ens-test-env devnet (anvil, chain id `31337`) is a fresh chain on every restart — but the chain
+id stays the same, so `ponder_sync` keeps trusting cache from the previous run and Ponder serves
+stale blocks instead of re-fetching. There is no clean prefix worth keeping (the chain is tiny and
+free to re-sync), so purge everything for the chain:
+
+```sql
+BEGIN;
+DELETE FROM ponder_sync.intervals            WHERE chain_id = 31337;
+DELETE FROM ponder_sync.logs                 WHERE chain_id = 31337;
+DELETE FROM ponder_sync.transaction_receipts WHERE chain_id = 31337;
+DELETE FROM ponder_sync.transactions         WHERE chain_id = 31337;
+DELETE FROM ponder_sync.traces               WHERE chain_id = 31337;
+DELETE FROM ponder_sync.rpc_request_results  WHERE chain_id = 31337;
+DELETE FROM ponder_sync.blocks               WHERE chain_id = 31337;
+COMMIT;
+```
+
+(Deterministic deploys may reproduce identical early blocks across runs — don't rely on it.)
+
+## Recipe: clip the cache to block N and re-fetch the tail
+
+Use when cache above some block N is stale/contaminated and you want Ponder to re-fetch `(N, head]`
+from the RPC while keeping the (expensive) deep history below N. Pick N = the **last block whose
+cached hash matches the live chain** (see diagnosis below).
+
+```sql
+BEGIN;
+-- 1. clip every synced interval to [.., N] inclusive
+UPDATE ponder_sync.intervals
+SET blocks = blocks * nummultirange(numrange(NULL, <N>, '(]'))
+WHERE chain_id = <chain>;
+
+-- 2. delete cached rows above N so they re-fetch clean (note: blocks uses `number`)
+DELETE FROM ponder_sync.logs                 WHERE chain_id=<chain> AND block_number > <N>;
+DELETE FROM ponder_sync.transaction_receipts WHERE chain_id=<chain> AND block_number > <N>;
+DELETE FROM ponder_sync.transactions         WHERE chain_id=<chain> AND block_number > <N>;
+DELETE FROM ponder_sync.traces               WHERE chain_id=<chain> AND block_number > <N>;
+DELETE FROM ponder_sync.rpc_request_results  WHERE chain_id=<chain> AND block_number > <N>;
+DELETE FROM ponder_sync.blocks               WHERE chain_id=<chain> AND number       > <N>;
+COMMIT;
+```
+
+Then restart the indexer. If the chain has **no** `_ponder_checkpoint` row and no entity rows, Ponder
+indexes it from scratch over the (now-correct) cache + re-fetched tail. If it has a checkpoint, it
+resumes from there.
+
+Always do interval clip + row deletes in **one transaction**, and keep them consistent: an interval
+that claims a range is synced while the rows are gone makes Ponder skip real events; rows present
+under a clipped interval are harmless (they get overwritten on re-fetch).
+
+## Diagnosing a stale / contaminated cache
+
+Symptom: a handler throws `RecordNotFoundError: No existing record found in table 'domains'` on a
+`db.update` (e.g. `ENSv1Registry:Transfer`) for an entity whose creating event (`NewOwner`) is
+earlier on-chain. The creating event was never indexed because the cache around it is stale.
+
+The usual culprit in this repo is a **restarted ens-test-env devnet** (chain id `31337`): the new
+run is a different chain under the same chain id, so every cached block from the old run diverges —
+purge the chain wholesale (recipe above). The same pattern appears with re-created forked testnets:
+re-forking gives the chain a **new fork block**, so cached blocks from the old incarnation diverge
+from the live chain, and clearing the cache only _above_ your resume point leaves the old-fork
+window _below_ it intact. The diagnosis below finds the clip point for that partial-divergence case.
+
+Steps:
+
+1. **Identify the failing node and its creating tx.** From the error, get `node`, `tx hash`,
+   `block`. Pull the receipt via the chain's RPC (`RPC_URL_<chainId>` in `apps/ensindexer/.env.local`)
+   to see the real event ordering (`NewOwner` creates, `Transfer`/`NewResolver` mutate).
+2. **Compare cached block hashes to the live chain** at the failing block and the creating block:
+
+   ```sql
+   SELECT number, hash FROM ponder_sync.blocks WHERE chain_id=<chain> AND number IN (<create>,<fail>);
+   ```
+
+   vs `eth_getBlockByNumber` on the live RPC. A mismatch at the creating block but a match at the
+   failing block = the cache below your resume point is from a different fork.
+
+3. **Find the true fork block** (last block where live testnet == real upstream chain) by binary
+   search over `eth_getBlockByNumber` hashes (testnet RPC vs a real upstream RPC, e.g. a public
+   node for the upstream chain). Test activity lives strictly **above** this block. (For the
+   ens-test-env devnet there is no upstream — skip the search and purge the chain wholesale.)
+4. **Find where the cache goes stale** (last cached block whose hash matches the real upstream
+   chain). Sample cached block numbers ascending and compare hashes; binary-search the boundary.
+   That boundary is the **old** fork — your clip point N.
+5. Clip + purge with the recipe above, using N = last clean block.
+
+Helper to compare a live RPC hash to the cache:
+
+```bash
+RPC=$(grep RPC_URL_<chainId> apps/ensindexer/.env.local | cut -d= -f2-)
+rpchash(){ curl -s -X POST "$1" -H 'content-type: application/json' \
+  --data "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getBlockByNumber\",\"params\":[\"$(printf 0x%x $2)\",false]}" \
+  | grep -o '"hash":"0x[0-9a-f]*"' | head -1 | sed 's/"hash":"//;s/"//'; }
+cachehash(){ psql "postgresql://postgres@localhost:5432/ponder" -tA \
+  -c "select hash from ponder_sync.blocks where chain_id=<chainId> and number=$1;"; }
+```
+
+## Splicing one chain's sync into a forked chain
+
+A forked testnet _is_ the upstream chain below its fork block, so you can avoid re-syncing millions
+of blocks through the fork's (often rate-limited) RPC by reusing real-upstream sync data:
+
+- For blocks `≤ forkBlock`: forked testnet ≡ upstream chain. Cache built against the upstream chain
+  (with `chain_id` rewritten to the testnet's id) is valid.
+- For blocks `> forkBlock`: only the testnet has the data; must come from the testnet RPC.
+
+The clip-and-refetch recipe handles the common case: keep valid cache below the (true, current)
+fork, let Ponder fetch the small tail above it from the fork's RPC. Only hand-splice upstream rows if even
+that tail is too large for the testnet RPC. When splicing, rewrite `chain_id` on every table **and**
+`intervals`, and keep `intervals` bounds inclusive.
+
+## Don't
+
+- Don't propose a Drizzle/Ponder schema migration — `ponder_sync` is Ponder-owned; edit it directly
+  in SQL, never via app migrations.
+- Don't delete rows without clipping the matching `intervals` (Ponder will trust the now-empty range
+  and skip events).
+- Don't trust the `blocks` table for coverage (it's sparse); trust `intervals`.
+- Don't use `\x…` bytea literals against the TEXT `address`/`hash`/`topic*` columns.
diff --git a/.agents/skills/ensindexer-perf-testing/SKILL.md b/.agents/skills/ensindexer-perf-testing/SKILL.md
new file mode 100644
index 0000000000..a7869a7d75
--- /dev/null
+++ b/.agents/skills/ensindexer-perf-testing/SKILL.md
@@ -0,0 +1,285 @@
+---
+name: ensindexer-perf-testing
+description: >
+  Run perf tests on the ENSIndexer (Ponder app under apps/ensindexer). Establishes a clean,
+  reproducible baseline by disabling ENSRainbow healing on the hot path
+  (DISABLE_ENSRAINBOW_HEAL), isolating the schema, wiping prometheus between runs, and
+  snapshotting per-handler metrics at realtime. Use when the user
+  asks to compare branches/configs, build a perf baseline, or measure a plugin combination.
+---
+
+# ENSIndexer perf testing
+
+Captures wall-clock + per-handler timings for an ENSIndexer run. Always works in the same shape:
+configure → disable heal → wipe → start → wait → snapshot → restore.
+
+## Required state before starting
+
+- Postgres at `postgresql://postgres@localhost:5432/ponder` is up.
+- ENSRainbow data at `apps/ensrainbow/data/data-subgraph_0/` is hydrated. (The `data-ens-test-env_0/` dir is for ETE; it lacks subgraph labels.)
+- Docker daemon is running (for prometheus/grafana sidecars).
+- Working tree is clean (perf numbers must come from the branch as committed — no stray edits).
+
+If any of these aren't true, fix that first — don't paper over it.
+
+## Step 1 — start prometheus + grafana
+
+```bash
+cd packages/ensindexer-perf-testing && pnpm start
+# prometheus :9090, grafana :3001 (anonymous admin)
+```
+
+Confirm scrape target is reachable:
+
+```bash
+curl -s http://localhost:9090/api/v1/targets?state=active | jq -r '.data.activeTargets[].health'
+# should be 'up' once indexer starts
+```
+
+## Step 2 — start ENSRainbow (subgraph label set)
+
+ENSIndexer performs an explicit health + ready check against ENSRainbow at startup, so the
+service must be running even when healing is disabled. Use the `subgraph` data dir for mainnet
+runs:
+
+```bash
+cd apps/ensrainbow && \
+  DATA_DIR=$PWD/data/data-subgraph_0 PORT=3223 LOG_LEVEL=warn \
+  pnpm tsx src/cli.ts serve > /tmp/perf-test/ensrainbow.log 2>&1 &
+# wait ~5s, then verify
+curl -s http://localhost:3223/health
+```
+
+For ens-test-env runs, swap `DATA_DIR=…/data-ens-test-env_0` and set
+`LABEL_SET_ID=ens-test-env` in `.env.local`.
+
+## Step 3 — disable ENSRainbow healing
+
+Set the undocumented env var `DISABLE_ENSRAINBOW_HEAL=true` (add it to `.env.local` in Step 4, or
+export it before launching). `labelByLabelHash` (`src/lib/graphnode-helpers.ts`) early-returns
+`null` — every label is treated as unhealable — giving an apples-to-apples baseline without
+ENSRainbow round-trips. No code edit needed.
+
+This changes indexing output: never set it outside perf runs, and always remove it from
+`.env.local` at end of run.
+
+## Step 4 — configure `.env.local`
+
+Pick a unique schema per run so concurrent/sequential runs don't pollute each other:
+
+```env
+NAMESPACE=mainnet
+PLUGINS=ensv2,protocol-acceleration   # or whatever combo
+ENSINDEXER_SCHEMA_NAME=ensindexer_perf_<label>
+DISABLE_ENSRAINBOW_HEAL=true
+
+ENSRAINBOW_URL=http://localhost:3223
+LABEL_SET_ID=subgraph
+LABEL_SET_VERSION=0
+ENSDB_URL=postgresql://postgres@localhost:5432/ponder
+```
+
+`LABEL_SET_ID=subgraph` is required for mainnet runs — `ens-test-env` will fail config
+validation against the subgraph label set baseline.
+
+Useful preset combos:
+
+- "alpha": `subgraph,basenames,lineanames,threedns,ensv2,protocol-acceleration,registrars,tokenscope`
+- "ensv2": `ensv2,protocol-acceleration`
+- "subgraph": `subgraph,basenames,lineanames,threedns,protocol-acceleration`
+
+## Step 5 — wipe state
+
+```bash
+PGPASSWORD= psql -U postgres -h localhost -d ponder \
+  -c "drop schema if exists ensindexer_perf_<label> cascade;"
+cd packages/ensindexer-perf-testing && pnpm wipe   # purges prometheus tsdb
+```
+
+## Step 6 — record start, launch indexer
+
+Always use `pnpm start` (production mode) — `pnpm dev` will hot-reload on file changes mid-run
+and tank the result. The schema env var must be exported because the start script references
+`$ENSINDEXER_SCHEMA_NAME` via shell expansion:
+
+```bash
+cd apps/ensindexer
+date "+%s" > /tmp/perf-test/main-<label>-start-epoch.txt
+date "+%Y-%m-%d %H:%M:%S %z" > /tmp/perf-test/main-<label>-start.txt
+ENSINDEXER_SCHEMA_NAME=ensindexer_perf_<label> pnpm start \
+  > /tmp/perf-test/main-<label>-indexer.log 2>&1 &
+```
+
+Watch the log for these signals:
+
+- `Indexed block range chain=…` lines start within ~10s = healthy
+- `ENSRainbow instance is healthy/ready` = config check passed
+- Errors (`Cannot find`, `MODULE_NOT_FOUND`, `Invariant(...)`) = abort and triage
+
+## Step 7 — wait for realtime
+
+The indexer is "done" when every chain has transitioned from backfill to live indexing. The
+authoritative signal is the indexer log line `Started live indexing chain=<id>` — one per
+chain, emitted as that chain crosses from historical to realtime. **Do NOT use prometheus
+metrics for this** — current Ponder (0.16.x) does _not_ emit `ponder_sync_is_realtime` or
+`ponder_sync_block_target`. A polling script based on those will hang forever.
+
+The expected chain count is derived from the same log: one `Started backfill indexing chain=`
+line is emitted per indexed chain at startup. The wait script reads it after the indexer is
+healthy and grep-counts the live-indexing lines until they match.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+LABEL=${1:-run}
+LOG=/tmp/perf-test/main-${LABEL}-indexer.log
+
+# Expected chain count = number of "Started backfill indexing chain=" lines.
+# Read after the indexer is past startup (give it ~10s).
+EXPECTED_CHAINS=$(grep -c "Started backfill indexing chain=" "$LOG" 2>/dev/null || echo 0)
+[ "$EXPECTED_CHAINS" -gt 0 ] || { echo "no chains started"; exit 1; }
+
+bail_if_crashed() {
+  if grep -qE "unhandledRejection|Started shutdown|index row requires|ELIFECYCLE|Failed to shutdown" "$LOG" 2>/dev/null; then
+    echo "INDEXER CRASHED"; tail -50 "$LOG"; exit 99
+  fi
+}
+
+while true; do
+  bail_if_crashed
+  count=$(grep -c "Started live indexing chain=" "$LOG" 2>/dev/null || true)
+  count=${count:-0}
+  echo "$(date '+%H:%M:%S') chains live: $count/$EXPECTED_CHAINS"
+  [ "$count" -ge "$EXPECTED_CHAINS" ] && break
+  sleep 60
+done
+
+date "+%s" > "/tmp/perf-test/main-${LABEL}-end-epoch.txt"
+date "+%Y-%m-%d %H:%M:%S %z" > "/tmp/perf-test/main-${LABEL}-end.txt"
+```
+
+Notes on EPS shape near the end: as chains finish backfill one-by-one, the instantaneous EPS
+_drops_ significantly because fewer chains are concurrently busy. That is expected — not a
+regression. Don't bail just because EPS fell from 3000 to 800. Only bail on a crash signature
+or a literal lack of progress (no new `Indexed block range` lines for many minutes).
+
+Mainnet alpha-class runs take ~8-15h on this hardware. Set up a single completion notifier:
+
+```bash
+until [ -f /tmp/perf-test/main-<label>-end-epoch.txt ]; do sleep 60; done
+```
+
+Run that with `run_in_background: true` — one notification when done, no polling.
+
+## Step 8 — snapshot metrics at end-of-run timestamp
+
+Critical: query prometheus _at_ the end-epoch timestamp, not "now". After the indexer shuts
+down, scrape stops and instant queries return empty. Always pass `--data-urlencode "time=$TS"`.
+
+Metric units note: `ponder_indexing_function_duration_*` is in **milliseconds**, not seconds.
+The metric name no longer carries the `_seconds` suffix it had in older Ponder versions.
+
+```bash
+TS=$(cat /tmp/perf-test/main-<label>-end-epoch.txt)
+q() {
+  curl -sf http://localhost:9090/api/v1/query \
+    --data-urlencode "query=$1" --data-urlencode "time=$TS"
+}
+
+# What to capture:
+q 'ponder_indexing_completed_events'                                    # cumulative event counts
+q 'ponder_indexing_function_duration_sum / ponder_indexing_function_duration_count'  # avg ms/event
+q 'ponder_indexing_function_duration_sum'                               # total ms wallclock
+q 'ponder_indexing_function_duration_count'                             # invocation count
+q 'histogram_quantile(0.95, sum by (event, le) (rate(ponder_indexing_function_duration_bucket[5m])))'
+q 'sum by (method) (rate(ponder_postgres_query_total[5m]))'             # PG QPS by method
+q 'sum by (chain_id) (rate(ponder_rpc_request_cache_hits[5m]))'         # RPC cache hits/s
+```
+
+Save each to `/tmp/perf-test/main-<label>-<thing>.json`. Wallclock is `end_epoch -
+start_epoch` (whole seconds; computed from the txt files, not from prometheus).
+
+## Step 9 — restore env
+
+Remove `DISABLE_ENSRAINBOW_HEAL` from `.env.local` (or restore from `.env.local.bak-perf-test` if
+you backed it up).
+
+Confirm before declaring done — `git status` must show no diff.
+
+**Do NOT drop the run's schema during cleanup.** The user manages schema lifecycle manually — they may want to inspect the indexed data, run queries against it, or compare it with a parallel run. Leave `ensindexer_perf_<label>` in place; the user will `drop schema … cascade` themselves when they're done with it. This applies to both clean-completion teardown and crash teardown.
+
+## Reporting
+
+GitHub issue **#2079** on `namehash/ensnode` is the _only_ canonical store for perf run reports. Post the report as a comment there via `gh issue comment 2079 -R namehash/ensnode --body-file <draft>`.
+
+**Do NOT** also save the report — or a summary of it, or its numbers — to local Claude memory. Memory may hold at most a one-line pointer to the GH comment URL when the run becomes _the_ canonical baseline that future runs compare against (see the existing baseline memory for the shape). One-off comparison runs for a feature branch get nothing in memory at all.
+
+Comment template:
+
+```
+**<label>** — branch/SHA, plugins, namespace
+- wallclock: Xh Ym (start → end)
+- avg events/sec: …
+- top 5 by wallclock: handler — Y ms total (Z events, A ms/ea, p95 B ms)
+- regressions vs prior baseline: …
+```
+
+Style: concise, lowercase by default, matter-of-fact. No `<details><summary>` tags — put the content directly under each bullet.
+
+Keep raw json snapshots in `/tmp/perf-test/` for ad-hoc re-analysis.
+
+## Common pitfalls
+
+- **`pnpm dev` hot-reload mid-run (indexer)** kills the HTTP server and nukes the run. Use `pnpm start`.
+- **ENSApi must also run via `pnpm start`, not `pnpm dev`.** When you bring ENSApi up to inspect
+  indexed data or to monitor indexing progress (`GET /api/indexing-status`) during a run, `pnpm dev`
+  (`tsx watch --env-file ./.env.local`) hot-reloads on _any_ file edit — so editing `.env.local`
+  mid-run restarts ENSApi, and if the env changed it can come back pointed at a
+  _different_ schema and silently break a schema-gated monitor/kill (e.g. swinging onto a prior
+  completed run whose chains are at tip → premature kill). Gotcha: ENSApi's `start`
+  (`tsx src/index.ts`) does **not** load `.env.local` (no `--env-file`, no in-code dotenv), so source
+  the env and override the schema inline:
+  ```bash
+  cd apps/ensapi
+  set -a; . ./.env.local; set +a
+  ENSINDEXER_SCHEMA_NAME=ensindexer_perf_<label> pnpm start > /tmp/perf-test/ensapi.log 2>&1 &
+  ```
+  Editing files (restoring env) then no longer disturbs the running ENSApi. A brief gap
+  while restarting is safe — a status poll that can't reach ENSApi reads 0 and keeps waiting.
+- **Untouched `.env.local`** — forgetting to switch `NAMESPACE`/`PLUGINS` → wrong run shape.
+  Always `cat .env.local` before launching.
+- **Stale prometheus from a prior run** — failing to `pnpm wipe` mixes histograms across
+  configs. Wipe between every run.
+- **Orphan ponder.js worker after kill** — `pkill -f "ponder --root"` only kills the `pnpm` /
+  shell parent; the underlying `node …/ponder.js …` worker keeps running, holds port 42069,
+  and silently steals prometheus scrapes from the next indexer (which falls back to 42070 and
+  reports `WARN Port in use port=42069` in its log). Between runs, verify with
+  `lsof -i :42069` and `pgrep -af ponder.js`. If the worker survived, `kill -9` its PID.
+- **`ponder_sync_is_realtime` does not exist** in current Ponder. Older transcripts (and the
+  prior version of this skill) used it as the realtime signal — those scripts will hang
+  forever today. Use the log-based signal (`Started live indexing chain=` count) instead.
+  Available sync metrics in 0.16.x are only `ponder_sync_block` and `ponder_sync_block_timestamp`;
+  there is no per-chain realtime flag or per-chain target block to compare against.
+- **Indexer-startup race in `LocalPonderClient.metrics`** — `initIndexingOnchainEvents` calls
+  `getIndexingMetadataContext` early, which reads chain metrics from the in-process Ponder
+  registry. On 6-chain mainnet configs this occasionally races and throws `Local Ponder Client
+is missing the Chains Indexing Metrics for indexed chain IDs: 1, 8453, 59144, 10, 42161, 534352`
+  → `unhandledRejection` → shutdown. There is no retry. If you see this in the first ~15s,
+  drop the schema, wipe prometheus, and relaunch — it is not deterministic and a clean retry
+  generally wins the race.
+- **EPS dropoff near end of backfill is expected** — as chains finish their backfill ranges,
+  the indexer has fewer chains' events to process concurrently, so instantaneous EPS falls.
+  3000 → 800 EPS at 99% backfill is normal. Don't interpret it as a stall unless `Indexed
+block range` log lines stop appearing for minutes.
+- **Metric name drift** — older transcripts use `_seconds_*`. Current Ponder emits ms-scale
+  metrics without the `_seconds` suffix. Verify with `curl :42069/metrics | grep duration` if in doubt.
+- **Renamed step-8 metrics** — `ponder_postgres_query_total` and `ponder_rpc_request_cache_hits`
+  do _not_ exist in current Ponder. Use `ponder_indexing_store_queries_total` and
+  `ponder_indexing_rpc_requests_total` / `ponder_indexing_rpc_prefetch_total` instead.
+  `curl :42069/metrics | grep -E "^ponder_indexing_(store|rpc)"` is the source of truth.
+- **Querying prometheus after indexer stops** without a `time=` parameter returns empty results.
+  Always snapshot at `end-epoch`.
+- **`ensv2-only` is not v2-only** — the ensv2 plugin pulls in chains 1/8453/10/42161/59144/534352
+  to mirror v1 state. Same shape as the canonical multichain configs in terms of chain count.
+- **TOCTOU during snapshot** — wait until the wait script signals all chains live before
+  snapshotting. Mid-realtime numbers are not stable.
diff --git a/.agents/skills/fix-audit/SKILL.md b/.agents/skills/fix-audit/SKILL.md
index 0fd78a47cc..5127f282f2 100644
--- a/.agents/skills/fix-audit/SKILL.md
+++ b/.agents/skills/fix-audit/SKILL.md
@@ -93,7 +93,7 @@ was still doing work; re-check.
 - Genuinely unmet peers that work in practice (e.g. an unmaintained package peering
   on an old major): acknowledge in `pnpm.peerDependencyRules.allowedVersions`, scoped
   as `"parent>peer": "^N"`.
-- Verify suppressions under a *fresh* resolution (warnings only print when resolution
+- Verify suppressions under a _fresh_ resolution (warnings only print when resolution
   runs): back up the lockfile, delete it, `pnpm install --lockfile-only`, read the
   output, restore the lockfile.
 
diff --git a/.changeset/omnigraph-skill-acceleration-and-status.md b/.changeset/omnigraph-skill-acceleration-and-status.md
new file mode 100644
index 0000000000..b75ce1a42a
--- /dev/null
+++ b/.changeset/omnigraph-skill-acceleration-and-status.md
@@ -0,0 +1,5 @@
+---
+"ensskills": patch
+---
+
+The `omnigraph` skill now explains Protocol Acceleration (resolve is accelerated by default, transparent protocol-compliant fallback, the `acceleration { requested attempted }` introspection) and the indexing-status/503 contract (when an instance responds 503 and how to check progress with `enscli ensnode indexing-status`). The `ens-protocol` skill now defines the ENS Namespace concept (a logically-isolated set of names spanning many chains, not 1:1 with an L1 chain).
diff --git a/.gitignore b/.gitignore
index 13ffe429e6..ca8b0776c2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,7 +32,7 @@ generated
 .terraform*
 terraform.tfstate*
 
-# Claude
+# Claude — use .agents for committed skills
 .claude
 
 # ENSRainbow data
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000000..c5280c5f96
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
index 6118ba7072..674747d4a3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,24 +1,50 @@
 # ENSNode
 
-ENSNode is a multichain ENS indexer monorepo. It indexes ENS names across multiple chains (mainnet, Basenames, Lineanames, 3DNS) and exposes them via GraphQL and REST APIs.
+ENSNode is the full-stack ENSv2 development platform: a suite of services and libraries that index the full state of ENS — ENSv1 and ENSv2, across all chains (mainnet, Basenames, Lineanames, 3DNS) — into a unified data model and expose it for integration.
+
+Core narrative (see `docs/ensnode.io` for the canonical versions):
+
+- **ENSDb** — a PostgreSQL database holding the live onchain state of ENS as a single unified data model (the **ENS Unigraph**). An open standard separating Writers (indexers) from Readers (APIs).
+- **ENSIndexer** — the reference ENSDb Writer: a Ponder-based multichain indexer combining ENSv1 Nametrees and the ENSv2 Namegraph into ENSDb.
+- **ENSApi** — serves ENSNode's APIs on top of ENSDb: the **ENS Omnigraph** GraphQL API (unified ENSv1+ENSv2, Relay spec), the legacy ENS Subgraph GraphQL API (deprecated), and REST APIs.
+- **ENSRainbow** — heals unknown labels (labelHash → label) as a sidecar consumed by ENSIndexer.
+- **ENSAdmin** — operator dashboard and ENS Protocol Inspector.
 
 ## Monorepo Structure
 
-- `apps/ensindexer` — Blockchain indexer powered by Ponder
-- `apps/ensapi` — ENS API server (GraphQL and REST, Hono)
+Apps (private, deployed as services):
+
+- `apps/ensindexer` — Multichain ENS indexer, powered by Ponder
+- `apps/ensapi` — ENS API server: Omnigraph + Subgraph GraphQL and REST (Hono)
 - `apps/ensadmin` — Dashboard for navigating indexed ENS state (Next.js)
-- `apps/ensrainbow` — Label healing service: recovers labels from labelHashes (Hono)
-- `apps/fallback-ensapi` — AWS Lambda fallback that proxies ENS Subgraph requests when ENSApi is unhealthy
-- `packages/ensdb-sdk` — SDK for interacting with data in ENSDb
-- `packages/ensnode-sdk` — SDK for interacting with ENSNode
-- `packages/ensrainbow-sdk` — SDK for interacting with ENSRainbow
+- `apps/ensrainbow` — Label healing service (Hono)
+- `apps/fallback-ensapi` — AWS Lambda fallback proxying ENS Subgraph requests when ENSApi is unhealthy
+
+Public packages (published to npm — exports are external API surface; changes need changesets):
+
+- `packages/enssdk` — `enssdk`: foundational ENS development library (typed Omnigraph client via gql.tada, hashing, normalization)
+- `packages/enskit` — `enskit`: ENS toolkit for React (urql-based Omnigraph hooks)
+- `packages/enscli` — `enscli`: agent- and human-friendly CLI for ENS, ENSNode, and the Omnigraph API
+- `packages/ensskills` — `ensskills`: agent skills for ENS, installed into consumer repos via skills-npm
+- `packages/ensnode-sdk` — SDK for interacting with ENSNode (ENSApi wire types, Omnigraph example queries)
+- `packages/ensdb-sdk` — SDK for ENSDb data (owns the indexed schema)
+- `packages/ensrainbow-sdk` — SDK for the ENSRainbow API
 - `packages/datasources` — Catalog of chain datasources (contracts, start blocks, event filters)
-- `packages/ponder-subgraph` — Hono middleware for Subgraph-compatible GraphQL
-- `packages/ponder-sdk` — Utility library for interacting with Ponder apps and data
+- `packages/ponder-sdk` / `packages/ponder-subgraph` — Ponder utilities / Subgraph-compatible GraphQL middleware
 - `packages/ens-referrals` — Utilities for ENS Referrals
 - `packages/namehash-ui` — UI components for NameHash Labs apps
-- `packages/shared-configs` — Shared TypeScript configurations
-- `docs/ensnode.io` — Documentation site (Astro/Starlight)
+
+Private packages: `packages/ensnode-react`, `packages/scalar-react`, `packages/shared-configs`, `packages/ensindexer-perf-testing`, `packages/integration-test-env`.
+
+Docs & examples: `docs/ensnode.io` (Astro/Starlight), `docs/ensrainbow.io`, `examples/*` (consumer examples for enssdk, enskit, ensskills, and raw Omnigraph GraphQL).
+
+Several projects have their own AGENTS.md with subsystem-specific invariants — it loads automatically when you work in that subtree: `apps/ensindexer`, `apps/ensapi`, `apps/ensrainbow`, `apps/ensadmin`, `apps/fallback-ensapi`, `docs/ensnode.io`, `packages/datasources`, `packages/integration-test-env`.
+
+## Agent Skills
+
+- Internal skills (repo workflows) live in `.agents/skills/` (committed). `pnpm install` mirrors them into `.claude/skills/` via `scripts/link-local-skills.mjs`; never create those symlinks by hand. New internal skills go in `.agents/skills/<name>/SKILL.md`.
+- External skills (how to use ENS/ENSNode) live in `packages/ensskills` and are symlinked in as `npm-ensskills-*` by skills-npm (configured in `skills-npm.config.ts`).
+- Placement rule: knowledge useful to external integrators (protocol concepts, Omnigraph usage, API contracts) belongs in `packages/ensskills` or `docs/ensnode.io` — never duplicated into internal AGENTS.md files. Internal AGENTS.md files hold repo-internal invariants only.
 
 ## Tech Stack
 
@@ -28,24 +54,29 @@ ENSNode is a multichain ENS indexer monorepo. It indexes ENS names across multip
 - **Indexer framework:** Ponder
 - **Validation:** Zod
 - **ORM:** Drizzle
-- **Linting/formatting:** Biome
+- **Linting/formatting:** Biome (TS/JSON), Prettier (md/mdx/astro)
 - **Testing:** Vitest
 - **Build:** tsup, tsx
 
 ## Commands
 
-Runnable commands for validating changes; lint and format with Biome.
-
 - Install dependencies: `pnpm install`
 - Run all tests: `pnpm test`
-  - Run tests for a single project: `pnpm test --project <project>` (e.g. `pnpm test --project ensapi`)
-  - Run tests for a single file: `pnpm test <path>`
+  - Single project: `pnpm test --project <project>` (e.g. `pnpm test --project ensapi`)
+  - Single file: `pnpm test <path>`
 - Lint and format: `pnpm lint` (fixes where applicable); CI lint: `pnpm lint:ci`
-- Type checking: `pnpm typecheck` (runs typecheck in all workspaces)
+- Type checking: `pnpm typecheck` (all workspaces)
   - Always use `pnpm -F <package-name> typecheck`, never call `tsc` or `tsgo` directly
-- Omnigraph examples (docs) are a two-step pipeline. The docs do NOT read SDK example queries directly — they render a vendored snapshot in `docs/ensnode.io/src/data/omnigraph-examples/` (`examples.json` + `schema.graphql` + `snapshot.json`):
-  1. `pnpm -F @docs/ensnode omnigraph:snapshot <version>` (e.g. `v1.15.2`) — vendors the workspace SDK's example queries and schema into the snapshot. Required after changing SDK Omnigraph example queries/variables in `packages/ensnode-sdk`; skipping it means step 2 POSTs the stale vendored queries.
-  2. `pnpm -F @docs/ensnode omnigraph-examples:refresh-responses [<id>,<id>]` (requires network) — POSTs the vendored queries to the hosted instances and updates `responses.json`. Scope to specific example IDs to leave the rest untouched.
+- Codegen: `pnpm generate` (always from the monorepo root, never scoped to a package) — regenerates OpenAPI defs, the Omnigraph GraphQL schema, and ensskills autogen regions
+
+## Local Runtime
+
+Default ports: ENSIndexer `42069`, ENSApi `4334`, ENSAdmin `4173`, ENSRainbow `3223`, Postgres `5432`.
+
+- Each app reads `.env.local` (copy from its `.env.local.example`). Dev startup order: Postgres → `pnpm -F ensrainbow serve` → `pnpm -F ensindexer dev` → `pnpm -F ensapi dev` → `pnpm -F ensadmin dev`.
+- Cross-app invariant: ENSIndexer and ENSApi must agree on `ENSDB_URL` and `ENSINDEXER_SCHEMA_NAME` — ENSApi reads the schema ENSIndexer writes. Each running ENSIndexer needs an exclusive schema name.
+- Full stack via Docker: `docker compose -f docker/docker-compose.devnet.yml up -d` (zero-config local devnet) or `docker/docker-compose.yml` with `.env.docker.local` (mainnet/sepolia).
+- Integration tests: orchestrated by `packages/integration-test-env` (`pnpm test:integration:ci` from root).
 
 ## Testing
 
@@ -62,6 +93,7 @@ Runnable commands for validating changes; lint and format with Biome.
 - Do not duplicate definitions across multiple locations. Duplication creates a significant maintenance burden.
 - Ensure documentation resides at the correct place and the correct layer of responsibility.
 - Use type aliases to document invariants. Each invariant MUST be documented exactly once, on its type alias.
+- Terminology is exacting in this codebase (Label vs Name, Literal vs Interpreted vs Beautified, Encoded LabelHash, Subregistry, …). The canonical glossary is `docs/ensnode.io/src/content/docs/docs/reference/terminology.mdx` — consult it before naming things; link to it rather than redefining terms.
 
 ## Code Comments
 
@@ -72,25 +104,18 @@ Runnable commands for validating changes; lint and format with Biome.
 
 Fail fast and loudly on invalid inputs.
 
-- **Validation — API requests:** Use the existing Hono validation middleware (Zod schemas + `validate()` from `apps/ensapi/src/lib/handlers/validate.ts`). Failed validation becomes a 400 response with structured details via `errorResponse`; handlers receive already-validated data. Do not manually call `zod.parse`/`safeParse` in route handlers for request body/params/query when this middleware is in use.
-- **Validation — non-API code (config, SDK, scripts):** Use `zod.parse(...)` when invalid input should throw immediately; use `zod.safeParse(...)` when you need a non-throwing branch (e.g. optional or fallback). Prefer `parse` for fail-fast.
+- **Non-API code (config, SDK, scripts):** Use `zod.parse(...)` when invalid input should throw immediately; use `zod.safeParse(...)` when you need a non-throwing branch (e.g. optional or fallback). Prefer `parse` for fail-fast.
 - **Error types:** Use plain `Error` (or `ZodError` when propagating Zod validation errors). The codebase does not define a custom hierarchy (e.g. `AppError`/`ValidationError`); do not introduce one unless the project adopts it. Use `throw new Error("message")` from application code.
-- **API boundaries:** Use the shared `errorResponse` helper (`apps/ensapi/src/lib/handlers/error-response.ts`) for all error responses in ENSApi (and equivalent pattern in other Hono apps). Mapping: validation (ZodError / Standard Schema) → 400 with `{ message, details }`; other known client errors → 4xx with `{ message }`; server errors → 500 with `{ message }`. Response shape: `{ message: string, details?: unknown }` (see `packages/ensnode-sdk/src/ensapi/api/shared/errors/response.ts`). A `code` field may be adopted later for machine-readable codes; do not add it inconsistently today.
-- **Examples:** Validation at boundary: route uses `validate("json", MySchema)`; on failure → 400 + `{ message: "Invalid Input", details }`. Non-API: `const config = ConfigSchema.parse(env)` or `const parsed = MySchema.safeParse(input); if (!parsed.success) return fallback;`. Handler: `return errorResponse(c, err)` or `return errorResponse(c, "Not found", 404)`.
-
-## Ponder
-
-- Schema changes never require a migration step. Ponder only runs fully-compatible indexes against existing schemas; otherwise the index is dropped and rebuilt from scratch. Do not propose, plan, or write migration code for the ensindexer drizzle schema.
-- Schema or handler changes always require a re-index. This is implicit — never qualify plans with "requires reindex" or similar.
-- Access entities by primary key only. Ponder's cache layer keys on PK; filters or complex selects force a flush to Postgres and are extremely unperformant in the hot path. If you need a non-PK lookup at index time, design the schema so the lookup key is the primary key.
-- TOCTOU is never a concern inside Ponder event handlers. Ponder serializes events per chain and runs each handler in a transaction, so a read-modify-write against the same row from two handlers cannot interleave. Bot reviewers will sometimes flag this — dismiss those comments. (Note: TOCTOU IS a concern in ENSApi when reading `ensIndexerSchema` — both parallel and serial reads can see different snapshots of the indexer's writes.)
+- API request validation and error responses are ENSApi conventions — see `apps/ensapi/AGENTS.md`.
 
 ## Workflow
 
 - Add a changeset when your PR includes a logical change that should bump versions or be communicated in release notes: https://ensnode.io/docs/contributing/prs#changesets
+  - ENSNode uses non-standard semver: breaking changes are `minor`, not `major`.
 - Before declaring work complete, run validation in the affected project(s):
   1. If OpenAPI Defs or the Omnigraph GraphQL Schema was affected, run `pnpm generate`
      - always run `pnpm generate` from the monorepo root, do NOT scope to a specific package
+     - the OpenAPI doc is a committed artifact (`docs/ensnode.io/src/data/ensapi-openapi.json`) and CI fails if it drifts from the ENSApi routes
   2. `pnpm -F <affected-project> typecheck`
      - at the end of a work session, always run `pnpm typecheck` from the monorepo root
   3. `pnpm lint`
diff --git a/apps/ensadmin/AGENTS.md b/apps/ensadmin/AGENTS.md
new file mode 100644
index 0000000000..735857ba6f
--- /dev/null
+++ b/apps/ensadmin/AGENTS.md
@@ -0,0 +1,32 @@
+# ENSAdmin
+
+Next.js dashboard for inspecting ENS state from a connected ENSNode instance. Client-only.
+
+## Static export — no server runtime
+
+- `next.config.ts` sets `output: "export"`. There is NO server at runtime: no route handlers, no server components doing fetches, no server actions. `app/api/*/page.tsx` are client pages (GraphiQL / REST explorer UIs), not API routes. The lone `app/api/_ai/route.ts` is fully commented-out dead code.
+- Build emits to `out/`; `pnpm start` serves it statically (`serve out`). Docker serves `out/` via nginx.
+- Dev and prod both bind port **4173** (`next dev -p 4173`, `serve -l 4173`). `ENSADMIN_PUBLIC_URL` overrides the self-URL used for OG/metadata (`lib/env.ts` `ensAdminPublicUrl`); auto-detected on Vercel.
+
+## Runtime env injection (the static-export gotcha)
+
+- `NEXT_PUBLIC_*` is baked at build time, so it can't configure a prebuilt image. ENSAdmin works around this: `layout.tsx` loads `/runtime-config.js` (`strategy="beforeInteractive"`) which sets `window.__ENSADMIN_RUNTIME_ENVIRONMENT_VARIABLES`. `docker-entrypoint.sh` regenerates that file from container env at startup.
+- `getRuntimeEnvVariable()` reads the window object first, falling back to `process.env`. Only `NEXT_PUBLIC_SERVER_CONNECTION_LIBRARY` flows through this path today. Any new container-configurable var must be wired through BOTH `docker-entrypoint.sh` and `getRuntimeEnvVariable`.
+
+## Connection model
+
+- ENSAdmin talks to one selected ENSNode instance at a time. The connection library = server defaults (`NEXT_PUBLIC_SERVER_CONNECTION_LIBRARY`, comma-separated) + user custom URLs persisted in localStorage (`ensadmin:custom-connections:urls`).
+- Selected connection lives in the `?connection=<url>` URL param. When building internal links, preserve it via `retainCurrentRawConnectionUrlParam(basePath)` (`use-connection-url-param.tsx`) — basePath must have no existing query/hash.
+- `useSelectedConnection()` / `useValidatedSelectedConnection()` THROW if no valid connection is selected; only call them under `<RequireSelectedConnection>` (or `RequireActiveConnection`). `SelectedEnsNodeProvider` bridges the selected URL into namehash-ui's `EnsNodeProvider`.
+
+## Data fetching & display via @namehash/namehash-ui
+
+- ENS reads do NOT happen in this app directly. They go through hooks re-exported from `@namehash/namehash-ui` (workspace pkg): `usePrimaryName`, `usePrimaryNames`, `useRecords`, `useRegistrarActions`. These read from the selected ENSNode via the `EnsNodeProvider` context. react-query (`@tanstack/react-query`) is the cache layer.
+- ALWAYS render ENS names with `<NameDisplay name={...} />` (or `EnsAvatar`, `AddressDisplay`, `ChainIcon`, `ChainName`, `RelativeTime`/`AbsoluteTime`) from namehash-ui — never raw name strings. `NameDisplay` beautifies via enssdk's `beautifyName`. Names are typed `Name` from `enssdk`; addresses `Address`. (`lib/beautify-url.ts` is for HTTP URLs, unrelated to ENS name display.)
+- Namespace-varying constants (example names/addresses, chain lists) must go through `getNamespaceSpecificValue(namespace, ...)` from `@ensnode/ensnode-sdk`, keyed off `useActiveEnsNodeStackInfo().ensIndexer.namespace`.
+
+## Conventions
+
+- App Router parallel routes: every top-level section has matching `@breadcrumbs/<section>` and `@actions/<section>` slots wired in `layout.tsx`. Adding/moving a route means updating those slots too.
+- `app/mock/*` is a component-preview gallery (Storybook-style), not real features. Use it to exercise namehash-ui components against mock data.
+- Styling: Tailwind v4 + shadcn-style primitives in `components/ui/` (Radix-based). Match existing component patterns.
diff --git a/apps/ensadmin/CLAUDE.md b/apps/ensadmin/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/apps/ensadmin/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/apps/ensapi/AGENTS.md b/apps/ensapi/AGENTS.md
new file mode 100644
index 0000000000..e55bc69ef8
--- /dev/null
+++ b/apps/ensapi/AGENTS.md
@@ -0,0 +1,48 @@
+# ENSApi
+
+Read-only Hono API in front of ENSDb (the indexer's Postgres). Three public surfaces, mounted in `src/app.ts`:
+
+- Omnigraph GraphQL (`/api/omnigraph`) — Pothos+Yoga schema in `src/omnigraph-api/`.
+- Legacy Subgraph GraphQL (`/subgraph`) — `@ensnode/ponder-subgraph` middleware.
+- REST (`/api/*`) — `@hono/zod-openapi` routes in `src/handlers/api/`.
+
+Default port: `ENSApi_DEFAULT_PORT = 4334` (`src/config/defaults.ts`).
+
+## Cross-service contracts
+
+- ENSApi reads the indexer's DB directly. `ENSDB_URL` + `ENSINDEXER_SCHEMA_NAME` (env) MUST match the running ENSIndexer's DB and schema name, else queries hit a stale/empty schema. Resolved into `EnsDbReader` via the DI container.
+- Request/response types and most domain enums/helpers live in `@ensnode/ensnode-sdk`, NOT in this app. Error response shape is `ErrorResponse` from `packages/ensnode-sdk/src/ensapi/api/shared/errors/response.ts`. Add/change wire types there.
+- `EnsNodeStackInfo` and indexing status come from the connected ENSIndexer (fetched at startup + cached); feature availability (`hasOmnigraphApiConfigSupport`, `hasSubgraphApiConfigSupport`, `canFallbackToTheGraph`, etc.) is gated on those sdk helpers, not local config.
+
+## DI container (`src/di.ts`)
+
+- Single frozen, lazily-built `di` singleton. `di.init()` runs at startup (verifies ENSDb + root-chain RPC connectivity, warms caches); HTTP server starts immediately, init is non-blocking — early requests may see uninitialized caches.
+- Access DB as `di.context.ensDb` / `di.context.ensIndexerSchema`. Do NOT import the schema elsewhere.
+- `di.context.stackInfo` is a SYNC getter that throws if the stackInfo cache hasn't loaded — only valid after init.
+
+## Middleware pipeline (`src/lib/hono-factory.ts`)
+
+- Use `createApp({ middlewares: [...] })`, not bare `app.use()`. Middlewares tagged with `producing([...keys])` make their `c.var.<key>` non-optional in handlers AND assert presence at runtime. Order matters — dependents declare their producer (e.g. `canAccelerate` requires `isRealtime` requires `indexingStatus`).
+- All `c.var.*` middleware variable types union into `MiddlewareVariables`; add new ones there.
+
+## Realtime / acceleration / fallback (gotchas)
+
+- `indexingStatusMiddleware` reads an SWR cache that retains the last good snapshot even when ENSIndexer is unreachable; on total failure `c.var.indexingStatus` is an `Error` (surfaces 503 on Omnigraph/Subgraph). Always handle the Error branch.
+- `isRealtime` = `worstCaseDistance <= maxWorstCaseDistance`. The threshold differs per surface (Resolution 60s, Omnigraph 600s, Subgraph 600s/10min) — don't assume one global value.
+- `canAccelerate` (Resolution + Omnigraph) requires the ENSIndexer to have the `ProtocolAcceleration` plugin AND be realtime. Acceleration is currently force-disabled for any ENSv2 namespace (datasource `ENSv2Root` present) — a temporary bailout, not a permanent rule.
+- Subgraph API proxies to The Graph (`thegraphFallbackMiddleware`) only when `canFallbackToTheGraph` AND not realtime; falls through to internal handling if the proxy throws. Never falls back when the indexer is not Subgraph-compatible (would corrupt results).
+
+## Error handling
+
+Fail fast and loudly on invalid inputs.
+
+- REST validation is the `@hono/zod-openapi` route `request` schemas; `createApp`'s `defaultHook` routes failures through `errorResponse`. Do NOT call `zod.parse`/`safeParse` on request body/params/query in handlers.
+- Use plain `Error` (or propagate `ZodError`). No custom error hierarchy (`AppError`/`ValidationError`) — don't introduce one.
+- All error responses go through `errorResponse` (`src/lib/handlers/error-response.ts`): ZodError / Standard Schema → 400 `{ message, details }`; other client errors → 4xx `{ message }`; server errors → 500 `{ message }`. A `code` field may be adopted later; do not add it inconsistently today.
+- TOCTOU IS a concern here: reading `ensIndexerSchema` in parallel OR serially can observe different snapshots of the indexer's in-flight writes. Don't assume cross-query consistency.
+
+## Generate
+
+- `pnpm generate` (root) runs `generate:gqlschema` here, which writes the Omnigraph SDL to `packages/enssdk/src/omnigraph/generated/schema.graphql` (the SDK is the source of truth, not this app). Re-run after any change to the Pothos schema in `src/omnigraph-api/`.
+- The OpenAPI document is generated from the live routes (`/openapi.json`, `src/openapi-document.ts`); the docs site fetches it. `HIDE_OPENAPI_ENDPOINTS` hides deprecated/legacy routes from the published doc.
+- Dev-only GraphQL methods are gated by `INCLUDE_DEV_METHODS`; SDL is NOT written when they're enabled (avoids a dirty schema diff).
diff --git a/apps/ensapi/CLAUDE.md b/apps/ensapi/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/apps/ensapi/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/apps/ensindexer/AGENTS.md b/apps/ensindexer/AGENTS.md
new file mode 100644
index 0000000000..e5f04d2f4a
--- /dev/null
+++ b/apps/ensindexer/AGENTS.md
@@ -0,0 +1,57 @@
+# ENSIndexer
+
+Ponder app indexing ENS across chains. ENS-protocol concepts (names, labels/labelhash, normalization, resolution, the registry/registrar/resolver model) live in the ensskills `ens-protocol` skill and the docs — read those, don't re-derive here.
+
+## Ponder
+
+- Schema changes never require a migration step. Ponder only runs fully-compatible indexes against existing schemas; otherwise the index is dropped and rebuilt from scratch. Do not propose, plan, or write migration code for the ensindexer drizzle schema.
+- Schema or handler changes always require a re-index. This is implicit — never qualify plans with "requires reindex" or similar.
+- Access entities by primary key only. Ponder's cache layer keys on PK; filters or complex selects force a flush to Postgres and are extremely unperformant in the hot path. If you need a non-PK lookup at index time, design the schema so the lookup key is the primary key.
+- TOCTOU is never a concern inside Ponder event handlers. Ponder serializes events per chain and runs each handler in a transaction, so a read-modify-write against the same row from two handlers cannot interleave. Bot reviewers will sometimes flag this — dismiss those comments.
+- Ordering is forced to `omnichain` (see `src/ponder/config.ts`); `multichain` is not supported.
+
+## Custom Ponder root
+
+- Ponder's root is `./ponder`, not `./src`. App source lives in `src/` (imported via `@/*`); `ponder/` holds only what Ponder bundles: `ponder.config.ts` (re-exports `src/ponder/config.ts`), `ponder.schema.ts` (re-exports `@ensnode/ensdb-sdk/ensindexer-abstract`), and `ponder/src/register-handlers.ts` + `ponder/src/api/`. This keeps colocated `*.test.ts` out of Ponder's handler bundle.
+- The drizzle schema is owned by `@ensnode/ensdb-sdk` (the "abstract" ENSIndexer Schema), not defined locally. Edit schema there.
+
+## Plugin architecture
+
+- A plugin (`src/plugins/*/plugin.ts` via `createPlugin`) declares `requiredDatasourceNames` + `allDatasourceNames` and a lazy `createPonderConfig`. Datasources (chains/contracts/start blocks/ABIs) come from `@ensnode/datasources`, keyed by `NAMESPACE`.
+- `NAMESPACE` (mainnet/sepolia/ens-test-env) + `PLUGINS` (comma-list) are the two knobs. A plugin can only activate if its required datasources exist in the namespace (`src/config/validations.ts`). `src/ponder/config.ts` merges active plugins' Ponder configs into one.
+- Contract names are namespaced per-plugin via `namespaceContract` → `"<plugin>/<Contract>"`, because plugins reuse contract names (e.g. `subgraph/Registry` vs `basenames/Registry`). This prefix becomes the Ponder handler name (`subgraph/Registry:NewResolver`).
+- Two registration sites must stay in sync when adding a plugin: `ALL_PLUGINS` in `src/plugins/index.ts` (config merge) and the conditional `attach_*Handlers()` calls in `ponder/src/register-handlers.ts` (handler registration).
+
+## Same-log handler ordering (footgun)
+
+- `attach_*()` call order does NOT control dispatch order. Ponder orders by checkpoint (chainId, blockNumber, txIndex, logIndex). Two handlers on the **same log** (e.g. Unigraph + ProtocolAcceleration both on `ENSv1Registry:NewResolver`) get identical checkpoints and Ponder's tie-break is non-deterministic — never rely on ordering between same-log handlers. Cross-log ordering IS deterministic (e.g. NodeMigration writes `nodeIsMigrated` on the new Registry's log; Old-registry guards read it on a different log).
+- See the long comment in `register-handlers.ts` before touching ProtocolAcceleration/Unigraph/NodeMigration registration.
+
+## ENSRainbow on the hot path
+
+- `labelByLabelHash` (`src/lib/graphnode-helpers.ts`) calls ENSRainbow for label healing on _every_ event needing it. Must be a colocated/local `ENSRAINBOW_URL`; the public server makes indexing extremely slow. Transient failures (network, 500) retry with backoff; any unrecovered throw propagates and crashes the process (intentional — forces re-index from checkpoint). `ENSRainbow` readiness/health is awaited before any onchain handler runs (`src/lib/indexing-engines/init-indexing-onchain-events.ts`).
+- `LABEL_SET_ID`/`LABEL_SET_VERSION` are pinned and part of indexing behavior — changing them changes results.
+- `DISABLE_ENSRAINBOW_HEAL=true` (undocumented env) makes `labelByLabelHash` early-return `null` — every label is treated as unhealable. For benchmarking only (see the `ensindexer-perf-testing` skill); it changes indexing output, never set it in production.
+
+## Indexing-behavior build ID
+
+- `src/ponder/indexing-behavior-injection-contract.ts` injects a fake contract whose `indexingBehaviorDependencies` (namespace, sorted plugins, blockrange, `isSubgraphCompatible`, `clientLabelSet`, ENSDb schema checksum) feed Ponder's Build ID. Any config that changes indexing output MUST be added here, or Ponder will wrongly resume an incompatible schema. Plugins are sorted so order-only differences don't fork the Build ID.
+
+## SUBGRAPH_COMPAT
+
+- Toggles how Literal Labels/Names are interpreted (Subgraph-Interpreted vs Interpreted) and changes default `PLUGINS`/label-set. When true the config must be Subgraph-Compatible or an invariant throws. Affects indexing output; see `.env.local.example` for the full semantics.
+
+## Cross-service contract
+
+- ENSIndexer is the _exclusive writer_ to its ENSDb schema, named by `ENSINDEXER_SCHEMA_NAME`. ENSApi reads the **same** schema name (`ensapi`'s `ENSINDEXER_SCHEMA_NAME` must match) — this is the integration point between the two services. Multiple indexers can share an ENSDb only with distinct schema names.
+- Beyond the Ponder-managed entity tables, ENSIndexer runs `EnsDbWriterWorker` (`src/lib/ensdb-writer-worker/`) which periodically upserts the IndexingMetadataContext record (indexing status / stack info) that ENSApi reads for its status/probe endpoints.
+
+## Env / dev
+
+- Copy `.env.local.example` → `.env.local`. Required: `ENSDB_URL`, `ENSINDEXER_SCHEMA_NAME`, `ENSRAINBOW_URL`, `NAMESPACE`, `PLUGINS`, `LABEL_SET_ID`/`LABEL_SET_VERSION`, and an `RPC_URL_<chainId>` (or provider key) for every chain the active plugins index.
+- `pnpm dev` forces `ENSINDEXER_SCHEMA_NAME=ensindexer_temp_dev` + `--disable-ui` and recreates the schema on every behavior change. `pnpm start` uses your real `$ENSINDEXER_SCHEMA_NAME` and refuses to reuse a schema built with different indexing behavior.
+
+## Deep procedures (skills, don't duplicate)
+
+- Perf testing this app: `ensindexer-perf-testing` skill.
+- Inspecting/editing Ponder's RPC sync cache (`ponder_sync` schema): `edit-ponder-sync` skill.
diff --git a/apps/ensindexer/CLAUDE.md b/apps/ensindexer/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/apps/ensindexer/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/apps/ensindexer/src/lib/graphnode-helpers.ts b/apps/ensindexer/src/lib/graphnode-helpers.ts
index f0433a5a2c..0118c5c7f7 100644
--- a/apps/ensindexer/src/lib/graphnode-helpers.ts
+++ b/apps/ensindexer/src/lib/graphnode-helpers.ts
@@ -39,6 +39,10 @@ import { logger } from "@/lib/logger";
  *   are exhausted.
  */
 export async function labelByLabelHash(labelHash: LabelHash): Promise<LiteralLabel | null> {
+  // escape hatch for benchmarking to skip healing entirely (every label is treated as unhealable)
+  // never set in production, use for performance testing only
+  if (process.env.DISABLE_ENSRAINBOW_HEAL === "true") return null;
+
   // Reset at the start of each attempt so that after p-retry exhaustion we can distinguish
   // "last failure was HealServerError" (set) from "last failure was a network throw" (undefined).
   let lastServerError: EnsRainbow.HealServerError | undefined;
diff --git a/apps/ensrainbow/AGENTS.md b/apps/ensrainbow/AGENTS.md
new file mode 100644
index 0000000000..3f879e5d49
--- /dev/null
+++ b/apps/ensrainbow/AGENTS.md
@@ -0,0 +1,42 @@
+# ENSRainbow
+
+Label-healing service: maps a 32-byte labelHash → its original label over a LevelDB (classic-level) database. See `packages/ensskills/skills/` for the ENS-protocol concepts (labelhash, label healing, encoded labelhash).
+
+## Entry point: CLI only
+
+- No `dev` script. Everything routes through `src/cli.ts` (yargs). Subcommands: `serve`, `entrypoint`, `ingest-ensrainbow`, `validate[ --lite]`, `purge`, `convert` (CSV→.ensrainbow), `convert-sql` (legacy SQL dump→.ensrainbow). Run via `pnpm <script>` (see package.json scripts).
+- The commented-out `ingest` command (SQL dump → LevelDB) in `cli.ts` is dead — leave it.
+- `serve` opens an already-populated `data-dir` and serves. `entrypoint` (the Docker `ENTRYPOINT`) binds HTTP _immediately_ then downloads+extracts+validates the DB in a background task — `/health` and `/ready` answer during bootstrap; DB-backed routes (`/v1/heal`, `/v1/labels/count`, `/v1/config`) return 503 until attached.
+
+## DB layout & data dirs (gitignored)
+
+- `data-dir` is a _parent_ dir; the actual LevelDB lives in `data-dir/data-<labelSetId>_<labelSetVersion>/` (e.g. `data-subgraph_0/`). `entrypoint` writes a `ensrainbow_db_ready` marker file alongside it; on restart, marker + subdir present ⇒ reuse without re-download.
+- `data/`, `data-*`, `test-data/` are gitignored — any such dirs present locally are artifacts, never source.
+- Prebuilt DBs come from a Labelset Server (`ENSRAINBOW_LABELSET_SERVER_URL`, default `https://bucket.ensrainbow.io`) as `databases/<schema>/<id>_<version>.tgz`, fetched by `scripts/download-prebuilt-database.sh`. `download-rainbow-tables.sh` (root) is the _legacy_ raw-table fetcher — different path/format.
+- `.ensrainbow` is a versioned protobuf format (`src/utils/protobuf-schema.ts`) carrying rainbow records + `label_set_id`/`label_set_version` metadata; files are named `<labelSetId>_<labelSetVersion>.ensrainbow` and served by the Labelset Server under `labelsets/<basename>` (with `.sha256sum` + `.LICENSE.txt` siblings; see `scripts/download-ensrainbow-files.sh`). `ingest-ensrainbow` ingests them into LevelDB; `convert`/`convert-sql` produce them.
+
+## Invariants & gotchas
+
+- `DB_SCHEMA_VERSION` is hardcoded in `src/lib/database.ts` (currently 3). It is duplicated as the env/config default; `invariant_dbSchemaVersionMatch` rejects any env value ≠ the code constant. Bumping the schema means bumping this constant — `validate`/`open` refuse a DB whose stored schema version differs (forces purge + re-ingest).
+- DB keys: 32 bytes ⇒ rainbow record (the labelHash); any other length ⇒ system/metadata key (count, ingestion status, schema version, highest label-set version, label-set id). Never use a 32-byte system key. Values are UTF-8 labels stored verbatim (may be non-normalized, contain dots/null bytes, or be empty).
+- Records are _versioned_: each stores a `labelSetVersion`. A heal is simulated as not-found when the record's version exceeds the client's requested `label_set_version` (`needToSimulateAsUnhealable`) — so a single DB can serve clients pinned to older label-set versions. `convert` against an `--existing-db-path` auto-increments to the next version and skips already-present labels.
+- `entrypoint` re-validates the env/CLI `LABEL_SET_ID`/`LABEL_SET_VERSION` against the _attached DB's_ label set after bootstrap; mismatch ⇒ refuse to serve and `process.exit(1)` (won't serve a misconfigured DB).
+- Heal double-checks every result by recomputing the labelHash from the stored label and returns not-found on mismatch (guards against corrupt records, issue #2188).
+- `validate --lite` (also run on every `open`/`attachDb`) only checks metadata; full `validate` iterates every record verifying hash↔label and the precalculated count. The count is precalculated/stored, never computed at serve time.
+
+## Port
+
+- Default `3223`. Precedence: `--port` flag > `PORT` env > default. Validated by `PortNumberSchema`.
+
+## Heal API contract
+
+- `GET /v1/heal/:labelHash` accepts optional `label_set_id` + `label_set_version` query params (`src/lib/api.ts`). A mismatched `label_set_id` is an error; a pinned `label_set_version` makes healing deterministic — records with a newer version are simulated as not-found (see versioned records above). Clients (the ensrainbow-sdk, ENSIndexer) pin both for reproducible indexing.
+
+## Cross-service contract (ENSIndexer)
+
+- ENSIndexer calls `heal` on the hot path for every label-bearing event via `@ensnode/ensrainbow-sdk` (`apps/ensindexer/src/lib/graphnode-helpers.ts`); a non-retryable heal error or exhausted retries _crashes the indexer and forces a re-index_. ENSIndexer blocks startup on `/health` then `/ready` (`waitForEnsRainbowToBeReady` retries 503 for ~1h to cover cold-start bootstrap; non-503 aborts fast). Run ENSRainbow on the same network as ENSIndexer in production.
+
+## Testing
+
+- Tests open real classic-level DBs in tmp dirs (`mkdtemp`) — no shared fixture DB required; `test/fixtures/` holds small input files. `*.integration.test.ts` is excluded by `vitest.config.ts` (needs network/real labelset server).
+- `cli.ts` `.fail()` rethrows under `VITEST` so `cli.parse` throws (instead of printing help) for assertions.
diff --git a/apps/ensrainbow/CLAUDE.md b/apps/ensrainbow/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/apps/ensrainbow/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/apps/fallback-ensapi/AGENTS.md b/apps/fallback-ensapi/AGENTS.md
new file mode 100644
index 0000000000..bd6ea33ddc
--- /dev/null
+++ b/apps/fallback-ensapi/AGENTS.md
@@ -0,0 +1,31 @@
+# fallback-ensapi
+
+AWS Lambda that proxies Subgraph requests to The Graph when a NameHash-hosted ENSApi is unhealthy. NameHash-infra-specific; logic does NOT generalize to third-party deployments.
+
+## Two distinct fallbacks — do not conflate
+
+- This Lambda = **infra-level** fallback. It only runs once an external health-check/load-balancer has already decided an ENSApi is down and rerouted traffic here. It cannot see indexer realtime status.
+- `thegraphFallbackMiddleware` (apps/ensapi) = **in-app** fallback. Runs inside a healthy ENSApi, proxies to The Graph per-request only when the indexer is not realtime, and falls through to internal Subgraph handling if the proxy throws.
+- Both share the same `canFallbackToTheGraph` SDK helper (`@ensnode/ensnode-sdk/internal`, source `packages/ensnode-sdk/src/shared/thegraph.ts`) → same fallback rules, same `gateway.thegraph.com` target URLs. Keep them in sync via that helper; don't fork the logic.
+
+## Routing / activation (out of this repo)
+
+- The health monitoring + DNS/load-balancer reroute that sends traffic to this Lambda lives in NameHash's private infra, NOT in `terraform/` here. Don't go looking for it in this repo.
+- This app's only job: given a rerouted request, decide if it can satisfy it and proxy or 503.
+
+## Request handling invariants
+
+- Only `/subgraph` is served. `/health` and `/` (welcome page titled "Fallback ENSApi") aside, everything else → 503.
+- Target deployment is identified by parsing the `Host` header (`api.<configTemplateId>.…`, see `parse-host-header.ts`), NOT a path/body param. New hosted deployments must match that regex.
+- `canFallback` is false (→ 503) for non-Subgraph-compatible (alpha/superset) deployments and namespaces The Graph doesn't host (SepoliaV2, ens-test-env). 503 here is correct behavior, not an error — proxying would corrupt results.
+
+## Auth / secrets
+
+- `/subgraph` requires header `x-origin-secret` == `CLOUDFLARE_SECRET` (despite the "cloudfront/cloudflare" naming). In production the app **throws at boot** if `CLOUDFLARE_SECRET` is unset; in dev the check is a no-op.
+- The Graph API key: dev reads `THEGRAPH_API_KEY` from `.env.local`; prod fetches from AWS Secrets Manager by `THEGRAPH_API_KEY_SECRET_ID` (secret stored as a JSON object keyed by `THEGRAPH_API_KEY`). Fetched once at module load — throws if missing.
+- `NODE_ENV === "production"` is the dev/prod switch for both secret sourcing and whether the local `@hono/node-server` runs. esbuild hard-defines it to `"production"` at build, tree-shaking the node-server path out of the Lambda bundle.
+
+## Build / deploy
+
+- `pnpm build` → esbuild bundles `src/index.ts` to `dist/index.mjs`, then zips to `dist/lambda.zip` (+ `dist/meta.json` for bundle analysis). `@aws-sdk/*` is marked external (provided by the Lambda runtime).
+- CI (`release*.yml` via `.github/actions/build_and_publish_lambda`) uploads `lambda.zip` as a GitHub Actions artifact. Actual Lambda deploy is done out-of-repo from that artifact.
diff --git a/apps/fallback-ensapi/CLAUDE.md b/apps/fallback-ensapi/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/apps/fallback-ensapi/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/context7.json b/context7.json
index 4b9dcffb1e..fe465654df 100644
--- a/context7.json
+++ b/context7.json
@@ -1,4 +1,14 @@
 {
+  "$schema": "https://context7.com/schema/context7.json",
   "url": "https://context7.com/namehash/ensnode",
-  "public_key": "pk_GJi29HM76TFnpBRbdYfOo"
+  "public_key": "pk_GJi29HM76TFnpBRbdYfOo",
+  "projectTitle": "ENSNode",
+  "description": "The full-stack ENSv2 development platform: multichain ENS indexing into ENSDb with the ENS Omnigraph GraphQL API, ENS Unigraph SQL, REST APIs, and ENSRainbow label healing.",
+  "folders": ["docs/ensnode.io/src/content/docs"],
+  "excludeFiles": ["CHANGELOG.md"],
+  "rules": [
+    "Prefer the ENS Omnigraph GraphQL API for reading ENS data over the deprecated ENS Subgraph API.",
+    "Use enssdk (TypeScript) or enskit (React) for typed ENS Omnigraph access.",
+    "AI agents working with ENS should install the ensskills npm package for curated agent skills."
+  ]
 }
diff --git a/docs/ensnode.io/AGENTS.md b/docs/ensnode.io/AGENTS.md
new file mode 100644
index 0000000000..91c0e52d5d
--- /dev/null
+++ b/docs/ensnode.io/AGENTS.md
@@ -0,0 +1,42 @@
+# ensnode.io Docs
+
+Astro/Starlight docs site (`@docs/ensnode`). Dev server: `pnpm dev` (http://localhost:4321). Build: `pnpm build` (no separate `astro check` step).
+
+## Content & sidebar
+
+- Docs content lives under `src/content/docs/docs/...` (note the doubled `docs/docs` — the Starlight root is `src/content/docs/`, and every page is namespaced under a `/docs` URL prefix).
+- The sidebar is NOT inferred from the file tree. It is hand-authored in `config/integrations/starlight/sidebar-topics/`. Adding a page does nothing until you also add a sidebar entry.
+- Sidebar entries reference pages by URL `link`, not by file path — a typo'd link silently 404s rather than failing the build.
+- `terminology.mdx` (`src/content/docs/docs/reference/terminology.mdx`) is the canonical glossary. Link to it for term definitions; do not redefine terms inline in other pages unless as an Aside to introduce the important concept (ex: `InterpretedName` Asides).
+
+## Formatting (footgun)
+
+- Two formatters split by file type, both run by root `pnpm lint` — always lint from the monorepo root, not from this dir.
+  - Prettier (config: root `.prettierrc.json`) formats `.md`/`.mdx`/`.astro` prose/templates.
+  - Biome formats TS (incl. `.astro` frontmatter, `config/`, `scripts/`, `src/**/*.ts`). This dir's `biome.jsonc` disables lint rules and import-organizing; it's formatting-only.
+- Prettier is configured with `embeddedLanguageFormatting: off` for `docs/ensnode.io/**/*.{md,mdx}`: hand-authored GraphQL/code blocks are NOT reflowed. Don't expect fenced code to be auto-formatted.
+
+## Generated / committed artifacts
+
+- `ensapi-openapi.json` is committed and rendered by Scalar on the API Reference page. Regenerate via `pnpm generate:openapi` (or `pnpm generate`) from the monorepo root after changing `apps/ensapi` route schemas. CI's `openapi-sync-check` fails on drift.
+- The OpenAPI spec and the Omnigraph snapshot are the two build inputs the docs read from disk rather than live — both must be regenerated + committed when their upstream source changes.
+
+## Omnigraph examples pipeline (two steps)
+
+The docs do NOT read SDK example queries directly — they render a vendored snapshot in `src/data/omnigraph-examples/` (`examples.json` + `schema.graphql` + `snapshot.json`):
+
+1. `pnpm -F @docs/ensnode omnigraph:snapshot <version>` (e.g. `v1.15.2`) — vendors the workspace SDK's example queries and schema into the snapshot. Required after changing SDK Omnigraph example queries/variables in `packages/ensnode-sdk`; skipping it means step 2 POSTs the stale vendored queries.
+2. `pnpm -F @docs/ensnode omnigraph-examples:refresh-responses [<id>,<id>]` (requires network) — POSTs the vendored queries to the hosted instances and updates `responses.json`. Scope to specific example IDs to leave the rest untouched.
+
+The Omnigraph Examples sidebar entries are generated from `src/data/omnigraph-examples/config.ts` (imported into `sidebar-topics/integrate.ts`), not hand-listed.
+
+## llms-txt (gotcha)
+
+- The `starlight-llms-txt` plugin (patched in root `patches/starlight-llms-txt@0.10.0.patch`) generates `/llms.txt`, `/llms-full.txt`, `/llms-small.txt` at build time.
+- It renders each page through an MDX-only container with NO React renderer. Any `.mdx` page importing a `.tsx` island (e.g. the GraphQL playground / schema reference) MUST be added to `exclude` in `config/integrations/llms-txt.ts` or `astro build` fails with `NoMatchingRenderer`. Exclude patterns are micromatch on the page `id` (path relative to `src/content/docs/`).
+
+## Misc
+
+- Redirects for moved/renamed pages live in `astro.config.mjs` (`redirects`). Renaming or moving a page means adding a redirect there.
+- Path aliases: `@components`, `@content`, `@data`, `@lib`, `@scripts`, `@styles`, `@assets`, `@workspace` (= monorepo root). Defined in `astro.config.mjs`.
+- `trailingSlash: "never"` — internal links must omit trailing slashes.
diff --git a/docs/ensnode.io/CLAUDE.md b/docs/ensnode.io/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/docs/ensnode.io/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/package.json b/package.json
index e11010555d..b620c2d11a 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,7 @@
     "generate:openapi": "pnpm -r generate:openapi",
     "generate:gqlschema": "pnpm -r generate:gqlschema",
     "generate:skills": "pnpm -F ensskills generate",
-    "prepare": "skills-npm --cwd ."
+    "prepare": "skills-npm --cwd . && node scripts/link-local-skills.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.1",
diff --git a/packages/datasources/AGENTS.md b/packages/datasources/AGENTS.md
new file mode 100644
index 0000000000..f46547177b
--- /dev/null
+++ b/packages/datasources/AGENTS.md
@@ -0,0 +1,26 @@
+# @ensnode/datasources
+
+Catalog of ENS contract configs (chain, address, ABI, startBlock, event filters) per ENS namespace. Public npm package — `src/index.ts` exports are external API surface; renaming/removing an export or a `DatasourceName`/contract key is a breaking change and needs a changeset.
+
+## Concepts
+
+- **ENSNamespace** = one logically-isolated set of ENS names with its own root Registry. The four: `mainnet`, `sepolia`, `sepolia-v2` (ENSv1+v2 on Sepolia), `ens-test-env` (deterministic Anvil deployment). They are NOT interchangeable with L1 chains — a namespace spans many chains. See `lib/types.ts` for the canonical definitions.
+- **Datasource** = `{ chain, contracts }` for one chain within a namespace, keyed by `DatasourceName` (`ensroot`, `basenames`, `lineanames`, reverse-resolver `rr*`, `threedns*`, `seaport`, `ENSv2Root`). `ensroot` is the only Datasource present in every namespace; the type system enforces this (`getDatasource` only allows `ensroot` for a non-literal `namespaceId` — use `maybeGetDatasource` otherwise).
+- **ContractConfig** = `{ abi, startBlock, address?, endBlock? }`. A contract with NO `address` is matched by event signature across the whole chain (e.g. `Resolver`) — these are skipped by `identifyDatasourceContracts`. `EventFilter`/`ContractConfig` are intentionally subsets of Ponder's types so plugins can spread them directly into `createConfig`.
+
+## Invariants (enforced by `invariants.test.ts`)
+
+- Every `address` must be a valid viem Address AND fully lowercase (enssdk `NormalizedAddress`). Never paste a checksummed address.
+- `startBlock` = the block the contract was deployed (or, for addressless event-filter contracts, the earliest block worth indexing). Getting it wrong silently drops early events; it is not validated by tests.
+- Use `endBlock` only when a contract was decommissioned (see Basenames `RegistrarController`).
+
+## Gotchas
+
+- ABIs live in `src/abis/<group>/` as `as const` arrays; their numbered/grouped suffixes (`Resolver1`, `DefaultPublicResolver4`, …) and `// NOTE:` comments encode real provenance (which proposal enabled them, whether they emit events, why some are documented-but-not-indexed). Preserve these comments — they are the only record of why an entry exists.
+- `ResolverABI` and `AnyRegistrar*ABI` (`src/lib/`) are `mergeAbis(...)` unions, not a single contract's ABI. A "Resolver" here is any contract emitting ANY of the merged events, not all.
+- `ens-test-env` / devnet addresses come from `src/devnet/constants.ts` (deterministic contracts-v2 deploy via `pnpm devnet`); devnet uses different PascalCase contract names than this catalog — the `// NOTE: named X in devnet` comments map them. All devnet `startBlock`s are `0`.
+- `ensTestEnvChain` (`src/lib/chains.ts`) is Anvil pinned to chainId 31337; it backs all integration tests against `ens-test-env`.
+
+## Cross-package contract
+
+- ENSIndexer plugins (`apps/ensindexer/src/plugins/*`) declare `requiredDatasourceNames`, pull configs via `getRequiredDatasources` / `pickContracts`, and spread each `ContractConfig` into Ponder `createConfig`. Adding a contract to a Datasource does nothing until a plugin references it; a plugin requiring a Datasource that a namespace lacks fails at config time.
diff --git a/packages/datasources/CLAUDE.md b/packages/datasources/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/packages/datasources/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/packages/ensskills/skills/ens-protocol/SKILL.md b/packages/ensskills/skills/ens-protocol/SKILL.md
index 94fa8d2c6f..4c45b9148d 100644
--- a/packages/ensskills/skills/ens-protocol/SKILL.md
+++ b/packages/ensskills/skills/ens-protocol/SKILL.md
@@ -85,6 +85,8 @@ ENS is not "just mainnet." Names and subdomains live across L1, L2s, and offchai
 - Some names resolve only through CCIP-Read (their data isn't on mainnet at all).
 - Reconciling registries, wrappers, resolvers, and chains by hand is exactly what an indexer like ENSNode (and the omnigraph skill) does for you — prefer that over first-principles chain queries.
 
+An **ENS Namespace** is a single, logically-isolated set of ENS names defined by its own root Registry — and it **spans many chains**, not just one. The canonical `mainnet` namespace, for example, roots on Ethereum mainnet but reaches across Base (Basenames), Linea (Lineanames), Optimism (3DNS), and offchain issuers. A namespace is therefore _not_ 1:1 with an L1 chain: separate namespaces (`mainnet`, `sepolia`, testing's `ens-test-env`) are fully independent — a name in one says nothing about the same string in another, and each has its own deployments of `.eth`, Basenames, etc. This is what "ENS Namespace `mainnet`" means above (under Records) when defining coinType `60`. See [references/ensv1-and-ensv2.md](references/ensv1-and-ensv2.md).
+
 ## ENSv1 and ENSv2
 
 **ENSv2 does not replace ENSv1 — the two coexist onchain at the same time.** Building correctly means reading a _unified_ view of both, not one or the other.
@@ -100,13 +102,13 @@ The fundamentals in this skill — names, normalization, hashing, the resolver/r
 
 Pull these only when a task needs the depth:
 
-| Topic                                                                               | File                                                               |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| Names, labels, normalization, namehash/labelhash, unknown labels                    | [references/names-and-hashing.md](references/names-and-hashing.md) |
-| Registry / resolver / registrar, NFTs, NameWrapper, subdomains, subregistries       | [references/architecture.md](references/architecture.md)           |
-| Forward/reverse resolution, primary names, Universal Resolver, CCIP-Read, coinTypes | [references/resolution.md](references/resolution.md)               |
-| All record types — address/text/avatar/contenthash/ABI/pubkey/interface/DNS/name    | [references/records.md](references/records.md)                     |
-| ENSv1 vs ENSv2 — coexistence, Namegraph, two-domains, resolving across both         | [references/ensv1-and-ensv2.md](references/ensv1-and-ensv2.md)     |
+| Topic                                                                                | File                                                               |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| Names, labels, normalization, namehash/labelhash, unknown labels                     | [references/names-and-hashing.md](references/names-and-hashing.md) |
+| Registry / resolver / registrar, NFTs, NameWrapper, subdomains, subregistries        | [references/architecture.md](references/architecture.md)           |
+| Forward/reverse resolution, primary names, Universal Resolver, CCIP-Read, coinTypes  | [references/resolution.md](references/resolution.md)               |
+| All record types — address/text/avatar/contenthash/ABI/pubkey/interface/DNS/name     | [references/records.md](references/records.md)                     |
+| ENS Namespaces, ENSv1 vs ENSv2 — coexistence, Namegraph, two-domains, resolving both | [references/ensv1-and-ensv2.md](references/ensv1-and-ensv2.md)     |
 
 Terminology: [ENSNode Terminology](https://ensnode.io/docs/reference/terminology) · Specs: [ENSIPs](https://docs.ens.domains/ensips)
 
diff --git a/packages/ensskills/skills/ens-protocol/references/ensv1-and-ensv2.md b/packages/ensskills/skills/ens-protocol/references/ensv1-and-ensv2.md
index adbabd4c82..8064cce87c 100644
--- a/packages/ensskills/skills/ens-protocol/references/ensv1-and-ensv2.md
+++ b/packages/ensskills/skills/ens-protocol/references/ensv1-and-ensv2.md
@@ -4,6 +4,10 @@ Definitions follow the [ENSNode Terminology Reference](https://ensnode.io/docs/r
 
 ENSv2 does not replace ENSv1 — both are live onchain at once, with substantially different data models, so an integration must read a **unified** view of both. This page details how they differ and what that means for your code.
 
+## ENS Namespaces (the outer boundary)
+
+Everything below happens _within an_ **ENS Namespace**: a single, logically-isolated set of ENS names defined by its own root Registry. A namespace **spans many chains** (and offchain systems) — the canonical `mainnet` namespace roots on Ethereum mainnet and reaches across Base, Linea, Optimism, and offchain issuers — so it is **not** 1:1 with an L1 chain. Distinct namespaces (`mainnet`, `sepolia`, the testing-only `ens-test-env`) are fully independent: each has its own root Registry and its own deployments of `.eth`, Basenames, Lineanames, etc., and a name in one namespace says nothing about the same string in another. ENSv1 and ENSv2 are two data models _inside_ a namespace, not two namespaces.
+
 ## ENSv1 (live today)
 
 - A name maps to state via a flat **`namehash → state`** table (a Nametable): the Registry stores each node's owner and resolver, resolvers store records.
diff --git a/packages/ensskills/skills/omnigraph/SKILL.md b/packages/ensskills/skills/omnigraph/SKILL.md
index ebfa341019..a3cfc949df 100644
--- a/packages/ensskills/skills/omnigraph/SKILL.md
+++ b/packages/ensskills/skills/omnigraph/SKILL.md
@@ -62,6 +62,14 @@ A condensed reference is also inlined below.
 - **Relay pagination** — connections expose `edges { node }`, `pageInfo { hasNextPage endCursor }`, and `totalCount`. Paginate with `first` + `after: <endCursor>`. (No offset pagination.)
 - **Field selection is the budget.** GraphQL returns exactly the fields you select — request only what you need to keep responses (and your context) small.
 
+## Protocol Acceleration
+
+`resolve` (on `Domain` and `Account`) is **accelerated by default**: the server implements the ENS Universal Resolver's forward/reverse resolution logic over its indexed data, serving each record straight from the index wherever possible (~10ms vs ~100–1000ms for RPC + CCIP-Read paths). Any record it can't accelerate transparently falls back to protocol-compliant RPC resolution — including performing CCIP-Read for offchain names on your behalf. **Results are identical either way**; acceleration changes latency, never correctness. There is normally no reason to disable it (`resolve(accelerate: false)` exists for debugging/comparison). Select `acceleration { requested attempted }` on a resolution to observe whether acceleration was attempted.
+
+## Indexing status & 503s
+
+The Omnigraph serves indexed state. An instance responds **503 Service Unavailable** (with a `reason`) when it can't serve a request faithfully — e.g. its indexer isn't sufficiently caught up to realtime, its indexing status is unavailable, or the instance isn't running the plugins a given API requires. Treat 503 as "temporarily unavailable or unsupported by this instance" (retry or switch instances), not as a malformed query. Check an instance's indexing progress with `npx enscli ensnode indexing-status [--namespace <ns> | --ensnode-url <url>]`.
+
 ## When the Omnigraph can't express it
 
 If a question genuinely isn't expressible in the Omnigraph schema, the underlying ENS state is also queryable via Unigraph SQL over ENSDb (the `unigraph-sql` skill). Prefer the Omnigraph first; escalate to SQL only for shapes the GraphQL surface doesn't support.
diff --git a/packages/integration-test-env/AGENTS.md b/packages/integration-test-env/AGENTS.md
new file mode 100644
index 0000000000..2e96ef4220
--- /dev/null
+++ b/packages/integration-test-env/AGENTS.md
@@ -0,0 +1,33 @@
+# @ensnode/integration-test-env
+
+Orchestrates the full ENSNode stack against the `ens-test-env` devnet so monorepo-level `*.integration.test.ts` files can run against a live instance. `src/lifecycle.ts` is the source of truth; `start.ts` and `ci.ts` are thin entrypoints over it.
+
+## Bring-up contract (lifecycle.ts `bringUp`)
+
+- Strictly ordered phases, each gated on the prior's health: ENSDb+devnet (docker-compose) → seed devnet → ENSRainbow → ENSIndexer → wait for omnichain `Following`/`Completed` → ENSApi. Order matters — seeding MUST land before ENSIndexer starts, since the indexer only sees state present at its start block sweep.
+- `--only <a,b>` (comma list of `devnet,ensrainbow,ensindexer,ensapi`) subsets the phases. `devnet` implicitly includes ENSDb + seeding; `ensindexer` implicitly includes the wait-for-indexing poll. Omitted services' ports aren't required.
+- On any spawned-service crash, a shared abort flag short-circuits every health/poll loop (`checkAborted`). Services run `detached` and are killed by process-group (`-pid`) on cleanup, because `pnpm` does not forward SIGTERM to its node children — don't "simplify" this to a plain `subprocess.kill()`.
+
+## Two usage modes
+
+- `pnpm start` (blocking) brings up the stack and waits for Ctrl+C; from another terminal run the monorepo-root `pnpm test:integration`. Use for iterating on tests.
+- `pnpm start:ci` (`CI=1`) does bring-up → `pnpm test:integration --bail 1` → teardown, all in one process. This is what `test:integration:ci` runs.
+
+## Hardcoded contract (must stay in sync across services)
+
+- Ports: ENSDb **5433** (host), ENSRainbow 3223, ENSIndexer 42069, ENSApi 4334, devnet RPC 8545 (anvil, chain id **31337** — `ensTestEnvChain`). 5433 (not 5432) is deliberate: avoids colliding with manually-started stacks; the orchestrator compose renames containers to `*-orchestrator` for the same reason.
+- Schema name `ensindexer_integration_test` is passed identically to ENSIndexer (writer) and ENSApi (reader). They MUST match or ENSApi reads an empty schema.
+- ENSIndexer runs `NAMESPACE=ens-test-env`, `PLUGINS=unigraph,protocol-acceleration`. ENSRainbow uses label set `ens-test-env`/`0`, `DB_SCHEMA_VERSION=3`.
+- Devnet image is pinned in `docker/docker-compose.orchestrator.yml`; bump it there.
+
+## Devnet seeding (`src/seed/`, fixtures in `src/devnet/fixtures.ts`)
+
+- Accounts derive from the anvil junk mnemonic by index: deployer(0), owner(1), user(2), user2(3) — these are devnet-only addresses, never real.
+- Seeds: primary name `test.eth` (on `owner`), the `test.eth` resolver text/addr/abi/contenthash records, and the effective-resolver-fallback case `noresolver.parent.eth` (no own resolver → ENSIP-10 fallback to `parent.eth`). `fixtures.ts` is the single source of truth for expected values; integration tests assert against it, so editing a fixture means re-checking the assertions.
+
+## Gotchas
+
+- Requires a running Docker daemon. ENSRainbow's `/ready` only flips green after it downloads + extracts a prebuilt LevelDB — the slowest phase; budget for it on a cold run.
+- Cleanup runs `compose down` with `removeVolumes: true` every time: Ponder rejects a schema owned by a prior app, so the Postgres volume can't be reused across runs. Don't disable this to "speed things up."
+- A leftover `*-orchestrator` container or a process squatting a hardcoded port from a crashed prior run will fail bring-up; remove stale containers / free the port first.
+- Integration tests read `ENSNODE_URL` (root config defaults to `http://localhost:4334`); the CI flow injects the live ENSApi endpoint. Point it elsewhere to target a remote instance.
diff --git a/packages/integration-test-env/CLAUDE.md b/packages/integration-test-env/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/packages/integration-test-env/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/scripts/link-local-skills.mjs b/scripts/link-local-skills.mjs
new file mode 100644
index 0000000000..cc4c7fb77b
--- /dev/null
+++ b/scripts/link-local-skills.mjs
@@ -0,0 +1,39 @@
+// Mirrors local skills from .agents/skills (canonical, committed) into
+// .claude/skills as symlinks, so Claude Code discovers them. npm-* entries are
+// managed by skills-npm and skipped. Runs via the root `prepare` script.
+import { lstatSync, mkdirSync, readdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const root = new URL("..", import.meta.url).pathname;
+const source = join(root, ".agents", "skills");
+const target = join(root, ".claude", "skills");
+
+mkdirSync(target, { recursive: true });
+
+const isLocalSkill = (name) => !name.startsWith("npm-") && !name.startsWith(".");
+const localSkills = readdirSync(source).filter(isLocalSkill);
+
+// drop symlinks into .agents/skills whose canonical skill no longer exists
+for (const name of readdirSync(target)) {
+  if (!isLocalSkill(name)) continue;
+  const path = join(target, name);
+  if (!lstatSync(path).isSymbolicLink()) continue;
+  const linksIntoSource = readlinkSync(path).includes(".agents/skills");
+  if (linksIntoSource && !localSkills.includes(name)) unlinkSync(path);
+}
+
+for (const name of localSkills) {
+  const path = join(target, name);
+  const desired = relative(target, join(source, name));
+  try {
+    if (readlinkSync(path) === desired) continue;
+    unlinkSync(path);
+  } catch {
+    // missing or not a symlink: a real directory here is a personal skill — leave it
+    try {
+      if (lstatSync(path).isDirectory()) continue;
+    } catch {}
+  }
+  symlinkSync(desired, path);
+  console.log(`linked .claude/skills/${name} -> ${desired}`);
+}
diff --git a/skills-npm.config.ts b/skills-npm.config.ts
new file mode 100644
index 0000000000..dc4247d15a
--- /dev/null
+++ b/skills-npm.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from "skills-npm";
+
+export default defineConfig({
+  // .agents/skills (universal) + .claude/skills only
+  agents: ["universal", "claude-code"],
+  yes: true,
+});

From e4a66b36da05b61b53ff702ffd7c5d45024c8439 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 11:49:38 -0500
Subject: [PATCH 04/10] feat: ensskills

---
 .changeset/enssdk-enskit-skills.md            |   5 +
 .../integration-options/ensskills.mdx         |   4 +-
 packages/enskit/README.md                     |   4 +-
 packages/enssdk/README.md                     |   4 +-
 .../references/names-and-hashing.md           |   4 +
 packages/ensskills/skills/enskit/SKILL.md     | 291 +++++++++++++++++-
 packages/ensskills/skills/enssdk/SKILL.md     | 278 ++++++++++++++++-
 7 files changed, 572 insertions(+), 18 deletions(-)
 create mode 100644 .changeset/enssdk-enskit-skills.md

diff --git a/.changeset/enssdk-enskit-skills.md b/.changeset/enssdk-enskit-skills.md
new file mode 100644
index 0000000000..5d7768409e
--- /dev/null
+++ b/.changeset/enssdk-enskit-skills.md
@@ -0,0 +1,5 @@
+---
+"ensskills": minor
+---
+
+The `enssdk` and `enskit` skills are now fully authored (previously stubs): `enssdk` covers the typed ENS Omnigraph client (gql.tada), hashing, normalization, and interpretation primitives for TypeScript integrations; `enskit` covers building ENS React UIs (provider setup, typed Omnigraph hooks, caching, Relay pagination). The `ens-protocol` skill also gained the Subgraph-Interpreted Label concept (why subgraph-compatible APIs may return an Encoded LabelHash where the Omnigraph returns the literal label).
diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx
index 5b02f8859a..501244604c 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx
@@ -77,11 +77,11 @@ It detects your agents and writes the skills into each (`.claude/skills`, `.curs
 - **`ens-protocol`** — how the ENS protocol works at a conceptual level: the nametree, normalization, namehash/labelhash, registry/resolver/registrar, forward & reverse resolution, primary names, records, and ENS across chains. Vendor-neutral, intentionally stable, with pull-as-needed reference pages. The mental model the other skills build on.
 - **`omnigraph`** — the monolithic ENS skill. Teaches the unified ENSv1 + ENSv2 datamodel, resolution via `Domain.resolve` / `Account.resolve`, Relay pagination, a condensed schema reference, vetted example queries, and how to execute and explore queries with `enscli`.
 - **`enscli`** — running ENS lookups from the shell: the output contract, namespace/URL resolution, input hardening, and every command (Omnigraph queries, offline schema exploration, `namehash`/`labelhash`, ENSRainbow healing, indexing status).
+- **`enssdk`** — TypeScript integration: the typed Omnigraph client (gql.tada setup, fragments, union/connection narrowing) and the easy-to-get-wrong primitives (normalization, namehash/labelhash, interpretation/beautification, branded types).
+- **`enskit`** — React integration: `OmnigraphProvider` setup, `useOmnigraphQuery`, the preconfigured normalized cache, Relay pagination patterns, and name-display conventions.
 
 The following are reserved and ship as stubs today, fleshed out in upcoming releases:
 
-- **`enssdk`** — TypeScript integration with the typed Omnigraph client.
-- **`enskit`** — React integration (`useOmnigraphQuery`, cache directives, infinite pagination).
 - **`migrate-to-omnigraph`** — migrating from the legacy ENS Subgraph.
 - **`unigraph-sql`** — SQL over ENSDb for query shapes the Omnigraph doesn't express.
 
diff --git a/packages/enskit/README.md b/packages/enskit/README.md
index a1fa5dbdb1..b95b39f7ca 100644
--- a/packages/enskit/README.md
+++ b/packages/enskit/README.md
@@ -12,8 +12,8 @@ For more information, visit [ensnode.io](https://ensnode.io).
 npm install enskit enssdk
 ```
 
-> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enskit@1.13.1` and `enssdk@1.13.1`. The latest published versions (`1.14.0+`) contain breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded.
+> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.15. If you are querying them from your own app, pin `enskit` and `enssdk` to the matching version — the Omnigraph API data model can change between versions.
 >
 > ```bash
-> npm install enskit@1.13.1 enssdk@1.13.1
+> npm install enskit@1.15.2 enssdk@1.15.2
 > ```
diff --git a/packages/enssdk/README.md b/packages/enssdk/README.md
index dfcdab1ef7..072a06e24a 100644
--- a/packages/enssdk/README.md
+++ b/packages/enssdk/README.md
@@ -10,10 +10,10 @@ Learn more about [ENSNode](https://ensnode.io/) from [the ENSNode docs](https://
 npm install enssdk
 ```
 
-> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enssdk@1.13.1`. The latest published version (`1.14.0+`) contains breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded.
+> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.15. If you are querying them from your own app, pin `enssdk` to the matching version — the Omnigraph API data model can change between versions.
 >
 > ```bash
-> npm install enssdk@1.13.1
+> npm install enssdk@1.15.2
 > ```
 
 ## Usage
diff --git a/packages/ensskills/skills/ens-protocol/references/names-and-hashing.md b/packages/ensskills/skills/ens-protocol/references/names-and-hashing.md
index 7247987d97..9c3a21cc1a 100644
--- a/packages/ensskills/skills/ens-protocol/references/names-and-hashing.md
+++ b/packages/ensskills/skills/ens-protocol/references/names-and-hashing.md
@@ -38,3 +38,7 @@ Because only hashes are registered, the human-readable label behind a node is so
 In `enssdk`: `encodeLabelHash` produces the `[…]` form, `isEncodedLabelHash` detects it, and `parseLabelHashOrEncodedLabelHash` accepts either a bare labelhash or the encoded form — handy when a label may or may not be known.
 
 ENSNode further distinguishes _Literal_ / _Interpreted_ / _Beautified_ forms of labels and names for indexing and display; see the [terminology reference](https://ensnode.io/docs/reference/terminology) if you need that precision.
+
+### Subgraph-Interpreted (legacy)
+
+The legacy ENS Subgraph treats some labels as **subgraph-unindexable**: Unknown Labels, plus any literal containing `\0`, `.`, `[`, or `]`. A **Subgraph Interpreted Label** renders those as an Encoded LabelHash _even when the literal is actually known_. Practical consequence: a subgraph-compatible API may return `[hash…]` where the ENS Omnigraph returns the literal label — expect this divergence when comparing results across the two APIs or migrating off the Subgraph.
diff --git a/packages/ensskills/skills/enskit/SKILL.md b/packages/ensskills/skills/enskit/SKILL.md
index 8df903d004..5c13bae9c5 100644
--- a/packages/ensskills/skills/enskit/SKILL.md
+++ b/packages/ensskills/skills/enskit/SKILL.md
@@ -1,16 +1,293 @@
 ---
 name: enskit
-description: Reference for building ENS React UIs with enskit (urql-based ENS Omnigraph hooks like useOmnigraphQuery, cache directives, infinite pagination). Coming soon.
+description: Build ENS React UIs with enskit — set up the OmnigraphProvider, run typed ENS Omnigraph queries with useOmnigraphQuery (gql.tada documents, loading/error states, union/connection handling), get a normalized urql cache for free, paginate Relay connections, and render beautified names. Use when wiring ENS data into a React app.
 ---
 
-# enskit (coming soon)
+# enskit
 
-A dedicated `enskit` React integration skill is planned (`useOmnigraphQuery`, the urql-based client, Omnigraph cache directives, infinite pagination). Until then, lean on the skills it depends on.
+`enskit` is the React toolkit for reading the **ENS Omnigraph** in a React app. It is a thin, typed layer over [`urql`](https://nearform.com/open-source/urql/) + [`gql.tada`](https://gql-tada.0no.co/): a provider that points at an ENSNode instance, a `useOmnigraphQuery` hook, and a preconfigured normalized cache (`@urql/exchange-graphcache`) tuned for the Omnigraph schema — relay pagination, cross-lookup cache hits, and native `bigint` scalars, all wired up for you.
+
+You author Omnigraph queries exactly as the **`omnigraph`** skill describes; `enskit` is how you _run_ them inside React components.
+
+```bash
+npm install enskit enssdk
+```
 
 ## Dependencies
 
-This skill depends on the following sibling skills — load them first:
+Load these sibling skills first:
+
+- **`base`** — shared ENS working conventions (prefer the Omnigraph for reads, `Node` terminology, output hygiene).
+- **`ens-protocol`** — the protocol the data models (names, normalization, resolution, records, ENSv1/ENSv2).
+- **`omnigraph`** — the query model and data shapes; **author your queries there**, then run them with the hooks here.
+- **`enssdk`** — enskit is built on `enssdk`. You construct the client and use name/address primitives (normalization, beautification) from `enssdk`.
+
+> **Version pinning matters.** enskit speaks the Omnigraph schema of a _specific_ ENSNode version, baked in via gql.tada introspection. Match your `enskit` and `enssdk` versions to the ENSNode instance you query (e.g. the NameHash-hosted instances). A mismatch surfaces as schema/type errors or unexpected nulls. See [ensnode.io/docs/hosted-instances](https://ensnode.io/docs/hosted-instances).
+
+## Entry points
+
+Two subpath exports:
+
+- `enskit/react/omnigraph` — `OmnigraphProvider`, `useOmnigraphQuery`, the `graphql` tagged-template (gql.tada), and the type helpers `FragmentOf` / `ResultOf` / `VariablesOf` + `readFragment`.
+- `enskit/react` — UI helpers, currently `EnsureInterpretedName`.
+
+## Provider setup
+
+Build an `EnsNodeClient` with `enssdk`, extend it with the `omnigraph` module, and hand it to `OmnigraphProvider`. The provider derives a `urql` client from the ENSNode `url` and POSTs operations to that instance's `/api/omnigraph` endpoint.
+
+```tsx
+import { OmnigraphProvider } from "enskit/react/omnigraph";
+import { createEnsNodeClient } from "enssdk/core";
+import { omnigraph } from "enssdk/omnigraph";
+
+// Pick the ENSNode instance / namespace by URL. Use a NameHash-hosted instance
+// (https://ensnode.io/docs/hosted-instances) or your own.
+const client = createEnsNodeClient({
+  url: "https://api.v2-sepolia.ensnode.io",
+}).extend(omnigraph);
+
+export function App() {
+  return (
+    <OmnigraphProvider client={client}>
+      <YourRoutes />
+    </OmnigraphProvider>
+  );
+}
+```
+
+The ENSNode `url` _is_ the namespace selector: different hosted instances serve different ENS Namespaces (mainnet, sepolia, sepolia-v2, …). There is no separate `namespace` prop — point the client at the instance for the namespace you want.
+
+`OmnigraphProvider` is a client component (`"use client"`). In Next.js App Router, render it in a `"use client"` boundary. enskit ships no Server Components / RSC data fetcher and no built-in Suspense integration — `useOmnigraphQuery` is a standard client hook driving loading/error state explicitly (below).
+
+## Typed queries with gql.tada
+
+Author queries with the `graphql` template from `enskit/react/omnigraph`. It is a project-bound `gql.tada` instance pre-loaded with the Omnigraph schema, so selections, variables, and results are **fully typed** — no codegen step at call sites, and the `BigInt` scalar comes back as a native `bigint`.
+
+```tsx
+import { graphql, useOmnigraphQuery } from "enskit/react/omnigraph";
+
+const DomainQuery = graphql(`
+  query DomainByName($name: InterpretedName!) {
+    domain(by: { name: $name }) {
+      __typename
+      id
+      canonical {
+        name {
+          beautified
+        }
+      }
+      owner {
+        address
+      }
+    }
+  }
+`);
+```
+
+To get end-to-end types in your editor, enable the gql.tada TS plugin in `tsconfig.json`, pointing `schema` at the `enssdk`-vendored Omnigraph SDL:
+
+```jsonc
+"plugins": [
+  {
+    "name": "gql.tada/ts-plugin",
+    "schema": "node_modules/enssdk/src/omnigraph/generated/schema.graphql",
+    "tadaOutputLocation": "./src/generated/graphql-env.d.ts",
+  },
+],
+```
+
+**Fragments** keep selections colocated and reusable. Pass dependent fragments as the second `graphql(...)` argument, then unwrap masked data at the render site with `readFragment`:
+
+```tsx
+import { type FragmentOf, graphql, readFragment } from "enskit/react/omnigraph";
+
+const DomainFragment = graphql(`
+  fragment DomainFragment on Domain {
+    __typename
+    id
+    canonical {
+      name {
+        beautified
+      }
+    }
+    owner {
+      address
+    }
+  }
+`);
+
+const ListQuery = graphql(
+  `
+    query Subdomains($name: InterpretedName!, $first: Int!, $after: String) {
+      domain(by: { name: $name }) {
+        subdomains(first: $first, after: $after) {
+          edges {
+            node {
+              ...DomainFragment
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    }
+  `,
+  [DomainFragment],
+);
+
+function Row({ data }: { data: FragmentOf<typeof DomainFragment> }) {
+  const domain = readFragment(DomainFragment, data);
+  return <span>{domain.canonical?.name.beautified ?? <em>non-canonical</em>}</span>;
+}
+```
+
+`VariablesOf<typeof Query>` and `ResultOf<typeof Query>` give you the typed variable/result shapes when you need to name them.
+
+## useOmnigraphQuery
+
+The single read hook. It is a typed pass-through to urql's `useQuery`, so it returns a tuple `[result, reexecute]`.
+
+```tsx
+const [result, reexecute] = useOmnigraphQuery({
+  query: DomainQuery,
+  variables: { name }, // typed from the document
+  pause: !name, // skip the request until inputs are ready
+  context: undefined, // optional urql OperationContext (see caching)
+});
+
+const { data, fetching, error } = result;
+
+if (!data && fetching) return <p>Loading…</p>;
+if (error) return <p>Error: {error.message}</p>;
+if (!data?.domain) return <p>Not found.</p>;
+```
+
+Notes:
+
+- `data` can be present _while_ `fetching` is true (e.g. refetching a new page). Gate the spinner on `!data && fetching`, not `fetching` alone, to avoid flashing the whole view on pagination.
+- `error` is a `CombinedError` — read `error.message`, or `error.graphQLErrors` / `error.networkError` for detail.
+- `pause: true` holds the query; flip it false once required variables exist.
+- The Omnigraph returns **503** when an instance can't serve a request faithfully (indexer behind realtime, or a required plugin absent — see the `omnigraph` skill). That arrives as `error.networkError`; treat it as "temporarily unavailable / retry," not a malformed query.
+
+### Unions and connections in components
+
+The Omnigraph schema leans on **interfaces/unions** (`Domain` → `ENSv1Domain` / `ENSv2Domain` / `UnindexedDomain`; `Registration` → `BaseRegistrarRegistration` / `NameWrapperRegistration` / …). Select `__typename` and inline fragments (`... on ENSv2Domain { … }`) in the query, then branch on `__typename` in JSX:
+
+```tsx
+{
+  domain.__typename === "ENSv2Domain" ? "Reserved" : (domain.owner?.address ?? "0x0");
+}
+```
+
+**Connections** follow the Relay spec: read `edges[].node`, `pageInfo.hasNextPage`, `pageInfo.endCursor`, and `totalCount`. There is no offset pagination — paginate by cursor (below).
+
+## Caching
+
+`OmnigraphProvider` installs a `@urql/exchange-graphcache` **normalized** cache configured against the Omnigraph schema. You get useful behavior with zero config:
+
+- **Entity normalization & dedup.** `Domain`, `Account`, `Registry`, `Resolver`, `Permissions`, etc. are keyed by `id` (Accounts also by `address`, `AccountId` by its stringified form). Embedded/value types (resolution containers, profile/record shapes, `CanonicalName`, …) are intentionally non-keyable and cached inline under their parent.
+- **Cross-lookup cache hits.** Fetch an entity one way and a different lookup for the _same_ entity resolves from cache without a network round-trip — e.g. `Query.root` then `registry(by: { id })` and `registry(by: { contract })` all hit the cached Registry. The same applies to `domain(by: { id })` after the Domain was loaded elsewhere (it resolves across the ENSv1/ENSv2/Unindexed variants).
+- **Native `bigint` scalars.** Fields typed `BigInt` in the schema are returned as JS `bigint` (the cache stores the string and rehydrates it), matching the `graphql` template's scalar mapping.
+
+Inspect cache outcome per operation via `result.operation?.context.meta?.cacheOutcome` (`"hit"` | `"partial"` | `"miss"`).
+
+Control freshness with urql's `requestPolicy` on the `context`:
+
+```tsx
+import { useMemo } from "react";
+
+const [result, reexecute] = useOmnigraphQuery({
+  query: RootRegistryQuery,
+  // MUST be memoized — a new context object each render causes an infinite re-render loop.
+  context: useMemo(() => ({ requestPolicy: "network-only" }), []),
+});
+
+// imperatively refetch (e.g. a "Refresh" button)
+reexecute({ requestPolicy: "network-only" });
+```
+
+`cache-and-network` (serve cache, revalidate in background) and `network-only` (skip the cache read) are the usual choices. There is no custom invalidation API exposed by enskit; rely on normalized updates + `requestPolicy`/`reexecute`. enskit does not configure mutation/`updates`/optimistic handlers — it is a read layer.
+
+## Pagination (Relay connections)
+
+The cache derives `relayPagination()` resolvers for **every** connection field in the schema, so successive pages of the same connection are **merged in the cache automatically** — you don't concatenate `edges` yourself. The component pattern: hold the `after` cursor in state, advance it from `pageInfo.endCursor`, and let the cache accumulate. Infinite-scroll is the same pattern with the button replaced by an intersection observer.
+
+```tsx
+const PAGE_SIZE = 20;
+
+function Subdomains({ name }: { name: InterpretedName }) {
+  const [after, setAfter] = useState<string | null>(null);
+
+  const [result] = useOmnigraphQuery({
+    query: ListQuery,
+    variables: { name, first: PAGE_SIZE, after },
+  });
+
+  const { data, fetching, error } = result;
+  if (!data && fetching) return <p>Loading…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  const conn = data?.domain?.subdomains;
+  return (
+    <>
+      <ul>
+        {conn?.edges.map((edge) => {
+          const { id } = readFragment(DomainFragment, edge.node);
+          return (
+            <li key={id}>
+              <Row data={edge.node} />
+            </li>
+          );
+        })}
+      </ul>
+      {conn?.pageInfo.hasNextPage && (
+        <button type="button" disabled={fetching} onClick={() => setAfter(conn.pageInfo.endCursor)}>
+          {fetching ? "Loading…" : "Next page"}
+        </button>
+      )}
+    </>
+  );
+}
+```
+
+For typeahead/search over `Query.domains`, the same hook works: debounce input, drive it through `variables.where.name` (e.g. `{ starts_with: query }`), reset `after` to `null` when the query string changes, and `pause` while the input is empty.
+
+## Displaying names
+
+Per the `base` / `ens-protocol` conventions: never `toLowerCase()` or hand-format a name. Two helpers:
+
+- **Render beautified.** Select `canonical { name { beautified } }` and show that string — it's the display-ready form. (`interpreted` is the normalized/ENSIP-15 form for keys, links, and comparison.) Fall back to a "non-canonical domain" label when `canonical` is null. Link Domains by their **stable `id`** (`DomainId`), not their name — a name is not a stable identifier across ENSv1/ENSv2.
+- **Coerce user input safely with `EnsureInterpretedName`.** When a name comes from the URL or a text field, wrap rendering in this component to convert a `LiteralName` into an `InterpretedName` (the branded type the Omnigraph variables expect) before querying — with render props for the three outcomes:
+
+```tsx
+import { EnsureInterpretedName } from "enskit/react";
+import { asLiteralName } from "enssdk";
+
+<EnsureInterpretedName
+  name={asLiteralName(rawNameFromUrl)}
+  options={{
+    allowEncodedLabelHashes: true,
+    coerceUnnormalizableLabelsToEncodedLabelHashes: true,
+  }}
+  // already a valid InterpretedName → render normally
+  children={(name) => <DomainPage name={name} />}
+  // input was coerced to canonical form → redirect to the canonical URL
+  coerced={(name) => <Navigate to={`/domain/name/${name}`} replace />}
+  // input can't be interpreted (unnormalizable) → show an error
+  malformed={(name) => <p>Invalid name: {name}</p>}
+/>;
+```
+
+`options` are forwarded to `enssdk`'s `literalNameToInterpretedName` (controls ENS-root handling, encoded-labelhash passthrough, and normalization/coercion of unnormalizable labels). Normalize addresses from user input with `enssdk`'s `isNormalizedAddress` / `toNormalizedAddress` before using them as `Address!` variables.
+
+## Putting it together
+
+A typical page: `OmnigraphProvider` at the root → `EnsureInterpretedName` (or address normalization) at the route boundary → a `graphql`-authored query run with `useOmnigraphQuery` → branch on `__typename`, render `beautified` names, link by `id`, and paginate connections by cursor. Author every query against the **`omnigraph`** skill's schema reference; this skill only changes _where_ those queries run.
+
+## Related skills
 
-- **`base`** — the shared working conventions every ENS skill assumes.
-- **`ens-protocol`** — the protocol model behind the data `enskit` renders.
-- **`omnigraph`** — the underlying query model `enskit`'s hooks execute.
+- **omnigraph** — author the queries (schema, examples, resolution, pagination semantics).
+- **enssdk** — the client (`createEnsNodeClient`/`omnigraph`) and the name/address primitives enskit builds on.
+- **migrate-to-omnigraph** — if you're porting an app off the legacy ENS Subgraph.
diff --git a/packages/ensskills/skills/enssdk/SKILL.md b/packages/ensskills/skills/enssdk/SKILL.md
index 400e967342..da90aa860a 100644
--- a/packages/ensskills/skills/enssdk/SKILL.md
+++ b/packages/ensskills/skills/enssdk/SKILL.md
@@ -1,16 +1,284 @@
 ---
 name: enssdk
-description: Reference for integrating ENS into JavaScript/TypeScript apps with the enssdk library (typed ENS Omnigraph client via gql.tada, hashing, normalization). Coming soon.
+description: Integrate ENS into JavaScript/TypeScript apps with enssdk — a fully-typed ENS Omnigraph client (typed GraphQL via gql.tada) plus the easy-to-get-wrong primitives (namehash/labelhash, ENSIP-15 normalization, name interpretation/beautification, branded Name/Label/Address types). Use when writing TS/JS that reads ENS data or manipulates ENS names.
 ---
 
-# enssdk (coming soon)
+# enssdk
 
-A dedicated `enssdk` integration skill is planned (typed Omnigraph queries with `gql.tada`, client setup, hashing/normalization helpers). Until then, lean on the skills it depends on.
+`enssdk` is the foundational ENS developer library for JavaScript/TypeScript: a typed client over the **ENS Omnigraph** (one GraphQL API unifying ENSv1 + ENSv2 across every chain) plus the name/hash/address primitives that are notoriously easy to get wrong. It is isomorphic (browser, Node, edge), tree-shakable, and exposes composable modules via subpath exports.
+
+**Reach for `enssdk` when** you are writing TS/JS that needs to read ENS state or handle ENS names — instead of hitting registry/resolver contracts, the legacy ENS Subgraph, or hand-rolling `namehash`/normalization yourself.
 
 ## Dependencies
 
 This skill depends on the following sibling skills — load them first:
 
 - **`base`** — the shared working conventions every ENS skill assumes.
-- **`ens-protocol`** — the underlying protocol (names, hashing, normalization, resolution) the SDK's helpers and types reflect.
-- **`omnigraph`** — the query model and data shapes `enssdk` exposes in TypeScript.
+- **`ens-protocol`** — the protocol the SDK's helpers and types reflect (names, hashing, normalization, resolution, records).
+- **`omnigraph`** — the query model and data shapes. **This is where queries get AUTHORED** (schema reference, field semantics, vetted example queries). This skill shows how to _run_ those queries from TypeScript; it does not re-document the schema. Author against `omnigraph`, run with `enssdk`.
+
+## Install
+
+```bash
+npm install enssdk
+```
+
+`gql.tada`, `graphql`, and `viem` are **peer dependencies** — install them too if you want typed queries / the viem-backed hashing helpers:
+
+```bash
+npm install gql.tada graphql viem
+```
+
+> **Version compatibility:** a NameHash-hosted ENSNode instance runs a specific ENSNode version, and the Omnigraph data model can change between versions. Pin `enssdk` to the version matching the instance you query (see [ensnode.io/docs/hosted-instances](https://ensnode.io/docs/hosted-instances)). Mismatched versions can produce schema/type drift.
+
+## Client setup
+
+Create a client pointed at an ENSNode instance, then `.extend()` it with the modules you need. The client is a small composable object — only the modules you attach ship in your bundle.
+
+```typescript
+import { createEnsNodeClient } from "enssdk/core";
+import { omnigraph } from "enssdk/omnigraph";
+
+// Point at any ENSNode instance. NameHash hosts several:
+//   mainnet  → https://api.alpha.ensnode.io
+//   sepolia  → https://api.alpha-sepolia.ensnode.io
+//   v2 (Sepolia) → https://api.v2-sepolia.ensnode.io
+// or your own (e.g. http://localhost:4334). See https://ensnode.io/docs/hosted-instances
+const client = createEnsNodeClient({
+  url: process.env.ENSNODE_URL ?? "https://api.alpha.ensnode.io",
+}).extend(omnigraph);
+```
+
+`createEnsNodeClient` config:
+
+- `url` (required) — the ENSNode instance base URL. Queries POST to `<url>/api/omnigraph`.
+- `fetch` (optional) — a custom `fetch` implementation for runtimes that need one.
+
+## Typed queries with gql.tada
+
+`enssdk/omnigraph` exports a `graphql` tag pre-bound to the Omnigraph schema. Documents you write with it are fully typed — variables, response shape, unions, and connections — with **zero codegen step for the query types themselves** (gql.tada infers them at the type level). You only need a one-time editor/tsc setup so gql.tada knows the schema.
+
+### One-time gql.tada setup
+
+The schema ships inside the package. Add the gql.tada TypeScript plugin to your `tsconfig.json`, pointing `schema` at the vendored file:
+
+```jsonc
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "gql.tada/ts-plugin",
+        // the Omnigraph schema is bundled with enssdk
+        "schema": "node_modules/enssdk/src/omnigraph/generated/schema.graphql",
+        // gql.tada writes inferred type metadata here; commit it
+        "tadaOutputLocation": "./src/generated/graphql-env.d.ts",
+      },
+    ],
+  },
+}
+```
+
+Then generate the typings the plugin uses (re-run when you bump `enssdk`):
+
+```bash
+npx gql.tada generate-output
+```
+
+This produces `graphql-env.d.ts`. With it in place, `graphql(...)` documents typecheck against the live schema and your editor autocompletes fields.
+
+> If you are not using TypeScript / a build that runs `tsc`, you can skip the plugin entirely and still execute queries — you just lose the static typing on the documents.
+
+### Authoring & executing
+
+```typescript
+import { createEnsNodeClient } from "enssdk/core";
+import { asInterpretedName } from "enssdk";
+import { graphql, omnigraph } from "enssdk/omnigraph";
+
+const client = createEnsNodeClient({ url: "https://api.alpha.ensnode.io" }).extend(omnigraph);
+
+// `$name: InterpretedName!` is a custom scalar; enssdk maps it to the branded InterpretedName type,
+// so the variable below must be a real InterpretedName — see "Primitives".
+const DomainByName = graphql(`
+  query DomainByName($name: InterpretedName!) {
+    domain(by: { name: $name }) {
+      __typename
+      canonical {
+        name {
+          beautified
+        }
+      }
+      owner {
+        address
+      }
+      resolve {
+        records {
+          addresses(coinTypes: [60]) {
+            address
+          }
+        }
+      }
+    }
+  }
+`);
+
+const result = await client.omnigraph.query({
+  query: DomainByName,
+  variables: { name: asInterpretedName("vitalik.eth") },
+});
+```
+
+The query result is `{ data?, errors? }` — see [Error handling](#error-handling--gotchas). `data` is typed exactly to your selection set.
+
+### Variables & the response shape
+
+- Pass `variables` typed to the document. If a document has no variables, `variables` is optional.
+- `signal?: AbortSignal` is accepted on `query(...)` for cancellation.
+- Custom scalars map to enssdk's branded types: `InterpretedName`, `Address` (→ `NormalizedAddress`), `Node`, `CoinType`, `BigInt` (serialized as `` `${bigint}` `` strings — deserialize yourself if you need real bigints), `JSON`, etc. So a `$name: InterpretedName!` variable will not accept a raw `string` — build it with `asInterpretedName`/`normalizeName`.
+
+### Fragments & narrowing
+
+Reuse selections with fragments, and narrow `data` safely with the gql.tada helpers `FragmentOf` / `readFragment` (re-exported from `enssdk/omnigraph`). `ResultOf` and `VariablesOf` are also re-exported for deriving types from a document.
+
+```typescript
+import { type FragmentOf, graphql, readFragment } from "enssdk/omnigraph";
+
+const DomainFragment = graphql(`
+  fragment DomainFragment on Domain {
+    __typename
+    canonical {
+      name {
+        beautified
+      }
+    }
+    owner {
+      address
+    }
+  }
+`);
+
+// compose: pass fragment dependencies as the second arg
+const Query = graphql(
+  `
+    query HelloWorld($name: InterpretedName!) {
+      domain(by: { name: $name }) {
+        ...DomainFragment
+        subdomains(first: 20) {
+          totalCount
+          edges {
+            node {
+              ...DomainFragment
+            }
+          }
+        }
+      }
+    }
+  `,
+  [DomainFragment],
+);
+
+// `readFragment` unmasks fragment data for type-safe access
+function formatDomain(data: FragmentOf<typeof DomainFragment>): string {
+  const domain = readFragment(DomainFragment, data);
+  const name = domain.canonical?.name.beautified ?? "<unnamed>";
+  return `${name} (${domain.__typename})`;
+}
+```
+
+For **unions** (e.g. `Registration`, `Domain` subtypes like `ENSv1Domain`/`ENSv2Domain`) select `__typename` and use inline fragments (`... on BaseRegistrarRegistration { … }`); gql.tada types each branch accordingly. For **connections**, walk `edges { node }`, read `pageInfo { hasNextPage endCursor }` / `totalCount`, and paginate with `first` + `after: <endCursor>` (cursor-based; no offset). The `omnigraph` skill has the full schema and copy-pasteable example queries — author there.
+
+## Primitives
+
+These have sharp edges; **use the SDK helpers, never hand-roll them** (never `toLowerCase()` a name, never `keccak256` a name yourself). Imported from the package root: `import { … } from "enssdk"`. The library uses **branded types** (`InterpretedName`, `LiteralName`, `InterpretedLabel`, `Beautified*`, `NormalizedAddress`, `Node`, `LabelHash`, …) so misuse is caught at compile time — the brand prevents passing, say, a `BeautifiedName` where an `InterpretedName` is required.
+
+### Normalization (ENSIP-15)
+
+```typescript
+import { normalizeName, isNormalizedName, normalizeLabel } from "enssdk";
+
+normalizeName("Vitalik.eth"); // → "vitalik.eth" (InterpretedName); throws if unnormalizable
+isNormalizedName("Vitalik.eth"); // → false (non-throwing check)
+normalizeLabel("vitalik"); // → InterpretedLabel; throws on '', on '.', or if unnormalizable
+```
+
+### namehash / labelhash
+
+```typescript
+import {
+  namehashInterpretedName,
+  labelhashInterpretedLabel,
+  asInterpretedName,
+  asInterpretedLabel,
+} from "enssdk";
+
+const node = namehashInterpretedName(asInterpretedName("vitalik.eth")); // → Node (the on-chain id)
+const labelHash = labelhashInterpretedLabel(asInterpretedLabel("vitalik")); // → LabelHash
+```
+
+- `namehashInterpretedName(InterpretedName): Node` — requires an already-interpreted name (call `asInterpretedName`/`normalizeName` first). Per the `base` skill, call the _result_ a **Node**, not a "namehash".
+- `labelhashInterpretedLabel(InterpretedLabel): LabelHash` — special-cases Encoded LabelHashes (`[hash]`). Use `labelhashLiteralLabel(LiteralLabel)` to hash a label's literal bytes with no encoded-labelhash detection.
+- Encoded LabelHashes: `encodeLabelHash`, `decodeEncodedLabelHash`, `isEncodedLabelHash`, `isLabelHash`.
+- `makeSubdomainNode(labelHash, node): Node` — one namehash step (child of a parent node).
+
+### Interpretation: literal ↔ interpreted
+
+The Omnigraph and on-chain data deal in **InterpretedName/InterpretedLabel** (a normalized name, or one whose unnormalizable labels are represented as Encoded LabelHashes). Use the interpretation helpers to convert user/literal input:
+
+```typescript
+import { asInterpretedName, literalNameToInterpretedName, asLiteralName } from "enssdk";
+
+asInterpretedName("vitalik.eth"); // validate+cast; throws if not already interpreted
+
+// coerce arbitrary user input → InterpretedName (normalizes labels by default)
+literalNameToInterpretedName(asLiteralName("Vitalik.eth")); // → "vitalik.eth"
+```
+
+`literalNameToInterpretedName(name, options?)` controls edge cases via `allowENSRootName`, `allowEncodedLabelHashes`, `coerceUnnormalizedLabelsToNormalizedLabels` (default `true`), `coerceUnnormalizableLabelsToEncodedLabelHashes` (default `false`). Related: `asInterpretedLabel`, `literalLabelToInterpretedLabel`, `interpretedNameToInterpretedLabels`, `isInterpretedName`/`isInterpretedLabel`.
+
+### Beautification (display only)
+
+```typescript
+import { beautifyInterpretedName } from "enssdk";
+
+beautifyInterpretedName(asInterpretedName("♾♾♾♾.eth")); // → "♾️♾️♾️♾️.eth" (BeautifiedName)
+```
+
+A `BeautifiedName`/`BeautifiedLabel` is for **presentation only**. It is intentionally _not_ an `InterpretedName` (the brand blocks it) — never use a beautified value as a lookup key, query variable, or navigation target. Keep the source `InterpretedName` for those. (`beautifyInterpretedLabel` does the same for a single label.)
+
+### Addresses
+
+```typescript
+import { toNormalizedAddress, isNormalizedAddress, asNormalizedAddress } from "enssdk";
+
+toNormalizedAddress("0xd8dA…6045"); // → lowercase NormalizedAddress; throws if not an EVM address
+isNormalizedAddress(x); // non-throwing guard
+asNormalizedAddress(x); // assert already-normalized; throws otherwise
+```
+
+The Omnigraph's `Address` scalar maps to `NormalizedAddress` (lowercase). Normalize before using an address as a query variable.
+
+### Coin types & constants
+
+`ETH_COIN_TYPE` (60), `evmChainIdToCoinType` / `coinTypeToEvmChainId` (ENSIP-9/11), and constants like `ENS_ROOT_NAME`, `ENS_ROOT_NODE`, `ETH_NODE` are exported from the root for record selection and traversal.
+
+## Error handling & gotchas
+
+- **GraphQL errors vs. transport errors are different paths.**
+  - A successful HTTP response returns `{ data?, errors? }`. **`query(...)` does not throw on GraphQL errors** — check `result.errors` yourself, and guard nullable fields (`result.data?.domain`):
+
+    ```typescript
+    const result = await client.omnigraph.query({ query, variables });
+    if (result.errors) throw new Error(JSON.stringify(result.errors));
+    if (!result.data?.domain) throw new Error("not found");
+    ```
+
+  - A non-2xx HTTP response **throws** an `Error` (`Omnigraph query failed: <status> …`). Notably an ENSNode instance returns **503** when it cannot serve a request faithfully (indexer not caught up to realtime, status unavailable, or the instance lacks the required plugins) — treat 503 as "temporarily unavailable / unsupported by this instance," retry or switch instances; it is not a malformed query.
+
+- **Primitive helpers throw on invalid input** (fail-fast): `normalizeName`, `asInterpretedName`, `toNormalizedAddress`, `decodeEncodedLabelHash`, etc. Use the `is*` guards (`isNormalizedName`, `isInterpretedName`, `isNormalizedAddress`, `isEncodedLabelHash`) when you need a non-throwing branch.
+- **Branded types are load-bearing.** A `string` will not satisfy an `InterpretedName`/`Address` variable — convert at the boundary (`asInterpretedName`, `toNormalizedAddress`). A `BeautifiedName` will not satisfy an `InterpretedName` either; that is deliberate.
+- **`BigInt` scalars arrive as strings** (`` `${bigint}` ``). Parse them if you need arithmetic.
+- **Re-run `gql.tada generate-output`** after upgrading `enssdk` or changing the schema reference, or document types will drift from the server.
+
+## Reporting
+
+Per the `base` skill: report the **result**, not the procedure. Surface only facts that change the user's understanding — an input was unnormalizable, a name resolves unexpectedly, an instance returned 503. Don't narrate normalizing, hashing, or field selection.

From f2e1d3cad7dac892444af25e7ec78b1aef38f9dc Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 11:56:34 -0500
Subject: [PATCH 05/10] checkpoint

---
 packages/ensskills/skills/enskit/SKILL.md | 2 +-
 packages/ensskills/skills/enssdk/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/ensskills/skills/enskit/SKILL.md b/packages/ensskills/skills/enskit/SKILL.md
index 5c13bae9c5..a885afaf80 100644
--- a/packages/ensskills/skills/enskit/SKILL.md
+++ b/packages/ensskills/skills/enskit/SKILL.md
@@ -43,7 +43,7 @@ import { omnigraph } from "enssdk/omnigraph";
 // Pick the ENSNode instance / namespace by URL. Use a NameHash-hosted instance
 // (https://ensnode.io/docs/hosted-instances) or your own.
 const client = createEnsNodeClient({
-  url: "https://api.v2-sepolia.ensnode.io",
+  url: "https://api.alpha.ensnode.io",
 }).extend(omnigraph);
 
 export function App() {
diff --git a/packages/ensskills/skills/enssdk/SKILL.md b/packages/ensskills/skills/enssdk/SKILL.md
index da90aa860a..76327b4487 100644
--- a/packages/ensskills/skills/enssdk/SKILL.md
+++ b/packages/ensskills/skills/enssdk/SKILL.md
@@ -128,7 +128,7 @@ const result = await client.omnigraph.query({
 });
 ```
 
-The query result is `{ data?, errors? }` — see [Error handling](#error-handling--gotchas). `data` is typed exactly to your selection set.
+The query result is `{ data?, errors? }` — see "Error handling & gotchas" below. `data` is typed exactly to your selection set.
 
 ### Variables & the response shape
 

From a6b45ba891d27ae586cba7f1d9df89fd05c9ba12 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 12:10:15 -0500
Subject: [PATCH 06/10] fix: unlink stray file before symlink; correct step-8
 metric names

---
 .agents/skills/ensindexer-perf-testing/SKILL.md | 5 +++--
 scripts/link-local-skills.mjs                   | 2 ++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/ensindexer-perf-testing/SKILL.md b/.agents/skills/ensindexer-perf-testing/SKILL.md
index a7869a7d75..c6fcfa4ab2 100644
--- a/.agents/skills/ensindexer-perf-testing/SKILL.md
+++ b/.agents/skills/ensindexer-perf-testing/SKILL.md
@@ -192,8 +192,9 @@ q 'ponder_indexing_function_duration_sum / ponder_indexing_function_duration_cou
 q 'ponder_indexing_function_duration_sum'                               # total ms wallclock
 q 'ponder_indexing_function_duration_count'                             # invocation count
 q 'histogram_quantile(0.95, sum by (event, le) (rate(ponder_indexing_function_duration_bucket[5m])))'
-q 'sum by (method) (rate(ponder_postgres_query_total[5m]))'             # PG QPS by method
-q 'sum by (chain_id) (rate(ponder_rpc_request_cache_hits[5m]))'         # RPC cache hits/s
+q 'sum by (method) (rate(ponder_indexing_store_queries_total[5m]))'     # store QPS by method
+q 'sum by (chain_id) (rate(ponder_indexing_rpc_requests_total[5m]))'    # RPC requests/s by chain
+q 'sum by (chain_id) (rate(ponder_indexing_rpc_prefetch_total[5m]))'    # RPC prefetch/s by chain
 ```
 
 Save each to `/tmp/perf-test/main-<label>-<thing>.json`. Wallclock is `end_epoch -
diff --git a/scripts/link-local-skills.mjs b/scripts/link-local-skills.mjs
index cc4c7fb77b..6863b512ea 100644
--- a/scripts/link-local-skills.mjs
+++ b/scripts/link-local-skills.mjs
@@ -32,6 +32,8 @@ for (const name of localSkills) {
     // missing or not a symlink: a real directory here is a personal skill — leave it
     try {
       if (lstatSync(path).isDirectory()) continue;
+      // a regular file here would make symlinkSync throw EEXIST — remove it first
+      unlinkSync(path);
     } catch {}
   }
   symlinkSync(desired, path);

From 85534954010b2bbac42ca40ddf79fce968518f68 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 12:19:17 -0500
Subject: [PATCH 07/10] docs: move enssdk/enskit skill announcement to
 docs/next

The integration-options page promotion of enssdk & enskit lives on docs/next
until those skill packages publish; the site deploys from main on merge.
---
 .../docs/docs/integrate/integration-options/ensskills.mdx     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx
index 501244604c..5b02f8859a 100644
--- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensskills.mdx
@@ -77,11 +77,11 @@ It detects your agents and writes the skills into each (`.claude/skills`, `.curs
 - **`ens-protocol`** — how the ENS protocol works at a conceptual level: the nametree, normalization, namehash/labelhash, registry/resolver/registrar, forward & reverse resolution, primary names, records, and ENS across chains. Vendor-neutral, intentionally stable, with pull-as-needed reference pages. The mental model the other skills build on.
 - **`omnigraph`** — the monolithic ENS skill. Teaches the unified ENSv1 + ENSv2 datamodel, resolution via `Domain.resolve` / `Account.resolve`, Relay pagination, a condensed schema reference, vetted example queries, and how to execute and explore queries with `enscli`.
 - **`enscli`** — running ENS lookups from the shell: the output contract, namespace/URL resolution, input hardening, and every command (Omnigraph queries, offline schema exploration, `namehash`/`labelhash`, ENSRainbow healing, indexing status).
-- **`enssdk`** — TypeScript integration: the typed Omnigraph client (gql.tada setup, fragments, union/connection narrowing) and the easy-to-get-wrong primitives (normalization, namehash/labelhash, interpretation/beautification, branded types).
-- **`enskit`** — React integration: `OmnigraphProvider` setup, `useOmnigraphQuery`, the preconfigured normalized cache, Relay pagination patterns, and name-display conventions.
 
 The following are reserved and ship as stubs today, fleshed out in upcoming releases:
 
+- **`enssdk`** — TypeScript integration with the typed Omnigraph client.
+- **`enskit`** — React integration (`useOmnigraphQuery`, cache directives, infinite pagination).
 - **`migrate-to-omnigraph`** — migrating from the legacy ENS Subgraph.
 - **`unigraph-sql`** — SQL over ENSDb for query shapes the Omnigraph doesn't express.
 

From bea5f7c542fb74bc8e75a6d5ae83a7cef71974cd Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 12:33:38 -0500
Subject: [PATCH 08/10] fix: ensskills example app

---
 examples/enskit-react-example/README.md      | 2 +-
 examples/enssdk-example/README.md            | 2 +-
 examples/ensskills-example/README.md         | 5 ++---
 examples/ensskills-example/package.json      | 4 ++--
 examples/omnigraph-graphql-example/README.md | 2 +-
 5 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/examples/enskit-react-example/README.md b/examples/enskit-react-example/README.md
index b8608a1201..b2e806ed7e 100644
--- a/examples/enskit-react-example/README.md
+++ b/examples/enskit-react-example/README.md
@@ -8,7 +8,7 @@ This app is hosted at [https://enskit-react-example.ensnode.io/](https://enskit-
 
 ## Usage (with NameHash Hosted Instance)
 
-> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.x`). If you query a different ENSNode version, you must match its ENSNode version with the same `enskit`/`enssdk` version.
+> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.2`). If you query a different ENSNode version, you must match its ENSNode version with the same `enskit`/`enssdk` version.
 
 ```sh
 # from the ENSNode monorepo root
diff --git a/examples/enssdk-example/README.md b/examples/enssdk-example/README.md
index 7708549f02..166580b8fe 100644
--- a/examples/enssdk-example/README.md
+++ b/examples/enssdk-example/README.md
@@ -6,7 +6,7 @@ Companion to the [enssdk integration guide](https://ensnode.io/docs/integrate/in
 
 ## Usage (with NameHash Hosted Instance)
 
-> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.x`). If you query a different ENSNode version, you must match its ENSNode version with the same `enskit`/`enssdk` version.
+> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.2`). If you query a different ENSNode version, you must match its ENSNode version with the same `enskit`/`enssdk` version.
 
 ```sh
 # from the ENSNode monorepo root
diff --git a/examples/ensskills-example/README.md b/examples/ensskills-example/README.md
index ec801446c7..369093f88c 100644
--- a/examples/ensskills-example/README.md
+++ b/examples/ensskills-example/README.md
@@ -3,8 +3,7 @@
 A minimal Node project for dogfooding the [`ensskills`](../../packages/ensskills) package — the
 versioned agent skills that teach AI coding agents the ENS Omnigraph.
 
-Unlike the published quickstart (which pins `ensskills` to an exact version), this example installs
-it from the workspace (`ensskills: workspace:*`) so you exercise whatever is on your current branch.
+> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.2`). If you query a different ENSNode version, you must match its ENSNode version with the same `enskit`/`enssdk` version.
 
 Refer to the [ensskills integration guide](https://ensnode.io/docs/integrate/integration-options/ensskills) to use `ensskills` in your own project.
 
@@ -18,7 +17,7 @@ Refer to the [ensskills integration guide](https://ensnode.io/docs/integrate/int
 - `--cwd .` (in `package.json`) keeps skills-npm from walking up to the monorepo root — without it,
   skills-npm detects `pnpm-workspace.yaml` and would symlink into the repo root's agent dirs.
 - `agents: ["claude-code"]` targets Claude Code. Drop it to auto-detect every agent you have installed.
-- `include: ["ensskills"]` pulls skills only from the workspace package.
+- `include: ["ensskills"]` pulls skills only from the `ensskills` package.
 
 ## Usage
 
diff --git a/examples/ensskills-example/package.json b/examples/ensskills-example/package.json
index e1dbabe361..df2cdc3e4b 100644
--- a/examples/ensskills-example/package.json
+++ b/examples/ensskills-example/package.json
@@ -8,8 +8,8 @@
     "prepare": "skills-npm --cwd ."
   },
   "devDependencies": {
-    "enscli": "workspace:*",
-    "ensskills": "workspace:*",
+    "enscli": "1.15.2",
+    "ensskills": "1.15.2",
     "skills-npm": "^1"
   }
 }
diff --git a/examples/omnigraph-graphql-example/README.md b/examples/omnigraph-graphql-example/README.md
index 0413d32f72..18eb571adb 100644
--- a/examples/omnigraph-graphql-example/README.md
+++ b/examples/omnigraph-graphql-example/README.md
@@ -8,7 +8,7 @@ Companion to the [ENS Omnigraph GraphQL API integration guide](https://ensnode.i
 
 ## Usage (with NameHash Hosted Instance)
 
-> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.x`). If you query a different ENSNode version, you may need to adjust the query format.
+> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.2`). If you query a different ENSNode version, you may need to adjust the query format.
 
 ```sh
 # from the ENSNode monorepo root

From 1ba603937b164b2aa99d71b794ce8b409b0096d1 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 12:42:57 -0500
Subject: [PATCH 09/10] fix: lockfile

---
 pnpm-lock.yaml | 77 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 73 insertions(+), 4 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c3c64ada02..f4157b1c23 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -916,11 +916,11 @@ importers:
   examples/ensskills-example:
     devDependencies:
       enscli:
-        specifier: workspace:*
-        version: link:../../packages/enscli
+        specifier: 1.15.2
+        version: 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
       ensskills:
-        specifier: workspace:*
-        version: link:../../packages/ensskills
+        specifier: 1.15.2
+        version: 1.15.2
       skills-npm:
         specifier: ^1
         version: 1.1.1
@@ -2150,6 +2150,21 @@ packages:
     peerDependencies:
       viem: ^2.9.2
 
+  '@ensnode/datasources@1.15.2':
+    resolution: {integrity: sha512-UHFHCAVysKRzR7sY5LOedwYuxZgCuNNAKFvtcqQopYJZ4Cxs5pOzGpXLFGKo0uRtFDaZmoBn53ZaAmPsZiAFMA==}
+    peerDependencies:
+      viem: ^2.50.3
+
+  '@ensnode/ensnode-sdk@1.15.2':
+    resolution: {integrity: sha512-GHFrTfxqpPDycfr/XTVDZCzqFl5kD/uoEUOO+7vuvac6od2Dv2IriPw7TQmm33Ov0VkDKBALe8txfmhUESrWrw==}
+    peerDependencies:
+      viem: ^2.50.3
+
+  '@ensnode/ensrainbow-sdk@1.15.2':
+    resolution: {integrity: sha512-yWiwxS60In7xXqh5h+6RNLpEBqYTJWSxRto12MUMNksM6+gxat04q3Rta6+CmJJLmn8N55AZ+eQ9aQ3dAYLc6w==}
+    peerDependencies:
+      viem: ^2.50.3
+
   '@envelop/core@5.3.2':
     resolution: {integrity: sha512-06Mu7fmyKzk09P2i2kHpGfItqLLgCq7uO5/nX4fc/iHMplWPNuAx4iYR+WXUQoFHDnP6EUbceQNQ5iyeMz9f3g==}
     engines: {node: '>=18.0.0'}
@@ -6777,6 +6792,10 @@ packages:
     resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
     engines: {node: '>=8.6'}
 
+  enscli@1.15.2:
+    resolution: {integrity: sha512-FoYQOqqIFhf+G/mZz1JNFSPxsUVPBhZz1BsjBFxyB+bCJGS/e6V0JVreBuASt7dxHuZRZh+sF/30/qxQxYQHVg==}
+    hasBin: true
+
   enskit@1.15.2:
     resolution: {integrity: sha512-61obMt+dpce/zqRfpSHlkwFrAi43PJhgZmsjRM7ZI42qccQKjDF+sDOjmdbvf7at1fmPJUATNJscHfb62jX6Xw==}
     peerDependencies:
@@ -6792,6 +6811,9 @@ packages:
       graphql: ^16
       viem: ^2
 
+  ensskills@1.15.2:
+    resolution: {integrity: sha512-NwBl3vUOg/5hv/HGPe5GIW1yqXl5uFQ3wA6uAgkvh9FLFTdlMk5sixhuynep24LupE8nOPbMeAqWCdBattqcmw==}
+
   entities@4.5.0:
     resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
     engines: {node: '>=0.12'}
@@ -11811,6 +11833,38 @@ snapshots:
       - typescript
       - zod
 
+  '@ensnode/datasources@1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))':
+    dependencies:
+      '@ponder/utils': 0.2.18(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      enssdk: 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      viem: 2.50.3(typescript@5.9.3)(zod@4.3.6)
+    transitivePeerDependencies:
+      - gql.tada
+      - graphql
+      - typescript
+
+  '@ensnode/ensnode-sdk@1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))':
+    dependencies:
+      '@ensdomains/address-encoder': 1.1.4
+      '@ensnode/datasources': 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      caip: 1.1.1
+      date-fns: 4.1.0
+      enssdk: 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      viem: 2.50.3(typescript@5.9.3)(zod@4.3.6)
+      zod: 4.3.6
+    transitivePeerDependencies:
+      - gql.tada
+      - graphql
+      - typescript
+
+  '@ensnode/ensrainbow-sdk@1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))':
+    dependencies:
+      enssdk: 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      viem: 2.50.3(typescript@5.9.3)(zod@4.3.6)
+    transitivePeerDependencies:
+      - gql.tada
+      - graphql
+
   '@envelop/core@5.3.2':
     dependencies:
       '@envelop/instrumentation': 1.0.0
@@ -16783,6 +16837,19 @@ snapshots:
       ansi-colors: 4.1.3
       strip-ansi: 6.0.1
 
+  enscli@1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6)):
+    dependencies:
+      '@ensnode/datasources': 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      '@ensnode/ensnode-sdk': 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(typescript@5.9.3)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      '@ensnode/ensrainbow-sdk': 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      citty: 0.1.6
+      enssdk: 1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6))
+      graphql: 16.11.0
+    transitivePeerDependencies:
+      - gql.tada
+      - typescript
+      - viem
+
   enskit@1.15.2(gql.tada@1.9.1(graphql@16.11.0)(typescript@5.9.3))(graphql@16.11.0)(react@19.2.1)(viem@2.50.3(typescript@5.9.3)(zod@4.3.6)):
     dependencies:
       '@urql/core': 6.0.1(graphql@16.11.0)
@@ -16803,6 +16870,8 @@ snapshots:
       graphql: 16.11.0
       viem: 2.50.3(typescript@5.9.3)(zod@4.3.6)
 
+  ensskills@1.15.2: {}
+
   entities@4.5.0: {}
 
   entities@6.0.1: {}

From 2944ef6b3ecb053b710101683ab07b926fc27c71 Mon Sep 17 00:00:00 2001
From: shrugs <mattgcondon@gmail.com>
Date: Thu, 11 Jun 2026 16:29:20 -0500
Subject: [PATCH 10/10] fix: bot review notes (link-local-skills error
 handling, comments, example readme)

---
 examples/ensskills-example/README.md |  2 +-
 scripts/link-local-skills.mjs        | 15 ++++++++++-----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/examples/ensskills-example/README.md b/examples/ensskills-example/README.md
index 369093f88c..03467f3bdc 100644
--- a/examples/ensskills-example/README.md
+++ b/examples/ensskills-example/README.md
@@ -3,7 +3,7 @@
 A minimal Node project for dogfooding the [`ensskills`](../../packages/ensskills) package — the
 versioned agent skills that teach AI coding agents the ENS Omnigraph.
 
-> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.2`). If you query a different ENSNode version, you must match its ENSNode version with the same `enskit`/`enssdk` version.
+> **Schema version:** This example tracks the NameHash-hosted instances' version (`1.15.2`). If you query a different ENSNode version, install the matching `ensskills` version.
 
 Refer to the [ensskills integration guide](https://ensnode.io/docs/integrate/integration-options/ensskills) to use `ensskills` in your own project.
 
diff --git a/scripts/link-local-skills.mjs b/scripts/link-local-skills.mjs
index 6863b512ea..6576abfc1d 100644
--- a/scripts/link-local-skills.mjs
+++ b/scripts/link-local-skills.mjs
@@ -13,7 +13,7 @@ mkdirSync(target, { recursive: true });
 const isLocalSkill = (name) => !name.startsWith("npm-") && !name.startsWith(".");
 const localSkills = readdirSync(source).filter(isLocalSkill);
 
-// drop symlinks into .agents/skills whose canonical skill no longer exists
+// drop symlinks in .claude/skills that point into .agents/skills whose canonical skill no longer exists
 for (const name of readdirSync(target)) {
   if (!isLocalSkill(name)) continue;
   const path = join(target, name);
@@ -30,11 +30,16 @@ for (const name of localSkills) {
     unlinkSync(path);
   } catch {
     // missing or not a symlink: a real directory here is a personal skill — leave it
+    let stat;
     try {
-      if (lstatSync(path).isDirectory()) continue;
-      // a regular file here would make symlinkSync throw EEXIST — remove it first
-      unlinkSync(path);
-    } catch {}
+      stat = lstatSync(path);
+    } catch {
+      stat = null; // nothing here; symlinkSync below will create it
+    }
+    if (stat?.isDirectory()) continue;
+    // a regular file here would make symlinkSync throw EEXIST — remove it first
+    // (let an unlink failure escape rather than mask it as a downstream EEXIST)
+    if (stat) unlinkSync(path);
   }
   symlinkSync(desired, path);
   console.log(`linked .claude/skills/${name} -> ${desired}`);