ultracost 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-06-14
+
 ### Changed
 - **The cost gate is now mode-aware and hard in every permission mode.** It reads
   `permission_mode` from the `PreToolUse` event: it asks (with the estimate) in
@@ -74,8 +76,8 @@ All notable changes to this project are documented here. The format is based on
 - Data-driven `policy.json` with load-time validation (rejects undefined default tiers
   and tiers whose model is in `neverUse`).
 - `ultracost status`, `ultracost doctor`, `ultracost uninstall`.
-- Docs: architecture, policy reference, and the ultracode rationale.
 
-[Unreleased]: https://github.com/danielkremen818/ultracost/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/danielkremen818/ultracost/compare/v0.2.1...HEAD
+[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
 [0.1.0]: https://github.com/danielkremen818/ultracost/releases/tag/v0.1.0

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="./assets/logo.png" alt="ultracost logo" width="150">
+
 # ultracost
 
 **Per-stage model routing for Claude Code dynamic workflows.**
@@ -29,14 +31,15 @@ guard that fails any unpinned stage.
 
 No telemetry. No network on the hot path. MIT.
 
-**Setup (plugin):**
+**Setup:**
 
-```text
-/plugin marketplace add danielkremen818/ultracost
-/plugin install ultracost@ultracost
+```bash
+npx ultracost init
 ```
 
-**Built-in command:** `/ultracost:check [script]` — flag any `agent()` stage missing a model pin.
+> A Claude Code plugin is planned; today ultracost installs via the npm CLI.
+
+**Command:** `ultracost check [script]` (or `/ultracost:check` in Claude Code) — flag any `agent()` stage missing a model pin.
 
 **CLI verbs:** `init · check · audit · estimate · pricing · status · doctor · uninstall`.
 
@@ -75,90 +78,33 @@ ultracost makes the routing **explicit, policy-driven, and verifiable** — with
 
 ## Architecture
 
-One shared core in `src/`, two delivery surfaces: a Claude Code **plugin** (primary) and an **npm CLI** (secondary). Both compile from the same `policy.json`.
-
-```mermaid
-flowchart TD
-    subgraph core["src/ — shared core"]
-        POL["policy.js<br/>(policy.json — you own it)"]
-        RUL["rules.js<br/>(rule compiler)"]
-        GRD["guard.js<br/>(static analysis)"]
-    end
-
-    subgraph plugin["Claude Code plugin — PRIMARY"]
-        SK["skills/ultracost<br/>routing policy (always-relevant)"]
-        CMD["/ultracost:check command"]
-        HK["hooks.json<br/>SessionStart (all sources)"]
-    end
-
-    subgraph cli["npm CLI — secondary"]
-        BIN["bin/cli.js<br/>init · check · audit · doctor · status · uninstall"]
-    end
-
-    POL --> RUL
-    RUL --> SK
-    RUL --> BIN
-    GRD --> CMD
-    GRD --> BIN
-    HK --> RE["reinject.mjs<br/>(node, no bash/jq)"]
-    BIN --> RE
-
-    classDef ft fill:#1f6feb,stroke:#0b3d91,color:#fff;
-    class POL,RUL,GRD ft;
-```
-
-The plan lives in **data** (`policy.json`), not in prose buried in a prompt. The guard is the enforcement layer the model can't talk its way out of. See [`docs/architecture.md`](./docs/architecture.md) for the full picture.
-
-## Install
-
-### Plugin (recommended)
-
-Inside Claude Code, add the marketplace and install the plugin:
+One shared core in `src/`, two delivery surfaces: an **npm CLI** (the install path today) and a Claude Code **plugin** (planned). Both compile from the same `policy.json`.
 
-```text
-/plugin marketplace add danielkremen818/ultracost
-/plugin install ultracost@ultracost
-```
-
-Then verify a workflow script at any time:
-
-```text
-/ultracost:check ./path/to/workflow.js
-```
-
-The plugin bundles four things and **touches none of your existing files**:
+<div align="center">
 
-- a **`SessionStart`** hook that injects the routing policy as context at session start and after compaction (the always-on guidance),
-- a **`PreToolUse` cost gate** on the `Workflow` tool that hard-stops every dynamic-workflow launch with an estimate (set `ULTRACOST_GATE=off` to disable; see [`docs/ESTIMATES.md`](./docs/ESTIMATES.md)),
-- the **`/ultracost:check`** command (the Workflow Guard), and
-- a **routing-policy skill** for explicit reference when Claude authors workflow/ultracode/subagent scripts.
+<img src="./assets/architecture.svg" alt="ultracost architecture — policy.json compiles through the src/ core into a Claude Code plugin and an npm CLI; the guard and a PreToolUse cost gate verify every workflow stage at runtime" width="960">
 
-> Requires Claude Code with the `/plugin` command (run `/help` to confirm) and dynamic workflows enabled.
+</div>
 
-### npm CLI (professional secondary)
+The plan lives in **data** (`policy.json`), not in prose buried in a prompt. The guard is the enforcement layer the model can't talk its way out of. See [`docs/architecture.md`](./docs/architecture.md) for the full picture.
 
-For CI, scripting, or if you prefer the `~/.claude/CLAUDE.md` injection path:
+## Install
 
 ```bash
 npx ultracost init
 ```
 
-This writes `~/.claude/ultracost/policy.json`, injects the routing block into `~/.claude/CLAUDE.md`, installs the re-inject hook (`~/.claude/ultracost/reinject.mjs`), and registers it in `~/.claude/settings.json`. New sessions pick it up immediately. Paths honor `CLAUDE_CONFIG_DIR` if you've relocated your config.
+This writes `~/.claude/ultracost/policy.json`, injects the routing block into `~/.claude/CLAUDE.md`, installs the re-inject hook (`~/.claude/ultracost/reinject.mjs`), and registers it on `SessionStart` in `~/.claude/settings.json`. New sessions pick it up immediately. Paths honor `CLAUDE_CONFIG_DIR` if you've relocated your config.
 
-> Requires Node ≥ 24.
-
-## Uninstall
-
-### Plugin
+Then verify a workflow script at any time:
 
-```text
-/plugin uninstall ultracost@ultracost
-/plugin marketplace remove ultracost
+```bash
+ultracost check ./path/to/workflow.js
 ```
 
-The plugin touches none of your own files — its hook, command, and skill live inside the plugin package, so removing it removes everything; nothing is left in your `~/.claude/CLAUDE.md` or `settings.json`. If Claude Code offers to "disable in `settings.local.json`" instead (because the plugin was enabled in a shared `settings.json`), that has the same effect — accept it, or remove the marketplace as above.
+> Requires Node ≥ 24. A Claude Code plugin — bundling the `SessionStart` policy injection, a `PreToolUse` cost gate on the `Workflow` tool, the `/ultracost:check` command, and a routing-policy skill — ships in this repo and is planned as a separate install path; for now use the npm CLI above.
 
-### npm CLI
+## Uninstall
 
 ```bash
 ultracost uninstall

package/docs/PUBLISHING.md

@@ -17,16 +17,16 @@ The GitHub handle is set to `danielkremen818` across the repo. If you fork or mo
 update the handle in every file that ships:
 
 - [x] `package.json` — `repository.url`, `bugs.url`, `homepage`.
-- [x] `README.md` — install commands (`/plugin marketplace add danielkremen818/ultracost`) and the npm/CI badge URLs.
+- [x] `README.md` — the npm install command (`npx ultracost init`) and the npm/CI badge URLs.
 - [x] `CHANGELOG.md` — the `[Unreleased]`/release compare links.
 - [x] `.claude-plugin/plugin.json` — `homepage` and `repository`; also confirm `author` and `version`.
 - [ ] `LICENSE` and `NOTICE` — confirm the copyright holder.
 
-Names that must stay consistent across the plugin package and the docs (so the documented
-install works):
+Names that must stay consistent across the plugin package and the docs (so the planned
+plugin install works once it is published):
 
-- Marketplace name: **`ultracost`** and plugin name: **`ultracost`** → users install with
-  `/plugin install ultracost@ultracost`.
+- Marketplace name: **`ultracost`** and plugin name: **`ultracost`** → the plugin resolves
+  as `ultracost@ultracost`.
 - Command resolves to **`/ultracost:check`**.
 
 Sanity-check before any submission:
@@ -88,16 +88,11 @@ What to know:
 
 ### 2. Your own marketplace repo
 
-ultracost ships its own `.claude-plugin/marketplace.json`, so anyone can install immediately
-without waiting on review:
-
-```text
-/plugin marketplace add danielkremen818/ultracost
-/plugin install ultracost@ultracost
-```
-
-This is the install path the README leads with. It works the moment the repo is public —
-put it in the README and launch posts.
+ultracost ships its own `.claude-plugin/marketplace.json`, so the repo can serve as a
+self-hosted plugin marketplace once that install path is announced. **Not yet documented as
+user-facing** — the README leads with the npm CLI (`npx ultracost init`) for now. When the
+plugin distribution is published, surface the marketplace-add + install steps here and in the
+README and launch posts.
 
 ### 3. awesome-claude-code (hesreallyhim)
 

package/docs/TESTING.md

@@ -111,14 +111,8 @@ Two ways to load the plugin from your working copy. Option A registers a marketp
 
 ### Option A — local marketplace install
 
-Inside Claude Code:
-
-```text
-/plugin marketplace add ~/projects/ultracost
-/plugin install ultracost@ultracost
-```
-
-Or non-interactively from a shell:
+Register the working copy as a local marketplace and install from it (the dev/test path —
+not a user-facing install):
 
 ```bash
 claude plugin marketplace add ~/projects/ultracost
@@ -247,13 +241,8 @@ ultracost uninstall          # removes the CLAUDE.md block, hook, settings entry
 npm unlink -g ultracost
 
 # plugin install (Step 3, Option A)
-```
-
-Inside Claude Code:
-
-```text
-/plugin uninstall ultracost@ultracost
-/plugin marketplace remove ultracost
+claude plugin uninstall ultracost@ultracost
+claude plugin marketplace remove ultracost
 ```
 
 `--plugin-dir` (Step 3, Option B) leaves nothing behind — it ends with the session.

package/docs/architecture.md

@@ -5,6 +5,16 @@ exposed through **two delivery surfaces**: a Claude Code **plugin** (primary) an
 **npm CLI** (secondary). Both compile from the same policy, so the routing rules can never
 drift between them.
 
+<div align="center">
+
+<img src="../assets/architecture.svg" alt="ultracost architecture — policy.json compiles through the src/ core into a Claude Code plugin and an npm CLI; the guard and a PreToolUse cost gate verify every workflow stage at runtime" width="960">
+
+</div>
+
+> The diagram above is generated by [`scripts/generate-architecture-svg.py`](../scripts/generate-architecture-svg.py)
+> (offline; logos vendored under `scripts/icons/`). The mermaid source below is the
+> text-first reference.
+
 ```mermaid
 flowchart TD
     subgraph core["src/ — shared core"]
@@ -43,7 +53,7 @@ flowchart TD
 
 | | Plugin (primary) | npm CLI (secondary) |
 |---|---|---|
-| **Install** | `/plugin marketplace add danielkremen818/ultracost` → `/plugin install ultracost@ultracost` | `npx ultracost init` |
+| **Install** | ships in-repo; a separate install path is planned (not yet announced) | `npx ultracost init` (the install path today) |
 | **Routing guidance** | **`SessionStart` hook** injects the policy as context (no file mutation); a skill ships alongside for explicit reference | block injected into `~/.claude/CLAUDE.md` |
 | **Guard** | `/ultracost:check` command (runs `guard.js`) | `ultracost check` / `ultracost audit` |
 | **Policy injection** | `hooks/hooks.json` → `node "${CLAUDE_PLUGIN_ROOT}/templates/hooks/reinject.mjs"` (all `SessionStart` sources) | `node "<config>/ultracost/reinject.mjs"`, registered in `settings.json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracost",
-  "version": "0.2.0",
+  "version": "0.2.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": {