@drakulavich/zapara 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-22
+
+### Changed
+- The week grid's `peak` column is painted in a TTY with the color of the level its index falls in, by the same thresholds `zapara status` reads a level from; `--no-color` and a pipe are unchanged.
+- The status file's `index` and `level` are the load of the sixty minutes ending at `asOf`, not of the calendar hour that contains it: the number no longer drops to nothing at every hour boundary (90 at 11:59:30, 6 at 12:00:30 on one machine) and no longer climbs through the hour as the bucket fills. `Day.live` in `--json` carries that bucket on the open day. Same formula, same norms; `schema` stays 1.
+
+## [0.4.0] - 2026-09-21
+
+### Changed
+- Streak norm recalibrated for the presence rule: 40 minutes of your own uninterrupted actions now score the full streak points (was 120, the p90 of the old rule that let agent activity keep a streak alive; the p90 under the new rule is 33 on one machine and 48 on another, and 40 sits between them).
+- Presence counts every human action, not only prompts: an interrupt, a tool rejection and an answer to a question or a plan hold a streak open and fill active minutes the same way a prompt does. They remain decisions where they already were; nothing is counted twice.
+- An hour's streak is the longest streak seen in it, not the one it happened to end on. A single prompt after a break no longer erases the run the hour held, nor the streak points of that hour's index.
+- The status file's streak is live: it counts from the first action of the streak you are in up to `asOf`, and resets to `0` once you have been away for more than ten minutes. Before, it was the current hour's bucket, so it fell to zero at every hour boundary.
+- `Day.presence` in `--json`: the day's last human action and the start of the streak it belongs to, as instants, or `null` on a day with no action of yours.
+
+### Fixed
+- The card's longest streak is no longer under-reported: a run that ended in an hour where another began used to be measured only up to the end of the hour before.
+- The status line's streak no longer drops to zero at each hour boundary.
+- `card --out` into a directory that does not exist or refuses the write says `cannot write the card: check the --out directory` instead of printing the full path back in a file-system error.
+- A permission-mode switch made before the first message of a session counts: it is attributed to the first timestamped record that follows, instead of vanishing.
+- A transcript whose modification time is outside the window is read when its last record is a big one: the rescue that looks for the last timestamp reads 64 KB from the end instead of 4 KB, so a day that ended on a large tool result is no longer dropped in full.
+- An output-token count that is not a finite non-negative integer is ignored instead of poisoning the day: a corrupt transcript could put `NaN` in the token column and `null` in the JSON, beside a made-up level.
+- A prompt with a pasted screenshot counts again: the image block comes before the typed text, and such prompts were read as no text at all, so a day spent pasting screenshots showed no prompts and no active minutes.
+
 ## [0.3.1] - 2026-09-19
 
 ### Changed

package/README.md

@@ -12,75 +12,88 @@
   <img src="https://raw.githubusercontent.com/drakulavich/zapara/main/assets/demo.webp" alt="zapara demo: week heatmap, day table, JSON" width="800">
 </p>
 
-Claude Code writes a JSONL transcript for every session under `~/.claude/projects`. zapara reads those files, puts each record in the local hour it happened in, and turns the hour into one number. A week is a heatmap of seven rows by 24 cells; a day is a table with one row per hour and, with `--explain`, the weighted contribution of each component. Nothing is installed into Claude Code, no hook is registered, and no network call is made.
+Claude Code writes a JSONL transcript for every session under `~/.claude/projects`. zapara reads those files, puts each record in the local hour it happened in, and turns the hour into one number. A week is a heatmap of seven rows by 24 cells; a day is a table with one row per hour and, with `--explain`, the weighted contribution of each component.
 
-## Quick Start
+## Quick start
 
 ```bash
-# Install Bun if you do not have it (zapara needs 1.4 or newer)
+# Skip this if you already have Bun 1.4 or newer
 curl -fsSL https://bun.sh/install | bash
 
-# The last 7 days, straight from the registry
+# Run it once, without installing
 bunx @drakulavich/zapara@latest
+```
 
-# Yesterday, hour by hour, with the components behind each index
-bunx @drakulavich/zapara@latest yesterday --explain
+To keep it, install it with Bun. The same command upgrades it later.
 
-# The card
-bunx @drakulavich/zapara@latest card
+```bash
+bun add -g @drakulavich/zapara
 ```
 
