diff -r 395808495a8a -r f97dbfc1a63f README.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Sun May 03 16:22:27 2026 -0500
@@ -0,0 +1,76 @@
+# isurus-hg
+
+A Claude Code plugin that teaches Claude to work fluently in **Mercurial 7.x**, with an **Isurus-conventions overlay** for the Isurus forge codebase, and a **PreToolUse hook** that prevents accidental `git` commands inside `.hg` repositories.
+
+Built because Claude's general competence is uneven on Mercurial — bookmarks, named branches, phases, and Isurus's house conventions are easy to get wrong without explicit guidance — and because "never use `git`" is more reliable as a hook than as a memorized instruction.
+
+## What it includes
+
+**Skills** (auto-loaded by Claude when relevant):
+- `mercurial-basics` — `status`, `diff`, `log`, `add`, `commit`, message format, phase awareness.
+- `mercurial-bookmarks-and-prs` — bookmark workflow as the unit of feature work and PRs.
+- `mercurial-sync-and-merge` — pull, update, multiple heads, merge, conflict resolution.
+- `mercurial-history-rewriting` — `amend`, `uncommit`, the draft-vs-public phase rule, recovery patterns.
+- `mercurial-finishing-a-branch` — pre-PR checklist + push flow (the hg counterpart to superpowers' `finishing-a-development-branch`).
+- `isurus-conventions` — overlay skill that activates in the Isurus repo; supplies project-specific values (URLs, branches, `make` targets) that the generic skills' procedures plug into.
+
+**Hook:**
+- `block-git-in-hg.sh` — fires on every `Bash` tool call. If the command starts with `git` and the working directory is inside an `.hg` repository (and not inside a closer `.git` repo or a bare git repo), the call is blocked with a message suggesting the `hg` equivalent.
+
+## Install
+
+Until the plugin is published to a marketplace, install via a path entry in `~/.claude/settings.json`:
+
+```json
+{
+  "plugins": {
+    "isurus-hg": {
+      "path": "/absolute/path/to/isurus-claude-plugin"
+    }
+  }
+}
+```
+
+Then restart Claude Code. The skills become available; the hook is registered automatically via `hooks/hooks.json`.
+
+**Requirements:**
+- Mercurial 7.x (the skills assume modern command behavior).
+- `jq` on `PATH` (the hook uses it to parse tool-call JSON; if missing, the hook fails open with a warning).
+- Bash 4+.
+
+## Hook behavior
+
+The hook intercepts `Bash` tool calls. Decision tree:
+
+1. Command doesn't start with `git` → allow.
+2. Working directory is a bare git repository (contains `HEAD`, `refs/`, `objects/` at top level) → allow.
+3. Closest VCS ancestor is `.git/` → allow.
+4. Closest VCS ancestor is `.hg/` → **block** with exit code 2 and a stderr message suggesting the `hg` equivalent.
+5. No VCS context → allow (e.g., `git --version` outside any repo).
+
+Documented limitation: only the leading token of the command is inspected, so `cd /tmp && git init` from inside an `.hg` repo is allowed (intended escape valve). Override the hook by commenting out the entry in `hooks/hooks.json`.
+
+## Development
+
+This plugin is developed in **Mercurial** (eating its own dogfood). To work on it:
+
+```sh
+hg clone <repo-url>
+cd isurus-claude-plugin
+
+# Validate skills
+./scripts/check-skills.sh
+
+# Run hook tests
+./hooks/test/run.sh
+
+# Walk manual scenarios after meaningful changes
+cat tests/MANUAL.md
+```
+
+Design spec: `docs/superpowers/specs/2026-05-01-isurus-hg-plugin-design.md`
+Implementation plan: `docs/superpowers/plans/2026-05-02-isurus-hg-plugin.md`
+
+## License
+
+MIT — see [LICENSE](LICENSE).