chore: maintenance pass, --version flag, AGENTS.md and 0.2.0 release prep

[TheStreamCode]

Summary

Maintenance pass on the launcher: one small user-facing feature, an actionable failure message, tooling/CI tidy-up, project documentation for contributors and AI agents, and the 0.2.0 version bump. No breaking changes.

Changes

CLI (src/)

• Add -v / --version, printing the installed version read from package.json (correct for global, local, and npm link installs). The flag is consumed by the switcher, like --help; -- --version still forwards to Copilot CLI.
• Replace the raw spawn ... ENOENT failure with a message naming the resolved executable path, the npm install -g @github/copilot command, and the COPILOT_BIN override.
• Remove a dead platform argument passed to buildCopilotSpawnOptions, which does not accept it.

Tests

• New coverage for --help, --version, interactive provider selection, interactive model selection, and the missing-binary path.
• 39 → 45 tests; line coverage 87.3% → 93.0% (src/cli.mjs 63.8% → 87.3%).
• Consolidated the duplicated src/cli.mjs import in test/cli.test.mjs.

Tooling / CI

• ESLint ignores coverage/, so linting after npm run test:coverage no longer depends on removing the report first.
• .gitignore covers *.tgz (npm pack output) and Thumbs.db.
• CI now triggers on pushes to main and v* tags, on pull requests, and on workflow_dispatch. Pull-request branches previously ran the six-job matrix twice. Job names are unchanged, so the required status checks still match.
• The issue-template security link points to SECURITY.md instead of a generic site URL.

Documentation

• New AGENTS.md: stack, repository layout, real commands, code conventions, non-negotiable secret-handling rules, the checklist for adding a built-in provider, the validation gate, generated files, and the protected-branch release process.
• README.md: full command-line option table (including --version), project structure, release process, contributing, security, changelog and license sections, Node engine and license badges, and refreshed pinned install versions.
• CHANGELOG.md: 0.2.0 entry.

Versioning

• 0.1.0 → 0.2.0 (backward-compatible feature). package.json, package-lock.json, CITATION.cff, CHANGELOG.md, and the pinned README versions are all in sync.

Testing

• npm run lint && npm test passes — 45/45, 0 failures
• Tested on Windows (Node 24.18.0, npm 11.16.0)
• Tested on macOS / Linux — covered by the CI matrix (Ubuntu and macOS, Node 22 and 24)
• Verified with at least one real provider — --dry-run against the built-in Chutes preset from the packed tarball; COPILOT_PROVIDER_API_KEY correctly rendered as <redacted>. No live inference call was made.

Additional verification:

• npm audit --omit=dev --audit-level=high → 0 vulnerabilities (also 0 including dev dependencies).
• npm pack → copilot-byok-switcher-0.2.0.tgz, 20.4 kB, 16 files. Contents verified: bin/, src/, examples/, docs/, schemas/, package.json, README.md, CHANGELOG.md, SECURITY.md, LICENSE. No tests, no node_modules, no .env, no local configuration.
• Smoke test: installed the tarball into a clean temp project; copilot-byok --version → 0.2.0, --help and --dry-run behave as documented.
• All README badge and link targets return HTTP 200 (npmjs.com returns 403 to scripted requests only; the package page is live and the shields npm badge resolves).

Checklist

• PR is focused on a single concern (maintenance + 0.2.0 release prep)
• README.md updated if user-facing behavior changed
• No API keys or credentials in code or examples
• New provider entries include base URL, env var, and default model — not applicable, no provider changes

Notes

• Behavior change to be aware of: --version and -v are now consumed by the switcher instead of being forwarded to Copilot CLI. Use -- --version to reach Copilot's own flag. This matches how --help / -h already behaved.
• Publishing is deliberately not done in this PR. After merge, the release still needs: npm publish, git tag v0.2.0, git push origin v0.2.0, and a GitHub Release for v0.2.0.
• No history rewriting, no force push, no protection bypass, no visibility change.

🤖 Generated with Claude Code