segreant 0.1.0 → 0.2.0

package/docs/CAPABILITY-EVIDENCE-CONTRACT.md

@@ -49,8 +49,15 @@ card into provider billing, or alter signed/canonical evidence bytes.
   traffic, applies local soft/hard/velocity controls, and serves a local CLI and
   dashboard.
 - A Segreant-process egress boundary starts in `local_locked` mode: it permits
-  literal loopback HTTP(S) targets only and refuses non-loopback targets before
-  DNS. `controlled_cloud` mode permits a cloud request only when an enabled,
+  literal loopback HTTP(S) targets and two built-in routes, the same in every
+  mode: a GET of the public price list at its exact fixed URL (purpose
+  `pricing_refresh`, no query or fragment, rule id `segreant-builtin-price-list`),
+  and the user's own proxied requests to the official provider APIs
+  (`https://api.anthropic.com` and `https://api.openai.com`, purpose
+  `provider_inference`, GET or POST under `/v1/`, rule ids
+  `segreant-builtin-provider-*`). Both need a public DNS answer and are receipted.
+  Every other non-loopback target is refused before DNS in `local_locked`; in
+  `controlled_cloud` mode a further cloud request is permitted only when an enabled,
   exact rule matches its purpose, data class, method, HTTPS origin, and leading
   path; it pins the selected public IP for the dial, follows no redirect, and,
   after policy evaluation, writes a redacted hash-chained `preflight_allowed`
@@ -107,9 +114,16 @@ card into provider billing, or alter signed/canonical evidence bytes.
   and every other causal gate passes. Until a real protocol is registered,
   executed, and qualified, the product has no causal result to present.
   Neither path routes providers or changes budgets automatically.
-- The browser dashboard has no third-party assets or analytics and is intended
-  to expose a preview before consequential local changes. The CLI remains the
-  reference surface while GUI parity is completed.
+- The browser dashboard has no third-party assets or analytics and shows a
+  preview before every consequential local change. Two jobs can be completed in
+  it end to end: Allocate (cost centres, rules, a recorded run) and Close
+  (declare the scope, import and adopt an export, record a reconciliation),
+  through local-only write routes that store what the CLI stores. The Statement
+  shows one calendar month's four claims side by side and exports them as CSV
+  without a total. The CLI remains the reference surface: the parity map in
+  Settings is derived from the registry, and a row's `full` or `partial`
+  coverage is checked against app source by
+  `test/dashboard-coverage-value.test.ts` rather than asserted.
 
 ## Intended direction
 
@@ -136,9 +150,9 @@ local-first from being read as offline.
 
 | Path | Operator control | Recipient | Data category | Non-claim |
 | --- | --- | --- | --- | --- |
-| Normal proxy route | Exact `provider_inference` controlled-cloud rule, then tool base URL and configured upstream | Configured AI provider | Provider request, which can contain prompts, source snippets, tool payloads, and provider credential | Segreant does not make provider retention/privacy promises. |
+| Normal proxy route | Tool base URL pointed at Segreant. The official OpenAI and Anthropic APIs are built in (`segreant-builtin-provider-*`, either mode); any other configured upstream needs one exact `provider_inference` rule | Configured AI provider | Provider request, which can contain prompts, source snippets, tool payloads, and provider credential | Segreant does not make provider retention/privacy promises. |
 | OpenAI Costs pull | Explicit applied command, declared scope, environment-only key, and exact `provider_cost_observation` rule | Fixed OpenAI Costs endpoint | Narrow read-only provider cost request; normalized observations retained locally | Not a provider-account verification or a request-level reconciliation. |
-| Pricing/baseline refresh | Explicit command or configured refresh plus an exact rule | Operator-selected HTTPS manifest | Public manifest request; accepted normalized result/provenance stored locally | Not usage telemetry or provider invoice evidence. |
+| Pricing/baseline refresh | The built-in public price list: `segreant pricing --refresh`, the configured refresh, or the first-sight lookup (on by default; `segreant pricing --auto off`), no rule needed. Any other manifest: explicit command plus an exact rule | The public price list, or an operator-selected HTTPS manifest | Public manifest request; accepted normalized result/provenance stored locally | Not usage telemetry or provider invoice evidence. |
 | Alert webhook | Explicit webhook configuration plus an exact rule | Operator-selected webhook | Configured alert summary | Not prompt, source, or credential transfer. |
 | Hosted judge | Explicit judge choice plus an exact rule | Configured judge provider | Bounded session excerpt for the selected tier | Not local-only evaluation. |
 | Team rollup | Explicit team push plus an exact rule | Operator-run team endpoint | Signed numeric aggregate | Not default telemetry or approved internet deployment. |
