@vimoxshah/tokenflow 1.1.1 → 1.2.0

package/docs/configuration.md

@@ -11,8 +11,10 @@ edit it. This page is the complete reference for when you do. `tokenflow config
 *effective* config (defaults merged with your file), and `tokenflow config path` prints the data
 home.
 
-Nothing here is ever transmitted anywhere. There are no keys, tokens, or accounts to configure —
-if a field looks like it wants a credential, you are reading the wrong project.
+Nothing here is transmitted anywhere unless you explicitly point it somewhere you own. The two
+exceptions are opt-in: `sync.token` (a bearer token for your own team server, never a vendor
+credential) and `delivery:` (your own webhook/Telegram/email). If a field looks like it wants a
+vendor API key or account, you are reading the wrong project.
 
 ---
 
@@ -69,6 +71,10 @@ sources:
     scanRoots: ["~/code", "~/work"]   # directories to scan for repositories
     repos: []                          # or list them explicitly
     autoFromUsage: true                # also use working dirs seen in usage records
+  otel:
+    # OpenTelemetry GenAI file exports. Defaults look for ~/.gemini/telemetry.log
+    # and ~/.tokenflow/otel/*.{jsonl,ndjson,json,log}; add paths of your own.
+    paths: ["~/code/my-project/.gemini/telemetry.log"]
 
 store:
   keepRaw: true                 # keep request-level records (Data Explorer + full export)
@@ -101,6 +107,23 @@ ui:
   port: 7799                    # the dashboard binds 127.0.0.1 on this port
   defaultRange: all             # all | 7d | 30d | 90d | mtd
   defaultFrom: null             # e.g. "2026-03-14" — a floor for the default view only
+
+# Optional, off by default. See the `sync` and `budgets` sections below.
+sync:
+  enabled: false
+  dir: ~/Sync/TokenFlow          # a shared folder both machines can see
+  machineName: MacBook Pro
+  developerName: null            # opt-in only; omit to stay anonymous in team views
+  receipts: true                 # set false to skip the branch/PR ledger file
+  to: null                       # POST to a server instead of writing into `dir`
+  token: null                    # bearer token for `to` (or env TOKENFLOW_SYNC_TOKEN)
+
+budgets:
+  - id: api-monthly
+    scope: repo                  # total | repo | team
+    repo: api                    # required when scope is repo
+    monthlyUsd: 150
+    warnAt: 0.8                  # optional, default 0.8
 ```
 
 ---
@@ -176,6 +199,96 @@ the exact reset instant in your timezone. Invalid definitions are reported via
 `tokenflow capacity --json` (`invalid`) and by the dashboard — never silently
 ignored. See [live-mode.md](live-mode.md) for semantics.
 
