Docs: the CLI install route, and check the branch not just the status

[mmcky]

Two gaps found within minutes of someone actually following docs/tutorial-run-an-audit.md to start run 1 of #16. Both are exactly the class of thing the validation program exists to surface — neither is visible from reading the doc, only from running it.

/plugin does not exist outside the terminal CLI

Every install instruction in this repo — README, using-skills.md, the new tutorial — offered only the slash form. In the VS Code extension (and the web app) that returns "/plugin isn't available in this environment", which reads like the marketplace is broken rather than like the command is unavailable. The claude plugin CLI does the same job from any shell:

claude plugin marketplace add QuantEcon/skills
claude plugin install audit@quantecon

Documented in docs/using-skills.md, which owns setup per the doc map; the tutorial's Step 0 now leads with the CLI form, since it is the one that works everywhere; README gets a pointer rather than a third copy.

All three also now say to restart the session after installing. Plugins register at startup, so a freshly installed skill is simply absent until you reopen — a second silent stumbling block, and one that looks identical to a failed install.

A clean tree on the wrong branch passed the preflight

Step 1 told the reader to check git status --short before starting. It never said to be on the default branch. Phase 2's core question is whether an issue still reproduces on main — run it from a feature branch and every answer is measured against unmerged work instead, silently invalidating the phase the whole run exists to test, while passing the check the tutorial did specify.

Caught on a real checkout that was sitting two commits ahead on a feature branch with a perfectly clean tree. The preflight is now git checkout main && git pull --ff-only before the status check, with the reasoning stated so it does not read as boilerplate.

Status of run 1

Started and underway on QuantEcon/action-translation, correctly on main. Phase 1 clean: 230 items (118 issues + 112 PRs), 1..230 fully accounted, no truncation, snapshot 2026-07-28T06:45:58Z, fetched_by populated. The tracker gained two issues in the twelve hours since #19 measured it at 228, which is a small live demonstration of why the report quotes its own snapshot rather than an earlier count.

Docs only — no plugin version change, validate.py green.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates installation and preflight instructions in the documentation so users can successfully install the marketplace/plugins outside the terminal slash-command environment, and so audit runs aren’t inadvertently performed from the wrong branch (which would invalidate phase-2 verification).

Changes:

• Documented the claude plugin … CLI install route (and why /plugin may not work in VS Code/web).
• Added explicit “restart the session” guidance after plugin install (so newly installed skills appear).
• Strengthened the audit tutorial preflight to check out/pull the default branch before starting.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
README.md	Adds a pointer clarifying /plugin vs claude plugin … installation routes (but currently misses the restart note).
docs/using-skills.md	Adds CLI-based install commands and a restart-after-install troubleshooting note in the canonical setup doc.
docs/tutorial-run-an-audit.md	Leads with CLI install, adds restart guidance, and updates preflight to ensure work happens on main before auditing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.