@@ -149,9 +163,16 @@ the provider or optional egress paths above.
 ### High-assurance egress modes
 
 - **Local locked** is the default and is enforceable for Segreant's own HTTP(S)
-  transport: no non-loopback target is resolved or dialled. It permits a local
-  inference service at a literal loopback address such as `127.0.0.1` or
-  `localhost`.
+  transport: no non-loopback target is resolved or dialled except two built-in
+  routes, which hold in every mode. One is the user's own proxied requests to
+  the official provider APIs (`https://api.anthropic.com`,
+  `https://api.openai.com`; GET or POST under `/v1/`, purpose
+  `provider_inference`). The other is the public price list (one exact HTTPS
+  URL, GET only, sending nothing about the user; `segreant pricing --auto off`
+  stops Segreant requesting it by itself). It permits a local inference service
+  at a literal loopback address such as `127.0.0.1` or `localhost`. A malformed
+  persisted egress section loads as `invalid` and refuses every non-loopback
+  target, the built-in routes included, until it is repaired.
 - **Controlled cloud** is opt-in and rule-scoped. A rule does not authorize a
   hostname pattern, arbitrary query/redirect target, plaintext remote HTTP, or
   another purpose/data class. The process receipt records a redacted target
@@ -176,7 +197,8 @@ the provider or optional egress paths above.
 - Say no Segreant-hosted telemetry by default; do not generalize that default into
   an egress guarantee or claim that proxy traffic remains on the device.
 - Say `local_locked Segreant-process transport refused non-loopback HTTP(S)
-  egress` only when that mode is active and receipts verify; say
+  egress other than its built-in routes` only when that mode is active and
+  receipts verify; say
   `controlled_cloud rule and receipt` for a permitted cloud request. Do not
   generalize either to the operating system, other applications, direct
   clients, or provider retention.

package/docs/CLI-JSON-CONTRACT.md

@@ -0,0 +1,38 @@
+# CLI JSON contract
+
+Use `--json` on a command that advertises machine output. Each completed read
+emits one JSON document on stdout, including on a structured refusal. A command
+that cannot produce a document exits non-zero with a concise diagnostic on
+stderr and empty stdout. Human progress messages and stack traces never belong
+in the JSON stream. Commands wrapping another process, persistent servers and
+the status-line stdin protocol have their own output rules.
+
+Every CLI JSON read response has the top-level integer `schemaVersion: 1`. Object
+responses keep their existing fields beside that version. Responses that were
+arrays, including request exports and audit rows, now use
+`{ "schemaVersion": 1, "data": [...] }`. JSON request exports written with
+`--out` use the same envelope as stdout. CSV output keeps its existing format.
+
+Within a version, existing field meanings and types remain stable. New optional
+fields may be added; readers should ignore fields they do not recognize. A
+required field removal, a type change, a meaning change, or a different envelope
+requires a new schema version and a documented migration. This promise begins
+with the versioned 0.2.0 output; pre-versioned array consumers must read `data`.
+
+A response that is itself a versioned document, such as a period-close record,
+already carries `schemaVersion` with that document's meaning, and the CLI leaves
+it unchanged rather than overwriting it.
+
+The response version is separate from a ledger, billing evidence document,
+signed receipt or pack schema. Backup/refusal output exposes the database
+version as `ledgerSchemaVersion`; nested artifact versions and signed bodies
+keep their own meanings. JSON formatting does not change those signed bodies.
+
+Money still carries its original basis: metered usage, provider-billed cost,
+allocated cost and realized value are distinct. Unknown stays null or the
+documented sentinel; versioning never supplies missing evidence.
+
+`test/cli-json-contracts.test.ts` derives command groups and aliases from the
+actual dispatcher. Its fixture modes cover missing, empty, corrupt and large
+synthetic ledgers, plus folders without Git. Adding a dispatch group requires
+classifying it for read coverage or stating why it has another output protocol.

package/docs/DATA-BOUNDARIES.md

@@ -52,9 +52,27 @@ figure, and each stays on the machine under the Segreant home:
 - `scan_snapshots.repos_json` — repository locations discovered by a local
   scan, so the same disclosure applies as for `requests.cwd`.
 
+Outside the ledger, `<home>/survival/` keeps git's answers to survival
+measurement between runs: for each measured repository, commit hashes, the
+repository-relative paths of files those commits touched, and per-file line
+counts by commit. It holds no file contents, and the repository's own location
+appears only as a hash in the file name. It is a cache, never evidence:
+deleting the directory costs the next value run its time, not any figure, and
+only the CLI and the dashboard it starts write it.
+
 Everything above is local. Only the declared egress paths below leave the
 Segreant process, and none of them carries these columns.
 
+The 0.2.0 readers add local reads only; none of them opens an outbound connection. `import` and `scan` read
+the session logs that Claude Code, Codex, opencode and Antigravity write on this
+machine. They keep token counts, model names, working directories (stored as
+`requests.cwd`) and the vendors' own rate-limit readings (`quota_events`; the
+`detail` column holds at most 120 characters of the vendor's limit message). `plan`
+reads only the `oauthAccount` plan fields of `~/.claude.json` and the `plan_type` of
+the newest Codex session log. It never opens Claude Code's credentials file. A plan
+price exists only when the operator sets it. `segreant-statusline` reads the JSON
+that Claude Code passes on standard input and makes no network request.
+
 When an operator explicitly runs `segreant billing import --file ... --apply`,
 Segreant also stores an immutable, provider-declared billing-evidence ledger. V1
 accepts only a strict local OpenAI evidence JSON contract. It retains the file
@@ -75,6 +93,22 @@ provider session, or API key. The status is always
 `operator_declared_unverified`; it is not provider-account verification,
 reconciliation, or an instruction to change routing.
 
+The dashboard can do the same local writes: declare a scope, import and adopt a
+cost export, record a reconciliation, and set up cost centres, rules and
+allocation runs. It does them through `POST /api/billing/write` and
+`POST /api/allocation/write`. Neither route is one of the declared egress paths
+below, and neither opens an outbound connection. They store exactly
+what the matching CLI commands store, under the same rules. A billing import
+from the browser keeps the same basename, digest and allowlisted fields as
+`segreant billing import`, and not the raw file. Both routes answer only
+requests that carry the `x-segreant-local: 1` header. A page on another origin
+cannot send that header to the loopback dashboard without the browser's
+pre-flight, and the dashboard answers no `OPTIONS`. They read a bounded body,
+accept only allow-listed fields, and never quote a refused request or export
+back in an error. In demo mode they refuse every write, while previews still
+answer. The Statement's CSV download is a read of the same local ledger and
+leaves the machine only if you send the file on.
+
 When an operator runs `segreant billing openai-costs pull ... --apply`, Segreant
 may make exactly one additional outbound type: a read-only `GET` to the fixed
 OpenAI Organization Costs endpoint at `https://api.openai.com/v1/organization/costs`.
