@scrylog/cli 0.2.0 → 0.3.0

package/src/tui/keybindings.ts

@@ -0,0 +1,49 @@
+import type { DashboardView } from "./model";
+
+export type BindingScope = "global" | DashboardView;
+
+export interface KeyBinding {
+  key: string;
+  description: string;
+  scope: BindingScope;
+  essential?: boolean;
+  footer?: boolean;
+}
+
+export const KEYBINDINGS: KeyBinding[] = [
+  { key: "Tab", description: "Switch tab", scope: "global", essential: true },
+  { key: "q", description: "Quit", scope: "global", essential: true },
+  { key: "r", description: "Refresh", scope: "global" },
+  { key: "s", description: "Open the sessions tab", scope: "global", essential: true, footer: false },
+  { key: "u", description: "Open the usage tab", scope: "global", essential: true, footer: false },
+  { key: "?", description: "Keybindings", scope: "global", essential: true },
+
+  { key: "j / Down", description: "Next session", scope: "sessions" },
+  { key: "k / Up", description: "Prev session", scope: "sessions" },
+  { key: "Enter", description: "Detail", scope: "sessions" },
+  { key: "t", description: "Attach", scope: "sessions" },
+  { key: "/", description: "Search", scope: "sessions" },
+  { key: "a", description: "Actionable filter", scope: "sessions" },
+  { key: "f", description: "Cycle filters", scope: "sessions" },
+  { key: "Esc", description: "Clear selection or close overlay", scope: "sessions" },
+
+  { key: "Click", description: "Select a session", scope: "sessions", footer: false },
+  { key: "2x Click", description: "Open session detail", scope: "sessions", footer: false },
+  { key: "Scroll", description: "Select next or previous session", scope: "sessions", footer: false },
+  { key: "Click tab", description: "Switch tabs", scope: "global", footer: false },
+];
+
+export function contextBindings(view: DashboardView): KeyBinding[] {
+  return KEYBINDINGS.filter((binding) => binding.scope === "global" || binding.scope === view);
+}
+
+export function essentialBindings(view: DashboardView): KeyBinding[] {
+  return contextBindings(view).filter((binding) => binding.essential);
+}
+
+export function bindingsForModal(): { scope: BindingScope; bindings: KeyBinding[] }[] {
+  const scopes: BindingScope[] = ["global", "sessions", "usage"];
+  return scopes
+    .map((scope) => ({ scope, bindings: KEYBINDINGS.filter((binding) => binding.scope === scope) }))
+    .filter((group) => group.bindings.length > 0);
+}

package/src/tui/model.ts

@@ -0,0 +1,295 @@
+import type { DetectionReason, ProcessInfo, SessionModel, SessionState, SessionTool } from "../shared/types";
+import type { SessionListItem } from "../shared/session-view";
+import { formatDuration, truncate } from "../shared/utils";
+import { BRAND } from "./theme";
+
+export type DashboardView = "sessions" | "usage";
+export type DashboardMode = "list" | "search" | "detail" | "message" | "bindings";
+export type SessionToolFilter = SessionTool | "all";
+export type SessionStateFilter = SessionState | "all";
+
+export interface DashboardFilters {
+  query: string;
+  actionableOnly: boolean;
+  tool: SessionToolFilter;
+  state: SessionStateFilter;
+}
+
+export type DashboardRow = ProjectHeaderRow | SessionRow | GapRow;
+
+export interface ProjectHeaderRow {
+  kind: "project-header";
+  projectKey: string;
+  projectName: string;
+}
+
+export interface SessionRow {
+  kind: "session";
+  projectKey: string;
+  session: SessionListItem;
+}
+
+export interface GapRow {
+  kind: "gap";
+  projectKey: string;
+}
+
+export interface SessionColumnWidths {
+  session: number;
+  state: number;
+  tool: number;
+  summary: number;
+}
+
+export const TOOL_FILTERS: SessionToolFilter[] = ["all", "opencode", "claude", "codex", "copilotcli", "shell", "unknown"];
+export const STATE_FILTERS: SessionStateFilter[] = ["all", "working", "waiting-input", "idle", "shell", "unknown"];
+export const WORKING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export const STATE_COLORS: Record<string, string> = {
+  working: BRAND.stateWorking,
+  idle: BRAND.stateIdle,
+  "waiting-input": BRAND.violet,
+  shell: BRAND.accentBlue,
+  error: BRAND.danger,
+  unknown: BRAND.grey,
+};
+
+export function applySessionFilters(
+  sessions: SessionListItem[],
+  filters: DashboardFilters,
+  standaloneMaxAgeHours: number,
+): SessionListItem[] {
+  const query = filters.query.toLowerCase();
+  const cutoff = standaloneMaxAgeHours > 0 ? Date.now() - standaloneMaxAgeHours * 3_600_000 : 0;
+  return sessions.filter((session) => {
+    if (session.parentSessionId) {
+      if (session.state !== "working" && session.state !== "waiting-input") return false;
+    } else if (cutoff > 0 && session.source === "standalone" && session.lastActivity < cutoff) {
+      return false;
+    }
+    if (filters.actionableOnly && !(session.hasAttention ?? session.state === "waiting-input")) return false;
+    if (filters.tool !== "all" && session.tool !== filters.tool) return false;
+    if (filters.state !== "all" && session.state !== filters.state) return false;
+    if (!query) return true;
+    const searchable = [
+      session.id,
+      session.tool,
+      session.state,
+      session.summary,
+      session.project?.displayName,
+      session.project?.compactLabel,
+      session.project?.branch,
+      session.displayName,
+      session.tmux?.session,
+      session.herdr?.workspace,
+      session.herdr?.name,
+      session.herdr?.tab,
+      session.herdr?.agent,
+      session.currentPath,
+    ].filter(Boolean).join(" ").toLowerCase();
+    return searchable.includes(query);
+  });
+}
+
+export function cycleFilters(filters: DashboardFilters): DashboardFilters {
+  const nextTool = TOOL_FILTERS[(TOOL_FILTERS.indexOf(filters.tool) + 1) % TOOL_FILTERS.length] ?? "all";
+  if (nextTool !== "all") return { ...filters, tool: nextTool, state: "all" };
+  const nextState = STATE_FILTERS[(STATE_FILTERS.indexOf(filters.state) + 1) % STATE_FILTERS.length] ?? "all";
+  return { ...filters, tool: "all", state: nextState };
+}
+
+function sessionSortWeight(session: SessionListItem): number {
+  // Active work first (working/waiting), then idle workloads.
+  const statePenalty = session.state === "working" ? 0 : session.state === "waiting-input" ? 20 : 60;
+  const toolPenalty = session.tool === "unknown" ? 30 : session.tool === "shell" ? 20 : 0;
+  return statePenalty + toolPenalty;
+}
+
+function groupSortWeight(group: { sessions: SessionListItem[] }): number {
+  const minWeight = Math.min(...group.sessions.map(sessionSortWeight));
+  return group.sessions.every((session) => !session.project) ? 1000 + minWeight : minWeight;
+}
+
+export function buildRows(sessions: SessionListItem[], narrow = false): DashboardRow[] {
+  const roots = sessions.filter((session) => !session.parentSessionId);
+  const childrenByParent = new Map<string, SessionListItem[]>();
+  for (const session of sessions) {
+    if (!session.parentSessionId) continue;
+    const children = childrenByParent.get(session.parentSessionId) ?? [];
+    children.push(session);
+    childrenByParent.set(session.parentSessionId, children);
+  }
+
+  const groups = new Map<string, { projectName: string; sessions: SessionListItem[] }>();
+  for (const session of roots) {
+    const key = getProjectGroupKey(session);
+    const group = groups.get(key);
+    if (group) {
+      group.sessions.push(session);
+    } else {
+      groups.set(key, {
+        projectName: session.project?.displayName ?? (session.source === "standalone"
+          ? (session.tool !== "unknown" ? session.tool : "standalone")
+          : session.source === "herdr"
+          ? session.herdr?.workspace ?? "herdr"
+          : session.tmux?.session ?? key),
+        sessions: [session],
+      });
+    }
+  }
+
+  const recency = (group: { sessions: SessionListItem[] }) => Math.max(...group.sessions.map((s) => s.lastActivity));
+  const sortedGroups = [...groups.entries()].sort(
+    ([, left], [, right]) => groupSortWeight(left) - groupSortWeight(right) || recency(right) - recency(left),
+  );
+  const rows: DashboardRow[] = sortedGroups.length > 0 ? [{ kind: "gap", projectKey: "__initial-gap__" }] : [];
+  sortedGroups.forEach(([projectKey, group], groupIndex) => {
+    if (groupIndex > 0) rows.push({ kind: "gap", projectKey });
+    group.sessions.sort((left, right) => sessionSortWeight(left) - sessionSortWeight(right) || right.lastActivity - left.lastActivity);
+    rows.push({ kind: "project-header", projectKey, projectName: group.projectName });
+    for (const session of group.sessions) {
+      rows.push({ kind: "session", projectKey, session });
+      if (!narrow) {
+        const children = (childrenByParent.get(session.id) ?? []).sort(
+          (left, right) => sessionSortWeight(left) - sessionSortWeight(right) || right.lastActivity - left.lastActivity,
+        );
+        for (const child of children) rows.push({ kind: "session", projectKey, session: child });
+      }
+    }
+  });
+  return rows;
+}
+
+function getProjectGroupKey(session: SessionListItem): string {
+  return session.project?.repositoryIdentityPath
+    ?? session.project?.gitRootPath
+    ?? session.project?.sourcePath
+    ?? session.project?.displayName
+    ?? (session.source === "standalone"
+      ? `standalone:${session.tool}`
+      : session.source === "herdr"
+      ? `herdr:${session.herdr?.workspaceId ?? session.herdr?.workspace ?? session.herdr?.paneId ?? session.id}`
+      : session.tmux?.session ?? session.id);
+}
+
+export function moveSelection(rows: DashboardRow[], selectedId: string | undefined, direction: 1 | -1): string | undefined {
+  if (rows.length === 0) return selectedId;
+  if (!selectedId) {
+    const candidates = direction > 0 ? rows : [...rows].reverse();
+    return candidates.find((row): row is SessionRow => row.kind === "session")?.session.id;
+  }
+  const current = rows.findIndex((row) => row.kind === "session" && row.session.id === selectedId);
+  if (current < 0) return undefined;
+  for (let index = current + direction; index >= 0 && index < rows.length; index += direction) {
+    const row = rows[index];
+    if (row?.kind === "session") return row.session.id;
+  }
+  return selectedId;
+}
+
+export function visibleRowWindow(rows: DashboardRow[], selectedId: string | undefined, limit: number): DashboardRow[] {
+  if (rows.length <= limit) return rows;
+  const selected = rows.findIndex((row) => row.kind === "session" && row.session.id === selectedId);
+  const start = Math.max(0, Math.min(selected - Math.floor(limit / 2), rows.length - limit));
+  return rows.slice(start, start + limit);
+}
+
+export function stateGlyph(state: string, spinnerFrame = 0): string {
+  if (state === "working") return WORKING_FRAMES[spinnerFrame % WORKING_FRAMES.length] ?? WORKING_FRAMES[0]!;
+  if (state === "idle") return "○";
+  if (state === "waiting-input") return "?";
+  if (state === "shell") return ">";
+  if (state === "error") return "✗";
+  return "?";
+}
+
+function formatBranchLabel(session: SessionListItem): string {
+  if (!session.project?.isGitRepository) return "";
+  return session.project.branch || "detached";
+}
+
+export function formatTargetLabel(session: SessionListItem, narrow = false): string {
+  let base: string;
+  if (session.parentSessionId) {
+    base = `    ↳ ${truncate(session.summary || session.id, narrow ? 22 : 26)}`;
+  } else if (session.tmux) {
+    const label = session.displayName?.trim()
+      || session.tmux.session?.trim()
+      || session.id;
+    base = `  ▸ ${label}`;
+  } else if (session.herdr) {
+    const label = session.displayName?.trim()
+      || session.herdr.tab?.trim()
+      || session.herdr.agent?.trim()
+      || session.herdr.paneId;
+    base = `  ▹ ${label}`;
+  } else {
+    const placeholder = session.activeTool
+      ? `[${session.activeTool}]`
+      : (session.id.includes(":") ? session.id.split(":")[1]!.slice(0, 8) : session.id.slice(0, 8));
+    base = `  ◇ ${placeholder}`;
+  }
+  const branch = formatBranchLabel(session);
+  return branch ? `${base}@${branch}` : base;
+}
+
+export type SessionToolMode = "text" | "monogram" | "icons";
+
+export function sessionColumnWidths(width: number, toolMode: SessionToolMode = "text", toolContentWidth = 0): SessionColumnWidths {
+  const narrow = width < 110;
+  const available = Math.max(36, width - 9);
+  if (narrow) {
+    const enhanced = toolMode !== "text";
+    const state = 11;
+    // On very narrow widths the summary column is a few truncated characters;
+    // drop it entirely and hand its space to the session column. The budget
+    // matches the pane's real content width (borders + padding + gutter) so
+    // rows fill from border to border.
+    if (width < 100) {
+      const filledAvailable = Math.max(36, width - 6);
+      const tool = Math.max(5, (toolContentWidth || (toolMode === "text" ? 10 : 7)) + 1);
+      return { session: Math.max(14, filledAvailable - state - tool), state, tool, summary: 0 };
+    }
+    const tool = toolMode === "text"
+      ? Math.min(12, Math.max(9, Math.floor(available * 0.18)))
+      : toolMode === "icons" ? 7 : 8;
+    const session = Math.min(enhanced ? 32 : 28, Math.max(14, Math.floor(available * (enhanced ? 0.4 : 0.34))));
+    return { session, state, tool, summary: Math.max(8, available - session - state - tool) };
+  }
+  const state = 11;
+  const tool = toolMode === "text" ? 13 : toolMode === "icons" ? 3 : 5;
+  if (toolMode !== "text") {
+    const remaining = available - state - tool;
+    const session = Math.min(72, Math.max(30, Math.floor(remaining * 0.55)));
+    return { session, state, tool, summary: Math.max(8, available - session - state - tool) };
+  }
+  const session = Math.min(40, Math.max(30, available - state - tool - 39));
+  return { session, state, tool, summary: Math.max(8, available - session - state - tool) };
+}
+
+export function formatStatusCell(session: SessionListItem, spinnerFrame: number): string {
+  const glyph = stateGlyph(session.state, spinnerFrame);
+  return `${glyph} (${formatDuration(session.stableForMs ?? 0)})`;
+}
+
+export function activeChildCounts(sessions: SessionListItem[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const session of sessions) {
+    if (!session.parentSessionId || (session.state !== "working" && session.state !== "waiting-input")) continue;
+    counts.set(session.parentSessionId, (counts.get(session.parentSessionId) ?? 0) + 1);
+  }
+  return counts;
+}
+
+export function sessionAttachCommand(session: SessionListItem, insideTmux: boolean): string[] | null {
+  if (session.source === "tmux" && session.tmux) {
+    return insideTmux
+      ? ["tmux", "switch-client", "-t", session.tmux.session]
+      : ["tmux", "attach-session", "-t", session.tmux.session];
+  }
+  if (session.source === "herdr" && session.herdr?.terminalId) {
+    return ["herdr", "terminal", "attach", session.herdr.terminalId];
+  }
+  return null;
+}
+

package/src/tui/state.ts

@@ -0,0 +1,77 @@
+import type { SessionModel } from "../shared/types";
+import type { SessionListItem, SessionViewCounts } from "../shared/session-view";
+import type { UsageState } from "../usage/types";
+import { cycleFilters, type DashboardFilters, type DashboardMode, type DashboardView } from "./model";
+
+export interface DashboardState {
+  view: DashboardView;
+  mode: DashboardMode;
+  sessions: SessionListItem[];
+  counts: SessionViewCounts | null;
+  usage: UsageState;
+  selectedSessionId?: string;
+  detail?: SessionModel;
+  message?: string;
+  daemonConnected: boolean;
+  filters: DashboardFilters;
+}
+
+export const INITIAL_DASHBOARD_STATE: DashboardState = {
+  view: "sessions",
+  mode: "list",
+  sessions: [],
+  counts: null,
+  usage: { providers: [], lastRefreshedAt: 0 },
+  daemonConnected: true,
+  filters: { query: "", actionableOnly: false, tool: "all", state: "all" },
+};
+
+export type DashboardAction =
+  | { type: "sessions-loaded"; sessions: SessionListItem[]; counts: SessionViewCounts }
+  | { type: "usage-loaded"; usage: UsageState }
+  | { type: "connection"; connected: boolean }
+  | { type: "select"; id?: string }
+  | { type: "view"; view: DashboardView }
+  | { type: "search" }
+  | { type: "query"; query: string }
+  | { type: "toggle-actionable" }
+  | { type: "cycle-filters" }
+  | { type: "detail"; session: SessionModel }
+  | { type: "message"; message: string }
+  | { type: "bindings" }
+  | { type: "close-overlay" };
+
+export function dashboardReducer(state: DashboardState, action: DashboardAction): DashboardState {
+  switch (action.type) {
+    case "sessions-loaded": {
+      const selectedSessionId = action.sessions.some((session) => session.id === state.selectedSessionId)
+        ? state.selectedSessionId
+        : undefined;
+      return { ...state, sessions: action.sessions, counts: action.counts, selectedSessionId, daemonConnected: true };
+    }
+    case "usage-loaded":
+      return { ...state, usage: action.usage };
+    case "connection":
+      return { ...state, daemonConnected: action.connected };
+    case "select":
+      return { ...state, selectedSessionId: action.id };
+    case "view":
+      return { ...state, view: action.view, mode: "list", detail: undefined, message: undefined };
+    case "search":
+      return { ...state, mode: "search" };
+    case "query":
+      return { ...state, filters: { ...state.filters, query: action.query } };
+    case "toggle-actionable":
+      return { ...state, filters: { ...state.filters, actionableOnly: !state.filters.actionableOnly } };
+    case "cycle-filters":
+      return { ...state, filters: cycleFilters(state.filters) };
+    case "detail":
+      return { ...state, mode: "detail", detail: action.session, message: undefined };
+    case "message":
+      return { ...state, mode: "message", message: action.message, detail: undefined };
+    case "bindings":
+      return { ...state, mode: "bindings", detail: undefined, message: undefined };
+    case "close-overlay":
+      return { ...state, mode: "list", detail: undefined, message: undefined };
+  }
+}

