ultracost 0.2.0

package/bin/cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadPolicy } from '../src/policy.js';
+import { scan, fixFile, collectFiles, auditScripts } from '../src/guard.js';
+import { estimateFile } from '../src/estimate.js';
+import { refreshPricing, writePricingToPolicy, DEFAULT_PRICING_URL } from '../src/pricing.js';
+import { install, uninstall, readSettings } from '../src/install.js';
+import {
+  ROOT, CLAUDE_MD, HOOK_PATH, POLICY_PATH, SETTINGS, PROJECTS_DIR, tilde, MARKER_START
+} from '../src/paths.js';
+import { c, log, ok, warn, err, info } from '../src/log.js';
+
+const version = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
+const argv = process.argv.slice(2);
+const cmd = argv[0] || 'help';
+const has = (flag) => argv.includes(flag);
+const positional = argv.slice(1).filter((a) => !a.startsWith('-'));
+
+const money = (x) => '$' + Number(x).toFixed(4);
+
+try {
+  await dispatch();
+} catch (e) {
+  err(e.message);
+  process.exit(1);
+}
+
+async function dispatch() {
+  switch (cmd) {
+    case 'init': case 'install': cmdInit(); break;
+    case 'check': case 'guard': cmdCheck(); break;
+    case 'audit': cmdAudit(); break;
+    case 'estimate': cmdEstimate(); break;
+    case 'pricing': await cmdPricing(); break;
+    case 'status': cmdStatus(); break;
+    case 'doctor': cmdDoctor(); break;
+    case 'uninstall': cmdUninstall(); break;
+    case '-v': case '--version': case 'version': log(version); break;
+    case 'help': case '-h': case '--help': cmdHelp(); break;
+    default:
+      err(`Unknown command: ${cmd}`);
+      cmdHelp();
+      process.exit(1);
+  }
+}
+
+function cmdHelp() {
+  log(`
+${c.bold('ultracost')} ${c.dim('v' + version)} — per-stage model routing for Claude Code workflows
+
+${c.bold('Usage')}
+  ultracost init                 Install routing rules, hook, and default policy
+  ultracost check [path]         Scan workflow scripts for unpinned agent() stages
+  ultracost audit [dir]          Report pin stats across your real workflow scripts
+  ultracost estimate <script>    Estimate agents, model mix, and cost vs all-Opus baseline
+  ultracost pricing [refresh]    Show pricing, or refresh it from Anthropic's official page
+  ultracost status               Show active policy and install state
+  ultracost doctor               Diagnose the installation
+  ultracost uninstall            Remove everything ultracost installed
+
+${c.bold('check flags')}
+  --json                        Machine-readable output
+  --fix                         Insert the default model on unpinned stages
+  --quiet                       Only print problems
+
+${c.bold('estimate / audit flags')}
+  --json                        Machine-readable output
+  ${c.dim('audit default dir:')} ${tilde(PROJECTS_DIR)}/**/workflows/scripts/*.js
+
+${c.bold('pricing flags')}
+  refresh                       Fetch official prices and update the installed policy
+  --url <url>                   Override the pricing page URL
+
+${c.bold('Policy')}
+  Edit ${tilde(POLICY_PATH)} to change tiers/rules/effort/pricing, then re-run ${c.cyan('ultracost init')}.
+`);
+}
+
+function cmdInit() {
+  const { policy, source } = loadPolicy();
+  const r = install(policy, { force: has('--force') });
+  log(`${c.bold('ultracost init')}\n`);
+  ok(`policy: ${r.policy} (${tilde(POLICY_PATH)})`);
+  ok(`rules: ${r.rules} (${tilde(CLAUDE_MD)})`);
+  ok(`hook: ${r.hook} (${tilde(HOOK_PATH)})`);
+  if (r.register === 'invalid') warn(`settings.json is invalid JSON — register the hook manually`);
+  else ok(`hook ${r.register} in ${tilde(SETTINGS)}`);
+  info(`\nactive policy from ${tilde(source)} — new sessions pick this up immediately.`);
+}
+
+function cmdCheck() {
+  const target = positional[0] || process.cwd();
+  const { policy } = loadPolicy();
+
+  if (has('--fix')) {
+    const targets = collectFiles(target);
+    let fixed = 0;
+    for (const f of targets) fixed += fixFile(f, policy);
+    ok(`applied ${fixed} fix(es) across ${targets.length} file(s)`);
+  }
+
+  const { findings, files } = scan(target, policy);
+  const errors = findings.filter((f) => f.severity === 'error');
+  const warns = findings.filter((f) => f.severity === 'warn');
+
+  if (has('--json')) {
+    log(JSON.stringify({ target, files: files.length, findings }, null, 2));
+    process.exit(errors.length ? 1 : 0);
+  }
+
+  if (!findings.length) {
+    ok(`${files.length} file(s) scanned — every agent() stage pins a model.`);
+    return;
+  }
+  for (const f of findings) {
+    const tag = f.severity === 'error' ? c.red(f.code) : c.yellow(f.code);
+    log(`${c.dim(tilde(f.file) + ':' + f.line + ':' + f.column)}  ${tag}  ${f.message}`);
+    if (!has('--quiet')) log(`    ${c.dim(f.snippet)}`);
+  }
+  log('');
+  log(`${errors.length} error(s), ${warns.length} warning(s) in ${files.length} file(s).`);
+  if (errors.length) {
+    info(`Fix with: ultracost check ${positional[0] || '.'} --fix`);
+    process.exit(1);
+  }
+}
+
+function cmdAudit() {
+  const base = positional[0] || PROJECTS_DIR;
+  const { policy } = loadPolicy();
+  const { files, totals } = auditScripts(base, policy);
+
+  if (has('--json')) {
+    log(JSON.stringify({ base, ...totals }, null, 2));
+    return;
+  }
+
+  log(`${c.bold('ultracost audit')}\n`);
+  if (!files.length) {
+    warn(`no workflow scripts found under ${tilde(base)}`);
+    info(`looked for ${tilde(base)}/**/workflows/scripts/*.js`);
+    return;
+  }
+  info(`scanned ${totals.scripts} script(s) under ${tilde(base)}\n`);
+  const pct = (totals.unpinnedRatio * 100).toFixed(1);
+  log(`  agent() stages   ${totals.stages}`);
+  log(`  pinned           ${c.green(totals.pinned)}`);
+  log(`  ${c.red('unpinned')}         ${c.red(totals.unpinned)}   ${c.dim('(UC001/UC002 — inherit the session model)')}`);
+  log(`  banned           ${totals.banned}   ${c.dim('(UC003)')}`);
+  log(`  inherit          ${totals.inherit}   ${c.dim('(UC004)')}`);
+  log(`  dynamic          ${totals.dynamic}   ${c.dim('(UC005 — options is a variable)')}`);
+  log('');
+  log(`  ${c.bold('unpinned ratio')}   ${pct}%`);
+}
+
+function cmdEstimate() {
+  const target = positional[0];
+  if (!target) { err('usage: ultracost estimate <workflow-script.js> [--json]'); process.exit(1); }
+  if (!existsSync(target)) { err(`not found: ${target}`); process.exit(1); }
+  const { policy } = loadPolicy();
+  const est = estimateFile(target, policy);
+
+  if (has('--json')) {
+    log(JSON.stringify({ target, ...est }, null, 2));
+    return;
+  }
+
+  const a = est.agents;
+  const fan = a.fanoutGroups ? ` + ${a.fanoutGroups} fan-out group(s) x ~${a.assumedPerFanout} = ~${a.assumedTotal}` : '';
+  const mix = Object.entries(est.modelMix).map(([k, v]) => `${v}x ${k}`).join(', ') || 'none';
+  log(`${c.bold('ultracost estimate')}  ${c.dim(tilde(target))}\n`);
+  log(`  agents      ${a.known} fixed${fan}`);
+  log(`  model mix   ${mix}`);
+  log('');
+  log(`  baseline (all ${est.assumptions.sessionModel})   ${money(est.cost.baseline)}`);
+  log(`  tiered (ultracost)        ${money(est.cost.tiered)}`);
+  log(`  ${c.green('savings')}                   ${c.green(money(est.cost.savings))}  ${c.green('(' + est.cost.savingsPct + '%)')}`);
+  log('');
+  info(`estimate; pricing as of ${est.assumptions.pricingAsOf || 'n/a'}; fan-out assumes ~${a.assumedPerFanout} items/group; unpinned stages inherit ${est.assumptions.sessionModel} (no saving).`);
+  if (est.cost.savingsPct === 0 && est.stages.length) info('tip: pin cheaper tiers (sonnet) on mechanical stages to cut cost.');
+}
+
+async function cmdPricing() {
+  const { policy } = loadPolicy();
+  if (positional[0] === 'refresh') {
+    const urlIdx = argv.indexOf('--url');
+    const url = urlIdx !== -1 ? argv[urlIdx + 1] : undefined;
+    info(`fetching official pricing from ${url || policy.pricing?._source || DEFAULT_PRICING_URL} ...`);
+    const updated = await refreshPricing(policy, { url });
+    const path = writePricingToPolicy(updated);
+    ok(`pricing updated in ${tilde(path)} (as of ${updated._asOf})`);
+    showPricing(updated);
+    return;
+  }
+  showPricing(policy.pricing);
+}
+
+function showPricing(pr) {
+  log(`${c.bold('ultracost pricing')} ${c.dim('(USD per million tokens)')}`);
+  if (pr?._source) info(`source: ${pr._source}`);
+  if (pr?._asOf) info(`as of:  ${pr._asOf}`);
+  for (const k of ['opus', 'sonnet', 'haiku']) {
+    if (pr?.[k]) log(`  ${c.cyan(k)}: $${pr[k].input} in / $${pr[k].output} out`);
+  }
+  info('refresh from the official page: ultracost pricing refresh');
+}
+
+function cmdStatus() {
+  const { policy, source } = loadPolicy();
+  log(`${c.bold('ultracost status')}\n`);
+  info(`policy source: ${tilde(source)}`);
+  log(`${c.bold('tiers')} (never: ${policy.neverUse.join(', ') || 'none'})`);
+  for (const [name, t] of Object.entries(policy.tiers)) {
+    const mark = name === policy.default ? c.green(' (default)') : '';
+    log(`  ${c.cyan(name)}: ${t.model}${t.effort ? ' @ ' + t.effort : ''}${mark}`);
+  }
+  log(`\n${c.bold('install')}`);
+  state(existsSync(CLAUDE_MD) && readFileSync(CLAUDE_MD, 'utf8').includes(MARKER_START), `rules in ${tilde(CLAUDE_MD)}`);
+  state(existsSync(HOOK_PATH), `hook at ${tilde(HOOK_PATH)}`);
+  const settings = readSettings();
+  const registered = settings && settings.hooks?.SessionStart?.some((h) => h.hooks?.some((hh) => hh.command?.includes('ultracost')));
+  state(!!registered, `hook registered in settings.json`);
+}
+
+function cmdDoctor() {
+  log(`${c.bold('ultracost doctor')}\n`);
+  let issues = 0;
+  const need = (cond, msg) => { if (cond) ok(msg); else { warn(msg); issues++; } };
+
+  try {
+    const { policy } = loadPolicy();
+    ok(`policy is valid (${Object.keys(policy.tiers).length} tiers)`);
+  } catch (e) {
+    err(e.message); issues++;
+  }
+  need(existsSync(CLAUDE_MD) && readFileSync(CLAUDE_MD, 'utf8').includes(MARKER_START), `routing rules present in ${tilde(CLAUDE_MD)}`);
+  need(existsSync(HOOK_PATH), `re-inject hook installed`);
+
+  const settings = readSettings();
+  if (settings === undefined) { err(`${tilde(SETTINGS)} is invalid JSON`); issues++; }
+  else {
+    const registered = settings?.hooks?.SessionStart?.some((h) => h.hooks?.some((hh) => hh.command?.includes('ultracost')));
+    need(!!registered, `hook registered for SessionStart`);
+    if (settings?.permissions?.defaultMode && settings.permissions.defaultMode !== 'auto') {
+      info(`tip: permission mode is "${settings.permissions.defaultMode}" — workflow subagents may prompt`);
+    }
+  }
+
+  log('');
+  if (issues === 0) log(c.green('All clear. Routing is configured.'));
+  else { log(c.red(`${issues} issue(s).`)); info('Run: ultracost init'); process.exit(1); }
+}
+
+function cmdUninstall() {
+  const r = uninstall();
+  log(`${c.bold('ultracost uninstall')}\n`);
+  for (const [k, v] of Object.entries(r)) info(`${k}: ${v}`);
+  ok('done.');
+}
+
+function state(good, label) {
+  log(`  ${good ? c.green('on ') : c.red('off')} ${label}`);
+}