+### `guard` — thresholds for the in-session circuit breaker
+
+Read by `tokenflow guard` when it runs as a Claude Code hook. Absent or all-null means the hook
+reports and never blocks. Values are declared, never inferred.
+
+```yaml
+guard:
+  warnCostUsd: 25            # session spend at which the hook warns (context + systemMessage)
+  maxCostUsd: 200            # session spend at which PreToolUse / UserPromptSubmit are blocked
+  warnContextTokens: 200000  # prompt size (fresh + cache read + cache write) at which to warn
+  maxContextTokens: null     # prompt size at which to block
+  warnMarginalUsd: null      # median cost of the last ten turns at which to warn
+```
+
+`tokenflow guard --set warnCostUsd=25,maxCostUsd=200` writes these; an empty value clears one.
+
+A repository can declare its own caps in `.tokenflow/policy.yaml`, committed with the code, so
+the cap travels with everyone who clones it:
+
+```yaml
+# <repo root>/.tokenflow/policy.yaml
+guard:
+  warnCostUsd: 10
+  maxCostUsd: 50
+note: "This repo's sessions run long — reasoning-heavy refactors, not chat."
+```
+
+A key declared there wins over `~/.tokenflow/config.yaml`, key by key; a key declared nowhere is
+`null` (informational only). `tokenflow guard --policy [--cwd <dir>]` shows the effective value
+for each key and which file it came from. `note` is optional and shown beside a triggered
+warning/block and beside `guard --policy`'s output. See [guard-codex.md](guard-codex.md).
+
+### `sources.otel.paths` — OpenTelemetry (GenAI) file exports
+
+```yaml
+sources:
+  otel:
+    paths: ["~/code/my-project/.gemini/telemetry.log", "~/.tokenflow/otel"]
+```
+
+Reads a standards-based OTLP JSON export from any tool's file/collector exporter, and Gemini
+CLI's own file telemetry. With no `paths` configured, the adapter still looks in its defaults:
+`~/.gemini/telemetry.log` and `~/.tokenflow/otel/*.{jsonl,ndjson,json,log}`. See
+[providers-otel.md](providers-otel.md).
+
+### `sync` — optional multi-machine aggregation
+
+Off by default. Exchanges daily rollups (and, unless disabled, a branch/PR receipt ledger)
+between machines through a folder you already sync, or by pushing to a server you run:
+
+```yaml
+sync:
+  enabled: true
+  dir: ~/Sync/TokenFlow        # a shared folder both machines can see
+  machineName: MacBook Pro     # label shown in aggregated views
+  developerName: null          # OPTIONAL, opt-in only — per-developer team views
+  receipts: true               # set false to skip the branch/PR ledger file
+  to: null                     # POST to a server instead of writing into `dir`
+  token: null                  # bearer token for `to` (or env TOKENFLOW_SYNC_TOKEN)
+```
+
+`to` and `dir` are alternatives, not both required: set `to` (a `tokenflow team serve` URL, or
+any server speaking its contract) to push there instead of `dir`. What is shared is always the
+same coarse shape — date, tokens, requests, estimated cost, plus the branch/PR ledger unless
+`receipts: false` — never prompts, code, file paths, or credentials. See
+[ledger.md](ledger.md) and [team-server.md](team-server.md).
+
+### `budgets` — caps scoped to a repository or a team
+
+Alongside the single monthly `budget` above, declare as many scoped budgets as you like:
+
+```yaml
+budgets:
+  - id: api-monthly
+    scope: repo            # total | repo | team
+    repo: api                # required when scope is repo; matched the same way
+                              # `tokenflow receipt` resolves a repository (worktrees
+                              # folded into their main checkout)
+    monthlyUsd: 150
+    warnAt: 0.8             # optional, default 0.8 (a fraction, like limits[].warnAt)
+  - id: team-monthly
+    scope: team
+    monthlyUsd: 1000
+```
+
+`total` sums every priced turn in the store this month; `repo` sums turns attributed to that
+repository; `team` reads this machine's shared sync folder, if enabled, and says so plainly
+(`no team data`) rather than reporting a number nobody synced. `tokenflow budget` prints every
+scoped row alongside the monthly cap. See [exports-and-budgets.md](exports-and-budgets.md).
+
 ### `watch` — the background refresher
 
 ```yaml
@@ -230,6 +343,8 @@ never a plausible-looking `$0`.
 | `TOKENFLOW_HOME` | move the whole data home (config, pricing, data, cache) |
 | `TOKENFLOW_DEMO=1` | enable the synthetic demo adapter |
 | `AI_USAGE_HOME` | legacy alias for `TOKENFLOW_HOME`, still honoured |
+| `TOKENFLOW_SYNC_TOKEN` | bearer token for `sync.to`, instead of `sync.token` |
+| `TOKENFLOW_TEAM_TOKEN` | shared bearer token for `tokenflow team serve` |
 
 Running several isolated datasets is just several homes:
 

package/docs/design-system.md

@@ -0,0 +1,187 @@
+# Design system
+
+One token source, three surfaces, gates that fail closed. This document is the
+doctrine; `design/tokens.yaml` is the source; `scripts/design-build.js` is the
+compiler; `test/design.test.js` is what makes a drift or a hand edit fail CI.
+
+```
+design/tokens.yaml ──► scripts/design-build.js ──► src/ui/styles.css        (generated block: dashboard + offline snapshot)
+                              │ gates              site/styles.css          (generated block: landing page)
+                              └──────────────────► menubar/TokenFlow/DesignTokens.swift  (whole file: menu bar)
+```
+
+```bash
+npm run design          # compile + write
+npm run design:check    # compile in memory, diff, exit 1 on drift or a failed gate
+```
+
+Edit the YAML, run `npm run design`, commit the result. Never edit inside a
+`@generated design-tokens` block; the test diffs it against the compiler.
+
+---
+
+## 1. Roles, not values
+
+Every colour is named for the job it does: `--plane`, `--surface-1`,
+`--text-muted`, `--accent`, `--border-strong`. Nothing is named for how it looks.
+A role stays true when a skin flips mode or is replaced; `--grey-200` becomes a
+lie the moment the palette changes. (Borrowed from design-kit's schema.)
+
+## 2. Two axes, kept apart
+
+| Axis | Values | Owns |
+|---|---|---|
+| `data-mode` | dark · light | ink polarity, surfaces, **the series steps** |
+| `data-skin` | aurora · terminal · editorial | the room: surfaces, borders, accent, density, display face |
+
+The categorical, sequential and diverging steps belong to the **mode**. They were
+validated against every skin's chart surface, so a skin restyles the room and
+never the data. Switching theme must not change what a colour means.
+
+**Fidelity beats variety.** Three skins are enough. A fourth is a deliberate
+decision with a stated reason, not a Friday afternoon.
+
+## 3. Hierarchy is carried by lightness, never by hue
+
+- The plane is the room. A card **lifts** toward the light in both modes.
+- Wells inside a card (`--surface-2`, `--surface-3`) **nest** away from the card:
+  lighter still in dark mode, greyer in light mode. The compiler checks both
+  directions.
+- The accent is an accent. It marks the selected thing, the primary action, the
+  live pill. It never floods a surface. A gradient is allowed in exactly one
+  place: behind a single hero number (`--hero-glow`), never behind a mark whose
+  colour has to stay comparable.
+- Status colours (`--good`, `--warning`, `--serious`, `--critical`) are reserved
+  for state. They are never a series, never a chart mark, never themed, and
+  always travel with an icon or a word. On light surfaces `warning` and
+  `critical` sit near series 4 and 8; the compiler reports that as a documented
+  relief, not as a pass.
+
+## 4. Type
+
+The dashboard and menu bar use the platform's faces (`system-ui`, `ui-monospace`,
+the platform serif). They ship optical sizing and tracking tables, and the
+offline snapshot must open from `file://` with nothing to fetch.
+
+Tracking and leading are **size-specific**: large text tightens, small text
+opens. One `letter-spacing` for every size is wrong somewhere.
+
+| Step | Size | Tracking | Leading | Used for |
+|---|---|---|---|---|
+| micro | 10.5 | +.02em | 1.3 | axis ticks, badges |
+| label | 11.5 | +.012em | 1.35 | KPI labels, hints |
+| caption | 12.5 | +.004em | 1.4 | table cells, card titles |
+| body | 13.5 | 0 | 1.45 | body, controls |
+| title | 15 | −.006em | 1.3 | dialog titles |
+| figure | 25 | −.015em | 1.12 | KPI values |
+| hero | 42 | −.025em | 1.05 | the one number on a view |
+| display | 60 | −.03em | 1.0 | landing headlines |
+
+Every number wears `font-variant-numeric: tabular-nums`. Text wears text tokens,
+never a series colour; a coloured mark beside it carries identity.
+
+The landing page has a voice of its own: Space Grotesk for display, IBM Plex
+Sans for body, IBM Plex Mono for figures — design-kit's `house-plex` pairing,
+self-hosted under `site/fonts/` (OFL-1.1). A sans display is the default for a
+developer tool; a serif would need a brand reason this product does not have.
+A product whose promise is "nothing leaves your machine" does not load fonts
+from a third party.
+
+## 5. Space, radius, elevation
+
+A 4-pt scale (`--sp-2` … `--sp-72`) with the two half-steps dense layouts use.
+Radii are per skin (`aurora` 14/9, `terminal` 5/4, `editorial` 8/6) because
+corner radius is part of a room's character. Shadows are tinted toward the
+skin's hue, never neutral black; a bigger surface reads as thicker (deeper
+shadow, stronger blur) than a chip.
+
+## 6. Motion — two tiers, one doctrine
+
+| Tier | Governs | Values |
+|---|---|---|
+| `ui` | dashboard, menu bar | press 120ms · fast 160ms · base 220ms · slow 300ms · stagger 40ms (max 6) |
+| `narrative` | landing, reveals | fast 180ms · base 320ms · slow 700ms · stagger 85ms (max 7) |
+
+Rules (Emil Kowalski, Apple, design-kit, in agreement):
+
+- **Should it animate at all?** Something seen a hundred times a day does not.
+  Keyboard-initiated actions never animate. The compiler refuses a UI value over
+  300ms.
+- **Every animation carries information** — sequence, causality, comparison,
+  magnitude. Motion that only decorates is deleted.
+- **Ease-out for entrances, ease-in-out for on-screen movement, never ease-in.**
+  Custom curves (`--ease-out`, `--ease-in-out`, `--ease-drawer`); the built-ins
+  are too weak.
+- **Feedback on press, not on release.** Every pressable scales to `.97` on
+  `:active` at `--dur-press`.
+- **Popovers scale from their trigger** (`transform-origin` at the trigger);
+  modals stay centred.
+- **Tooltips delay once, then are instant** for neighbours.
+- **Enter from `scale(.96)` + opacity, never from `scale(0)`.** Use
+  `@starting-style` for entry.
+- **Transitions over keyframes** for anything that can be re-triggered; specify
+  properties, never `transition: all`.
+- **Stagger only when a view changes**, 40ms apart, at most six items. Never
+  front-load then freeze; once content has resolved it holds still.
+- **Hover states are gated** behind `(hover: hover) and (pointer: fine)`.
+- **Reduced motion degrades to an instant, complete state** — never a broken
+  half-state. Transparency and contrast preferences are honoured the same way.
+
+## 7. Charts
+
+Ramps are **authored, never derived**. The eight categorical steps, the seven
+sequential steps and the five diverging steps live in the token file and pass
+the compiler's gates on every build:
+
+| Gate | Threshold | Shipped |
+|---|---|---|
+| series on each skin's chart surface | ≥ 3:1 | pass in dark; light slots 3–5 are the documented relief |
+| adjacent series distance (CIE76 ΔE) | ≥ 20 | worst 76 dark · 84 light |
+| first three slots, all pairs | ≥ 20 | pass |
+| sequential luminance | strictly monotonic | pass |
+| diverging ends / midpoint | ends ΔE ≥ 40 · midpoint near-neutral | pass |
+| status vs series | ≥ 12 hard, < 20 reported | light `warning`/`critical` are the documented relief |
+
+Rules that hold in every chart (dataviz):
+
+- Colour is assigned to the **entity, in fixed order, never by rank**. A filter
+  that removes a series never repaints the survivors. Past eight, fold into
+  "Other".
+- **One axis.** Two measures of different scale are two charts.
+- Sequential is one hue light→dark; diverging is two hues with a neutral grey
+  midpoint. Never a rainbow.
+- Thin marks, 2px lines, hairline grid, recessive axes, selective direct labels.
+- A legend is always present for two or more series; a single series needs
+  none.
+- **Every chart has a table twin.** No value is reachable only by hovering.
+  This is the relief that lets three light-mode slots sit under 3:1.
+
+## 8. Surfaces
+
+| Surface | Consumes | Notes |
+|---|---|---|
+| Dashboard | `src/ui/styles.css` generated block | hand-authored components below the block |
+| Offline snapshot | the same stylesheet, inlined | one file; that is why the block lives inside `styles.css` |
+| Menu bar | `DesignTokens.swift` | every role is a dark/light pair resolved by appearance |
+| Landing | `site/styles.css` generated block | single world (Aurora dark), narrative motion tier, self-hosted faces |
+
+## 9. What the compiler cannot measure
+
+These are review rules. The compiler prints them; a person enforces them.
+
+- **Rationing.** One accent per view. One hero number per view. A status colour
+  appears only with the word it qualifies.
+- **The point.** Every view should answer a question in its first line. A grid
+  of numbers you have to interpret is a failure of hierarchy, not of data.
+- **Honesty.** Missing is not zero; estimated and measured never mix; a cap
+  table is an upper bound; a receipt says what it did not count.
+
+## 10. How to change something
+
+1. Edit `design/tokens.yaml`. Quote every hex (`#` starts a YAML comment).
+2. `npm run design`. Read the report; a warning is information, a failure is a
+   stop.
+3. `npm test`. `test/design.test.js` checks the gates and that every target is
+   current.
+4. Look at it. Render the dashboard, the snapshot and the landing before
+   claiming done; the compiler measures colour, not layout.

