@duckmind/dm-darwin-x64 0.35.8 → 0.35.9

package/extensions/dm-usage/README.md

@@ -7,12 +7,20 @@ Bundled DM extension that adds `/usage`, an interactive dashboard for local sess
 ## Included command surface
 
 - `/usage`
+- `/usage use [provider-id|clear|remove <provider-id>]`
+- `/usage show`
+- `/usage rotation`
+- `/usage verify`
+- `/usage path`
+- `/usage reset [manual|quota|all]`
+- `/usage help`
 
 ## Runtime notes
 
 - Reads session JSONL files recursively from `~/.dm/agent/sessions/`.
 - Respects `DM_CODING_AGENT_DIR`; `PI_CODING_AGENT_DIR` is accepted only as a compatibility fallback.
 - Displays raw provider `openai-codex` as `duckmind-ultra` and `openrouter` as `duckmind-standard` without changing recorded session data.
+- Restored account-tool subcommands keep local managed-account metadata in `~/.dm/agent/usage/state.json`; they do not store API secrets or route provider requests.
 - `Tab` / `←` / `→` switch periods, `v` toggles table/insights view, and `q` / `Esc` closes the dashboard.
 - Cost data comes from recorded assistant usage payloads, so accuracy depends on providers reporting `usage.cost.total`.
 

package/extensions/dm-usage/index.ts

@@ -9,9 +9,10 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
 import { DynamicBorder } from "@mariozechner/pi-coding-agent";
-import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncateToWidth, wrapTextWithAnsi, type AutocompleteItem } from "@mariozechner/pi-tui";
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 
 // =============================================================================
@@ -90,6 +91,31 @@ interface UsageData {
 
 type TabName = "today" | "thisWeek" | "lastWeek" | "allTime";
 type ViewMode = "table" | "insights";
+type UsageSubcommand = "use" | "show" | "rotation" | "verify" | "path" | "reset" | "help";
+type UsageResetTarget = "manual" | "quota" | "all";
+
+interface UsageManagedAccount {
+	id: string;
+	label: string;
+	provider: string;
+	source: "session" | "manual";
+	updatedAt: string;
+	quotaExhaustedUntil?: number;
+}
+
+interface UsageManagedState {
+	version: 1;
+	manualAccountId?: string;
+	removedAccountIds: string[];
+	accounts: UsageManagedAccount[];
+	updatedAt: string;
+}
+
+interface UsageManagedSummary {
+	data: UsageData;
+	state: UsageManagedState;
+	accounts: UsageManagedAccount[];
+}
 
 // =============================================================================
 // Column Configuration
@@ -195,10 +221,25 @@ const TABLE_LAYOUTS: TableLayoutCandidate[] = [
 // Data Collection
 // =============================================================================
 
-function getSessionsDir(): string {
+function getAgentDir(): string {
 	// Respect DM_CODING_AGENT_DIR, keeping PI_CODING_AGENT_DIR only as a compatibility fallback
-	const agentDir = process.env.DM_CODING_AGENT_DIR || process.env.PI_CODING_AGENT_DIR || join(homedir(), ".dm", "agent");
-	return join(agentDir, "sessions");
+	return process.env.DM_CODING_AGENT_DIR || process.env.PI_CODING_AGENT_DIR || join(homedir(), ".dm", "agent");
+}
+
+function getSessionsDir(): string {
+	return join(getAgentDir(), "sessions");
+}
+
+function getUsageStateDir(): string {
+	return join(getAgentDir(), "usage");
+}
+
+function getUsageStatePath(): string {
+	return join(getUsageStateDir(), "state.json");
+}
+
+function getAgentSettingsPath(): string {
+	return join(getAgentDir(), "settings.json");
 }
 
 async function collectSessionFilesRecursively(dir: string, files: string[], signal?: AbortSignal): Promise<void> {
@@ -513,6 +554,449 @@ async function collectUsageData(signal?: AbortSignal): Promise<UsageData | null>
 	return data;
 }
 
+// =============================================================================
+// Managed Account Command Helpers
+// =============================================================================
+
+const USAGE_SUBCOMMANDS = ["use", "show", "rotation", "verify", "path", "reset", "help"] as const;
+const USAGE_RESET_TARGETS = ["manual", "quota", "all"] as const;
+const USAGE_HELP_TEXT = [
+	"Usage: /usage [use|show|rotation|verify|path|reset|help]",
+	"use: select, activate, or remove managed account",
+	"show: managed account and usage summary",
+	"rotation: current rotation behavior",
+	"verify: runtime health checks",
+	"path: storage and settings locations",
+	"reset: clear manual or quota state",
+].join("\n");
+
+function parseUsageCommandArgs(args: string): { subcommand?: string; rest: string } {
+	const trimmed = args.trim();
+	if (!trimmed) return { rest: "" };
+	const firstSpaceIndex = trimmed.indexOf(" ");
+	if (firstSpaceIndex < 0) return { subcommand: trimmed.toLowerCase(), rest: "" };
+	return {
+		subcommand: trimmed.slice(0, firstSpaceIndex).toLowerCase(),
+		rest: trimmed.slice(firstSpaceIndex + 1).trim(),
+	};
+}
+
+function isUsageSubcommand(value: string): value is UsageSubcommand {
+	return USAGE_SUBCOMMANDS.some((subcommand) => subcommand === value);
+}
+
+function parseUsageResetTarget(value: string): UsageResetTarget | undefined {
+	if (value === "manual" || value === "quota" || value === "all") return value;
+	return undefined;
+}
+
+function toAutocompleteItems(values: readonly string[]): AutocompleteItem[] {
+	return values.map((value) => ({ value, label: value }));
+}
+
+function getUsageCommandCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+	const trimmedStart = argumentPrefix.trimStart();
+	if (!trimmedStart) return toAutocompleteItems(USAGE_SUBCOMMANDS);
+
+	const firstSpaceIndex = trimmedStart.indexOf(" ");
+	if (firstSpaceIndex < 0) {
+		const matches = USAGE_SUBCOMMANDS.filter((value) => value.startsWith(trimmedStart.toLowerCase()));
+		return matches.length > 0 ? toAutocompleteItems(matches) : null;
+	}
+
+	const subcommand = trimmedStart.slice(0, firstSpaceIndex).toLowerCase();
+	const rest = trimmedStart.slice(firstSpaceIndex + 1).toLowerCase();
+	if (subcommand === "reset") {
+		const matches = USAGE_RESET_TARGETS.filter((value) => value.startsWith(rest));
+		return matches.length > 0 ? matches.map((value) => ({ value: `reset ${value}`, label: value })) : null;
+	}
+	if (subcommand === "use") {
+		const matches = ["clear", "remove"].filter((value) => value.startsWith(rest));
+		return matches.length > 0 ? matches.map((value) => ({ value: `use ${value}`, label: value })) : null;
+	}
+	return null;
+}
+
+function emptyUsageManagedState(): UsageManagedState {
+	return { version: 1, removedAccountIds: [], accounts: [], updatedAt: new Date(0).toISOString() };
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeUsageManagedAccount(value: unknown): UsageManagedAccount | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	const id = asString(record.id);
+	const provider = asString(record.provider) ?? id;
+	if (!id || !provider) return undefined;
+	const label = asString(record.label) ?? formatProviderName(provider);
+	const source = record.source === "manual" ? "manual" : "session";
+	const updatedAt = asString(record.updatedAt) ?? new Date(0).toISOString();
+	const quota =
+		typeof record.quotaExhaustedUntil === "number" && Number.isFinite(record.quotaExhaustedUntil)
+			? record.quotaExhaustedUntil
+			: undefined;
+	return { id, label, provider, source, updatedAt, quotaExhaustedUntil: quota };
+}
+
+function normalizeUsageManagedState(value: unknown): UsageManagedState {
+	const empty = emptyUsageManagedState();
+	if (!value || typeof value !== "object") return empty;
+	const record = value as Record<string, unknown>;
+	const accounts = Array.isArray(record.accounts)
+		? record.accounts.map(normalizeUsageManagedAccount).filter((account): account is UsageManagedAccount => Boolean(account))
+		: [];
+	const removedAccountIds = Array.isArray(record.removedAccountIds)
+		? record.removedAccountIds.map(asString).filter((id): id is string => Boolean(id))
+		: [];
+	return {
+		version: 1,
+		manualAccountId: asString(record.manualAccountId),
+		removedAccountIds,
+		accounts,
+		updatedAt: asString(record.updatedAt) ?? empty.updatedAt,
+	};
+}
+
+function getErrorCode(error: unknown): string | undefined {
+	return error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : undefined;
+}
+
+async function readUsageManagedState(): Promise<{ state: UsageManagedState; error?: string }> {
+	try {
+		const raw = await readFile(getUsageStatePath(), "utf8");
+		return { state: normalizeUsageManagedState(JSON.parse(raw)) };
+	} catch (error) {
+		if (getErrorCode(error) === "ENOENT") return { state: emptyUsageManagedState() };
+		return { state: emptyUsageManagedState(), error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+async function saveUsageManagedState(state: UsageManagedState): Promise<void> {
+	state.version = 1;
+	state.updatedAt = new Date().toISOString();
+	state.removedAccountIds = [...new Set(state.removedAccountIds)].sort();
+	state.accounts = state.accounts
+		.filter((account) => !state.removedAccountIds.includes(account.id))
+		.sort((a, b) => a.label.localeCompare(b.label));
+	await mkdir(dirname(getUsageStatePath()), { recursive: true });
+	await writeFile(getUsageStatePath(), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function isQuotaActive(account: UsageManagedAccount): boolean {
+	return typeof account.quotaExhaustedUntil === "number" && account.quotaExhaustedUntil > Date.now();
+}
+
+function getAccountStats(data: UsageData, account: UsageManagedAccount): ProviderStats | undefined {
+	return data.allTime.providers.get(account.provider);
+}
+
+function getManagedAccounts(data: UsageData, state: UsageManagedState): UsageManagedAccount[] {
+	const now = new Date().toISOString();
+	const accounts = new Map<string, UsageManagedAccount>();
+	for (const account of state.accounts) {
+		if (!state.removedAccountIds.includes(account.id)) accounts.set(account.id, account);
+	}
+	for (const provider of data.allTime.providers.keys()) {
+		if (state.removedAccountIds.includes(provider) || accounts.has(provider)) continue;
+		accounts.set(provider, {
+			id: provider,
+			label: formatProviderName(provider),
+			provider,
+			source: "session",
+			updatedAt: now,
+		});
+	}
+
+	return Array.from(accounts.values()).sort((a, b) => {
+		const manualId = state.manualAccountId;
+		if (a.id === manualId && b.id !== manualId) return -1;
+		if (b.id === manualId && a.id !== manualId) return 1;
+		if (isQuotaActive(a) !== isQuotaActive(b)) return isQuotaActive(a) ? 1 : -1;
+		const costDelta = (getAccountStats(data, b)?.cost ?? 0) - (getAccountStats(data, a)?.cost ?? 0);
+		if (costDelta !== 0) return costDelta;
+		return a.label.localeCompare(b.label);
+	});
+}
+
+function getActiveManagedAccount(accounts: UsageManagedAccount[], state: UsageManagedState): UsageManagedAccount | undefined {
+	const manual = accounts.find((account) => account.id === state.manualAccountId && !isQuotaActive(account));
+	return manual ?? accounts.find((account) => !isQuotaActive(account));
+}
+
+function findManagedAccount(accounts: UsageManagedAccount[], query: string): UsageManagedAccount | undefined {
+	const normalized = query.trim().toLowerCase();
+	return accounts.find(
+		(account) =>
+			account.id.toLowerCase() === normalized ||
+			account.provider.toLowerCase() === normalized ||
+			account.label.toLowerCase() === normalized
+	);
+}
+
+function formatManagedAccountLine(account: UsageManagedAccount, data: UsageData, state: UsageManagedState): string {
+	const stats = getAccountStats(data, account);
+	const tags = [
+		state.manualAccountId === account.id ? "manual" : undefined,
+		isQuotaActive(account) ? "quota" : undefined,
+		account.source === "manual" ? "manual-entry" : undefined,
+	]
+		.filter(Boolean)
+		.join(", ");
+	const suffix = tags ? ` (${tags})` : "";
+	const cost = stats ? formatCost(stats.cost) : formatCost(0);
+	const messages = stats ? formatNumber(stats.messages) : "0";
+	const sessions = stats ? formatNumber(stats.sessions.size) : "0";
+	return `${account.label}${suffix} · id=${account.id} · spend=${cost} · messages=${messages} · sessions=${sessions}`;
+}
+
+async function loadUsageManagedSummary(ctx: ExtensionCommandContext): Promise<UsageManagedSummary | null> {
+	const data = await collectUsageData(ctx.signal);
+	if (!data) {
+		ctx.ui.notify("Usage data unavailable or cancelled.", "warning");
+		return null;
+	}
+	const { state, error } = await readUsageManagedState();
+	if (error) {
+		ctx.ui.notify(`dm-usage state unreadable; using empty state: ${error}`, "warning");
+	}
+	return { data, state, accounts: getManagedAccounts(data, state) };
+}
+
+function managedAccountNoDataMessage(): string {
+	return "No managed accounts found. Run /usage after at least one provider response, or use /usage use <provider-id> to create a local manual entry.";
+}
+
+async function activateUsageAccount(ctx: ExtensionCommandContext, summary: UsageManagedSummary, account: UsageManagedAccount): Promise<void> {
+	summary.state.manualAccountId = account.id;
+	summary.state.removedAccountIds = summary.state.removedAccountIds.filter((id) => id !== account.id);
+	summary.state.accounts = summary.accounts.map((item) => (item.id === account.id ? { ...item, updatedAt: new Date().toISOString() } : item));
+	await saveUsageManagedState(summary.state);
+	ctx.ui.notify(`dm-usage: now using ${account.label} (${account.id})`, "info");
+}
+
+async function clearUsageManualAccount(ctx: ExtensionCommandContext, state: UsageManagedState): Promise<void> {
+	const hadManual = Boolean(state.manualAccountId);
+	state.manualAccountId = undefined;
+	await saveUsageManagedState(state);
+	ctx.ui.notify(`dm-usage: manual account ${hadManual ? "cleared" : "was not set"}`, "info");
+}
+
+async function removeUsageAccountState(ctx: ExtensionCommandContext, summary: UsageManagedSummary, account: UsageManagedAccount): Promise<void> {
+	summary.state.removedAccountIds = [...summary.state.removedAccountIds, account.id];
+	if (summary.state.manualAccountId === account.id) summary.state.manualAccountId = undefined;
+	summary.state.accounts = summary.accounts.filter((item) => item.id !== account.id);
+	await saveUsageManagedState(summary.state);
+	ctx.ui.notify(`dm-usage: removed local managed-account state for ${account.label}; session data was not changed.`, "info");
+}
+
+async function runUsageUseSubcommand(ctx: ExtensionCommandContext, rest: string): Promise<void> {
+	const summary = await loadUsageManagedSummary(ctx);
+	if (!summary) return;
+
+	if (rest === "clear") {
+		await clearUsageManualAccount(ctx, summary.state);
+		return;
+	}
+
+	if (rest.startsWith("remove ")) {
+		const account = findManagedAccount(summary.accounts, rest.slice("remove ".length));
+		if (!account) {
+			ctx.ui.notify(`Unknown managed account: ${rest.slice("remove ".length)}`, "warning");
+			return;
+		}
+		await removeUsageAccountState(ctx, summary, account);
+		return;
+	}
+
+	if (rest) {
+		const account =
+			findManagedAccount(summary.accounts, rest) ??
+			({ id: rest, label: formatProviderName(rest), provider: rest, source: "manual", updatedAt: new Date().toISOString() } satisfies UsageManagedAccount);
+		if (!summary.accounts.some((item) => item.id === account.id)) summary.accounts.push(account);
+		await activateUsageAccount(ctx, summary, account);
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		ctx.ui.notify(summary.accounts.length ? summary.accounts.map((account) => formatManagedAccountLine(account, summary.data, summary.state)).join("\n") : managedAccountNoDataMessage(), summary.accounts.length ? "info" : "warning");
+		return;
+	}
+
+	const options = [
+		...summary.accounts.map((account) => formatManagedAccountLine(account, summary.data, summary.state)),
+		"add manual account",
+		"clear manual account",
+	];
+	const selected = await ctx.ui.select("DuckMind Usage Accounts", options);
+	if (!selected) return;
+	if (selected === "add manual account") {
+		const id = (await ctx.ui.input("Managed account id (provider key, no secret)"))?.trim();
+		if (!id) return;
+		await runUsageUseSubcommand(ctx, id);
+		return;
+	}
+	if (selected === "clear manual account") {
+		await clearUsageManualAccount(ctx, summary.state);
+		return;
+	}
+
+	const account = summary.accounts[options.indexOf(selected)];
+	if (!account) return;
+	const action = await ctx.ui.select("Account Action", ["activate", "remove local state", "cancel"]);
+	if (action === "activate") await activateUsageAccount(ctx, summary, account);
+	if (action === "remove local state") await removeUsageAccountState(ctx, summary, account);
+}
+
+async function runUsageShowSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const summary = await loadUsageManagedSummary(ctx);
+	if (!summary) return;
+	const active = getActiveManagedAccount(summary.accounts, summary.state);
+	const hiddenCount = summary.state.removedAccountIds.length;
+	const lines = [
+		"DuckMind Usage managed account summary",
+		`active: ${active ? `${active.label} (${active.id})` : "none"}`,
+		`manual: ${summary.state.manualAccountId ?? "none"}`,
+		`accounts: ${summary.accounts.length}${hiddenCount ? ` · hidden=${hiddenCount}` : ""}`,
+		`all-time: spend=${formatCost(summary.data.allTime.totals.cost)} · messages=${formatNumber(summary.data.allTime.totals.messages)} · sessions=${formatNumber(summary.data.allTime.totals.sessions)} · tokens=${formatTokens(summary.data.allTime.totals.tokens.total)}`,
+		"",
+		...(summary.accounts.length
+			? summary.accounts.map((account) => formatManagedAccountLine(account, summary.data, summary.state))
+			: [managedAccountNoDataMessage()]),
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select("DuckMind Usage Summary", lines);
+	} else {
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+}
+
+async function runUsageRotationSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const lines = [
+		"Current policy: manual account first, then accounts without quota cooldown, then highest all-time local spend, then alphabetical fallback.",
+		"dm-usage is observational: this state changes /usage account summaries only and does not route provider requests or store API secrets.",
+		"Use /usage reset manual to clear manual selection, or /usage reset quota to clear quota cooldown markers.",
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select("DuckMind Usage Rotation", lines);
+	} else {
+		ctx.ui.notify(lines.join(" "), "info");
+	}
+}
+
+async function isDirectoryReadable(path: string): Promise<boolean> {
+	try {
+		await access(path, fsConstants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function isWritableDirectoryFor(filePath: string): Promise<boolean> {
+	try {
+		const directory = dirname(filePath);
+		await mkdir(directory, { recursive: true });
+		await access(directory, fsConstants.R_OK | fsConstants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function runUsageVerifySubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const sessionsReadable = await isDirectoryReadable(getSessionsDir());
+	const stateWritable = await isWritableDirectoryFor(getUsageStatePath());
+	const settingsWritable = await isWritableDirectoryFor(getAgentSettingsPath());
+	const stateRead = await readUsageManagedState();
+	const summary = await loadUsageManagedSummary(ctx);
+	const accounts = summary?.accounts.length ?? 0;
+	const active = summary ? getActiveManagedAccount(summary.accounts, summary.state)?.id ?? "none" : "none";
+	const ok = sessionsReadable && stateWritable && settingsWritable && !stateRead.error;
+	const lines = [
+		`verify: ${ok ? "PASS" : "WARN"}`,
+		`sessions readable: ${sessionsReadable ? "yes" : "no"}`,
+		`state directory writable: ${stateWritable ? "yes" : "no"}`,
+		`settings directory writable: ${settingsWritable ? "yes" : "no"}`,
+		`state json: ${stateRead.error ? `invalid (${stateRead.error})` : "ok"}`,
+		`managed accounts: ${accounts}`,
+		`active account: ${active}`,
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select(`DuckMind Usage Verify (${ok ? "PASS" : "WARN"})`, lines);
+	} else {
+		ctx.ui.notify(lines.join("\n"), ok ? "info" : "warning");
+	}
+}
+
+async function runUsagePathSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const lines = [
+		`Session storage: ${getSessionsDir()}`,
+		`Managed account state: ${getUsageStatePath()}`,
+		`Agent settings: ${getAgentSettingsPath()}`,
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select("DuckMind Usage Paths", lines);
+	} else {
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+}
+
+async function chooseUsageResetTarget(ctx: ExtensionCommandContext, argument: string): Promise<UsageResetTarget | undefined> {
+	const explicitTarget = parseUsageResetTarget(argument.toLowerCase());
+	if (explicitTarget) return explicitTarget;
+	if (argument) {
+		ctx.ui.notify("Unknown reset target. Use: /usage reset [manual|quota|all]", "warning");
+		return undefined;
+	}
+	if (!ctx.hasUI) return "all";
+	const selected = await ctx.ui.select("Reset DuckMind Usage State", [
+		"manual - clear manual account override",
+		"quota - clear quota cooldown markers",
+		"all - clear manual override, quota cooldown markers, and hidden account state",
+	]);
+	if (!selected) return undefined;
+	if (selected.startsWith("manual")) return "manual";
+	if (selected.startsWith("quota")) return "quota";
+	return "all";
+}
+
+async function runUsageResetSubcommand(ctx: ExtensionCommandContext, rest: string): Promise<void> {
+	const target = await chooseUsageResetTarget(ctx, rest);
+	if (!target) return;
+	const { state } = await readUsageManagedState();
+	const hadManual = Boolean(state.manualAccountId);
+	if (target === "manual" || target === "all") state.manualAccountId = undefined;
+	let quotaCleared = 0;
+	if (target === "quota" || target === "all") {
+		state.accounts = state.accounts.map((account) => {
+			if (account.quotaExhaustedUntil === undefined) return account;
+			quotaCleared++;
+			const { quotaExhaustedUntil: _quotaExhaustedUntil, ...restAccount } = account;
+			return restAccount;
+		});
+	}
+	const hiddenCleared = target === "all" ? state.removedAccountIds.length : 0;
+	if (target === "all") state.removedAccountIds = [];
+	await saveUsageManagedState(state);
+	ctx.ui.notify(
+		`reset: target=${target} manualCleared=${hadManual && !state.manualAccountId ? "yes" : "no"} quotaCleared=${quotaCleared} hiddenCleared=${hiddenCleared}`,
+		"info"
+	);
+}
+
+async function runUsageSubcommand(subcommand: UsageSubcommand, rest: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (subcommand === "use") return runUsageUseSubcommand(ctx, rest);
+	if (subcommand === "show") return runUsageShowSubcommand(ctx);
+	if (subcommand === "rotation") return runUsageRotationSubcommand(ctx);
+	if (subcommand === "verify") return runUsageVerifySubcommand(ctx);
+	if (subcommand === "path") return runUsagePathSubcommand(ctx);
+	if (subcommand === "reset") return runUsageResetSubcommand(ctx, rest);
+	ctx.ui.notify(USAGE_HELP_TEXT, "info");
+}
+
 // =============================================================================
 // Insights
 // =============================================================================
@@ -1161,9 +1645,21 @@ class UsageComponent {
 
 export default function (pi: ExtensionAPI) {
 	pi.registerCommand("usage", {
-		description: "Show usage statistics dashboard",
-		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		description: `Show usage statistics dashboard and account tools: ${USAGE_SUBCOMMANDS.join(", ")}`,
+		getArgumentCompletions: getUsageCommandCompletions,
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const parsed = parseUsageCommandArgs(args);
+			if (parsed.subcommand) {
+				if (!isUsageSubcommand(parsed.subcommand)) {
+					ctx.ui.notify(`Unknown /usage subcommand: ${parsed.subcommand}\n${USAGE_HELP_TEXT}`, "warning");
+					return;
+				}
+				await runUsageSubcommand(parsed.subcommand, parsed.rest, ctx);
+				return;
+			}
+
 			if (!ctx.hasUI) {
+				await runUsageShowSubcommand(ctx);
 				return;
 			}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckmind/dm-darwin-x64",
-  "version": "0.35.8",
+  "version": "0.35.9",
   "description": "DuckMind (dm) binary payload for darwin x64",
   "license": "MIT",
   "os": [