@@ -91,8 +125,25 @@ recommendations. Failed/partial pulls retain failure metadata with no usable
 provider observations.
 
 All Segreant-process HTTP(S) transport is now governed by the egress boundary.
-The default `egress.mode: "local_locked"` permits literal loopback targets only
-and refuses non-loopback targets before DNS. A cloud operation needs
+The default `egress.mode: "local_locked"` permits literal loopback targets, plus
+two built-in routes, and refuses every other non-loopback target before DNS.
+
+The first is your own traffic to your provider. A request your tool sends to
+`https://api.anthropic.com` or `https://api.openai.com` (GET or POST under
+`/v1/`, purpose `provider_inference`) is forwarded with no setup, receipted under
+a `segreant-builtin-provider-*` rule id. It was going to that provider before
+Segreant existed; Segreant only meters it on the way. Any other upstream (a
+gateway, OpenRouter, a hosted open model) needs one exact rule, and a refused
+request prints the command.
+
+The second is Segreant's own price list: a GET of exactly
+`https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json`
+for purpose `pricing_refresh` and data class `pricing_manifest`, with no query or
+fragment. It carries nothing about the user, its DNS answer must be public, and
+it is receipted under rule id `segreant-builtin-price-list` like any cloud route.
+Without it the rate card could never update and every new model would be priced
+by a guess. Both routes hold in `controlled_cloud` mode too, so adding a rule for a webhook
+never cuts off your provider or your price updates. Any other cloud operation needs
 `controlled_cloud` mode plus one enabled exact rule for its purpose, data class,
 method, HTTPS origin, and leading path. Before an allowed request is dialled,
 Segreant persists redacted local receipts for policy preflight and dial start; it
@@ -145,7 +196,7 @@ added without appearing on this page.
 | Purpose | Data class | What may cross | Reached by |
 | --- | --- | --- | --- |
 | `provider_inference` | `provider_request` | prompts, source snippets, tool payloads, and the caller's provider credential, exactly as the provider API requires | any tool pointed at the Segreant proxy |
