switchboard-fyi 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable Switchboard CLI changes are recorded here. Keep this file in sync
+with the hosted release notes at `https://www.switchboard.fyi/release/latest`.
+
+## 0.2.0 - 2026-05-26
+
+### Changed
+
+- Reworked the published README into a shorter install and quick-start guide.
+
+## 0.1.0 - 2026-05-26
+
+### Added
+
+- First public `switchboard-fyi` CLI release on npm.
+- Homebrew tap formula for `brew install switchboardfyi/tap/switchboard-fyi`.
+- Local routing, observe mode, dashboard, model catalog, and update checks for
+  Codex and Claude Code workflows.

package/README.md

@@ -1,538 +1,36 @@
 # Switchboard
 
-## Local routing CLI
+Switchboard picks the right model for your Codex and Claude Code requests, so you stop wasting expensive ones on easy tasks.
 
-Switchboard is designed to sit in front of normal `codex` and `claude` usage.
-The install step creates local PATH shims so those commands route through
-Switchboard anywhere in the terminal.
-
-Install from npm:
+## Install
 
 ```bash
 npm install -g switchboard-fyi
 ```
 
-Or install with Homebrew after the public tap is published:
-
-```bash
-brew install switchboardfyi/tap/switchboard-fyi
-```
-
-Installed CLI entrypoint:
-
-```bash
-switchboard
-```
-
-Bare `switchboard` opens the interactive local console. The published CLI
-supports macOS and Linux for launch; Windows shims are intentionally not
-included in this release.
-
-The interactive `start` action opens the live dashboard for that harness. It
-does not launch Codex or Claude Code.
-
-Harness state is runtime scoped:
-
-- `installed`: Switchboard is ready, but routing is off. Codex and Claude use
-  your normal model settings.
-- `observe`: `switchboard observe <harness>` is running in a terminal. Harness
-  calls go through Switchboard for logging, but models are preserved.
-- `routing`: `switchboard start <harness>` is running in a terminal. Harness calls
-  go through Switchboard and can be routed according to the selected profile.
-
-Closing the `start` or `observe` terminal turns that harness back to
-`installed`.
-
-Only one `start` or `observe` terminal can own a harness at a time. If Codex or
-Claude Code is already active in another window, Switchboard refuses the second
-start and shows the owning process id.
-
-Only one wrapped Codex or Claude Code session can run through Switchboard for a
-harness at a time. That keeps local gateways tied to visible terminal sessions
-instead of accumulating in the background.
-
-The home screen is harness-first: before a shim is active, each harness only
-offers `install`; after install, it offers `start`, `observe`, `settings`, and
-`uninstall`.
-
-Install the shims:
+## Set up
 
 ```bash
 switchboard install
 ```
 
