@oxy-hq/cli 0.8.0 → 0.10.0

package/skills/oxy-custom-apps/SKILL.md

@@ -1,36 +1,47 @@
 ---
 name: oxy-custom-apps
-description: Use when building, debugging, reviewing, or shipping an Oxy custom-app bundle (a code-first React/Vite app served by oxy), including writing Oxy Functions and driving them from the UI. Encodes the contract rules, pitfalls, performance guardrails, and the self-serve `oxyc publish` ship flow.
+description: >-
+  Use when building, debugging, reviewing, shipping, or verifying an Oxy
+  custom-app bundle (a code-first React/Vite app served by Oxy at
+  /customer-apps/<org>/<slug>/), including writing Oxy Functions, driving them
+  from the UI, and checking a published app in the browser with the Playwright
+  MCP server (no CI checks a published bundle). Covers the oxy-app.json
+  contract, @oxy-hq/sdk and @oxy-hq/vite-plugin, where app data goes
+  (ctx.airhouse, ctx.oltp, ctx.storage), pitfalls, performance guardrails, load
+  speed and usage tracking (service worker, Activity tab, useTrackEvent), the
+  self-serve oxyc publish ship flow, dev-<handle> sandboxes and workspace
+  previews, how an AI agent gets its own short-lived credential (oxyc tokens
+  create --sandbox-agent or --agent, never the engineer's oxyc login), and
+  reading a deployment's live data with oxyc api and oxyc proxy (which replaced
+  oxy api and the Rust oxy login, publish and proxy).
 ---
 
-# Customer-app development
+# Custom-app development
 
-Customer-app bundles are arbitrary JS apps served by oxy at
+Custom-app bundles are arbitrary JS apps served by Oxy at
 `https://<env>/customer-apps/<org>/<slug>/`. Oxy is a data gateway:
 serves static assets, gates cookie auth, and proxies queries. The
 bundle is opaque above the data plane — no per-app server config.
 
+This file is the contract. The detail lives in `references/` — see
+[Read next](#read-next) for which file answers what.
+
 ## The Oxy App Kit (use it)
 
 Two small packages remove the footguns — default to them rather than wiring a
 bundle by hand:
 
 - **`@oxy-hq/sdk`** — the data layer (`useQuery`, `useSemanticQuery`,
-  `useAgentRun`, `<OxyChat>`); see rule 2 and `oxy-hq/customer-apps:
-  docs/sdk-flow.md`.
+  `useAgentRun`, `<OxyChat>`); see rule 2 and the `@oxy-hq/sdk` README.
 - **`@oxy-hq/vite-plugin`** (`oxyApp()` in `vite.config.ts`) — bakes the asset
   **base path** from the manifest, copies `oxy-app.json` into `out/`, proxies
   `/api` in dev, and injects the `window.__OXY_APP__` shim. Dropping it
   re-introduces the #1 bug — asset 404s → blank dashboard (rule 3).
 
-Scaffold both with `@oxy-hq/create-oxy-app` or by copying `oxy-hq/customer-apps:
-examples/hello-oxy/`. The
-platform is kit-agnostic (any bundle with a correct base path works), but
-hand-rolling means owning the base-path + dev-proxy wiring yourself.
-
-(**`oxy-hq/customer-apps:` prefixes a path in that repo**, not in whatever repo
-you are sitting in. This skill loads globally, so every such pointer is
-qualified.)
+Scaffold both with `pnpm create @oxy-hq/oxy-app my-app` (templates `vite` — the
+default — `functions`, `dashboard`, `single-store`; `-t functions` adds Oxy
+Functions). The platform is kit-agnostic (any bundle with a correct base path
+works), but hand-rolling means owning the base-path + dev-proxy wiring yourself.
 
 ## Three rules
 
@@ -39,6 +50,7 @@ qualified.)
 
    ```json
    {
+     "$schema": "https://unpkg.com/@oxy-hq/sdk/schema/oxy-app.schema.json",
      "schemaVersion": 2,
      "slug": "url-slug",
      "orgSlug": "your-org",
@@ -46,23 +58,44 @@ qualified.)
    }
    ```
 