-| `pricing_refresh` | `pricing_manifest` | nothing about you — a plain GET for a public pricing manifest | `segreant pricing --refresh`, or `pricing.autoRefresh` |
+| `pricing_refresh` | `pricing_manifest` | nothing about you — a plain GET for a public pricing manifest | `segreant pricing --refresh`, `pricing.autoRefresh`, or a running Segreant's first-sight lookup (`pricing.lookupUnknownModels`, on by default) |
 | `market_refresh` | `market_manifest` | nothing about you — plain GETs for the public leaderboard and price files listed in `docs/MARKET-SOURCES.md` | `segreant market --refresh <source|all>` |
 | `baseline_refresh` | `baseline_manifest` | nothing about you — a plain GET for the manifest at an operator-supplied URL | `segreant baseline --refresh --url ...` |
 | `alert_delivery` | `alert_metadata` | configured alert summaries; never prompts, source, or credentials | `segreant alerts --set-webhook ...` |
@@ -187,14 +238,23 @@ this data to request in the first place.
 
 ## Optional outbound paths
 
+One path is on by default:
+
+- the first-sight price lookup. When a running Segreant prices a request by a
+  guess (the model is not on its rate card), it downloads the built-in public
+  price list once, at most once an hour, outside the request's path. Recorded
+  amounts are not rewritten; `segreant reprice` previews the correction and
+  `--apply` commits it. `segreant pricing --auto off` sets
+  `pricing.lookupUnknownModels` (and `pricing.autoRefresh`) to false.
+
 These paths are off unless an operator deliberately invokes or configures them:
 
 - `segreant pricing --refresh`, or `pricing.autoRefresh` with a configured manifest,
   downloads a public pricing manifest from the selected HTTPS URL. The request is
   a plain GET with no usage, prompt, or customer data; the accepted normalized
-  card and redacted source provenance remain local under the Segreant home. It
-  additionally needs an exact `pricing_refresh` egress rule in controlled-cloud
-  mode.
+  card and redacted source provenance remain local under the Segreant home. The
+  built-in public price list needs no rule in either mode; any other manifest
+  URL needs an exact `pricing_refresh` egress rule in controlled-cloud mode.
 - `segreant baseline --refresh --url ...` downloads a baseline manifest from the
   URL supplied by the operator and needs an exact `baseline_refresh` rule.
 - `segreant alerts --set-webhook ...` sends configured alert summaries to the

package/docs/FAQ.md

@@ -13,8 +13,15 @@ team rollup. [DATA-BOUNDARIES.md](DATA-BOUNDARIES.md) is the complete,
 current outbound and retention contract.
 
 **Can I make Segreant itself refuse all cloud traffic?**
-Yes. New configuration begins in `local_locked` mode, where Segreant refuses
-non-loopback HTTP(S) targets before DNS. A local model at `localhost` or
+Yes, for everything Segreant would send on its own. New configuration begins in
+`local_locked` mode, where Segreant refuses non-loopback HTTP(S) targets before
+DNS, with two built-in routes: your own requests to the official OpenAI and
+Anthropic APIs (they were going there anyway; Segreant meters them on the way),
+and its download of the public price list, which sends nothing about you.
+`segreant pricing --auto off` stops Segreant making that download by itself.
+Your own provider requests are not something egress settings switch off: they go
+out whenever a tool sends them through the proxy, so to stop them, stop the
+proxy or point the tool back at the provider. A local model at `localhost` or
 `127.0.0.1` remains available. To permit a cloud route, use `segreant egress
 plan` to inspect one exact rule and `segreant egress apply --apply` to persist it;
 `segreant egress verify` validates the redacted local receipt chain. This is a
@@ -210,12 +217,19 @@ Usually the `/v1` double-version gotcha: if your client already appends
 `/chat/completions`, point it at `http://localhost:8090` **without** `/v1`. See
 [INTEGRATIONS.md](INTEGRATIONS.md).
 
