Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions docs/DASHBOARD.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,8 @@ its right.
Scorecard reads top to bottom as one argument: what the window cost, how you spent it, and what that
says about the way you work. Figures derive from locally retained transcripts. Claude/Codex cost uses the bundled
rate table (including fallback rates for unknown models); OpenCode uses its recorded
message cost when present and falls back to that table otherwise. None is an invoice
message cost when present and falls back to that table otherwise, except that a local
model with no recorded cost is left unpriced rather than charged a fallback rate. None is an invoice
or proof of subscription billing. Claude Code writes one transcript line per content block and
repeats the message's usage on each, so Claude tokens, cost, responses and context samples count
each API message once.
Expand Down Expand Up @@ -249,9 +250,10 @@ evidence supports. **Model mix over time** stacks per-day cost by coarse model f
families coloured and the rest folded into a de-emphasised band.

**Reliability** reports turns that never landed: exceptions per thousand responses, aborted turns,
and a per-day exceptions sparkline that names the worst single day. Aborted turns are **codex-only
normalized evidence** — the other parsers do not populate this counter — so the count appears only when the window holds a
codex session, and otherwise reads `—` rather than a zero that would look measured.
and a per-day exceptions sparkline that names the worst single day. Aborted turns are **codex and
opencode normalized evidence** — the Claude parser does not populate this counter — so the count
appears only when the window holds a codex or opencode session, and otherwise reads `—` rather
than a zero that would look measured. An OpenCode turn you stop counts as an abort, not an exception.

`ak usage score` prints the same scorecard figures in a terminal, offline, including the rhythm
pair, the posture and served-by tables, and the reliability lines.
Expand Down
118 changes: 63 additions & 55 deletions docs/TRANSCRIPTS.md

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ ak sync # apply it
| `status` shows `ruvnet-brain … not installed` | The RuvNet Brain (offline KB + `search_ruvnet` MCP) isn't on disk | `ak sync` (or `ak setup`) runs the installer; `npx ruvnet-brain --doctor` health-checks it |
| A heal says `degraded` while the tool is still usable | The native repair failed and a fallback or older artifact remains available; exit status is authoritative | Use the reported repair command/error. The operation will not render green or advance a version stamp until a later repair exits successfully |
| Usage suddenly shows no data for one host, or a lower total than expected | Any of the four local sources (Claude/Codex transcript roots, OpenCode's SQLite store, the Codex thread ledger) can go absent, busy, corrupt, or query-incompatible; none of these are collapsed into an ordinary empty result | Inspect the branded host-icon pills in the dashboard's tabbar (top of every view, right-aligned — or `sourceHealth` in usage-index JSON) — one pill per host; the Codex pill folds its transcript-root and thread-ledger statuses together (worse status leads, both shown in the status side's tooltip). A degraded OpenCode scan retains in-window last-good cached sessions; repair the named source before treating zero as observed truth |
| The OpenCode pill's tooltip warns `usage-not-reported:N`, or a local-model session reads $0 with unpriced messages | A local model server (LM Studio, Ollama, llama.cpp) finished N responses without reporting token counts or a cost. The responses are counted, their usage is unknown, and no price is invented for a local model | Expected for servers that do not report usage; `costEvidence.unpricedMessages` on the session names the unpriced messages. Turn on usage reporting in the server if it offers it |
| The Codex pill warns `unparsed-rollouts` or `oversized-lines-clipped` | A rollout could not be read or parsed and contributes nothing, or a single line over 16 MiB was clipped to its identifying head instead of parsed. Rollouts over 128 MiB stream through a bounded-memory reader, so size alone no longer drops a file | `sourceHealth.codex.diagnostics` names the count and, for unparsed files, the reason (`read-error`: permissions or a vanished file; `parse-error`). Fix the file's permissions or report a parse error; a clipped line still counts as one event |
| Codex sessions, prompts or responses are far lower than the Codex app lists | Sessions Codex imported from Claude Code transcripts (turn ids `external-import-turn-N`) are not Codex activity and are excluded from every Codex figure; their real usage is under Claude | `sourceHealth.codex.diagnostics.importedExcluded` is the count. No action needed |
| A Codex thread's tokens exceed the thread ledger's `tokens_used`, or a Codex subagent's are far below it | The ledger keeps only the last cumulative snapshot, so it omits everything before the host's counter restarted (the scorecard sums each segment). A forked subagent's rollout also replays its parent's history, which the ledger includes and the scorecard does not count | Expected; the scorecard is the more accurate figure in both directions |
Expand Down
Loading
Loading