diff -r 69f1b9b7ebe2 -r e1d35e2fb4d4 .claude-plugin/plugin.json
--- a/.claude-plugin/plugin.json	Sun May 03 16:25:38 2026 -0500
+++ b/.claude-plugin/plugin.json	Mon May 04 16:49:59 2026 -0500
@@ -1,6 +1,6 @@
 {
   "name": "isurus-hg",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Mercurial fluency for Claude Code, with an Isurus-conventions overlay and a hook that prevents accidental git use in hg repos.",
   "author": {
     "name": "Chris Tusa",
diff -r 69f1b9b7ebe2 -r e1d35e2fb4d4 README.md
--- a/README.md	Sun May 03 16:25:38 2026 -0500
+++ b/README.md	Mon May 04 16:49:59 2026 -0500
@@ -19,25 +19,56 @@
 
 ## Install
 
-Until the plugin is published to a marketplace, install via a path entry in `~/.claude/settings.json`:
+Two supported mechanisms, depending on whether you want the plugin loaded for one session or persistently across sessions.
+
+### Option 1 — `--plugin-dir` flag (session-only, recommended for development and testing)
 
-```json
-{
-  "plugins": {
-    "isurus-hg": {
-      "path": "/absolute/path/to/isurus-claude-plugin"
-    }
-  }
-}
+Launch Claude Code with the plugin directory as an argument:
+
+```sh
+claude --plugin-dir /absolute/path/to/isurus-claude-plugin
 ```
 
-Then restart Claude Code. The skills become available; the hook is registered automatically via `hooks/hooks.json`.
+The plugin is loaded for that session only. Repeat the flag to load multiple plugins. Takes precedence over installed marketplace plugins, which is what you want while iterating on the plugin itself.
+
+### Option 2 — local marketplace (persistent across sessions)
+
+If you want the plugin to load every time Claude Code starts, register it through a local marketplace.
+
+1. Create a `marketplace.json` in any parent directory of the plugin. For this repo's recommended layout, place it at `<parent>/.claude-plugin/marketplace.json`:
+
+   ```json
+   {
+     "name": "local-isurus",
+     "owner": { "name": "Your Name" },
+     "plugins": [
+       {
+         "name": "isurus-hg",
+         "source": "./isurus-claude-plugin",
+         "description": "Mercurial fluency for Claude Code, with an Isurus-conventions overlay."
+       }
+     ]
+   }
+   ```
+
+   `source` is relative to the marketplace.json's directory.
+
+2. Register the marketplace and install the plugin from inside Claude Code:
+
+   ```
+   /plugin marketplace add /absolute/path/to/parent
+   /plugin install isurus-hg@local-isurus
+   ```
+
+The skills become available and 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+.
 
+> **Note for v0.1.0 users:** earlier README revisions described an undocumented `"plugins": { ... }` block in `~/.claude/settings.json`. That block is not a supported Claude Code feature and is silently ignored. Use one of the two mechanisms above instead.
+
 ## Hook behavior
 
 The hook intercepts `Bash` tool calls. Decision tree:
diff -r 69f1b9b7ebe2 -r e1d35e2fb4d4 docs/superpowers/plans/2026-05-02-isurus-hg-plugin.md
--- a/docs/superpowers/plans/2026-05-02-isurus-hg-plugin.md	Sun May 03 16:25:38 2026 -0500
+++ b/docs/superpowers/plans/2026-05-02-isurus-hg-plugin.md	Mon May 04 16:49:59 2026 -0500
@@ -1977,25 +1977,56 @@
 
 ## 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"
-    }
-  }
-}
+Two supported mechanisms, depending on whether you want the plugin loaded for one session or persistently across sessions.
+
+### Option 1 — `--plugin-dir` flag (session-only, recommended for development and testing)
+
+Launch Claude Code with the plugin directory as an argument:
+
+```sh
+claude --plugin-dir /absolute/path/to/isurus-claude-plugin
 ```
 
-Then restart Claude Code. The skills become available; the hook is registered automatically via `hooks/hooks.json`.
+The plugin is loaded for that session only. Repeat the flag to load multiple plugins. Takes precedence over installed marketplace plugins, which is what you want while iterating on the plugin itself.
+
+### Option 2 — local marketplace (persistent across sessions)
+
+If you want the plugin to load every time Claude Code starts, register it through a local marketplace.
+
+1. Create a `marketplace.json` in any parent directory of the plugin. For this repo's recommended layout, place it at `<parent>/.claude-plugin/marketplace.json`:
+
+   ```json
+   {
+     "name": "local-isurus",
+     "owner": { "name": "Your Name" },
+     "plugins": [
+       {
+         "name": "isurus-hg",
+         "source": "./isurus-claude-plugin",
+         "description": "Mercurial fluency for Claude Code, with an Isurus-conventions overlay."
+       }
+     ]
+   }
+   ```
+
+   `source` is relative to the marketplace.json's directory.
+
+2. Register the marketplace and install the plugin from inside Claude Code:
+
+   ```
+   /plugin marketplace add /absolute/path/to/parent
+   /plugin install isurus-hg@local-isurus
+   ```
+
+The skills become available and 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+.
 
+> **Note for v0.1.0 users:** earlier README revisions described an undocumented `"plugins": { ... }` block in `~/.claude/settings.json`. That block is not a supported Claude Code feature and is silently ignored. Use one of the two mechanisms above instead.
+
 ## Hook behavior
 
 The hook intercepts `Bash` tool calls. Decision tree:
@@ -2229,19 +2260,13 @@
 
 - [ ] **Step 7: Install locally and smoke-test**
 
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "plugins": {
-    "isurus-hg": {
-      "path": "/home/ctusa/repos/isurus-project/isurus-claude-plugin"
-    }
-  }
-}
+Launch a Claude Code session with the plugin loaded via the `--plugin-dir` flag (session-only; preferred for the smoke test):
+
+```sh
+claude --plugin-dir /home/ctusa/repos/isurus-project/isurus-claude-plugin
 ```
 
-Restart Claude Code, then in a Claude session:
+In the session:
 
 1. `cd` into `~/repos/isurus-project/isurus`.
 2. Ask: "Run `git status` here." → confirm the hook blocks.
@@ -2249,6 +2274,8 @@
 
 If both work, v0.1.0 is ready for the dogfooding period described in the spec's rollout section.
 
+> **Note:** earlier revisions of this plan described an `~/.claude/settings.json` `"plugins"` block as the install method. That key is not a supported Claude Code feature and is silently ignored. The `--plugin-dir` flag (above) and a local marketplace are the two verified mechanisms — see the spec's "Install for v1" section for the local-marketplace recipe.
+
 - [ ] **Step 8: Final commit-log review**
 
 ```bash
diff -r 69f1b9b7ebe2 -r e1d35e2fb4d4 docs/superpowers/specs/2026-05-01-isurus-hg-plugin-design.md
--- a/docs/superpowers/specs/2026-05-01-isurus-hg-plugin-design.md	Sun May 03 16:25:38 2026 -0500
+++ b/docs/superpowers/specs/2026-05-01-isurus-hg-plugin-design.md	Mon May 04 16:49:59 2026 -0500
@@ -197,7 +197,7 @@
 
 Three sections:
 1. **What it does** — one paragraph + bulleted list of the 6 skills and the hook.
-2. **Install** — local path entry for now (`~/.claude/settings.json` plugin path), with a "marketplace coming soon" note for after the git mirror is set up.
+2. **Install** — `--plugin-dir` flag for development/testing, plus a local-marketplace recipe for persistent use, with a "remote marketplace coming soon" note for after the git mirror is set up.
 3. **Hooks behavior** — one paragraph explaining the git-blocking hook so a user understands why their `git status` got rejected.
 
 No `CHANGELOG`, `CONTRIBUTING`, or `SECURITY` files for v1.
@@ -261,21 +261,46 @@
 
 ### Install for v1 (local development)
 
-Until the plugin is published, install via a path entry in `~/.claude/settings.json`:
+> **Correction (post-v0.1.0):** earlier revisions of this spec described an `~/.claude/settings.json` `"plugins"` block as the install mechanism. That key is not a documented Claude Code feature and is silently ignored. The verified mechanisms below replace it.
+
+Two supported mechanisms.
+
+**1. Session-only (recommended for development and the manual-scenarios walk-through):**
+
+```sh
+claude --plugin-dir /home/ctusa/repos/isurus-project/isurus-claude-plugin
+```
+
+Loads the plugin for that session. Repeat the flag to load multiple plugins. Takes precedence over installed marketplace plugins.
+
+**2. Persistent (recommended once dogfooding is stable):** create a local marketplace.
+
+Place a `marketplace.json` in any parent directory of the plugin checkout (suggested: `<parent>/.claude-plugin/marketplace.json`):
 
 ```json
 {
-  "plugins": {
-    "isurus-hg": {
-      "path": "/home/ctusa/repos/isurus-project/isurus-claude-plugin"
+  "name": "local-isurus",
+  "owner": { "name": "Chris Tusa" },
+  "plugins": [
+    {
+      "name": "isurus-hg",
+      "source": "./isurus-claude-plugin",
+      "description": "Mercurial fluency for Claude Code, with an Isurus-conventions overlay."
     }
-  }
+  ]
 }
 ```
 
-Restart Claude Code. The 6 skills become available; the hook fires on `Bash` tool calls.
+Then from inside Claude Code:
 
-For other Leafscale devs (once dogfooding is solid): same path-entry pattern with their checkout location, or — when the git mirror is set up — install via the marketplace mechanism.
+```
+/plugin marketplace add /home/ctusa/repos/isurus-project
+/plugin install isurus-hg@local-isurus
+```
+
+Either mechanism activates the 6 skills and registers the hook on `Bash` tool calls.
+
+For other Leafscale devs (once dogfooding is solid): use Option 2 with their own checkout path, or — when the git mirror is set up — point a marketplace at the published git URL instead of a local path.
 
 ### Initial dogfooding plan