-To keep it around, `bun add -g @drakulavich/zapara` puts `zapara` on your PATH. There is no build step and no runtime dependency: Bun runs `src/index.ts` from the package as it is.
+`zapara` lands in Bun's global bin directory, `~/.bun/bin` unless `BUN_INSTALL_BIN` says otherwise; `bun pm bin -g` prints the one in force. Bun's own installer puts that directory on your PATH; a Homebrew Bun does not, so add it yourself. Then:
+
+```bash
+zapara                      # the last 7 days
+zapara yesterday --explain  # one day, with the components behind each index
+zapara card                 # the picture
+```
+
+No build step and no runtime dependency: Bun runs `src/index.ts` from the package as it is.
 
 ## What it looks like
 
-Both pictures below come from the synthetic fixture in `tests/fixtures/busy-week`: a calm morning of one session, a five-session storm in the middle of the day, and a late tail that runs past midnight.
+The week below, and the day behind the fold under it, come from the synthetic fixture in `tests/fixtures/busy-week`: a calm morning of one session, a five-session storm in the middle of the day, and a late tail that runs past midnight.
 
 ```
             00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23   peak  active
 Mon 14/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ░  █  █  █  ·  ·  ·  ·  ·  ░  ░  ·  ░     87    8h50
 Tue 15/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ░  ░  ▒  ▒  ▒  ░  ·  ·  ·  ·  ·  ·     33    7h55
 Wed 16/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·      -    0h00
-Thu 17/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     14    1h55
-Fri 18/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ▓  ·  ·  ·  ·  ·  ·  ·  ·     81    1h00
-Sat 19/09    ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     24    1h55
+Thu 17/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     15    1h55
+Fri 18/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ▓  ·  ·  ·  ·  ·  ·  ·  ·     81    0h35
+Sat 19/09    ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     25    1h55
 Sun 20/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·      -    0h00
 
   ░ calm   ▒ warming   ▓ heating   █ fried
-  21h35 active   348 prompts   0 reports   100 decisions   5 sessions at once
+  21h10 active   323 prompts   0 reports   86 decisions   5 sessions at once
+```
+
+<details>
+<summary><b>Monday hour by hour, and the commands that print both</b></summary>
+
+The fixture's timestamps are UTC and zapara buckets by local time, so pin the zone to get these exact hours:
+
+```bash
+TZ=UTC bun src/index.ts --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
+```
+
+That prints the grid above. One day of it, with the weighted parts behind each index:
+
+```bash
+TZ=UTC bun src/index.ts 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
 ```
 
 ```
 hour   index  level    sess  prompts  intr  rej  quest  plan  mode  ctx-sw  streak  out-tok  par  pace   sup  read  strk  late
-09:00      9  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1   4.2     0
-10:00     14  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1   9.2     0
+09:00     15  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1    10     0
+10:00     15  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1    10     0
 11:00     15  Calm        1        7     0    0      0     0     0       0    179m      600    0   5.3     0   0.1    10     0
 12:00     87  Fried       5       55    20    1      1     1     2      54    235m    55.0k   25    15    30   6.9    10     0
 13:00     87  Fried       5       55    20    1      1     1     2      54    295m    55.0k   25    15    30   6.9    10     0
 14:00     87  Fried       5       55    20    1      1     1     2      54    355m    55.0k   25    15    30   6.9    10     0
-20:00      9  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1   4.2     0
-21:00     14  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1   9.2     0
-23:00     19  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1   4.2    10
+20:00     15  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1    10     0
+21:00     15  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1    10     0
+23:00     25  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1    10    10
   no reports today
 ```
 
-<details>
-<summary><b>Reproduce these pictures from the repository</b></summary>
-
-Two commands in a terminal reproduce them. The fixture's timestamps are UTC and zapara buckets by local time, so pin the zone to get these exact hours:
-
-```bash
-TZ=UTC bun src/index.ts --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
-TZ=UTC bun src/index.ts 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
-```
-
 The grid is a fixed 98 columns wide, 100 with its hour header, and does not reflow, so it needs a terminal at least that wide.
 
 </details>
 
 ## Share a card
 
