fathom-cli 0.2.4 → 0.3.1

package/README.md

@@ -1,28 +1,55 @@
 # fathom-cli
 
-Estimate AI token costs before work, track actuals during work, and calibrate your estimates after. One command runs the full loop.
+[![npm version](https://img.shields.io/npm/v/fathom-cli)](https://www.npmjs.com/package/fathom-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/olivelliott/fathom/blob/main/LICENSE)
 
-## Install
+**Know what your AI coding actually costs.** Estimate tokens before you build, track actuals while you build, calibrate so estimates get better over time.
 
 ```bash
 npm install -g fathom-cli
+fathom
 ```
 
-Add `ANTHROPIC_API_KEY` to your project's `.env` file (auto-loaded).
+## The Problem
+
+You're spending real money on AI coding and have zero visibility into where it goes. You don't know what a feature costs until the bill arrives. Overhead — context resends, tool calls, error recovery — is invisible.
+
+## What Fathom Does
+
+**Estimate** → token cost per feature, based on task type + complexity + overhead model
+
+**Track** → auto-imports sessions from Claude, GPT, Gemini, or any provider. Tags to features automatically.
+
+**Calibrate** → compares estimates to actuals, adjusts the model. Gets more accurate every cycle.
 
-## One Command
+```
+$ fathom estimate "add OAuth login with Google and GitHub"
+  ~42,000 tokens (~$0.84) — complexity: L, type: integration
+
+$ fathom track
+  3 sessions imported, 2 auto-tagged (auth-login: 89%, payment: 72%)
+
+$ fathom reconcile
+  auth-login: estimated 42K, actual 67K (1.6x over — error recovery overhead)
+
+$ fathom calibrate
+  adjusted integration overhead: 1.8x → 2.4x (based on 12 data points)
+```
+
+## One Command Workflow
 
 ```bash
 fathom
 ```
 
-That's it. `fathom` with no arguments walks through the entire workflow:
+With no arguments, `fathom` runs the full loop:
 
-1. **Intake** — extracts work items from your requirements, estimates tokens + cost
-2. **Build** — generates a context-rich prompt and launches Claude Code
-3. **Review** — tracks sessions, reconciles estimates vs actuals, calibrates
+1. **Intent** — captures what you're building, what matters, your budget and guardrails
+2. **Intake** — extracts work items, estimates tokens and cost
+3. **Build** — launches your AI tool with full context
+4. **Review** — tracks sessions, reconciles, calibrates
 
-New project? It auto-scaffolds everything. Returning project? Shows progress and offers contextual next steps:
+New project? Auto-scaffolds everything. Returning? Shows progress:
 
 ```
 $ fathom
@@ -30,65 +57,46 @@ $ fathom
   Fathom — myproject
   6/12 features complete (50%) — $8.40 of $14.20 spent
 
-  What would you like to do?
-  ❯ Continue building (next: payment-integration)
+  > Continue building (next: payment-integration)
     New intake — add more work
     Review — reconcile recent sessions
-    Status overview
-```
-
-Resume from any phase:
-
-```bash
-fathom --from build     # Skip intake
-fathom --from review    # Just track + reconcile + calibrate
-fathom --auto           # Skip all confirmations
 ```
 
-## Build Modes
+## Also Does
 
-Fathom offers three ways to build (choice is remembered):
+- **Model routing** — recommends Haiku/Sonnet/Opus based on task complexity and budget
+- **Tool config generation** — creates system prompts for Claude, Cursor, Copilot, Windsurf from your project intent
+- **Guardrail templates** — OWASP, WCAG, HIPAA, GDPR, PCI, SOC2 built-in
+- **MCP server** — use Fathom as tools inside any MCP-compatible editor
+- **Velocity benchmarks** — "auth features take 2.3 days and 85K tokens on average"
 
-- **Launch Claude Code** — opens Claude with full project context, priority queue, and feature details
-- **Worktree** — creates an isolated git branch per feature, launches Claude in it
-- **Manual** — prints the spec path and build prompt so you can build however you want
-
-## Individual Commands
-
-All commands also work standalone:
+## All Commands
 
 | Command | What it does |
 |---------|-------------|
-| `fathom` | **Full workflow** — intake → build → review |
-| `fathom intake` | Generate a spec from raw feedback (interactive) |
-| `fathom estimate <desc>` | Quick cost estimate for a single feature |
-| `fathom analyze <spec>` | Parse an existing spec and estimate all features |
-| `fathom setup` | Scaffold project tracking in `.claude/` |
-| `fathom track` | Import Claude Code sessions, auto-tag to features |
-| `fathom reconcile` | Compare estimates vs actuals |
-| `fathom calibrate` | Adjust profiles from real data |
-| `fathom velocity` | Throughput metrics and benchmarks |
+| `fathom` | Full workflow — intake, build, review |
+| `fathom estimate <desc>` | Quick cost estimate |
+| `fathom intake` | Requirements → estimated spec slices |
+| `fathom analyze <spec>` | Parse spec, estimate features |
+| `fathom track` | Import + auto-tag sessions |
+| `fathom reconcile` | Estimates vs actuals |
+| `fathom calibrate` | Adjust from real data |
+| `fathom velocity` | Throughput metrics |
 | `fathom status` | Project overview |
-| `fathom rename <name>` | Rename project across config files |
-| `fathom pricing` | Show model pricing |
+| `fathom pricing` | Model pricing table |
+| `fathom go` | Launch AI tool with context |
 
 ## Environment Variables
 
-Auto-loaded from `.env` in your project directory.
-
 | Variable | Purpose |
 |----------|---------|
-| `ANTHROPIC_API_KEY` | Required for `intake` and `estimate` |
-| `CONVEX_URL` | Optional — enables real-time dashboard sync |
-
-## Dashboard
-
-Optional web dashboard (Next.js + Convex) with project burn-down, velocity charts, cost analytics, and more. All CLI commands auto-sync when `CONVEX_URL` is set. See the [repo](https://github.com/olivelliott/fathom) for setup.
+| `ANTHROPIC_API_KEY` | For intake extraction |
+| `OPENAI_API_KEY` | Alternative provider |
+| `CONVEX_URL` | Optional — real-time dashboard |
 
-## Links
+## Part of Fathom
 
-- [GitHub](https://github.com/olivelliott/fathom)
-- [Issues](https://github.com/olivelliott/fathom/issues)
+`fathom-cli` wraps the [Fathom](https://github.com/olivelliott/fathom) headless packages into a CLI. Use the packages directly if you're building your own tooling.
 
 ## License