fathom-cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,157 @@
+# fathom-cli
+
+Workflow intelligence for AI-augmented development. Estimate token costs before work, automatically track actuals during work, reconcile and calibrate after work, and build velocity benchmarks over time.
+
+```
+intake → estimate → build (tracked) → reconcile → calibrate → velocity
+```
+
+## Install
+
+```bash
+npm install -g fathom-cli
+```
+
+## Quick Start
+
+```bash
+# Estimate a feature in seconds
+fathom estimate "React dashboard with OAuth" --complexity L
+
+# Analyze a full spec with multiple features
+fathom analyze spec.md --project myapp
+
+# Scaffold tracking for an existing project
+fathom setup --project myapp
+
+# Import and auto-tag Claude Code sessions
+fathom track --project myapp
+
+# Compare estimates vs actuals
+fathom reconcile --project myapp
+
+# See velocity metrics
+fathom velocity --project myapp
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `fathom estimate <desc>` | Quick single-feature token + cost estimate |
+| `fathom analyze <spec>` | Parse spec, estimate all features, generate registry |
+| `fathom intake <text>` | Extract work items from raw feedback via Claude API |
+| `fathom track` | Import Claude Code sessions, auto-tag to features |
+| `fathom reconcile` | Compare estimates vs actuals per feature |
+| `fathom calibrate` | Show drift and suggest profile adjustments |
+| `fathom velocity` | Velocity metrics and benchmarks |
+| `fathom status` | Project overview with tracking data |
+| `fathom pricing` | Show current model pricing |
+| `fathom setup` | Scaffold `.claude/` skill + hooks + registry |
+| `fathom validate <spec>` | Validate spec file format |
+| `fathom init` | Initialize global config |
+
+## How It Works
+
+### 1. Estimate (Before Work)
+
+Write a spec with `### Feature:` headings, or just describe a feature:
+
+```bash
+fathom estimate "Build a real-time chat system with WebSocket support" --complexity L
+# → 205,865 tokens, $2.51 estimated cost, recommends Sonnet
+```
+
+Estimates use a calibrated model: base tokens per task type × complexity multiplier × overhead (context resend, tool calls, thinking, error recovery, planning, review).
+
+### 2. Track (During Work)
+
+Fathom automatically discovers Claude Code sessions from `~/.claude/projects/` and tags them to features using a 4-signal cascade:
+
+1. **Explicit feature ID** in conversation → 99% confidence
+2. **Git branch** pattern match → 85%
+3. **Keyword** match → 75%
+4. **File path** match → 70%
+
+Zero configuration needed — just run `fathom track`.
+
+### 3. Reconcile + Calibrate (After Work)
+
+```bash
+fathom reconcile --project myapp
+# Shows: Feature | Estimated | Actual | Drift% | Cost | Sessions
+
+fathom calibrate --project myapp
+# Shows: Feature | Drift | Suggested adjustment multiplier
+```
+
+Over time, your estimates get more accurate as the profiles learn from real data.
+
+### 4. Velocity Intelligence
+
+```bash
+fathom velocity --project myapp --benchmarks
+# "M-complexity React components: $0.85 avg, 1.1 days, 2.8 sessions"
+```
+
+## Dashboard
+
+Fathom includes a real-time web dashboard (Next.js + Convex) with 7 views: overview, projects, burn-down, intake queue, cost analytics, velocity benchmarks, and calibration health.
+
+```bash
+# Set up Convex sync (optional — CLI works fully offline)
+export CONVEX_URL=https://your-deployment.convex.cloud
+
+# All commands auto-sync when CONVEX_URL is set
+fathom analyze spec.md --project myapp  # → syncs estimates
+fathom track --project myapp            # → syncs actuals
+```
+
+See the [full repo](https://github.com/olivelliott/fathom) for dashboard setup.
+
+## Intake Pipeline
+
+Turn raw feedback into estimated, structured work items:
+
+```bash
+# From text
+fathom intake "Users say the calendar is slow and Zoom links are missing" --project myapp
+
+# From a file
+fathom intake --file meeting-notes.md --project myapp --markdown
+```
+
+Requires `ANTHROPIC_API_KEY` environment variable.
+
+## Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `ANTHROPIC_API_KEY` | For `intake` only | Claude API for work item extraction |
+| `CONVEX_URL` | Optional | Enable dashboard sync |
+
+## Spec Format
+
+Fathom parses markdown specs with `### Feature:` headings:
+
+```markdown
+### Feature: User Authentication
+- **Complexity**: L
+- **Category**: Infrastructure
+- **Description**: OAuth2 with Google + email/password login
+
+### Feature: Dashboard
+- **Complexity**: M
+- **Category**: Frontend
+- **Description**: Main dashboard with metrics and charts
+```
+
+## Links
+
+- [GitHub Repository](https://github.com/olivelliott/fathom)
+- [Roadmap](https://github.com/olivelliott/fathom/blob/main/ROADMAP.md)
+- [Report an Issue](https://github.com/olivelliott/fathom/issues)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Workflow intelligence for AI-augmented development — estimate, track, reconcile, calibrate",
   "type": "module",
   "bin": {