@tokenomist-ai/tokenomist-cli 0.1.1 → 0.2.0

package/dist/update-check.js

@@ -1,89 +1,12 @@
 #!/usr/bin/env node
+import {
+  package_default
+} from "./chunk-DCGA3ANT.js";
 
 // src/update-check.ts
 import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-
-// package.json
-var package_default = {
-  name: "@tokenomist-ai/tokenomist-cli",
-  version: "0.1.1",
-  description: "CLI tool for the Tokenomist API \u2014 query token unlocks, emissions, fundraising, burns, and buybacks from the terminal",
-  type: "module",
-  main: "dist/index.js",
-  bin: {
-    tok: "dist/index.js"
-  },
-  scripts: {
-    postinstall: "node scripts/postinstall.js",
-    build: "tsup",
-    dev: "tsup --watch",
-    start: "node dist/index.js",
-    test: "vitest run",
-    "test:watch": "vitest",
-    lint: "eslint src/ tests/",
-    "lint:fix": "eslint src/ tests/ --fix",
-    format: "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts'",
-    prepublishOnly: "npm run build"
-  },
-  keywords: [
-    "tokenomist",
-    "crypto",
-    "token",
-    "unlock",
-    "emission",
-    "fundraising",
-    "burn",
-    "buyback",
-    "cli",
-    "api"
-  ],
-  author: {
-    name: "tokenomist-ai",
-    email: "support@tokenomist.ai",
-    url: "https://tokenomist.ai"
-  },
-  license: "MIT",
-  repository: {
-    type: "git",
-    url: "git+https://github.com/tokenomist-ai/tokenomist-cli.git"
-  },
-  homepage: "https://github.com/tokenomist-ai/tokenomist-cli#readme",
-  bugs: {
-    url: "https://github.com/tokenomist-ai/tokenomist-cli/issues"
-  },
-  engines: {
-    node: ">=18.0.0"
-  },
-  publishConfig: {
-    access: "public"
-  },
-  files: [
-    "dist",
-    "skills/**",
-    "scripts/postinstall.js",
-    "LICENSE",
-    "README.md"
-  ],
-  dependencies: {
-    "cli-table3": "^0.6.5",
-    commander: "^12.1.0",
-    dotenv: "^16.4.7"
-  },
-  devDependencies: {
-    "@types/node": "^22.10.0",
-    eslint: "^9.16.0",
-    prettier: "^3.4.2",
-    tsup: "^8.3.5",
-    typescript: "^5.7.2",
-    "typescript-eslint": "^8.57.0",
-    vitest: "^3.2.4"
-  }
-};
-
-// src/update-check.ts
 var CONFIG_DIR = join(homedir(), ".tokenomist");
 var CACHE_PATH = join(CONFIG_DIR, "update-check.json");
 var ONE_DAY = 24 * 60 * 60 * 1e3;