-`zapara card` turns your last two weeks into one picture: a character named after the kind of load that dominates your hours, the sentence behind it, the peak hour, the share of calm, warming, heating and fried hours, and three highlights. No dates, no hour totals, nothing that reads as a timesheet.
+`zapara card` turns your last two weeks into one picture: a character named after the kind of load that dominates your hours, the sentence behind it, the peak hour, the share of calm, warming, heating and fried hours, and three highlights. It carries no dates and no hour totals, so it does not read as a timesheet.
 
 ```bash
 zapara card                    # writes zapara-card.png in the current directory
@@ -100,7 +113,7 @@ wrote zapara-card.png
 
 <p align="center"><img src="https://raw.githubusercontent.com/drakulavich/zapara/main/assets/card.webp" alt="zapara card: The Marathoner, longest streak 7h53m, 68% of hours calm" width="800"></p>
 
-This one comes from the same `busy-week` fixture as the pictures above. The picture is taken by a headless browser that Bun drives: WebKit on macOS, an installed Google Chrome elsewhere, so on Linux or Windows install Chrome, or write `--out card.html` and open the page in any browser.
+This one comes from the same `busy-week` fixture as the pictures above. A headless browser that Bun drives takes the picture: WebKit on macOS, an installed Google Chrome elsewhere. On Linux or Windows, install Chrome or write `--out card.html` and open the page in any browser.
 
 ## Usage
 
@@ -122,19 +135,19 @@ This one comes from the same `busy-week` fixture as the pictures above. The pict
 | `--json` | Print the whole window as one JSON document instead of a table. |
 | `--projects <dir>` | Read this directory instead of `~/.claude/projects`. |
 | `--out <path>` | Where `card` writes; the extension picks the format. |
-| `--no-color` | Plain glyphs with no ANSI codes. `NO_COLOR` in the environment does the same. |
+| `--no-color` | Plain glyphs and peaks with no ANSI codes. `NO_COLOR` in the environment does the same. |
 | `-h`, `--help` | Usage, exit 0. |
 | `-V`, `--version` | The version from `package.json`, exit 0. |
 
 Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
 
-The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; there is no flag to force text in a pipe yet. `card` always writes its file and prints its two lines, piped or not, and only `card --json` prints JSON. `status` always writes its file and prints the same JSON line, piped or not, and `--json` changes nothing there.
+The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card --json` is the exception: it prints the card's data and writes no file. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
 
-Exit codes are 0 on success, 1 when the projects directory is missing or cannot be read, or when `status` cannot write its file (three different messages, none with a path), and 2 for a usage error such as a bad date or an unknown flag, which prints one line and a hint to `--help`. A value flag given twice is a usage error. A window with no data prints an empty grid and exits 0.
+Exit codes are 0 on success, 1 for a failure zapara can name, which prints one line to stderr and never a path: the projects directory missing or unreadable, `status` unable to write its file, `card` unable to write its picture or to find a browser engine, and whatever else goes wrong below the command line; and 2 for a usage error such as a bad date, an unknown flag or a value flag given twice, which prints one line and a hint to `--help`. A window with no data prints an empty grid and exits 0.
 
 ## Status line
 
