ytstats 0.1.0

package/docs/cli.md

@@ -0,0 +1,285 @@
+---
+description: Complete ytstats command reference — every command, flag, default, and exit code.
+tags: [cli, commands, flags, reference]
+source:
+  - src/cli.js
+  - src/dates.js
+---
+
+# CLI Reference
+
+Every command, every flag. For the shape of what comes back, see [output-contract.md](output-contract.md). For what the underlying API calls cost, see [youtube-apis.md](youtube-apis.md).
+
+## Invocation
+
+```bash
+ytstats [global flags] <command> [command flags]
+```
+
+Installed globally, or run without installing via `npx ytstats <command>`.
+
+## Global flags
+
+Global flags go **before** the command name.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `-a, --account <channel>` | the default account | Channel id or `@handle` to use when several are signed in |
+| `--compact` | off | Single-line JSON instead of pretty-printed |
+| `-q, --quiet` | off | Suppress progress and warnings on stderr; stdout is unaffected |
+| `-V, --version` | — | Print the package version and exit 0 |
+| `-h, --help` | — | Print usage and exit 0 |
+
+```bash
+ytstats --account UC1234567890 --compact daily --days 7
+```
+
+`--account` accepts a channel id, a custom URL/handle, or a channel title — `loadAccount()` matches the id first, then falls back to a case-insensitive comparison against `customUrl` and `channelTitle`. An unrecognised selector fails with `AUTH_ACCOUNT_UNKNOWN`; it never silently falls back to the default.
+
+## Date window flags
+
+Every analytics command accepts the same three flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `-d, --days <number>` | `90` | Days of history ending today (UTC) |
+| `--start <date>` | — | `YYYY-MM-DD`; overrides `--days` |
+| `--end <date>` | today (UTC) | `YYYY-MM-DD` |
+
+Rules enforced before any network call:
+
+- Dates must match `YYYY-MM-DD` exactly. A locale format such as `01/01/2026` fails with `INPUT_INVALID_DATE`.
+- The date must exist on the calendar. `2026-02-31` is rejected — `Date` would otherwise roll it silently into March.
+- `--days` must be a positive number, and at most **3650** (enforced in `src/dates.js`).
+- `--start` must be on or before `--end`, checked only once both parse cleanly.
+
+All input problems are reported **together**, in one envelope, before authentication:
+
+```bash
+$ ytstats daily --start 01/01/2026 --end yesterday --days -3
+# → 3 errors in one envelope: two INPUT_INVALID_DATE, one INPUT_INVALID_RANGE
+```
+
+## Authentication commands
+
+### login
+
+```bash
+ytstats login [-c|--client-secret <path>] [--no-browser] [--timeout <seconds>]
+```
+
+Runs the loopback OAuth flow: opens the browser, captures the callback on `127.0.0.1`, exchanges the code, fetches the channel identity, and stores both the OAuth client and the tokens.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `-c, --client-secret <path>` | resolution order below | Path to the `client_secret` JSON downloaded from Google Cloud |
+| `--no-browser` | off | Print the URL and read the pasted redirect back — for SSH and headless machines |
+| `--timeout <seconds>` | `300` | How long to wait for the browser callback, so an automated caller is never blocked indefinitely |
+
+Credentials are resolved in this order: `--client-secret` → `YTSTATS_CLIENT_ID`/`YTSTATS_CLIENT_SECRET` → stored `credentials.json` → `client_secret*.json` in the working directory. See [configuration.md](configuration.md).
+
+Returns `{ channelId, channelTitle, customUrl, configDir }`.
+
+```bash
+ytstats login --client-secret ~/Downloads/client_secret_1234.json
+ytstats login --no-browser          # headless
+```
+
+### logout
+
+```bash
+ytstats logout [--all] [--forget-credentials]
+```
+
+Revokes the token with Google (best effort) and deletes it locally.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--all` | off | Log out of every channel on this machine |
+| `--forget-credentials` | off | Also delete the stored OAuth client id and secret |
+
+Local removal happens even when revocation fails — being offline should not leave credentials on disk. Returns `{ loggedOut, revoked, accounts }`.
+
+### status
+
+```bash
+ytstats status
+```
+
+Reports who is signed in and where configuration lives. Takes no flags and needs no authentication.
+
+Returns `{ authenticated, configDir, credentialSource, accounts[], setupGuide? }`. Each account carries `channelId`, `channelTitle`, `customUrl`, `savedAt`, and `isDefault` — never token material. `setupGuide` appears only when no account is signed in.
+
+### doctor
+
+```bash
+ytstats doctor
+```
+
+Runs four independent readiness checks, cheapest first, and reports all of them rather than stopping at the first failure:
+
+| Check id | What it proves |
+|---|---|
+| `config_writable` | The config directory exists and accepts a write (probe file is written then removed) |
+| `credentials` | An OAuth client resolved from some source |
+| `signed_in` | At least one channel has stored tokens |
+| `api_reachable` | A live `channels.list` call succeeds with the stored token |
+
+`api_reachable` is skipped when earlier checks failed, since it cannot succeed.
+
+`doctor` itself always succeeds — `ok: true`, exit 0. The verdict is `data.healthy`, and the blocking diagnostics are in `data.blocking`. Failures are also attached as envelope warnings. This is deliberate: a health check that exits non-zero when it finds a problem is reporting its own success incorrectly.
+
+### use
+
+```bash
+ytstats use <channelId|@handle>
+```
+
+Sets the default channel for subsequent commands. Fails if that channel is not signed in.
+
+### import-legacy
+
+```bash
+ytstats import-legacy <tokensFile> [-c|--client-secret <path>]
+```
+
+Imports tokens from a pre-`ytstats` project-local `tokens.json`. The legacy file holds no channel identity, so the tokens are exchanged for one before anything is stored. Never overwrites an account that already exists — it returns `{ migrated: false, reason }` instead, where `reason` is one of `no-legacy-file`, `no-refresh-token`, `unknown-channel`, or `already-logged-in`.
+
+## fetch
+
+```bash
+ytstats fetch [--days 90] [--start <date>] [--end <date>]
+              [--no-retention] [--retention-limit <n>] [--reach]
+```
+
+Every dimension in a single JSON document — the command to pipe into a script.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--no-retention` | retention on | Skip retention curves, which cost one API call per video |
+| `--retention-limit <number>` | `50` | How many recent videos to pull retention for, newest first |
+| `--reach` | off | Also include thumbnail impressions and CTR from the Reporting API |
+
+`data` contains `channel`, `videos`, `daily`, `videoAnalytics`, `trafficSources`, `trafficSourceDetails`, `demographics`, `deviceTypes`, `contentTypes`, `searchTerms`, `geography`, `playbackLocations`, `audienceRetention`, and `reach` when `--reach` is passed.
+
+Alongside it: `period` (`{ startDate, endDate, days }`), `warnings` (per-step failures, each `{ step, code, message }`), and `notes` (informational, such as a truncated retention run).
+
+Individual analytics steps degrade rather than abort — see [architecture.md](architecture.md#fetch-all-orchestration).
+
+```bash
+ytstats fetch --days 90 > snapshot.json
+ytstats fetch --no-retention --days 30      # cheapest full fetch
+ytstats fetch --reach                       # includes CTR, if reports exist yet
+```
+
+## Dataset commands
+
+All of these accept the date window flags above and return `{ period, rows }`. An empty `rows` array raises a `DATA_EMPTY` warning so "the query worked and found nothing" is distinguishable from "the query failed".
+
+| Command | Returns | Extra flags |
+|---|---|---|
+| `channel` | Channel metadata and lifetime stats *(no period; no date flags)* | — |
+| `videos` | Every video with metadata and current counts *(no period; no date flags)* | see below |
+| `daily` | Day-by-day views, watch time, likes, comments, subscribers | — |
+| `traffic` | Views by traffic source type | — |
+| `demographics` | Viewer age and gender split | — |
+| `devices` | Views by device type | — |
+| `content-types` | Shorts vs long-form vs live, using YouTube's own `creatorContentType` | — |
+| `search-terms` | What people search on YouTube to find the channel | `-n, --limit` (default `25`, capped at 25) |
+| `geography` | Viewer breakdown by country | `-n, --limit` (default `50`) |
+| `playback-locations` | Where viewers watch — Shorts feed, watch page, embedded | — |
+| `video-analytics` | Per-video metrics, top 200 by views | — |
+
+### channel
+
+```bash
+ytstats channel
+```
+
+Returns the channel resource directly, not `{ period, rows }`: `id`, `title`, `description`, `customUrl`, `publishedAt`, `country`, `subscriberCount`, `viewCount`, `videoCount`, `uploadsPlaylistId`, `thumbnailUrl`.
+
+### videos
+
+```bash
+ytstats videos [-n <number>] [-s <field>] [--order asc|desc] [-t <type>]
+```
+
+| Flag | Default | Choices |
+|---|---|---|
+| `-n, --limit <number>` | all | — |
+| `-s, --sort <field>` | `publishedAt` | `publishedAt`, `viewCount`, `likeCount`, `commentCount`, `durationSeconds` |
+| `--order <dir>` | `desc` | `asc`, `desc` |
+| `-t, --type <type>` | all | `SHORTS`, `VIDEO_ON_DEMAND`, `LIVE_STREAM` |
+
+Filtering and sorting happen locally after every video is fetched, so `-n` reduces output size but not API cost. `contentType` is duration-based and can disagree with YouTube's own classification — see [the gotcha](gotchas/youtube-api.md#two-content-type-vocabularies-disagree).
+
+```bash
+ytstats videos --type SHORTS --sort viewCount | jq '.data[0:5]'
+```
+
+### retention
+
+```bash
+ytstats retention <videoId> [--days 90] [--start <date>] [--end <date>]
+```
+
+Audience retention curve for one video — roughly 100 points at 1% intervals. Returns `{ videoId, period, curve }`, where each point is `{ position, ratio }`.
+
+Ratios above `1.0` are correct and never clamped: a Short showing `1.54` means viewers looped it.
+
+## reach
+
+```bash
+ytstats reach
+ytstats reach-jobs
+```
+
+`reach` is the only source of thumbnail impressions and CTR. It works unlike every other command because the data comes from the asynchronous Reporting API: the first run only *creates* the job, and reports appear 24-48 hours later with a 30-day backfill.
+
+Returns `{ job, reportCount, pending, rows[] }`, plus `message` when pending. A pending result is a `REACH_PENDING` **warning**, not an error — the command succeeded, the data does not exist yet. Re-running is harmless and creates no duplicate job.
+
+Rows carry `date`, `channelId`, `videoId`, `impressions`, and `impressionsCtr`. **`impressionsCtr` is a decimal fraction, not a percentage**: `0.0561` means 5.61%.
+
+`reach-jobs` lists the Reporting API jobs on the channel.
+
+## query
+
+```bash
+ytstats query -m <metrics> [--dimensions <list>] [--filters <expr>]
+              [--sort <field>] [-n <max>] [date flags]
+```
+
+Escape hatch for an arbitrary YouTube Analytics API query.
+
+| Flag | Required | Notes |
+|---|---|---|
+| `-m, --metrics <list>` | yes | Comma-separated, e.g. `views,likes` |
+| `--dimensions <list>` | no | Comma-separated, e.g. `day` |
+| `--filters <filters>` | no | e.g. `video==VIDEO_ID` |
+| `--sort <field>` | no | Prefix with `-` for descending |
+| `-n, --max <number>` | no | Maximum rows |
+
+Returns `{ columns, rows }`, where `columns` is `[{ name, type }]` taken from the response's `columnHeaders`.
+
+The Analytics API rejects many documented combinations, and which ones vary by channel — a rejection surfaces as `API_QUERY_NOT_SUPPORTED`. Notably `videoThumbnailImpressions` never works; use `reach` instead.
+
+```bash
+ytstats query -m views,likes --dimensions day --start 2026-01-01
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. Warnings do not change this. |
+| `1` | General or unexpected failure |
+| `2` | Authentication |
+| `3` | Bad input |
+| `4` | API error |
+
+The code is also available as `meta.exitCode` in the envelope, so a consumer that can only read stdout still knows.
+
+```bash
+ytstats fetch --days 30 2>/dev/null | jq '.data.channel.subscriberCount'
+ytstats fetch 2>/dev/null | jq -r 'if .ok then "fine" else .nextSteps[0] end'
+```

package/docs/configuration.md

@@ -0,0 +1,127 @@
+---
+description: Environment variables, the per-user config directory, stored file formats, and CI setup.
+tags: [configuration, environment, config-directory, ci]
+source:
+  - src/config/**
+  - src/auth/credentials.js
+---
+
+# Configuration
+
+`ytstats` has no config file of its own. Everything is either an environment variable or state written by `login`. For the traps in the storage layer, see [gotchas/config-storage.md](gotchas/config-storage.md).
+
+## Environment variables
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `YTSTATS_CONFIG_DIR` | `resolveConfigDir()` | Overrides the config directory entirely. Relative values are resolved to absolute against the working directory |
+| `YTSTATS_CLIENT_ID` | `resolveCredentials()` | OAuth client id. **Both** this and the secret must be set for the pair to be used |
+| `YTSTATS_CLIENT_SECRET` | `resolveCredentials()` | OAuth client secret |
+| `XDG_CONFIG_HOME` | `resolveConfigDir()` | Linux/BSD config base. **Ignored when relative**, per the XDG spec |
+| `APPDATA` | `resolveConfigDir()` | Windows config base; falls back to `%USERPROFILE%\AppData\Roaming` |
+| `HTTPS_PROXY` | `googleapis` / Node | Standard proxy variable, named in the `NETWORK_UNREACHABLE` remediation |
+
+Note the deliberate asymmetry: a relative `XDG_CONFIG_HOME` is ignored because the spec says so, while a relative `YTSTATS_CONFIG_DIR` is accepted and resolved — it is an explicit override, not an environment convention.
+
+## The config directory
+
+`resolveConfigDir({ platform, env, home })` picks the location, checking `YTSTATS_CONFIG_DIR` first and otherwise following platform convention:
+
+| OS | Location |
+|---|---|
+| macOS | `~/Library/Application Support/ytstats/` |
+| Linux / BSD | `$XDG_CONFIG_HOME/ytstats/`, default `~/.config/ytstats/` |
+| Windows | `%APPDATA%\ytstats\` |
+
+The function is pure — platform, environment, and home directory are all parameters. Only `configDir()` reads `process.platform`, `process.env`, and `os.homedir()`. That is what lets the test suite assert Windows and Linux behaviour while running on macOS.
+
+`ytstats status` and `ytstats doctor` both report the resolved path.
+
+## Stored files
+
+Two files, both written by `login`.
+
+### credentials.json
+
+The BYO OAuth client, saved so later commands need no flags — and because Google's token endpoint requires the client secret on **every** refresh, not just the initial exchange.
+
+```jsonc
+{
+  "version": 1,
+  "clientId": "123456789012-abc.apps.googleusercontent.com",
+  "clientSecret": "GOCSPX-…",
+  "source": "/Users/you/Downloads/client_secret_1234.json",
+  "savedAt": "2026-07-27T10:00:00.000Z"
+}
+```
+
+`source` records where the credentials originally came from, for display only.
+
+### tokens.json
+
+The multi-account token store, keyed by channel id:
+
+```jsonc
+{
+  "version": 1,
+  "default": "UC…",
+  "accounts": {
+    "UC…": {
+      "channelId": "UC…",
+      "channelTitle": "…",
+      "customUrl": "@…",
+      "tokens": { "access_token": "…", "refresh_token": "…", "expiry_date": 0 },
+      "savedAt": "2026-07-27T10:00:00.000Z"
+    }
+  }
+}
+```
+
+Deleted entirely when the last account is removed. See [auth.md](auth.md#token-storage) for how it is read and merged.
+
+## Permissions and write discipline
+
+Everything the store holds is a secret, so:
+
+- The directory is created at `0700` and the mode is re-asserted with `chmod`, since `mkdir`'s mode is masked by umask and the directory may predate the run.
+- Files are written at `0600`. The temp file is created **at** that mode rather than chmod'd afterwards, so the secret is never briefly world-readable.
+- Writes are atomic: a uniquely-named temp file in the same directory, then `rename`. A crash never leaves a half-written token file, and a concurrent reader never sees one.
+- File names must be flat basenames. Separators, `..`, absolute paths, and NUL are **rejected**, not sanitised.
+
+On Windows POSIX modes are meaningless; the protection there is the per-user `%APPDATA%` location.
+
+These are plaintext files, the same approach `gcloud`, `gh`, and `aws` take. `ytstats logout` revokes the token with Google and deletes them.
+
+## CI and headless machines
+
+Supply the OAuth client through the environment instead of a file:
+
+```bash
+export YTSTATS_CLIENT_ID=123456789012-abc.apps.googleusercontent.com
+export YTSTATS_CLIENT_SECRET=GOCSPX-…
+export YTSTATS_CONFIG_DIR=$PWD/.ytstats     # if $HOME is not writable
+ytstats login --no-browser
+```
+
+Both `YTSTATS_CLIENT_ID` and `YTSTATS_CLIENT_SECRET` must be set — one alone is ignored and resolution falls through to the next source.
+
+`--no-browser` prints the authorization URL and reads the pasted redirect back, so a machine with no browser can still complete the flow. The refresh token it produces is then reusable, provided the consent screen is published to Production — in Testing mode Google expires it after 7 days.
+
+If the config directory is not writable, `doctor` reports `CONFIG_UNWRITABLE` and its remediation points at `YTSTATS_CONFIG_DIR`.
+
+## Credential resolution order
+
+Ordered in `resolveCredentials()`; the first complete pair wins:
+
+1. `--client-secret <file>`
+2. `YTSTATS_CLIENT_ID` + `YTSTATS_CLIENT_SECRET` (both required)
+3. Stored `credentials.json`
+4. `client_secret*.json` auto-discovered in the working directory
+
+Auto-discovery prefers an exact `client_secret.json`, otherwise takes the alphabetically first match so the same directory always resolves the same way. Full detail in [auth.md](auth.md#credential-resolution).
+
+## Not committing credentials
+
+The repository's `.gitignore` excludes `client_secret*.json`, `credentials.json`, `tokens.json`, and `.env` — because a downloaded client secret can easily land in the working directory during testing, and auto-discovery means it will be picked up from there.
+
+The stored copies live in the per-user config directory, outside any repository.

package/docs/contributing.md

@@ -0,0 +1,155 @@
+---
+description: How to extend ytstats — adding datasets, commands, and diagnostics; the dependency policy; and the release process.
+tags: [contributing, workflow, dependencies, release, versioning]
+source:
+  - package.json
+  - CHANGELOG.md
+  - vitest.config.js
+---
+
+# Contributing
+
+How to change `ytstats` without breaking the contracts it makes. Read [architecture.md](architecture.md) first for how the pieces fit together.
+
+## Adding a new dataset
+
+1. **Add the fetcher** to the relevant `src/api/*.js`, taking `apis` as its first argument so it stays injectable.
+2. **Add a test asserting the exact query parameters**, not just the return shape. That is what protects the undocumented API limits — a test that only checks returned rows lets someone raise `maxResults` and reintroduce an opaque failure.
+3. **Wire it into `fetch-all.js` behind `step()`** so a failure degrades to a warning rather than aborting the whole run.
+4. **Add a dedicated command in `cli.js`** if it is independently useful. Most analytics datasets can use the `simple()` helper, which supplies the date flags, the range validation, and the `DATA_EMPTY` warning.
+5. **Add a diagnostic to `diagnostics.js`** if it introduces a new failure mode. The catalog test fails unless the entry has a title, detail, cause, and at least one remediation step.
+6. **Update [cli.md](cli.md), [youtube-apis.md](youtube-apis.md), and `CHANGELOG.md`.**
+
+If YouTube rejects a metric or dimension combination in a way that is not obvious, add it to [gotchas/youtube-api.md](gotchas/youtube-api.md) naming the handling site — so the next person does not undo the workaround.
+
+## Adding a command
+
+Commands live in `src/cli.js`, grouped by section. Three helpers exist:
+
+- **`run(name, body, { validate })`** wraps a command body: diagnostics in, one envelope plus exit code out. The `validate` callback runs **before** authentication and returns an array of diagnostics rather than throwing, so every input problem is reported at once.
+- **`simple(name, description, fn)`** defines a date-windowed analytics command with the standard flags, range validation, and empty-result warning. Returns the command so extra options can be chained.
+- **`dateOptions(cmd)`** adds `--days`, `--start`, and `--end` to a command built by hand.
+
+Use `withApis(globalOpts)` to authenticate and get the API bundle. Never write to stdout directly — go through `reporter.succeed()` or `reporter.fail()`, or you break the one-JSON-document guarantee.
+
+Commander's negated options read inverted: `--no-retention` surfaces as `cmdOpts.retention`, defaulting to `true`.
+
+## Adding a diagnostic
+
+Entries in `DIAGNOSTICS` (`src/diagnostics.js`) are built with the `def()` helper, which defaults `severity` to `error` and `exitCode` to `EXIT.GENERAL`. A complete entry needs:
+
+```js
+MY_NEW_CODE: def({
+  code: 'MY_NEW_CODE',
+  exitCode: EXIT.API,
+  recoverable: true,      // can this be fixed at all?
+  retryable: false,       // would re-running the SAME command help?
+  title: '…',
+  detail: '…',
+  cause: '…',
+  remediation: { summary: '…', steps: ['…'], commands: [DOCTOR_CMD], docs: ['…'] },
+})
+```
+
+Get `recoverable` and `retryable` right — they are the anti-loop signals an agent depends on. Marking something `retryable: true` when a retry cannot help sends a caller into an infinite loop.
+
+Use `defaults: { … }` for context values that must appear even when a call site forgets to pass them, as `INPUT_INVALID_DATE` does with `expected`.
+
+Throw it with `fail(DIAGNOSTICS.MY_NEW_CODE, { … })` rather than constructing a `YtStatsError` by hand.
+
+## The stability contract
+
+**`code` values are public API.** Scripts and agents consuming `ytstats` JSON branch on them. Add new codes freely; never repurpose an existing one, and never delete one without a major version bump.
+
+The same applies to the envelope's shape invariance — every key present on every response — and to the rule that `data` is `null` whenever `ok` is false. See [output-contract.md](output-contract.md).
+
+## Dependency policy
+
+**No native dependencies.** `npx ytstats` must start instantly, which rules out anything requiring a prebuild download or a node-gyp compile. Runtime dependencies are `commander`, `googleapis`, and `open` — all pure JS. Think hard before adding a fourth.
+
+Node 18 or newer is required (`engines.node`).
+
+### The gaxios override
+
+`package.json` pins `gaxios` above its transitive default:
+
+```jsonc
+"overrides": { "gaxios": "^7.1.4" }
+```
+
+`package.json` carries the rationale inline under `overridesRationale`: `googleapis-common` pins gaxios 7.1.3, which drags in `rimraf > glob > minimatch > brace-expansion` and a high-severity DoS advisory (GHSA-mh99-v99m-4gvg). gaxios 7.1.4+ dropped that chain. Same major version, so this is a patch-level floor rather than a compatibility risk.
+
+**Remove the override once `googleapis-common` raises its own floor.** Keeping a stale override silently pins a dependency the upstream has moved past.
+
+## Testing requirements
+
+Every change needs tests, and the suite must stay offline. See [testing.md](testing.md) for the injection seams available.
+
+The two rules that catch the most regressions:
+
+- Assert **exact query parameters** on API fetchers, since that is what pins the undocumented limits.
+- Use `useTempConfigDir()` for anything touching the config store, so tests never read real credentials.
+
+## Release process
+
+The package is published to npm. `files` in `package.json` limits the tarball to `bin/`, `src/`, `docs/`, `README.md`, `CHANGELOG.md`, and `LICENSE` — tests and config are not shipped.
+
+A release has two halves, and the split is deliberate:
+
+| Half | Steps | Automated? |
+|---|---|---|
+| **Cut the release** | Version bump, changelog, commit, tag | Yes — the `release-cli` skill |
+| **Ship to production** | `git push`, `npm publish` | No — always manual |
+
+Nothing publishes to npm without a human running `npm publish`. That boundary is the point, not an unfinished feature.
+
+### Cutting a release manually
+
+These steps are the contract. The skill below automates them; it does not replace them.
+
+1. Make sure `npm test` passes. `prepublishOnly` runs it again and blocks publication on failure.
+2. Update `CHANGELOG.md`. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/): move entries out of `## [Unreleased]` into a new version heading with its date, and update the link references at the bottom.
+3. Bump the version in `package.json` following [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Removing or repurposing a diagnostic `code`, changing the envelope shape, or dropping a command is a **major** bump — see [The stability contract](#the-stability-contract).
+4. Commit `package.json` and `CHANGELOG.md` only, as `chore(release): ytstats v<version>`.
+5. Tag it: `git tag -a v<version> -m "Release v<version>"`.
+
+`meta.version` in the envelope is read from `package.json` at runtime, so it tracks the bump automatically.
+
+### Cutting a release with the release-cli skill
+
+`release-cli` is an AI-agent skill that performs steps 1-5 above. It is **optional tooling, not a project dependency** — it lives in `.agents/skills/release-cli/` and is excluded from the npm tarball, so a clone or an npm install does not necessarily have it. Install it with [HappySkills](https://happyskills.ai) if it is absent.
+
+```bash
+/release-cli                              # analyze changes and propose a bump
+/release-cli minor "Added --json-lines"   # force the bump level, supply a note
+/release-cli unreleased                   # record changes only, no bump or tag
+```
+
+**Three gates must pass before it will cut a release**, and none can be overridden:
+
+1. The working directory is clean. A release commits only `package.json` and `CHANGELOG.md`, so uncommitted code would produce a tag whose commit does not contain the changes it ships.
+2. `npm test` passes.
+3. `## [Unreleased]` is non-empty — it refuses to stamp an empty version.
+
+**It warns on breaking changes rather than deciding for you.** The skill scans the diff for this project's documented major-bump triggers — a removed or repurposed diagnostic `code`, an envelope key that changed or became conditional, a dropped command, a remapped exit code, a dropped `src/index.js` export — and asks you to confirm the bump when it finds one. It is a `grep`-and-diff heuristic: it cannot see a code whose *meaning* changed while its string stayed the same, so it is a safety net, not a substitute for knowing what you changed.
+
+**The `unreleased` ledger mode** records changes into `## [Unreleased]` without bumping or tagging. It appends rather than replaces, so several sessions working the same branch can each record their own work and the next release promotes the whole section — instead of one session reconstructing everyone's scope from `git log` at release time.
+
+### Shipping to production
+
+After the tag exists, deployment is two manual commands:
+
+```bash
+git push && git push --tags
+npm publish
+```
+
+`prepublishOnly` re-runs the full test suite as the last gate before the tarball is built.
+
+> This repository currently has **no git remote configured**, so `git push` will fail until one is added. It also has no tags — `v0.1.0` shipped per the changelog but was never tagged, which leaves the `compare/v0.1.0...HEAD` link in `CHANGELOG.md` unresolved. Backfilling that tag would repair the link and give future releases a baseline to diff against.
+
+## Documentation
+
+Documentation lives in `docs/`, indexed from [README.md](../README.md). Each file carries frontmatter declaring the `source` globs it documents, and `doc-manifest.json` at the project root is the derived retrieval index — regenerated, never hand-edited.
+
+When a change touches code covered by a doc's `source` globs, update that doc in the same commit.