+**`egress` refuses `--path-prefix /v1/` in Git Bash on Windows.**
+Git Bash rewrites any argument that starts with `/` into a Windows path, so
+Segreant receives `C:/Program Files/Git/v1/` and refuses it (the refusal names
+the value it received). Put `MSYS_NO_PATHCONV=1` in front of the command, or run
+it from PowerShell or cmd, where `/v1/` arrives unchanged.
+
 **`doctor` says the rate card is stale.**
 `segreant pricing --refresh` pulls current rates from the community price feed
 (LiteLLM's model-price file — machine-readable, updated by hundreds of
 contributors within days of every model release; the GET sends nothing about
-you). It needs a reviewed `pricing_refresh` egress rule in controlled-cloud
-mode. For self-maintenance, `segreant pricing --auto` refreshes on start
+you). The public price list is a built-in route in either egress mode, so it
+needs no rule; a custom `pricing.manifestUrl` needs an exact `pricing_refresh`
+rule in controlled-cloud mode. For self-maintenance, `segreant pricing --auto` refreshes on start
 whenever the table goes stale. A malformed or shrunken feed is refused and the
 current table kept — a bad refresh can never corrupt your pricing.
 
@@ -229,11 +243,31 @@ Every Segreant rate remains a local list-price estimate, not a provider invoice,
 contractual discount, credit, tax, or reconciliation result.
 
 **How does pricing stay correct as new models launch?**
-Three layers, in order: the refreshed community feed above (170+ models across
-Anthropic, OpenAI, Google); substring family-matching when an exact name is
-missing (a new `-preview` variant prices as its family); and a conservative
-flat fallback that marks every such request `~est` — surfaced in `doctor` as
-"% of spend on estimated rates", so pricing drift is measured, never silent.
+Each request is priced by the first of these that knows its model:
+
+1. **A price you set.** `segreant pricing set <model>` with `--input` and
+   `--output` (USD per million tokens), `--like <model>` to price it as a model
+   on the card, or `--free` for a local model. Shown as "your price", never as
+   list price.
+2. **The rate card**, by exact model name. The bundled card is refreshed from
+   the public price list before each release.
+3. **The public price list, looked up on first sight.** When a running Segreant
+   meets a model the card does not know, it downloads the public price list
+   (at most once an hour, outside the request's path, sending nothing about
+   you). New requests then get the list price. Requests already recorded keep
+   their estimate until `segreant reprice` (a preview) and
+   `segreant reprice --apply`.
+4. **The nearest model on the card** (a new `-preview` variant prices as its
+   family), marked as such.
+5. **A generic rate** ($3 in, $15 out per million tokens), marked `~est`.
+
+The generic rate is a guess in both directions: claude-haiku-5-5 costs $0.10 /
+$0.50, so it read 30 times too high, and about a third of the models on the
+card cost more than $3 / $15, so a premium model reads too low, including
+against a budget cap. That is why the lookup comes before it.
+`segreant pricing unknown` lists every model still priced by a guess, with its
+requests and recorded cost, and `segreant pricing --auto off` turns the lookup
+off.
 
 **Nothing shows under value / RoI.**
 Attach a git repo (`--repo .`) and let the maturity window elapse, or report outcomes

package/docs/GETTING-STARTED.md

@@ -14,6 +14,16 @@ choice.
 > installing, prefix a command with `npx`, for example
 > `npx segreant demo --serve`. From a clone of the repository, run
 > `npm install`, `npm run build` and `npm link` once instead.
+>
+> **Windows, in a folder whose path contains `&`** (for example
+> `Projects & Learning`): npm's `.cmd` launcher, and `npx` or `npm exec`, which
+> use it, break at the ampersand in Command Prompt before Segreant starts. A
+> global install lives under your user folder, so it is affected only if that
+> path contains `&`. For a local install in such a folder, use
+> PowerShell, where `segreant` runs npm's PowerShell launcher, or call Node
+> directly: `node node_modules/segreant/bin/segreant.mjs demo --serve`. CI
+> installs into a path with a space and an ampersand on Windows, macOS and
+> Linux and runs these routes.
 
 ---
 
@@ -116,23 +126,20 @@ $env:ANTHROPIC_BASE_URL="http://localhost:8090"
 $env:OPENAI_BASE_URL="http://localhost:8090/v1"
 ```
 
-**Grant the provider route.** Segreant starts in **local-locked** mode and forwards
-nothing to a cloud provider until you allow that exact route. For OpenAI:
+**No provider setup for OpenAI or Anthropic.** Your requests to their official
+APIs go through as soon as Segreant starts: that traffic was already going to your
+provider, and Segreant meters it on the way. Segreant still starts in
+**local-locked** mode for everything it would send on its own (webhooks, team
+rollups, hosted judging), which stays off until you allow it.
 
-```bash
-segreant egress apply --apply --mode controlled_cloud \
-  --id openai-inference --purpose provider_inference \
-  --data-class provider_request --method POST \
-  --origin https://api.openai.com --path-prefix /v1/
-```
-
-For Anthropic, add a second rule (the OpenAI rule is kept):
+Another provider (OpenRouter, a gateway, a hosted open model) needs one rule for
+its address. A refused request prints the exact command, for example:
 
 ```bash
 segreant egress apply --apply --mode controlled_cloud \