package/docs/exports-and-budgets.md

@@ -0,0 +1,85 @@
+# Exports that travel, and budgets per repo and per team
+
+Two additions on top of `receipt` and the monthly `budget`: receipts and a
+weekly summary you can drop into Slack or a PR, and a budget you can scope to
+one repository or to your whole team.
+
+## Receipt cards: SVG, PNG, and CSV
+
+`tokenflow receipt --branch <name>` already prints a PR-comment receipt. Add
+`--svg` to also write it as a card:
+
+```bash
+tokenflow receipt --branch feat/x --svg receipt.svg
+tokenflow receipt --branch feat/x --svg receipt.svg --png receipt.png
+tokenflow receipt --branch feat/x --png receipt.png   # writes receipt.png.svg too
+```
+
+The card is a plain SVG file. It opens in a browser, and it drops straight
+into Slack or a PR comment as an image. Every colour on it comes from
+`design/tokens.yaml`, read at render time, so it always matches the skin and
+mode set in `config.yaml` (`ui.skin`, `ui.mode`). Nothing is downloaded and
+nothing is drawn with a colour that is not one of the project's own tokens.
+
+`--png` needs a local Chromium or Chrome install (checked at
+`/opt/homebrew/bin/chromium`, `/Applications/Google Chrome.app`, or on your
+`PATH`). When none is found, the command says so in one line and the SVG is
+still there.
+
+Add `--csv` to get one row per branch instead, across every repository the
+`receipt` command would otherwise print as a table:
+
+```bash
+tokenflow receipt --csv > receipts.csv
+tokenflow receipt --repo api --csv > api-receipts.csv
+```
+
+Columns: `repo, branch, costUsd, contextShare, sessions, turns, subagentTurns,
+first, last, longLived, prNumber, mergedAt, changedLines, costPer100Lines`. A
+missing value is an empty cell, never `0`, the same rule the rest of
+TokenFlow's exports follow.
+
+## `tokenflow week`: your AI week as a card
+
+```bash
+tokenflow week                         text summary
+tokenflow week --svg week.svg          a shareable card
+tokenflow week --svg week.svg --png week.png
+tokenflow week --json                  everything, machine readable
+```
+
+Spend this calendar week (Monday through today) against last week (the full
+prior Monday through Sunday), the context share, turns, sessions, the three
+branches that cost the most, the single most expensive session, and one
+sentence of insight. Every number in that sentence is a number: no "a lot" or
+"much higher" without a figure next to it.
+
+## Budgets per repository and per team
+
+The existing monthly budget (`tokenflow budget --set 200`) still works exactly
+as before. Alongside it, declare as many scoped budgets as you like:
+
+```yaml
+budgets:
+  - id: api-monthly
+    scope: repo            # total | repo | team
+    repo: api                # required when scope is repo
+    monthlyUsd: 150
+    warnAt: 0.8             # optional, default 0.8 (a fraction, like limits[].warnAt)
+  - id: team-monthly
+    scope: team
+    monthlyUsd: 1000
+```
+
+- `total`: every priced turn in the store this month.
+- `repo`: turns this month attributed to that repository, resolved the same
+  way `tokenflow receipt` resolves it. A worktree checkout folds into its main
+  repository, so a repo's spend is never split across every worktree it ever
+  had.
+- `team`: this machine's shared sync folder (`sync.dir`), if `sync.enabled` is
+  set. Nothing is invented: with sync off, or with a sync folder that has no
+  data yet, the row says so plainly (`no team data`) rather than reporting a
+  number nobody synced.
+
+Each row reports `spentUsd`, `monthlyUsd`, `share`, and a state: `ok`, `warn`
+(at or above `warnAt`), or `over` (at or above the cap).

