October 20, 2026 Production Release

.agents/skills/react-doctor/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: react-doctor
+description: Use when finishing a feature, fixing a bug, before committing React code, or when the user types `/doctor`, asks to scan, triage, or clean up React diagnostics. Covers lint, accessibility, bundle size, architecture. Includes a regression check and a full local-triage workflow that fetches the canonical playbook.
+version: "1.2.0"
+---
+
+# React Doctor
+
+Scans React codebases for security, performance, correctness, and architecture issues. Outputs a 0–100 health score.
+
+## After making React code changes:
+
+Run `npx react-doctor@latest --verbose --scope changed` and check the score did not regress.
+
+If the score dropped, fix the regressions before committing.
+
+## For general cleanup or code improvement:
+
+Run `npx react-doctor@latest --verbose` (the default `--scope full`) to scan the full codebase. Fix issues by severity — errors first, then warnings.
+
+## For a focused UI design audit:
+
+Run `npx react-doctor@latest design --verbose`. This selects only design-tagged UI composition, typography, interaction, accessibility, and motion rules, including focused rules that remain opt-in during a general health scan.
+
+## /doctor — full local triage workflow
+
+When the user types `/doctor`, says "run react doctor", or asks for a full triage / cleanup pass (not just a regression check), fetch the canonical local-triage playbook and follow every step in it:
+
+```bash
+curl --fail --silent --show-error \
+  --header 'Cache-Control: no-cache' \
+  https://www.react.doctor/prompts/react-doctor-agent.md
+```
+
+The playbook is the single source of truth — a scan → filter → triage → fix → validate loop that edits the working tree directly (never commits, never opens PRs). Updating the prompt at its source updates every agent on its next fetch — no skill reinstall needed.
+
+Pair it with the matching per-rule prompts at `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md` (fetched on demand inside the playbook) so each fix uses the canonical, reviewer-tested recipe.
+
+## Configuring or explaining rules
+
+When the user wants to understand a rule, disagrees with one, or wants to disable / tune which rules run (not fix code), read [references/explain.md](references/explain.md) and follow it. Start with `npx react-doctor@latest rules explain <rule>`, then apply the narrowest control via `npx react-doctor@latest rules disable|set|category|ignore-tag …`, which edits your `doctor.config.*` (or `package.json#reactDoctor`).
+
+## Command
+
+```bash
+npx react-doctor@latest --verbose --scope changed
+```
+
+| Flag              | Purpose                                                          |
+| ----------------- | ---------------------------------------------------------------- |
+| `.`               | Scan current directory                                           |
+| `--verbose`       | Show affected files and line numbers per rule                    |
+| `--scope changed` | Only report issues introduced vs the base branch (default: full) |
+| `--scope lines`   | Only report issues on the changed lines                          |
+| `--score`         | Output only the numeric score                                    |
+| `design`          | Run only the focused UI design diagnostics                       |

.agents/skills/react-doctor/references/explain.md

