ultracost 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,22 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-14
+
+### Added
+- **A slash command for every verb inside Claude Code.** The plugin previously shipped only
+  `/ultracost:check`, so the phase-2 features were reachable solely through the npm CLI. It now
+  ships `/ultracost:estimate · explain · simulate · diff · audit · usage · reconcile · calibrate ·
+  ledger · status` as well — each runs the bundled CLI via `${CLAUDE_PLUGIN_ROOT}/bin/cli.js`, so
+  plugin users need nothing on `PATH`. Generated from one table (`scripts/generate-commands.mjs`)
+  and drift-tested.
+
+### Changed
+- **README is plugin-first.** The first-use example is `/ultracost:check ./path/to/workflow.js`
+  (the slash command), not the npm `ultracost check` — which plugin users don't have on `PATH`.
+  Added a full slash-command table and noted the `/ultracost:<verb>` equivalent next to each CLI
+  block. The npm CLI is now framed as the CI/scripting path.
+
 ## [0.3.0] - 2026-06-14
 
 Phase 2 — closed-loop precision and a zero-dependency visual overhaul. Still zero runtime
@@ -125,7 +141,8 @@ dependencies, Claude-Code-only, and offline on the hot path.
   and tiers whose model is in `neverUse`).
 - `ultracost status`, `ultracost doctor`, `ultracost uninstall`.
 
-[Unreleased]: https://github.com/danielkremen818/ultracost/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/danielkremen818/ultracost/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/danielkremen818/ultracost/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/danielkremen818/ultracost/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/danielkremen818/ultracost/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/danielkremen818/ultracost/compare/v0.1.0...v0.2.0

package/README.md

@@ -44,9 +44,9 @@ No telemetry. No network on the hot path. MIT.
 npx ultracost init
 ```
 
-**Command:** `ultracost check [script]` (or `/ultracost:check` in Claude Code) — flag any `agent()` stage missing a model pin.
+**First command (in Claude Code):** `/ultracost:check ./path/to/workflow.js` — flag any `agent()` stage that would silently inherit Opus. The plugin ships a slash command for every verb (`/ultracost:check · estimate · explain · simulate · diff · audit · usage · reconcile · calibrate · ledger · status`) — no global binary needed.
 
-**CLI verbs:** `init · check · audit · estimate · explain · simulate · diff · usage · reconcile · calibrate · ledger · pricing · status · doctor · uninstall`.
+**Same verbs on the npm CLI** (CI / scripting): `ultracost init · check · audit · estimate · explain · simulate · diff · usage · reconcile · calibrate · ledger · pricing · status · doctor · uninstall`.
 
 <div align="center">
 
@@ -104,13 +104,29 @@ Inside Claude Code:
 /plugin install ultracost@ultracost
 ```
 
-Then verify a workflow script at any time:
+Then, **without leaving Claude Code**, drive everything through slash commands — verify the workflow Claude just drafted, estimate it, or reconcile a finished run against what it actually cost:
 
 ```text
 /ultracost:check ./path/to/workflow.js
 ```
 
-The plugin bundles — touching none of your own files — a `SessionStart` policy-injection hook, a `PreToolUse` cost gate on the `Workflow` tool (`ULTRACOST_GATE=off` to disable), the `/ultracost:check` command, and a routing-policy skill. Requires Claude Code with the `/plugin` command and dynamic workflows enabled.
+The plugin bundles — touching none of your own files — a `SessionStart` policy-injection hook, a `PreToolUse` cost gate on the `Workflow` tool (`ULTRACOST_GATE=off` to disable), a routing-policy skill, and a slash command for every verb (each runs the bundled CLI via `${CLAUDE_PLUGIN_ROOT}`, so there's nothing to install on `PATH`):
+
+| Command | What it does |
+|---------|--------------|
+| `/ultracost:check [path]` | Flag `agent()` stages that don't pin a model (or pin the wrong tier). Defaults to the most recent workflow script. |
+| `/ultracost:estimate <script>` | Agent count, model mix, tiered cost vs an all-opus baseline. |
+| `/ultracost:explain <script>` | Per-stage rationale: model, effort, the tier the prompt reads like, est cost, check flags. |
+| `/ultracost:simulate <script>` | Cost under all-opus vs your tiered pins vs all-sonnet. |
+| `/ultracost:diff <a> <b>` | Cost delta between two versions of a script. |
+| `/ultracost:audit [dir]` | Pin stats across your real workflow scripts. |
+| `/ultracost:usage [dir]` | Real token cost from local transcripts (main vs subagents vs stages). |
+| `/ultracost:reconcile [--last\|<id>]` | Estimate vs **actual** per stage for a finished run. |
+| `/ultracost:calibrate` | Tune the estimator from your real token usage. |
+| `/ultracost:ledger` | Cumulative savings vs all-opus across recorded runs. |
+| `/ultracost:status` | How ultracost is delivered (plugin/cli), the policy, and the bypass caveat. |
+
+Requires Claude Code with the `/plugin` command and dynamic workflows enabled.
 
 ### npm CLI
 
@@ -147,7 +163,9 @@ ultracost uninstall
 
 Reverses everything `init` did: removes the routing block from `~/.claude/CLAUDE.md`, deletes `~/.claude/ultracost/`, and unregisters the hook from `~/.claude/settings.json` (an invalid `settings.json` is reported, never overwritten).
 
-## Quickstart (CLI)
+## Quickstart (npm CLI)
+
+> Inside Claude Code, every verb below is also a slash command — `/ultracost:estimate`, `/ultracost:reconcile`, etc. (see the table above). This section is the npm path for CI, scripting, or the CLAUDE.md-injection workflow.
 
 ```bash
 ultracost init                      # install policy + rules + hook (refuses if the plugin already delivers it)
@@ -197,6 +215,8 @@ ultracost calibrate             # learn a token prior from your real runs (estim
 ultracost ledger                # cumulative $ saved vs an all-opus baseline, persisted
 ```
 
+In Claude Code these are `/ultracost:usage`, `/ultracost:reconcile`, `/ultracost:calibrate`, and `/ultracost:ledger` — same output, no CLI install.
+
 - **Self-calibrating.** `calibrate` learns real per-stage token sizes (outlier-filtered) into `~/.claude/ultracost/calibration.json`; `estimate`, `explain`, `simulate`, and the gate use it automatically — the estimate gets closer to your reality every run.
 - **Savings ledger.** `ledger` keeps a running tally of what the policy saved you versus running everything on Opus, persisted in `~/.claude/ultracost/ledger.jsonl` (idempotent per run).
 - **Pre-flight budget guard.** Set `budget.perRun` / `budget.perDay` in the policy and the cost gate **denies** a launch whose estimate would blow the cap — before it runs.
@@ -209,6 +229,8 @@ ultracost simulate ./wf.js      # cost under all-opus vs your tiered pins vs all
 ultracost diff old.js new.js    # cost delta between two versions (--ci → PR-comment table)
 ```
 
+Or `/ultracost:explain`, `/ultracost:simulate`, `/ultracost:diff` inside Claude Code.
+
 ## How routing is decided
 
 | Tier | Model | Use for |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracost",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Per-stage model routing for Claude Code dynamic workflows (ultracode). Quality-first policy, CLAUDE.md rule injection, and a workflow-script guard that catches subagent stages that would silently inherit Opus.",
   "type": "module",
   "bin": {