@oalo-ai/cli 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@oalo-ai/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Wire a local app into your OALO workspace: link a token, generate typed bindings, and serve the build surface over MCP.",
+  "type": "module",
+  "bin": {
+    "oalo": "src/index.js"
+  },
+  "files": [
+    "src",
+    "plugin",
+    "man",
+    "README.md",
+    "LICENSE",
+    "!src/coord",
+    "!src/commands/coord.ts"
+  ],
+  "man": [
+    "./man/oalo.1"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "smoke": "node test/smoke.mjs",
+    "smoke:mcp": "node test/mcp-smoke.mjs",
+    "test:coord": "bun test test/coord.test.ts",
+    "test:unit": "node --test test/*.test.mjs",
+    "man": "node scripts/man.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "phoenix": "^1.7.0",
+    "ws": "^8.16.0"
+  },
+  "keywords": [
+    "oalo",
+    "mcp",
+    "sync",
+    "codegen"
+  ],
+  "license": "MIT"
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "oalo",
+  "description": "Work on an Oalo workspace from Claude Code: edit chat flows, loops and code tools, lint and push them safely, and run test conversations with a bot.",
+  "version": "0.1.0",
+  "author": { "name": "Oalo" },
+  "mcpServers": {
+    "oalo": {
+      "command": "npx",
+      "args": ["-y", "@oalo-ai/cli", "mcp"]
+    }
+  }
+}

package/plugin/skills/oalo/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: oalo
+description: Build and change an Oalo workspace (the person's Oalo Base) from the terminal with the oalo CLI or its MCP server: chat flows, loops (automations), code tools, bots and what they know, data models and rows, hosting a repo and its environment variables, and what an app gets from Oalo (its own token, events into workflows, workflows as functions, its endpoints as bot tools, a chat widget, member sign-in and sync). Use when editing a flow, loop or tool, testing how a bot answers, moving data in or out of Oalo, bringing or deploying an app, or wiring an app's own code to Oalo.
+---
+
+# Working on an Oalo workspace
+
+Oalo runs chatbots, chat flows, loops (background automations) and code tools in
+the cloud. You edit their definitions locally and push them; they run on the
+server. A push is a deploy: a saved flow or loop is live for real customers the
+moment it saves, with no staging copy. (Data and apps do have two: dev and prod.)
+
+Don't guess a command, flag or endpoint: `oalo help <command>` has every flag,
+`oalo docs --search "<words>"` finds Oalo's own pages, and `oalo call --list
+<word>` finds anything the commands don't cover.
+
+## The loop
+
+```sh
+oalo pull                 # flows, loops and code tools into .oalo/, plus the node catalogs
+# edit .oalo/flows/<bot>/<flow>.json, .oalo/loops/<loop>.json, .oalo/tools/<tool>.js
+oalo lint                 # check every changed file; nothing is saved
+oalo push                 # lint, then save with the version you pulled (strict)
+oalo qa <bot> "hola" "..." --channel whatsapp   # talk to the bot, read the transcript
+oalo status               # what changed locally and on the server
+```
+
+Over MCP the same steps are `oalo_node_catalog`, `oalo_get_flow` / `oalo_get_loop` /
+`oalo_get_tool_source`, `oalo_lint_flow` / `oalo_lint_loop`, `oalo_save_flow` /
+`oalo_save_loop` / `oalo_save_tool_source`, `oalo_test_conversation` and
+`oalo_test_loop`.
+
+## Rules
+
+1. **Never guess a node's keys.** The contract is `.oalo/catalog/flow.json` and
+   `.oalo/catalog/loop.json` (or `oalo_node_catalog`): every node type, its keys,
+   which are required, allowed values, what it outputs, and the edge and
+   reference rules. The runner ignores keys it doesn't know, so a misspelled
+   key silently does nothing.
+2. **Edit the content, not the bookkeeping.** In a pulled file, change `flow`,
+   `loop` or `tool` (and a tool's `.js`), and a loop's `triggers`. Leave `id`,
+   `version`, `base_hash` and `trigger_base` alone: they are how push detects a
+   concurrent edit and what you changed.
+3. **Keep what you don't change.** A save replaces the whole graph. Keep every
+   node and edge, and the editor's keys (`x`, `y`, `position`, `label`) so the
+   visual editor still lays it out.
+4. **Fix every lint error before pushing.** Each finding names the node, what
+   is wrong and how to fix it. Read the warnings too: most are real (a condition
+   that can never match, a reference to a field a step doesn't produce).
+5. **Never force your way past a conflict.** A conflict means someone saved
+   after you pulled. Push saves their copy next to yours (`*.server.json`, or
+   `*.server.js` for a tool): merge your change into it and push again. Use
+   `--force` only when you have checked their change can be dropped. A code
+   tool is the exception: after merging their `.server.js` into your `.js`,
+   `oalo push <file> --force` is the right step (a tool has no version to
+   re-base on).
+6. **Test after every change** with `oalo qa`, using the channel customers use.
+   WhatsApp, Instagram and SMS run in text mode (no pickers or forms), so a flow
+   that works on web can still fail there. `--flow <name>` starts that flow with
+   the first message even while it's off, so test a new flow before anyone
+   turns it on.
+7. **Test conversations do real work.** They never reach a customer's phone,
+   but the bot's tools and flows run: contact details are saved, handoffs
+   happen. Use a test bot, or flows whose side effects are fine to repeat.
+   Test a loop with `oalo loops test <name>`: sends are simulated.
+   To test a loop's trigger, `oalo emit <event> --dry-run` (MCP: `oalo_emit`
+   with `dry_run`) lists the loops an event would fire. Without `--dry-run` it
+   fires them for real, and they may email or message real contacts, so ask
+   the person before a real emit.
+8. **Customer-facing words are product copy.** Keep the bot's language and
+   tone, and never show customers internal names: SKUs, codes, step ids, tool
+   names.
+
+## Flows and loops differ
+
+| | Chat flow | Loop |
+|---|---|---|
+| First step | `graph.entry` (required) | `entry` if set, else the first node no edge points to |
+| Reading an earlier step | `{{state.<id>.<field>}}` | `{{<id>.<field>}}`; the previous step is `{{input}}` |
+| Several conditions match | the first match wins | every match is followed |
+| No condition matches, no default edge | the flow ends quietly | the run fails |
+| Action settings | keys on the node | inside `params` |
+
+Edge conditions read the source step's own output, with no prefix:
+`_ok == false`, `count > 0`, `decision == "refund"`.
+
+## Starting, chaining, on and off
+
+```sh
+oalo loops test welcome --sample example   # run every step, sends simulated
+oalo loops on welcome                      # or off; MCP: oalo_set_loop_enabled
+oalo flows on <bot> quote_helper           # or off; MCP: oalo_set_flow_enabled
+```
+
+1. **What starts a flow** is its `trigger`: `llm_tool` (the bot decides, from
+   `trigger_instructions`), `manual` (only another flow or the API),
+   `on_media_upload`, plus `auto_start_on_open` for a web chat.
+2. **What starts a loop** is its triggers, kept apart from its definition:
+   `triggers` in a pulled loop file (push adds and removes them), or
+   `oalo_loop_triggers` (catalog, list, add, remove). Types: `event` (with an
+   optional payload `filter`), `scheduled` (cron, UTC), `date_field` (a
+   contact's date), `widget_submit`, `exit`, and `api` (an app calls the loop:
+   `oalo docs workflow-calls`). An event is one from the catalog, an `app.*`
+   name an app sends (fine before it first sends it), `data.<table>.created` or
+   `.updated` (fires once `oalo data events <table> created` is on), or
+   `source.<name>.received`. Don't invent other names.
+   **To stop a drip once the contact does what it's for** (books, pays,
+   replies), add an `exit` trigger on that event (`appointment.booked`,
+   `order.created`, ...). It never starts a run: it cancels the contact's
+   pending waits in that loop, so the later steps never happen.
+3. **Chaining.** A flow runs another flow of the same bot with a
+   `call_other_flow` step. Give the helper `trigger: "manual"` and turn it on,
+   because a call can't run a flow that is off. A loop starts another loop with
+   a `function_call` to `enroll_in_loop` (now, for the contact), and the other
+   loop must be on: enrolling into a loop that is off is refused. A
+   `schedule_event` step fires a catalog event later, which starts every loop
+   with that trigger.
+4. **New and changed work stays off until the person says to turn it on.**
+   Turning something off when asked is safe. Delete only when they ask: it
+   can't be undone, and off keeps it.
+5. **Test a loop with `oalo loops test`** (MCP: `oalo_test_loop`), not by
+   running it: `oalo run loop` and a real `oalo emit` send real messages. In a
+   loop, `{{trigger.payload.x}}` is the event in any step; `{{input}}` is only
+   the previous step's output.
+6. `oalo docs triggers-and-chaining` has the whole picture: every trigger, what
+   on and off mean for each, and the common mistakes.
+
+## When something went wrong, and what flows and loops use
+
+```sh
+oalo loops runs welcome_series        # its recent runs; MCP: oalo_loop_runs
+oalo loops runs --id 4812             # one run, step by step
+```
+
+1. **Look at what ran before changing anything.** A loop's runs and each
+   step's output: `oalo_loop_runs` (`name`, then `run_id`). A flow's runs:
+   `oalo_flow_runs` (then `run_id`). One real conversation with its flow
+   steps: `oalo_get_conversation`. Find the step that failed or the condition
+   that didn't match, then fix that.
+2. **Conversations are real customers'.** Read only what the task needs, and
+   never copy their details into files, code or your reply.
+3. **The pieces a flow or loop names must exist:**
+   - a widget (form or picker) a flow shows: `oalo_widgets`. `fields`
+     replaces the whole list on update, so `get` it first. `assign` it to the
+     bot that uses it.
+   - a WhatsApp message outside the 24-hour reply window needs an approved
+     template: `oalo_wa_templates` (`list`, or `create` a draft). **Submitting
+     a template sends it to Meta for review: only when the person says so.**
+   - stage ids for steps that move deals: `oalo_pipelines` (`list`).
+   - code tools: `oalo_tool_templates` (ready-made, or `copy` a built-in) before
+     `oalo_generate_tool` writes a new one.
+   - notes loops keep between runs: `oalo_loop_docs`.
+4. **No MCP?** Every `oalo_*` tool above has an event behind it: `oalo call
+   --list <word>` finds it and the params it takes, and `oalo call <event>
+   '<json>'` runs it.
+
+## Data: models and rows
+
+Every workspace has data models (tables) in two schemas: `dev`, a sandbox, and
+`prod`, which live apps read. A row is `{id, document, owner_id, availability,
+product_id, ...}`; the fields are in `document`.
+
+```sh
+oalo data models                                  # what exists: fields, shared or owned
+oalo data models create orders_mirror --field total:float --field email   # dev and prod
+oalo data push orders_mirror orders.csv --id-field order_no --dry-run     # check first
+oalo data push orders_mirror orders.csv --id-field order_no               # upsert into dev
+oalo data list orders_mirror --limit 5            # look at what landed
+oalo data promote orders_mirror                   # copy dev rows to prod, when the person wants it live
+oalo data routes                                  # the Sync API's endpoints, scopes and limits
+```
+
+Over MCP: `oalo_list_models`, `oalo_create_model`, `oalo_read_rows`,
+`oalo_write_rows` (env required; prod needs `confirm`), `oalo_promote_model`,
+`oalo_sync_routes`.
+
+1. **Look before you create.** Reuse a model that exists (`oalo data models`).
+   Use `--owned-by <field>` only when each app user owns their rows.
+2. **Always give rows an id** (`--id-field`), usually the source system's own
+   key. Then sending a row again updates it instead of adding a copy.
+3. **Write to dev, check, then promote.** Rows written to prod sync to live apps
+   at once, so writing there needs `--env prod` and the person's go-ahead.
+4. **For an app's own server** (mirroring its database into Oalo, reading data
+   out): a server app hosted on Oalo already has `OALO_URL` and
+   `OALO_SYNC_TOKEN` in its environment, locked to its own env's data. Use
+   them: there is no token to make. For a server hosted elsewhere, the person
+   runs `oalo tokens create --name <what> --scope write:<table>` themselves (it
+   prints the token once) and stores it in that host's secrets. Don't run it
+   yourself: the token would land in your context. The app calls
+   `/api/sync/v1`; `oalo docs sync-rest-api` explains it and `oalo data routes`
+   lists the endpoints. Never put a sync token in a mobile or web app: it reads
+   and writes every member's rows.
+5. **For an app's members** (a web or mobile app showing each member their own
+   data): the app signs the member in with an email code and syncs as that member
+   with the sync SDK (`@synclib-io/client`, or the Flutter scaffold), so Oalo
+   returns only their rows of an owned model. **Before writing any of it, read
+   `oalo docs connect-your-own-frontend`**: the sign-in endpoints, the socket
+   URL, the one channel topic every app uses, and how to write rows. Don't guess
+   these; a wrong topic or write call fails silently. To start from working code
+   instead, `oalo deploy --app <slug> --pull` fetches an Oalo app that already
+   has sign-in and sync wired.
+
+## Two tokens
+
+- **CLI token**: everything above. It acts as you, with your permissions.
+- **Sync token**: data only, for `oalo typegen` and `oalo data` reads.
+  Server-side only; never ship it in an app. `oalo data` writes make
+  their own token limited to the tables written, the first time.
+
+`oalo login <workspace>` (their Base, `<workspace>.oalo.ai`; `--server <url>`
+for a custom domain) gets both: the person approves it in the dashboard
+(Account, CLI & agents), so ask them to run it rather than asking for tokens.
+If a command says it needs a CLI token, that is the fix. `oalo whoami` shows
+which workspace and person the CLI acts as and checks both tokens.
+`oalo help --json` describes every command, flag and exit code.
+
+## Deploying an app
+
+```sh
+oalo apps                            # the apps: slug, preview and live address, live release
+oalo deploy --new [<name>]           # this repo becomes a new app, its history kept
+oalo deploy --new --from <https url> # a repo on a Git host becomes an app, no checkout
+oalo deploy --app shop               # this branch's commits to the preview (dev)
+oalo deploy --app shop --env prod    # build and swap the live release
+```
+
+0. **A repo that isn't on Oalo yet** (the person wants to host their code):
+   check `oalo apps` first, then run `oalo deploy --new` from the repo's root.
+   It needs no Dockerfile, no git remote and no credential besides the login:
+   Oalo works out the kind of app from the files at the root and starts a
+   preview. Don't write a Dockerfile or create the app in the dashboard first.
+   If the deploy says it couldn't tell what the app is (a monorepo, an unusual
+   framework), `oalo docs bring-your-repo` says what to add. When the code is
+   on a Git host and not checked out here, `oalo deploy --new --from <https
+   url>`; for a private repo the person puts a read token in an environment
+   variable and you pass `--token-env VAR`. Never put a token in the URL or a
+   flag.
+1. **Commit first.** A deploy sends commits; uncommitted changes are not sent.
+2. **Preview first, live when the person says so.** `--env prod` changes what
+   live visitors see as soon as the build passes. A failed build leaves the old
+   release live.
+3. **If a deploy is refused because the app has commits you don't** (the builder
+   agent or a teammate changed it on Oalo): `oalo deploy --app shop --pull`, then
+   `git merge oalo/shop`, then deploy again. Don't use `--replace` unless the
+   person wants their branch to overwrite the app's code: it discards what was
+   made on Oalo (it is tagged, so it can be recovered).
+4. **How Oalo starts a server app:** a `Procfile` (`web:` serves HTTP, other
+   lines are workers, `release:` runs once per live deploy, e.g. migrations),
+   else package.json `start` (`dev` in the preview), else the runtime's default
+   (index.js, main.py, app.py, manage.py). The app must listen on `$PORT`.
+   When a repo starts some other way, add a Procfile rather than renaming files.
+5. **When an app doesn't start or misbehaves, read its logs first:**
+   a dev deploy whose preview doesn't run says so and exits 1 (the code is
+   saved).
+   `oalo logs --app <slug> [--env prod]` (MCP: `oalo_app_logs`). Fix the repo
+   yourself; `oalo setup` (an agent on the Base does it on a branch for the
+   person to accept) is for when they ask for it. A live deploy
+   only swaps once the new release answers on its port; one that crashes
+   brings the previous release back, and the error shows its last lines.
+   When the live app went down or keeps restarting, `oalo incidents --app
+   <slug>` says when and why: a memory kill names the size to raise in
+   `.oalo/app.json`.
+6. **Rolling back** (`oalo deploy --rollback`, MCP: `oalo_releases`) changes what
+   live visitors get: only when the person asks. `--history` lists the
+   releases.
+
+## An app's environment variables
+
+```sh
+oalo env --app shop                                    # dev's variables; secrets show only as "secret"
+oalo env set API_BASE_URL=https://api.example.com --app shop --public
+oalo env set --file .env.production --app shop --env prod
+oalo env unset OLD_FLAG --app shop
+```
+
+1. **Never handle a secret value.** When the app needs a key the person holds
+   (a payment or model provider key, a password), don't ask them to paste it to
+   you, and don't put it in a command, a file or your reply. Tell them to run
+   `oalo env set NAME --secret --app <slug>` themselves: it asks for the value
+   without showing it. You may set public values (URLs, switches) yourself.
+2. **Keys go to server apps only.** A static app (React, Expo, Flutter) never
+   gets secret variables, because its build ships to the visitor's browser.
+   Don't get a key into one with `--public` or a `VITE_`/`EXPO_PUBLIC_` name.
+   Have the static app call a server app that holds the key.
+3. **dev and prod are separate sets.** 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), so change prod only when the person says so. Don't
+   run `oalo deploy --env prod` to apply a variable: that also ships whatever
+   is committed. `--no-restart` batches several changes; the last one without
+   it relaunches.
+4. **Read them from the environment in code** (`process.env.NAME`,
+   `import.meta.env.VITE_NAME`), and don't commit `.env` files with values.
+   `oalo docs app-environment` has the details.
+
+## What your app gets from Oalo
+
+Each of these is a few lines of the app's own code. Read its page before
+writing it: the endpoints, headers and shapes are there.
+
+| To | Do | `oalo docs` |
+|---|---|---|
+| Call Oalo from a server app | Use `OALO_URL` and `OALO_SYNC_TOKEN`, already in its environment (data, events, workflows, chat; locked to its env). `DATABASE_URL` is its PostgreSQL. | `app-environment` |
+| Start workflows when something happens in the app | `POST /api/events/v1` with an `app.*` name, or `oalo data events <table> created updated` for row changes, then a loop trigger on that event. Check with `oalo emit <event> --dry-run`. | `app-events` |
+| Run a workflow like a function | Give the loop an `api` trigger; the app calls `POST /api/workflows/v1/<name>/run`. | `workflow-calls` |
+| Let a bot call the app's endpoints | Declare them in `.oalo/app.json`, deploy, then `oalo bots tools <bot> --add <tool>`. The calls are signed. | `app-tools` |
+| Put a bot on the app's pages | One script tag (`chat-widget.js`), signed in as the app's user through `POST /api/chat/v1/sessions`. | `chat-widget` |
+| Sign members in and sync their data | An email code, then `@synclib-io/client`. | `connect-your-own-frontend` |
+| Take rows from another system | `oalo sources create <name> ...` gives it an address to post to. A system that can't post: `oalo sources fetch <name> <https url>`, or a view in its own database: `oalo sources fetch <name> "$DB_URL" --relation <schema.view> --cursor updated_at`. Documents for a bot: `--bot <bot>`. | `data-sources` |
+| Run the app on this machine | The person makes a dev-only token (`oalo tokens create --name local --scope read,write,events,workflows,chat,env:dev`) and puts it in an uncommitted `.env`. Its events and workflow calls are test runs. | `tokens-and-credentials` |
+| Give the live app more CPU or memory, a health check, or required variables | All in one committed file, `.oalo/app.json`: `{"sizes": {"web": "medium"}, "health": "/healthz", "env": {"required": ["STRIPE_KEY"]}}`. A live deploy is refused while a required variable isn't set for prod. There is no `infra.json`. | `live-server-apps` |
+| Show the app's own numbers to its users (a chart in the app) | `queryMetric({ table: "sessions", every: "week", days: 90, by: "coach_id" })` from `oalo typegen`, called on the app's server. | `dashboards` |
+| Work on an app made from Oalo's Flutter template on this machine | `oalo typegen --dart` (the models, and `.oalo/dart-defines.json`), then `flutter run -d chrome --dart-define-from-file=.oalo/dart-defines.json`. | `flutter-on-your-machine` |
+
+## Selling: products and paid content
+
+```sh
+oalo products                                                    # what the workspace sells, by id
+oalo products create premium --name "Premium" --price 9.99 --monthly   # test key; --once, --yearly
+oalo typegen                                                     # PRODUCTS and the ProductId type
+oalo products orders premium
+```
+
+1. **The id is what code names.** Run `oalo products` and use an id it lists;
+   if what the app sells isn't there, create it. After a create, run `oalo
+   typegen` and type product ids as `ProductId` (Dart: the `Products`
+   class), so a typo doesn't compile. The id goes in `BuyButton
+   productId`, in a row's `product_id` (with `availability` `product`, or
+   `premium` for any subscriber), and is what a member's
+   `purchased_products` holds.
+2. **The server does the locking.** A locked row reaches the app with
+   `_stripped: true`: show the paywall on that (`oalo docs commerce` has the
+   checkout and paywall code). Never decide access in the
+   app from `availability` or by hiding rows.
+3. **Payments run on the workspace's own Stripe key,** which the person
+   pastes in the dashboard's Payment settings. Never ask for it. Create
+   products with the test key; `--live` is for when the person says to sell
+   for real, and needs `--yes` (so does a price over 500).
+4. **Buyers are affected at once.** `price` (new buyers pay it, subscribers
+   keep theirs) and `archive` (no longer sold; buyers keep access) only when
+   the person asks. Archive, don't delete: `delete` is for an archived
+   product nobody bought.
+
+## Numbers and dashboards
+
+```sh
+oalo metrics orders --sum total --by status --days 30 --where "status != test"   # a number, now
+oalo metrics contacts --every week --days 90             # also: events --event order.created
+oalo dashboards                                                                   # the dashboards
+oalo dashboards add Sales orders --title "Revenue by plan" --kind bars --sum total --by plan --days 30
+```
+
+1. **A question about numbers** (how many, how much, per week): `oalo metrics`
+   (MCP `oalo_query_metrics`). Don't read rows and add them up.
+2. **A chart the person wants to keep** goes on a dashboard with `oalo
+   dashboards add` (MCP `oalo_save_dashboard_widget`); the dashboard is made
+   when none has that name. Check `oalo dashboards` first: the same title
+   replaces a chart. Everyone with access sees it, so say which dashboard.
+3. **The workspace's own numbers are a dashboard, not an app.** Don't build or
+   deploy a page for them. An app's charts for its own users call `queryMetric`
+   (from `oalo typegen`) on the app's server.
+
+## Bots
+
+```sh
+oalo bots                                            # the bots, by public id (bot_...)
+oalo data vectorize products --fields title,description   # make a table searchable
+oalo bots knowledge bot_ABC --add products           # let the bot search it
+oalo bots tools bot_ABC --add order_status           # let it call a tool
+oalo bots settings --explain model                   # what each setting does
+oalo bots settings bot_ABC set <key>=<value> --dry-run
+oalo channels                                        # WhatsApp, Instagram, email, web chat: which bot answers
+```
+
+1. **To make a bot answer from a table,** vectorize the table, then attach it
+   with `oalo bots knowledge`. Attaching alone does nothing for a table that
+   isn't searchable.
+2. **Read a setting with `--explain` before changing it.** Don't guess keys or
+   values.
+3. **A published bot is live for customers.** `set` on one shows the change and
+   saves nothing unless you pass `--yes`: show the person the `--dry-run` and
+   use `--yes` only when they say so.
+4. **Test with `oalo qa`** after any change to what a bot knows or how it
+   answers.
+5. **Which bot answers a WhatsApp number or an Instagram account:**
+   `oalo channels` lists them, `oalo channels set whatsapp "<number>" --bot
+   <bot>` changes it at once for every customer writing in, so only when the
+   person asks. Connecting a number needs Meta's sign-in in a browser: `oalo
+   channels connect whatsapp --bot <bot>` prints the link for the person to
+   open. Never ask for their Meta login or token.
+6. **A field the bot must never see** (a cost price, an internal note):
+   `oalo data keep-from-ai <table> cost_price`. It stays stored and synced,
+   but the bot's data tools leave it out, and it can't be embedded. Don't
+   vectorize it.
+
+## Reading the docs
+
+Before building on a feature you don't know, read Oalo's own docs. They come
+from the workspace's own server (its Base), so they match what it runs:
+
+```sh
+oalo docs --search "data models owner"   # find the page
+oalo docs data-models                     # read it (markdown)
+oalo docs                                 # every page, with a one-line summary
+```
+
+Over MCP: `oalo_docs` with `q` or `slug`. Good first pages:
+`bring-your-repo` and `connect-your-own-frontend` for your own code,
+`app-environment`, `tokens-and-credentials`, `data-models`, `sync-rest-api`
+and `triggers-and-chaining`.
+
+For anything the commands don't cover, `oalo call --list <text>` lists the
+events you may call and the params each accepts (MCP: `oalo_call` with event
+`cli_api:events` and `{"q": "<text>"}`). Don't guess param names: a wrong
+shape is refused with the shapes the event takes.

package/src/api.js

@@ -0,0 +1,132 @@
+/** Minimal Sync API client. No dependencies — fetch is built in on Node 18+. */
+
+export class ApiError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export async function syncGet(path, { serverUrl, token, env }) {
+  const url = new URL(`${serverUrl.replace(/\/$/, "")}/api/sync/v1${path}`);
+  if (env) url.searchParams.set("env", env);
+
+  let res;
+  try {
+    res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+  } catch (e) {
+    // A bad host is by far the most common setup mistake, so name it.
+    throw new ApiError(`could not reach ${serverUrl} (${e.message})`, 0, null);
+  }
+
+  const text = await res.text();
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    /* non-JSON (a proxy error page, say) */
+  }
+
+  if (!res.ok) {
+    // 403 here almost always means the token lacks the scope, which is the
+    // failure worth spelling out rather than echoing a bare status.
+    //
+    // `error` is not always a string: some replies nest an object, and
+    // interpolating one yields the useless "[object Object]". Flatten to
+    // something a human can act on, and never lose the status.
+    throw new ApiError(errorDetail(body, text) || `HTTP ${res.status}`, res.status, body);
+  }
+
+  return body;
+}
+
+export const fetchManifest = (cfg) => syncGet("/manifest", cfg);
+
+/**
+ * The workflows apps can call, with their input and output. `[]` from a
+ * workspace too old to have the route (404), so typegen still works there.
+ */
+export async function fetchWorkflows({ serverUrl, token }, fetchImpl = fetch) {
+  let res;
+  try {
+    res = await fetchImpl(new URL(`${serverUrl.replace(/\/$/, "")}/api/workflows/v1`), { headers: { Authorization: `Bearer ${token}` } });
+  } catch (e) {
+    throw new ApiError(`could not reach ${serverUrl} (${e.message})`, 0, null);
+  }
+  if (res.status === 404) return [];
+  const text = await res.text();
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    /* non-JSON */
+  }
+  if (!res.ok) throw new ApiError(errorDetail(body, text) || `HTTP ${res.status}`, res.status, body);
+  return body?.workflows || [];
+}
+
+/**
+ * Any Sync API call, for the data commands. Unlike `syncGet` it hands back the
+ * status and headers on success too, because a bulk writer needs the rate-limit
+ * headers to pace itself.
+ *
+ * `query` values that are null or undefined are left out. `fetchImpl` is for
+ * tests.
+ */
+export async function syncRequest(method, path, { serverUrl, token, env }, { query = {}, body, fetchImpl = fetch } = {}) {
+  const url = new URL(`${serverUrl.replace(/\/$/, "")}/api/sync/v1${path}`);
+  if (env) url.searchParams.set("env", env);
+  for (const [k, v] of Object.entries(query)) if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+
+  const headers = { Authorization: `Bearer ${token}` };
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+
+  let res;
+  try {
+    res = await fetchImpl(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+  } catch (e) {
+    throw new ApiError(`could not reach ${serverUrl} (${e.message})`, 0, null);
+  }
+
+  const text = await res.text();
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    /* non-JSON */
+  }
+
+  if (!res.ok) {
+    const err = new ApiError(errorDetail(parsed, text) || `HTTP ${res.status}`, res.status, parsed);
+    err.headers = res.headers;
+    throw err;
+  }
+
+  return { status: res.status, body: parsed, headers: res.headers };
+}
+
+/**
+ * Pull a human-readable reason out of an error body.
+ *
+ * The API is not uniform here: a 401 replies
+ *   {"error":{"code":"invalid_token","message":"Missing or invalid ..."}}
+ * while a scope failure replies {"error":"token lacks read scope"}. Handle both,
+ * prefer the nested `message` over dumping JSON, and keep the `code` since it is
+ * the part worth searching for.
+ */
+function errorDetail(body, text) {
+  const e = body?.error ?? body?.reason ?? body?.message;
+
+  if (typeof e === "string" && e) return e;
+
+  if (e && typeof e === "object") {
+    const msg = typeof e.message === "string" ? e.message : null;
+    if (msg) return e.code ? `${msg} (${e.code})` : msg;
+    return JSON.stringify(e);
+  }
+
+  if (body && typeof body === "object" && Object.keys(body).length) return JSON.stringify(body);
+  return (text || "").trim().slice(0, 200);
+}

package/src/app-ref.js

@@ -0,0 +1,11 @@
+/**
+ * An app named on the command line, by slug (what `oalo apps` shows and
+ * `oalo deploy --app` takes) or by id (what the pulled loop files use under
+ * `.oalo/loops/apps/<id>/`). Returns the app's id, or throws with what to do.
+ */
+export async function appIdFor(ch, ref) {
+  const { apps = [] } = await ch.call("list_apps", {});
+  const app = apps.find((a) => a.slug === ref || a.id === ref);
+  if (!app) throw new Error(`no app ${ref} in this workspace. \`oalo apps\` lists them.`);
+  return app.id;
+}