-  --id anthropic-inference --purpose provider_inference \
+  --id provider-openrouter-ai-8b97b9a4-post --purpose provider_inference \
   --data-class provider_request --method POST \
-  --origin https://api.anthropic.com --path-prefix /v1/
+  --origin https://openrouter.ai --path-prefix /
 ```
 
 `segreant egress status` shows the active mode and rules. The full behaviour,

package/docs/GUIDE.md

@@ -24,26 +24,25 @@ linked onto your `PATH`, run the same thing as `npm run segreant -- <verb>`.
 
 ## Egress control
 
-Segreant starts in **local-locked** mode. Before a cloud provider can receive
-routed traffic, grant only the exact route you intend to use. For the default
-OpenAI Responses/Chat API path:
+Segreant starts in **local-locked** mode. Your requests to the official OpenAI
+and Anthropic APIs go through with no setup: that traffic was already going to
+your provider, and Segreant meters it on the way. The public price-list download
+is built in the same way. Everything else Segreant could send on its own
+(webhooks, team rollups, hosted judging) stays off until you add an exact rule.
 
-```bash
-segreant egress apply --apply --mode controlled_cloud \
-  --id openai-inference --purpose provider_inference \
-  --data-class provider_request --method POST \
-  --origin https://api.openai.com --path-prefix /v1/
-```
-
-For Anthropic, add a second exact rule (this preserves the OpenAI rule):
+Another provider (OpenRouter, a gateway, a hosted open model) needs one rule
+for its address. A refused request prints the exact command, for example:
 
 ```bash
 segreant egress apply --apply --mode controlled_cloud \
-  --id anthropic-inference --purpose provider_inference \
+  --id provider-openrouter-ai-8b97b9a4-post --purpose provider_inference \
   --data-class provider_request --method POST \
-  --origin https://api.anthropic.com --path-prefix /v1/
+  --origin https://openrouter.ai --path-prefix /
 ```
 
+The built-in routes hold in either mode, so adding a rule never cuts off your
+provider or your price updates.
+
 Use `segreant egress status` to inspect the active mode/rules and
 `segreant egress verify` to verify the local receipt chain. Return to
 `local_locked` with `segreant egress apply --apply --mode local_locked`. These
@@ -65,8 +64,10 @@ tree from silently running older source.
 Onboarding — where you are, and how spend gets in with no wiring at all:
 
 ```
+segreant                       Bare: this month, your plans, how much of the AI work
+                                stayed in the code, and the next step
 segreant guide                 Where you are + the single next step, read from your
-                                real state — also what bare `segreant` shows  (--json)
+                                real state — the full checklist  (--json)
 segreant scan [path]           One-command setup: find the AI tools + git repos on
                                 this machine, preview a plan (read-only). --setup
                                 imports every detected tool and correlates every repo
@@ -75,7 +76,8 @@ segreant scan [path]           One-command setup: find the AI tools + git repos
                                 the walk.
 segreant import <tool|all>     NATIVE metering, no routing — reads the usage a tool
                                 already logs locally (works on subscriptions the proxy
-                                can never see). Tools: claude-code, opencode, codex.
+                                can never see). Tools: claude-code, opencode, codex,
+                                antigravity (or all).
                                 Idempotent; --watch keeps it live.  (--days N, --json)
 segreant discover              Correlate already-imported projects into per-project
                                 RoI without re-importing — `scan --setup`'s other half
@@ -83,6 +85,15 @@ segreant connect <tool>        Wire a tool through the proxy as a connected sour
                                 (opencode, antigravity, or any OpenAI-compatible API)
 segreant sources                Spend by connected source, at its honest depth
                                 (--all for all-time, --json)