package/dist/update-check.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/update-check.ts","../package.json"],"sourcesContent":["import { readFileSync, writeFileSync, mkdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { homedir } from \"node:os\";\nimport pkg from \"../package.json\" with { type: \"json\" };\n\nconst CONFIG_DIR = join(homedir(), \".tokenomist\");\nconst CACHE_PATH = join(CONFIG_DIR, \"update-check.json\");\nconst ONE_DAY = 24 * 60 * 60 * 1000;\nconst REGISTRY_URL = \"https://registry.npmjs.org/@tokenomist-ai%2Ftokenomist-cli/latest\";\n\ninterface UpdateCache {\n  latest: string;\n  current: string;\n  checkedAt: number;\n}\n\nasync function main() {\n  // Check if cache is fresh\n  try {\n    const raw = readFileSync(CACHE_PATH, \"utf-8\");\n    const cache = JSON.parse(raw) as UpdateCache;\n    if (Date.now() - cache.checkedAt < ONE_DAY) {\n      return; // Already checked recently\n    }\n  } catch {\n    // No cache or invalid — proceed with check\n  }\n\n  const current: string = pkg.version;\n\n  const res = await fetch(REGISTRY_URL, {\n    signal: AbortSignal.timeout(5000),\n  });\n\n  if (!res.ok) return;\n\n  const data = (await res.json()) as { version: string };\n  const latest = data.version;\n\n  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });\n\n  const cache: UpdateCache = { latest, current, checkedAt: Date.now() };\n  writeFileSync(CACHE_PATH, JSON.stringify(cache), { encoding: \"utf-8\", mode: 0o600 });\n}\n\nmain().catch(() => {});\n","{\n  \"name\": \"@tokenomist-ai/tokenomist-cli\",\n  \"version\": \"0.1.1\",\n  \"description\": \"CLI tool for the Tokenomist API — query token unlocks, emissions, fundraising, burns, and buybacks from the terminal\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.js\",\n  \"bin\": {\n    \"tok\": \"dist/index.js\"\n  },\n  \"scripts\": {\n    \"postinstall\": \"node scripts/postinstall.js\",\n    \"build\": \"tsup\",\n    \"dev\": \"tsup --watch\",\n    \"start\": \"node dist/index.js\",\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"lint\": \"eslint src/ tests/\",\n    \"lint:fix\": \"eslint src/ tests/ --fix\",\n    \"format\": \"prettier --write 'src/**/*.ts' 'tests/**/*.ts'\",\n    \"format:check\": \"prettier --check 'src/**/*.ts' 'tests/**/*.ts'\",\n    \"prepublishOnly\": \"npm run build\"\n  },\n  \"keywords\": [\n    \"tokenomist\",\n    \"crypto\",\n    \"token\",\n    \"unlock\",\n    \"emission\",\n    \"fundraising\",\n    \"burn\",\n    \"buyback\",\n    \"cli\",\n    \"api\"\n  ],\n  \"author\": {\n    \"name\": \"tokenomist-ai\",\n    \"email\": \"support@tokenomist.ai\",\n    \"url\": \"https://tokenomist.ai\"\n  },\n  \"license\": \"MIT\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/tokenomist-ai/tokenomist-cli.git\"\n  },\n  \"homepage\": \"https://github.com/tokenomist-ai/tokenomist-cli#readme\",\n  \"bugs\": {\n    \"url\": \"https://github.com/tokenomist-ai/tokenomist-cli/issues\"\n  },\n  \"engines\": {\n    \"node\": \">=18.0.0\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"files\": [\n    \"dist\",\n    \"skills/**\",\n    \"scripts/postinstall.js\",\n    \"LICENSE\",\n    \"README.md\"\n  ],\n  \"dependencies\": {\n    \"cli-table3\": \"^0.6.5\",\n    \"commander\": \"^12.1.0\",\n    \"dotenv\": \"^16.4.7\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^22.10.0\",\n    \"eslint\": \"^9.16.0\",\n    \"prettier\": \"^3.4.2\",\n    \"tsup\": \"^8.3.5\",\n    \"typescript\": \"^5.7.2\",\n    \"typescript-eslint\": \"^8.57.0\",\n    \"vitest\": \"^3.2.4\"\n  }\n}\n"],"mappings":";;;AAAA,SAAS,cAAc,eAAe,iBAAiB;AACvD,SAAS,YAAY;AACrB,SAAS,eAAe;;;ACFxB;AAAA,EACE,MAAQ;AAAA,EACR,SAAW;AAAA,EACX,aAAe;AAAA,EACf,MAAQ;AAAA,EACR,MAAQ;AAAA,EACR,KAAO;AAAA,IACL,KAAO;AAAA,EACT;AAAA,EACA,SAAW;AAAA,IACT,aAAe;AAAA,IACf,OAAS;AAAA,IACT,KAAO;AAAA,IACP,OAAS;AAAA,IACT,MAAQ;AAAA,IACR,cAAc;AAAA,IACd,MAAQ;AAAA,IACR,YAAY;AAAA,IACZ,QAAU;AAAA,IACV,gBAAgB;AAAA,IAChB,gBAAkB;AAAA,EACpB;AAAA,EACA,UAAY;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,QAAU;AAAA,IACR,MAAQ;AAAA,IACR,OAAS;AAAA,IACT,KAAO;AAAA,EACT;AAAA,EACA,SAAW;AAAA,EACX,YAAc;AAAA,IACZ,MAAQ;AAAA,IACR,KAAO;AAAA,EACT;AAAA,EACA,UAAY;AAAA,EACZ,MAAQ;AAAA,IACN,KAAO;AAAA,EACT;AAAA,EACA,SAAW;AAAA,IACT,MAAQ;AAAA,EACV;AAAA,EACA,eAAiB;AAAA,IACf,QAAU;AAAA,EACZ;AAAA,EACA,OAAS;AAAA,IACP;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,cAAgB;AAAA,IACd,cAAc;AAAA,IACd,WAAa;AAAA,IACb,QAAU;AAAA,EACZ;AAAA,EACA,iBAAmB;AAAA,IACjB,eAAe;AAAA,IACf,QAAU;AAAA,IACV,UAAY;AAAA,IACZ,MAAQ;AAAA,IACR,YAAc;AAAA,IACd,qBAAqB;AAAA,IACrB,QAAU;AAAA,EACZ;AACF;;;ADtEA,IAAM,aAAa,KAAK,QAAQ,GAAG,aAAa;AAChD,IAAM,aAAa,KAAK,YAAY,mBAAmB;AACvD,IAAM,UAAU,KAAK,KAAK,KAAK;AAC/B,IAAM,eAAe;AAQrB,eAAe,OAAO;AAEpB,MAAI;AACF,UAAM,MAAM,aAAa,YAAY,OAAO;AAC5C,UAAMA,SAAQ,KAAK,MAAM,GAAG;AAC5B,QAAI,KAAK,IAAI,IAAIA,OAAM,YAAY,SAAS;AAC1C;AAAA,IACF;AAAA,EACF,QAAQ;AAAA,EAER;AAEA,QAAM,UAAkB,gBAAI;AAE5B,QAAM,MAAM,MAAM,MAAM,cAAc;AAAA,IACpC,QAAQ,YAAY,QAAQ,GAAI;AAAA,EAClC,CAAC;AAED,MAAI,CAAC,IAAI,GAAI;AAEb,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,QAAM,SAAS,KAAK;AAEpB,YAAU,YAAY,EAAE,WAAW,MAAM,MAAM,IAAM,CAAC;AAEtD,QAAM,QAAqB,EAAE,QAAQ,SAAS,WAAW,KAAK,IAAI,EAAE;AACpE,gBAAc,YAAY,KAAK,UAAU,KAAK,GAAG,EAAE,UAAU,SAAS,MAAM,IAAM,CAAC;AACrF;AAEA,KAAK,EAAE,MAAM,MAAM;AAAC,CAAC;","names":["cache"]}
+{"version":3,"sources":["../src/update-check.ts"],"sourcesContent":["import { readFileSync, writeFileSync, mkdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { homedir } from \"node:os\";\nimport pkg from \"../package.json\" with { type: \"json\" };\n\nconst CONFIG_DIR = join(homedir(), \".tokenomist\");\nconst CACHE_PATH = join(CONFIG_DIR, \"update-check.json\");\nconst ONE_DAY = 24 * 60 * 60 * 1000;\nconst REGISTRY_URL = \"https://registry.npmjs.org/@tokenomist-ai%2Ftokenomist-cli/latest\";\n\ninterface UpdateCache {\n  latest: string;\n  current: string;\n  checkedAt: number;\n}\n\nasync function main() {\n  // Check if cache is fresh\n  try {\n    const raw = readFileSync(CACHE_PATH, \"utf-8\");\n    const cache = JSON.parse(raw) as UpdateCache;\n    if (Date.now() - cache.checkedAt < ONE_DAY) {\n      return; // Already checked recently\n    }\n  } catch {\n    // No cache or invalid — proceed with check\n  }\n\n  const current: string = pkg.version;\n\n  const res = await fetch(REGISTRY_URL, {\n    signal: AbortSignal.timeout(5000),\n  });\n\n  if (!res.ok) return;\n\n  const data = (await res.json()) as { version: string };\n  const latest = data.version;\n\n  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });\n\n  const cache: UpdateCache = { latest, current, checkedAt: Date.now() };\n  writeFileSync(CACHE_PATH, JSON.stringify(cache), { encoding: \"utf-8\", mode: 0o600 });\n}\n\nmain().catch(() => {});\n"],"mappings":";;;;;;AAAA,SAAS,cAAc,eAAe,iBAAiB;AACvD,SAAS,YAAY;AACrB,SAAS,eAAe;AAGxB,IAAM,aAAa,KAAK,QAAQ,GAAG,aAAa;AAChD,IAAM,aAAa,KAAK,YAAY,mBAAmB;AACvD,IAAM,UAAU,KAAK,KAAK,KAAK;AAC/B,IAAM,eAAe;AAQrB,eAAe,OAAO;AAEpB,MAAI;AACF,UAAM,MAAM,aAAa,YAAY,OAAO;AAC5C,UAAMA,SAAQ,KAAK,MAAM,GAAG;AAC5B,QAAI,KAAK,IAAI,IAAIA,OAAM,YAAY,SAAS;AAC1C;AAAA,IACF;AAAA,EACF,QAAQ;AAAA,EAER;AAEA,QAAM,UAAkB,gBAAI;AAE5B,QAAM,MAAM,MAAM,MAAM,cAAc;AAAA,IACpC,QAAQ,YAAY,QAAQ,GAAI;AAAA,EAClC,CAAC;AAED,MAAI,CAAC,IAAI,GAAI;AAEb,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,QAAM,SAAS,KAAK;AAEpB,YAAU,YAAY,EAAE,WAAW,MAAM,MAAM,IAAM,CAAC;AAEtD,QAAM,QAAqB,EAAE,QAAQ,SAAS,WAAW,KAAK,IAAI,EAAE;AACpE,gBAAc,YAAY,KAAK,UAAU,KAAK,GAAG,EAAE,UAAU,SAAS,MAAM,IAAM,CAAC;AACrF;AAEA,KAAK,EAAE,MAAM,MAAM;AAAC,CAAC;","names":["cache"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tokenomist-ai/tokenomist-cli",
-  "version": "0.1.1",
-  "description": "CLI tool for the Tokenomist API — query token unlocks, emissions, fundraising, burns, and buybacks from the terminal",
+  "version": "0.2.0",
+  "description": "CLI tool for the Tokenomist API — query token unlocks, emissions, fundraising, burns, buybacks, and point-in-time history from the terminal",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/skills/tokenomist-allocation-breakdown/SKILL.md

@@ -65,7 +65,8 @@ tok allocation detail solana --output json
 
 ## Domain Context
 
-- Allocations are **point-in-time analyses**. They reflect the current understanding of token distribution and may be updated as new information becomes available.
+- `tok allocation detail` reflects the **current** understanding of token distribution and may be updated as new information becomes available. To see the allocation as it was published at a past date or version, use `tok pit allocation <id> --as-of <date>` (see the `tokenomist-point-in-time` skill).
+- `totalLockedAmount` is the sum of the Scheduled rows' `allocationLockedAmount`; it can differ slightly from `tok token list`'s token-level figure, which is computed at a different instant.
 - `standardAllocationName` enables cross-project comparison — different projects may use different names for similar allocations (e.g., "Core Contributors" vs "Team"), but the standard name normalizes this.
 - `totalTBDLockedAmount` represents tokens that are known to be locked but have no defined unlock schedule. Their classification may change as the project releases more information.
 

package/skills/tokenomist-burn-buyback/SKILL.md

@@ -96,20 +96,23 @@ tok buyback detail aave --start 2024-01-01 --end 2024-12-31 --output json
 
 **Burn list:**
 - `totalBurnAmount` — total tokens burned for this token
+- `totalBurnValue` — USD value of those burns (null if no burn has a price; `0` in `burn detail` when no burn is in the range)
 
 **Burn detail:**
 - `burns[].burnDate` — when the burn happened
 - `burns[].amount` — tokens burned
+- `burns[].pricePerToken` / `burns[].value` — price and USD value at the burn
 - `burns[].burnType` — type of burn event
 - `burns[].metadata.burnReasons` — why tokens were burned
 
 **Buyback list:**
 - `totalBuybackAmount` — total tokens bought back
+- `totalBuybackValue` — USD value of those buybacks (null if none has a price; `0` in `buyback detail` when no buyback is in the range)
 
 **Buyback detail:**
 - `buybacks[].buybackDate` — when the buyback happened
 - `buybacks[].tokenAmount` — tokens bought back
-- `buybacks[].value` — USD value of buyback
+- `buybacks[].pricePerToken` / `buybacks[].value` — price and USD value of the buyback
 - `buybacks[].spentAmount` / `spentUnit` — what was spent (e.g. USDC)
 
 ## Analysis workflow
@@ -123,7 +126,8 @@ tok buyback detail aave --start 2024-01-01 --end 2024-12-31 --output json
 
 - A sequential buyback + burn is a **single** deflationary event, not two. Counting both would double-count the supply reduction.
 - Burns from **locked** supply don't reduce circulating supply — they reduce future potential supply instead.
-- The `startDate`/`endDate` filters on burn/buyback detail commands filter by **last activity date**, not the event date range. This is an API quirk — the filters determine which tokens to include based on when they last had activity.
+- `--start`/`--end` on burn/buyback detail keep events dated from `start` 00:00 UTC to `end` 00:00 UTC (an event later on the `end` day is excluded). With either set, the totals are recomputed from the kept events; without them they are all-time.
+- `burn list` / `buyback list` are paginated: the page position is printed to stderr (`Page 1/7 · 125 total`). Raise `--page-size` or walk `--page` to get every token.
 
 ## Workflow
 

package/skills/tokenomist-emission-report/SKILL.md

@@ -66,6 +66,10 @@ tok emission weekly arbitrum --start 2024-01-01 --end 2024-06-30 --output json
 tok emission weekly arbitrum --standard-allocation "founderTeam" --output json
 ```
 
+## Pagination
+
+List and series commands return one page (20 rows by default). The page position is printed to **stderr** — e.g. `Page 1/3 · 56 total · next: --page 2` — while stdout stays the JSON/CSV data. To get everything, raise `--page-size` or call again with `--page <n>` until the page equals the total pages. A page past the last returns the last page again, so never stop on "unchanged" data.
+
 ## Key output fields
 
 | Field | Description |

package/skills/tokenomist-fundraising-lookup/SKILL.md

@@ -80,6 +80,10 @@ tok investor detail andreessen-horowitz --is-lead-investor --output json
 tok investor detail andreessen-horowitz --funding-date-min 2023-01-01 --raised-amount-min 5000000 --output json
 ```
 
+## Pagination
+
+List and series commands return one page (20 rows by default). The page position is printed to **stderr** — e.g. `Page 1/3 · 56 total · next: --page 2` — while stdout stays the JSON/CSV data. To get everything, raise `--page-size` or call again with `--page <n>` until the page equals the total pages. A page past the last returns the last page again, so never stop on "unchanged" data.
+
 ## Key output fields
 
 **Token fundraising:**

package/skills/tokenomist-point-in-time/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: tokenomist-point-in-time
+description: See a token's tokenomics as published at a past version — allocations, daily emission and cliff unlocks as known on a given date. Use for history, audits, backtests, or explaining how a token's schedule changed over time.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tok
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tok]
+allowed-tools: Bash(tok:*)
+---
+
+# Skill: Point-in-Time History
+
+See a token's tokenomics as it was published at a past version: the versions on its timeline, and its allocations, daily emission and cliff unlock events as known at a given instant.
+
+## When to use
+
+- "What did the unlock schedule look like on 2024-01-01?" (backtests must not use data published later)
+- "When and how did this token's tokenomics change?"
+- Comparing two versions of a token's schedule.
+
+For the **current** data, use the regular commands (`tok allocation detail`, `tok emission daily`, `tok unlock events`) — they include USD values, which point-in-time answers do not.
+
+## Commands
+
+### List versions
+```bash
+tok pit versions <tokenId> --output json
+```
+
+| Option | Description |
+|--------|-------------|
+| `--start <date>` | Keep versions valid from this day (YYYY-MM-DD) |
+| `--end <date>` | Keep versions valid from up to this day (YYYY-MM-DD) |
+| `--page <number>` | Page number |
+| `--page-size <number>` | Items per page |
+
+Each version has `id`, `historyOrder`, `status` (`current` / `previous`), `validFrom`, `validUntil`, `previousVersionId`, `change` (`category`, `title`, `description`) and `changeReferences` (sources).
+
+### Data at a version
+```bash
+tok pit allocation <tokenId> --as-of 2024-01-01 --output json
+tok pit daily-emission <tokenId> --as-of 2024-01-01 --start 2024-03-01 --end 2024-03-31 --output json
+tok pit unlock-events <tokenId> --version-id <id> --output json
+```
+
+| Option | Description |
+|--------|-------------|
+| `--as-of <instant>` | Answer as known at this instant: `YYYY-MM-DD` or RFC 3339 (`2024-07-01T12:00:00Z`) |
+| `--version-id <id>` | Answer from this version (an `id` from `pit versions`) |
+| `--start <date>` / `--end <date>` | Date window (daily-emission, unlock-events) |
+| `--standard-allocation <names>` | `community`, `founderTeam`, `privateInvestors`, `publicInvestors`, `others`, `reserve` (comma-separated; daily-emission, unlock-events) |
+| `--page <number>` / `--page-size <number>` | Pagination (daily-emission, unlock-events) |
+
+Use `--as-of` **or** `--version-id`, never both. With neither, the current version answers.
+
+## Output (`--output json`)
+
+`pit allocation`, `pit daily-emission` and `pit unlock-events`:
+
+```json
+{
+  "asOf": "2024-01-01T00:00:00Z",
+  "version": { "id": "arbitrum-p-…", "historyOrder": 2, "validFrom": "…", "validUntil": "…", "status": "previous" },
+  "data": { },
+  "pagination": { "page": 1, "totalPages": 3, "pageSize": 20, "total": 45 }
+}
+```
+
+`pagination` is present on paginated commands only. `pit versions` returns `{ "data", "pagination" }` (no `asOf`/`version`). Walk `--page` until `page` equals `totalPages`.
+
+## Domain Context
+
+- **No USD fields**: point-in-time answers carry amounts only (no `unlockValue`, `cliffValue`, `referencePrice`, `valueToMarketCap`).
+- `pit daily-emission` is the **complete supply inflow** per day (cliff + linear) and keeps `totalCumulativeUnlockedAmount` as a running total. `pit unlock-events` is **cliff events only**. Never add the two over the same window (double-counts every cliff).
+- Never sum or mix figures across versions; each answer is one version's view.
+- Committed claims are kept only when timestamped at or before `asOf`.
+
+## Errors
+
+| Message | Meaning |
+|---------|---------|
+| `FORBIDDEN: Forbidden` | The plan has no point-in-time access (API, ELITE or TEAM required). |
+| `FORBIDDEN (PLAN_NOT_ELIGIBLE)` | `--as-of` is earlier than the plan allows; the message names the plan's range. `Earliest valid date:` (when present) is the first instant inside that range with a version. |
+| `… (NO_VERSION_AT_AS_OF)` | The token had no version yet at `--as-of`. `Earliest valid date:` names the first instant with one. |
+| `… (VERSION_NOT_FOUND)` | Unknown `--version-id` for this token. |
+| `… (INVALID_AS_OF)` | Malformed or future `--as-of`. |
+| `… (TOKEN_NOT_FOUND)` | Unknown token ID — resolve it with `tok token search <name>`. |

package/skills/tokenomist-unlock-analysis/SKILL.md

@@ -91,6 +91,10 @@ Options:
 tok unlock events solana --start 2025-01-01 --end 2025-12-31 --output json
 ```
 
+## Pagination
+
+List and series commands return one page (20 rows by default). The page position is printed to **stderr** — e.g. `Page 1/3 · 56 total · next: --page 2` — while stdout stays the JSON/CSV data. To get everything, raise `--page-size` or call again with `--page <n>` until the page equals the total pages. A page past the last returns the last page again, so never stop on "unchanged" data.
+
 ## Key output fields
 
 **unlock list / upcoming:**