package/docs/guard-codex.md

@@ -0,0 +1,132 @@
+# The guard for Codex CLI, and caps that travel with a repository
+
+`tokenflow guard` started as a Claude Code hook. This page covers the two
+things layered on top of it: a per-repository policy file, and a Codex CLI
+integration that **warns but never blocks**.
+
+## Codex cannot be blocked — read this first
+
+Claude Code gives a hook a chance to reject a tool call or a prompt before it
+runs (`PreToolUse` / `UserPromptSubmit`, exit code `2`). Codex CLI has no
+equivalent. Its only extension point after a turn is `notify` in
+`~/.codex/config.toml`: one external program, run once per completed turn,
+with no way to stop anything that already happened.
+
+So the Codex integration **only warns**, through an OS notification (the same
+`src/core/notify.js` used everywhere else in TokenFlow — `osascript` on
+macOS, `notify-send` on Linux, a toast on Windows). It cannot cap a runaway
+Codex session the way the Claude Code hook can cap a runaway Claude Code
+session. If you want an enforceable cap, Claude Code's `PreToolUse` /
+`UserPromptSubmit` hook is still the only one that can actually stop a turn.
+
+## What Codex sends, and what TokenFlow reads
+
+Codex's `notify` program receives one JSON argument after every turn
+(`agent-turn-complete` is currently the only event). Per Codex's own docs,
+common fields are:
+
+```json
+{
+  "type": "agent-turn-complete",
+  "thread-id": "0199...",
+  "turn-id": "turn-...",
+  "cwd": "/Users/you/project",
+  "input-messages": ["..."],
+  "last-assistant-message": "..."
+}
+```
+
+`tokenflow guard --codex-notify` reads **only** `thread-id` and `cwd`. It
+never reads, logs, or stores `input-messages` or `last-assistant-message` —
+those carry the actual conversation, and TokenFlow's rule is counts and
+metadata only, never prompt or code content.
+
+From `thread-id` it locates the matching rollout transcript —
+`~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-<timestamp>-<thread-id>.jsonl` (or
+`archived_sessions`) — and ingests it with the same openai adapter and the
+same incremental, offset-based cache `tokenflow refresh` and the Claude Code
+guard already use (`$TOKENFLOW_HOME/guard/codex-<thread-id>.json`), so a long
+session's transcript is re-read only for the bytes appended since the last
+turn. From `cwd` it resolves the effective guard policy (below) and judges
+the session exactly the way the Claude Code hook does — same thresholds, same
+`evaluateGuard`.
+
+On `warn` or `block` it sends **one** OS notification with the same text
+`tokenflow guard --session <file>` would print. A `block`-level verdict is
+still only a notification: the title says so explicitly ("warning only —
+Codex has no blocking hook"). `src/core/notify.js` truncates a notification
+body to 240 characters, so a long verdict (several reasons, a suggestion) may
+arrive clipped — the full text is always available by running
+`tokenflow guard --session <the rollout file>` yourself.
+
+## Wiring it up
+
+```bash
+tokenflow guard --install --codex            # print the exact notify = [...] line
+tokenflow guard --install --codex --apply    # append it to ~/.codex/config.toml, if safe to do so
+```
+
+`--apply` only writes when **both** are true: `~/.codex/config.toml`'s parent
+directory exists (otherwise Codex does not look installed on this machine,
+and nothing is created), and the file declares no `notify` key yet. Codex
+allows exactly one `notify` program — if one is already configured (for
+example a computer-use client, or your own script), `--apply` refuses and
+prints the same instructions `--install --codex` alone would, so you can
+merge it by hand instead of silently losing whatever was there. Restart
+Codex CLI for a config change to take effect.
+
+## Per-repository caps: `.tokenflow/policy.yaml`
+
+A threshold set with `tokenflow guard --set` lives in
+`~/.tokenflow/config.yaml` — one machine, one person. A repository can
+instead declare its own caps in a file that travels with it:
+
+```yaml
+# <repo root>/.tokenflow/policy.yaml
+guard:
+  warnCostUsd: 10
+  maxCostUsd: 50
+  warnContextTokens: 150000
+note: "This repo's sessions run long — reasoning-heavy refactors, not chat."
+```
+
+Any of the five guard keys may be declared (see `docs/configuration.md`'s
+`guard` section for what each one means); an invalid value (not a number, or
+not positive) is reported and ignored rather than applied — a typo in a
+checked-in file must not take the hook down for everyone who clones the repo.
+`note` is optional and shown alongside a warning/block that the policy
+triggered, and beside `guard --policy`'s output; it may sit at the top level
+or beside the `guard:` block.
+
+**A repository's declared key wins over the personal config, key by key.** A
+key the repository does not declare falls back to `~/.tokenflow/config.yaml`,
+and a key declared nowhere is `null` — informational only, same as today.
+
+```bash
+tokenflow guard --policy                  # effective policy for the current directory
+tokenflow guard --policy --cwd <dir>      # for some other directory / repository
+```
+
+prints each of the five keys, its value, and where it came from —
+`[repo]`, `[config]`, or `[default]` — plus the repository root that was
+found (a plain `.git` directory is enough; a git worktree resolves to its
+main checkout, same as everywhere else in TokenFlow) and any errors in
+`policy.yaml`.
+
+When a warning or block fires because of a repo-declared key, one extra line
+is appended to the verdict naming which key(s) came from
+`.tokenflow/policy.yaml` (and the `note`, if one is set) — for both the
+Claude Code hook and the Codex path, since both call the same
+`effectiveGuardPolicy()`.
+
+## Everything this adds, at a glance
+
+| Command | What it does |
+| --- | --- |
+| `tokenflow guard --policy [--cwd <dir>]` | Show the effective guard policy and each value's source |
+| `tokenflow guard --install --codex [--apply]` | Wire up (or print) Codex's `notify` line |
+| `tokenflow guard --codex-notify <json>` | What Codex's `notify` actually runs, once per turn |
+
+Nothing here makes a network call, reads prompt or code content, or writes
+outside `$TOKENFLOW_HOME` and (only with `--apply`, and only when safe)
+`~/.codex/config.toml`.