diff --git a/README.md b/README.md
index cc79a2b..69638e6 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,8 @@ Lecture repositories opt in by checking the following into their `.claude/settin
 /plugin install audit@quantecon
 ```
 
+Those are slash commands in a Claude Code session; **restart the session afterwards**, since plugins register at startup. `/plugin` is a terminal-CLI built-in, so in the VS Code extension or the web app use the equivalent `claude plugin …` CLI commands instead — see [using-skills § Setup](docs/using-skills.md#setup).
+
 ### CI (GitHub Actions)
 
 The official action accepts the marketplace and plugin directly:
diff --git a/docs/tutorial-run-an-audit.md b/docs/tutorial-run-an-audit.md
index 5c90372..cc6a060 100644
--- a/docs/tutorial-run-an-audit.md
+++ b/docs/tutorial-run-an-audit.md
@@ -15,21 +15,28 @@ Canonical references (this tutorial points, never restates): the procedure in [S
 
 ## Step 0 — install the plugin
 
+```bash
+claude plugin marketplace add QuantEcon/skills
+claude plugin install audit@quantecon
 ```
-/plugin marketplace add QuantEcon/skills
-/plugin install audit@quantecon
-```
 
-Confirm with `/plugin list`; the version should read **0.1.2**. If `/audit:issues` does not appear in the slash menu, see [using-skills § troubleshooting](using-skills.md#updating-and-troubleshooting) — natural-language invocation ("audit every issue in this repo") works on any version.
+**Then restart your session** — plugins register at startup, so the skill does not appear until you reopen.
+
+The `/plugin marketplace add …` slash form does the same job, but it is a *terminal-CLI built-in*: the VS Code extension and the web app answer `/plugin isn't available in this environment`, while the `claude plugin` CLI above works from any shell. Confirm with `claude plugin list` — the version should read **0.1.2**.
+
+If `/audit:issues` is still unrecognised after restarting, the plugin-prefixed slash form needs Claude Code 2.1.216+; the bare `/issues` works on older builds, and natural-language invocation ("audit every issue in this repo, output to …") works on any version ([using-skills § troubleshooting](using-skills.md#updating-and-troubleshooting)).
 
 ## Step 1 — put the working directory where the repo already ignores it
 
 ```bash
 cd ~/work/quantecon/action-translation
-git status --short          # must be clean before you start — it is the read-only baseline
-git check-ignore -v .dev/scratch/x    # → .gitignore:… .dev/scratch/*
+git checkout main && git pull --ff-only   # phase 2 verifies against the DEFAULT branch
+git status --short                        # must be empty — the read-only baseline
+git check-ignore -v .dev/scratch/x        # → .gitignore:… .dev/scratch/*
 ```
 
+**Be on the default branch, not merely clean.** Phase 2's core question is whether an issue still reproduces on `main`; run from a feature branch and every answer is measured against your unmerged work instead. A clean tree on the wrong branch passes the `git status` check and silently invalidates the phase the whole run exists to test — so check the branch, not just the status.
+
 `action-translation` has a `.dev/` notes system whose `.dev/scratch/*` is already gitignored, which makes it the first-choice working directory: the run leaves `git status` completely clean, and no `.gitignore` edit is needed — that would itself be a change to a tracked file. Repos without one fall back to an untracked `.audit/` at the root ([SKILL.md § Working directory](../audit/skills/issues/SKILL.md)).
 
 ## Step 2 — invoke
diff --git a/docs/using-skills.md b/docs/using-skills.md
index 879ee60..dac2473 100644
--- a/docs/using-skills.md
+++ b/docs/using-skills.md
@@ -15,6 +15,15 @@ For lecture authors, reviewers, and maintainers who want to *use* the skills. (B
 /plugin install audit@quantecon        # maintainer-facing bulk audits
 ```
 
+**`/plugin` is a terminal-CLI built-in**, so the VS Code extension and the web app answer `/plugin isn't available in this environment`. The `claude plugin` CLI does the same job from any shell and works everywhere:
+
+```bash
+claude plugin marketplace add QuantEcon/skills
+claude plugin install audit@quantecon      # and/or qe@quantecon, benchmark@quantecon
+```
+
+Either route, **restart the session afterwards** — plugins register at startup, so a newly installed skill is absent until you reopen. `claude plugin list` shows what is installed and at which version.
+
 **In CI** — `anthropics/claude-code-action@v1` accepts `plugin_marketplaces` and `plugins` inputs directly; see the repo README for the workflow snippet.
 
 ## Invoking a skill