+segreant launch -- <command>   Run one tool metered through the proxy while it runs;
+                                with a cap set, a stopped proxy refuses unless
+                                --allow-unmetered
+segreant plan                  Your plans, what you pay, and the list-price work they
+                                did (plan set <tool> <usd> records a price you pay)
+segreant quota                 The vendors' own usage meters and the pace to their
+                                reset, beside Segreant's count  (--json)
+segreant statusline --setup    Prints the one line that makes Claude Code's status
+                                line record its live usage meter
 ```
 
 Metering, governance, and value:
@@ -116,7 +127,8 @@ segreant team push --url <u>   Cross-machine: sign + push this window's per-proj
                                 <name>, --json)
 segreant budget --recommend    Evidence-limited cap recommendation from usage +
                                 realized value (applies a cap only; no routing or
-                                budget reallocation)
+                                budget reallocation); --detail prints the full
+                                decision record behind the verdict
 segreant alerts                Governance alerts — spikes, throttling, runaway, value
                                 craters (--repo for value; --json; exits 1 if critical).
                                 Deliver to your webhook: --set-webhook <url>, then --notify
@@ -129,6 +141,18 @@ segreant report --kind K       Wire an outcome gate: tested|merged|shipped|incid
                                 --commit <hash> [--verdict pass|fail] [--detail "…"]
 segreant exec -- <command>     AMBIENT outcome capture — wrap a command once (e.g.
                                 `npm test`); every run reports its own exit code
+segreant outcome record        Preview a self-reported chat, image or other result;
+                                --apply records it (--request ID, --session ID, or
+                                --from/--to --tool to link it)
+segreant outcome report        Cost per accepted and used self-reported result, by
+                                kind and model  (--days N, --json)
+segreant market                Public quality per dollar by kind of work, from a
+                                bundled dated snapshot — never mixed with your own
+                                figures (--repo P shows yours beside it; --refresh
+                                fetches through egress)
+segreant evidence github       Signed, offline CI evidence: `emit` runs in a
+                                protected workflow, `import` verifies a pinned key and
+                                the exact repository, branch, workflow and policy
 segreant receipt --repo <path> Emit signed value receipts (--pubkey to publish your
                                 identity; --verify <file> --key-id <id> to verify + pin)
 segreant yield --repo <path>   Artifact persistence (legacy yield lens) — retained introduced lines per $
@@ -141,9 +165,28 @@ Operations:
 ```
 segreant init                  Write default config + print setup steps
 segreant doctor                First-run health check — config, DB, proxy, caps, pricing
+segreant help [all]            The short list of commands; `help all` prints every
+                                command and flag
+segreant --version             Print the installed version
 segreant config                Show config and file paths      (--json)
+segreant features              List optional subsystems and their switches;
+                                features on|off <key> previews, --apply saves
+segreant economic              Exact economic events, roles, bases and legacy
+                                coverage; period close/finalize/reopen controls
+                                (--days N | --all, --as-of <ISO>, --json)
+segreant alloc <action>        Cost-centre allocation: centres, rules, and a
+                                previewed split (--apply records it). See
+                                "Cost-centre allocation" below
 segreant pricing --refresh     Update the rate card from the community price feed
-                                (--auto opts into a refresh check on start when stale)
+                                (--auto on|off: the start-time refresh when stale and
+                                the first-sight lookup of an unknown model, together)
+segreant pricing unknown       Models still priced by a guess, with requests and
+                                recorded cost (--json)
+segreant pricing set <model>   Give a model a price: --input <usd> --output <usd>
+                                (per 1M tokens, optional --cache-read/--cache-write/--cache-write-1h),
+                                --like <card-model>, or --free for a local model.
+                                Shown as "your price", never as list price
+segreant pricing unset <model> Remove a price you set
 segreant pricing --coverage    Read-only per-model historical rate-card and match
                                 evidence (--days N or --all; --json for automation)
 segreant reprice               Re-cost estimated rows against the current rate card
@@ -176,6 +219,12 @@ segreant plugin run --manifest <file> --request <file> --exec <path> --scope k=v
 segreant restore --from <file> --out <file>
                                 Preview a snapshot, or create a new verified
                                 database with --apply (never overwrites the active ledger)
+segreant causal                Retained randomized-study evidence: status, inspect,
+                                replay verification and review-only estimates; never
+                                changes routing (causal design|transport|family
+                                --options <file> check study declarations)
+segreant capital evaluate      Review-only AI-capital decomposition from a bounded
+                                JSON snapshot (--options <file>); no chargeback
 segreant demo                  Seed isolated, labeled synthetic data so every surface
                                 populates with no API key (--serve starts the dashboard
                                 on it; --clear removes it). Append --demo to today,
@@ -460,7 +509,21 @@ IDE / Agent → ANTHROPIC_BASE_URL/OPENAI_BASE_URL → Segreant proxy (:8090)
    versioned rate card, and logs it on-device. Prompt bodies are not stored by
    this metering path.
 3. **Runaway spend is capped** — soft warnings, hard caps, and a velocity guard