package/docs/ESTIMATES.md

@@ -0,0 +1,191 @@
+# Cost estimate, dynamic effort, and the pre-flight gate
+
+ultracost does three things beyond routing: it **estimates** the cost of a workflow
+before it runs, it has Claude pick a **per-stage effort** level, and it puts a
+**pre-flight gate** in front of a workflow launch so you can approve, cancel, or
+restructure it.
+
+## `ultracost estimate <script>`
+
+Static analysis (the same parser as `check`) reads every `agent()` stage, its pinned
+`model` and `effort`, and whether it is a fan-out, then prices it.
+
+```text
+ultracost estimate ./workflow.js
+
+  agents      4 fixed + 1 fan-out group(s) x ~5 = ~9
+  model mix   3x opus, 6x sonnet
+
+  baseline (all opus)   $0.9000
+  tiered (ultracost)        $0.5304
+  savings                   $0.3696  (41%)
+```
+
+- **baseline** = every stage on the session model (opus @ xhigh) — what an unguided
+  ultracode run does.
+- **tiered** = the per-stage `model` + `effort` actually pinned. Unpinned stages
+  inherit the session model, so they contribute **no** savings (a built-in incentive
+  to pin them).
+- `--json` emits the full breakdown for CI or tooling.
+
+### The cost model (and its assumptions)
+
+`cost(stage) = inputTokens/1e6 * price.input + outputTokens * effortMultiplier / 1e6 * price.output`
+
+Defaults (all editable in `policy.json` under `estimation`):
+
+- `tokensPerStage`: `{ input: 2000, output: 1200 }`
+- `effortOutputMultiplier`: `low 0.4, medium 1, high 1.8, xhigh 3, max 4`
+- `assumedFanout`: `5` (items per fan-out group, since the real count is a runtime value)
+
+These are deliberately simple per-stage assumptions, **not** a measured token count.
+Treat the dollar figures as relative estimates (tiered vs baseline), not a bill. The
+savings **percentage** is robust to the absolute token assumption; the absolute dollars
+scale with it.
+
+## Pricing is official-sourced and refreshable
+
+Prices live in `policy.json` under `pricing`, with provenance:
+
+```json
+"pricing": {
+  "_source": "https://platform.claude.com/docs/en/about-claude/pricing",
+  "_asOf": "2026-06-13",
+  "_models": { "opus": "Claude Opus 4.8", "sonnet": "Claude Sonnet 4.6", "haiku": "Claude Haiku 4.5" },
+  "opus":   { "input": 5, "output": 25 },
+  "sonnet": { "input": 3, "output": 15 },
+  "haiku":  { "input": 1, "output": 5 }
+}
+```
+
+The committed numbers are a snapshot of Anthropic's official pricing page. Refresh them
+any time:
+
+```text
+ultracost pricing            # show current prices + source + as-of date
+ultracost pricing refresh    # fetch the official page, parse, and update policy.json
+```
+
+The estimate reads prices from `policy.json` (offline, deterministic) — there is **no**
+network call on the estimate hot path, so it works in CI and offline. `refresh` is the
+only command that reaches the network, and only when you run it. Bump the model version
+strings in `_models` when a new model ships, then `refresh`.
+
+## Dynamic per-stage effort
+
+Each stage also gets an `effort`, chosen as the **lowest level that fits**, bounded by
+the model (`sonnet` up to `high`, `opus` up to `xhigh`):
+
+| effort | use for |
+|--------|---------|
+| `low`    | trivial deterministic work: listing/globbing, simple extraction, formatting |
+| `medium` | light judgment on a small surface: a single straightforward edit, summarizing one source |
+| `high`   | standard coding/analysis: most refactors, per-file review, non-trivial tests |
+| `xhigh`  | hard reasoning: cross-file architecture, adversarial review, planning, final synthesis |
+
+Effort feeds the estimate (higher effort = more output tokens = more cost), so dialing a
+mechanical stage down to `low` is visible savings.
+
+## The pre-flight gate (approve / cancel / modify)
+
+Before launching a workflow, the injected policy has Claude: draft the script, run
+`ultracost estimate` on it, then use the **AskUserQuestion** tool to offer three
+options — **Approve** (launch), **Cancel** (don't), **Modify** (restructure to cut cost,
+re-estimate, ask again).
+
+### Two gate mechanisms, and an honest limitation
+
+1. **Deterministic `PreToolUse` gate (default, hard).** `templates/hooks/workflow-gate.mjs`
+   is registered by the plugin (`hooks/hooks.json`) on the `Workflow` tool. It runs the
+   static guard **and** the cost estimate on the drafted script, then returns a permission
+   decision so **every** workflow launch pauses with the numbers — independent of whether
+   the model decides to ask. This is the enforcement layer.
+   - **Where you see the number.** The gate emits the estimate as a top-level
+     `systemMessage` (the documented hook→user channel) **and** as the
+     `permissionDecisionReason`. The `systemMessage` is what reliably renders: Claude Code
+     currently does **not** display the `permissionDecisionReason` for an `"ask"` decision
+     in the TUI ([anthropics/claude-code#24059](https://github.com/anthropics/claude-code/issues/24059)),
+     so without `systemMessage` the cost would be computed but invisible. For `strict`/`deny`
+     the reason renders too. The native "Run a dynamic workflow?" confirmation is Claude
+     Code's own dialog — the ultracost line appears as a system message around it, not inside it.
+   - **It leads with the problem.** If any stage is unpinned/banned/`inherit`, the message
+     opens with `⚠ ultracost: N/M stage(s) NOT pinned -> will inherit <session model>` before
+     the estimate — so an accidental all-Opus fan-out is impossible to miss. (This is the
+     exact failure a live test caught: a `pipeline(...)` build/verify/fix workflow where the
+     model pinned *no* stage.)
+   - **Mode-aware by default — hard in every permission mode.** A `PreToolUse` hook runs in
+     *all* permission modes; bypass only auto-approves the `ask` path, while a `deny` is
+     honored regardless of mode. The gate reads `permission_mode` from the event and adapts:
+
+     | mode | clean (all pinned) | problem (unpinned/banned/`inherit`) |
+     |---|---|---|
+     | `default` / `acceptEdits` / `auto` | ask + estimate | **ask** + ⚠ warning (an ask surfaces here) |
+     | `bypassPermissions` / `dontAsk` | ask + estimate | **deny** (an ask wouldn't pause, so block) |
+     | `plan` | (a workflow doesn't launch in plan mode) | — |
+
+   - **Env overrides (`ULTRACOST_GATE`):**
+     - *unset* (default) — the mode-aware behavior above.
+     - `strict` — **deny** on any problem in *every* mode; `ask` when all pinned.
+     - `ask` — never escalate to deny; always `ask` (opt out of the mode-aware deny).
+     - `off` — disable entirely, for non-interactive runs (`claude -p`, Auto Mode, CI),
+       where an unanswered `ask` is denied (the gate fails closed). Disable it there on
+       purpose rather than letting an unpriced fan-out through silently.
+   - **Residual limitation:** Claude Code currently skips `PreToolUse` hooks for subagents
+     dispatched under `bypassPermissions`
+     ([anthropics/claude-code#43772](https://github.com/anthropics/claude-code/issues/43772)),
+     so a nested agent there can evade the gate. The top-level `Workflow` launch is still gated.
+2. **AskUserQuestion-mediated (nicer UX, model-driven).** Driven by the always-on
+   `SessionStart` policy injection. This renders the arrow-key 3-option
+   Approve/Cancel/Modify menu, but it is *model-mediated* — Claude runs it because the
+   policy is in context. It only appears in an interactive session. The hard hook above
+   is what guarantees a stop even when this is skipped.
+
+A plugin hook **cannot** render a fully custom arrow-key menu directly — that is an open
+Claude Code feature request
+([anthropics/claude-code#52343](https://github.com/anthropics/claude-code/issues/52343)).
+Hooks can only block, allow, or escalate to the built-in allow/deny prompt. The custom
+3-option Approve/Cancel/Modify menu therefore comes from `AskUserQuestion`, which the
+model invokes, rather than from the kernel. This is documented, not hidden.
+
+## Covered cases
+
+- Fixed stages, fan-out stages (`.map`/`.flatMap`/`Array.from` **and `pipeline(items, ...stages)`**,
+  whose every stage runs once per item), nested `parallel([...])` thunks (fixed count),
+  pinned and unpinned stages, banned/`inherit` models, and prompt text that literally
+  contains `agent(` (ignored). See `tests/estimate.test.js`.
+
+> `pipeline(items, ...stages)` is the Workflow API's per-item fan-out primitive — each
+> stage's `agent()` runs once for every item in `items`. The guard and estimate treat
+> those stages as fan-out (counted as `assumedFanout` each, like `.map`). This is the
+> exact shape an `ultracode` build/verify/fix workflow takes, so without it the agent
+> count and cost are badly under-reported.
+
+## Limitations
+
+- **Estimates, not bills.** Per-stage token counts are assumptions; the absolute dollars
+  scale with them. The tiered-vs-baseline ratio is the trustworthy signal.
+- **Fan-out is a range.** The real item count is a runtime value; the estimate uses
+  `assumedFanout` and the total scales linearly with the real count.
+- **Dynamic options** (`agent(task, opts)` where `opts` is a variable) can't be read
+  statically — the guard reports `UC005` and the estimate treats the stage as unpinned.
+- **The gate's pause needs a TUI; deny does not.** The hard `PreToolUse` gate is on by
+  default. In interactive modes that surface an ask (`default`/`acceptEdits`/`auto`) it
+  pauses with the estimate; in `bypassPermissions`/`dontAsk` it auto-escalates an unpinned
+  workflow to a `deny` (honored in every mode). In non-interactive runs an unanswered `ask`
+  is denied, so set `ULTRACOST_GATE=off` there. The 3-option AskUserQuestion menu needs a
+  TUI session.
+
+## Validation (live, multi-domain)
+
+Drafted by Claude under the plugin across domains; each script guard-clean (every stage
+pinned), with dynamic effort, then measured by `ultracost estimate`:
+
+| Domain | stages (model @ effort) | est. baseline (all-opus) | est. tiered | savings |
+|--------|--------------------------|--------------------------|-------------|---------|
+| Code refactor | opus@xhigh, opus@high, opus@xhigh | $0.30 | $0.264 | 12% |
+| Web research | opus@high, sonnet@medium, opus@xhigh | $0.30 | $0.188 | 37% |
+| CSV data | sonnet@low, sonnet@high (fan-out), opus@xhigh | $0.70 | $0.305 | 56% |
+| Docs gen | sonnet@low, opus@high, opus@xhigh | $0.30 | $0.177 | 41% |
+
+Savings track how much of the work is mechanical/fan-out (droppable to sonnet + lower
+effort) versus genuine reasoning that stays on opus — exactly as intended.

package/docs/PUBLISHING.md

@@ -0,0 +1,164 @@
+# Publishing & recognition
+
+How to ship ultracost and get it found, ordered by impact. Do the pre-publish checklist
+first, then work down the distribution list.
+
+> **External-site note.** Anthropic plugin/marketplace facts below were verified against
+> the official docs (`code.claude.com/docs/en/plugins`,
+> `code.claude.com/docs/en/plugin-marketplaces`) on **2026-06-14**. Third-party sites
+> (awesome lists, auto-trackers) come from the project plan — confirm their current
+> submission rules on each site before relying on them, since they change.
+
+---
+
+## Pre-publish checklist
+
+The GitHub handle is set to `danielkremen818` across the repo. If you fork or move it,
+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] `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):
+
+- Marketplace name: **`ultracost`** and plugin name: **`ultracost`** → users install with
+  `/plugin install ultracost@ultracost`.
+- Command resolves to **`/ultracost:check`**.
+
+Sanity-check before any submission:
+
+```bash
+claude plugin validate .            # marketplace.json schema + referenced plugin.json
+claude plugin validate ./           # (same, repo root)
+npm test                            # unit tests
+node bin/cli.js check examples/workflow.good.js
+```
+
+### GitHub repo "About" (sidebar metadata)
+
+When the remote is created, set these on the repo's **About** panel (the gear icon at
+the top-right of the repo page) so the listing reads well and the auto-trackers index it.
+
+**Description** (one line):
+
+```text
+Per-stage model routing for Claude Code ultracode dynamic workflows — keeps a fan-out from silently running every subagent on Opus 4.8.
+```
+
+**Topics:**
+
+```text
+claude-code, claude-code-plugin, ultracode, dynamic-workflows, subagents, model-routing, cost-optimization, anthropic, claude
+```
+
+**Website:** the npm package page once published (`https://www.npmjs.com/package/ultracost`).
+
+---
+
+## Distribution, ordered by impact
+
+### 1. Official community marketplace (highest reach)
+
+Anthropic runs a public community marketplace, `anthropics/claude-plugins-community`, that
+users add with `/plugin marketplace add anthropics/claude-plugins-community` and install
+from as `@claude-community`. Approved plugins also surface on `claude.com/plugins`.
+
+Submit through the in-app directory form. The project plan points to the short link
+**`clau.de/plugin-directory-submission`**. As of 2026-06-14 the official docs list these
+canonical submission entry points:
+
+- **claude.ai:** `claude.ai/admin-settings/directory/submissions/plugins/new` — requires a
+  Team or Enterprise org with directory-management access (org Owners have it by default).
+- **Console:** `platform.claude.com/plugins/submit` — for individual authors not in a
+  Team/Enterprise org.
+
+What to know:
+
+- Submissions go through an **automated safety screening** plus the same
+  `claude plugin validate` check the pipeline runs — pass it locally first.
+- Approved plugins are pinned to a specific commit SHA in the community catalog; CI bumps the
+  pin as you push. The public catalog **syncs nightly**, so expect a delay between approval
+  and your plugin appearing.
+- The separate **official** marketplace (`claude-plugins-official`) is curated by Anthropic
+  at its discretion — there's no application; the submission form does not add to it.
+
+### 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.
+
+### 3. awesome-claude-code (hesreallyhim)
+
+A large, high-traffic curated list (the plan notes ~45k stars — verify the current count).
+Submit via the repo's contribution form/PR process. Their bar, which ultracost already meets:
+
+- **Evidence-based claims** — lead with the audit finding (most real `ultracode` stages are
+  unpinned; even Anthropic's bundled `deep-research` workflow pins zero stages) and a short
+  demo (`ultracost audit ~/.claude/projects`).
+- **OSS license** — MIT.
+- **No telemetry, no network calls** — ultracost is a local static analyzer + file installer;
+  it makes no outbound requests.
+
+### 4. Auto-trackers (passive listings)
+
+These sites index public Claude Code plugin/marketplace repos automatically; a public repo
+with a valid `marketplace.json` is usually enough. Per the plan:
+
+- `awesomeclaudeplugins.com`
+- `claudecodemarketplace.com`
+- `claudecodeplugins.dev`
+
+Confirm each site's current intake (some have a submit form, some scrape) before assuming a
+listing.
+
+### 5. npm publish + GitHub release
+
+CI is already wired: pushing a `vX.Y.Z` tag runs the tests, creates a GitHub Release with
+generated notes, and publishes to npm when `NPM_TOKEN` is set (see
+`.github/workflows/release.yml`).
+
+```bash
+# bump version in package.json (and plugin.json), update CHANGELOG.md, commit, then:
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+This makes `npx ultracost ...` work for the CLI/CI audience and gives the plugin a citable
+release.
+
+### 6. Launch posts
+
+Lead every post with the evidence line:
+
+> Even Anthropic's bundled `deep-research` workflow runs every stage on your session model —
+> in a scan of ~22 real `ultracode` scripts, almost none pinned a model. ultracost makes the
+> per-stage routing explicit and verifiable.
+
+Channels:
+
+- **r/ClaudeAI** — problem + the `ultracost audit` screenshot + install.
+- **Anthropic Discord** — relevant plugin/workflow channels.
+- **#claudecode on X** — the evidence line + a short demo clip.
+- **GitHub Discussions** — a longer write-up linking the audit output and `docs/ultracode.md`.
+
+---
+
+## Post-launch
+
+- Watch the community catalog for your plugin to appear (nightly sync) and link it once live.
+- Keep `version` bumped on every plugin change, or users won't get updates (Claude Code skips
+  re-install when the resolved version is unchanged).
+- Re-run `ultracost audit` periodically as Claude Code evolves — the headline stat is the best
+  proof the problem still exists.