-This writes `codex` and `claude` wrappers to `~/.switchboard/bin`, records the
-real binary paths in `~/.switchboard/install.json`, and adds a managed PATH
-block to your shell rc file. Open a new terminal after install. Then use the
-tools normally:
-
-```bash
-codex
-claude
-```
-
-To install one harness or remove the shims:
-
-```bash
-switchboard install codex
-switchboard install claude
-switchboard uninstall codex
-switchboard uninstall claude
-switchboard uninstall
-```
-
-Settings expose each installed harness model set, including the difficulty
-`1..5` model map for each harness.
-
-Run Codex through the Responses model-provider proxy:
-
-```bash
-codex
-```
-
-Codex must be routed at the model-provider boundary, not the app-server
-`turn/start` boundary. The canonical path is:
-
-```text
-codex -> Switchboard /v1/responses -> chatgpt.com/backend-api/codex/responses
-```
-
-This preserves ChatGPT/Codex subscription auth locally and exposes each internal
-Codex model request to Switchboard.
-Switchboard v1 supports ChatGPT subscription auth only for Codex. API-key Codex
-requests are rejected locally before routing, without spending a Switchboard
-request credit or forwarding to `api.openai.com`.
-
-Run Claude Code through the Anthropic-compatible gateway:
-
-```bash
-claude
-```
-
-Switchboard v1 supports Claude Code subscription OAuth only, including
-`CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`. Anthropic API-key,
-PAYG, Bedrock, Vertex, and Foundry auth paths are stripped or rejected before
-routing.
-
-Observe mode:
-
-```bash
---observe
-```
-
-Switchboard API routing:
-
-```bash
-switchboard login
-switchboard balance
-switchboard config use-switchboard-api https://api.switchboard.fyi
-```
-
-The gateway sends a compact classification packet and local routing settings to
-the Switchboard API. The Cloudflare API owns the classifier prompt, checks
-credits, calls Workers AI, and returns difficulty `1..5`, a reason code, and a
-short dashboard task label. The local CLI maps that difficulty to the configured
-model for the active harness. A successful new API classification spends one request credit,
-including best and observe recommendations. It sends a compact routing summary,
-not the raw provider request, and the billing ledger does not store full
-prompts. If the API is unavailable or the account has no request credits, the
-dashboard records an explicit router error or insufficient-balance state.
-
-After that, this is enough:
-
-Terminal 1:
-
-```bash
-switchboard start codex
-```
-
-Terminal 2:
-
-```bash
-codex \
-  exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox \
-  "Reply with exactly: router-ok"
-```
-
-For an interactive Codex session, use:
-
-```bash
-codex
-```
-
-If the default local proxy port is already occupied, the wrapper automatically
-uses the next free port and prints the port it selected.
-
-Model catalog and difficulty map:
-
-```bash
-switchboard models
-switchboard models list
-switchboard models codex
-switchboard models claude-code
-switchboard difficulty
-switchboard difficulty set codex 5 gpt-5.5 xhigh
-switchboard difficulty set claude-code 3 claude-sonnet-4-6 medium
-```
-
-Switchboard classifies each request as difficulty `1..5`, then resolves that
-difficulty locally from the configured map for the active harness. Use
-`models` to inspect the bundled catalog and `difficulty set` to edit a single
-difficulty level. The default Codex map is:
-
-```text
-5  gpt-5.5       reasoning=xhigh
-4  gpt-5.5       reasoning=medium
-3  gpt-5.4       reasoning=medium
-2  gpt-5.4-mini  reasoning=medium
-1  gpt-5.4-mini  reasoning=low
-```
-
-For Codex, the three main-model choices are `gpt-5.5 reasoning=xhigh`,
-`gpt-5.5 reasoning=high`, and `gpt-5.5 reasoning=medium`. For Claude Code,
-the default map routes lower difficulty requests to Haiku/Sonnet and higher
-difficulty requests to Opus.
-
-The model catalog lists standard uncached input and output billing rates per
-million tokens: Codex uses Codex credits, and Claude uses USD API pricing.
-The local CLI dashboard shows requests and provider token usage from local
-responses. Account status shows hosted request counts; hosted token totals are
-shown only when token accounting is available. It does not show cost estimates.
-
-The bundled model catalog is curated and updates with new Switchboard releases.
-
-CLI updates:
-
-```bash
-switchboard update check
-switchboard update
-```
-
-After the npm package is published, `switchboard update check` reads the npm
-registry and `switchboard update` runs the package-manager update flow. The CLI
-also checks periodically and can show a TTY-only update prompt:
-
-```text
-✨ Switchboard update available! 0.1.0 -> 0.1.1
-
-Release notes: https://switchboard.fyi/release/latest
-
-  1. Update Switchboard
-  2. Skip
-```
-
-Skipping only applies to the current run; if the same version is still latest,
-Switchboard prompts again on the next interactive `switchboard` launch. Normal
-wrapped `codex` and `claude` runs never show this prompt. The latest npm result
-is cached in `~/.switchboard/update-state.json` so normal Switchboard launches
-do not hit the registry every time.
+Open a new terminal after install.
 
-Component status:
+## Run it
 
 ```bash
-switchboard status
-switchboard status set codex needs-update "Codex harness needs a Switchboard update"
-switchboard status set claude down "Claude harness temporarily disabled"
-switchboard status set switchboard api degraded "Classifier API latency is elevated"
-switchboard status clear codex
-switchboard config set componentStatus.url https://status.example.com/switchboard.json
-switchboard status refresh
+switchboard
 ```
 
-`status set` writes a local override to `~/.switchboard/config.json`. By default,
-remote component status is read from `<api.baseUrl>/v1/status`. That API-owned
-feed is the production source of truth for `claude`, `codex`, and `api`
-compatibility. Its steady state should be `ok`; `unknown` is only a local
-fallback when no status source has been read.
-
-Production incidents should be handled through the API status feed, not local
-overrides. The operational runbook is in
-`docs/component-status-runbook.md`.
+Then keep using `codex` and `claude` exactly as you do today.
 