-   Required: `schemaVersion` (must be `2`), `slug` (non-empty).
+   Required: `schemaVersion` (must be `2`), `slug` (1–63 lowercase
+   letters, digits and single hyphens — it becomes the served path and
+   the OLTP schema name).
    Strongly recommended: `orgSlug` (lets `@oxy-hq/vite-plugin` derive
    the asset base path automatically, so plain `pnpm build` produces
-   a bundle ready to drop into the linked org with no env var).
-   Optional: `name` (display), `projectId` (dev-time hint).
+   a bundle ready to drop into the linked org with no env var, and lets
+   `pnpm dev` and `oxyc publish` find the app without `--org` / `OXY_ORG`;
+   `create-oxy-app --org <slug>` writes it).
+   Optional: `name` (display), `description`, `icon`, `art`, `status`
+   (launcher card), `projectId` (dev-time hint), `build` (what `oxyc
+   publish` runs — `install`, `command`, `outDir`; the plugin reads
+   `outDir` too), `functions`, `env`, `storage`, `notifications`, …
+
+   **One contract.** The file is validated against the JSON Schema
+   `@oxy-hq/sdk` ships (`schema/oxy-app.schema.json`, generated from the
+   SDK's `OxyAppManifest` type; `$schema` gives your editor completion)
+   by `oxyc validate`, `oxyc publish`, the Vite plugin and the SDK's own
+   loader — the same check, the same words. A wrong type, a bad name or
+   a missing required field is refused; a field the schema does not know
+   is a **warning** (the platform ignores what it does not read — so a
+   typo'd `timeoutSecond` is said, not silently dropped). Every field and
+   what the server does with it: `OxyAppManifest` in
+   `@oxy-hq/sdk/manifest`, which also exports the schema, `isValidSlug`
+   / `isValidFunctionName` and `validateOxyAppManifest` for a tool of
+   your own.
 
    At serve time, oxy injects the authoritative org + project from
    the admin row via `window.__OXY_APP__` — the manifest's `orgSlug`
    and `projectId` are advisory hints only, never enforcement.
 
    Do not invent `products`, `writers`, or `from:`-blocks. Those
-   don't exist in v2 and the probe rejects them.
+   don't exist in v2 and the schema rejects them.
 
    File location: **`<root>/oxy-app.json`**, sibling to
-   `vite.config.ts`. The vite-plugin reads it from there; legacy
-   bundles that kept it under `public/` won't see the plugin's
-   base-path derivation kick in.
+   `vite.config.ts`. The vite-plugin reads it from there, and so does
+   `oxyc publish` (only from the directory it runs in); legacy bundles
+   that kept it under `public/` get neither the plugin's base-path
+   derivation nor the publish's `slug` / `orgSlug`.
 
 2. **All data flows through SDK hooks → oxy HTTP endpoints.** The
    surface is intentionally small:
@@ -86,8 +119,8 @@ qualified.)
    <OxyChat agentId="analytics" />
    ```
 
-   See `oxy-hq/customer-apps: docs/sdk-flow.md` for the full reference,
-   including `OxyApiError` parsing and beta-surface caveats.
+   See the `@oxy-hq/sdk` README for the full reference, including
+   `OxyApiError` parsing and beta-surface caveats.
 
    **Server-side work → Oxy Functions, not the browser.** `useQuery` &
    friends run in the client; for work the browser shouldn't do
@@ -118,9 +151,10 @@ qualified.)
    `ctx.storage` — and customer warehouses are read-only. See
    **Where data goes** below before writing anything.
    `oxyc publish` bundles `functions/*.ts` with
-   esbuild — no separate backend to stand up. Worked example +
-   author-facing `ctx` types: `oxy-hq/customer-apps:
-   examples/hello-oxy/functions/`.
+   esbuild — no separate backend to stand up. Author-facing types:
+   `OxyFunctionContext` / `OxyFunctionRequest` from `@oxy-hq/sdk`; a worked
+   example ships in the `functions` template (`pnpm create @oxy-hq/oxy-app
+   my-app -t functions`).
 
 3. **`OXY_APP_BASE_PATH` must match the path the bundle is linked
    under.** `@oxy-hq/vite-plugin` resolves it from (in order):
@@ -139,20 +173,12 @@ qualified.)
 | **Files** — photos, PDFs, exports | Your app's storage silo | `ctx.storage` | function: `"storage": { "read": true, "write": true }` |
 | **The customer's warehouse** — ClickHouse, Snowflake, BigQuery, their Postgres | Theirs | `ctx.query` · `ctx.warehouse.query(db, sql)` | read-only: a write is refused unless the function declares `"customerWarehouseWrites": { "<db>": "<why>" }` |
 
-**Availability.** `ctx.airhouse`, `ctx.oltp.tx`, `airhouseMigrations`, the
-read-only rule for customer warehouses and `oxyc validate`'s data-placement
-and manifest checks arrive with the Oxy release carrying oxygen-internal#3187,
-together with the `@oxy-hq/sdk` and `@oxy-hq/cli` published from it. Against
-an older Oxy, `ctx.airhouse` is `undefined` and the new manifest fields are
-ignored; vendored `oxy.d.ts` copies (`examples/hello-oxy/functions/oxy.d.ts`)
-gain the types when they are re-synced from that SDK.
-
 Three questions, in order: **Is it bytes?** → storage (keep the key in a record
 or fact). **Does it change after it's written?** No → a fact; yes → a record;
 both when you need history (the record says what is true now, the fact says
 what changed). **Is it already in the customer's warehouse?** → read it there.
 
-`<writer>` is your slug with `-` → `_` (`store-ops` → `app_store_ops`); a slug
+`<writer>` is your slug with `-` → `_` (`my-app` → `app_my_app`); a slug
 with `_` can't back a schema. Both stores are written **as the app**, whoever
 invoked the function, so a scheduled run writes like a click.
 
@@ -189,6 +215,90 @@ async function completeChecklist(ctx, runId: string, storeGuid: string) {
 }
 ```
 
+## Telling people something
+
+Name **people**; the platform reaches them. Don't build a recipient table, a
+"sent" log or a Slack webhook helper:
+
+```ts
+await ctx.notify({
+  to: { role: "Store Manager", location: storeId }, // or { userId } · { team }
+  kind: "list_overdue",                             // declared in oxy-app.json
+  title: "Opening list is 30 minutes late",
+  link: `/lists/${listId}`,                         // a path inside the app
+  email: true,                                      // optional; slack: true too
+  idempotencyKey: `overdue:${occurrenceId}`,        // retry-safe
+});
+```
+
+`oxy-app.json`: `"notify": { "kinds": { "list_overdue": {} } }` on the function
+(`{ "critical": true }` for a kind people must not mute). Everyone lands in
+their Oxygen inbox — frontline crew too, who have no email — and is pushed,
+emailed or Slacked where they can be. `slack: true` DMs each person's own Slack
+account (found by their email once the org has connected Slack), so an app
+never holds a Slack token or maps users to Slack ids. Needs the org's OLTP
+store. Use
+`ctx.email.send` only for addresses **outside** the org (a vendor, an
+accountant), and give it an `idempotencyKey` in a scheduled function.
+
+### Categories, levels, threads and actions
+
+Describe your kinds once, at the top level of `oxy-app.json`. It is the tree
+people mute in (a whole app, a category, or one kind) and the one a phone groups
+by, so declare it with the first `ctx.notify`, not later:
+
+```json
+"notifications": {
+  "categories": {
+    "operations": { "label": "Store operations" },
+    "operations/food-safety": { "label": "Food safety" }
+  },
+  "kinds": {
+    "list_overdue": { "category": "operations", "label": "Overdue lists", "level": "time_sensitive" },
+    "temp_alarm": { "category": "operations/food-safety", "label": "Temperature alarm", "level": "critical",
+                    "actions": [{ "id": "ack", "label": "Acknowledge", "function": "ack-alarm" }] }
+  }
+}
+```
+
+- **Category**: a path of up to 3 segments (`a-z0-9`, `_`, `-`); a declared
+  path's parents need no entry. A kind with none is in `general`.
+- **Level**: `passive`, `active` (default), `time_sensitive`, `critical`. Only
+  `critical` ignores mutes; a function's `"critical": true` still makes it so.
+- **Actions**: at most 3, label ≤ 24 characters. With `function` (one this app
+  declares), a tap calls it as the person with `{ notificationId, action, link }`
+  and marks it read; without, it opens the link.
+- **Thread**: ``ctx.notify({ …, thread: `store:${storeId}` })`` (≤ 128
+  characters) folds a run of notifications about one thing into the newest.
+- The function's `notify.kinds` still decides what it may send; a kind it sends
+  that the catalogue leaves out gets the defaults. `oxyc validate`, the Vite
+  plugin (`pnpm dev` / `pnpm build`) and `oxyc publish` refuse a malformed or
+  unknown category, a bad level, more than 3 actions, an action naming an
+  undeclared function, a misspelt field and any `oxy.` kind — every problem at
+  once; a catalogue kind no function sends is a warning.
+
+The app opens in its own tab, so show the inbox **in the app** — people who
+live in it (crew on a kiosk) never see Oxygen's bell:
+
+```tsx
+import { NotificationsBell } from "@oxy-hq/sdk";
+
+<NotificationsBell onNavigate={(link) => navigate(link)} /> // in the header
+```
+
+It lists this app's notifications (`scope="all"` for the whole inbox), each
+with its category under the title, `critical` and `time_sensitive` ones marked,
+and threads folded; a tap
+hands the `link` you passed to `ctx.notify` to `onNavigate` (without it, the
+page loads that path under the app's base). It renders nothing where there is
+no inbox (signed out, an older server, `pnpm dev`). `useNotifications()` gives
+`{ items, unread, markRead, markAllRead, refresh, … }` to draw your own, and
+takes `{ category, kind, thread }` to narrow it. Theme
+it with `--oxy-notifications-*` CSS variables. Push sign-up and mutes stay in
+Oxygen's Settings → Notifications — don't build them. In tests,
+`createTestInbox({ manifest })` from `@oxy-hq/sdk/testing` is a fake inbox to pass as
+`<OxyAppProvider fetcher={inbox.fetcher}>`.
+
 ## Four pitfalls
 
 - **CORS errors are usually wrong-URL errors in disguise.** The SDK's
@@ -211,154 +321,140 @@ async function completeChecklist(ctx, runId: string, storeGuid: string) {
   rely on the nil UUID `00000000-...` as a default project; don't
   assume `OXY_STATE_DIR` is writable.
 
-## Performance guardrails
-
-Any app that ships an Oxy Function or drives a batch of them should keep these —
-cheap up front, hard to retrofit. (Established by the pokehouse `post-je` function.)
-
-**In an Oxy Function — count the round-trips.** Each isolate run is stateless and
-pays a fresh network hop per `ctx.query` / `ctx.warehouse.*`, so serial *dependent*
-calls dominate latency.
-- Run independent data-plane calls with `Promise.all`, not sequential `await`
-  (e.g. resolve reference data **and** provision tables concurrently — only the
-  final step needs both).
-- Fold a check into a query that already runs: a duplicate/existence guard is a
-  scalar subquery on the main `SELECT`, not a second round-trip.
-- `Promise.all` idempotent DDL (`CREATE TABLE IF NOT EXISTS`); better, keep
-  provisioning off the hot path if a migration can own it.
-- A "cheap" extra `ctx.query`/`ctx.log` is N× the cost across N invocations.
-
-**Driving many function calls from the UI (bulk actions) — don't go serial.**
-- Independent calls run with **bounded concurrency** (~3–4) via a worker-pool over a
-  queue, not one-at-a-time — turns an O(N) wall-clock batch into a few waves.
-- If the calls share mutable server state that races under concurrency (a rotating
-  token, a lazily-created table), the best fix is to **remove the shared mutation**
-  (e.g. a single-writer scheduled refresher owns the token; requests only read).
-  When you can't, warm the state with one call first, then fan out.
-- Don't refetch derived state (a status ledger) after *every* item — the progress UI
-  is the live feedback; **throttle** the refetch (~1/s) and flush once at the end.
-- Guard `setState` after the component may have unmounted mid-batch (`mounted` ref).
-
-**Trust the server, not the client body.** Environment / tenant / which-secret
-selection is derived server-side (a function secret, a server-side mapping table,
-the authed identity), never from the request body — validate or override anything
-the client sends that picks a target.
-
-**Reuse the SDK's data-plane caching.** `useQuery` already dedups concurrent identical
-queries and short-caches results — don't hand-roll a fetch that bypasses it. Mark
-read-only functions `cache: { ttlSeconds }` in the manifest; **never** cache a
-side-effecting one (it silently drops writes). `idempotencyKey` = a fresh UUID
-per ATTEMPT (click), never a stable per-subject key: the server stores each
-key's response indefinitely and replays it WITHOUT running the function, so a
-`store:period` key silently breaks any post → compensate (delete) → post-again
-cycle — the second post "succeeds" with the stale response and writes nothing.
-The key shields one request from transport duplication; cross-attempt dedup
-belongs in the function itself (a server-side guard over real state, e.g. a
-posted-ledger row the compensating action clears).
-
-**Watch-outs when optimizing (each surfaced in review):**
-- **Clear UI running-state in `finally`.** An async batch driver must reset its
-  `running`/loading flag (and do its final refetch) in a `finally`, not after the
-  `await` — a stray throw otherwise leaves the bar stuck at "…" with the button
-  disabled.
-- **Parallelizing can move a side effect ahead of a gate.** Running an independent
-  side-effecting call concurrently with a validation query means it can now fire
-  even when validation would reject. Fine if the side effect is benign — just know
-  you traded the ordering for the latency.
-- **Additive migration for a scoped guard → backfill legacy rows to their TRUE value,
-  not a constant.** When a dedup/uniqueness guard starts keying on a new column,
-  `ADD COLUMN … DEFAULT <constant>` silently defeats the guard for pre-existing rows.
-  Derive the real value from an existing column (e.g. a DocNumber prefix) so old rows
-  stay correctly scoped.
-
-## Minimal starter
-
-Easiest path: `pnpm dlx @oxy-hq/create-oxy-app@latest my-app --template vite`.
-The scaffolded layout:
-
-```
-my-app/
-├── oxy-app.json            ← project root, not public/
-├── src/
-│   ├── App.tsx
-│   └── main.tsx
-├── package.json
-├── vite.config.ts
-└── tsconfig.json
-```
-
-`oxy-app.json`:
-```json
-{ "schemaVersion": 2, "slug": "my-app", "orgSlug": "test", "name": "My App" }
-```
-
-`src/main.tsx`:
-```tsx
-import { OxyAppProvider } from "@oxy-hq/sdk";
-import { createRoot } from "react-dom/client";
-import { App } from "./App";
-
-createRoot(document.getElementById("root")!).render(
-  <OxyAppProvider><App /></OxyAppProvider>
-);
-```
-
-`src/App.tsx`:
-```tsx
-import { useQuery } from "@oxy-hq/sdk";
+Two more that read as bugs — `useTrackEvent("oxy-…")` is refused (`400`,
+the prefix is reserved), and a hovered-but-never-opened app records no view —
+are in [references/performance-and-usage.md](references/performance-and-usage.md).
 
-export function App() {
-  const { rows, loading, error } = useQuery({
-    sql: "SELECT 1 AS hello",
-  });
-  if (loading) return <p>loading…</p>;
-  if (error) return <p style={{ color: "red" }}>{error.message}</p>;
-  return <pre>{JSON.stringify(rows, null, 2)}</pre>;
-}
-```
+## Run a function locally
 
-`vite.config.ts`:
-```ts
-import oxyApp from "@oxy-hq/vite-plugin";
-import react from "@vitejs/plugin-react";
-import { defineConfig } from "vite";
+`oxyc fn dev <name>` runs one handler from your source in-process, in seconds,
+with no publish. It bundles the handler with the same esbuild call `oxyc publish`
+uses, then invokes it on `createTestContext` seeded from `oxy-app.json`: the
+function's capabilities, `ctx.env` from the env file, and its destinations. It
+prints the response, then the host ops the handler made.
 
-export default defineConfig({
-  plugins: [react(), oxyApp()],
-});
+```bash
+oxyc fn dev notify --input '{"name":"Ada"}'            # a literal, @file, or - for stdin
+oxyc fn dev notify --input @sample.json --env-file .env.dev --watch
+oxyc fn dev report --read-through --env dev     # reads hit that deployment; writes stay stubbed
 ```
 
-The plugin handles `outDir = "out"`, base-path resolution from the
-manifest, dev-server proxy to `/api`, and the `window.__OXY_APP__`
-dev shim. Plain `pnpm build` produces a bundle with the correct
-asset base baked in.
+- **Run it from the app directory** (the one with `oxy-app.json`). `--env-file`
+  defaults to `.env`; `ctx.env` holds that file's keys and nothing from your
+  shell. A `required` secret the file lacks is a warning.
+- **`--watch` re-runs** when a file in the app changes, reading the manifest,
+  env file and `@file` input afresh. A broken edit prints its error and waits
+  for the next save. Exit with Ctrl-C.
+- **Exit codes:** `0` for a 2xx `Response`; `1` when the handler throws or
+  answers non-2xx (as `fn call`); `2` for a function the manifest does not
+  declare, or a missing env file.
+- **A local run is not the isolate.** There is no timeout, memory or log cap;
+  `Buffer`, `TextEncoder` and `process` exist where the isolate lacks them; and
+  every warehouse, semantic, storage, fetch and email call is a stub in memory,
+  so (without `--read-through`) nothing reaches a deployment. The context does refuse what the manifest
+  does not grant, in the host's words. A `ctx.warehouse` destination's engine is
+  assumed (a `customerWarehouseWrites` entry is a customer Postgres, any other
+  is Airhouse), because the workspace config is not read.
+- **`--read-through` reads real data, and only reads.** It sends `ctx.query`,
+  `ctx.warehouse.query` and `ctx.semantic.query` to the deployment `--env <name|url>`
+  (or `--target`) names, through the app's own `POST /api/projects/{project}/query`
+  and `/semantic-query`, with your `oxyc login` bearer or `OXY_TOKEN` (the way
+  `oxyc api` authenticates). What you may read is the server's decision. The
+  project is `--project` / `OXY_PROJECT`, else looked up from `oxy-app.json`
+  `slug` + `orgSlug`. Every other call (warehouse writes, `ctx.tx`, `ctx.oltp`,
+  `ctx.airhouse`, storage, fetch, email, notify, and `ctx.queryStream`) stays a
+  stub in memory and never leaves your machine. Each call in the report is marked
+  `real` or `stubbed`. `--env` defaults to production, so name a dev environment
+  when you can. A sandbox agent token is refused: use a person's login.
+  `ctx.semantic.query` row keys are `view__member` in the isolate but the route
+  strips the prefix, so read-through puts it back from your spec; a key it could
+  not map unambiguously stays as the route named it, so confirm that one with
+  `fn call` on a sandbox. Still not the isolate.
+- Before you ship, run it where it really runs: publish to your sandbox and
+  `oxyc fn call`, or `oxyc checks run`. For a committed regression test use
+  `createTestContext` from `@oxy-hq/sdk/testing` in vitest, as the functions
+  template does.
 
 ## Publishing
 
-Ship with `oxyc publish` — **no CI, no S3 sync, no folder picker**. From
-the app directory (`oxy-hq/customer-apps: examples/hello-oxy/` is the worked
-shell; note its manifest deliberately carries no `orgSlug`, leaving the org to
-be resolved at publish time):
+**These commands are a person's, or an agent's on a token that person
+approved.** `oxyc login` is the engineer's own browser login, and a publish to
+a channel or a promote is refused under a sandbox agent token. As an agent,
+iterate in your own sandbox
+([references/sandbox-agent-loop.md](references/sandbox-agent-loop.md)). Ship
+only when your engineer asked you to, on an agent token they approved
+(`oxyc tokens create --agent`, plus `--standing` for staff access): it
+publishes and promotes as them. With no browser on your machine, see
+[Headless and cloud sessions](#headless-and-cloud-sessions): a token approved
+there never carries staff access.
+
+Ship with `oxyc publish` (`npm i -g @oxy-hq/cli`) — **no CI step, no S3 sync,
+no folder picker**. From the app directory:
 
 ```bash
 oxyc login --env production    # once; browser flow, caches a token,
                                # and prints whether you're an app-admin
-oxyc validate                           # data-placement and manifest checks first
-oxyc publish --env production           # build → tar → upload (draft channel)
-oxyc publish --env production --promote # …straight to live
+oxyc validate                           # schema, data-placement and function checks first
+oxyc publish --env production           # build → bundle functions → tar → upload (draft = staging)
+oxyc promote <org>/<app> --env production --dry-run   # the plan: changes, migrations, blockers
+oxyc promote <org>/<app> --env production             # staging's build → production (asks first)
+oxyc rollback <org>/<app> --env production --app-env production   # back to the build before
 ```
 
-- **Identity** is the manifest's `slug` + `orgSlug` (override with
-  `--app` / `--org`). The server upserts the app row — there is no
-  separate `oxy apps create` step.
-- **First publish of a new app** needs `--project <workspace-uuid>`: the
-  build-config lookup can't resolve a project until the app exists. Drop
+Production only ever serves a build staging has served, and every way of
+moving it — `oxyc promote`, `oxyc rollback`, the console's **Promote draft**
+and **Roll back to…**, a promoting publish — applies the build's pending migrations **before** it moves
+(a failure leaves the old build live). `promote` and `rollback` print the plan
+first and refuse on a blocker: `staging_never_served`, `required_secrets_unset`
+(set the key in production first), `schedule_removal_unconfirmed` (pass
+`--remove-schedule <function>`). Off a terminal pass `--yes`.
+`oxyc publish --promote` still works and warns that it is deprecated: it shows
+nobody the plan.
+
+- **Identity**, for each half, is `--app` / `--org`, then `OXY_APP` /
+  `OXY_ORG`, then the manifest's `slug` + `orgSlug`, then an
+  `apps/<org>/<app>/` working directory. `--org` takes a slug or a UUID; pass
+  the slug whenever `oxyc` runs the build, because the asset base path is
+  baked from what you pass. With no org from any of those, the build stops
+  with `missing org: the app's base path needs it` (exit `2`): add
+  `"orgSlug"` to `oxy-app.json` (`create-oxy-app --org <slug>` writes it)
+  or `--org <org-slug>`, and `--app <slug>` when the directory has no
+  manifest. The server upserts the app row — there is no separate create
+  step.
+- **First publish of a new app is one step.** The app is not registered
+  yet, so the build-config lookup 404s; with your login `oxyc publish` then
+  lists the org's workspaces, and when there is exactly one (a freshly
+  provisioned org) publishes into it and says which. With several it prints
+  them with their uuids beside the flag to pass — `--project
+  <workspace-uuid>` (or `OXY_PROJECT`), which also supplies the org. Drop
   the flag after the first publish — it's auto-resolved from then on.
-- **`--env` targets:** `local` → the oxy web-app Vite dev server `:5173`
-  (run `pnpm dev` there; it serves `/cli-auth` and proxies `/api` to
-  oxy on `:3000`), `dev`/`staging`/`production` →
-  `app{-dev,-staging,}.oxygen-hq.com`.
-- `--dir out` skips the build and uploads a prebuilt directory.
+  Trusted publishing (CI) only ever publishes a registered app.
+- **Old kit.** Before the build, an app whose `@oxy-hq/sdk` or
+  `@oxy-hq/vite-plugin` is more than one minor behind the versions this
+  `oxyc` was built with gets one warning naming the `pnpm add` — the
+  manifest contract and the function runtime move with them.
+- **`--env` targets:** `local` → a local Oxy web-app Vite dev server `:5173`
+  (it serves `/cli-auth` and proxies `/api` to oxy on `:3000`), `dev` →
+  `aip.dev.oxy.tech`, `staging` → `aip.staging.oxy.tech`, `production` (the
+  default) → `app.oxygen-hq.com`. A value with a `.`, `/` or `:` is read as a
+  URL.
+- **Function lint.** Before the build, each Oxy Function's source is checked
+  for what the host would refuse at the first call: a `ctx.*` call whose
+  capability the manifest lacks, a global the isolate does not have
+  (`Buffer`, `TextEncoder`, `process`, …), a write outside `destinations`. A finding fails
+  the publish (exit `1`); `--allow-function-lint` publishes past a false
+  positive.
+- `--dir out` skips the build and uploads a prebuilt directory (declared
+  functions are still bundled into it); `--build-only` builds and bundles
+  without a credential or an upload; `--prebuilt` (with `--dir`) uploads a
+  directory whose functions are already bundled. Server warnings print on
+  stderr; `--json` prints the result.
+- `.env.local` / `.env` are loaded from the app directory and its parents
+  (never overriding what is already set), so a stray `OXY_PROJECT` there
+  retargets a publish.
+- **Credential:** `OXY_TOKEN`, then `oxyc login`'s cache — or, in a GitHub
+  Actions job with `id-token: write`, the job's OIDC identity.
+  `oxyc init-ci` writes a workflow that publishes with no stored secret.
 - Promote / roll back / unpublish from the oxy admin app-detail console;
   every publish is audited (who shipped each build, when).
 - **What is live now:** `oxyc apps show <org>/<app>` prints the live build, the
@@ -366,8 +462,86 @@ oxyc publish --env production --promote # …straight to live
   `oxyc apps builds <org>/<app>` is the history. `oxyc apps drift <org>/<app>`
   lists the commits in your checkout that touch the app after the live build's
   commit — `unknown` there means it could not compare, not that nothing changed.
-
-Full hands-on guide: `oxy-hq/customer-apps: docs/local-development.md`.
+- **A customer's own domain** (`app.acme.com`) serves production only:
+  `oxyc apps domains add <org>/<app> app.acme.com` prints a CNAME and a TXT
+  record for the customer to create, then `oxyc apps domains verify …`. Build
+  nothing differently — the bundle keeps its `/customer-apps/<org>/<app>/` base
+  and its same-origin `/api` calls work on the domain. A visitor signs in once
+  through the Oxygen login; on that domain the session reaches only the app's
+  workspace, so a call to another workspace there is refused by design.
+
+The build is not the check: after a publish, drive the page
+([references/verifying-in-the-browser.md](references/verifying-in-the-browser.md)).
+
+## Headless and cloud sessions
+
+A Claude Code cloud session (claude.ai/code), a CI runner or any machine with
+no browser can mint a token, iterate in a sandbox and publish. A person
+approves once, from any device.
+
+1. **The cloud environment.** Its owner sets this once in the environment's
+   settings. Under **Network access → Custom**, allow `app.oxygen-hq.com` and
+   `*.oxy.tech`, and keep the default package-manager list ticked so npm can
+   install `oxyc`. Optionally add `OXY_APPROVER=<their email>` under
+   environment variables, so each approval request is pushed to them.
+2. **The repo's SessionStart hook,** `.claude/hooks/oxyc-cloud-session.sh`,
+   with its entry in `.claude/settings.json`. In a cloud session it installs
+   `oxyc` and routes it through the session's proxy. It also makes a minted
+   token reach every later command, which an `export` in one shell call cannot
+   do. What it prints at session start says what is missing.
+   - A customer repo that `oxyc new` or `oxyc adopt` made has both files.
+   - In an existing customer repo, `oxyc update --apply` adds the script but
+     only reports the settings entry, because the team may have their own
+     settings. Add the entry by hand:
+     ```json
+     { "hooks": { "SessionStart": [ { "matcher": "", "hooks": [ { "type": "command",
+       "command": "\"${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/oxyc-cloud-session.sh\"",
+       "timeout": 120 } ] } ] } }
+     ```
+   - Any other repo can copy both from the `template/.claude/` directory of the
+     installed `@oxy-hq/cli` package.
+3. **The credential.** Run this in the background, because the approval can
+   outlast a two-minute shell limit:
+   ```bash
+   mkdir -p ~/.config/oxy && (umask 077; oxyc tokens create --agent --no-browser \
+     --env production >~/.config/oxy/agent-token.env)
+   ```
+   Give your engineer the URL and the code it prints on stderr. The token goes
+   to that file and never into your context. The hook loads the file before
+   every later command. To iterate in a sandbox, mint
+   `--sandbox-agent --app <org>/<app>` into the same file instead. A token
+   lasts 8 hours by default (`--hours`, up to 168). On exit `4`, mint again.
+4. **Ship** with the commands above, each with `--token-env OXY_TOKEN`.
+   `promote` and `rollback` need `--yes`, because there is no terminal to ask.
+
+**A token approved by device code never carries staff or partner access.**
+`--standing --no-browser` is a usage error (exit `2`). The token from step 3
+reaches only what the approver's org memberships do. That is enough when they
+belong to the app's org. Staff shipping a customer's app have three ways:
+
+- **Let the repo's CI publish a draft, and a person promote it.** This works
+  only where the repo turned CI publishing on, with the repository variable
+  `OXY_CI_PUBLISH=on`. Without it, the publish job is skipped and the run
+  still shows green.
+  - `gh workflow run publish.yaml -f ref=<branch>` publishes that ref as
+    production's draft, which is staging. A push to `main` publishes to `dev`
+    instead.
+  - Check that the publish job ran, not that the run is green.
+  - Then your engineer runs `oxyc promote <org>/<app> --dry-run`, then
+    `oxyc promote <org>/<app>`, and sees the plan before it ships.
+  - Never pass `-f promote=true`. It rebuilds the ref and puts it live with no
+    plan, the deprecated promoting publish.
+- **Mint the standing token where a browser opens.** On the engineer's own
+  machine, run `oxyc tokens create --agent --standing --hours <n>`. They put
+  the value in the cloud environment's variables as `OXY_TOKEN`. Anyone who
+  uses that environment can read it, so keep `--hours` short and revoke the
+  token when the task is done.
+- **Leave the ship step to the engineer.** Hand back the sandbox's build and
+  the `oxyc promote --from dev-<handle>` command.
+
+Without the hook, start each command with `. ~/.config/oxy/agent-token.env &&`.
+If a command fails with `fetch failed` (exit `7`) while `HTTPS_PROXY` is set,
+`oxyc` is too old to use the proxy. Update it, or set `NODE_USE_ENV_PROXY=1`.
 
 ## Sandboxes — try a change on real data before shipping it
 
@@ -375,13 +549,18 @@ A sandbox (`dev-<handle>`, 1-12 lowercase letters/digits/hyphens, no leading,
 trailing or double hyphen) is a named, short-lived environment of one app: its
 own build pointer, storage silo, secrets and Airhouse sibling schema. Reads
 hit production; most writes are isolated or *held* (recorded, not performed —
-`ctx.oltp`/`ctx.warehouse` stay shared — see
-`internal-docs/custom-app-sandboxes.md` if you have this repo checked out; if
-not, the per-call table is in this skill's "Where data goes" section above,
-and a held write's `note` field in `invocations held` names the manifest key
-that would make it land instead). It starts with no build, costs nothing
-idle, and is gone after 7 idle days or an explicit delete — safe to use for
-every iteration that would otherwise touch staging. Limit: 20 per app.
+`ctx.oltp`/`ctx.warehouse` stay shared; a held write's `note` field in
+`invocations held` names the manifest key that would make it land instead).
+A sandbox's schedules are **off by default** (staging's too): staff turn them
+on per environment with `oxyc env schedules <app> dev-x --on`, and a scheduled
+fire is not activity. To test a scheduled function without that, run it once
+as its cron would — `oxyc fn run <app> <fn> --app-env dev-x --as-schedule` (no
+input, system identity). Webhooks reach a sandbox on their own route,
+`/api/webhooks/apps-env/dev-x/<org>/<app>/<fn>`, verified with the sandbox's
+own `secretVar` value — set it with `env secret set`; staging's does not count.
+It starts with no build, costs nothing idle, and is gone after 7 idle days or
+an explicit delete — safe to use for every iteration that would otherwise
+touch staging. Limit: 20 per app, counting ones still being deleted.
 
 ```bash
 oxyc env create acme/store dev-x --env dev --json          # starts with no build
@@ -389,136 +568,43 @@ oxyc publish --env dev --app-env dev-x --json               # build + publish to
 oxyc env secret set acme/store KEY --app-env dev-x --env dev --value-env VAR  # optional: its own secret
 oxyc fn call acme/store submit-order --app-env dev-x --env dev --data '{}' --json   # call it
 oxyc checks run acme/store --app-env dev-x --env dev --json # run its checks
+oxyc fn run acme/store nightly-sync --app-env dev-x --as-schedule --env dev --json  # a scheduled function, once
 oxyc invocations list acme/store --app-env dev-x --env dev --json  # what ran; a row's id is `id`
 oxyc invocations held acme/store <invocation-id> --env dev --json  # what it held, not wrote
+oxyc logs acme/store --app-env dev-x --env dev --json       # its function logs
+oxyc logs acme/store --app-env dev-x --env dev --follow --timeout 300 --json  # live, as printed
 oxyc env delete acme/store dev-x --env dev --yes --wait --json     # done; tears its homes down
 ```
 
 (`--data` has no short form — don't write `-d`.)
 
-**An agent's credential is a sandbox agent token** (`oxy_sbx_…`), not a staff
-login. Get it yourself, once per task — your operator approves in the browser
-that opens — and end it when the task is done:
-
-```bash
-eval "$(oxyc tokens create --sandbox-agent --app acme/store --env dev)"   # prints: export OXY_TOKEN=oxy_sbx_…
-oxyc whoami --env dev --json     # kind "sandbox_agent", your app in `apps`, `expires_at` after the task ends
-# … the loop above …
-oxyc tokens revoke --current --env dev                                     # last, after the delete
-```
-
-It does this loop on the apps it was minted for (`--app`, up to five), in
-sandboxes it created, for 8 hours (`--hours`, up to 168) — and nothing else:
-production, staging, other apps, `oxyc api`, `oxyc apps` and a secret's value
-are all refused. With it, every verb that takes `--app-env` requires a
-`dev-<handle>` (exit `2` otherwise), and at most three of its sandboxes may be
-live at once.
-
-**Over MCP.** If your runtime speaks MCP, `oxyc mcp --env dev` serves the same
-loop as tools — `oxy_env_create` / `oxy_env_list` / `oxy_env_show` /
-`oxy_env_delete`, `oxy_publish_sandbox`, `oxy_fn_call`, `oxy_checks_run`,
-`oxy_invocations_list` / `oxy_invocations_held`, `oxy_logs`. It reads its
-credential from `OXY_TOKEN` and nowhere else (a person on their own login
-adds `--login`). With a sandbox agent token the list is those ten,
-`oxy_whoami`, `oxy_env_secret_list` / `_set` / `_delete` and
-`oxy_token_revoke` (`confirm: true`) — and no `oxy_request`. Prefer them to
-shelling out: each calls its verb's own request-building code, so the result
-is the document that verb's `--json` prints, and the choice changes nothing
-on the server. There is no exit code over MCP: a failure is `isError: true`
-with the class at the end of its text (`[exit 5 NOT_FOUND]`, plus `server
-code: <code>` when the server sent one) — branch on that the way you would
-on the exit code. `oxy_fn_call` and `oxy_checks_run` set `isError` when the
-function or a check failed, with the full document still in the result.
-`oxy_env_delete` needs `confirm: true`. `oxy_publish_sandbox` takes only a
-`dev-<handle>` and cannot reach staging or production.
-
 Iterate from `publish` as the code changes — each publish is a new build, and
-the sandbox always serves the newest. A sandbox build is **never promoted**:
-ship by publishing the same tree to staging, then promoting from the console.
+the sandbox always serves the newest. A sandbox build reaches production
+only through staging: a person runs `oxyc promote <app> --from dev-<handle>`
+(the build you verified becomes staging's), checks it there, then `oxyc
+promote <app>`.
 Staff only (needs `develop_apps` + `manage_apps`) — or a sandbox agent token
 such staff approved; a publish token is refused on every sandbox operation,
 so CI cannot use one.
 
-**Driving this loop unattended (an agent, not a human at a keyboard):**
-
-- Name your sandbox `dev-<short-task-slug>` — one per agent/task, never reused
-  across unrelated tasks, so parallel agents don't collide. `env create`
-  answers exit `6` if the name is already taken.
-- Branch on exit codes and JSON fields only, never on stderr text: `0` ok,
-  `1` it ran and the thing itself failed, `2` you called it wrong, `4` not
-  authenticated — your token expired, was revoked, or your operator lost
-  access (stop — don't try another credential, a cached `oxyc login`
-  included), `5` not found
-  (environment/function/invocation — check the name, or publish first if
-  the environment has no build), `6` a conflict or bad name (pick another
-  name, wait out a teardown, or free up the 20-sandbox limit — or, on
-  `token_sandbox_limit`, delete one of your own three with `--wait` first: a
-  sandbox still being deleted counts toward the three), `7` retryable
-  (network/5xx, or a `--wait` deadline), `8` refused (stop and report), `9`
-  a check failed — read `invocations held` for that check's invocation
-  before assuming the function is broken.
-- Hard rules: never pass `--promote` in this loop; never `publish` without
-  `--app-env` while iterating in a sandbox; never use `production` as
-  `--app-env` to "check" something — reads already hit production. Always
-  delete the sandbox you created, **even when an earlier step failed**. On
-  exit `4` or `8`, stop and report to a human rather than retrying with a
-  different credential or flag. A held write is information to report, not
-  an error to engineer around. Set a sandbox's secret with `oxyc env secret
-  set` (`oxy_env_secret_set`), never a hand-built request, and never try to
-  read a value back. Revoke your token last: `oxyc tokens revoke --current`.
-- Report back: the sandbox name, the build id(s) published, each check's
-  `passed`, every held write (`op`/`plane`/`table`/`note`), and confirmation
-  the sandbox was deleted.
+**An agent runs this loop on its own sandbox agent token**, never a person's
+login, with `--token-env OXY_TOKEN` on every command — the mint, exit codes,
+rules and what to hand back are in
+[references/sandbox-agent-loop.md](references/sandbox-agent-loop.md). Read it
+before an agent runs any `oxyc` command against a deployment.
 
 **A sandbox isolates the app, not the workspace.** The semantic model,
 automations and Airway pipelines it reads are `main`'s. To try a workspace
-branch, open a **workspace preview** (staff only) — a separate loop:
-
-```bash
-oxyc preview create <branch> --wait --workspace <id> --json      # compile the branch; idempotent
-oxyc preview checks <branch> --workspace <id> --json             # Airway change check of that revision
-oxyc preview run <branch> procedure <file.automation.yml> --wait --workspace <id> --json  # held dry run
-oxyc preview runs list <branch> --workspace <id> --json          # every run, the server's own included
-oxyc preview runs show <run-id> --wait --workspace <id> --json   # one run: held steps, outcome
-oxyc preview delete <branch> --yes --workspace <id> --json       # done
-```
-
-`preview run`'s kind is `procedure` or `airway_sample`; never post a
-`transform_build` or `compare` run — the server queues those itself, and you
-read them with `preview runs list` / `runs show`. A `--wait` verb exits `1`
-when what it waited for ended `failed` or `cancelled`, `7` past its deadline.
-Over MCP the same verbs are `oxy_preview_create` / `_list` / `_show` /
-`_delete` (`confirm: true`) / `_checks` / `_run` / `_runs_list` / `_run_show`.
-To make a sandbox read the branch's semantic model, publish to it with
-`--semantic-branch <branch>`.
-
-## Reading data while vibe-coding
-
-You don't need an `X-API-Key` to poke at the data API by hand — your
-`oxyc login` token authenticates as a bearer. From an app directory:
-
-```bash
-oxyc login --env local       # once; caches a token per host
-
-# gh-api-style client (resolves the target + bearer for you, no headers):
-oxyc api user --env local                                   # who am I?
-oxyc api projects/<projectId>/query --env local -f sql='select 1'
-
-# raw curl with your token (e.g. to script or debug):
-curl -H "Authorization: Bearer $(oxyc token --env local)" \
-     -H 'content-type: application/json' \
-     localhost:5173/api/projects/<projectId>/query -d '{"sql":"select 1"}'
-```
-
-`oxyc api <path>` takes the path relative to `/api/`; `-X` sets the method
-(POST when a body is given), `-f`/`-F` set the body (string / JSON-typed),
-`--input` sends a raw one, `-i` includes response headers. `--env` resolves the
-same targets as `oxyc publish` (`local` → the Vite dev server `:5173`, which
-proxies `/api` → oxy `:3000`).
-
-Do not guess a path: `oxyc routes <filter>` lists what exists and
-`oxyc schema <path>` gives the body it expects.
-
-Access is your **normal org membership** — fine for your own test
-workspace, not a cross-customer backdoor. The `projectId` is the one the
-vite-plugin already resolved for the app (it's in `window.__OXY_APP__`).
+branch, open a workspace preview (staff only, `oxyc preview …`), or publish to
+the sandbox with `--semantic-branch <branch>` — see
+[references/sandbox-agent-loop.md](references/sandbox-agent-loop.md#a-sandbox-isolates-the-app-not-the-workspace).
+
+## Read next
+
+| File | Read it when |
+| --- | --- |
+| [references/sandbox-agent-loop.md](references/sandbox-agent-loop.md) | You are an AI agent about to touch a deployment: minting the sandbox agent token, the loop, exit codes, rules, what to hand back, when you cannot get a token, the MCP tools, workspace previews. |
+| [references/verifying-in-the-browser.md](references/verifying-in-the-browser.md) | You changed something a person sees (`src/**`, or a function a card calls) and need to prove it on the published page. |
+| [references/reading-data.md](references/reading-data.md) | You need a deployment's live data while building: an agent's own `--agent` token, `oxyc api` / `routes` / `schema`, and `oxyc proxy` for `pnpm dev` against cloud data. |
+| [references/performance-and-usage.md](references/performance-and-usage.md) | You write an Oxy Function, a bulk action, caching or idempotency keys — or need to know what Oxy does for load speed and usage tracking, and the opt-outs. |
+| [references/minimal-starter.md](references/minimal-starter.md) | You are writing an app by hand instead of scaffolding it, or need the smallest correct layout. |