fathom-cli 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,8 @@
 # fathom-cli
 
-Estimate AI token costs before work, track actuals during work, and calibrate your estimates after. One command runs the full loop.
+> **Active development.** APIs and features may change between versions. We welcome feedback — run `fathom feedback` or see [FEEDBACK.md](../../FEEDBACK.md).
+
+The CLI for [Fathom](https://github.com/olivelliott/fathom) -- the headless intelligence layer for AI-augmented development. One command runs the full loop: capture intent, estimate tokens, route to the right model, build with full context, track actuals, reconcile, calibrate.
 
 ## Install
 
@@ -8,8 +10,6 @@ Estimate AI token costs before work, track actuals during work, and calibrate yo
 npm install -g fathom-cli
 ```
 
-Add `ANTHROPIC_API_KEY` to your project's `.env` file (auto-loaded).
-
 ## One Command
 
 ```bash
@@ -18,22 +18,23 @@ fathom
 
 That's it. `fathom` with no arguments walks through the entire workflow:
 
-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 from your requirements, estimates tokens and cost
+3. **Build** -- generates a context-rich prompt and launches your AI tool of choice
+4. **Review** -- tracks sessions, reconciles estimates vs actuals, calibrates
 
 New project? It auto-scaffolds everything. Returning project? Shows progress and offers contextual next steps:
 
 ```
 $ fathom
 
-  Fathom — myproject
-  6/12 features complete (50%) — $8.40 of $14.20 spent
+  Fathom -- myproject
+  6/12 features complete (50%) -- $8.40 of $14.20 spent
 
   What would you like to do?
-  ❯ Continue building (next: payment-integration)
-    New intake — add more work
-    Review — reconcile recent sessions
+  > Continue building (next: payment-integration)
+    New intake -- add more work
+    Review -- reconcile recent sessions
     Status overview
 ```
 
@@ -42,35 +43,29 @@ Resume from any phase:
 ```bash
 fathom --from build     # Skip intake
 fathom --from review    # Just track + reconcile + calibrate
-fathom --auto           # Skip all confirmations
 ```
 
-## Build Modes
-
-Fathom offers three ways to build (choice is remembered):
-
-- **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 |
+| Command | Description |
 |---------|-------------|
-| `fathom` | **Full workflow** — intake → build → review |
-| `fathom intake` | Generate a spec from raw feedback (interactive) |
+| `fathom` | Full workflow -- intake, build, review (default) |
+| `fathom intake` | Turn raw feedback into structured spec slices with estimates |
+| `fathom analyze <spec>` | Parse a spec file and estimate all features |
 | `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 setup` | Scaffold project tracking |
+| `fathom init` | Initialize a new Fathom project |
+| `fathom track` | Import sessions, auto-tag to features |
 | `fathom reconcile` | Compare estimates vs actuals |
-| `fathom calibrate` | Adjust profiles from real data |
+| `fathom calibrate` | Adjust task profiles from real data |
 | `fathom velocity` | Throughput metrics and benchmarks |
+| `fathom project` | Manage project configuration |
 | `fathom status` | Project overview |
-| `fathom rename <name>` | Rename project across config files |
 | `fathom pricing` | Show model pricing |
+| `fathom validate` | Validate project configuration |
+| `fathom rename <name>` | Rename project across config files |
+| `fathom research` | Research tasks with AI assistance |
+| `fathom feedback` | How to report bugs and request features |
 
 ## Environment Variables
 
@@ -78,17 +73,23 @@ 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 |
+| `ANTHROPIC_API_KEY` | Required for intake extraction and AI-powered estimation |
+| `OPENAI_API_KEY` | Alternative provider for intake extraction |
+| `CONVEX_URL` | Optional -- enables real-time dashboard sync |
+
+## Feedback
 
-## Dashboard
+```bash
+fathom feedback
+fathom feedback --bug "description of the issue"
+fathom feedback --feature "description of what you'd like"
+```
 
-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.
+See [FEEDBACK.md](https://github.com/olivelliott/fathom/blob/main/FEEDBACK.md) for details.
 
-## Links
+## Part of the Fathom ecosystem
 
-- [GitHub](https://github.com/olivelliott/fathom)
-- [Issues](https://github.com/olivelliott/fathom/issues)
+`fathom-cli` is a consumer of the Fathom packages -- it wires all the headless intelligence into a command-line interface. See the [Fathom README](https://github.com/olivelliott/fathom) for the full picture.
 
 ## License