-Use API-level component status when an upstream Claude Code or Codex release
-breaks Switchboard compatibility, or when the Switchboard API itself is
-degraded. The CLI renders `ok` as a checkmark and `degraded`, `needs_update`,
-or `down` as attention states. For incidents that should use a different feed,
-publish a small JSON manifest at `componentStatus.url`; the CLI caches it in
-`~/.switchboard/component-status.json` and still allows local overrides for
-testing or emergency support.
-
-Manifest shape:
-
-```json
-{
-  "schemaVersion": 1,
-  "updatedAt": "2026-05-19T12:00:00Z",
-  "components": {
-    "codex": { "state": "ok" },
-    "claude": { "state": "needs-update", "message": "Run switchboard update before using Claude Code." },
-    "api": { "state": "degraded", "message": "Classifier latency is elevated." }
-  }
-}
-```
-
-Logs:
+## Other handy commands
 
 ```bash
-switchboard watch codex
-switchboard watch claude-code
-switchboard inspect
-switchboard inspect --harness codex
-switchboard inspect --harness claude-code
-switchboard status codex
-switchboard config show
-switchboard dashboard --local codex
-switchboard dashboard --local claude-code
-switchboard watch codex
-switchboard logs codex
-tail -f ~/.switchboard/harnesses/codex/events.jsonl
-tail -f ~/.switchboard/harnesses/claude/events.jsonl
+switchboard login      # sign in for smart routing
+switchboard status     # check what's running
+switchboard update     # update Switchboard
+switchboard uninstall  # remove the shims
 ```
 
