@gtrabanco/pi-nan-provider 0.7.0 → 0.8.0

package/README.es.md

@@ -1,7 +1,7 @@
 # @gtrabanco/pi-nan-provider
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.6.5-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Version](https://img.shields.io/badge/version-0.8.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
 
 [NaN Builders](https://nan.builders) model provider + MCP bridges para [pi](https://github.com/earendil-works/pi). 
 
@@ -156,74 +156,99 @@ bun run check-nan-mcp-server --issue    # crea/refresca el issue
 
 ## 📊 Uso de Cuotas: `/nan-usage`
 
-Muestra tu uso de tokens de NaN por modelo, los límites mensuales y el tiempo hasta el reinicio del ciclo de facturación.
+Muestra tu uso de tokens de NaN por modelo combinado con los límites mensuales documentados, los totales de la ventana, tus totales acumulados y el tiempo hasta el reinicio del ciclo de facturación.
 
 ### Cómo funciona
 
-`/nan-usage` lee el token de sesión desde `~/.config/nan/session.json` — el mismo archivo que usa la [CLI de NaN](https://github.com/helmcode/nan-cli). Si el archivo existe y contiene una sesión válida, el comando obtiene datos de uso reales del dashboard de NaN. Si no, muestra los límites de cuota estáticos de la documentación.
+`/nan-usage` llama al endpoint [`GET /v1/usage`](https://nan.builders/docs/api#tag/usage) de NaN con **la misma API key que ya usas para chat** — la credencial guardada en pi (`/login nan`) o `NAN_API_KEY`. Sin login de la CLI, sin cookie de sesión, sin configuración extra.
+
+El endpoint devuelve tu uso (filas por fecha y modelo) y los totales de la ventana solicitada — máximo 90 días inclusivos. El comando lee esos totales y los combina con los límites publicados en la [documentación de NaN](https://nan.builders/docs/models) para mostrarte qué porcentaje de cada cuota mensual has consumido. `/usage` solo reporta consumo, así que los límites siempre vienen de la tabla documentada (comprobado 2026-09-27).
+
+Límite de tasa: 30 peticiones por minuto para `/usage`, separado del de los endpoints de modelos.
+
+### Uso
+
+```
+/nan-usage        # mes en curso en UTC (coincide con las cuotas mensuales)
+/nan-usage 7      # ventana móvil de 7 días (1-90)
+/nan-usage 30     # ventana móvil de 30 días
+/nan-usage help   # muestra la línea de uso
+```
 
 ### Configuración
 
-1. **Instala la CLI de NaN**:
-   ```bash
-   curl -fsSL https://nan.builders/install | sh
+1. **Autentica el proveedor `nan` en pi** con tu clave `sk-...`:
+   ```
+   /login nan
    ```
-2. **Inicia sesión**:
+   o expórtala en su lugar:
    ```bash
-   nan auth login
+   export NAN_API_KEY=sk-...
    ```
-   Te envía un enlace de inicio de sesión por email. Pega el enlace en la terminal.
-3. **Usa en pi**:
+2. **Úsalo en pi**:
    ```
    /nan-usage
    ```
 
 > [!TIP]
-> El token de sesión se comparte automáticamente — no necesitas variables de entorno ni configuración extra. Si la sesión expira, ejecuta `nan auth login` de nuevo.
+> ¿No se resuelve ninguna API key? El comando muestra la tabla estática de cuotas de la documentación y te indica cómo autenticarte.
 
 ### Lo que ves
 
-**Con sesión válida** (uso real):
+**Con API key** (uso real):
 ```
-📊 NaN Quota Status
+📊 NaN Usage
+
+🗓️  Window: 2026-09-01 → 2026-09-27 UTC (27 days)
 
-⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+⏱️  Next billing reset: 2026-09-30 UTC (2d 14h 30m 0s)
 
 Models with monthly caps:
 
 DeepSeek V4 Flash:
-  [████████░░░░░░░░░░░░] 40.2%
-  Used: 1.2B / 3.0B (1.8B remaining)
+  [████████░░░░░░░░░░░░] 40.0% of monthly cap
+  Used: 1.2B / 3.0B (1.8B remaining) · 5,120 requests
 
 MiMo V2.5:
-  [██░░░░░░░░░░░░░░░░░░] 12.5%
-  Used: 125.0M / 1.0B (875.0M remaining)
+  [███░░░░░░░░░░░░░░░░░] 12.5% of monthly cap
+  Used: 125.0M / 1.0B (875.0M remaining) · 840 requests
+
+GLM 5.3 👑:
+  [████████░░░░░░░░░░░░] 40.0% of monthly cap
+  Used: 1.2B / 3.0B (1.8B remaining) · 2,400 requests
+  ↳ rolling window: 400.0M / 4h (daily granularity — /usage cannot break it down)
 
 Uncapped models:
 
-Qwen 3.6: 890.5K used
-Gemma 4: 234.1K used
+Qwen 3.6: 890.5K used · 123 requests
+
+Window totals: 2.6B tokens (2.0B prompt / 640.0M completion) · 18,432 requests
+All time: 13.2B tokens · 41,250 requests (cached 2026-02-01)
+💡 Source: GET /v1/usage · caps from https://nan.builders/docs/models
 ```
 
-**Sin sesión** (solo límites estáticos):
+**Sin API key** (solo límites estáticos):
 ```
 📊 NaN Quota Status (static limits)
 
-⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+⏱️  Next billing reset: 2026-09-30 UTC (2d 14h 30m 0s)
 
 Model                        Monthly Cap
 ─────────────────────────────────────────────────
 DeepSeek V4 Flash            3.0B
 MiMo V2.5                    1.0B
+MiMo V2.6 Flash              1.0B
 Qwen 3.6                     uncapped
 Gemma 4                      uncapped
 Qwen 3.8 Flash               500.0M
 GLM 5.3 Flash                2.0B
-GLM 5.3 👑                   3.0B (rolling 400.0M/4h)
+GLM 5.3                      3.0B 👑 (rolling 400.0M/4h)
 
-💡 Run `nan auth login` to see real usage data.
+💡 Set NAN_API_KEY or run `/login nan` to see real usage (GET /v1/usage).
 ```
 
+Los errores siguen siendo accionables: `401` → ejecuta `/login nan` o corrige `NAN_API_KEY`, `404` → la cuenta no tiene identidad de uso que reportar, `429` → reintenta tras los segundos de `Retry-After`.
+
 ---
 
 ## 📊 Modelos

package/README.md

@@ -1,7 +1,7 @@
 # @gtrabanco/pi-nan-provider
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.6.5-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Version](https://img.shields.io/badge/version-0.8.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
 
 [NaN Builders](https://nan.builders) model provider + MCP bridges for [pi](https://github.com/earendil-works/pi). 
 
@@ -156,74 +156,99 @@ bun run check-nan-mcp-server --issue    # create/refresh the issue
 
 ## 📊 Quota Usage: `/nan-usage`
 
-Shows your NaN token usage per model, monthly limits, and time until the billing cycle resets.
+Shows your NaN token usage per model merged with the documented monthly caps, the window totals, your all-time totals, and the time until the billing cycle resets.
 
 ### How it works
 
-`/nan-usage` reads the session token from `~/.config/nan/session.json` — the same file the [NaN CLI](https://github.com/helmcode/nan-cli) uses. If the file exists and contains a valid session, the command fetches real usage data from NaN's dashboard. Otherwise, it shows static quota limits from the docs.
+`/nan-usage` calls NaN's [`GET /v1/usage`](https://nan.builders/docs/api#tag/usage) endpoint with the **same API key you already use for chat** — pi's stored credential (`/login nan`) or `NAN_API_KEY`. No CLI login, no session cookie, no extra setup.
+
+The endpoint returns your usage (rows per date and model) plus totals covering the requested window — at most 90 inclusive days. The command reads those totals and merges them with the caps published in the [NaN docs](https://nan.builders/docs/models) to show how much of each monthly cap you have consumed. `/usage` reports consumption only, so the caps themselves always come from the documented table (checked 2026-09-27).
+
+Rate limit: 30 requests per minute for `/usage`, separate from the model endpoints.
+
+### Usage
+
+```
+/nan-usage        # current UTC month (matches the monthly caps)
+/nan-usage 7      # rolling 7-day window (1-90)
+/nan-usage 30     # rolling 30-day window
+/nan-usage help   # show the usage line
+```
 
 ### Setup
 
-1. **Install the NaN CLI**:
-   ```bash
-   curl -fsSL https://nan.builders/install | sh
+1. **Authenticate the `nan` provider in pi** with your `sk-...` key:
+   ```
+   /login nan
    ```
-2. **Log in**:
+   or export it instead:
    ```bash
-   nan auth login
+   export NAN_API_KEY=sk-...
    ```
-   This sends a sign-in link to your email. Paste the link back into the terminal.
-3. **Use in pi**:
+2. **Use in pi**:
    ```
    /nan-usage
    ```
 
 > [!TIP]
-> The session token is shared automatically — no env vars or extra config needed. If the session expires, run `nan auth login` again.
+> No API key resolves? The command falls back to the static quota table from the docs and tells you how to authenticate.
 
 ### What you see
 
-**With a valid session** (real usage):
+**With an API key** (real usage):
 ```
-📊 NaN Quota Status
+📊 NaN Usage
+
+🗓️  Window: 2026-09-01 → 2026-09-27 UTC (27 days)
 
-⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+⏱️  Next billing reset: 2026-09-30 UTC (2d 14h 30m 0s)
 
 Models with monthly caps:
 
 DeepSeek V4 Flash:
-  [████████░░░░░░░░░░░░] 40.2%
-  Used: 1.2B / 3.0B (1.8B remaining)
+  [████████░░░░░░░░░░░░] 40.0% of monthly cap
+  Used: 1.2B / 3.0B (1.8B remaining) · 5,120 requests
 
 MiMo V2.5:
-  [██░░░░░░░░░░░░░░░░░░] 12.5%
-  Used: 125.0M / 1.0B (875.0M remaining)
+  [███░░░░░░░░░░░░░░░░░] 12.5% of monthly cap
+  Used: 125.0M / 1.0B (875.0M remaining) · 840 requests
+
+GLM 5.3 👑:
+  [████████░░░░░░░░░░░░] 40.0% of monthly cap
+  Used: 1.2B / 3.0B (1.8B remaining) · 2,400 requests
+  ↳ rolling window: 400.0M / 4h (daily granularity — /usage cannot break it down)
 
 Uncapped models:
 
-Qwen 3.6: 890.5K used
-Gemma 4: 234.1K used
+Qwen 3.6: 890.5K used · 123 requests
+
+Window totals: 2.6B tokens (2.0B prompt / 640.0M completion) · 18,432 requests
+All time: 13.2B tokens · 41,250 requests (cached 2026-02-01)
+💡 Source: GET /v1/usage · caps from https://nan.builders/docs/models
 ```
 
-**Without a session** (static limits only):
+**Without an API key** (static limits only):
 ```
 📊 NaN Quota Status (static limits)
 
-⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+⏱️  Next billing reset: 2026-09-30 UTC (2d 14h 30m 0s)
 
 Model                        Monthly Cap
 ─────────────────────────────────────────────────
 DeepSeek V4 Flash            3.0B
 MiMo V2.5                    1.0B
+MiMo V2.6 Flash              1.0B
 Qwen 3.6                     uncapped
 Gemma 4                      uncapped
 Qwen 3.8 Flash               500.0M
 GLM 5.3 Flash                2.0B
-GLM 5.3 👑                   3.0B (rolling 400.0M/4h)
+GLM 5.3                      3.0B 👑 (rolling 400.0M/4h)
 
-💡 Run `nan auth login` to see real usage data.
+💡 Set NAN_API_KEY or run `/login nan` to see real usage (GET /v1/usage).
 ```
 
+Failures stay actionable: `401` → run `/login nan` or fix `NAN_API_KEY`, `404` → the account has no usage identity to report, `429` → retry after the `Retry-After` seconds.
+
 ---
 
 ## 📊 Models

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and MCP bridges (official web search + optional community media server)",
 	"keywords": [
 		"pi",

package/scripts/check-pi-sdk-versions.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/**
+ * Monitor PI SDK versions and NaN-related dependencies for pi-nan-provider.
+ *
+ * This script:
+ * 1. Reads current versions from package.json (devDependencies and peerDependencies).
+ * 2. Queries npm for latest versions.
+ * 3. Flags version bumps and checks compatibility.
+ *
+ * Exit 0 = nothing to do.
+ * Exit 1 = updates available.
+ *
+ * Usage:
+ *   node scripts/check-pi-sdk-versions.mjs --report
+ *   node scripts/check-pi-sdk-versions.mjs --fail
+ *   node scripts/check-pi-sdk-versions.mjs  (JSON output for CI)
+ */
+
+import https from "node:https";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const ROOT = fileURLToPath(new URL("../", import.meta.url));
+
+/**
+ * Packages that ship from the `@earendil-works` scope and carry Pi SDK code.
+ * pi-nan-provider depends on these for AI model operations.
+ */
+const SDK_PACKAGES = [
+  "@earendil-works/pi-ai",
+  "@earendil-works/pi-coding-agent",
+];
+
+// ---------------------------------------------------------------------------
+// Package.json reader
+// ---------------------------------------------------------------------------
+
+function readPackageJson() {
+  const raw = readFileSync(new URL("../package.json", import.meta.url), "utf-8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Get the currently constrained version for a package from
+ * devDependencies and peerDependencies.
+ */
+function getConstrainedVersion(pkg, packageName) {
+  const sources = ["devDependencies", "peerDependencies"];
+  for (const src of sources) {
+    const ver = pkg[src]?.[packageName];
+    if (ver) return { version: ver, source: src };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// npm registry client (no dependencies)
+// ---------------------------------------------------------------------------
+
+function npmGet(packageName) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      `https://registry.npmjs.org/${encodeURIComponent(packageName)}`,
+      { headers: { accept: "application/json" } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`npm registry returned ${res.statusCode} for ${packageName}`));
+          return;
+        }
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => resolve(JSON.parse(data)));
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(15_000, () => {
+      req.destroy();
+      reject(new Error(`Timeout fetching ${packageName} from npm`));
+    });
+  });
+}
+
+function npmLatest(packageName) {
+  return npmGet(packageName).then((data) => {
+    const distTags = data["dist-tags"] ?? {};
+    const latestVersion = distTags["latest"];
+    if (!latestVersion) {
+      throw new Error(`No "latest" dist-tag for ${packageName}`);
+    }
+    const versions = Object.keys(data.versions ?? {}).sort((a, b) => {
+      const pa = a.split(".").map(Number);
+      const pb = b.split(".").map(Number);
+      for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va < vb) return -1;
+        if (va > vb) return 1;
+      }
+      return 0;
+    });
+    return { latestVersion, latestTag: "latest", allVersions: versions, data };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Semver helpers
+// ---------------------------------------------------------------------------
+
+function parseSemver(version) {
+  // Handle versions like "1" (major only) or "1.2" (major.minor)
+  let normalized = version;
+  while (normalized.split(".").length < 3) {
+    normalized += ".0";
+  }
+  const m = normalized.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), raw: version };
+}
+
+function bumpLevel(current, target) {
+  const c = parseSemver(current);
+  const t = parseSemver(target);
+  if (!c || !t) return "unknown";
+  if (t.major > c.major) return "major";
+  if (t.minor > c.minor) return "minor";
+  if (t.patch > c.patch) return "patch";
+  return "none";
+}
+
+/**
+ * Check if a version satisfies a semver range.
+ * Handles caret, tilde, comparison operators, and ranges.
+ */
+function checkSemverSatisfies(version, range) {
+  const cVer = parseSemver(version);
+  if (!cVer) return false;
+
+  // Handle disjunction (OR): ">=1.0.0 <2.0.0 || >=3.0.0"
+  if (range.includes("||")) {
+    const parts = range.split("||").map((p) => p.trim());
+    return parts.some((part) => checkSemverSatisfies(version, part));
+  }
+
+  // Handle conjunction (AND via spaces): ">=1.0.0 <2.0.0"
+  const parts = [];
+  let current = "";
+  const tokens = range.split(/\s+/);
+  for (const token of tokens) {
+    if (token.startsWith(">=") || token.startsWith("<=") ||
+        token.startsWith(">") || token.startsWith("<") || token.startsWith("=") ||
+        token.startsWith("^") || token.startsWith("~")) {
+      if (current && !current.startsWith("^") && !current.startsWith("~")) {
+        parts.push(current);
+      }
+      current = token;
+    } else if (current) {
+      current = current + " " + token;
+    } else {
+      current = token;
+    }
+  }
+  if (current) parts.push(current);
+
+  if (parts.length > 1) {
+    // Check each part
+    return parts.every((part) => checkSemverSatisfies(version, part));
+  }
+
+  // Single constraint
+  const constraint = range.trim();
+
+  // Handle caret: ^X.Y.Z
+  if (constraint.startsWith("^")) {
+    const target = parseSemver(constraint.slice(1));
+    if (!target) return false;
+    // ^0.x: same major and minor >= target.minor
+    // ^1.x+: same major and minor >= target.minor
+    return cVer.major === target.major && cVer.minor >= target.minor;
+  }
+
+  // Handle tilde: ~X.Y.Z
+  if (constraint.startsWith("~")) {
+    const target = parseSemver(constraint.slice(1));
+    if (!target) return false;
+    return cVer.major === target.major && cVer.minor === target.minor && cVer.patch >= target.patch;
+  }
+
+  // Handle comparison: >=X.Y.Z, <X.Y.Z, =X.Y.Z, etc.
+  let op = "";
+  let verStr = constraint;
+  if (constraint.startsWith(">=")) {
+    op = ">=";
+    verStr = constraint.slice(2);
+  } else if (constraint.startsWith("<=")) {
+    op = "<=";
+    verStr = constraint.slice(2);
+  } else if (constraint.startsWith(">")) {
+    op = ">";
+    verStr = constraint.slice(1);
+  } else if (constraint.startsWith("<")) {
+    op = "<";
+    verStr = constraint.slice(1);
+  } else if (constraint.startsWith("=")) {
+    op = "=";
+    verStr = constraint.slice(1);
+  }
+
+  const target = parseSemver(verStr);
+  if (!target) return false;
+
+  const cmp = semverCompare(cVer, target);
+
+  switch (op) {
+    case ">=": return cmp >= 0;
+    case "<=": return cmp <= 0;
+    case ">": return cmp > 0;
+    case "<": return cmp < 0;
+    case "=": return cmp === 0;
+    default: return false;
+  }
+}
+
+function semverCompare(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return (a.patch ?? 0) - (b.patch ?? 0);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = process.argv.slice(2);
+  const flags = {
+    report: args.includes("--report"),
+    fail: args.includes("--fail"),
+  };
+
+  const pkg = readPackageJson();
+
+  const results = [];
+  let exitCode = 0;
+
+  for (const packageName of SDK_PACKAGES) {
+    try {
+      const npmInfo = await npmLatest(packageName);
+      const constrained = getConstrainedVersion(pkg, packageName);
+
+      if (!constrained) {
+        results.push({
+          packageName,
+          status: "not-found",
+          message: "Not found in package.json dependencies",
+        });
+        continue;
+      }
+
+      // Extract numeric version from constraint
+      let constraintVer = constrained.version;
+      // Remove version range operators to get the base version
+      if (constraintVer.startsWith("^")) {
+        constraintVer = constraintVer.slice(1);
+      } else if (constraintVer.startsWith("~")) {
+        constraintVer = constraintVer.slice(1);
+      }
+
+      const bump = bumpLevel(constraintVer, npmInfo.latestVersion);
+
+      // Check if latest satisfies peer dependencies
+      const peerRange = pkg.peerDependencies?.[packageName] ?? null;
+      const latestSatisfiesPeer = peerRange
+        ? checkSemverSatisfies(npmInfo.latestVersion, peerRange)
+        : true;
+
+      // Check if current satisfies peer dependencies
+      const currentSatisfiesPeer = peerRange
+        ? checkSemverSatisfies(constraintVer, peerRange)
+        : true;
+
+      const result = {
+        packageName,
+        source: constrained.source,
+        constrainedVersion: constrained.version,
+        constraintVer,
+        latestVersion: npmInfo.latestVersion,
+        latestTag: npmInfo.latestTag,
+        bump,
+        peerRange,
+        latestSatisfiesPeer,
+        currentSatisfiesPeer,
+        totalVersions: npmInfo.allVersions.length,
+        allVersions: npmInfo.allVersions,
+      };
+
+      // Determine status
+      if (!currentSatisfiesPeer) {
+        result.status = "WARNING";
+        result.message = `Current version ${constraintVer} does NOT satisfy peer dependency range ${peerRange}`;
+        exitCode = 1;
+      } else if (bump === "major" && npmInfo.latestVersion !== constraintVer) {
+        result.status = "BREAKING";
+        result.message = `Major version bump: ${constraintVer} → ${npmInfo.latestVersion}. Review changelog before upgrading.`;
+        if (latestSatisfiesPeer) {
+          result.message += ` Latest version satisfies peer dependency range.`;
+        } else {
+          result.message += ` ⚠️ Latest version does NOT satisfy peer dependency range!`;
+        }
+        exitCode = 1;
+      } else if (bump === "minor" && npmInfo.latestVersion !== constraintVer) {
+        result.status = "minor";
+        result.message = `Minor version bump: ${constraintVer} → ${npmInfo.latestVersion}. Check for API changes.`;
+        exitCode = 1;
+      } else if (bump === "patch" && npmInfo.latestVersion !== constraintVer) {
+        result.status = "patch";
+        result.message = `Patch version bump: ${constraintVer} → ${npmInfo.latestVersion}. May be safe to update.`;
+      } else {
+        result.status = "up-to-date";
+        result.message = `Already on latest version.`;
+      }
+
+      if (latestSatisfiesPeer && bump !== "none") {
+        result.message += ` Latest satisfies peer dependency range.`;
+      } else if (!latestSatisfiesPeer) {
+        result.message += ` Latest does NOT satisfy peer dependency range!`;
+      }
+
+      results.push(result);
+    } catch (err) {
+      results.push({
+        packageName,
+        status: "error",
+        message: err.message,
+      });
+      exitCode = 1;
+    }
+  }
+
+  // Print report
+  if (flags.report) {
+    console.log("\n=== PI SDK Version Monitor (pi-nan-provider) ===\n");
+
+    for (const r of results) {
+      if (r.status === "not-found") {
+        console.log(`  ❌ ${r.packageName}: ${r.message}`);
+        continue;
+      }
+      if (r.status === "error") {
+        console.log(`  ⚠️  ${r.packageName}: ${r.message}`);
+        continue;
+      }
+      if (r.status === "up-to-date") {
+        console.log(`  ✅ ${r.packageName}: ${r.message} (${r.latestVersion})`);
+        continue;
+      }
+      if (r.status === "WARNING") {
+        console.log(`  ❗ ${r.packageName}: ${r.message} (current: ${r.constrainedVersion})`);
+        continue;
+      }
+      const icon = r.status === "BREAKING" ? "🔴" : r.status === "minor" ? "🟡" : "🟢";
+      console.log(`  ${icon} ${r.packageName}: ${r.message} (${r.source}: ${r.constrainedVersion})`);
+      console.log(`     → Latest available: ${r.latestVersion} (tag: ${r.latestTag})`);
+      if (r.peerRange) {
+        console.log(`     → Peer dependency range: ${r.peerRange}`);
+        console.log(`     → Latest satisfies peer range: ${r.latestSatisfiesPeer ? "✅" : "❌"}`);
+      }
+      if (r.bump === "major") {
+        console.log(`     → Total versions published: ${r.totalVersions}`);
+      }
+    }
+
+    console.log();
+  } else {
+    // JSON output for CI consumption
+    console.log(JSON.stringify(results, null, 2));
+  }
+
+  if (flags.fail && exitCode === 1) {
+    process.exit(1);
+  }
+
+  process.exit(exitCode);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err.message);
+  process.exit(2);
+});

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-25T22:43:00.930Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-27T21:25:24.946Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -436,7 +436,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-25T22:43:00.930Z",
+	fetchedAt: "2026-09-27T21:25:24.946Z",
 	modelCount: 7,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.5","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [

package/src/usage.ts

@@ -1,21 +1,28 @@
 /**
- * `/nan-usage` — slash command showing NaN quota status per model.
+ * `/nan-usage` — slash command: NaN token usage merged with the documented
+ * quota limits.
  *
- * NaN's quota endpoint (`cloud-api.nan.builders/api/usage/quota`) requires
- * a session token (not API key auth). The token is obtained via the NaN CLI
- * login flow (email → link → `nan_session` cookie), stored in
- * `~/.config/nan/session.json`.
+ * Data source: NaN's `GET /v1/usage` (OpenAPI tag "Usage",
+ * https://nan.builders/docs/api#tag/usage), authenticated with the same
+ * personal API key used for chat (`Authorization: Bearer`) — pi's stored
+ * credential (`/login nan`) or `NAN_API_KEY`.
  *
- * This command auto-detects the nan-cli session file. No env vars needed —
- * just run `nan auth login` once and `/nan-usage` works.
+ * This replaced the previous dashboard flow, which needed a NaN CLI session
+ * cookie (`nan auth login` → `~/.config/nan/session.json`). `/usage` is
+ * member-scoped and API-key authed, so no CLI login is involved anymore
+ * (NaN docs, checked 2026-09-27).
  *
- * Quota sources: https://nan.builders/docs/models (checked 2026-09-21)
+ * The endpoint reports consumption, never caps: quotas below come from
+ * https://nan.builders/docs/models (checked 2026-09-21) and are merged with
+ * the returned per-model totals. `/usage` returns daily rows (paginated) plus
+ * `totals` covering the whole requested window — max 90 inclusive days, wider
+ * windows are rejected with 400 — so the command reads `totals.by_model` and
+ * asks for a single-row page. Rate limit: 30 requests/min, separate from the
+ * model endpoints.
  */
 
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { NAN_API_KEY_ENV, resolveNanApiKey } from "./mcp/nan-search.ts";
 
 // ── Known quota limits per model (from NaN docs) ──────────────────────────
 
@@ -45,58 +52,88 @@ export const MODEL_QUOTAS: readonly ModelQuota[] = [
 	{ model: "glm5.3", label: "GLM 5.3", monthlyCap: 3_000_000_000, rollingWindowCap: 400_000_000, rollingWindowHours: 4, premium: true },
 ];
 
-// ── Dashboard API types ───────────────────────────────────────────────────
+// ── GET /v1/usage types ───────────────────────────────────────────────────
 
-interface DashboardModelQuota {
+export interface UsageModelTotals {
 	model: string;
-	tokensUsed: number;
-	cap: number;
-	percentage: number;
-	resetAt: string | null;
-	windowHours: number | null;
+	prompt_tokens: number;
+	completion_tokens: number;
+	total_tokens: number;
+	api_requests: number;
 }
 
-interface DashboardUncappedModelQuota {
-	model: string;
-	tokensUsed: number;
-	resetAt: string | null;
-	windowHours: number | null;
+export interface UsageTotals {
+	prompt_tokens: number;
+	completion_tokens: number;
+	total_tokens: number;
+	api_requests: number;
+	by_model: UsageModelTotals[];
 }
 
-interface DashboardQuotaResponse {
-	periodStart: string;
-	models: Array<{
-		model: string;
-		tokensUsed: number;
-		cap: number;
-		windowHours?: number;
-		periodEnd?: string;
-	}>;
+export interface UsageAllTime {
+	prompt_tokens: number;
+	completion_tokens: number;
+	total_tokens: number;
+	api_requests: number;
+	cached_at: string | null;
 }
 
-// ── nan-cli session reader ────────────────────────────────────────────────
-
-interface NanCliSession {
-	token: string;
+export interface UsageReport {
+	object: "usage.report";
+	/** First day of the window actually served (after clamping). */
+	start_date: string;
+	/** Last day of the window actually served (after clamping). */
+	end_date: string;
+	/** Daily (date, model) rows — paginated; unused here (totals cover the window). */
+	data: unknown[];
+	totals: UsageTotals;
+	all_time: UsageAllTime;
+	has_more: boolean;
+	next_cursor: string | null;
 }
 
-/** Read the nan_session token from ~/.config/nan/session.json (shared with nan-cli). */
-function readNanCliSessionToken(): string | undefined {
-	try {
-		const sessionPath = join(homedir(), ".config", "nan", "session.json");
-		const data = readFileSync(sessionPath, "utf8");
-		const session = JSON.parse(data) as NanCliSession;
-		if (typeof session === "object" && session !== null && typeof session.token === "string" && session.token.length > 0) {
-			return session.token;
-		}
-	} catch {
-		// File doesn't exist or is invalid.
-	}
-	return undefined;
+export interface UsageFetchError {
+	/** HTTP status when the endpoint answered with an error. */
+	status?: number;
+	/** `Retry-After` seconds, present on 429. */
+	retryAfterSeconds?: number;
+	/** Endpoint or transport detail (error message / provider message). */
+	detail?: string;
 }
 
+export type FetchUsageResult =
+	| { ok: true; report: UsageReport }
+	| { ok: false; error: UsageFetchError };
+
+/** NaN's usage endpoint (OpenAPI tag "Usage"), API-key authed. */
+export const NAN_USAGE_URL = "https://api.nan.builders/v1/usage";
+export const USAGE_TIMEOUT_MS = 10_000;
+/** The endpoint rejects windows wider than 90 inclusive days with 400. */
+export const MAX_USAGE_WINDOW_DAYS = 90;
+
+const USAGE_LINE =
+	"Usage: /nan-usage [days] — days 1-90 (default: the current UTC month, matching the monthly caps). /nan-usage help";
+
 // ── Time helpers ──────────────────────────────────────────────────────────
 
+export interface UsageWindow {
+	/** Inclusive start, `YYYY-MM-DD` UTC. */
+	start: string;
+	/** Inclusive end, `YYYY-MM-DD` UTC. */
+	end: string;
+	/** Inclusive day count. */
+	days: number;
+}
+
+function isoDate(date: Date): string {
+	return date.toISOString().slice(0, 10);
+}
+
+function daysBetween(start: string, end: string): number {
+	const ms = Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`);
+	return Math.round(ms / 86_400_000) + 1;
+}
+
 function formatDuration(ms: number): string {
 	if (ms <= 0) return "already reset";
 	const totalSeconds = Math.floor(ms / 1000);
@@ -113,97 +150,96 @@ function formatDuration(ms: number): string {
 	return parts.join(" ");
 }
 
-function getNextBillingReset(): Date {
-	const now = new Date();
+function getNextBillingReset(now = new Date()): Date {
 	const year = now.getUTCFullYear();
 	const month = now.getUTCMonth();
 	return new Date(Date.UTC(year, month + 1, 0, 0, 0, 0));
 }
 
-function formatTokens(n: number): string {
+function resetLine(now = new Date()): string {
+	const resetDate = getNextBillingReset(now);
+	const timeUntilReset = resetDate.getTime() - now.getTime();
+	return `⏱️  Next billing reset: ${isoDate(resetDate)} UTC (${formatDuration(timeUntilReset)})`;
+}
+
+/** Default window: the current UTC month, so usage lines up with the monthly caps. */
+export function currentMonthWindow(now = new Date()): UsageWindow {
+	const start = isoDate(new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)));
+	const end = isoDate(now);
+	return { start, end, days: daysBetween(start, end) };
+}
+
+/** Rolling window of `days` inclusive days ending today (UTC), clamped to 1–90. */
+export function rollingWindow(days: number, now = new Date()): UsageWindow {
+	const span = Math.min(Math.max(Math.trunc(days), 1), MAX_USAGE_WINDOW_DAYS);
+	const start = isoDate(new Date(now.getTime() - (span - 1) * 86_400_000));
+	const end = isoDate(now);
+	return { start, end, days: daysBetween(start, end) };
+}
+
+export type UsageArgs =
+	| { kind: "window"; window: UsageWindow }
+	| { kind: "help" }
+	| { kind: "invalid"; message: string };
+
+/** Parse the optional `/nan-usage [days]` argument. */
+export function parseUsageArgs(tokens: readonly string[], now = new Date()): UsageArgs {
+	if (tokens.length === 0) return { kind: "window", window: currentMonthWindow(now) };
+	if (tokens.length === 1) {
+		const token = tokens[0]!;
+		if (["help", "-h", "--help"].includes(token.toLowerCase())) return { kind: "help" };
+		if (/^\d+$/.test(token)) {
+			const days = Number(token);
+			if (days >= 1 && days <= MAX_USAGE_WINDOW_DAYS) return { kind: "window", window: rollingWindow(days, now) };
+		}
+	}
+	return {
+		kind: "invalid",
+		message: `Unknown argument "${tokens.join(" ")}". ${USAGE_LINE}`,
+	};
+}
+
+// ── Formatting helpers ────────────────────────────────────────────────────
+
+export function formatTokens(n: number): string {
 	if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
 	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
 	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
 	return String(n);
 }
 
+/** Locale-independent thousands separator (request counts). */
+export function formatCount(n: number): string {
+	return String(Math.trunc(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
 function progressBar(percentage: number, width = 20): string {
-	const filled = Math.round((percentage / 100) * width);
+	const clamped = Math.min(Math.max(percentage, 0), 100);
+	const filled = Math.round((clamped / 100) * width);
 	const empty = width - filled;
 	return `[${"█".repeat(filled)}${"░".repeat(empty)}]`;
 }
 
-// ── Dashboard client ──────────────────────────────────────────────────────
-
-const DASHBOARD_QUOTA_URL = "https://cloud-api.nan.builders/api/usage/quota";
-const FETCH_TIMEOUT_MS = 10_000;
-
-async function fetchDashboardQuota(token: string): Promise<DashboardQuotaResponse | null> {
-	try {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-		try {
-			const response = await fetch(DASHBOARD_QUOTA_URL, {
-				method: "GET",
-				headers: { cookie: `nan_session=${token}` },
-				redirect: "manual",
-				cache: "no-store",
-				signal: controller.signal,
-			});
-			if (!response.ok) return null;
-			return (await response.json()) as DashboardQuotaResponse;
-		} finally {
-			clearTimeout(timeout);
-		}
-	} catch {
-		return null;
-	}
-}
-
-function parseDashboardQuota(data: DashboardQuotaResponse): {
-	capped: DashboardModelQuota[];
-	uncapped: DashboardUncappedModelQuota[];
-} {
-	const capped: DashboardModelQuota[] = [];
-	const uncapped: DashboardUncappedModelQuota[] = [];
-	const seen = new Set<string>();
-
-	for (const entry of data.models) {
-		if (seen.has(entry.model)) continue;
-		seen.add(entry.model);
-
-		if (entry.cap === 0) {
-			uncapped.push({
-				model: entry.model,
-				tokensUsed: entry.tokensUsed,
-				resetAt: entry.periodEnd ?? null,
-				windowHours: entry.windowHours ?? null,
-			});
-		} else {
-			capped.push({
-				model: entry.model,
-				tokensUsed: entry.tokensUsed,
-				cap: entry.cap,
-				percentage: (entry.tokensUsed / entry.cap) * 100,
-				resetAt: entry.periodEnd ?? null,
-				windowHours: entry.windowHours ?? null,
-			});
-		}
-	}
-
-	return { capped, uncapped };
+/**
+ * `api_requests` comes back as 0 for some models that do have usage (live
+ * probe 2026-09-27: qwen3.8-flash 796M tokens / 0 requests, while the window
+ * total still sums the other models exactly). Reporting a bare "0 requests"
+ * next to real consumption would read as a bug in this command, so say what
+ * the endpoint actually reported.
+ */
+function requestsSuffix(tokens: number, requests: number): string {
+	if (tokens > 0 && requests === 0) return "requests not reported";
+	return `${formatCount(requests)} requests`;
 }
 
 // ── Message builders ──────────────────────────────────────────────────────
 
-function buildStaticMessage(): string {
-	const resetDate = getNextBillingReset();
-	const timeUntilReset = resetDate.getTime() - Date.now();
-
+/** Static quota table — shown when no API key resolves. */
+export function buildStaticMessage(now = new Date()): string {
 	const lines: string[] = [
 		"📊 NaN Quota Status (static limits)",
 		"",
-		`⏱️  Next billing reset: ${resetDate.toISOString().split("T")[0]} UTC (${formatDuration(timeUntilReset)})`,
+		resetLine(now),
 		"",
 		"Model                        Monthly Cap",
 		"─".repeat(45),
@@ -219,89 +255,225 @@ function buildStaticMessage(): string {
 		lines.push(`${quota.label.padEnd(28)} ${capStr}${premiumStr}${rollingStr}`);
 	}
 
-	lines.push("");
-	lines.push("💡 Run `nan auth login` to see real usage data.");
-
+	lines.push("", `💡 Set ${NAN_API_KEY_ENV} or run \`/login nan\` to see real usage (GET /v1/usage).`);
 	return lines.join("\n");
 }
 
-function buildDashboardMessage(
-	capped: DashboardModelQuota[],
-	uncapped: DashboardUncappedModelQuota[],
-): string {
-	const resetDate = getNextBillingReset();
-	const timeUntilReset = resetDate.getTime() - Date.now();
+/** Usage report merged with the documented caps. */
+export function buildUsageMessage(report: UsageReport, now = new Date()): string {
+	const start = report.start_date;
+	const end = report.end_date;
+	const days = daysBetween(start, end);
+	const totals = report.totals;
+	const byModel = totals?.by_model ?? [];
+	const totalTokens = totals?.total_tokens ?? 0;
+	const totalRequests = totals?.api_requests ?? 0;
 
 	const lines: string[] = [
-		"📊 NaN Quota Status",
+		"📊 NaN Usage",
+		"",
+		`🗓️  Window: ${start} → ${end} UTC (${days} day${days === 1 ? "" : "s"})`,
 		"",
-		`⏱️  Next billing reset: ${resetDate.toISOString().split("T")[0]} UTC (${formatDuration(timeUntilReset)})`,
+		resetLine(now),
 		"",
 	];
 
-	if (capped.length > 0) {
-		lines.push("Models with monthly caps:");
-		lines.push("");
-		for (const m of capped) {
-			const quota = MODEL_QUOTAS.find((q) => q.model === m.model);
-			const label = quota?.label ?? m.model;
-			const pct = m.percentage.toFixed(1);
-			const remaining = m.cap - m.tokensUsed;
-			lines.push(`${label}:`);
-			lines.push(`  ${progressBar(m.percentage)} ${pct}%`);
-			lines.push(`  Used: ${formatTokens(m.tokensUsed)} / ${formatTokens(m.cap)} (${formatTokens(remaining)} remaining)`);
-			if (m.windowHours) {
-				lines.push(`  Rolling window: ${m.windowHours}h`);
+	const usageOf = (model: string): UsageModelTotals | undefined => byModel.find((m) => m.model === model);
+
+	if (totalTokens === 0 && totalRequests === 0 && byModel.length === 0) {
+		lines.push("No usage in this window.");
+	} else {
+		const capped = MODEL_QUOTAS.filter((q) => q.monthlyCap > 0);
+		const uncapped = MODEL_QUOTAS.filter((q) => q.monthlyCap === 0);
+		const known = new Set(MODEL_QUOTAS.map((q) => q.model));
+		const others = byModel.filter((m) => !known.has(m.model)).sort((a, b) => b.total_tokens - a.total_tokens);
+
+		lines.push("Models with monthly caps:", "");
+		for (const quota of capped) {
+			const usage = usageOf(quota.model);
+			const used = usage?.total_tokens ?? 0;
+			const requests = usage?.api_requests ?? 0;
+			const percentage = (used / quota.monthlyCap) * 100;
+			const remaining = Math.max(quota.monthlyCap - used, 0);
+
+			lines.push(`${quota.label}${quota.premium ? " 👑" : ""}:`);
+			lines.push(`  ${progressBar(percentage)} ${percentage.toFixed(1)}% of monthly cap`);
+			lines.push(
+				`  Used: ${formatTokens(used)} / ${formatTokens(quota.monthlyCap)} (${formatTokens(remaining)} remaining) · ${requestsSuffix(used, requests)}`,
+			);
+			if (quota.rollingWindowCap > 0) {
+				lines.push(
+					`  ↳ rolling window: ${formatTokens(quota.rollingWindowCap)} / ${quota.rollingWindowHours}h ` +
+						"(daily granularity — /usage cannot break it down)",
+				);
 			}
 			lines.push("");
 		}
-	}
 
-	if (uncapped.length > 0) {
-		lines.push("Uncapped models:");
-		lines.push("");
-		for (const m of uncapped) {
-			const quota = MODEL_QUOTAS.find((q) => q.model === m.model);
-			const label = quota?.label ?? m.model;
-			lines.push(`${label}: ${formatTokens(m.tokensUsed)} used`);
+		const usedUncapped = uncapped.filter((q) => (usageOf(q.model)?.total_tokens ?? 0) > 0);
+		if (usedUncapped.length > 0) {
+			lines.push("Uncapped models:", "");
+			for (const quota of usedUncapped) {
+				const usage = usageOf(quota.model)!;
+				lines.push(`${quota.label}: ${formatTokens(usage.total_tokens)} used · ${requestsSuffix(usage.total_tokens, usage.api_requests)}`);
+			}
+			lines.push("");
 		}
-		lines.push("");
-	}
 
-	if (capped.length === 0 && uncapped.length === 0) {
-		lines.push("No usage data. Session may have expired.");
-		lines.push("Run `nan auth login` to refresh.");
+		if (others.length > 0) {
+			lines.push("Other models (no documented cap):", "");
+			for (const usage of others) {
+				lines.push(`${usage.model}: ${formatTokens(usage.total_tokens)} used · ${requestsSuffix(usage.total_tokens, usage.api_requests)}`);
+			}
+			lines.push("");
+		}
 	}
 
+	lines.push(
+		`Window totals: ${formatTokens(totalTokens)} tokens ` +
+			`(${formatTokens(totals?.prompt_tokens ?? 0)} prompt / ${formatTokens(totals?.completion_tokens ?? 0)} completion) · ` +
+			`${formatCount(totalRequests)} requests`,
+	);
+	const allTime = report.all_time;
+	if (allTime) {
+		const cached = allTime.cached_at ? ` (cached ${allTime.cached_at.slice(0, 10)})` : "";
+		lines.push(`All time: ${formatTokens(allTime.total_tokens)} tokens · ${formatCount(allTime.api_requests)} requests${cached}`);
+	}
+	lines.push("💡 Source: GET /v1/usage · caps from https://nan.builders/docs/models");
 	return lines.join("\n");
 }
 
+/** Map an endpoint/transport failure to an actionable message. */
+export function formatUsageError(error: UsageFetchError): string {
+	const { status, retryAfterSeconds, detail } = error;
+	const suffix = detail ? ` (${detail})` : "";
+	if (status === 401) return `NaN rejected the API key (401). Run /login nan or set ${NAN_API_KEY_ENV} to a valid key${suffix}.`;
+	if (status === 404) return `NaN has no usage identity for this account (404): nothing to report${suffix}.`;
+	if (status === 429) {
+		const wait = retryAfterSeconds === undefined ? "a few" : String(retryAfterSeconds);
+		return `Rate limited by /usage (429): retry in ${wait}s — 30 requests/min, separate from the model endpoints${suffix}.`;
+	}
+	if (status === 409) return `The API key alias is reserved for a service key (409); usage is not reported for it${suffix}.`;
+	if (status === 400) return `NaN rejected the /usage parameters (400)${suffix}.`;
+	if (status !== undefined && status >= 500) return `NaN /usage is failing (HTTP ${status})${suffix}. Try again shortly.`;
+	return `Could not fetch NaN usage${suffix}.`;
+}
+
+// ── Endpoint client ───────────────────────────────────────────────────────
+
+export interface FetchUsageOptions {
+	apiKey: string;
+	window: UsageWindow;
+	fetchImpl?: typeof fetch;
+	timeoutMs?: number;
+}
+
+/**
+ * `GET /v1/usage?start_date&end_date&limit=1` with Bearer auth.
+ * `limit=1` keeps the payload small: `totals` always spans the whole window,
+ * so the daily rows are never needed. Never throws — failures come back as
+ * `{ ok: false, error }`.
+ */
+export async function fetchUsageReport(options: FetchUsageOptions): Promise<FetchUsageResult> {
+	const { apiKey, window, fetchImpl = fetch, timeoutMs = USAGE_TIMEOUT_MS } = options;
+	const url = `${NAN_USAGE_URL}?start_date=${window.start}&end_date=${window.end}&limit=1`;
+
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetchImpl(url, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+			cache: "no-store",
+			signal: controller.signal,
+		});
+		if (!response.ok) {
+			const retryAfter = Number(response.headers.get("retry-after"));
+			let detail: string | undefined;
+			try {
+				const body = (await response.json()) as { error?: { message?: string } };
+				detail = body?.error?.message;
+			} catch {
+				// Non-JSON error body (proxy/CDN page) — status alone is enough.
+			}
+			return {
+				ok: false,
+				error: {
+					status: response.status,
+					...(Number.isFinite(retryAfter) && retryAfter > 0 ? { retryAfterSeconds: retryAfter } : {}),
+					...(detail ? { detail } : {}),
+				},
+			};
+		}
+		const report = (await response.json()) as UsageReport;
+		if (!report || typeof report !== "object" || !report.totals) {
+			return { ok: false, error: { detail: "unexpected payload from /v1/usage (no totals)" } };
+		}
+		return { ok: true, report };
+	} catch (error) {
+		return { ok: false, error: { detail: error instanceof Error ? error.message : String(error) } };
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
 // ── Command registration ──────────────────────────────────────────────────
 
-export function registerNanUsageCommand(pi: import("@earendil-works/pi-coding-agent").ExtensionAPI): void {
+export interface NanUsageCommandOptions {
+	/** Injected transport (tests); defaults to the global fetch. */
+	fetchImpl?: typeof fetch;
+	/** Injected API-key resolution (tests); defaults to pi's registry + env. */
+	resolveApiKey?: (ctx: ExtensionCommandContext) => Promise<string | undefined>;
+}
+
+export function registerNanUsageCommand(pi: ExtensionAPI, options: NanUsageCommandOptions = {}): void {
 	if (typeof pi.registerCommand !== "function") return;
 
+	const resolveApiKey = options.resolveApiKey ?? ((ctx: ExtensionCommandContext) => resolveNanApiKey(ctx));
+
 	pi.registerCommand("nan-usage", {
-		description: "Show NaN quota status: token limits, usage, and time until billing reset",
-		handler: async (_args: string, ctx: ExtensionCommandContext) => {
-			const token = readNanCliSessionToken();
-
-			if (token) {
-				ctx.ui.notify("Fetching usage from NaN dashboard...", "info");
-				const data = await fetchDashboardQuota(token);
-				if (data) {
-					const { capped, uncapped } = parseDashboardQuota(data);
-					ctx.ui.notify(buildDashboardMessage(capped, uncapped), "info");
-				} else {
-					ctx.ui.notify(
-						"Failed to fetch dashboard data. Session may have expired.\n" +
-						"Run `nan auth login` to refresh.",
-						"warning",
-					);
-				}
-			} else {
+		description: "Show NaN token usage vs monthly caps, window/all-time totals, and time until billing reset",
+		getArgumentCompletions: (argumentPrefix: string) => {
+			const prefix = argumentPrefix.trim().toLowerCase();
+			const items = [
+				{ value: "", label: "(current month)", description: "Usage for the current UTC month" },
+				{ value: "7", label: "7", description: "Rolling 7-day window" },
+				{ value: "30", label: "30", description: "Rolling 30-day window" },
+				{ value: "90", label: "90", description: "Rolling 90-day window (API maximum)" },
+				{ value: "help", label: "help", description: "Show the usage line" },
+			];
+			const filtered = items.filter((item) => item.value.startsWith(prefix));
+			return filtered.length > 0 ? filtered : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const parsed = parseUsageArgs(tokens);
+
+			if (parsed.kind === "help") {
+				ctx.ui.notify(USAGE_LINE, "info");
+				return;
+			}
+			if (parsed.kind === "invalid") {
+				ctx.ui.notify(parsed.message, "warning");
+				return;
+			}
+
+			const apiKey = await resolveApiKey(ctx);
+			if (!apiKey) {
 				ctx.ui.notify(buildStaticMessage(), "info");
+				return;
 			}
+
+			ctx.ui.notify("Fetching usage from GET /v1/usage ...", "info");
+			const result = await fetchUsageReport({
+				apiKey,
+				window: parsed.window,
+				...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+			});
+			ctx.ui.notify(
+				result.ok ? buildUsageMessage(result.report) : formatUsageError(result.error),
+				result.ok ? "info" : "warning",
+			);
 		},
 	});
 }