readme: add development section with shell, testing, and env var docs

Author: nodeselector

README.md

@@ -10,7 +10,7 @@ gh extension install github/gh-actions-pin
 
 ## Usage
 
-Scan every workflow under `.github/workflows/` and pin what it can — pinning
+Scan every workflow under `.github/workflows/` and pin what it can -- pinning
 each resolvable action to an immutable SHA and updating the lockfile:
 
 ```bash
@@ -23,7 +23,7 @@ Scope the scan to a single workflow (same default behavior, one file):
 gh actions-pin .github/workflows/ci.yml
 ```
 
-By default, already-pinned workflows are trusted from the lockfile — their
+By default, already-pinned workflows are trusted from the lockfile -- their
 reachability isn't re-checked against upstream. To force a full re-verification
 of every recorded pin (bypassing that fast path):
 
@@ -43,7 +43,7 @@ format. Structured results go to stdout, progress to stderr.
 ## How it works
 
 GitHub Actions is a package manager that forgot to ship a lockfile. Your
-workflows are the manifest — every `uses:` line is a dependency, resolved by
+workflows are the manifest -- every `uses:` line is a dependency, resolved by
 mutable tag or branch *at runtime*, on GitHub's servers, with no record of what
 actually ran. `gh-actions-pin` supplies the missing half: `.github/workflows/actions.lock`,
 the Actions analogue of `go.sum` or `package-lock.json`. Each run resolves every
@@ -88,6 +88,66 @@ flowchart TD
 The security guarantee lives in **Verifying reachability**: a SHA pin is only
 trustworthy if that commit is reachable from the tag/branch it claims to come
 from. A SHA that resolves but isn't in the ref's history is an *impostor commit*
-— the fork-network attack `gh-actions-pin` exists to catch — and it's flagged
+-- the fork-network attack `gh-actions-pin` exists to catch -- and it's flagged
 rather than silently trusted.
 
+## Development
+
+### Build
+
+```bash
+make build
+```
+
+### Tests
+
+```bash
+make test              # Go unit tests
+make test-integration  # all integration scenarios (stub + live)
+make test-stub         # stub scenarios only (no network, fast)
+make test-live         # live repo scenarios only (clones real repos)
+```
+
+### Interactive shell
+
+The test shell is a REPL for rapid iteration. It runs scenarios through a PTY
+so you see real ANSI output, spinners, and colors exactly as a user would.
+
+```bash
+make test-shell
+```
+
+Inside the shell:
+
+```
+pin-test > list                   # show all scenarios by category
+pin-test > run happy_path         # run a scenario with live PTY output
+pin-test > happy_path             # shorthand -- bare name works too
+pin-test > run github/github      # ad-hoc test against any repo
+pin-test > run all                # run every scenario
+pin-test > build                  # rebuild the binary without leaving
+pin-test > inspect lockfile_fresh # show fixtures without running
+pin-test > diff                   # git diff from the last run
+pin-test > profile on             # enable CPU/trace profiling
+pin-test > auth                   # show current auth source
+pin-test > help                   # full command list
+```
+
+Live scenarios and ad-hoc repo runs require GitHub auth. The shell uses
+`gh auth token` automatically, or you can set `GH_TOKEN` explicitly.
+
+### Scenario catalog
+
+All scenarios are defined in `test/scenarios/catalog.yml` and consumed by both
+the Go test suite (`test/scenarios/catalog_test.go`) and the Ruby integration
+harness (`test/integration/run.rb`). Add new scenarios to the YAML -- both
+sides pick them up.
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `GH_TOKEN` / `GITHUB_TOKEN` | Auth token for live tests (falls back to `gh auth token`) |
+| `GH_ACTIONS_PIN_WORKFLOWS_DIR` | Override the workflows directory to scan (lab/testing use) |
+| `KEEP_FIXTURES` | Keep temp dirs after test runs for debugging |
+