-Switchboard keeps runtime logs and health state per harness under
-`~/.switchboard/harnesses/<harness>/`, while global config remains shared.
-Use `switchboard inspect` for the local web inspector. It groups calls by
-`decisionId` and shows the routing payload, API/router response, applied
-route, forwarding status, and raw JSONL events.
-
-More detail is in `docs/mvp-usage.md`, `docs/codex-subscription-provider-proxy.md`,
-`docs/routing-api.md`, `docs/known-limitations.md`, and `docs/smoke-test.md`.
-
-## 1-Page Product Spec
-
-Switchboard — 1-Page Product Spec
-Product summary
-
-Switchboard is an API-directed model-routing gateway for developers using tools like Claude Code, Codex, and future AI coding harnesses.
-
-Developers keep using their existing tools exactly as normal. Switchboard sits behind the harness as the model endpoint, asks the Switchboard API where to route, tries the recommended cheaper model when directed, and automatically falls back to the original model if the routed provider call fails before useful output is sent.
-
-Use the right model without thinking about it.
-
-Core promise
-
-Switchboard does one thing:
-
-Route when the Switchboard API says to route, and protect the developer with automatic original-call fallback.
-
-It does not rewrite prompts, compact context, modify tools, change agent behavior, or interfere with the developer’s workflow.
-
-Problem
-
-Developers love Claude Code and Codex because the harness is already excellent: repo awareness, shell access, tool use, patches, context handling, and workflow muscle memory.
-
-But these tools often use expensive models for tasks that do not need them:
-
-Rename this variable
-Write a PR description
-Explain this small error
-Summarize this diff
-Make this copy clearer
-
-At the same time, many tasks genuinely deserve the strongest model:
-
-Fix this auth bug
-Refactor this module
-Debug failing tests
-Think through this architecture
-Make a complex multi-file change
-
-Today, users have to manually decide which model is worth using. Most will not. So they either overspend or risk underpowering important work.
-
-Target users
-
-Initial users are AI-heavy developers, indie hackers, founders, and small teams who already use Claude Code, Codex, Cursor, or similar tools daily.
-
-They want:
-
-- lower AI model spend
-- less top-tier quota waste
-- no workflow migration
-- no degraded quality on hard tasks
-- simple override controls
-Non-goals
-
-Switchboard v1 should be intentionally narrow.
-
-It should not do:
-
-- prompt rewriting
-- context compaction
-- tool blocking
-- repo analysis
-- validation loops
-- custom agent behavior
-- coding-agent replacement
-- new IDE/chat interface
-
-The trust boundary is simple:
-
-Switchboard only chooses the destination model.
-
-How it works
-Claude Code / Codex
-        ↓
-Switchboard Gateway
-        ↓
-Route Classifier
-        ↓
-Lower-cost model OR strongest model
-        ↓
-Response streams back to original harness
-
-The user configures their tool to use Switchboard as the model endpoint.
-
-Example model alias:
-
-model = "auto"
-
-Switchboard maps `auto` to the model configured for the API-assigned
-difficulty. It maps `auto` to the configured best model when preserved,
-uncertain, or falling back.
-Routing policy
-
-Switchboard classifies each request into difficulty `1..5`:
-
-- `1` → trivial, exact, mechanical, or simple text work
-- `2` → light routine text or bounded work
-- `3` → normal bounded coding or analysis
-- `4` → substantial multi-step, tool-driven, or multi-file work
-- `5` → hard debugging, architecture, large context, or high-risk work
-
-The API owns difficulty classification. The CLI owns model selection,
-execution, retry, and narrow routed-path cooldowns after real routed failures.
-
-Default principle:
-
-Route to save money when the API recommends it; fall back to the original model when execution proves that route unhealthy.
-
-Lower-tier examples
-- naming
-- simple rewrites
-- small explanations
-- commit messages
-- PR descriptions
-- formatting
-- command generation
-
-Mid-tier examples
-- summarizing short diffs
-- simple terminal-output explanation
-- large-context summarization
-- straightforward single-file edits
-- routine config/docs work
-
-Best-tier examples
-- bug fixing
-- auth/payments/security work
-- refactors
-- multi-file edits
-- test failures
-- architecture decisions
-- unclear requirements
-- consequential security review
-- repeated failed attempts
-- anything the router is unsure about
-Product modes
-1. Observe
-
-No routing. Switchboard only reports what it would have done.
-
-12 calls would have been preserved on the strongest model.
-7 calls could likely have used cheaper routing.
-2. Auto
-
-Switchboard automatically routes obvious low-risk calls down and preserves the strongest model for everything else.
-
-Three routing modes:
-
-- `Quality`: prioritize the strongest model for harder work while still routing clear low-risk waste
-- `Balanced`: recommended default for everyday sessions
-- `Saver`: route more aggressively to reduce spend while still protecting high-risk work
-User experience
-
-The product should be quiet.
-
-The developer still runs:
-
-claude
-
-or:
-
-codex
-
-Optional session receipt:
-
-Disabled by default. Enable it with:
-
-```bash
-switchboard config set sessionReceipt.enabled true
-```
-
-Switchboard session receipt
-
-Requests: 8
-Tokens processed: 42k
-Cheap-route retries: 0
-
-Power-user overrides:
-
-auto
-lower
-best
-MVP
-Must-have
-- gateway endpoint
-- Claude Code / Codex setup instructions
-- model alias: auto
-- API-directed route classifier
-- difficulty-to-model mapping
-- streaming response passthrough
-- request/cost logging
-- session receipt
-- user override: force best
-Should-have
-- observe mode
-- auto mode
-- simple dashboard
-- per-project settings
-- routed-request regret tracking
-Success metrics
-
-Primary metric:
-
-Best-tier requests avoided without increasing retries.
-
-Track:
-
-- strongest-model requests avoided
-- tokens processed
-- routed-request retry rate
-- user override rate
-- router disable rate
-- preserved-request rate
-- cost per accepted task
-
-Most important quality metric:
-
-Lower-tier regret rate
-
-Meaning:
-
-How often did a user rerun, override, or escalate after Switchboard used a lower-cost tier?
-
-That number must stay low.
-
-Positioning
-
-Simple version:
-
-Switchboard routes AI coding requests through the Switchboard API and falls back to the original model when a routed provider call fails.
-
-Developer version:
-
-An API-directed model-routing layer for Claude Code, Codex, and other AI coding harnesses. Keep your workflow. Cut wasted top-tier calls. Fall back safely.
-
-Punchier tagline:
-
-Use your strongest model where it matters.
+More docs live at [switchboard.fyi](https://www.switchboard.fyi).

package/docs/release.md

@@ -0,0 +1,133 @@
+# Release Process
+
+This is the canonical release path for `switchboard-fyi`. The npm registry is
+the source package; Homebrew installs the npm tarball by URL and checksum.
+
+## One-Time Setup
+
+```bash
+cd /Users/dannywitters/Documents/switchboard/cli
+npm login
+npm whoami
+
+brew tap switchboardfyi/tap
+```
+
+## 1. Prepare The CLI Release
+
+Choose the next semver version and update package metadata without creating an
+automatic git tag:
+
+```bash
+npm version patch --no-git-tag-version
+```
+
+Update:
+
+- `CHANGELOG.md`
+- `web/app/release/latest/page.tsx` in the web repo, so the update prompt's
+  release notes URL matches the shipped version
+- any README/docs affected by the change
+
+Run the preflight:
+
+```bash
+npm run release:preflight
+```
+
+The preflight runs tests, checks version/changelog/package consistency, verifies
+the version is not already on npm, and runs `npm publish --dry-run`.
+
+Commit the release prep:
+
+```bash
+VERSION="$(node -p "require('./package.json').version")"
+git status --short
+git add package.json package-lock.json CHANGELOG.md README.md docs scripts bin lib test packaging
+git commit -m "Release switchboard-fyi $VERSION"
+git push origin main
+```
+
+## 2. Publish npm
+
+```bash
+npm publish
+```
+
+If npm asks for two-factor auth:
+
+```bash
+npm publish --otp 123456
+```
+
+Verify the published package:
+
+```bash
+VERSION="$(node -p "require('./package.json').version")"
+npm view "switchboard-fyi@$VERSION" version dist.tarball dist.integrity
+
+NPM_PREFIX="$(mktemp -d)"
+npm install -g --prefix "$NPM_PREFIX" "switchboard-fyi@$VERSION"
+"$NPM_PREFIX/bin/switchboard" version
+```
+
+## 3. Update Homebrew
+
+After npm is live, update the Homebrew formula from the actual registry
+tarball:
+
+```bash
+npm run release:homebrew -- --tap ../homebrew-tap
+```
+
+This updates both:
+
+- `cli/packaging/homebrew/Formula/switchboard-fyi.rb`
+- `homebrew-tap/Formula/switchboard-fyi.rb`
+
+Commit the CLI-side template update:
+
+```bash
+VERSION="$(node -p "require('./package.json').version")"
+git add packaging/homebrew/Formula/switchboard-fyi.rb
+git commit -m "Update Homebrew template for switchboard-fyi $VERSION"
+git tag "v$VERSION"
+git push origin main "v$VERSION"
+```
+
+Commit and push the public tap:
+
+```bash
+cd ../homebrew-tap
+git status --short
+git add Formula/switchboard-fyi.rb
+git commit -m "Update switchboard-fyi to $VERSION"
+git push origin main
+```
+
+## 4. Verify Homebrew
+
+```bash
+brew update
+brew reinstall switchboardfyi/tap/switchboard-fyi
+brew test switchboardfyi/tap/switchboard-fyi
+switchboard version
+```
+
+If a local npm-global install already owns `/opt/homebrew/bin/switchboard`,
+Homebrew may build the formula but fail to link. For release verification on
+your own machine, this is expected and can be resolved with:
+
+```bash
+brew link --overwrite switchboard-fyi
+```
+
+## 5. Final Checks
+
+```bash
+npm view switchboard-fyi version
+brew info switchboardfyi/tap/switchboard-fyi
+```
+
+Confirm the latest version shown by npm, Homebrew, `CHANGELOG.md`, and the web
+release page all match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard-fyi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local model-routing CLI for Codex and Claude Code.",
   "license": "MIT",
   "homepage": "https://www.switchboard.fyi",
@@ -12,6 +12,7 @@
     "switchboard-inspector": "bin/switchboard-inspector.mjs"
   },
   "files": [
+    "CHANGELOG.md",
     "bin/switchboard.mjs",
     "bin/switchboard-gateway.mjs",
     "bin/switchboard-inspector.mjs",
@@ -19,6 +20,7 @@
     "docs/codex-subscription-provider-proxy.md",
     "docs/known-limitations.md",
     "docs/mvp-usage.md",
+    "docs/release.md",
     "docs/routing-api.md",
     "docs/smoke-test.md",
     "README.md",
@@ -42,6 +44,9 @@
     "config": "node ./bin/switchboard.mjs config",
     "gateway": "node ./bin/switchboard-gateway.mjs start",
     "self-test": "node ./bin/switchboard-gateway.mjs self-test",
+    "release:check": "node scripts/release-check.mjs",
+    "release:preflight": "npm test && node scripts/release-check.mjs --prepublish && npm publish --dry-run",
+    "release:homebrew": "node scripts/update-homebrew-formula.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {