@hanamorilabs/tab 0.1.11 → 0.1.13

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.11";
+export const TAB_VERSION = "0.1.13";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamorilabs/tab",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
   "license": "MIT",
   "type": "module",
@@ -15,18 +15,18 @@
     "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",
     "prepublishOnly": "pnpm build"
   },
   "optionalDependencies": {
-    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.7",
-    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.7",
-    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.7",
-    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.7",
-    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.7"
+    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.8",
+    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.8",
+    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.8",
+    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.8",
+    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.8"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",