-   can halt a looping agent before further proxy-routed provider usage.
+   can halt a looping agent before further proxy-routed provider usage. A cap
+   set with `segreant budget` takes effect on a running proxy without a
+   restart. The check happens before a request is sent, so requests already in
+   flight when the cap is crossed still finish: the overshoot is at most one
+   request per concurrent stream.
+
+A request is priced by the first of these that knows its model: a price you
+set (`segreant pricing set`), the rate card by exact name, the nearest model on
+the card, then a generic $3 / $15 per million tokens. A running Segreant that
+prices a request by either of the last two downloads the public price list once
+(at most hourly, outside the request's path, sending nothing about you), so the
+next request for that model gets its list price; an interactive
+`scan --setup` does the same before it imports, then asks for a price for the
+costliest models still guessed (Enter skips). Recorded rows keep their estimate
+until `segreant reprice --apply`.
 
 The rate card is a local list-price estimate. Every newly calculated ledger row
 retains the exact rate-card SHA-256, source kind, and exact/family/fallback

package/docs/INTEGRATIONS.md

@@ -27,20 +27,20 @@ upstream at the provider.** That's the whole integration.
 | `upstreams.openai` / `upstreams.anthropic` | `~/.segreant/config.json` | where Segreant forwards, after metering |
 | `egress` rule | `segreant egress apply --apply ...` | the exact cloud method/origin/path/data class Segreant may forward |
 
-For native OpenAI or Anthropic, the upstream defaults are correct, but a fresh
-Segreant install is `local_locked` and deliberately refuses cloud forwarding until
-you add an exact `provider_inference` egress rule. This is a second deliberate
-consent step: it records that a provider can receive the routed payload. You
-touch the upstream setting only to meter an OpenAI-*compatible* provider that
-isn't OpenAI (Gemini, OpenRouter, DeepSeek, Ollama, …).
+For native OpenAI or Anthropic, the upstream defaults are correct and need no
+other step: forwarding to their official APIs is built in, because that traffic
+was already going there. You touch the upstream setting only to meter an
+OpenAI-*compatible* provider that isn't OpenAI (Gemini, OpenRouter, DeepSeek,
+Ollama, …). A remote one of those needs one exact `provider_inference` rule; a
+refused request prints the command. A local server on `localhost` needs none.
 
-For example, before routing default OpenAI traffic:
+For example, before routing traffic to a gateway:
 
 ```bash
 segreant egress apply --apply --mode controlled_cloud \
-  --id openai-inference --purpose provider_inference \
+  --id provider-openrouter-ai-8b97b9a4-post --purpose provider_inference \
   --data-class provider_request --method POST \
-  --origin https://api.openai.com --path-prefix /v1/
+  --origin https://openrouter.ai --path-prefix /
 ```
 
 The receipt chain is local and redacted: `segreant egress verify` checks its

package/docs/METHODOLOGY.md

@@ -158,8 +158,9 @@ alert webhooks, an explicitly selected hosted judge, a deliberate OpenAI Costs
 pull, and an opt-in numeric team rollup. The complete, current list and each
 retention control are in [DATA-BOUNDARIES.md](DATA-BOUNDARIES.md).
 
-New installations run Segreant-process HTTP(S) in `local_locked` mode. A
-controlled-cloud action needs an exact purpose/data/method/origin/path rule and
+New installations run Segreant-process HTTP(S) in `local_locked` mode, with two
+built-in routes: the user's own requests to the official provider APIs and the
+public price-list download. Any other controlled-cloud action needs an exact purpose/data/method/origin/path rule and
 creates a redacted local receipt trail. This strengthens the Segreant boundary;
 it does not establish machine-wide egress control or a provider-side privacy
 guarantee.

package/docs/NEUTRALITY.md

@@ -47,7 +47,7 @@ collects nothing centrally.
   payment; offering it as a hosted service and selling Segreant itself are
   not allowed; each version becomes Apache 2.0 two years after publication
   (`LICENSING.md`). No function behaves differently for anyone: the license
-  is a legal term, not a feature gate. Earlier commits carried MIT, copyright "Segreant contributors".
+  is a legal term, not a feature gate. Commits up to `28dc6dd` carried the MIT license under the project's earlier name, with the copyright line recorded in that commit's LICENSE.
 - `docs/RELEASE-GATE.md`'s "Product claims allowed at this stage" section
   fixes the precise language this project may use about itself and forbids
   overclaiming (not "AI financial advice," not "zero egress," not a verified