-A status line wants one number every thirty seconds and cannot wait half a second for a transcript scan, so zapara writes the number down and the status line reads it back. `zapara status` computes today exactly as `zapara today` does, writes it as one line of JSON to `~/.claude/zapara/status.json`, and prints the same line. Only `--projects` applies to it; the window flags, `--explain` and `--out` are usage errors, and `--json` changes nothing because the output is already JSON. There is one file per user, whatever `--projects` said, created with mode `0600` in a directory with mode `0700`; the write goes to a temporary file and is renamed into place, so a reader sees the old line or the new one and never half of one. The file holds the nine values below and nothing else: no path, no project, no session count, no text.
+A status line wants one number every thirty seconds and cannot wait half a second for a transcript scan, so zapara writes the number down and the status line reads it back. `zapara status` computes today exactly as `zapara today` does, writes it as one line of JSON to `~/.claude/zapara/status.json`, and prints the same line. Only `--projects` applies; the window flags, `--explain` and `--out` are usage errors. There is one file per user, whatever `--projects` said, created with mode `0600` in a directory with mode `0700`; the write goes to a temporary file and is renamed into place, so a reader sees the old line or the new one and never half of one. The file holds the nine values below and nothing else: no path, no project, no session count, no text.
 
 ```json
 {"schema":1,"asOf":"2026-09-19T12:30:38.300Z","date":"2026-09-19","hour":15,"index":36,"level":"Warming","peak":41,"activeMin":555,"streakMin":166}
@@ -146,27 +159,27 @@ A status line wants one number every thirty seconds and cannot wait half a secon
 | `asOf` | When the snapshot was taken, ISO 8601 UTC: the `Day.asOf` of the base spec, the `now` of this run. A reader decides staleness from this field, never from the file's mtime. |
 | `date` | The local calendar day the numbers describe, `YYYY-MM-DD`. |
 | `hour` | The local hour that contains `asOf`, `0`..`23`. |
-| `index` | That hour's load index, `0`..`100`, or `null` when the hour has no activity yet. |
-| `level` | That hour's level, `Calm`, `Warming`, `Heating` or `Fried`, or `null` with `index`. A reader colors by this field so it never needs the thresholds. |
+| `index` | The load index of the sixty minutes ending at `asOf`, `0`..`100`, or `null` when they hold no session. It does not reset at an hour boundary: the hour buckets of `zapara today` are calendar hours, this one is the clock's last hour. |
+| `level` | That index's level, `Calm`, `Warming`, `Heating` or `Fried`, or `null` with `index`. A reader colors by this field so it never needs the thresholds. |
 | `peak` | The day's peak index so far, or `null` on a day with no activity. |
-| `activeMin` | Minutes of your presence in the day so far: the 5-minute slots covered by your prompts and the gaps of at most 10 minutes between them; `0` on a day with no prompt. |
-| `streakMin` | Minutes of the unbroken presence streak as of the current hour: your prompts no more than 10 minutes apart, across sessions; `0` when the hour has none. |
+| `activeMin` | Minutes of your presence in the day so far: the 5-minute slots covered by your actions and the gaps of at most 10 minutes between them; `0` on a day with no action of yours. |
+| `streakMin` | Minutes of your live presence streak as of `asOf`: from the streak's first action to `asOf`, when your last action is no more than 10 minutes before `asOf`; `0` once you have been away longer. It keeps growing while you sit there, and it does not reset at an hour boundary. |
 
-Refreshing is the reader's job, and zapara adds no hook, no timer and no daemon. A reader decodes the file strictly and treats anything that fails validation, and a missing or unreadable file, as no data: it draws nothing and counts the file as stale. When the snapshot is stale or missing it starts `zapara status` as a detached process, does not wait for it, and draws what it has, which is also how the file first comes to exist on a machine that never ran zapara. It starts at most one run per threshold and never one per render, so a file that never validates costs one run per threshold and no more; the whole contract is in [the status file spec](docs/superpowers/specs/2026-09-19-zapara-status-file-design.md), and [pult](https://github.com/drakulavich/pult) is the reader that exists, with a five-minute threshold.
+Refreshing is the reader's job, and zapara adds no hook, no timer and no daemon. A reader that finds the file stale or missing starts `zapara status` detached and draws what it has, which is also how the file first comes to exist on a machine that never ran zapara. The rest of the contract, from strict decoding to concurrent runs, is in [the status file spec](docs/superpowers/specs/2026-09-19-zapara-status-file-design.md); [pult](https://github.com/drakulavich/pult) is the reader that exists, with a five-minute threshold.
 
 ## Privacy
 
-zapara reads `~/.claude/projects/**/*.jsonl`, skipping subagent transcripts under `subagents/`. Selection is by modification time first, and a file whose modification time is older than the window is opened only to read the last timestamp in its final 4 KB; nothing from that tail is kept or printed. Message text is compared against a few fixed markers, for interrupts, tool rejections and inbound agent messages, and then discarded. What survives into an event is a timestamp, a session id, an event kind and a token count.
+zapara reads `~/.claude/projects/**/*.jsonl`, skipping subagent transcripts under `subagents/`. It picks files by modification time first, and opens one whose modification time is older than the window only to read the last timestamp in its final 64 KB; nothing from that tail is kept or printed. It compares message text against a few fixed markers, for interrupts, tool rejections and inbound agent messages, then discards it. What survives into an event is a timestamp, a session id, an event kind and a token count.
 
-No message text, prompt length, file path or session title is kept, written or printed. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. Nothing is sent anywhere, no file is written except the card or the status file you ask for, and nothing is installed into Claude Code.
+zapara keeps, writes and prints no message text, prompt length, file path or session title. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. It sends nothing anywhere, writes no file except the card or the status file you ask for, and installs nothing into Claude Code.
 
 ## Limits
 
-- Time is local and buckets are whole hours, so an hour that straddles midnight or a daylight-saving change is bucketed by the local clock. On a fall-back day two wall-clock hours share one label and merge.
-- Only Claude Code transcripts are read. Work in other tools, and time away from the keyboard, is invisible.
-- Files are chosen by modification time, and a file whose modification time is older than the window is still read when the last timestamp in it falls inside the window, so a restored or synced transcript is not lost. A very old session touched today is read in full, but only its in-window events count.
+- Time is local and buckets are whole hours, so an hour that straddles midnight or a daylight-saving change is bucketed by the local clock. On a fall-back day two wall-clock hours share one label and merge, so that bucket can hold up to 120 active minutes and the day up to 1500.
+- zapara reads only Claude Code transcripts. Work in other tools, and time away from the keyboard, is invisible.
+- A file whose modification time is older than the window is still read when the last timestamp in it falls inside the window, so a restored or synced transcript is not lost. A very old session touched today is read in full, but only its in-window events count.
 - The transcript format is Claude Code's private format, built against version 2.1.274, and it may drift. `bun run stats` shows when it has.
-- The norms come from two machines of one user working in auto mode. They are a starting point for a conversation about the metric, not a study.
+- The norms come from two machines of one user working in auto mode, which makes them a starting point for a conversation about the metric rather than a study.
 - The 98-column grid does not adapt to a narrow terminal.
 - For the grid and the day a pipe always gets JSON, and there is no flag to ask for text instead.
 - The card needs a browser engine: WebKit comes with macOS, elsewhere Google Chrome must be installed. `--out card.html` works everywhere.
@@ -174,7 +187,7 @@ No message text, prompt length, file path or session title is kept, written or p
 
 ## Under the hood
 
-The formula behind the number and the transcript record behind every column, for when the number surprises you.
+The formula behind the number and the transcript record behind every column, for when the number surprises you. For the whole path from a transcript line to the status line, with a diagram, read [How the numbers are made](docs/how-the-numbers-are-made.md).
 
 <details>
 <summary><b>How the index works</b></summary>
@@ -186,7 +199,7 @@ parallel    = clamp((sessions - 1) / 4)                                   # 1 se
 pace        = clamp(prompts / 20)                                         # 10 prompts/hour → 0.5, 20+ → 1
 supervision = clamp((3 * decisions + reports + contextSwitches) / 45)     # 15 decisions alone → 1; 45 reports alone → 1
 reading     = clamp(outputTokens / 80000)                                 # 40k → 0.5, 80k+ → 1
-streak      = clamp(streakMin / 120)                                      # 60 min → 0.5, 2h+ → 1
+streak      = clamp(streakMin / 40)                                       # 20 min → 0.5, 40+ → 1
 late        = lateNight ? 1 : 0
 
 index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak + 10*late)
@@ -201,7 +214,7 @@ index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak +
 | Heating | 60–84 |
 | Fried | 85–100 |
 
-The norms come from two machines, 14 days each, of real transcripts covering 116 and 114 active hours. The surprise in that data was how rare explicit decisions are: in auto mode the p90 is 3 decisions per hour, so a component built on decisions alone reads near zero on hours that felt heavy. What those hours actually cost is reading the reports agents send back, switching between sessions, and getting through the volume of model output, which is why supervision carries 30 points and reading 10. Human prompts reached a p90 of 13 per hour on one machine and 20 on the other, hence the pace norm of 20. The parallel-session threshold follows the research this project started from rather than the transcripts: BCG and HBR report that productivity drops past three simultaneous AI tools, and Osmani makes the same point as three focused teammates beating five scattered ones.
+The norms are the p90 of two weeks of real transcripts on two machines, 116 and 114 active hours. Why each one is what it is, and what surprised us in that data, is in [How the numbers are made](docs/how-the-numbers-are-made.md#5-the-index).
 
 Weights and norms live in one exported constant in `src/score.ts`, so a recalibration is one diff there plus a line in `CHANGELOG.md`.
 
@@ -221,7 +234,7 @@ Weights and norms live in one exported constant in `src/score.ts`, so a recalibr
 | `plan` | `ExitPlanMode` tool calls in an assistant message, one per block. |
 | `mode` | Permission-mode switches. A `permission-mode` record whose mode differs from the previous one; the first record of a session sets the baseline and repeats of the same mode count nothing. |
 | `ctx-sw` | Context switches. Over the hour's prompts in time order, the number of consecutive pairs that came from different sessions. |
-| `streak` | Minutes since the current presence streak began: your prompts no more than 10 minutes apart, across sessions, which may reach back before the hour. Agent activity between two prompts does not bridge a gap. |
+| `streak` | Minutes of the longest presence streak the hour saw. Presence is every action you take: a prompt, an interrupt, a tool rejection, an answer to a question or a plan. A streak is a run of them no more than 10 minutes apart, across sessions, and it may reach back before the hour. Agent activity between two of your actions does not bridge a gap. |
 | `out-tok` | Assistant output tokens, summed once per request and only for requests that produced a text block. Claude Code repeats the same usage on each content block of a response, and a request holding only tool calls is not text anyone reads. |
 
 `bun run stats --days 14` is the tool the norms were set with. It prints the per-hour distribution of each signal over the active hours of a window (n, p50, p75, p90, max, and how many hours were zero), the top hours by reports and by human prompts, and a format-drift line comparing records seen against events the parser recognised. Run it on another machine, or after a Claude Code update, to see whether the norms and the parser still fit. It prints numbers and nothing else.
@@ -237,7 +250,7 @@ bun install
 bun link
 ```
 