@@ -0,0 +1,73 @@
+# Explaining and configuring rules
+
+Explain React Doctor rules and edit `doctor.config.*` safely. Use this when a user
+wants to understand a rule or change which rules run — not for fixing diagnostics
+(that is the main `react-doctor` skill / `/doctor`).
+
+Triggers: "why did this rule fire", "I disagree with this rule", "turn this rule off",
+"stop flagging X", "too noisy", "disable design rules".
+
+## Workflow
+
+1. Identify the rule key from the diagnostic (e.g. `react-doctor/no-array-index-as-key`).
+2. Explain it before changing anything:
+
+```bash
+npx react-doctor@latest rules explain react-doctor/no-array-index-as-key
+```
+
+3. Pick the narrowest control that matches the user's intent (see decision guide).
+4. Apply it with a `rules` subcommand (edits your `doctor.config.*` or `package.json#reactDoctor` in place, preserving other fields and formatting).
+5. Validate the change did what they wanted:
+
+```bash
+npx react-doctor@latest --verbose --diff
+```
+
+## Commands
+
+```bash
+npx react-doctor@latest rules list                         # every rule + its effective severity
+npx react-doctor@latest rules list --configured            # only what your config changed
+npx react-doctor@latest rules list --category Performance   # filter by category
+npx react-doctor@latest rules explain <rule>               # why it matters + how to configure
+npx react-doctor@latest rules disable <rule>               # rule never runs
+npx react-doctor@latest rules enable <rule>                # turn back on at its recommended severity
+npx react-doctor@latest rules set <rule> warn              # off | warn | error
+npx react-doctor@latest rules category "React Native" off   # whole category
+npx react-doctor@latest rules ignore-tag design            # skip a rule family (design, test-noise, …)
+npx react-doctor@latest rules unignore-tag design
+```
+
+Rule references accept the full key (`react-doctor/no-danger`), the bare id (`no-danger`), or a legacy key (`react/no-danger`).
+
+## Decision guide
+
+Match the control to the intent — prefer the narrowest one:
+
+- **User disagrees with one rule / it's a false positive for them** → `rules disable <rule>` (sets `rules.<key> = "off"`; the rule stops running everywhere). This is the default for "I don't want this rule".
+- **Rule is fine but wrong severity** → `rules set <rule> warn` or `rules set <rule> error`.
+- **A disabled-by-default rule they want on** → `rules enable <rule>`.
+- **A whole area is unwanted** (e.g. all React Native rules) → `rules category "<Category>" off`.
+- **A behavioral family is noisy** (`design`, `test-noise`, `migration-hint`) → `rules ignore-tag <tag>`.
+- **Keep it locally but hide from PR comment / score / CI gate only** → do NOT disable. Edit `surfaces` in your config (`surfaces.prComment.excludeRules`, `surfaces.score.excludeTags`, `surfaces.ciFailure.excludeCategories`). The rule still shows in local `cli` output.
+- **Restore test or story findings to production health** → set `surfaces.score.includeFileContexts` or `surfaces.ciFailure.includeFileContexts` to `["test"]`, `["story"]`, or both. Other surface exclusions still apply.
+
+How the layers combine: `ignore.tags` disables every rule carrying that tag **before** linting, so a tagged rule stays off even if `rules`/`categories` set it to `warn`/`error` (a rule-level override cannot re-enable a tag-ignored rule). For rules that aren't tag-disabled, `rules` overrides `categories` overrides the rule's default. `surfaces` is visibility-only and never changes whether a rule runs.
+
+## Config shape
+
+Config lives in `doctor.config.ts` (or `.js`/`.mjs`/`.cjs`/`.json`/`.jsonc`), or the `reactDoctor` key in `package.json`. The `rules` commands edit whichever exists — TS/JS edits preserve formatting (via magicast) — and create `doctor.config.json` when none does, stamping `$schema`:
+
+```ts
+// doctor.config.ts
+export default {
+  rules: { "react-doctor/no-array-index-as-key": "off" },
+  categories: { "React Native": "warn" },
+  ignore: { tags: ["design"] },
+};
+```
+
+## Educating the user
+
+When explaining a rule, lead with the "Why it matters" guidance from `rules explain` and, when they want depth, the per-rule recipe at `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md`. Only after they understand it should you offer to disable it — many "bad" rules are catching real issues.

.changeset/README.md

@@ -0,0 +1,5 @@
+# Changesets
+
+OWS publishable packages (`@1shotapi/ows-*`) are versioned independently via [Changesets](https://github.com/changesets/changesets).
+
+Example apps are excluded. Maintainers: `npm run changeset` → `npm run version-packages` → `npm run release`.

.changeset/config.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@1shotapi/ows-onchain",
+    "@1shotapi/ows-example-general-wallet",
+    "@1shotapi/ows-example-host",
+    "@1shotapi/ows-example-credential-issuer",
+    "@1shotapi/ows-example-credential-verifier"
+  ]
+}

.cursor/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "postToolUse": [
+      {
+        "command": "node .cursor/hooks/react-doctor.mjs",
+        "matcher": "Write|Edit|MultiEdit|ApplyPatch",
+        "timeout": 120
+      }
+    ]
+  }
+}

.cursor/hooks/react-doctor.mjs