package/src/tui/theme.ts

@@ -0,0 +1,110 @@
+/**
+ * Scrylog brand palette (source: brand guide, OpenTUI-compatible ANSI sheet).
+ *
+ * Single source of truth for every color used by the TUI: change a value here
+ * (or swap the whole object for an alternate theme) and the whole UI follows.
+ */
+export const BRAND = {
+  /** Main Teal/Cyan — primary brand color (xterm 80). */
+  primary: "#5CCCCC",
+  /** Accent Light Blue (xterm 159). */
+  accentBlue: "#A1E6FF",
+  /** Highlight Violet (xterm 177). */
+  violet: "#CFA6FF",
+  /** Detail Grey — secondary text (xterm 246). */
+  grey: "#A0A0A0",
+  /** Background Dark (xterm 234). */
+  bgDark: "#1A1A1A",
+  /** Modal / floating panel surface (near-black, kept from legacy scheme). */
+  surface: "#11151c",
+  /** Functional colors kept unchanged (no palette equivalent). */
+  danger: "#f05252",
+  warning: "#f5a524",
+
+  /** Legacy chrome visuals preserved by design: pane borders and separators. */
+  border: "#495365",
+  /** Selected session row background (legacy slate). */
+  selection: "#263244",
+  /** Fallback foreground for rows whose state has no mapping. */
+  fallback: "#d8dee9",
+
+  /** Session state colors (palette-family tints). */
+  stateWorking: "#E8BC5D",
+  stateIdle: "#6BD9A4",
+  /** Usage semaphore ≥90% (soft coral, danger family). */
+  usageHigh: "#E28686",
+} as const;
+
+export interface ProviderVisual {
+  name: string;
+  short: string;
+  brandColor: string;
+  borderColor: string;
+  /** Alternative brand color readable on dark terminal backgrounds. */
+  onDarkColor?: string;
+  tileColor?: string;
+  terminalAsset?: URL;
+  graphicsAsset?: URL;
+}
+
+/** Third-party provider brand colors: data, not brand palette. */
+export const PROVIDER_BRANDS: Record<string, ProviderVisual> = {
+  claude: {
+    name: "Claude",
+    short: "CL",
+    brandColor: "#d97757",
+    borderColor: "#d97757",
+    terminalAsset: new URL("./assets/providers/claude-terminal.png", import.meta.url),
+    graphicsAsset: new URL("./assets/providers/claude.png", import.meta.url),
+  },
+  codex: {
+    name: "Codex",
+    short: "CX",
+    brandColor: "#539af8",
+    borderColor: "#539af8",
+    terminalAsset: new URL("./assets/providers/openai-terminal.png", import.meta.url),
+    graphicsAsset: new URL("./assets/providers/openai.png", import.meta.url),
+  },
+  "opencode-go": {
+    name: "OpenCode Go",
+    short: "OC",
+    brandColor: "#111111",
+    onDarkColor: "#c8cdd8",
+    borderColor: BRAND.grey,
+    tileColor: "#f3f3f3",
+    terminalAsset: new URL("./assets/providers/opencode-terminal.png", import.meta.url),
+    graphicsAsset: new URL("./assets/providers/opencode.png", import.meta.url),
+  },
+  copilot: {
+    name: "Copilot",
+    short: "CP",
+    brandColor: "#c8cdd8",
+    borderColor: BRAND.grey,
+    graphicsAsset: new URL("./assets/providers/copilot.png", import.meta.url),
+  },
+  shell: {
+    name: "Shell",
+    short: "SH",
+    brandColor: "#c8cdd8",
+    borderColor: BRAND.grey,
+    graphicsAsset: new URL("./assets/providers/shell.png", import.meta.url),
+  },
+  unknown: {
+    name: "Unknown",
+    short: "?",
+    brandColor: BRAND.grey,
+    borderColor: BRAND.grey,
+    graphicsAsset: new URL("./assets/providers/unknown.png", import.meta.url),
+  },
+};
+
+export const BRAND_MARK = {
+  /** Blocks: front-view crystal ball + prompt + circuit pedestal, brand palette. */
+  art: [
+    { fg: BRAND.accentBlue, content: "  ▗▄▄▄▄▄▄▖" },
+    { fg: BRAND.primary, content: " ▐▓▒░░░░▒▓▌" },
+    { fg: BRAND.primary, content: " ░ ◉◈◉ ›_ ░" },
+    { fg: BRAND.violet, content: " ▜▓▒░░░░▒▓▛" },
+    { fg: BRAND.violet, content: "  ▐█╿██╵█▌" },
+  ],
+} as const;

package/src/usage/README.md

@@ -297,7 +297,7 @@ These clients use the global `fetch` and have no Node.js or platform dependencie
 |---|---|---|
 | `enabled` | `true` | Enable usage collection |
 | `pollIntervalMs` | `300000` | Polling interval (5 minutes) |
-| `providers` | `["claude", "opencode-go"]` | Which providers to poll |
+| `providers` | `["claude", "opencode-go", "codex"]` | Which providers to poll |
 | `claude.dataSource` | `"auto"` | `"auto"`, `"oauth"`, `"web"`, or `"cli"` |
 | `claude.webExtrasEnabled` | `true` | Enrich OAuth/CLI with Web API extras |
 | `codex.dataSource` | `"auto"` | `"auto"` or `"oauth"` |
@@ -311,7 +311,7 @@ These clients use the global `fetch` and have no Node.js or platform dependencie
 | Claude OAuth (`~/.claude/.credentials.json`) | ⚠️ (fallback only) | ✅ | ✅ | ✅ |
 | Claude Web (browser cookies) | ✅ (Chrome + Safari) | ✅ (Chrome/Chromium) | ✅ (Chrome/Chromium) | ❌ (Chrome: DPAPI not implemented) |
 | Claude CLI (PTY probe) | ✅ (`script` wrapper) | ⚠️ (no PTY wrapper) | ⚠️ (no PTY wrapper) | ⚠️ (no PTY wrapper) |
-| Codex OAuth (`~/.codex/auth.json`) | ✅ | ✅ | ✅ | ✅ (filepath) |
+| Codex OAuth + owner CLI recovery | ✅ | ✅ | ✅ | ⚠️ (CLI launch is experimental) |
 | OpenCode Go (browser cookies) | ✅ | ✅ | ✅ | ❌ (Chrome: DPAPI not implemented) |
 
 ## Adding a new provider
@@ -319,5 +319,5 @@ These clients use the global `fetch` and have no Node.js or platform dependencie
 1. Create resolver + client in `src/usage/resolvers/` and `src/usage/clients/`
 2. Create provider in `src/usage/providers/<name>.ts` that returns `{ entry: UsageProviderEntry, snapshot: any }`
 3. Add mapper in `src/usage/mappers.ts`: `map<Name>ToEntry(snapshot, errors, available)` — include `accountId` computation
-4. Register in `UsageCollector.poll()` with availability pre-check
+4. Register in `UsageCollector.poll()`; the provider returns an unavailable entry when credentials are absent
 5. No changes needed to `UsageState`, Zod schemas, or API route