-`bun link` registers the clone's `bin` entry, so `zapara` runs this checkout; without it, `bun src/index.ts week` does the same thing.
+`bun link` registers the clone's `bin` entry, so `zapara` runs this checkout; without it, `bun src/index.ts` does the same thing.
 
 ```bash
 bun run check    # tsc --noEmit, then the test suite under TZ=UTC
@@ -245,6 +258,6 @@ bun run check    # tsc --noEmit, then the test suite under TZ=UTC
 
 Tests are fixture-driven: they build or load transcripts in the real Claude Code format and assert the statistics that come out of the public seams, `analyze()`, `report()` and the CLI itself. No test imports the parser, the deriver or the scanner, so refactoring internals never touches a test. The rules every change follows are in [CLAUDE.md](CLAUDE.md), the design is in [docs/superpowers/specs/2026-09-17-zapara-design.md](docs/superpowers/specs/2026-09-17-zapara-design.md), and every change is recorded in [CHANGELOG.md](CHANGELOG.md).
 
-## License
+---
 
-MIT. See [LICENSE](LICENSE).
+<p align="center">Made with ❤️ and 🥤 energy under <a href="LICENSE">MIT License</a></p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/zapara",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Cognitive load index for people driving Claude Code, computed locally from transcripts",
   "license": "MIT",
   "author": "Anton Yakutovich",

package/src/analyze.ts

@@ -1,12 +1,11 @@
-import { derive } from "./derive.ts";
+import { compareStrings, derive } from "./derive.ts";
 import { parseTranscript } from "./parse.ts";
 import type { Day, Transcript, Window } from "./types.ts";
 
-// The core's entry point: transcripts already in memory, in the real JSONL format, in.
-// Day[] out. Transcripts are sorted by path so file discovery order cannot change a result.
+// Sorted by path so file discovery order cannot change a result.
 export function analyze(transcripts: Transcript[], w: Window): Day[] {
   const events = [...transcripts]
-    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .sort((a, b) => compareStrings(a.path, b.path))
     .flatMap((t) => parseTranscript(t.text));
   return derive(events, w);
 }

package/src/card.ts

@@ -1,7 +1,5 @@
-// Card data: which of four characters a window is, the sentence behind it, the
-// peak hour, the load spectrum and three highlights, every value already
-// formatted for the page. Pure: Day[] in, CardData out. Nothing here knows a
-// date, a path or a file, so nothing here can leak one.
+// Pure: Day[] in, CardData out, every value already formatted for the page.
+// Nothing here knows a date, a path or a file, so nothing here can leak one.
 import { formatCount, formatTokens, plural } from "./format.ts";
 import { NORMS, WEIGHTS } from "./score.ts";
 import type { Day, HourBucket, Level, Score } from "./types.ts";
@@ -34,9 +32,8 @@ const MOTTOS: Record<Character, string> = {
   marathoner: "You do not stop while it compiles.",
   nightOwl: "The best commits happen after midnight.",
 };
-// Ranking norms for the third highlight: a value over its norm says how remarkable
-// it is next to the others. Sums are per active hour. These rank a picture and
-// never touch the index; the index's own norms stay in score.ts.
+// Rank the third highlight, per active hour. They never touch the index, whose
+// norms stay in score.ts.
 const CARD_NORMS = { reportsPerHour: 12, tokensPerHour: 65_000, interruptsPerHour: 3, latePercent: 25 } as const;
 const OWNED: Record<Character, [HighlightKey, HighlightKey]> = {
   conductor: ["peakSessions", "contextSwitches"],
@@ -94,15 +91,15 @@ export function cardData(days: Day[], w: { days: number }): CardData | null {
   const max = (f: (b: Active) => number): number => active.reduce((a, b) => Math.max(a, f(b)), 0);
   const count = (level: Level): number => active.filter((b) => b.score.level === level).length;
 
-  // Each share is the fraction of that character's maximum possible points the
-  // window collected, so a 10-point component competes fairly with a 40-point one.
+  // A share is the fraction of the character's maximum points, so a 10-point
+  // component competes fairly with a 40-point one.
   const shares: Record<Character, number> = {
     conductor: sum((b) => b.score.parts.parallel + b.score.parts.pace) / ((WEIGHTS.parallel + WEIGHTS.pace) * n),
     supervisor: sum((b) => b.score.parts.supervision + b.score.parts.reading) / ((WEIGHTS.supervision + WEIGHTS.reading) * n),
     marathoner: sum((b) => b.score.parts.streak) / (WEIGHTS.streak * n),
     nightOwl: sum((b) => b.score.parts.late) / (WEIGHTS.late * n),
   };
-  // Strict > keeps the earlier of equal shares: CHARACTERS is the tie order.
+  // Strict >: CHARACTERS is the tie order.
   const character = CHARACTERS.reduce((best, c) => (shares[c] > shares[best] ? c : best));
 
   const maxSessions = max((b) => b.sessions);
@@ -143,7 +140,7 @@ export function cardData(days: Day[], w: { days: number }): CardData | null {
     lateShare: late / CARD_NORMS.latePercent,
   };
   const owned = OWNED[character];
-  // A late-night number on anyone but the Night Owl is the kind of thing they would hide.
+  // A late-night number belongs to the Night Owl alone.
   const rest = POOL.filter((k) => !owned.includes(k) && (k !== "lateShare" || character === "nightOwl"));
   const third = rest.reduce((best, k) => (norms[k] > norms[best] ? k : best));
   const highlights = [...owned, third].map((key) => ({ key, value: values[key], caption: CAPTIONS[key] }));

package/src/cardhtml.ts

@@ -1,7 +1,6 @@
-// The card page: one self-contained HTML document from CardData and the embedded
-// assets. Pure: strings in, string out. Nothing is escaped because nothing from a
-// transcript reaches this file: only CardData's fixed strings and formatted numbers.
-// The look is the table in docs/superpowers/specs/2026-09-18-zapara-card-design.md.
+// Nothing is escaped because nothing from a transcript reaches this file: only
+// CardData's fixed strings and formatted numbers. The look is the table in
+// docs/superpowers/specs/2026-09-18-zapara-card-design.md.
 import type { CardData, Character, Segment } from "./card.ts";
 import type { Level } from "./types.ts";
 
@@ -10,10 +9,8 @@ export type CardAssets = {
   characters: string;
 };
 
-// Where each character sits on the sheet, as fractions [x, y, w, h] of its side,
-// measured on the current assets/characters.webp. The box is scaled so the
-// rectangle's longer side is BOX px and centred at CENTRE, with CSS background-size
-// and background-position, so no cropping happens anywhere.
+// Fractions [x, y, w, h] of the sheet's side, measured on assets/characters.webp.
+// Scaled so the longer side is BOX px, centred at CENTRE; nothing is cropped.
 export const CHARACTER_RECTS: Record<Character, [number, number, number, number]> = {
   conductor: [0.02, 0.01, 0.53, 0.543],
   supervisor: [0.55, 0.07, 0.38, 0.505],
@@ -23,7 +20,7 @@ export const CHARACTER_RECTS: Record<Character, [number, number, number, number]
 const BOX = 360;
 const CENTRE = { x: 195, y: 300 };
 
-// Streak accent, its rgb for alpha gradients, and the light shade for the repo link.
+// main, its rgb for alpha gradients, and the light shade for the repo link.
 const ACCENT: Record<Character, { main: string; rgb: string; light: string }> = {
   conductor: { main: "#8b5cf6", rgb: "139,92,246", light: "#c4b5fd" },
   supervisor: { main: "#22d3ee", rgb: "34,211,238", light: "#a5f3fc" },