@oalo-ai/cli 0.0.0-stage → 0.1.0

package/src/help.js

@@ -0,0 +1,920 @@
+/**
+ * One registry drives every form of help: the overview, per-command detail, and
+ * the JSON form an agent can parse. One source so they can't drift, for the
+ * same reason typegen reads the manifest instead of hardcoding a schema.
+ */
+
+export const TAGLINE = "wire a local app into your OALO workspace";
+
+export const TOKENS = [
+  {
+    kind: "sync",
+    where: "`oalo login` (read-only), dashboard -> Account -> CLI & agents, or dashboard -> Sync API for an app's own servers",
+    plane: "data (/api/sync/v1)",
+    usedBy: ["typegen", "data"],
+    warning:
+      "Server-side only. Carries no end-user identity, so it reads and writes EVERY member's rows. Never ship one inside a mobile or web app.",
+  },
+  {
+    kind: "cli",
+    where: "`oalo login`, or dashboard -> Account -> CLI & agents",
+    plane: "control (the build surface)",
+    usedBy: ["whoami", "tail", "call", "run", "emit", "data", "tokens", "docs", "apps", "deploy", "env", "logs", "secrets", "loops", "flows", "pull", "status", "lint", "push", "qa", "rehearse", "bots", "sources", "mcp"],
+    warning: "Acts as you, with exactly your permissions. No read-only mode. Treat it like a password.",
+  },
+];
+
+export const COMMANDS = [
+  {
+    name: "login",
+    summary: "Connect this machine to a workspace by approving it in the browser.",
+    usage: ['oalo login <workspace> [--name "<this machine>"] [--no-browser]', "oalo login --server <url>"],
+    flags: [
+      { flag: "--server <url>", desc: "Workspace URL, e.g. https://acme.oalo.ai. Defaults to OALO_URL or the linked project." },
+      { flag: "--name <name>", desc: "What the connection is called in the dashboard. Default: this machine's hostname." },
+      { flag: "--no-browser", desc: "Print the approval URL without opening it (for a remote shell)." },
+    ],
+    notes: [
+      "Opens the dashboard on Account -> CLI & agents with a code. Approve it there (check the code matches) and the CLI saves a CLI token plus a read-only data token.",
+      "Saved to ~/.oalo/credentials.json (mode 0600), by workspace URL, never in a project. Every command, oalo mcp included, finds them there.",
+      "The code lasts 10 minutes. Nothing is created until you approve.",
+    ],
+    exits: { 0: "connected", 1: "denied, expired or unreachable", 2: "missing --server" },
+  },
+  {
+    name: "logout",
+    summary: "Revoke this machine's connection and forget its saved tokens.",
+    usage: ["oalo logout [--server <url>]"],
+    flags: [{ flag: "--server <url>", desc: "Workspace URL. Defaults to OALO_URL or the linked project." }],
+    notes: ["Revokes the connection on the server when it was made by oalo login, then removes every saved token for that workspace."],
+    exits: { 0: "done", 2: "missing --server" },
+  },
+  {
+    name: "whoami",
+    summary: "Show the workspace, person and connection this machine uses, and check its tokens.",
+    usage: ["oalo whoami [--json]"],
+    flags: [{ flag: "--json", desc: "Print everything as JSON." }],
+    notes: [
+      "Checks the CLI token by connecting and the data token by reading the manifest, so it tells you which one is the problem when a command is refused.",
+      "Also shows the workspace's API version and features, and says when this CLI is too old for it.",
+    ],
+    exits: { 0: "connected and both checks passed", 1: "a token failed, or the workspace is unreachable", 2: "not connected" },
+  },
+  {
+    name: "link",
+    summary: "Point this project at a workspace and save credentials.",
+    usage: [
+      "oalo link --server <url> [--token <sync token>] [--cli-token <token>] [--app <slug>] [--env dev|prod] [--no-skill]",
+      "oalo link --status",
+    ],
+    flags: [
+      { flag: "--server <url>", desc: "Workspace URL, e.g. https://acme.oalo.ai" },
+      { flag: "--token <token>", desc: "Sync token (data plane). Not needed after oalo login, which saved one." },
+      { flag: "--cli-token <token>", desc: "CLI token (control plane), for tail and mcp. Optional." },
+      { flag: "--app <slug>", desc: "The app that deploy, env, logs, secrets and dockerfile use when you don't pass --app (`oalo apps` lists them). `oalo deploy --new` sets it." },
+      { flag: "--env dev|prod", desc: "Which schema later commands touch. Default dev." },
+      { flag: "--status", desc: "Show the current link and re-check reachability." },
+      { flag: "--no-skill", desc: "Don't install or refresh the OALO skill for coding agents (see `oalo skill`)." },
+    ],
+    notes: [
+      "Every token is verified against the thing it is for BEFORE anything is saved, so a bad or mixed-up token fails here rather than later.",
+      "Writes .oalo/config.json (safe to commit) and ~/.oalo/credentials.json (mode 0600, never in the project). OALO_HOME relocates the credential store.",
+      "Also installs the OALO skill for coding agents (.claude/skills/oalo/SKILL.md), or refreshes it, from this CLI version; an AGENTS.md section from `oalo skill --agents` is refreshed too.",
+    ],
+    exits: { 0: "linked", 1: "verification failed", 2: "missing or invalid arguments" },
+  },
+  {
+    name: "typegen",
+    summary: "Generate TypeScript bindings from the workspace's own schema: its models, and the workflows apps can call.",
+    usage: ["oalo typegen [--out <file>] [--check]", "oalo typegen --dart [--out <project dir>] [--check]"],
+    flags: [
+      { flag: "--out <file>", desc: "Output path. Default oalo.generated.ts. With --dart, the Flutter project's root (default the current folder)." },
+      { flag: "--dart", desc: "For a Flutter app from Oalo's template: write lib/sync/generated and lib/models (the Base's own Dart generator, the one the box uses), and .oalo/dart-defines.json with the Base's address, the linked app's slug and the env, for `flutter run --dart-define-from-file=.oalo/dart-defines.json`." },
+      { flag: "--check", desc: "Do not write; exit non-zero if the file is stale or missing. For CI." },
+    ],
+    notes: [
+      "Commit the output. Document interfaces are OPEN: the manifest describes some fields and rows may carry more, so undeclared keys stay reachable.",
+      "A table-scoped token generates only the tables it can read.",
+      "--dart files are the same ones the box writes after a model changes; run it again after `oalo data models create`. Commit them.",
+      "The env is stamped in the header: dev and prod are separate schemas.",
+      "Workflows with an api trigger get <Name>Input and <Name>Output types and runWorkflow(name, input, {contact, wait}), which calls POST /api/workflows/v1/<name>/run from the app's server with OALO_URL and OALO_SYNC_TOKEN. A preview's token runs it as a test: dev data, outside actions simulated. --check fails when a workflow's input or output changes too.",
+      "Every file also gets createChatSession(bot, user), for the chat widget signed in as your app's user: the endpoint in the widget's data-user-url answers with it (see `oalo docs chat-widget`).",
+      "And verifyOaloToolCall(req), which an endpoint declared as a bot tool in .oalo/app.json uses to check a call came from Oalo and for which user (see `oalo docs app-tools`).",
+      "And the workspace's products: PRODUCTS, the ProductId type and isProductId() (Dart: the Products class and allProductIds). Use them wherever code names a product. --check fails when one is added or archived.",
+    ],
+    exits: { 0: "written, or up to date under --check", 1: "stale, missing, or fetch failed", 2: "not linked" },
+  },
+  {
+    name: "tail",
+    summary: "Watch loop runs, jobs, builds and activity as they happen.",
+    usage: ["oalo tail [--filter <text>] [--json] [--all]"],
+    flags: [
+      { flag: "--filter <text>", desc: "Only events whose name or payload contains this text." },
+      { flag: "--json", desc: "One JSON object per line. Pipes into jq." },
+      { flag: "--all", desc: "Include high-frequency streaming chunk events." },
+    ],
+    notes: [
+      "Answers 'I did a thing, did the expected thing happen?'. A flow that never fired shows as silence.",
+      "Does NOT show direct Sync REST writes (they do not broadcast); you see their consequences.",
+      "Events go to stdout, the banner to stderr, so grep and jq both behave. Runs until interrupted.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "stopped cleanly", 1: "could not connect", 2: "no CLI token" },
+  },
+  {
+    name: "call",
+    summary: "Call any build-surface event directly. The escape hatch.",
+    usage: ["oalo call <event> ['<json params>']", "oalo call --list [text] [--json]"],
+    flags: [
+      { flag: "--list [text]", desc: "List the events you can call, from the workspace. With text, the matching events and the params each accepts." },
+      { flag: "--namespaces", desc: "The events you may call, counted per namespace (what `--list` with no text shows)." },
+      { flag: "--compact", desc: "Print the reply as one line of JSON." },
+    ],
+    notes: [
+      "The build surface has ~500 events. First-class commands cover the common ones; this reaches the rest without a command per feature.",
+      "Params are a JSON object. Org and user identity come from your token, never the params, so a call cannot exceed what you can do.",
+      "--list comes from the server's own handlers and is filtered to what you may call, so it never goes stale. On an older workspace it falls back to a list of namespaces.",
+      "An unknown event returns a clean error naming what you sent. An event that exists but gets the wrong params says which params it takes.",
+      "Example: oalo call loops:run_now '{\"name\":\"Nurture\"}'",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "the call succeeded", 1: "the call failed or was rejected", 2: "bad arguments or no token" },
+  },
+  {
+    name: "run",
+    summary: "Fire a loop, or send a bot a test message, and watch what happens.",
+    usage: ['oalo run loop <name> [--env dev|prod] [--watch]', 'oalo run bot <id> "<message>"'],
+    flags: [
+      { flag: "--watch", desc: "Stream events after firing. Default on for bots." },
+      { flag: "--timeout <s>", desc: "How long to watch. Default 30." },
+      { flag: "--env dev|prod", desc: "Which schema the loop runs against." },
+      { flag: "--app <slug>", desc: "Only for a loop pinned to one app: that app's slug (`oalo apps`) or id. Loops are org-wide by default." },
+    ],
+    notes: [
+      "IMPORTANT: `run loop` fires the loop DIRECTLY and does NOT exercise its trigger binding. Triggers come from the event bus (a real form submission, a real inbound message). So this proves the loop body works; to test that its trigger is wired, use `oalo emit`.",
+      "bot ids accept an integer, a numeric string, or a public bot_ id.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "ran, or watch window elapsed", 1: "the run failed to start", 2: "bad arguments or no token" },
+  },
+  {
+    name: "emit",
+    summary: "Fire a domain event (form.submitted, order.created, ...) to test a loop's trigger.",
+    usage: ["oalo emit <event type> [--payload '<json>'] [--contact <id>] [--dry-run] [--json]", "oalo emit --list [--json]"],
+    flags: [
+      { flag: "--payload <json>", desc: "The event's payload, a JSON object. `oalo emit --list` shows each event's fields." },
+      { flag: "--contact <id>", desc: "An existing contact the event is about. Never creates one." },
+      { flag: "--dry-run", desc: "List the loops it would fire, and emit nothing." },
+      { flag: "--list", desc: "Every event a trigger can listen for, with its payload fields and the loops listening now." },
+      { flag: "--json", desc: "Print the reply as JSON." },
+    ],
+    notes: [
+      "`oalo run loop` fires a loop directly and skips its trigger. emit goes through the real event bus, so it tests the trigger and its payload filter too.",
+      "The loops it fires do real things: send email or WhatsApp, mark invoices paid. Run --dry-run first.",
+      "Admins and members with Developer access only (an admin turns it on under Team). Events are tagged as coming from the CLI and posted to the team feed.",
+      "The type must be one a trigger can listen for; a typo gets a suggestion instead of vanishing.",
+    ],
+    exits: { 0: "emitted (or dry run done)", 1: "refused or failed", 2: "bad arguments or no token" },
+  },
+  {
+    name: "data",
+    summary: "Models and rows in this workspace: list, read, push (bulk upsert), delete, watch, promote, and make tables searchable by bots.",
+    usage: [
+      "oalo data models [--json]",
+      "oalo data models create <name> --field name:type [--field ...] [--owned-by <field>]",
+      "oalo data list <table> [--since N] [--limit N] [--include-deleted] [--json]",
+      "oalo data get <table> <id> [--json]",
+      "oalo data push <table> <file.csv|.json|.jsonl> [--id-field id] [--format csv|json|jsonl] [--types] [--from N] [--new-ids] [--dry-run] [--json]",
+      "oalo data delete <table> <id>",
+      "oalo data watch <table> [--since N] [--json]",
+      "oalo data promote <table>",
+      "oalo data routes [--json]",
+      "oalo data events <table> created [updated] | --off",
+      "oalo data vectorize <table> [--fields a,b] [--where '<field> in a,b'] [--describe '<text>'] [--id <column>] [--json]",
+      "oalo data vectorize <table> --off",
+      "oalo data keep-from-ai <table> [<field,...>] [--off] [--json]",
+    ],
+    flags: [
+      { flag: "--env dev|prod", desc: "Which schema. Default: the project's link, else dev. Writing to prod needs --env prod on the command line." },
+      { flag: "--since N", desc: "list, watch: only rows changed after this sequence number." },
+      { flag: "--limit N", desc: "list: how many rows (the server caps it)." },
+      { flag: "--order seqnum|-seqnum", desc: "list: oldest change first (the default), or newest first." },
+      { flag: "--include-deleted", desc: "list: include deleted rows." },
+      { flag: "--format csv|json|jsonl", desc: "push: the file's format, when its extension doesn't say." },
+      { flag: "--field name:type", desc: "models create: a field. Repeat it, or comma-separate. Types: string text integer float boolean datetime date json list references:<table>." },
+      { flag: "--owned-by <field>", desc: "models create: rows belong to the app user in this field (each member sees only their own). Without it the model is shared." },
+      { flag: "--id-field <name>", desc: "push: which field holds each record's id (default id). Re-sending a record updates it." },
+      { flag: "--types", desc: "push, CSV only: turn plain numbers, true/false and empty cells into numbers, booleans and null. Off by default so ids like 007 stay text." },
+      { flag: "--from N", desc: "push: skip the first N records, to resume a push that stopped." },
+      { flag: "--new-ids", desc: "push: let the server make ids for records without one. A re-send then adds copies." },
+      { flag: "--dry-run", desc: "push: parse, check the model exists, show the first row, write nothing." },
+      { flag: "--fields a,b", desc: "vectorize: the fields (a model's) or columns (a plain table's) whose text bots search. Turns it on, and embeds the existing rows." },
+      { flag: "--where <filter>", desc: "vectorize, models only: embed only matching rows. `status in active,draft`, `status not in archived`, `status = active`, `status != archived`, `cover present`, `cover absent`." },
+      { flag: "--describe <text>", desc: "vectorize: what the table holds. Bots see its first 120 characters when deciding what to search." },
+      { flag: "--id <column>", desc: "vectorize, plain tables: the unique column each row is keyed by (default id)." },
+      { flag: "--off", desc: "events, vectorize: turn it off. keep-from-ai: take the named fields off the list, or all of them when none are named." },
+      { flag: "--json", desc: "Print the reply as JSON." },
+    ],
+    notes: [
+      "dev is a sandbox; live apps read prod. Push to dev, check it, then `oalo data promote <table>` copies dev rows to prod.",
+      "Reads use the saved data token (read-only). Row writes use a write token limited to the tables written, made as you over the CLI token the first time you write a table and saved beside it (`oalo tokens list` shows it; it expires in 30 days).",
+      "models create and promote run as you over the CLI token, so they follow your dashboard access.",
+      "push sends up to 1,000 rows per request, waits out the rate limit (120 writes a minute), retries network errors, and lists rows the server rejected.",
+      "Every write syncs to apps on that schema at once. A delete marks the row deleted; it leaves synced apps.",
+      "The exact contract: `oalo data routes`, or the OpenAPI spec at <workspace>/api/docs.",
+      "vectorize works on an Oalo model (both schemas) or a table the app made (the --env schema). With no flags it shows the status: fields, filter, rows embedded. New and edited rows are embedded within 15 minutes, whoever writes them. Then attach it to a bot with `oalo bots knowledge <bot> --add <table>`.",
+      "vectorize sends the text of the chosen fields to the embedding provider (Voyage); a bot's answer sends the rows its search finds to its AI model. Leave out fields that shouldn't leave Oalo.",
+      "keep-from-ai names fields a bot's data tools (data_search, data_related, table_search, search) leave out of what they hand its AI model, and that can't be embedded. They're still stored, synced to your apps, and read by workflows. A field that's embedded now has to be vectorized away first. With no fields, the list.",
+    ],
+    exits: { 0: "done", 1: "failed, or some rows were rejected", 2: "bad arguments or no token" },
+  },
+  {
+    name: "incidents",
+    summary: "A live app's outages and restart bursts, as Oalo's uptime check saw them, newest first.",
+    usage: ["oalo incidents [--app <slug>] [--all] [--json]"],
+    flags: [
+      { flag: "--app <slug>", desc: "The app. Default: the one saved with `oalo link --app`." },
+      { flag: "--all", desc: "Show the details of closed incidents too (open ones always show them)." },
+      { flag: "--json", desc: "The reply as JSON." },
+    ],
+    notes: [
+      "Oalo checks each live server app every minute: its port answers (and .oalo/app.json's health path, when set), and how often Docker restarted its processes. An incident opens after 3 failed checks in a row, or 3 restarts in 10 minutes; it closes after 2 good checks.",
+      "Each one says what was seen: which process, how many restarts, a memory kill with the size and the fix, the exit code, and the last log lines. The workspace is told in the dashboard's bell and by email (each person can turn that off under Notifications).",
+    ],
+    exits: { 0: "no open incident", 1: "an incident is open, or the request failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "db",
+    summary: "All of an env's data as plain SQL (every app's own tables and the Oalo models), to keep a copy or take it anywhere.",
+    usage: ["oalo db dump [--env dev|prod] [--out <file.sql>] [--force]"],
+    flags: [
+      { flag: "--env dev|prod", desc: "Which env's data. Default prod." },
+      { flag: "--out <file.sql>", desc: "Where to write it. Default <workspace>-<env>-<date>.sql here." },
+      { flag: "--force", desc: "Replace the file if it exists." },
+    ],
+    notes: [
+      "Workspace admins only: it holds every member's data. Restore it into any Postgres with psql -f.",
+      "Your code is in git (oalo deploy --pull); this is the data. Together they are everything you need to run your apps elsewhere.",
+    ],
+    exits: { 0: "a whole dump was written", 1: "refused, unreachable, or cut off (the partial file is removed)", 2: "bad arguments, the file exists, or no CLI token" },
+  },
+  {
+    name: "metrics",
+    summary: "A number from the workspace's data: count, sum or average over a model's rows, events or contacts, grouped or over time.",
+    usage: [
+      "oalo metrics <model | events | contacts> [--sum|--avg|--min|--max|--distinct <field>] [--by <field>] [--every day|week|month] [--days N] [--where <filter>] [--json]",
+    ],
+    flags: [
+      { flag: "--sum <field>", desc: "The sum of a number field. Also --avg, --min, --max, and --distinct (how many different values). Default: count the rows." },
+      { flag: "--avg <field>", desc: "The average of a number field." },
+      { flag: "--min <field>", desc: "The lowest value of a number field." },
+      { flag: "--max <field>", desc: "The highest value of a number field." },
+      { flag: "--distinct <field>", desc: "How many different values a field has." },
+      { flag: "--by <field>", desc: "Group by a field, largest first. Contacts group by status, source or custom_fields.<name>." },
+      { flag: "--every <day|week|month>", desc: "Over time, one row per day, week or month." },
+      { flag: "--days N", desc: "The window, ending now. Default: all time." },
+      { flag: "--where <filter>", desc: 'Only matching rows: "status = paid and total > 100". Also !=, >=, <, <=, ~ (contains), in a,b, present, absent.' },
+      { flag: "--event <type>", desc: "events: one type, like order.created. Default: every type." },
+      { flag: "--time <created|changed|field>", desc: "A model row counts at when it was created (default), last changed, or one of its date fields." },
+      { flag: "--compare", desc: "Also the same over the window before (needs --days)." },
+      { flag: "--env dev|prod", desc: "A model's live (default) or dev data." },
+      { flag: "--json", desc: "The answer as JSON." },
+    ],
+    notes: [
+      "The same query the dashboards draw. Model rows count at when they were created, stamped by the server; rows from before the stamp are counted as untracked.",
+      "A model's fields are checked: `oalo data models` lists them. An app's server asks the same with queryMetric from `oalo typegen` (see `oalo docs dashboards`).",
+    ],
+    exits: { 0: "done", 1: "the query failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "dashboards",
+    summary: "The workspace's dashboards, and a chart put on one (made when no dashboard has that name).",
+    usage: [
+      "oalo dashboards [--json]",
+      'oalo dashboards add <dashboard> <model | events | contacts> --title "<title>" --kind number|line|bars|table [metrics flags] [--app <slug>] [--width 1|2|3]',
+      'oalo dashboards add <dashboard> --title "<title>" --kind funnel --steps a,b,c [--days N]',
+    ],
+    flags: [
+      { flag: "--title <title>", desc: "The chart's title. A chart with the same title on that dashboard is replaced." },
+      { flag: "--kind <kind>", desc: "number (a total; --compare adds the window before), line (needs --every), bars (needs --by), table, funnel." },
+      { flag: "--steps a,b", desc: "funnel: event types, in order." },
+      { flag: "--width <1|2|3>", desc: "Columns of three." },
+      { flag: "--app <slug>", desc: "A dashboard made now shows on this app too (its Dashboard tab)." },
+      { flag: "--json", desc: "The answer as JSON." },
+    ],
+    notes: [
+      "add runs the query first and refuses one that can't draw, then prints its numbers. It changes what everyone with access sees.",
+      "The flags after the model are the same as oalo metrics.",
+    ],
+    exits: { 0: "done", 1: "the request failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "products",
+    summary: "What the workspace sells (Oalo commerce on its own Stripe account): list, create, rename, change a price, archive, and see orders.",
+    usage: [
+      "oalo products [--all] [--json]",
+      'oalo products create <id> --name "<name>" --price <amount> --once|--monthly|--yearly [--trial <days>] [--currency <code>] [--description <text>] [--live] [--yes]',
+      'oalo products edit <id> [--name "<name>"] [--description <text>]',
+      "oalo products price <id> <amount> [--yes]",
+      "oalo products archive <id> --yes",
+      "oalo products delete <id> --yes",
+      "oalo products orders [<id>] [--limit N]",
+    ],
+    flags: [
+      { flag: "--name <name>", desc: "create, edit: the name buyers see." },
+      { flag: "--price <amount>", desc: "create: the price, like 9.99." },
+      { flag: "--once", desc: "create: paid once." },
+      { flag: "--monthly", desc: "create: a subscription, billed every month." },
+      { flag: "--yearly", desc: "create: a subscription, billed every year." },
+      { flag: "--trial <days>", desc: "create: free days before a subscription's first charge." },
+      { flag: "--currency <code>", desc: "create: ISO code, like EUR. Default USD." },
+      { flag: "--description <text>", desc: "create, edit: shown on the checkout page." },
+      { flag: "--live", desc: "create: on your live Stripe key (real charges). Without it, the test key." },
+      { flag: "--yes", desc: "Go ahead: needed for archive and delete, for --live, and for a price over 500." },
+      { flag: "--all", desc: "list: archived products too." },
+      { flag: "--limit N", desc: "orders: how many, newest first. Default 50." },
+      { flag: "--json", desc: "The reply as JSON." },
+    ],
+    notes: [
+      "The id (premium, pro_yearly) is what code uses: BuyButton productId, a row's product_id (with availability product), and a member's purchased_products. `oalo typegen` writes the ids as PRODUCTS and the ProductId type (Dart: the Products class), so a typo fails to compile.",
+      "Payments run on the workspace's own Stripe key (Payment settings). A product made with the test key is bought with test cards only.",
+      "price makes a new Stripe price and archives the old one: new buyers pay the new price, existing subscriptions keep theirs.",
+      "archive stops a product being sold; its orders stay and its buyers keep access. delete is for an archived product nobody bought, and frees its id.",
+      "PayPal, Apple and Google prices are set up from the dashboard's Storefront or by asking the builder.",
+    ],
+    exits: { 0: "done", 1: "the request failed", 2: "bad arguments, a confirmation (--yes) needed, or no CLI token" },
+  },
+  {
+    name: "channels",
+    summary: "Every channel the workspace has (WhatsApp, Instagram, email, web chat) and which bot answers each; change the bot, check or connect a number.",
+    usage: [
+      "oalo channels [--json]",
+      "oalo channels set whatsapp|instagram <number or @account> --bot <bot>",
+      "oalo channels check whatsapp <number>",
+      "oalo channels connect whatsapp --bot <bot>",
+      "oalo channels connect instagram",
+      "oalo channels disconnect whatsapp|instagram <number or @account> --yes",
+    ],
+    flags: [
+      { flag: "--bot <bot>", desc: "The bot's public id (`oalo bots` lists them)." },
+      { flag: "--yes", desc: "Go ahead with disconnect. Without it, disconnect only says what it would do." },
+      { flag: "--json", desc: "The reply as JSON." },
+    ],
+    notes: [
+      "A WhatsApp number can be given as shown (+54 9 11 5555-0100), as its digits, or by its id; an Instagram account as @username or its id.",
+      "WhatsApp numbers and Instagram accounts are kept by the platform, where Meta's messages arrive; your Base asks it. Email is the sending address (no bot answers it); the web chat is each published bot's own widget.",
+      "connect prints a link to open in a browser, because Meta's own sign-in has to run there. The WhatsApp link is for you only and works for a few minutes.",
+      "Changes (set, connect, disconnect) are for workspace admins. Reading is for admins and members with Developer access. Disconnecting stops the bot answering at once; the conversations stay in the Inbox.",
+    ],
+    exits: { 0: "done (check: Oalo can send on the number)", 1: "the request failed, or check found it can't send", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "setup",
+    summary: "The setup agent on your Base makes an app run that Oalo can't run on its own, on a branch you then accept or reject.",
+    usage: [
+      "oalo setup [--app <slug>]",
+      "oalo setup status [--app <slug>] [--json]",
+      "oalo setup accept [--app <slug>]",
+      "oalo setup reject [--app <slug>]",
+      "oalo setup auto on|off [--app <slug>]",
+    ],
+    flags: [
+      { flag: "--app <slug>", desc: "The app. Default: the one saved with `oalo link --app`." },
+      { flag: "--json", desc: "The reply as JSON." },
+    ],
+    notes: [
+      "The agent works in the app's folder on a branch, oalo/setup: it reads the repo and adds what's missing (a Procfile, a Dockerfile, .oalo/app.json, a fix for a hard-coded port), the smallest change that makes it run. It never writes a secret; it names the variables to set.",
+      "Oalo checks each attempt itself: the app is detected and, for a server app, installed, its `release:` run, and its preview answering. Up to 6 attempts and a dollar budget (shown), then it stops and says why.",
+      "When it runs, the preview shows the branch. accept makes its commits the app's code (a fast-forward); reject throws them away. Deploys wait until then.",
+      "status has the agent's report: what the app is, what it changed and why, variables to set, whether it can run as several copies, what it couldn't fix.",
+      "auto on: a dev deploy that finds nothing runnable, or a preview that doesn't run, starts one by itself. Off by default.",
+      "Admins and members with Developer access only.",
+    ],
+    exits: { 0: "done", 1: "refused, or (status) the last setup failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "sources",
+    summary: "Feeds that send Oalo rows from outside (another system, a webhook, an export), keeping only the fields you choose.",
+    usage: [
+      "oalo sources [list] [--json]",
+      "oalo sources create <name> --from <sample.csv|.json|.jsonl> [--table <new model>] [--id-field <field>] [--mode upsert|snapshot] [--auth bearer|hmac|url] [--env dev|prod]",
+      "oalo sources create <name> --table <existing model or table> [--fields a,b] [--id-field <field>] [--auth bearer|hmac|url]",
+      "  (either form) [--keep-from-ai a,b] [--retention <days>]",
+      "oalo sources show <name> [--json]",
+      "oalo sources create <name> --bot <bot> [--auth bearer|hmac|url]",
+      "oalo sources push <name> <file.csv|.json|.jsonl> [--json]",
+      "oalo sources push <name> <doc.pdf|.docx|.md|.html|.txt> [more...] [--json]",
+      "oalo sources remove <name> <document>",
+      "oalo sources fetch <name> <https url> [--every <minutes>] [--header <\"Name: value\">] [--records-at <path>] [--document <name>] [--now]",
+      "oalo sources fetch <name> <postgres url> --relation <schema.view> [--key <column>] [--cursor <column>] [--every <minutes>] [--now]",
+      "oalo sources fetch <name> --now | --off",
+      "oalo sources fields <name> a,b",
+      "oalo sources retention <name> <days|off>",
+      "oalo sources rotate <name>",
+      "oalo sources delete <name> [--wipe]",
+    ],
+    flags: [
+      { flag: "--from <file>", desc: "create: a sample of what the sender sends. Its fields and their types make the source's fields and a new model (--table, default the source's name)." },
+      { flag: "--bot <bot>", desc: "create: send documents into this bot's knowledge (its public id, from oalo bots) instead of rows into a table. Each upload is one document by name; the same name replaces it." },
+      { flag: "--table <model>", desc: "create: the model or plain table the rows go to (a table the app made with its own SQL, or an import kept as it is). An existing one keeps all its fields or columns, or the ones in --fields. A plain table's --id-field must be a unique column." },
+      { flag: "--keep-from-ai a,b", desc: "create: fields stored and synced but never handed to a bot's AI model (see oalo data keep-from-ai)." },
+      { flag: "--retention <days>", desc: "create, a new model only: drop rows the source hasn't sent in this many days (1 to 3650), each night. Rows added by hand stay." },
+      { flag: "--fields a,b", desc: "create, existing model: keep only these fields. Anything else a sender sends is dropped, never stored." },
+      { flag: "--id-field <field>", desc: "create: the field that identifies a record (default id). A record sent again updates its row." },
+      { flag: "--mode snapshot", desc: "create: each upload is the whole set, and rows it leaves out are deleted. Only for a model the source makes. Default upsert." },
+      { flag: "--auth bearer|hmac|url", desc: "create: how a sender proves it's allowed. bearer (default): Authorization: Bearer <secret>. hmac: a signature header over the raw body (--hmac-header, default x-signature; --hmac-format sha256=hex, hex or base64), for tools that sign their webhooks. url: the secret is the last part of the address, for tools that can only send to an address." },
+      { flag: "--env dev|prod", desc: "create: which copy of the model the rows go to. Default prod." },
+      { flag: "--every <minutes>", desc: "fetch: how often Oalo fetches the address, 5 to 10080 minutes. Default 60." },
+      { flag: "--header <value>", desc: "fetch: a request header, \"Name: value\" (an API key, say: --header \"Authorization: Bearer $KEY\"). Repeat it for more, up to 10. Sealed on the server; show prints only the names. Left out, the ones set before stay; --header \"\" clears them." },
+      { flag: "--records-at <path>", desc: "fetch, a table's source: the records are the list at this key of the JSON answer (data.items)." },
+      { flag: "--document <name>", desc: "fetch, a knowledge source: the document's name (default the address's last part)." },
+      { flag: "--relation <name>", desc: "fetch, a postgres:// address: the view (or table) to read, like public.orders_for_oalo. Write a view of just the columns to share." },
+      { flag: "--key <column>", desc: "fetch, a postgres:// address: the view's column that identifies a row. Default the source's id field." },
+      { flag: "--cursor <column>", desc: "fetch, a postgres:// address: a column that grows as rows change (updated_at). Each run then reads only rows past the last one seen, up to 50,000. Without it, each run reads the whole view (up to 200,000 rows), so a snapshot source deletes what the view no longer has." },
+      { flag: "--now", desc: "fetch: fetch once now, and say what was stored." },
+      { flag: "--off", desc: "fetch: stop fetching." },
+      { flag: "--wipe", desc: "delete: also delete the rows, when the source made the model." },
+      { flag: "--json", desc: "The reply as JSON." },
+    ],
+    notes: [
+      "A sender posts JSON (an object or an array), NDJSON or CSV to the source's address. Keys and CSV headers are snake-cased as the CSV import does it, so \"Order ID\" and order_id are one field.",
+      "The secret is shown when the source is made, and by rotate; it only writes. Each upload answers what it stored, rejected and dropped, is listed in show, and fires source.<name>.received for workflows.",
+      "Rows sync to your apps at once and fire the model's row events, as Sync API writes do. Up to 10,000 records a request, 120 requests a minute per source, 200,000 rows a day per workspace.",
+      "push sends a file from here, over your CLI token, in batches of 1,000; in snapshot mode the rows missing from the whole file are deleted after its last batch.",
+      "A --bot source takes one document an upload: the file as the body named by ?name= (or an X-Document-Name header, or a form upload), or JSON {\"name\", \"text\"}. Its text is read on arrival, so a file without text (a scanned PDF) is refused then. Oalo keeps the text, not the file. DELETE to the address with ?name= removes a document. The bot answers from it once indexed, live at once (bots have no draft knowledge).",
+      "fetch from a postgres:// address reads a view in your own database: tested when set (connected, columns read), then on the schedule. Public addresses only, TLS required, a read-only session with a 30 s statement timeout, opened per run. The address, password included, is sealed; show prints it without the password. Pass it from an environment variable (\"$ORDERS_DB_URL\") to keep it out of your shell history.",
+      "fetch is for a system that can't post: Oalo GETs the address on a schedule and stores the answer as a post would be (JSON, NDJSON or CSV by its Content-Type; a knowledge source's document). Public https addresses only, up to 3 redirects, 10 MB. An answer that hasn't changed is skipped. show has the last run and its error.",
+      "Into a plain table, each record writes only the columns it has, cast by Postgres to the column's type; a value that doesn't fit rejects that record and says why. Snapshot, retention and delete --wipe are for a model the source made.",
+    ],
+    exits: { 0: "done", 1: "refused, failed, or some records were rejected", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "bots",
+    summary: "The workspace's bots: the tables each can search, and every setting (knowledge, memory, model, replies, limits).",
+    usage: [
+      "oalo bots [--json]",
+      "oalo bots knowledge <bot> [--json]",
+      "oalo bots knowledge <bot> --add <source> [--add ...] [--remove <source>] [--json]",
+      "oalo bots tools <bot> [--add <tool>] [--remove <tool>] [--json]",
+      "oalo bots settings <bot> [--json]",
+      "oalo bots settings <bot> set key=value [key=value ...] [--yes] [--dry-run] [--json]",
+      "oalo bots settings --explain [<key> | <group>] [--json]",
+    ],
+    flags: [
+      { flag: "tools --add <tool>", desc: "Let the bot call one of the workspace's tools, by name. Your server apps' own endpoints are listed once a deploy reads their .oalo/app.json (see `oalo docs app-tools`). --remove takes it away." },
+      { flag: "--add <source>", desc: "knowledge: attach a searchable table: its handle (model:products, table:prod.faq) or just its name when that's unique. Repeat it, or comma-separate." },
+      { flag: "--remove <source>", desc: "Detach one. The table stays searchable for other bots." },
+      { flag: "set key=value", desc: "settings: change one or more. A value starting with @ is read from that file (for the frame). none, default or an empty value clears a setting where its help says so." },
+      { flag: "--yes", desc: "settings set: apply to a published bot. Without it a published bot's change is shown and not saved." },
+      { flag: "--dry-run", desc: "settings set: show what would change; save nothing." },
+      { flag: "--explain [key]", desc: "settings: what each setting does, its values and default. A key, a group (knowledge, memory, model, replies, limits, data) or all." },
+      { flag: "--json", desc: "The bots, or the bot's sources and what else could be attached, as JSON." },
+    ],
+    notes: [
+      "<bot> is the bot's public id (bot_...), as `oalo bots` prints it.",
+      "A source is a table made searchable with `oalo data vectorize <table> --fields ...`. A bot always searches its own knowledge base (documents) too.",
+      "The same as ticking a table in the bot's Knowledge pane in the dashboard, with the same access as there.",
+      "settings go through the dashboard's own actions, with the same checks and access. A change sets only the settings it names: the model without the provider keeps the provider, one limit keeps the others, one context.* key keeps the rest of the context config.",
+      "Every setting is described in `man oalo` (BOT SETTINGS) and by `oalo bots settings --explain`.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "tokens",
+    summary: "List, create and revoke the workspace's sync tokens, for an app's own server.",
+    usage: [
+      "oalo tokens list [--json]",
+      "oalo tokens create --name <name> --scope write:<table> [--scope ...] [--days N] [--json]",
+      "oalo tokens revoke <id>",
+    ],
+    flags: [
+      { flag: "--name <name>", desc: "What the token is for, shown in the dashboard." },
+      { flag: "--scope <scope>", desc: "read, write, read_manifest, read:<table>, write:<table>, events (send events to POST /api/events/v1), workflows (call workflows, POST /api/workflows/v1/<name>/run), chat (sign the chat widget in as your app's user, POST /api/chat/v1/sessions), or env:dev / env:prod (lock it to one env's data: env:dev makes events and workflow calls safe test runs, for running your app on your machine). Repeat it. Prefer the narrowest. An unknown scope is refused." },
+      { flag: "--days N", desc: "Expiry in days (default 90; 0 for none)." },
+    ],
+    notes: [
+      "A sync token reads or writes every row of its tables, for every member. It belongs in a server's secrets, never in a mobile or web app.",
+      "The token is printed once. Copy it into the app server's secrets right away.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "docs",
+    summary: "Read the OALO platform docs from your workspace: list, search, or print a page as markdown.",
+    usage: ["oalo docs [--audience developer|trainer] [--json]", "oalo docs <slug> [--json]", "oalo docs --search \"<words>\" [--json]"],
+    flags: [
+      { flag: "--search <words>", desc: "Pages ranked for the words, each with the line that matched." },
+      { flag: "--audience developer|trainer", desc: "Only pages for that reader (pages for both always show)." },
+      { flag: "--json", desc: "Structured output: summaries for a list or search, the full page with markdown for a slug." },
+    ],
+    notes: [
+      "Served by your workspace's own server (its Base), so the pages match the version it runs.",
+      "Good starting pages for building on OALO: bring-your-repo and connect-your-own-frontend for your own code, app-environment, tokens-and-credentials, data-models, sync-rest-api, triggers-and-chaining.",
+      "A page goes to stdout as markdown, so `oalo docs data-models > notes.md` saves it. Related pages are listed on stderr.",
+    ],
+    exits: { 0: "done", 1: "no such page, or the workspace failed", 2: "no CLI token" },
+  },
+  {
+    name: "apps",
+    summary: "List the workspace's apps: type, state, preview and live addresses, and the live release.",
+    usage: ["oalo apps [--json]"],
+    flags: [{ flag: "--json", desc: "Print the apps as JSON." }],
+    notes: ["The first column is the slug, which `oalo deploy --app` and `oalo link --app` take."],
+    exits: { 0: "done", 1: "the workspace failed", 2: "no CLI token" },
+  },
+  {
+    name: "deploy",
+    summary: "Send this repo's commits to an app and run them: the preview (dev) by default, the live release with --env prod.",
+    usage: [
+      "oalo deploy [--app <slug>] [--env dev|prod] [--allow-dirty] [--json]",
+      "oalo deploy --new [<name>] [--name \"Display name\"]",
+      "oalo deploy --new [<name>] --from <https url> [--branch <name>] [--token-env <VAR>]",
+      "oalo deploy --app <slug> --pull",
+      "oalo deploy --app <slug> --replace",
+      "oalo deploy --app <slug> --history",
+      "oalo deploy --app <slug> --rollback [--to <sha>]",
+    ],
+    flags: [
+      { flag: "--app <slug>", desc: "The app (`oalo apps` lists them). Default: the app saved with `oalo link --app`." },
+      { flag: "--env dev|prod", desc: "dev updates the preview; prod builds and swaps the live release. prod must be on the command line." },
+      { flag: "--new [<name>]", desc: "Make a new app from this repo: its type found from the files at the repo's root (no Dockerfile needed), its commits kept as the app's history, its preview set up. The name (default: the repo's folder) becomes its slug, and this project is linked to it. When nothing at the root says what the app is (a monorepo, say), it is made as code only and the deploy says what to add: see `oalo docs bring-your-repo`." },
+      { flag: "--name <display name>", desc: "With --new: the app's display name. Default: its slug." },
+      { flag: "--from <https url>", desc: "With --new: make the app from a Git repository at this address instead of this folder (no local checkout needed). The Base clones one branch with its whole history (https to a public host only, up to 200 MB, 5 minutes), then makes the app as --new does. The name defaults to the repository's. Nothing is linked here." },
+      { flag: "--branch <name>", desc: "With --from: the branch to import. Default: the repository's default branch." },
+      { flag: "--token-env <VAR>", desc: "With --from: for a private repository, the environment variable holding an access token that can read it (a GitHub, GitLab, Bitbucket or Forgejo personal access token). Without it, at a terminal, you're asked for the token, hidden, when the host wants one. It is used for that one clone: never stored, logged or kept in the app's repo." },
+      { flag: "--pull", desc: "Fetch the app's code as OALO has it into oalo/<slug>, to merge changes made there (by the builder agent or a teammate)." },
+      { flag: "--replace", desc: "Make this branch the app's code even though the histories differ. The app's current code is tagged first so it can be recovered." },
+      { flag: "--allow-dirty", desc: "Deploy the last commit even though there are uncommitted changes (which are not sent)." },
+      { flag: "--history", desc: "The live releases the app has had, newest first." },
+      { flag: "--rollback", desc: "Make the release before the current one live again (or --to <sha>). Again goes further back; it never returns to a release you rolled back from. It is built and checked like any live deploy; a failing one leaves the current release live." },
+      { flag: "--to <sha>", desc: "With --rollback: the release to make live (`--history` lists them)." },
+    ],
+    notes: [
+      "What is sent is the current branch's commits, as a git bundle, signed in with your CLI token. No git remote or extra credential is needed. Uncommitted changes are never sent.",
+      "The app only moves forward. If it has commits your repo lacks, the deploy stops and lists them: run --pull, merge, deploy again.",
+      "dev: dependencies are reinstalled when package.json, a lockfile, requirements.txt, mix.exs or pubspec.yaml changed, then the preview restarts.",
+      "prod: the app is built (install, then its build script), a Procfile `release:` line runs, and the live release swaps over once the new one answers on its port. A failed build or release command leaves the old release live; a release that crashes or never answers is removed, and the old one keeps serving (the error shows its last lines).",
+      "How a server app starts: its Procfile (`web:`, workers, `release:`), else its package.json `start` (`dev` in the preview), else the runtime's default (index.js, main.py, app.py, manage.py, mix).",
+      "--from is what the dashboard's Add app, From Git does: the same app, the same type detection, secret scan and preview. A token is never a flag value, since that stays in your shell history.",
+      "Admins and members with Developer access only. Progress streams while it runs.",
+    ],
+    exits: { 0: "deployed", 1: "refused or failed", 2: "bad arguments, no CLI token, or not in a git repo" },
+  },
+  {
+    name: "env",
+    summary: "An app's environment variables on OALO (API keys, settings), per env: list, set, unset, rotate-token.",
+    usage: [
+      "oalo env [--app <slug>] [--env dev|prod] [--json]",
+      "oalo env set NAME=value [NAME=value ...] [--secret | --public] [--no-restart]",
+      "oalo env set NAME --secret",
+      "oalo env set --file .env.production --env prod",
+      "oalo env unset NAME [NAME ...]",
+      "oalo env rotate-token [--env dev|prod]",
+    ],
+    flags: [
+      { flag: "--app <slug>", desc: "The app (`oalo apps` lists them). Default: the app saved with `oalo link --app`." },
+      { flag: "--env dev|prod", desc: "dev is the preview, prod the live app. Each has its own variables. Changing prod needs --env prod on the command line." },
+      { flag: "--secret", desc: "Store as secret: never shown again, and only server apps get it. A NAME with no =value asks for the value without echoing it (or reads stdin when piped)." },
+      { flag: "--public", desc: "Store as public: shown by `oalo env`, and given to static apps too." },
+      { flag: "--file <path>", desc: "Set every NAME=value line of a .env file in one step (all or none)." },
+      { flag: "--no-restart", desc: "Don't restart the preview (dev) or relaunch the live app (prod) after this change." },
+    ],
+    notes: [
+      "A variable is secret unless its name starts with VITE_, EXPO_PUBLIC_, NEXT_PUBLIC_, PUBLIC_ or REACT_APP_, or it's set with --public.",
+      "Server apps get every variable, in the preview and live. Static apps (React, Expo, Flutter) only get public ones, because whatever their build sees ends up in the browser.",
+      "Names Oalo sets itself can't be set: any starting with OALO_, PORT, DATABASE_URL, APP_SCHEMA, APP_SLUG, CONTAINER_HOST (and their VITE_/EXPO_PUBLIC_ forms), and the process basics (PATH, HOME, LANG, TZ, the Mix, Hex and Flutter homes). `oalo env set` refuses one by name.",
+      "A server app gets OALO_URL and OALO_SYNC_TOKEN: a Sync API token for its own env's data that can also send events, call workflows and start chat sessions, so it needs no token of its own. It also signs OALO's calls to the app's endpoints (.oalo/app.json tools). The preview's token can't touch live data, and its events and workflow calls are test runs. `rotate-token` replaces it at once and restarts the app on the new one.",
+      "A dev change restarts the preview. A prod change relaunches the live app at the commit it already runs (a build; no new code goes out). --no-restart skips that, to batch several changes: the last one without it relaunches.",
+      "Admins and members with Developer access only.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "secrets",
+    summary: "Keys and tokens found committed to an app's code (on import, and in each push or deploy).",
+    usage: ["oalo secrets [--app <slug>] [--all] [--json]", "oalo secrets dismiss <fingerprint> [--app <slug>]"],
+    flags: [
+      { flag: "--app <slug>", desc: "The app (`oalo apps` lists them). Default: the app saved with `oalo link --app`." },
+      { flag: "--all", desc: "Dismissed findings too." },
+      { flag: "--json", desc: "The findings as JSON." },
+    ],
+    notes: [
+      "Only where each one is and what it looks like: no value is ever kept.",
+      "For each: rotate it with its provider (it stays in the repo's history), set the new one with `oalo env set NAME --secret`, and read it from the environment in the code.",
+      "Admins and members with Developer access only.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "dockerfile",
+    summary: "How a server app's live image is built, and the Dockerfile it builds from.",
+    usage: ["oalo dockerfile [--app <slug>] [--json]", "oalo dockerfile --write [--force] [--app <slug>]"],
+    flags: [
+      { flag: "--app <slug>", desc: "The app (`oalo apps` lists them). Default: the app saved with `oalo link --app`." },
+      { flag: "--write", desc: "Save OALO's Dockerfile as ./Dockerfile, to change. Once committed, the repo's copy is used." },
+      { flag: "--force", desc: "With --write, replace an existing ./Dockerfile." },
+      { flag: "--json", desc: "method, source (repo or oalo), runtime and the Dockerfile's text." },
+    ],
+    notes: [
+      "The first that fits: the repo's own Dockerfile; OALO's for the runtime, for the languages buildpacks can't build; buildpacks for the rest. `oalo docs live-server-apps` lists which language gets which.",
+      "Every image runs as uid 1000 with a read-only filesystem (/tmp is writable) and must serve $PORT. A Procfile's lines still name the processes: web runs the image's own command when the Procfile has no web line.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "logs",
+    summary: "What an app's own processes printed (server, workers, release command), per env.",
+    usage: ["oalo logs [--app <slug>] [--env dev|prod] [--process web|<worker>] [--limit N] [--follow] [--json]"],
+    flags: [
+      { flag: "--app <slug>", desc: "The app (`oalo apps` lists them). Default: the app saved with `oalo link --app`." },
+      { flag: "--env dev|prod", desc: "dev is the preview, prod the live app. Default dev." },
+      { flag: "--process <name>", desc: "Only this process: web, a Procfile worker's name, release, build (a live build's output, with --env prod), or oalo (OALO's own notes)." },
+      { flag: "--limit N", desc: "How many recent lines (default 200, at most 2000)." },
+      { flag: "--follow", desc: "Keep printing new lines as they come, until Ctrl-C." },
+      { flag: "--json", desc: "One JSON object per line: at, process, line." },
+    ],
+    notes: [
+      "The workspace keeps the last 2,000 lines per env in memory; restarting the workspace empties them.",
+      "Lines from `oalo` are OALO's own: which command started, and when a process exited and with what status.",
+      "Admins and members with Developer access only: an app can print secrets or customers' details.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "loops",
+    summary: "Test a loop (sends simulated), see its past runs, turn it on or off, or delete it, without pulling and pushing it.",
+    usage: [
+      "oalo loops test <name> [--sample latest|example] [--input <json|@file.json>] [--json]",
+      "oalo loops on <name>",
+      "oalo loops off <name>",
+      "oalo loops delete <name>",
+      "oalo loops runs [<name>] [--limit N] [--json]",
+      "oalo loops runs --id <run> [--json]",
+    ],
+    flags: [
+      { flag: "--sample latest|example", desc: "Test with the loop's most recent real event, or one built from its trigger's fields." },
+      { flag: "--input <json|@file>", desc: "Test with this input instead: an event envelope {type, contact_id, payload}, or what a scheduled loop's first step reads." },
+      { flag: "--app <slug>", desc: "Only for a loop pinned to one app: that app's slug (`oalo apps`) or id. Works with test, runs, on, off and delete." },
+      { flag: "--id <run>", desc: "runs: one run step by step, with each step's output." },
+      { flag: "--limit N", desc: "runs: at most this many (default 20)." },
+      { flag: "--json", desc: "Print the test result as JSON." },
+    ],
+    notes: [
+      "A test runs every step. Steps that send messages or change records are simulated, and their output says what they would have done. Custom tools and AI steps run for real. It works on a loop that is off.",
+      "A loop that is on runs for real whenever its triggers fire. Starting a run now, for real: `oalo run loop <name>`.",
+      "Deleting can't be undone; turning a loop off keeps it.",
+    ],
+    exits: { 0: "done (a test passed)", 1: "refused, failed, or the test run failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "flows",
+    summary: "Turn a chat flow on or off, or delete it, by bot and flow name, without pulling and pushing it.",
+    usage: ["oalo flows on <bot> <flow>", "oalo flows off <bot> <flow>", "oalo flows delete <bot> <flow>"],
+    flags: [],
+    notes: [
+      "<bot> is the bot's public id (the folder under .oalo/flows/ after `oalo pull`, or the MCP tool oalo_list_bots), <flow> its name or id.",
+      "A flow that is on can start in real conversations. A call_other_flow step only runs a flow that is on.",
+      "Deleting can't be undone; turning a flow off keeps it.",
+    ],
+    exits: { 0: "done", 1: "refused or failed", 2: "bad arguments or no CLI token" },
+  },
+  {
+    name: "pull",
+    summary: "Fetch chat flows, loops and code tools into .oalo/ as files you can edit.",
+    usage: ["oalo pull [flows|loops|tools] [--bot <id>] [--name <name>] [--force]"],
+    flags: [
+      { flag: "--bot <id>", desc: "Only this bot's flows (numeric or public bot_ id)." },
+      { flag: "--name <name>", desc: "Only the flow or loop with this name." },
+      { flag: "--force", desc: "Overwrite files you have edited since the last pull." },
+    ],
+    notes: [
+      "Writes .oalo/flows/<bot>/<flow>.json, .oalo/loops/<loop>.json (loops pinned to an app under loops/apps/<app>/), .oalo/tools/<tool>.js + .json for code tools, and the node contracts .oalo/catalog/flow.json and loop.json.",
+      "Only code (JavaScript) tools are pulled; webhooks, built-ins and Elixir actions are configured in the dashboard. A tool's code is compiled when pushed, so code that doesn't build is refused.",
+      "A loop file also lists the loop's `triggers` (what starts it). Add or delete entries and push: push adds the new ones and removes the ones you deleted, and keeps any a teammate added since your pull. Set a trigger's `enabled` to turn it on or off.",
+      "Each file holds the editable object (`flow` or `loop`) plus the CLI's bookkeeping: id, version (sent back as base_version on push) and base_hash (how the CLI knows you edited it). Edit the object; leave the bookkeeping alone.",
+      "A file you have edited is kept, not overwritten, unless you pass --force.",
+      "To create a flow or loop, write a file in the same shape without id or version, then push it.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "pulled", 1: "pull failed", 2: "bad arguments or no token" },
+  },
+  {
+    name: "status",
+    summary: "Show which flow and loop files changed, locally or on the server.",
+    usage: ["oalo status [<file>...] [--json]"],
+    flags: [{ flag: "--json", desc: "One JSON array of {path, state, note}." }],
+    notes: [
+      "States: new (never pushed), clean, modified (push it), behind (the server has a newer version: pull it), conflict (both changed: merge by hand), gone (deleted on the server), invalid (not a readable file), error (the server check failed; the note says why).",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "nothing in conflict", 1: "a conflict, an invalid file, or a failed check", 2: "no token" },
+  },
+  {
+    name: "lint",
+    summary: "Check flow and loop files without saving anything.",
+    usage: ["oalo lint [<file>...] [--verbose] [--json]"],
+    flags: [
+      { flag: "--verbose", desc: "Also show info-level findings." },
+      { flag: "--json", desc: "One JSON object per file: {path, findings}." },
+    ],
+    notes: [
+      "The same checks the server runs before a strict save: node types and keys against the catalog, required settings, edges and conditions, references between steps, and tools the flow or loop calls.",
+      "Each finding names the node, what is wrong and how to fix it.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "no errors (warnings allowed)", 1: "errors found", 2: "no token" },
+  },
+  {
+    name: "push",
+    summary: "Lint and save edited flow, loop and tool files, guarded against concurrent edits.",
+    usage: ["oalo push [<file>...] [--dry-run] [--no-strict] [--force] [--all] [--verbose]"],
+    flags: [
+      { flag: "--dry-run", desc: "Lint only; save nothing." },
+      { flag: "--no-strict", desc: "Save even with error-level findings. Structural damage is still refused." },
+      { flag: "--force", desc: "Drop the version guard: overwrite whatever the server has." },
+      { flag: "--all", desc: "Push every file, not only the edited ones." },
+      { flag: "--verbose", desc: "Also show info-level findings." },
+    ],
+    notes: [
+      "Without files, pushes every file edited since its pull (and new ones).",
+      "Each save sends the pulled version: if someone saved in between, the push is refused as a conflict and nothing is overwritten. Pull, merge, push again.",
+      "Saves are strict: error-level lint findings block them. Fix the findings (each says how) or pass --no-strict.",
+      "After a save the file is rewritten from the server's copy with the new version.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "every file saved", 1: "a file was refused, in conflict, or failed", 2: "bad arguments or no token" },
+  },
+  {
+    name: "qa",
+    summary: "Run a scripted test conversation with a bot and print the transcript.",
+    usage: [
+      'oalo qa <bot> "<message>" ["<message>" ...] [--channel web|whatsapp|instagram|sms] [--flow <name>] [--timeout <s>] [--json]',
+      "oalo qa <bot> --script <file.json>",
+    ],
+    flags: [
+      { flag: "--channel <name>", desc: "Act as this channel: web (default), whatsapp, instagram, sms, embed. Changes how the bot behaves (text mode vs pickers)." },
+      { flag: "--flow <name>", desc: "Start this flow with the first message, even while it's off, so a new or changed flow is tested before it's turned on." },
+      { flag: "--script <file>", desc: 'A JSON file: {"channel": "whatsapp", "flow": "<name>", "messages": ["...", "..."]}.' },
+      { flag: "--timeout <s>", desc: "How long one turn may take to settle. Default 90, at most 300." },
+      { flag: "--label <text>", desc: "Tag stored on the test conversation." },
+      { flag: "--json", desc: "Print the whole run as JSON: turns (replies, flow state, ms, settled), flow_path, cost_usd." },
+    ],
+    notes: [
+      "The conversation is a preview with no phone number or external id: the inbox leaves it out and nothing is sent to WhatsApp, Instagram or SMS.",
+      "Everything else is real: the bot's tools and flows run, collected contact details are saved, handoffs happen. Use a test bot, or flows whose side effects you are fine repeating.",
+      "Each message waits until the bot settles (no new message and no running flow), then the next is sent. Any flow still active at the end is cancelled and the conversation is closed.",
+      "At most 20 messages per run. bot accepts a numeric id or a public bot_ id.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "every turn settled", 1: "a turn timed out or the run failed", 2: "bad arguments or no token" },
+  },
+  {
+    name: "rehearse",
+    summary: "Rehearse inbound WhatsApp conversations end to end: routing, triage and the bot's reply.",
+    usage: ["oalo rehearse [--number <phone_number_id>] [--responder <bot_...>] [--timeout <s>] [--json]", "oalo rehearse --script <file.json>"],
+    flags: [
+      { flag: "--number <id>", desc: "The WhatsApp number (phone_number_id) the customer writes to. Default: the workspace's default number." },
+      { flag: "--responder <bot_...>", desc: "The bot that should end up answering, by its public id (`oalo bots` lists them). Default: the bot an enabled triage loop hands threads to, else the number's bot." },
+      { flag: "--script <file>", desc: 'A JSON file: {"scenarios": [{"name", "messages", "known_contact", "opted_out", "open_thread": {"bot_id", "number", "hours_ago", "tags", "assigned", "deal"}, "expect": {"reply", "bot_id", "assigned"}}]}.' },
+      { flag: "--timeout <s>", desc: "How long one message may take to settle. Default 120, at most 300." },
+      { flag: "--json", desc: "Print every scenario as JSON: turns (what was sent), threads, loop runs and their steps, checks, why_silent, cost_usd." },
+    ],
+    notes: [
+      "Without --script it runs the standard scenarios: a new customer, a known contact whose thread is still open on another number, returning the same day, returning after 24 hours, writing again after their deal was won, writing again after opting out, handed to a teammate earlier today, and with a teammate but writing from another number.",
+      "Each message goes through the same code as a real WhatsApp message. The customer is a fictional 555-01XX number: sends to it are recorded, never posted, its threads stay out of the Inbox, and assignment emails, team-chat cards and workflow notices are skipped.",
+      "Real: LLM calls and their cost, loop runs in the run history. At the end its threads are closed and its contact removed.",
+      "A FAIL prints why the customer got no reply (opted out, a failed triage step, autopilot off, assigned to a teammate).",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "every scenario passed", 1: "a scenario failed or the run failed", 2: "bad arguments or no token" },
+  },
+  {
+    name: "skill",
+    summary: "Teach this project's coding agent how to work on OALO.",
+    usage: ["oalo skill [--agents]", "oalo skill --print"],
+    flags: [
+      { flag: "--agents", desc: "Also write the rules into AGENTS.md (between oalo markers), for agents other than Claude Code." },
+      { flag: "--print", desc: "Print the skill instead of installing it." },
+    ],
+    notes: [
+      "Installs .claude/skills/oalo/SKILL.md, which Claude Code loads on its own: the pull, lint, push, qa loop, and the rules (read the node catalog, never force past a conflict, test on the customer's channel, test conversations do real work).",
+      "The skill ships with this CLI version, and the installed copy says which. Re-running replaces it, and the AGENTS.md section when there is one, nothing else. Commit both.",
+      "`oalo link` installs it too. After a CLI update, the first command in a project with an older copy says so, once; `oalo skill` updates it.",
+    ],
+    exits: { 0: "installed or printed" },
+  },
+  {
+    name: "mcp",
+    summary: "Serve the workspace over MCP on stdio, for Claude Code or Cursor.",
+    usage: ["oalo mcp"],
+    flags: [],
+    notes: [
+      "stdout is the MCP protocol stream. Diagnostics go to stderr.",
+      "Exposes a curated tool set plus an oalo_call passthrough; the build surface has ~442 events and mapping them all would wreck tool selection.",
+      "Reads OALO_URL and OALO_CLI_TOKEN, or falls back to what `oalo link --cli-token` saved.",
+      "Needs a CLI token.",
+    ],
+    exits: { 0: "stopped cleanly", 1: "no workspace or CLI token" },
+  },
+  {
+    name: "coord",
+    // Not in the npm package yet: it needs Bun (bun:sqlite, TypeScript), so
+    // it's left out of help, the man page and help --json until it ships as a
+    // binary. `bun src/index.js coord` still runs it in development.
+    hidden: true,
+    summary: "Coordinate several agents on one codebase: task board, worktrees, merge queue.",
+    usage: [
+      "oalo coord init [--main <branch>] [--test-cmd <cmd>] [--merge auto|manual] [--signal-review]",
+      "oalo coord mcp",
+      "oalo coord board [--json]",
+      "oalo coord events [--follow] [--since <id>] [--json]",
+      "oalo coord claim <task>",
+      "oalo coord merge [--all]",
+      "oalo coord approve plan | merge <task> | signal <task> <milestone> | proposal <id>",
+      "oalo coord reject proposal <id>",
+      "oalo coord hooks install [--claude] [--opencode]",
+      "oalo coord hook <pre-tool|stop|subagent-stop|check-write|check-stop>",
+    ],
+    flags: [
+      { flag: "--main <branch>", desc: "init: branch the merge queue integrates into. Default: current branch." },
+      { flag: "--test-cmd <cmd>", desc: "init: merge-gate test command. Default: detected (mix test, npm test, ...)." },
+      { flag: "--merge auto|manual", desc: "init: manual holds each merge for `approve merge`." },
+      { flag: "--signal-review", desc: "init: milestones unblock dependents only after `approve signal`." },
+      { flag: "--json", desc: "board/events: machine-readable output." },
+      { flag: "--follow", desc: "events: keep streaming." },
+      { flag: "--all", desc: "merge: keep merging until the queue is idle or blocked." },
+    ],
+    notes: [
+      "Local only: the board is .oalo/coord.db in the project; no server, no account.",
+      "Every agent session attaches `oalo coord mcp`. The manager plans tasks; workers claim them in their own git worktree.",
+      "Human gates are CLI-only so no agent can approve its own work: approve plan, merge, signal, scope proposals.",
+      "`hooks install` adds the guards: edits only inside your task's worktree and write set; no stopping while holding a claim; the manager waits for its inbox instead of polling.",
+      "Requires the oalo binary (Bun runtime); the other commands also run under Node.",
+    ],
+    exits: { 0: "ok", 1: "operation refused or failed (message on stderr)", 2: "bad arguments", 3: "no board here; run `oalo coord init`" },
+  },
+];
+
+export const ENV_VARS = [
+  { name: "OALO_URL", desc: "Workspace URL; overrides the linked config." },
+  { name: "OALO_SYNC_TOKEN", desc: "Sync token; overrides the stored one." },
+  { name: "OALO_CLI_TOKEN", desc: "CLI token; overrides the stored one." },
+  { name: "OALO_HOME", desc: "Relocate the credential store (CI, containers, tests)." },
+  { name: "OALO_DEBUG", desc: "Log channel transport activity to stderr." },
+  { name: "NO_COLOR", desc: "Disable colour in tail output." },
+];
+
+const pad = (s, n) => s + " ".repeat(Math.max(0, n - s.length));
+
+/** The commands `help`, `help --json` and the man page show (not the hidden ones). */
+export const PUBLIC = COMMANDS.filter((c) => !c.hidden);
+
+export function overview() {
+  const lines = [`oalo: ${TAGLINE}`, ``, `Commands:`];
+  for (const c of PUBLIC) lines.push(`  ${pad(c.name, 10)} ${c.summary}`);
+  lines.push(
+    ``,
+    `Run \`oalo help <command>\` for detail, or \`oalo help --json\` for a`,
+    `machine-readable description of every command, flag and exit code.`,
+    ``,
+    `Two token kinds, NOT interchangeable:`,
+  );
+  for (const t of TOKENS) {
+    lines.push(`  ${pad(t.kind, 5)} ${t.plane}`);
+    lines.push(`        from ${t.where}`);
+    lines.push(`        used by ${t.usedBy.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+export function commandHelp(name) {
+  const c = COMMANDS.find((x) => x.name === name);
+  if (!c) return null;
+
+  const lines = [`oalo ${c.name}: ${c.summary}`, ``, `Usage:`];
+  for (const u of c.usage) lines.push(`  ${u}`);
+
+  if (c.flags.length) {
+    lines.push(``, `Flags:`);
+    const w = Math.max(...c.flags.map((f) => f.flag.length));
+    for (const f of c.flags) lines.push(`  ${pad(f.flag, w)}  ${f.desc}`);
+  }
+
+  if (c.notes.length) {
+    lines.push(``, `Notes:`);
+    for (const n of c.notes) lines.push(`  - ${n}`);
+  }
+
+  lines.push(``, `Exit codes:`);
+  for (const [code, meaning] of Object.entries(c.exits)) lines.push(`  ${code}  ${meaning}`);
+  return lines.join("\n");
+}
+
+/** Machine-readable. Intended for an agent deciding how to drive the CLI. */
+export function helpJson() {
+  return JSON.stringify(
+    { name: "oalo", tagline: TAGLINE, commands: PUBLIC, tokens: TOKENS, env: ENV_VARS },
+    null,
+    2,
+  );
+}