@@ -0,0 +1,153 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// --verbose scans on large diffs can exceed spawnSync's 1 MiB default.
+const SPAWN_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+
+const EDIT_TOOL_NAMES = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'ApplyPatch']);
+
+const readFileOrEmpty = (filePath) => {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * Consume hook JSON from stdin without `readFileSync(0)`, which blocks until
+ * EOF and can hang the hook when stdin is not a ready pipe.
+ */
+const readStdin = async () => {
+  if (process.stdin.isTTY) {
+    return '';
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+const hookEventName = (input) =>
+  input.hook_event_name || input.eventName || input.event_name;
+
+const shouldScan = (input) => {
+  const eventName = hookEventName(input);
+  if (eventName === 'PostToolBatch') {
+    const toolCalls = Array.isArray(input.tool_calls) ? input.tool_calls : [];
+    return toolCalls.some((toolCall) => EDIT_TOOL_NAMES.has(toolCall.tool_name));
+  }
+  const toolName = input.tool_name || input.toolName || input.tool;
+  // hooks.json matcher already limits invocation. If the payload omits toolName,
+  // scan conservatively rather than silently skipping. If toolName is present
+  // but not an edit tool, skip.
+  if (toolName == null || toolName === '') {
+    return true;
+  }
+  return EDIT_TOOL_NAMES.has(toolName);
+};
+
+const runReactDoctor = (outputPath) => {
+  // Each candidate is a single shell command string (not an args array):
+  // `shell: true` is required to run the Windows `.cmd` shims, and an args
+  // array with `shell: true` trips Node's DEP0190. A missing command exits
+  // 127 via a POSIX shell (no ENOENT error) and 9009 via cmd.exe, so fall
+  // through on those. The local bin is probed with existsSync (its `./`
+  // prefix form is not runnable by cmd.exe at all). Returns `null` when no
+  // runner is available (distinct from exit 0 = clean scan).
+  const localBin = process.platform === 'win32'
+    ? 'node_modules\\.bin\\react-doctor.cmd'
+    : './node_modules/.bin/react-doctor';
+  const commands = [
+    ...(existsSync(localBin)
+      ? [localBin + ' --verbose --scope changed --blocking warning --no-score']
+      : []),
+    'react-doctor --verbose --scope changed --blocking warning --no-score',
+    'pnpm dlx react-doctor@latest --verbose --scope changed --blocking warning --no-score',
+    'npx --yes react-doctor@latest --verbose --scope changed --blocking warning --no-score',
+  ];
+
+  for (const command of commands) {
+    const result = spawnSync(command, { encoding: 'utf8', shell: true, maxBuffer: SPAWN_MAX_BUFFER_BYTES });
+    if (result.error?.code === 'ENOENT' || result.status === 127 || result.status === 9009) continue;
+    try {
+      writeFileSync(outputPath, (result.stdout || '') + (result.stderr || ''));
+    } catch {}
+    return result.status ?? 1;
+  }
+
+  return null;
+};
+
+const cleanup = (...paths) => {
+  for (const path of paths) {
+    try { unlinkSync(path); } catch {}
+  }
+};
+
+const fail = (error) => {
+  const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  // stderr only — stdout is reserved for hook JSON the agent parses.
+  console.error(`[react-doctor hook] ${message}`);
+  process.exit(1);
+};
+
+const main = async () => {
+  let input;
+  try {
+    input = JSON.parse((await readStdin()) || '{}');
+  } catch (error) {
+    fail(error instanceof Error ? error : new Error(`invalid hook stdin JSON: ${String(error)}`));
+  }
+
+  if (!shouldScan(input)) {
+    process.exit(0);
+  }
+
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || join(__dirname, '../..');
+  const outputPath = join(tmpdir(), `react-doctor-agent-hook-output-${process.pid}.txt`);
+
+  try {
+    process.chdir(projectRoot);
+  } catch (error) {
+    fail(error);
+  }
+
+  const scanResult = runReactDoctor(outputPath);
+  if (scanResult === null) {
+    // Soft skip: do not block the agent, but do not pretend a clean scan ran.
+    cleanup(outputPath);
+    console.error('[react-doctor hook] react-doctor not found; skipping scan');
+    process.exit(0);
+  }
+  if (scanResult === 0) {
+    cleanup(outputPath);
+    process.exit(0);
+  }
+
+  // Scan findings are reported via stdout JSON below. Missing scan output
+  // (e.g. unwritable tmpdir) is a soft skip — not a hook runtime failure.
+  const scanOutput = readFileOrEmpty(outputPath).trim();
+  cleanup(outputPath);
+
+  if (!scanOutput) {
+    process.exit(0);
+  }
+
+  const message = `React Doctor found issues in the changed files. Review this output and fix the regressions before finishing. For confirmed issues that cannot be fixed now, create GitHub issues with the rule, file/line, confidence, impact, and proposed fix.\n\n${scanOutput}`;
+
+  if (hookEventName(input) === 'PostToolBatch') {
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolBatch', additionalContext: message } }));
+  } else {
+    console.log(JSON.stringify({ additional_context: message }));
+  }
+};
+
+main().catch(fail);

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.sol]
+indent_size = 4

.env.example

@@ -0,0 +1,26 @@
+# Repo root — copy to .env (gitignored)
+
+# ngrok authtoken for `npm run dev:general-wallet`
+# https://dashboard.ngrok.com/get-started/your-authtoken
+NGROK_AUTHTOKEN=
+
+# Optional: reserved ngrok domain (stable URL instead of random subdomain)
+# Find yours at https://dashboard.ngrok.com/domains — e.g. immune-sheep-light.ngrok-free.app
+NGROK_DOMAIN=
+
+# Optional: full Branding Layer iframe URL for host / credential-issuer / credential-verifier.
+# Overrides NGROK_DOMAIN and the localhost default — useful when testing another wallet repo.
+# Example: WALLET_IFRAME_URL=https://immune-sheep-light.ngrok-free.app/wallet/
+# WALLET_IFRAME_URL=
+
+# Optional: HTTPS for Host Layer examples (host, credential-issuer, credential-verifier).
+# Required when embedding HTTPS wallet iframes for passkeys (secure-context ancestor chain).
+# If examples/host/certs/dev-*.pem exist, HTTPS is enabled for all three automatically.
+# HOST_HTTPS=1
+# HOST_SSL_CERT=examples/host/certs/dev-cert.pem
+# HOST_SSL_KEY=examples/host/certs/dev-key.pem
+# Generate: mkcert -install && mkcert -cert-file examples/host/certs/dev-cert.pem -key-file examples/host/certs/dev-key.pem ows-host.com ows-issuer.com ows-verifier.com localhost 127.0.0.1
+
+# Optional: public origins for credential demos (defaults shown)
+# ISSUER_ORIGIN=https://ows-issuer.com:5175
+# VERIFIER_ORIGIN=https://ows-verifier.com:5176

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test