@rosh100yx/outlier 0.4.24 → 0.7.0

package/README.md

@@ -50,9 +50,27 @@
                                  └───────────┘
 ```
 **Step 1:** Developer delegates code generation to an AI agent (Claude Code, Cursor).  
-**Step 2:** Developer attempts to merge code into the main branch.  
-**Step 3:** The `outlier` Bouncer hook triggers. If AI reliance > 70%, the commit is physically blocked.  
-**Step 4:** A "Mentoring Emergency" is triggered, forcing the developer to solve an architectural challenge to prove mastery and prevent deskilling.  
+**Step 2:** `outlier` reads the local trace — git history + AI logs — already on the machine.  
+**Step 3:** It reports who wrote the code, what it cost, and your authorship limit.  
+**Step 4:** Optionally, a local git hook *warns* (never silently blocks) when AI authorship exceeds your limit, so you review before you merge.  
+
+### What it reads (and what it doesn't)
+
+`outlier` is local-first. It reads, from your own machine, only:
+
+- **`git log`** of the current repo — to count commits carrying a `Co-Authored-By` trailer (the AI-authorship share).
+- **Your Claude Code session transcripts** at `~/.claude/projects/<this-repo>/*.jsonl` — to sum token usage for the cost / cache / carbon estimate. (Falls back to `~/.claude/tokenomics-log.jsonl` if present.)
+
+It does **not** send anything anywhere — no API calls, no telemetry, no account. Your code and prompts never leave the machine. The only network action in the whole tool is *you* choosing to open a share link or a feedback issue.
+
+### How accurate is it?
+
+We are deliberately honest about this:
+
+- **Authorship** is an exact count of trailer-tagged commits, but it is a *proxy* for real human-vs-AI effort, and it **under-counts** when your agent doesn't write the `Co-Authored-By` trailer. A surprisingly low number usually means missing trailers, not that you wrote everything.
+- **Tokens** are exact when the transcripts are present; otherwise the cost/carbon section reads zero.
+- **Cost ($)** is exact when the log carries a cost field, otherwise a *rough* blended token estimate (labelled as such).
+- **Carbon** is a rough estimate (inference energy varies ~4–20× in the literature) and the per-region figure is a *counterfactual* — cloud inference runs on the provider's grid, not yours. Treat it as an order-of-magnitude signal, not an audit.
 
 ## What Outlier Adds
 `outlier` builds a coordination layer on top of native agent workflows.
@@ -70,8 +88,25 @@
 | `npx @rosh100yx/outlier` | Run the full AI reliance & capability audit |
 | `npx @rosh100yx/outlier authorship` | Scan git history for AI co-authorship ratio |
 | `npx @rosh100yx/outlier carbon` | Scan local logs for context waste & token costs |
-| `npx @rosh100yx/outlier capabilities` | Audit active MCPs, skills, and orchestrations |
+| `npx @rosh100yx/outlier capabilities` | Map what your agents can reach + blast radius |
 | `npx @rosh100yx/outlier policy` | Configure Personal, Team, or Enterprise guardrails in CI |
+| `npx @rosh100yx/outlier --json` | Machine-readable audit for agents, CI, and swarms |
+
+### For agents, CI & swarms (`--json`)
+
+`outlier --json` emits a clean, ANSI-free JSON audit and nothing else — so an agent (or a supervisor in a swarm) can read its own authorship, cost, carbon, and **blast radius** before it acts, and CI can gate on it. Local-first: it still never leaves the machine.
+
+```jsonc
+{
+  "tool": "outlier",
+  "authorship": { "aiPercent": 7.4, "provenance": "proxy" },
+  "cost": { "totalTokens": 137700000, "estUsd": 63.76, "provenance": "measured" },
+  "carbon": { "co2Kg": 0.10, "region": "Global Average", "provenance": "estimated" },
+  "reach": { "blastRadius": "HIGH", "toolCount": 13, "writeOrDeployCount": 5,
+             "reasons": ["can deploy to production", "can push to your remote repos"] },
+  "policy": { "aiCapPercent": 70, "status": "within" }
+}
+```
 
 ### The UX Flow
 If you run `npx @rosh100yx/outlier` directly, you'll instantly get your Thermal Receipt and a simple list of follow-up commands: