@hanamorilabs/tab 0.1.12 → 0.1.13

package/README.md

@@ -86,6 +86,8 @@ Codex shows `FlockTab - Self-hosted` as its provider.
 
 ## Commands
 
+`tab help` lists every command by group. `tab help <command>` (or `tab <command> --help`) explains one in full: what it does, its options, examples. `tab help glossary` says what is what, `tab help errors` lists every refusal and what to do. The same reference, with how the system works, is in the console under Docs (`console.flocktab.com/docs`).
+
 ```
 tab login            approve this machine in the console, once
 tab <agent> [args]   claude, codex, grok, kimi, gemini, or any command, on the tab

package/dist/cli.js

@@ -32,9 +32,11 @@ import { bold, box, cyan, dim, green, heading, line, rows, underline, yellow } f
 import { envFor, knownClients, subscriptionVendorFor } from "./clients.js";
 import { describeLogin, localLogin } from "./logins.js";
 import { prepareCodexHome } from "./codex-home.js";
-import { addMember, loadPool, memberEnv, memberHome, POOL_VENDORS, poolVendorFor, prepareClaudeMember, prepareSharedSessions, removeMember, savePool, setThreshold, thresholdFor, usedPct } from "./pool.js";
+import { addMember, loadPool, memberEnv, memberHome, POOL_VENDORS, poolVendorFor, prepareClaudeMember, prepareSharedSessions, limitsFor, removeMember, savePool, setGuard, setThreshold, thresholdFor, usage as quotaUsage } from "./pool.js";
 import { runPooled } from "./pool-run.js";
 import { renderPool } from "./pool-view.js";
+import { renderHelp } from "./help.js";
+import { findTabCommand } from "./tab-docs.js";
 import { ConsoleApiError, createAgent, issueAgentKey, listAgents } from "./console-api.js";
 import { consoleUrlFor, DeviceLoginError, startDeviceLogin, waitForApproval } from "./device-login.js";
 import { clearConfig, configDir, configPath, HOSTED_PROXY, isLocalProxy, loadConfig, LOCAL_PROXY, normalizeProxyUrl, presentedKey, saveConfig, } from "./config.js";
@@ -50,52 +52,15 @@ const say = (text) => console.error(text);
 const ok = (text) => say(line("ok", text));
 const warn = (text) => say(line("warn", text));
 const fail = (text) => say(line("fail", text));
-function usage() {
-    const others = knownClients().filter((n) => n !== "claude" && n !== "codex");
-    const cmd = (name, what) => [`tab ${name}`, what];
-    say(`${heading("tab")} ${dim("- run any AI agent on a FlockTab tab")}
-`);
-    say(rows([
-        cmd("login", "approve this machine in the console, once"),
-        cmd("claude [args]", "Claude Code on the tab"),
-        cmd("codex [args]", "Codex on the tab"),
-        cmd(others.join(" | tab "), "the same, for those agents"),
-        cmd("<command> [args]", "any other agent, both APIs pointed at the tab"),
-        cmd("use", "pick or change the Agent this folder runs as (.flocktab)"),
-        cmd("agent create <name>", "a new Agent: --subscription (your own logins) or --api (the flock's key, metered)"),
-        cmd("agent kind <agent> api|subscription", "change it"),
-        cmd("accounts", "accounts your subscription Agents were seen on: plan, price, quota used"),
-        cmd("pool", "several logins of one vendor; tab claude runs as the one with most room"),
-        cmd("pool add claude|codex|grok|kimi <name>", "sign another login in through the browser (--email to prefill, --dir <path> to use a folder you have)"),
-        cmd("pool at [claude|codex|grok|kimi] <percent>", "move to another login once this much of a window is used (default 80); per vendor if named"),
-        cmd("alias setup <name>...", "make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)"),
-        cmd("alias remove <name>...", "undo that; `tab alias list` shows them"),
-        cmd("status", "which flock, which Agent here, is the proxy up"),
-        cmd("log [-f] [--all]", "everything through the tab on this machine's Agents, one line per call; -f follows"),
-        cmd("log --proxy [-f]", "self-hosted: the local proxy's own log (cached tokens, milliseconds; no keys, logins or prompts)"),
-        cmd("version", "tab and proxy versions"),
-        cmd("list", "every Agent: state, spent of cap, window, project"),
-        cmd("close | open [agent]", "the kill switch; omit the Agent for this folder's"),
-        cmd("cap [agent] <dollars>", "set the cap (--window day|week|month|run|hour|lifetime)"),
-        cmd("rename <agent> <name>", "rename it (the slug stays)"),
-        cmd("policy [agent]", "show or set: --velocity N|none --models a,b|none --allow tool|none"),
-        cmd("project [agent] <name>", "attribute to a project (--create, --repo owner/name, none)"),
-        cmd("projects [add <name>]", "list or add projects"),
-        cmd("key rotate [agent]", "new key, kept on this machine (--show prints it once)"),
-        cmd("archive [agent]", "close for good and leave the bill"),
-        cmd("ledger [agent]", "one row per call (--limit N --blocked)"),
-        cmd("spend [agent|project|day]", "meter and outside spend (--since 7d --agent x)"),
-        cmd("outside", "outside-spend connections and per-project totals"),
-        cmd("live", "who is working now (--watch 4)"),
-        cmd("web [agent]", "open the Agent's console page"),
-        cmd("... --json", "every read command as JSON, for scripts and agents"),
-        cmd("up", "self-hosted: start the local proxy (fetches it the first time)"),
-        cmd("down", "self-hosted: stop the local proxy"),
-        cmd("update", "the newest tab (and proxy) from npm; restarts a running local proxy"),
-        cmd("logout", "forget the session and keys"),
-    ].map(([k, v]) => [cyan(k), v])));
-    say(`
-${dim("Config")} ${configPath()}  ${dim("or FLOCKTAB_PROXY_URL, FLOCKTAB_KEY, FLOCKTAB_UNLOCK")}`);
+/** `tab help`, `tab help <word>`: the overview, one command, the glossary, the errors. */
+function usage(word) {
+    const text = renderHelp(word, { configPath: configPath() });
+    if (text === undefined) {
+        fail(`No help for "${word}". ${dim("tab help lists every command.")}`);
+        return 2;
+    }
+    say(text);
+    return 0;
 }
 /**
  * Without a terminal (CI, a script, `printf ... | tab up`) every answer
@@ -537,6 +502,31 @@ const VENDOR_HARNESS = { anthropic: "claude", openai: "codex", xai: "grok", kimi
 async function flockAccounts(config) {
     return (await manage.api(config)("GET", "/api/cli/accounts")).accounts;
 }
+/**
+ * Tell the console which logins this machine is signed in with, so a pool
+ * member shows there before its first call. Only what the harness's own
+ * files say about the account (the vendor's id, email, plan tier), never a
+ * login. Best effort: the pool works the same when the console is away.
+ */
+async function registerPoolLogins(config, pool) {
+    const accounts = [];
+    for (const vendor of POOL_VENDORS) {
+        for (const member of pool.members[vendor] ?? []) {
+            const login = await memberLogin(vendor, member);
+            if (!login?.accountId)
+                continue;
+            accounts.push({ provider: vendor, externalId: login.accountId, ...(login.email ? { email: login.email } : {}), ...(login.plan ? { plan: login.plan } : {}) });
+        }
+    }
+    if (accounts.length === 0)
+        return undefined;
+    try {
+        return (await manage.api(config)("POST", "/api/cli/accounts", { accounts })).accounts;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Each member with the login its folder holds and how used the vendor last said that account is. */
 async function poolStandings(config, vendor, members, known) {
     const accounts = known ?? (await flockAccounts(config).catch(() => []));
@@ -548,7 +538,7 @@ async function poolStandings(config, vendor, members, known) {
         const shown = email ?? (login?.accountId ? `account ${login.accountId.slice(0, 12)}` : undefined);
         // The vendor's plan name once seen on the wire; before that, what the harness's own file says.
         const plan = account?.planLabel ?? login?.plan?.replace(/^default_/, "").replaceAll("_", " ");
-        return { member, used: account ? usedPct(account.quota) : undefined, ...(shown ? { email: shown } : {}), ...(plan ? { plan } : {}), ...(account ? { windows: account.quota } : {}) };
+        return { member, used: undefined, ...(account ? quotaUsage(account.quota) : {}), ...(shown ? { email: shown } : {}), ...(plan ? { plan } : {}), ...(account ? { windows: account.quota } : {}) };
     }));
 }
 /** Quiet: no call of this Agent in flight, and no reply from the vendor in the last 20 seconds. */
@@ -661,6 +651,7 @@ async function runAgent(name, argv) {
     // Codex, Grok and Kimi members share one conversations folder.
     for (const member of members)
         await prepareSharedSessions(poolVendor, member);
+    void registerPoolLogins(config, pool);
     if (poolVendor === "openai") {
         for (const member of members) {
             await prepareCodexHome({ baseDir: member.dir, proxyUrl: config.proxyUrl, presentedKey: key, mode: config.mode, auth, userCodexHome: path.join(member.dir, "no-personal-login") });
@@ -668,7 +659,7 @@ async function runAgent(name, argv) {
     }
     return runPooled(args, {
         harness: name,
-        at: thresholdFor(pool, poolVendor),
+        limits: limitsFor(pool, poolVendor),
         swap: pool.swap,
         ...(pinned ? { pinned } : {}),
         standings: () => poolStandings(config, poolVendor, members),
@@ -696,23 +687,32 @@ async function poolCommand(argv) {
     const HARNESSES = "claude|codex|grok|kimi";
     if (sub === "at") {
         // `tab pool at 80` for everyone; `tab pool at claude 70` for one vendor; `tab pool at claude default` to clear it.
-        const vendor = rest.length > 1 ? vendorOf(rest[0]) : undefined;
-        const value = rest.length > 1 ? rest[1] : rest[0];
+        // A window word makes it the weekly guard: `tab pool at 7d 95`, `tab pool at claude weekly 90`.
+        const words = rest.filter((w) => !["7d", "weekly", "week", "long"].includes(w));
+        const guard = words.length !== rest.length;
+        // `5h` / `short` is the default meaning, accepted so both read the same way.
+        const plain = words.filter((w) => !["5h", "short"].includes(w));
+        const vendor = plain.length > 1 ? vendorOf(plain[0]) : undefined;
+        const value = plain.length > 1 ? plain[1] : plain[0];
         const clear = vendor !== undefined && (value === "default" || value === "reset");
-        if ((rest.length > 1 && !vendor) || (!clear && !/^\d{1,3}$/.test(value ?? ""))) {
-            fail(`tab pool at <percent>, or tab pool at claude|codex|grok|kimi <percent>|default. ${dim("A percent is 1 to 100.")}`);
+        if ((plain.length > 1 && !vendor) || plain.length > 2 || (!clear && !/^\d{1,3}$/.test(value ?? ""))) {
+            fail(`tab pool at [claude|codex|grok|kimi] [7d] <percent>|default. ${dim("A percent is 1 to 100. Without 7d it is the short (5-hour) window; with it, the weekly guard.")}`);
             return 2;
         }
         let next;
         try {
-            next = setThreshold(pool, clear ? undefined : Number(value), vendor);
+            next = (guard ? setGuard : setThreshold)(pool, clear ? undefined : Number(value), vendor);
         }
         catch (err) {
             fail(err.message);
             return 2;
         }
         await savePool(next);
-        if (!vendor) {
+        if (guard) {
+            const g = vendor ? limitsFor(next, vendor).guard : next.guard;
+            ok(`${vendor ? `${VENDOR_NAMES[vendor]} logins give` : "A login gives"} way once ${g}% of the long (weekly) window is used, whatever the short one says. ${dim("Below that the weekly window is ignored.")}`);
+        }
+        else if (!vendor) {
             const own = POOL_VENDORS.filter((v) => next.atByVendor[v] !== undefined).map((v) => `${VENDOR_HARNESS[v]} ${next.atByVendor[v]}%`);
             ok(`The pool moves to another login at ${next.at}% used.${own.length > 0 ? dim(` Still their own: ${own.join(", ")}.`) : ""}`);
         }
@@ -795,7 +795,9 @@ async function poolCommand(argv) {
             return 1;
         }
         await savePool(next);
-        ok(`${bold(memberName)} is in the pool as ${describeLogin(login)}.`);
+        const session = await loadConfig();
+        const shown = session?.token ? await registerPoolLogins(session, next) : undefined;
+        ok(`${bold(memberName)} is in the pool as ${describeLogin(login)}.${shown ? dim(" It shows in the console under Subscriptions.") : ""}`);
         return 0;
     }
     if (sub && sub !== "list" && sub !== "ls" && sub !== "--paths") {
@@ -810,9 +812,9 @@ async function poolCommand(argv) {
         say(dim(`No logins in the pool. ${bold("tab pool add claude work")} signs one in; then ${bold("tab claude")} runs as whichever has most room.`));
         return 0;
     }
-    // One read of the accounts for every vendor.
-    const accounts = await flockAccounts(config).catch(() => []);
-    const sections = await Promise.all(vendors.map(async (vendor) => ({ vendor, title: VENDOR_NAMES[vendor], harness: VENDOR_HARNESS[vendor], at: thresholdFor(pool, vendor), standings: await poolStandings(config, vendor, pool.members[vendor], accounts) })));
+    // One round trip: register what this machine is signed in with, and get every account back.
+    const accounts = (await registerPoolLogins(config, pool)) ?? (await flockAccounts(config).catch(() => []));
+    const sections = await Promise.all(vendors.map(async (vendor) => ({ vendor, title: VENDOR_NAMES[vendor], harness: VENDOR_HARNESS[vendor], limits: limitsFor(pool, vendor), standings: await poolStandings(config, vendor, pool.members[vendor], accounts) })));
     say(renderPool(sections, { at: pool.at, swap: pool.swap, paths: argv.includes("--paths") }));
     return 0;
 }
@@ -1042,13 +1044,20 @@ async function managed(command, rest) {
 }
 async function main(argv) {
     const [command, ...rest] = argv;
+    if (command && (rest.includes("--help") || rest.includes("-h"))) {
+        const doc = findTabCommand(command);
+        // `tab claude --help` is Claude's help: everything after an agent's name is the agent's.
+        if (doc && doc.group !== "run")
+            return usage(command);
+    }
     switch (command) {
         case undefined:
         case "-h":
         case "--help":
-        case "help":
-            usage();
-            return command === undefined ? 2 : 0;
+        case "help": {
+            const code = usage(command === "help" ? rest[0] : undefined);
+            return command === undefined ? 2 : code;
+        }
         case "login":
             return login(rest);
         case "logout":

package/dist/codex-home.js

@@ -10,7 +10,7 @@
  *
  * The person's own `~/.codex` is never read or written.
  */
-import { chmod, copyFile, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, readdir, readFile, rename, rm, symlink, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import { passthroughBase } from "./clients.js";
@@ -67,13 +67,57 @@ export async function prepareCodexHome(input) {
         await writeFile(config, codexConfigToml(input.proxyUrl, input.model, input.mode ?? "hosted"), { mode: 0o600 });
     }
     await chmod(config, 0o600);
+    await shareConversations(home, input.userCodexHome ?? path.join(homedir(), ".codex"));
     return home;
 }
+/**
+ * Codex keeps conversations as rollout files under `sessions`. The tab's
+ * home is its own folder (so its config and login never touch `~/.codex`),
+ * which hid every conversation the person already had: `tab codex resume
+ * <id>` answered "no saved session". `sessions` is therefore a link to the
+ * person's own, and anything already recorded under the tab is moved across
+ * first. With no `~/.codex` on the machine there is nothing to share.
+ */
+export async function shareConversations(home, userCodexHome) {
+    if (!(await lstat(userCodexHome).then((s) => s.isDirectory(), () => false)))
+        return "none";
+    const theirs = path.join(userCodexHome, "sessions");
+    const mine = path.join(home, "sessions");
+    if (path.resolve(theirs) === path.resolve(mine))
+        return "already";
+    const state = await lstat(mine).catch(() => undefined);
+    if (state?.isSymbolicLink())
+        return "already";
+    await mkdir(theirs, { recursive: true, mode: 0o700 });
+    if (state?.isDirectory()) {
+        await moveInto(mine, theirs);
+        await rm(mine, { recursive: true, force: true });
+    }
+    await symlink(theirs, mine);
+    return "linked";
+}
+/** Move every file under `from` to the same place under `to`; a file already there is kept. */
+export async function moveInto(from, to) {
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+        const src = path.join(from, entry.name);
+        const dest = path.join(to, entry.name);
+        if (entry.isDirectory()) {
+            await mkdir(dest, { recursive: true, mode: 0o700 });
+            await moveInto(src, dest);
+        }
+        else if (!(await lstat(dest).then(() => true, () => false))) {
+            await rename(src, dest).catch(async () => {
+                // Another volume: copy, then the caller removes the source tree.
+                await copyFile(src, dest);
+            });
+        }
+    }
+}
 /**
  * The ChatGPT login for the tab's Codex home. A login already there (from
  * `codex login` run through `tab codex`) stays. Otherwise the person's own
  * `~/.codex/auth.json` is copied, owner-only: same machine, same person,
- * and `~/.codex` itself is still never written. A leftover API-key auth
+ * and the login and config in `~/.codex` are still never written. A leftover API-key auth
  * file from metered mode is replaced; with nothing to copy, Codex asks the
  * person to sign in and keeps that login in the tab home.
  */

package/dist/help.js

@@ -0,0 +1,105 @@
+/**
+ * `tab help`, drawn from the one command reference (`tab-docs.ts`, generated
+ * from packages/shared): the overview by group, one command in full, the
+ * glossary, and the refusals a call can meet.
+ */
+import { findTabCommand, TAB_COMMAND_GROUPS, TAB_COMMANDS, TAB_ERRORS, TAB_GLOSSARY } from "./tab-docs.js";
+import { bold, cyan, dim, heading, rows, width, yellow } from "./ui.js";
+const DOCS_URL = "https://console.flocktab.com/docs";
+/** Break a paragraph at word boundaries so it fits `cols`, each line after `indent` spaces. */
+export function wrap(text, cols, indent = 0) {
+    const room = Math.max(24, cols - indent);
+    const lines = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (line && width(line) + 1 + width(word) > room) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.map((l) => `${" ".repeat(indent)}${l}`).join("\n");
+}
+const columns = () => Math.min(100, Math.max(60, process.stdout.columns ?? 100));
+export function renderOverview(opts) {
+    const cols = opts.cols ?? columns();
+    const out = [`${heading("tab")} ${dim("- run any AI agent on a FlockTab tab: a hard cap, a kill switch and a record of every call")}`, ""];
+    // One width for the usage column across every group, so the summaries line up.
+    const first = (c) => `tab ${c.overview ?? c.usage[0]}`;
+    const left = Math.min(42, Math.max(...TAB_COMMANDS.map((c) => width(first(c)))));
+    for (const group of TAB_COMMAND_GROUPS) {
+        out.push(bold(group.title));
+        out.push(dim(wrap(group.blurb, cols, 2)));
+        for (const c of TAB_COMMANDS.filter((x) => x.group === group.id)) {
+            const name = first(c);
+            const label = width(name) > left ? `${name.slice(0, left - 1)}…` : name;
+            const text = wrap(c.summary, cols, left + 4).trimStart();
+            out.push(`  ${cyan(label)}${" ".repeat(left - width(label))}  ${text}`);
+        }
+        out.push("");
+    }
+    out.push(`${bold("tab help <command>")}  ${dim("everything about one command: what it does, its options, examples")}`);
+    out.push(`${bold("tab help glossary")}   ${dim("what is what: Agent, tab, kind, hold, unlock, pool, ...")}`);
+    out.push(`${bold("tab help errors")}     ${dim("every refusal a call can meet, and what to do")}`);
+    out.push("");
+    out.push(dim(`Docs ${DOCS_URL}   Config ${opts.configPath}   or FLOCKTAB_PROXY_URL, FLOCKTAB_KEY, FLOCKTAB_UNLOCK`));
+    return out.join("\n");
+}
+export function renderCommand(doc, cols = columns()) {
+    const out = [`${heading(`tab ${doc.name}`)}${doc.aliases?.length ? dim(`  also: ${doc.aliases.join(", ")}`) : ""}`, wrap(doc.summary, cols), ""];
+    out.push(bold("Usage"));
+    for (const u of doc.usage)
+        out.push(`  ${cyan(`tab ${u}`)}`);
+    out.push("");
+    for (const p of doc.details)
+        out.push(wrap(p, cols), "");
+    if (doc.options?.length) {
+        out.push(bold("Options"));
+        const w = Math.max(...doc.options.map((o) => width(o.flag)));
+        for (const o of doc.options)
+            out.push(`  ${yellow(o.flag)}${" ".repeat(w - width(o.flag))}  ${wrap(o.what, cols, w + 4).trimStart()}`);
+        out.push("");
+    }
+    if (doc.examples?.length) {
+        out.push(bold("Examples"));
+        const w = Math.max(...doc.examples.map((e) => width(e.cmd)));
+        for (const e of doc.examples)
+            out.push(`  ${cyan(e.cmd)}${" ".repeat(w - width(e.cmd))}  ${dim(wrap(e.what, cols, w + 4).trimStart())}`);
+        out.push("");
+    }
+    if (doc.see?.length)
+        out.push(dim(`See also: ${doc.see.map((s) => `tab help ${s}`).join(" · ")}`));
+    return out.join("\n").trimEnd();
+}
+export function renderGlossary(cols = columns()) {
+    const out = [heading("What is what"), ""];
+    for (const e of [...TAB_GLOSSARY].sort((a, b) => a.term.replace(/^[^A-Za-z]+/, "").localeCompare(b.term.replace(/^[^A-Za-z]+/, "")))) {
+        out.push(`${bold(e.term)}${e.also?.length ? dim(`  (${e.also.join(", ")})`) : ""}`);
+        out.push(wrap(e.meaning, cols, 2), "");
+    }
+    return out.join("\n").trimEnd();
+}
+export function renderErrors(cols = columns()) {
+    const out = [heading("When a call is refused"), wrap("A refusal always happens before the provider or vendor is reached, and carries an x-flocktab-reason header naming the rule.", cols), ""];
+    for (const e of TAB_ERRORS) {
+        out.push(`${yellow(String(e.status))} ${bold(e.code)}`);
+        out.push(wrap(e.when, cols, 2));
+        out.push(dim(wrap(`Do: ${e.fix}`, cols, 2)), "");
+    }
+    return out.join("\n").trimEnd();
+}
+/** What `tab help [word]` prints, or undefined when the word names nothing. */
+export function renderHelp(word, opts) {
+    if (!word)
+        return renderOverview(opts);
+    if (word === "glossary" || word === "terms")
+        return renderGlossary();
+    if (word === "errors" || word === "error")
+        return renderErrors();
+    const doc = findTabCommand(word);
+    return doc ? renderCommand(doc) : undefined;
+}
+export { rows };

package/dist/logins.js

@@ -73,7 +73,9 @@ export async function localLogin(vendor, opts = {}) {
         if (!entry)
             return undefined;
         const email = str(entry.email);
-        const accountId = str(entry.user_id);
+        // The proxy files Grok calls under the login token's subject, then its user id: read it the same way.
+        const claims = jwtClaims(entry.key);
+        const accountId = str(claims?.sub) ?? str(claims?.user_id) ?? str(entry.user_id);
         return email || accountId ? { ...(email ? { email } : {}), ...(accountId ? { accountId } : {}) } : undefined;
     }
     if (vendor === "kimi") {

package/dist/manage.js

@@ -198,7 +198,7 @@ export async function accounts(config, flags) {
         };
         return table(["vendor", "account", "plan", "/month", "30d at list", "calls", "used", "agents"], list.map((a) => [
             a.vendor,
-            a.label ?? a.email ?? dim(a.id),
+            a.label ?? a.email ?? dim(`account ${(a.externalId ?? a.id).slice(0, 12)}`),
             a.planLabel ?? dim("unknown"),
             a.monthlyCents ? money(a.monthlyCents) : dim("-"),
             money(a.listCents),

package/dist/pool-run.js

@@ -4,29 +4,35 @@
  * another has room, wait for a quiet moment and relaunch into the same
  * conversation as that other login.
  */
-import { pickMember, relaunchArgs, shouldSwap } from "./pool.js";
-const label = (s) => `${s.member.name}${s.email ? ` (${s.email})` : ""}${s.used === undefined ? "" : `, ${Math.round(s.used)}% used`}`;
+import { isOver, pickMember, relaunchArgs, shouldSwap } from "./pool.js";
+const label = (s) => `${s.member.name}${s.email && s.email !== s.member.name ? ` (${s.email})` : ""}${s.used === undefined ? "" : `, ${Math.round(s.used)}% used`}`;
+/** Which limit a login is over, in words. */
+function why(s, limits) {
+    return (s.used ?? 0) >= limits.at ? `is over ${limits.at}%` : `has ${Math.round(s.longUsed ?? 0)}% of its long window used`;
+}
 export async function runPooled(args, deps) {
     const all = await deps.standings();
-    let current = deps.pinned ? all.find((s) => s.member.name === deps.pinned) : pickMember(all, deps.at);
+    let current = deps.pinned ? all.find((s) => s.member.name === deps.pinned) : pickMember(all, deps.limits);
     if (!current) {
         deps.say(deps.pinned ? `No pool member named ${deps.pinned}. See tab pool.` : "The pool is empty. Add a login with tab pool add.");
         return 2;
     }
-    if (!deps.pinned && (current.used ?? 0) >= deps.at)
-        deps.say(`Every login in the pool is over ${deps.at}%. Running as the least used.`);
+    if (!deps.pinned && isOver(current, deps.limits))
+        deps.say(`Every login in the pool is over its limit. Running as the least used.`);
     let launchArgs = args;
     for (;;) {
         deps.say(`Pool: running as ${label(current)}.`);
         const child = deps.start(current, launchArgs);
         let next;
+        let seen = current;
         if (!deps.pinned && deps.swap === "auto") {
             while (await deps.wait(deps.intervalMs ?? 60_000, child.done)) {
                 // A failed look at the console is not a reason to touch a running harness.
                 const now = await deps.standings().catch(() => undefined);
-                const to = now ? shouldSwap(now, deps.at, current.member.name) : undefined;
+                const to = now ? shouldSwap(now, deps.limits, current.member.name) : undefined;
                 if (to && (await deps.idle().catch(() => false))) {
                     next = to;
+                    seen = now?.find((s) => s.member.name === current.member.name) ?? current;
                     child.stop();
                     break;
                 }
@@ -35,7 +41,7 @@ export async function runPooled(args, deps) {
         const code = await child.done;
         if (!next)
             return code;
-        deps.say(`Pool: ${current.member.name} is over ${deps.at}%. Continuing as ${label(next)}; the conversation carries over, the vendor's prompt cache does not.`);
+        deps.say(`Pool: ${current.member.name} ${why(seen, deps.limits)}. Continuing as ${label(next)}; the conversation carries over, the vendor's prompt cache does not.`);
         current = next;
         launchArgs = relaunchArgs(deps.harness, args);
     }

package/dist/pool-view.js

@@ -3,7 +3,7 @@
  * used the vendor last said it is (a bar, then each window with when it
  * resets), and an arrow on the login the next launch would run as.
  */
-import { pickMember } from "./pool.js";
+import { isOver, pickMember, windowMinutes } from "./pool.js";
 import { bold, dim, green, red, table, width, yellow } from "./ui.js";
 const BAR = 10;
 /** "2h 10m", "3d 4h", "12m": how long until a window resets. */
@@ -30,19 +30,15 @@ export function usageBar(pct, at) {
     const filled = Math.min(BAR, Math.max(0, Math.round((pct / 100) * BAR)));
     return `${paint(pct, at)("█".repeat(filled))}${dim("░".repeat(BAR - filled))}`;
 }
-/** `5h` before `7d`: the window that bites soonest comes first. */
-function minutes(window) {
-    const m = /^(\d+)([mhd])$/.exec(window);
-    return m ? Number(m[1]) * (m[2] === "d" ? 1440 : m[2] === "h" ? 60 : 1) : Number.MAX_SAFE_INTEGER;
-}
 /** "claude max 20x" and "pro" as the harness files spell them, in the vendor's capitals. */
 export function planName(plan) {
     if (!plan)
         return undefined;
     return plan.replace(/\b[a-z]/g, (c) => c.toUpperCase()).replace(/\b(\d+)X\b/g, "$1x");
 }
-function windowsLine(windows, at, now) {
-    const live = [...(windows ?? [])].sort((a, b) => minutes(a.window) - minutes(b.window)).filter((w) => !w.resetsAt || new Date(w.resetsAt).getTime() > now.getTime());
+function windowsLine(windows, limits, now) {
+    const sorted = [...(windows ?? [])].sort((a, b) => windowMinutes(a.window) - windowMinutes(b.window));
+    const live = sorted.filter((w) => !w.resetsAt || new Date(w.resetsAt).getTime() > now.getTime());
     if (!windows || windows.length === 0)
         return dim("no call through FlockTab yet");
     if (live.length === 0)
@@ -50,6 +46,8 @@ function windowsLine(windows, at, now) {
     return live
         .map((w) => {
         const left = until(w.resetsAt, now);
+        // The short window is judged by the threshold, the long one by its guard.
+        const at = sorted.length > 1 && w === sorted.at(-1) ? limits.guard : limits.at;
         return `${w.window} ${paint(w.usedPct, at)(`${Math.round(w.usedPct)}%`)}${left ? dim(` resets in ${left}`) : ""}`;
     })
         .join(dim("  ·  "));
@@ -63,11 +61,12 @@ export function renderPool(sections, opts) {
     const loginWidth = Math.max(5, ...all.map((s) => width(s.email ? whoOf(s) : `${whoOf(s)} not signed in`)));
     const planWidth = Math.max(4, ...all.map((s) => width(planName(s.plan) ?? "-")));
     for (const section of sections) {
-        const at = section.at ?? opts.at;
-        const next = pickMember(section.standings, at)?.member.name;
-        const over = section.standings.filter((s) => (s.used ?? 0) >= at).length;
+        const limits = section.limits ?? { at: opts.at, guard: opts.guard ?? 95 };
+        const at = limits.at;
+        const next = pickMember(section.standings, limits)?.member.name;
+        const over = section.standings.filter((s) => isOver(s, limits)).length;
         const count = `${section.standings.length} ${section.standings.length === 1 ? "login" : "logins"}`;
-        out.push(`${bold(section.title)}  ${dim(`${count} · moves at ${at}%${over > 0 ? ` · ${over} over` : ""} · tab ${section.harness}`)}`);
+        out.push(`${bold(section.title)}  ${dim(`${count} · moves at ${at}% · weekly guard ${limits.guard}%${over > 0 ? ` · ${over} over` : ""} · tab ${section.harness}`)}`);
         out.push(table(["", "login".padEnd(loginWidth), "plan".padEnd(planWidth), "used", "", "windows", ...(opts.paths ? ["folder"] : [])], section.standings.map((s) => {
             const who = whoOf(s);
             return [
@@ -76,13 +75,13 @@ export function renderPool(sections, opts) {
                 planName(s.plan) ?? dim("-"),
                 usageBar(s.used, at),
                 s.used === undefined ? dim("   -") : paint(s.used, at)(`${String(Math.round(s.used)).padStart(3)}%`),
-                windowsLine(s.windows, at, now),
+                windowsLine(s.windows, limits, now),
                 ...(opts.paths ? [dim(s.member.dir)] : []),
             ];
         }), { indent: 1 }));
         out.push("");
     }
-    out.push(dim(`${green("→")} runs next. A login over its vendor's threshold gives way to the one with most room${opts.swap === "auto" ? ", also while running when idle" : ", at launch only"}.`));
-    out.push(dim("--as <login> pins one · --no-pool uses your usual login · tab pool at [claude|codex|grok|kimi] <percent> · --paths shows folders"));
+    out.push(dim(`${green("→")} runs next. The short window decides; the weekly one only from its guard up. A login over either gives way to the one with most room${opts.swap === "auto" ? ", also while running when idle" : ", at launch only"}.`));
+    out.push(dim("--as <login> pins one · --no-pool uses your usual login · tab pool at [vendor] [7d] <percent> · --paths shows folders"));
     return out.join("\n");
 }

package/dist/pool.js

@@ -8,12 +8,14 @@
  * threshold and another has room, the harness is relaunched into the same
  * conversation as that other login.
  */
-import { chmod, mkdir, readdir, readFile, symlink, writeFile, lstat } from "node:fs/promises";
+import { chmod, mkdir, readdir, readFile, readlink, symlink, unlink, writeFile, lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { moveInto } from "./codex-home.js";
 import { configDir } from "./config.js";
 export const POOL_VENDORS = ["anthropic", "openai", "xai", "kimi"];
 export const DEFAULT_AT = 80;
+export const DEFAULT_GUARD = 95;
 export function poolPath(env = process.env) {
     return path.join(configDir(env), "pool.json");
 }
@@ -29,22 +31,26 @@ export function poolVendorFor(harness) {
     return undefined;
 }
 export async function loadPool(env = process.env) {
-    const empty = { at: DEFAULT_AT, atByVendor: {}, swap: "auto", members: {} };
+    const empty = { at: DEFAULT_AT, atByVendor: {}, guard: DEFAULT_GUARD, guardByVendor: {}, swap: "auto", members: {} };
     try {
         const raw = JSON.parse(await readFile(poolPath(env), "utf8"));
         const valid = (n) => typeof n === "number" && n >= 1 && n <= 100;
         const at = valid(raw.at) ? raw.at : DEFAULT_AT;
         const members = {};
         const atByVendor = {};
+        const guardByVendor = {};
         for (const vendor of POOL_VENDORS) {
             const own = raw.atByVendor?.[vendor];
             if (valid(own))
                 atByVendor[vendor] = own;
+            const ownGuard = raw.guardByVendor?.[vendor];
+            if (valid(ownGuard))
+                guardByVendor[vendor] = ownGuard;
             const list = raw.members?.[vendor];
             if (Array.isArray(list))
                 members[vendor] = list.filter((m) => typeof m?.name === "string" && typeof m?.dir === "string").map((m) => ({ name: m.name, dir: m.dir }));
         }
-        return { at, atByVendor, swap: raw.swap === "launch" ? "launch" : "auto", members };
+        return { at, atByVendor, guard: valid(raw.guard) ? raw.guard : DEFAULT_GUARD, guardByVendor, swap: raw.swap === "launch" ? "launch" : "auto", members };
     }
     catch {
         return empty;
@@ -61,6 +67,26 @@ export async function savePool(pool, env = process.env) {
 export function thresholdFor(pool, vendor) {
     return pool.atByVendor[vendor] ?? pool.at;
 }
+/** Both limits for one vendor: its own where set, else the shared ones. */
+export function limitsFor(pool, vendor) {
+    return { at: thresholdFor(pool, vendor), guard: pool.guardByVendor[vendor] ?? pool.guard };
+}
+/** Set the weekly guard, shared or one vendor's; `undefined` for a vendor clears its override. */
+export function setGuard(pool, pct, vendor) {
+    if (pct !== undefined && (!Number.isFinite(pct) || pct < 1 || pct > 100))
+        throw new Error("A threshold is a percent from 1 to 100.");
+    if (!vendor) {
+        if (pct === undefined)
+            throw new Error("A threshold is a percent from 1 to 100.");
+        return { ...pool, guard: Math.round(pct) };
+    }
+    const guardByVendor = { ...pool.guardByVendor };
+    if (pct === undefined)
+        delete guardByVendor[vendor];
+    else
+        guardByVendor[vendor] = Math.round(pct);
+    return { ...pool, guardByVendor };
+}
 /** Set the shared threshold, or one vendor's; `undefined` for a vendor clears its override. */
 export function setThreshold(pool, pct, vendor) {
     if (pct !== undefined && (!Number.isFinite(pct) || pct < 1 || pct > 100))
@@ -107,46 +133,97 @@ export function memberEnv(vendor, member) {
 }
 /**
  * Codex, Grok Build and Kimi Code keep conversations in `sessions` inside
- * their home. Members of one vendor link that to one shared folder, so the
- * login that takes over finds the conversation the other was in. A home
+ * their home. Every member links that to one place, so the login that takes
+ * over finds the conversation the other was in. A home
  * that already has its own `sessions` is left as it is.
  */
-export async function prepareSharedSessions(vendor, member, env = process.env) {
+export async function prepareSharedSessions(vendor, member, env = process.env, userHome = homedir()) {
     if (vendor === "anthropic")
         return;
     const home = memberHome(vendor, member);
     const link = path.join(home, "sessions");
-    if (await lstat(link).then(() => true, () => false))
+    const poolShared = path.join(configDir(env), "pool", vendor, ".shared", "sessions");
+    const existing = await lstat(link).catch(() => undefined);
+    const pointsAt = existing?.isSymbolicLink() ? await readlink(link).catch(() => undefined) : undefined;
+    // A folder of its own, or a link somewhere we did not choose, is left alone.
+    if (existing && pointsAt !== poolShared)
+        return;
+    // The person's own conversations where that harness has a home here, so a
+    // pooled launch can resume what was started without the pool; else one
+    // folder shared by this vendor's members.
+    const own = { openai: [".codex"], xai: [".grok"], kimi: [".kimi-code", ".kimi"] }[vendor].map((d) => path.join(userHome, d));
+    let shared = poolShared;
+    for (const dir of own) {
+        if (path.resolve(dir) !== path.resolve(home) && (await lstat(dir).then((s) => s.isDirectory(), () => false))) {
+            shared = path.join(dir, "sessions");
+            break;
+        }
+    }
+    if (existing && shared === poolShared)
         return;
-    const shared = path.join(configDir(env), "pool", vendor, ".shared", "sessions");
     await mkdir(shared, { recursive: true, mode: 0o700 });
     await mkdir(home, { recursive: true, mode: 0o700 });
+    if (existing) {
+        // An earlier link to the pool-only folder: carry its conversations over, then point at the person's own.
+        await moveInto(poolShared, shared).catch(() => undefined);
+        await unlink(link);
+    }
     await symlink(shared, link);
 }
-/** How used an account is: its fullest window that has not reset yet. */
-export function usedPct(quota, now = new Date()) {
-    const live = quota.filter((w) => !w.resetsAt || new Date(w.resetsAt).getTime() > now.getTime());
+/** `5h` is 300 minutes, `7d` 10080; a name that is not a length sorts last. */
+export function windowMinutes(window) {
+    const m = /^(\d+)([mhd])$/.exec(window);
+    return m ? Number(m[1]) * (m[2] === "d" ? 1440 : m[2] === "h" ? 60 : 1) : Number.MAX_SAFE_INTEGER;
+}
+/**
+ * How used an account is. The short window (Claude's 5 hours, Codex's
+ * primary) is the usage: it runs out first and comes back within hours. The
+ * long one (the week) is kept apart as `longUsed`, and only matters once it
+ * is nearly spent. A window past its reset counts as nothing used.
+ */
+export function usage(quota, now = new Date()) {
     if (quota.length === 0)
-        return undefined;
-    return live.reduce((max, w) => Math.max(max, w.usedPct), 0);
+        return {};
+    const sorted = [...quota].sort((x, y) => windowMinutes(x.window) - windowMinutes(y.window));
+    const pct = (w) => (!w.resetsAt || new Date(w.resetsAt).getTime() > now.getTime() ? w.usedPct : 0);
+    const short = sorted[0];
+    const long = sorted.length > 1 ? sorted.at(-1) : undefined;
+    return { used: pct(short), ...(long ? { longUsed: pct(long) } : {}) };
 }
 const room = (s) => s.used ?? 0;
-/** Stay on the current login while it is under the threshold; else the one with most room. */
-export function pickMember(all, at, current) {
+const longRoom = (s) => s.longUsed ?? 0;
+export function isOver(s, limits) {
+    return room(s) >= limits.at || longRoom(s) >= limits.guard;
+}
+/** The vendor refuses every call: a window is fully spent. */
+const spent = (s) => room(s) >= 100 || longRoom(s) >= 100;
+/** Least short-window usage first, in steps of five points; within a step, the emptier week first. */
+function byRoom(a, b) {
+    return Math.floor(room(a) / 5) - Math.floor(room(b) / 5) || longRoom(a) - longRoom(b) || room(a) - room(b);
+}
+/**
+ * Stay on the current login while it is fine; else the login with most
+ * room among those that are fine; and when none is, the least used that the
+ * vendor would still answer, rather than refusing to run.
+ */
+export function pickMember(all, limits, current) {
     if (all.length === 0)
         return undefined;
     const now = all.find((s) => s.member.name === current);
-    if (now && room(now) < at)
+    if (now && !isOver(now, limits))
         return now;
-    return [...all].sort((a, b) => room(a) - room(b))[0];
+    const fine = all.filter((s) => !isOver(s, limits)).sort(byRoom);
+    if (fine.length > 0)
+        return fine[0];
+    return [...all].sort((a, b) => Number(spent(a)) - Number(spent(b)) || byRoom(a, b))[0];
 }
-/** The login to move to, when the current one is over and another has room. */
-export function shouldSwap(all, at, current) {
+/** The login to move to, when the current one is over and another is not. */
+export function shouldSwap(all, limits, current) {
     const now = all.find((s) => s.member.name === current);
-    if (!now || room(now) < at)
+    if (!now || !isOver(now, limits))
         return undefined;
-    const best = pickMember(all, at, current);
-    return best && best.member.name !== current && room(best) < at ? best : undefined;
+    const best = pickMember(all, limits, current);
+    return best && best.member.name !== current && !isOver(best, limits) ? best : undefined;
 }
 /** Arguments that reopen the conversation the previous login was in. */
 export function relaunchArgs(harness, args) {

package/dist/tab-docs.js

@@ -0,0 +1,429 @@
+// GENERATED from packages/shared/src/tab-docs.ts by scripts/sync-docs.mjs. Edit that file, not this one.
+/**
+ * The `tab` CLI, described once. `tab help`, `tab help <command>` and the
+ * console's Docs pages all read this file, so what the terminal says and
+ * what the docs say cannot drift apart.
+ *
+ * Pure data: no imports, nothing from Node or the browser. `apps/tab` ships
+ * to npm on its own, so it carries a generated copy of this file
+ * (`apps/tab/src/tab-docs.ts`, written by `apps/tab/scripts/sync-docs.mjs`);
+ * a test there fails when the copy is stale.
+ */
+export const TAB_COMMAND_GROUPS = [
+    { id: "start", title: "Get started", blurb: "Once per machine, then once per project folder." },
+    { id: "run", title: "Run an agent on the tab", blurb: "Prefix the agent you already use. Its calls are gated, recorded and, on an API-key Agent, charged to the cap." },
+    { id: "agents", title: "Agents, caps and policy", blurb: "Everything the console's Agent page does, from the terminal. Leave the Agent out and the command acts on this folder's." },
+    { id: "subscriptions", title: "Subscriptions and the pool", blurb: "Agents that run on your own Claude, ChatGPT, SuperGrok or Kimi plan, and choosing between several logins of one vendor." },
+    { id: "watch", title: "See what happened", blurb: "Read commands. Add --json to any of them for scripts and agents." },
+    { id: "selfhost", title: "Self-hosted proxy", blurb: "Provider keys stay on your machine; the ledger stays on flocktab.com." },
+    { id: "machine", title: "This machine", blurb: "The CLI itself." },
+];
+export const TAB_COMMANDS = [
+    {
+        name: "login",
+        group: "start",
+        usage: ["login"],
+        summary: "Approve this machine in the console, once.",
+        details: [
+            "Asks whether this machine uses the hosted proxy (proxy.flocktab.com) or a self-hosted one on this machine, then prints a short code and opens the console. Approve the code there and the machine receives its session. Nothing is typed into the terminal except that choice, and no Agent is chosen here.",
+            "Login is per machine. Which Agent a project runs as is per folder: see tab use.",
+            "On a hosted flock with a saved provider key, login also asks for the flock's unlock, checks that it opens the key, and keeps it in the machine's config (owner-only). The unlock is never stored on FlockTab.",
+        ],
+        examples: [{ cmd: "tab login", what: "approve this machine" }],
+        see: ["use", "logout", "status"],
+    },
+    {
+        name: "use",
+        group: "start",
+        usage: ["use"],
+        summary: "Pick or change the Agent this folder runs as.",
+        details: [
+            "Lists the flock's Agents (state, kind, cap) and lets you choose one or make a new one. A new Agent asks for its kind: API key or Subscription. The choice is written to a one-line .flocktab file at the git root (or this folder), and a key for that Agent is minted and kept on this machine.",
+            "Running tab claude or tab codex in a folder with no .flocktab asks the same question, so tab use is only needed to change the answer.",
+            "An Agent that already holds a key on another machine can be used here too, but minting a key here replaces the one there. tab asks before doing it.",
+        ],
+        see: ["agent", "key", "list"],
+    },
+    {
+        name: "claude",
+        overview: "claude | codex | grok | kimi | <cmd>",
+        aliases: ["codex", "grok", "kimi", "gemini", "aider", "cursor", "<command>"],
+        group: "run",
+        usage: ["claude [args]", "codex [args]", "grok [args]", "kimi [args]", "<any command> [args]"],
+        summary: "Run an agent on this folder's tab. Everything after the name goes to the agent untouched.",
+        details: [
+            "tab sets the environment that agent reads (its base URL and key, or for Codex a home folder of its own) and starts it. It does not wrap or parse the agent's traffic; the proxy does the gating.",
+            "On an API-key Agent the agent presents the tab's key, the flock's provider key pays, and every call is held, settled and charged to the cap. A call that would pass the cap is refused before the provider with 402 tab_closed.",
+            "On a Subscription Agent the agent keeps its own login (Claude Max, ChatGPT, SuperGrok, Kimi). The tab key rides in the base URL, the same kill switch and policies apply before the vendor is reached, the call is recorded at list price under the account the vendor names, and nothing is charged to the cap.",
+            "Any other command works too: tab points both the OpenAI and the Anthropic variables at the proxy and runs it. An agent with no consumer plan on a Subscription Agent runs metered on the flock's key, and tab says so.",
+            "With logins in the pool for that vendor, a Subscription Agent runs as the login with most room. See tab pool.",
+        ],
+        options: [
+            { flag: "--as <login>", what: "run as one pool login and never move off it" },
+            { flag: "--no-pool", what: "ignore the pool and use the agent's usual login" },
+            { flag: "--pool", what: "require the pool; fail rather than fall back when it cannot be used" },
+        ],
+        examples: [
+            { cmd: "tab claude", what: "Claude Code on this folder's tab" },
+            { cmd: "tab codex resume <id>", what: "arguments pass straight through; Codex sees the conversations in ~/.codex" },
+            { cmd: "tab claude --as work", what: "pin the pool login named work" },
+            { cmd: "tab python agent.py", what: "any script, with OPENAI_* and ANTHROPIC_* pointed at the tab" },
+        ],
+        see: ["use", "pool", "alias", "log"],
+    },
+    {
+        name: "alias",
+        overview: "alias setup | remove | list",
+        aliases: ["unalias"],
+        group: "run",
+        usage: ["alias setup <name>...", "alias remove <name>...", "alias list"],
+        summary: "Make the plain command (codex) run through the tab (tab codex).",
+        details: [
+            "Writes a small shim named like the agent into ~/.flocktab/bin. With that folder first on your PATH, typing codex runs tab codex. tab removes that folder from the PATH of the agent it starts, so the shim never calls itself.",
+            "tab alias setup prints the PATH line to add to your shell if it is not there yet.",
+        ],
+        examples: [
+            { cmd: "tab alias setup claude codex", what: "plain claude and codex now run on the tab" },
+            { cmd: "tab alias remove codex", what: "undo one" },
+        ],
+    },
+    {
+        name: "agent",
+        overview: "agent create | kind",
+        group: "agents",
+        usage: ["agent create <name> --subscription|--api [--cap <dollars>]", "agent kind <agent> api|subscription"],
+        summary: "Make an Agent of a given kind, or change an Agent's kind.",
+        details: [
+            "An Agent is one named worker with one tab. Its kind is the only thing anyone declares: api means the flock's provider key pays and the cap is the meter; subscription means its agents use your own plan logins and nothing is charged.",
+            "Changing the kind applies to the next launch. tab claude reads it fresh every time.",
+        ],
+        options: [
+            { flag: "--subscription | --api", what: "the kind of the new Agent (api when neither is given)" },
+            { flag: "--cap <dollars>", what: "the new Agent's cap; 50 when left out" },
+        ],
+        examples: [
+            { cmd: "tab agent create billing-api --api --cap 20", what: "a metered Agent with a $20 cap" },
+            { cmd: "tab agent create my-laptop --subscription", what: "an Agent for your own plan logins" },
+            { cmd: "tab agent kind billing-api subscription", what: "switch an existing Agent" },
+        ],
+        see: ["use", "cap", "accounts"],
+    },
+    {
+        name: "list",
+        aliases: ["ls"],
+        group: "agents",
+        usage: ["list"],
+        summary: "Every Agent: kind, state, spent of cap, window, project.",
+        details: ["One row per Agent in the flock. The same list tab use chooses from."],
+        options: [{ flag: "--json", what: "the rows as JSON" }],
+        see: ["status", "live"],
+    },
+    {
+        name: "close",
+        overview: "close | open [agent]",
+        aliases: ["open"],
+        group: "agents",
+        usage: ["close [agent]", "open [agent]"],
+        summary: "The kill switch. Close stops the next call; open lets calls through again.",
+        details: [
+            "Closing a tab takes effect on the next call: it is refused before the provider or vendor with 402 tab_closed. Calls already in flight finish. This works the same on API-key and Subscription Agents.",
+            "A tab that closed itself by reaching its cap reopens by itself when its window rolls over (unless its reopen rule says manual or never), or now with tab open.",
+        ],
+        examples: [
+            { cmd: "tab close", what: "stop this folder's Agent" },
+            { cmd: "tab open billing-api", what: "let a named Agent run again" },
+        ],
+        see: ["cap", "policy"],
+    },
+    {
+        name: "cap",
+        group: "agents",
+        usage: ["cap [agent] <dollars>"],
+        summary: "Set the hard cap and, optionally, its window.",
+        details: [
+            "The cap is a hard dollar limit on one Agent for one window. Before every call the proxy holds an estimate against it; a call whose estimate would pass the cap is refused before the provider. There is no overage.",
+            "The window is how often the spent amount starts again: run, hour, day, week, month or lifetime.",
+        ],
+        options: [{ flag: "--window run|hour|day|week|month|lifetime", what: "when spent starts again" }],
+        examples: [{ cmd: "tab cap 25 --window week", what: "$25 a week for this folder's Agent" }],
+        see: ["close", "policy", "spend"],
+    },
+    {
+        name: "policy",
+        group: "agents",
+        usage: ["policy [agent]", "policy [agent] --velocity N|none --models a,b|none --allow tool,tool|none"],
+        summary: "Show or set the rules checked before every call.",
+        details: [
+            "Checked in this order, first refusal wins: tab state, cap, velocity (calls per minute, 429), model allowlist (403 model_blocked), irreversible tools (403 risk_blocked), per-tool caps (402 tool_cap).",
+            "A tool FlockTab does not know is treated as a write, not a read. Irreversible tools (payments, sending email, deletes, production deploys) are denied unless named in --allow, and even then only while at least $25.00 of the cap remains.",
+        ],
+        options: [
+            { flag: "--velocity N|none", what: "most calls per minute (a new Agent starts at 120)" },
+            { flag: "--models a,b|none", what: "the only models allowed; none allows any" },
+            { flag: "--allow tool,tool|none", what: "irreversible tools this Agent may call" },
+        ],
+        examples: [{ cmd: "tab policy --velocity 60 --models claude-sonnet-5,gpt-5", what: "slow it down and pin its models" }],
+        see: ["cap", "ledger"],
+    },
+    {
+        name: "rename",
+        group: "agents",
+        usage: ["rename <agent> <name>"],
+        summary: "Rename an Agent. Its slug, and so its console URL and .flocktab files, stay.",
+        details: ["The display name changes everywhere. The slug is permanent so folders and links keep working."],
+    },
+    {
+        name: "key",
+        overview: "key rotate [agent]",
+        group: "agents",
+        usage: ["key rotate [agent]"],
+        summary: "Mint a new key for an Agent, kept on this machine. The old one stops working.",
+        details: [
+            "Keys look like ft_live_... and are stored hashed; FlockTab cannot show one again. The old key is refused (401 key_revoked) from the next call, on every machine that still holds it.",
+        ],
+        options: [{ flag: "--show", what: "print the new key once, for a machine without tab" }],
+        see: ["use"],
+    },
+    {
+        name: "project",
+        overview: "project | projects",
+        aliases: ["projects"],
+        group: "agents",
+        usage: ["projects", "projects add <name>", "project [agent] <name>|none"],
+        summary: "Group Agents under a project for chargeback (Team plan and up).",
+        details: [
+            "A project is a label on FlockTab's own meter: what these Agents spent, together. --repo links a GitHub repository so outside spend (Actions, storage) can be attributed to the same project.",
+        ],
+        options: [
+            { flag: "--create", what: "make the project if it does not exist" },
+            { flag: "--repo owner/name", what: "link a GitHub repository" },
+        ],
+        see: ["spend", "outside"],
+    },
+    {
+        name: "archive",
+        group: "agents",
+        usage: ["archive [agent]"],
+        summary: "Close an Agent for good and take it off the bill. Its history stays.",
+        details: ["The tab closes for good, the Agent leaves the lists and stops counting towards the plan's Agents. Its ledger rows stay."],
+        options: [{ flag: "--yes", what: "do not ask" }],
+    },
+    {
+        name: "accounts",
+        aliases: ["quota"],
+        group: "subscriptions",
+        usage: ["accounts"],
+        summary: "Every plan login your Subscription Agents were seen on, and how used it is.",
+        details: [
+            "Accounts are discovered, never typed in: the vendor names the login on every reply, and FlockTab files the call under it. Each row shows the plan, the seat price taken from the plan tier, what the last 30 days would have cost at list price, the number of calls, and the usage the vendor last reported per window.",
+            "The console shows the same under Spend, Subscriptions; a label or a seat price of your own is set under Control, Accounts.",
+        ],
+        see: ["pool", "agent"],
+    },
+    {
+        name: "pool",
+        overview: "pool [add | remove | at | swap]",
+        group: "subscriptions",
+        usage: [
+            "pool",
+            "pool add claude|codex|grok|kimi <name> [--email <address>] [--dir <folder>]",
+            "pool remove claude|codex|grok|kimi <name>",
+            "pool at [claude|codex|grok|kimi] [7d] <percent>|default",
+            "pool swap auto|launch",
+        ],
+        summary: "Several logins of one vendor on this machine; the agent runs as the one with most room.",
+        details: [
+            "A pool member is a folder the agent signs in to itself (CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME, KIMI_CODE_HOME). tab never reads, copies or forwards a login, and neither proxy holds one: tab only chooses which folder a launch uses. pool add opens the vendor's own browser sign-in and finishes by itself. The login then shows in the console under Subscriptions at once, before its first call: tab tells the console the account's id, email and plan tier as the agent's own files state them, never the login itself.",
+            "Usage is what the vendor last reported for that account. The short window (Claude's 5 hours, Codex's primary) decides: at or over the threshold, the login gives way. The long window (the week) is ignored until it reaches its guard, 95% unless set, and then the login gives way whatever the short window says. Between logins within five points of each other, the one with more of its week left goes first. A login never seen through FlockTab counts as unused.",
+            "At launch tab takes the login with most room. While running (swap auto) it looks once a minute; when the login in use is over a limit and another is not, it waits for a quiet moment, stops the agent and starts it again as the other login in the same conversation. The vendor's prompt cache does not carry over, and anything typed but not sent is lost. When every login is over, nothing moves, and at launch the least used still runs.",
+            "Members share your own conversations (~/.claude, ~/.codex, ~/.grok, ~/.kimi-code), so a conversation continues under another login and can be resumed with or without the pool. The pool lives in ~/.flocktab/pool.json on this machine only.",
+        ],
+        options: [
+            { flag: "--email <address>", what: "pool add: prefill the sign-in page (a name that is an email does this by itself)" },
+            { flag: "--dir <folder>", what: "pool add: use a config folder you already have instead of making one" },
+            { flag: "--paths", what: "pool: also show each login's folder" },
+            { flag: "at <percent>", what: "the short-window threshold for every vendor (default 80)" },
+            { flag: "at <vendor> <percent>", what: "one vendor's own threshold; default clears it" },
+            { flag: "at [vendor] 7d <percent>", what: "the weekly guard (default 95)" },
+            { flag: "swap auto|launch", what: "auto also moves a running agent when idle; launch only chooses at start" },
+        ],
+        examples: [
+            { cmd: "tab pool add claude me@example.com", what: "sign a Claude login in; the email is prefilled" },
+            { cmd: "tab pool", what: "every login: plan, usage bar, each window and its reset, and which runs next" },
+            { cmd: "tab pool at claude 70", what: "Claude logins give way at 70% of the 5-hour window" },
+            { cmd: "tab pool at 7d 90", what: "any login gives way once 90% of its week is used" },
+            { cmd: "tab claude --as me@example.com", what: "pin one login for this run" },
+        ],
+        see: ["accounts", "claude"],
+    },
+    {
+        name: "status",
+        group: "watch",
+        usage: ["status"],
+        summary: "Which flock, which Agent this folder runs as, its kind, and whether the proxy answers.",
+        details: ["The first thing to run when something is off. Exit code 0 only when the machine is logged in, the folder has an Agent with a key here, and the proxy is healthy."],
+        see: ["login", "use", "up"],
+    },
+    {
+        name: "log",
+        overview: "log [-f] | log --proxy",
+        aliases: ["logs"],
+        group: "watch",
+        usage: ["log [-f] [--all] [--lines N]", "log --proxy [-f]"],
+        summary: "Everything that went through the tab, one line per call.",
+        details: [
+            "tab log reads the flock's ledger and shows the calls of the Agents keyed on this machine: time, Agent, what was called, tokens in and out, the amount, and the outcome (settled, subscription, refunded, blocked and why). It works the same on hosted and self-hosted.",
+            "tab log --proxy (also tab logs) is the self-hosted proxy's own log on this machine: one line per call with the vendor, model, status, cached tokens and milliseconds. Neither log ever contains a key, a login, a prompt, an email or an IP address.",
+        ],
+        options: [
+            { flag: "-f", what: "follow: keep printing new calls" },
+            { flag: "--all", what: "every Agent in the flock, not only this machine's" },
+            { flag: "--lines N", what: "how many to start with (30)" },
+            { flag: "--proxy", what: "the local proxy's log instead" },
+        ],
+        see: ["ledger", "live"],
+    },
+    {
+        name: "ledger",
+        group: "watch",
+        usage: ["ledger [agent]"],
+        summary: "One row per call, with the hold and what it settled at.",
+        details: [
+            "SETTLED $0.08 of $0.14 held means $0.14 was held before the call and $0.08 was the real cost; the rest went back. REFUNDED means the provider failed and nothing was charged. SUBSCRIPTION is a call on your own plan, priced at list and not charged. BLOCKED names the rule that refused it.",
+        ],
+        options: [
+            { flag: "--limit N", what: "how many rows" },
+            { flag: "--blocked", what: "only refused calls" },
+        ],
+        see: ["log", "spend"],
+    },
+    {
+        name: "spend",
+        group: "watch",
+        usage: ["spend [agent|project|day]"],
+        summary: "What was spent through the tab, and outside it, grouped.",
+        details: ["Meter spend is what went through FlockTab. Outside spend is what the connected billing sources report (Team plan and up), so the two can be told apart."],
+        options: [
+            { flag: "--by agent|project|day", what: "how to group" },
+            { flag: "--since 7d", what: "how far back" },
+            { flag: "--agent <agent>", what: "only one Agent" },
+        ],
+        see: ["outside", "ledger"],
+    },
+    {
+        name: "outside",
+        group: "watch",
+        usage: ["outside"],
+        summary: "The outside-spend connections and their totals per project.",
+        details: ["Connections are made in the console (Control, Outside spend): provider admin APIs and cloud billing. They answer whether a dollar went through a tab or around it."],
+        see: ["spend", "project"],
+    },
+    {
+        name: "live",
+        group: "watch",
+        usage: ["live"],
+        summary: "Who is working right now.",
+        details: ["Each Agent's pulse (working, recent, idle, stopped), calls per minute and last decision."],
+        options: [{ flag: "--watch N", what: "refresh every N seconds" }],
+    },
+    {
+        name: "web",
+        group: "watch",
+        usage: ["web [agent]"],
+        summary: "Open the Agent's page in the console.",
+        details: ["Opens this folder's Agent when none is named."],
+    },
+    {
+        name: "up",
+        overview: "up | down",
+        aliases: ["down"],
+        group: "selfhost",
+        usage: ["up", "down"],
+        summary: "Start or stop the self-hosted proxy on this machine.",
+        details: [
+            "The self-hosted proxy is one binary (flocktab-proxy). Your provider keys live in ~/.flocktab/proxy.env on this machine, owner-only, and never reach FlockTab. The proxy asks flocktab.com to hold, settle or refund each call with the Agent's own key, so caps, policies, the kill switch and the ledger work exactly as on hosted.",
+            "tab up asks for provider keys the first time (typed without echo), starts the proxy on 127.0.0.1:8787 and waits until it answers. tab claude on a self-hosted machine starts it by itself when it is down.",
+            "tab down stops the proxy that tab started. Anything running through it is cut, so stop your agents first.",
+        ],
+        see: ["log", "update", "status"],
+    },
+    {
+        name: "update",
+        aliases: ["upgrade"],
+        group: "machine",
+        usage: ["update"],
+        summary: "Install the newest tab from npm, and with it the newest proxy.",
+        details: ["Restarts a self-hosted proxy that was running, so it runs the new version. Stop your agents first on a self-hosted machine."],
+        see: ["version"],
+    },
+    {
+        name: "version",
+        group: "machine",
+        usage: ["version"],
+        summary: "The versions of tab and of the proxy it carries.",
+        details: ["A proxy that is older than tab can miss features; tab says so when it notices."],
+    },
+    {
+        name: "logout",
+        group: "machine",
+        usage: ["logout"],
+        summary: "Forget this machine's session and Agent keys.",
+        details: ["Removes ~/.flocktab/config.json. The pool, the proxy's provider keys and each folder's .flocktab are left alone. The Agents and their history are untouched on FlockTab."],
+        see: ["login"],
+    },
+];
+/** What is what. Alphabetical in the docs; grouped by subject here. */
+export const TAB_GLOSSARY = [
+    { term: "Flock", meaning: "Your workspace: many Agents, one plan, one ledger. Each console login has its own." },
+    { term: "Agent", meaning: "One named worker, such as billing-api or my-laptop. It has exactly one tab, one kind, and its own keys, policies and history. Plans count Agents." },
+    { term: "Tab", meaning: "An Agent's spend account: a hard dollar cap, a window, and a state, open or closed. Closing the tab is the kill switch." },
+    { term: "Kind", also: ["api", "subscription"], meaning: "What pays for an Agent's tokens. api: the flock's provider key, every call charged to the cap. subscription: your own plan login, gated and recorded but never charged. Chosen when the Agent is made; it can be changed." },
+    { term: "Cap", meaning: "The most an Agent may spend in one window, in dollars. Hard: a call that would pass it is refused before the provider. There is no overage." },
+    { term: "Window", meaning: "How often a tab's spent amount starts again: run, hour, day, week, month or lifetime." },
+    { term: "Hold", also: ["reserve"], meaning: "Before each call the proxy estimates its cost and holds that against the cap. If the hold does not fit, the call is refused and the provider is never reached." },
+    { term: "Settle", also: ["commit"], meaning: "After the provider answers, the hold is replaced by the real cost from the provider's own token counts, and the rest goes back to the cap." },
+    { term: "Refund", meaning: "The provider failed (any non-2xx): the hold is released and nothing is charged. Only a successful call is ever charged." },
+    { term: "Shadow row", also: ["subscription call"], meaning: "The record of a call made on your own plan: the same row as a metered call, priced at list from the vendor's token counts, filed under the account, and never added to the tab's spent amount." },
+    { term: "List price", meaning: "What a call would have cost through the API at the vendor's published rates, with cached input priced at its discount. It is how a plan's worth is stated; nobody is charged it." },
+    { term: "Kill switch", meaning: "Closing a tab. It applies to the next call, on API-key and Subscription Agents alike, before the provider or vendor is reached. Close all tabs does it for the whole flock." },
+    { term: "Policy", meaning: "The rules checked before every call, first refusal wins: tab state, cap, velocity, model allowlist, irreversible tools, per-tool caps." },
+    { term: "Velocity", meaning: "The most calls per minute an Agent may make. Over it, calls are refused with 429 until the minute passes. A new Agent starts at 120." },
+    { term: "Irreversible tool", meaning: "A tool whose effect cannot be undone: payments, sending email, deletes, production deploys. Denied unless the Agent's policy names it, and then only while at least $25.00 of the cap remains. A tool FlockTab does not know counts as a write." },
+    { term: "Virtual key", also: ["tab key", "ft_live_"], meaning: "The key an agent presents to the proxy: ft_live_... (or ft_test_...). It names the Agent. It is stored hashed and shown once. It is not a provider key and is worth nothing at a provider." },
+    { term: "Provider key", also: ["BYOK"], meaning: "Your own OpenAI, Anthropic or other API key. You pay the provider directly; FlockTab takes no cut. Hosted: saved encrypted, opened only by your unlock. Self-hosted: it never leaves your machine." },
+    { term: "Unlock", meaning: "A secret of yours that opens the flock's saved provider key for the length of one call. It is never stored on FlockTab. Agents send it inside the key (ft_live_<secret>.<unlock>) or as the x-flocktab-unlock header. Without it a hosted call fails closed." },
+    { term: "Proxy", meaning: "What agents talk to instead of the provider. It checks the tab and the policies, holds, forwards, and settles. Hosted at proxy.flocktab.com, or self-hosted on your machine." },
+    { term: "Hosted", meaning: "Agents talk to proxy.flocktab.com, which opens your saved provider key with your unlock for each call. Nothing to run." },
+    { term: "Self-hosted", meaning: "Agents talk to a proxy on your own machine (tab up). Provider keys stay in a file there; only the hold, settle and refund requests, with token counts, go to flocktab.com." },
+    { term: "Control plane", meaning: "The part of flocktab.com a self-hosted proxy settles through: identity, reserve, commit, refund, and for subscriptions the account and its quota." },
+    { term: "Passthrough", meaning: "How a Subscription Agent's calls travel: /t/<tab key>/<vendor>/... on either proxy. The agent's own login is forwarded untouched; FlockTab adds nothing to the request and keeps no copy of the login." },
+    { term: "Account", also: ["vendor account", "subscription"], meaning: "One plan login (a Claude Max, ChatGPT, SuperGrok or Kimi account) as the vendor named it on the wire. Discovered on first sight, with its plan tier, seat price and reported usage. Nobody types one in." },
+    { term: "Quota window", also: ["5h", "7d"], meaning: "A vendor's own usage limit over a period, reported on every reply: Claude's 5-hour and 7-day windows, Codex's primary and secondary. FlockTab keeps the latest figure and its reset time per account." },
+    { term: "Pool", meaning: "Several logins of one vendor on one machine, and tab choosing between them by reported usage. Each member is a folder the agent signs in to itself." },
+    { term: "Threshold", meaning: "In the pool: the share of the short window at which a login gives way to one with more room. 80% unless set, per vendor if you like." },
+    { term: "Weekly guard", meaning: "In the pool: the share of the long window from which a login gives way whatever its short window says. 95% unless set. Below it the weekly window is ignored." },
+    { term: "Account switch", meaning: "An Agent's call landing on a different account of the same vendor than its previous one: a new login mid-session, another machine, or the pool moving. Shown on the Agent's page and under Accounts." },
+    { term: "Project", meaning: "A label grouping Agents for chargeback on FlockTab's own meter, optionally linked to a GitHub repository. Team plan and up." },
+    { term: "Outside spend", meaning: "Money that did not go through a tab, read from provider admin APIs and cloud billing, so it can be told apart from metered spend. Team plan and up." },
+    { term: "Ledger", meaning: "Every decision, one row per call: allowed, settled, refunded, blocked and why. Money is whole cents, never a fraction. If the ledger cannot be reached, no call goes out." },
+    { term: "Fail closed", meaning: "When FlockTab cannot be sure a call fits (the ledger is down, the key is unknown, the unlock is missing) the call is refused rather than let through." },
+    { term: "Harness", meaning: "The coding agent you run: Claude Code, Codex, Grok Build, Kimi Code, or any command. tab calls them agents in its output." },
+    { term: ".flocktab", meaning: "A one-line file at a project's root naming the Agent that folder runs as. Safe to commit: it holds no key." },
+    { term: "~/.flocktab", meaning: "This machine's tab folder: the session and Agent keys (config.json), the pool (pool.json), the self-hosted proxy's keys, log and binary, and the alias shims. Owner-only." },
+];
+/** Every refusal the proxy can answer with, for the docs and for `tab help errors`. */
+export const TAB_ERRORS = [
+    { status: 402, code: "tab_closed", when: "The tab is closed, or the call's estimate would pass the cap.", fix: "tab open, raise the cap with tab cap, or wait for the window to roll over." },
+    { status: 402, code: "tool_cap", when: "A per-tool cap is reached.", fix: "Raise that tool's cap in the console." },
+    { status: 403, code: "risk_blocked", when: "An irreversible tool that the Agent's policy does not allow, or less than $25.00 of the cap remains.", fix: "tab policy --allow <tool>, and leave room under the cap." },
+    { status: 403, code: "model_blocked", when: "The model is not on the Agent's allowlist.", fix: "tab policy --models ..., or none to allow any." },
+    { status: 403, code: "agent_frozen", when: "The Agent was frozen from the console.", fix: "Frozen by FlockTab support or an admin rule; write to support." },
+    { status: 403, code: "not_subscription", when: "A passthrough (/t/...) call for an API-key Agent.", fix: "tab agent kind <agent> subscription, or run it metered." },
+    { status: 429, code: "velocity", when: "More calls this minute than the policy allows.", fix: "Wait, or tab policy --velocity N." },
+    { status: 401, code: "key_revoked", when: "The key is unknown, rotated or missing.", fix: "tab key rotate mints a fresh one on this machine." },
+    { status: 503, code: "ledger_unavailable", when: "FlockTab could not reach its ledger. Nothing was sent to the provider.", fix: "Retry. This is fail closed on purpose." },
+];
+export function findTabCommand(word) {
+    const w = word.trim().toLowerCase();
+    return TAB_COMMANDS.find((c) => c.name === w || c.aliases?.includes(w));
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Written by scripts/write-version.mjs from package.json at build; `tab version` prints it. */
-export const TAB_VERSION = "0.1.12";
+export const TAB_VERSION = "0.1.13";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamorilabs/tab",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "node scripts/write-version.mjs && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "build": "node scripts/write-version.mjs && node scripts/sync-docs.mjs && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",