@oxy-hq/cli 0.8.0 → 0.10.0

package/skills/oxy-custom-apps/references/minimal-starter.md

@@ -0,0 +1,71 @@
+# Minimal starter
+
+Easiest path: `pnpm dlx @oxy-hq/create-oxy-app@latest my-app --template vite`
+(`--template functions` adds Oxy Functions).
+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` (`$schema` is optional — editor completion against the SDK's
+generated schema; `oxyc validate` and the Vite plugin check the file against it
+either way):
+```json
+{
+  "$schema": "https://unpkg.com/@oxy-hq/sdk/schema/oxy-app.schema.json",
+  "schemaVersion": 2,
+  "slug": "my-app",
+  "orgSlug": "your-org",
+  "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";
+
+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>;
+}
+```
+
+`vite.config.ts`:
+```ts
+import oxyApp from "@oxy-hq/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react(), oxyApp()],
+});
+```
+
+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. Then publish it:
+[SKILL.md → Publishing](../SKILL.md#publishing).

package/skills/oxy-custom-apps/references/performance-and-usage.md

@@ -0,0 +1,151 @@
+# Performance and usage
+
+Two halves: what you keep in your own code (the guardrails), and what Oxy does
+for every published app without any (load speed and usage tracking).
+
+## Performance guardrails
+
+Any app that ships an Oxy Function or drives a batch of them should keep these —
+cheap up front, hard to retrofit.
+
+**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.
+
+## Load speed & usage tracking (automatic — know what you get, and the opt-outs)
+
+**You do not wire load performance; Oxy does it at publish and serve time.**
+Every published app gets, with no bundle code:
+
+- **Preload hints.** At publish, Oxy parses your built `index.html` and emits
+  `Link: rel=preload`/`modulepreload` on the shell, so the browser fetches your entry
+  chunks while the HTML is still in flight. This is why the **base-path wiring in
+  [rule 3](../SKILL.md#three-rules) is load-bearing twice over**: a bundle whose
+  entry `<script>`/`<link>` tags are real, hashed, same-origin assets (what
+  `@oxy-hq/vite-plugin` produces) gets hinted; one that inlines everything into a
+  single HTML file has nothing to hint, which is fine but flat.
+- **A service worker** (`__oxy/sw.js`) that precaches those entry assets and serves
+  content-hashed files cache-first — a repeat load is near-instant and works offline.
+- **Usage instrumentation** — SPA pageviews, Core Web Vitals, engagement time, and
+  uncaught-error counts, posted to `__oxy/beacon` and shown on the app's Activity tab.
+  This is *in addition to* `useTrackEvent` (your own named events), which is unaffected.
+
+**The two opt-outs, in `oxy-app.json` (both default on — omit to keep them):**
+
+```jsonc
+{ "schemaVersion": 2, "slug": "…",
+  "performance": { "serviceWorker": false },  // ships its own SW, or must never cache
+  "analytics": false }                         // silences the platform's client events only
+```
+
+Typed as `OxyAppManifest["performance"]` / `["analytics"]` in `@oxy-hq/sdk`. `analytics:
+false` stops only the *client* runtime — Oxy still records one view row per navigation
+server-side, so the Activity tab never goes dark. Reach for these rarely: the defaults are
+the fast, observable path.
+
+### A tab left open across a publish (automatic — and what it can cost you)
+
+Oxy's injected runtime also watches for a newer build. Every app gets this with no bundle
+code, so an app that keeps work in memory has to know about it:
+
+- **It notices a publish within ~5 minutes.** A visible tab polls `__oxy/build`, and checks
+  again when it comes back to the foreground or online. When the live build differs, it
+  fires a cancelable `oxy:update-available` event on `window`.
+- **A broken lazy chunk after a publish reloads the page — in every mode except the
+  platform's `off`.** A route the tab never opened asks for a chunk the new build no
+  longer has; rather than white-screen, the runtime checks `__oxy/build` and, if the
+  build moved, reloads onto it. That reload **discards in-memory state** unless the app
+  holds `useBusyWhile` / `holdUpdates`, an input is focused, or it cancels the
+  `oxy:chunk-stale` event.
+- **Whether a tab reloads by itself is `performance.autoUpdate`.** The platform default is
+  set by the operator (announce only, today). Set it per app:
+
+```jsonc
+{ "performance": { "autoUpdate": true } }   // reload at a safe moment: a navigation,
+                                            // 2 idle minutes with nothing focused, or a
+                                            // return after 10+ minutes away
+{ "performance": { "autoUpdate": false } }  // never reload by itself; offer it with useAppUpdate
+{ "performance": { "autoUpdate": "prompt" } } // shell shows "Update ready"; reloads at the
+                                              // next safe moment if nobody taps it in 24 h
+```
+
+**The rule: wrap unsaved in-memory work.** A checklist half filled, a form not yet saved,
+a write in flight — hold updates while it is dirty, and the runtime will not reload under
+it (a held token older than 12 h is ignored, so a leak cannot pin a tab forever):
+
+```tsx
+import { useAppUpdate, useBusyWhile } from "@oxy-hq/sdk";
+
+useBusyWhile(isDirty, "checklist not saved");   // or: const release = holdUpdates("…")
+
+const { available, apply } = useAppUpdate();    // offer the update in your own UI
+{available && <button onClick={() => apply()}>Update now</button>}
+```
+
+`useFunction` already holds updates for the life of each call. `UpdatePill` (from
+`@oxy-hq/sdk/shell`) is the ready-made "Update ready" chip; `useKioskIdle` signs a kiosk
+out after the device's idle timeout, which is also a full reload onto the live build.
+An app's own `beforeunload` "leave this page?" prompt still applies. When the viewer
+chooses to stay, the runtime does not reload onto that build by itself again, but
+`apply()` and the chip still work.
+
+**Two gotchas that read as bugs:**
+- **`oxy-` is a reserved event-name prefix.** `useTrackEvent("oxy-…")` is refused with a
+  400 — that namespace is the platform's own instrumentation. Name your events anything
+  else. (It is a collision guard, not a security boundary: the beacon rides your app's own
+  auth gate, so it is *your* rows that are protected from accidental merging, not made
+  unforgeable.)
+- **A prefetch is not a view.** A launcher may warm an app on hover; Oxy checks
+  `Sec-Purpose`/`Purpose`/`X-moz` and does not record a view or start a session for a
+  speculative load. So a hovered-but-never-opened app shows no phantom traffic.

package/skills/oxy-custom-apps/references/reading-data.md

@@ -0,0 +1,106 @@
+# Reading data while vibe-coding: `oxyc`
+
+You don't need an `X-API-Key` to poke at the data API by hand — a bearer
+token works, and **`oxyc`** (`npm i -g @oxy-hq/cli`) is the client that sends
+it for you. **It replaced `oxy api`, and the Rust `oxy login`, `oxy publish`
+and `oxy proxy` with it**: every command that talks to a deployment's HTTP API
+is `oxyc`. It reads the `credentials.json` the Rust `oxy login` wrote, so an
+existing login still works.
+
+The bearer is `OXY_TOKEN` (or the variable `--token-env` names), else the
+`oxyc login` cache for that deployment.
+
+## As an agent: your own agent token
+
+**An agent does not read data on its engineer's login.** It mints its own
+token for the task:
+
+```bash
+eval "$(oxyc tokens create --agent --env <deployment>)"   # prints: export OXY_TOKEN=oxy_pat_…
+oxyc api user --env <deployment> --token-env OXY_TOKEN     # …work…
+oxyc tokens revoke --current --env <deployment> --token-env OXY_TOKEN   # last
+```
+
+- A page opens in your engineer's browser; **the click is theirs** — tell
+  them it is waiting, and never click it with a browser tool. The token is
+  printed once as `export OXY_TOKEN=…` and never written to disk; never put it
+  in a file, a commit or your report.
+- It reaches what its approver can reach, for 8 hours
+  by default (`--hours`, 1 to 168). Staff or partner access comes only with
+  `--standing`, and the approver still chooses it on the page.
+- Pass `--token-env OXY_TOKEN` to every command: one that lost the variable
+  then exits `4` instead of running on a cached login.
+- It is not the sandbox agent token. To build and test a custom-app change,
+  mint `--sandbox-agent` instead ([sandbox-agent-loop.md](sandbox-agent-loop.md)).
+  A sandbox agent token is refused by `oxyc api` before any request (exit `2`),
+  and the data API answers it `404`: read what your change did through your
+  sandbox (`oxyc fn call`, `oxyc invocations`, `oxyc logs`). Do not unset
+  `OXY_TOKEN` to reach the login cache.
+
+## Ask the deployment, never guess a path
+
+The point of the tool is that **you never guess a path** — ask the deployment
+you are actually talking to:
+
+```bash
+oxyc login --env local       # a person, once; caches a token per host
+
+oxyc routes projects --env local                        # what exists, and what each does
+oxyc schema projects/{project_id}/query -X POST         # the body it expects
+oxyc api user --env local                               # who am I?
+oxyc api projects/<projectId>/query --env local -f sql='select 1' --md
+```
+
+- **Path** is relative to `/api/` (`oxyc api user` → `<target>/api/user`); a
+  leading `/` or `api/` is fine, and `/external/api/**` passes through to the
+  API-key surface untouched.
+- **Fields follow `gh api`**: `-f k=v` is a **string** field, `-F k=v` a
+  **typed** one (`true`, `3`, `["a"]`, `@file`), `--input @body.json` (or `-`)
+  a raw body. On GET/HEAD/DELETE, fields become query parameters instead.
+  `-X` sets the method (POST when a body is given); `-i` includes the status
+  line and response headers.
+- **Read cheaply.** `--md` renders a markdown table and `--jq '<expr>'` (`-q`)
+  filters before you pay for the rows — both far fewer tokens than raw JSON,
+  which repeats every field name per row. `/sql/query` answers arrays of
+  strings **header row first**, not objects; `--md` is what makes that
+  readable.
+- **Exit codes are a contract** (`oxyc exit-codes`) — branch on them rather
+  than parsing stderr: `4` = no usable credential, `5` = not found, `6` = the
+  request was malformed and will fail identically forever, `7` = retryable.
+- **Credentials are per deployment and `--env` defaults to production.** A
+  401 that reads like an expired session is usually a dev call made with a
+  prod token — check the `--env`. A `200` with a `null` body is the *other*
+  expired-token shape; `oxyc whoami` tells them apart.
+- For a raw `curl`, `oxyc token` prints the resolved bearer (`oxy api
+  --print-token` went with the rest of that command):
+
+  ```bash
+  curl -H "Authorization: Bearer $(oxyc token --env local)" \
+       -H 'content-type: application/json' \
+       localhost:5173/api/projects/<projectId>/query -d '{"sql":"select 1"}'
+  ```
+
+`--env` resolves the same targets as `oxyc publish` (`local` → the Vite dev
+server `:5173`, which proxies `/api` → oxy `:3000`; `dev`, `staging`,
+`production`), and a value with a `.`, `/` or `:` is read as a URL.
+
+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__`).
+
+## Working locally against cloud data: `oxyc proxy`
+
+`pnpm dev` is cross-origin, so the browser sends no oxy cookie and the data
+API answers `origin not allowed`. The sidecar listens where a local
+`oxy serve` would (`:3000`) and forwards your dev server's Oxy calls to the
+cloud target with your token attached:
+
+```bash
+oxyc proxy --env dev          # then `pnpm dev` as usual
+```
+
+Its guardrails are the reason to use it rather than a bare token:
+side-effecting calls are **held** (`--allow-writes` forwards them), tracking
+events **dropped** (`--allow-events`), and a production target is refused
+without `--yes`. The token stays in the proxy process and never reaches the
+browser. It cannot target a sandbox.

package/skills/oxy-custom-apps/references/sandbox-agent-loop.md

@@ -0,0 +1,307 @@
+# The sandbox agent loop
+
+How an AI agent builds and tests a custom-app change on a deployment without a
+person's login: its own short-lived token, its own `dev-<handle>` sandbox, and
+a report its engineer can act on. What a sandbox is, and the same loop as a
+person runs it, are in
+[SKILL.md → Sandboxes](../SKILL.md#sandboxes--try-a-change-on-real-data-before-shipping-it).
+
+## An agent's own credential: the sandbox agent token
+
+**If you are an AI agent, you do not work on your engineer's login.** A login
+carries everything the engineer can do, for 90 days. You mint a token for the
+task instead (`oxy_sbx_…`): it reaches only the apps you name, your engineer
+approves it once, and you end it when the task is done.
+
+```bash
+oxyc tokens create --sandbox-agent --app <org>/<app> --env <deployment>
+# → a page opens in your engineer's browser: the apps, the lifetime, Approve
+# → stdout, once:   export OXY_TOKEN=oxy_sbx_…
+```
+
+- **The click is your engineer's.** Tell them a page is waiting in their
+  browser. The command waits five minutes for the click, so run it with a
+  timeout at least that long: a shell tool that stops a command after two
+  minutes kills it first. Never open or click that page with a browser tool.
+- **Where no browser can reach your machine** (a cloud container, a CI job, a
+  remote box), add `--no-browser`. `oxyc` prints a URL and an eight-letter
+  code on stderr instead of opening a page, and waits up to ten minutes. Give
+  your engineer both: they open the URL on any device where they are signed
+  in, type the code the terminal shows, and approve. The token is printed
+  exactly as above. The rule does not change: never open or approve that page
+  yourself, with a browser tool or any other way.
+- **Name who approves with `--approver <email>`** (or `OXY_APPROVER`), only
+  with `--no-browser`: the engineer is told by push, email and Slack; they type
+  the code from your output on the page. Use the email your engineer gave you,
+  and still show them the code `oxyc` printed, since the notice does not carry
+  it. Only that person can open the request: if you were given no address, omit
+  the flag and hand them the URL and the code as before. Never open or click
+  the page yourself.
+- **Evaluate that line and work with the token.** In a shell that persists:
+  `eval "$(oxyc tokens create --sandbox-agent --app <org>/<app> --env <deployment>)"`.
+  In one that does not, such as an agent's shell tool, redirect it to
+  `~/.config/oxy/agent-token.env` under `umask 077`, and start each command
+  with `. ~/.config/oxy/agent-token.env &&`. In a Claude Code cloud session,
+  the repo's SessionStart hook does that for you
+  ([SKILL.md → Headless and cloud sessions](../SKILL.md#headless-and-cloud-sessions)).
+  `oxyc` writes nothing to the credentials file. That file is the only place
+  the token goes. Never put it in a commit or your report.
+- **Make the variable the only credential.** Put `--token-env OXY_TOKEN` on
+  every command after the mint, as the loop below does. With it, a command
+  that lost the variable exits `4` (`OXY_TOKEN is not set`): set it and run the
+  command again. Without it, `oxyc` falls back to your engineer's login cache
+  on this machine, and a publish with no `--app-env` then goes to the app's
+  draft channel as them.
+- **Name every app the task touches** with its own `--app`, five at most.
+  `<org>/<app>` is `orgSlug` and `slug` from the app's `oxy-app.json`, not the
+  folder names, which can differ. When the manifest has no `orgSlug`, take the
+  org slug from the app's README or from your engineer. Pass `--hours` when
+  the task will outlast the default 8; the most is 168 (seven days). Apps and
+  lifetime are fixed at mint, and the token cannot be extended.
+- **Check it** with `oxyc whoami --env <deployment> --token-env OXY_TOKEN --json`:
+  `"kind": "sandbox_agent"`, your app in `apps`, and an `expires_at` after the
+  task ends. Run it first when `OXY_TOKEN` was already set before you started:
+  without that `kind` it is someone else's credential, and you mint your own.
+  Then `oxyc env list <org>/<app> --env <deployment> --token-env OXY_TOKEN --json`:
+  exit `0` means the app and the deployment are right.
+- **Set `OXY_AGENT=<your name>`** beside it, so the audit log tells your
+  requests from your engineer's.
+- `--env` is the deployment (`dev`, `staging`, `production`). Pass the same
+  one on every command; omitted, it is `production`. Use the one your engineer
+  named. When they named none, use `production` and say so when you tell them
+  the approval is waiting.
+
+For anything that is not the sandbox loop — reading data with `oxyc api`,
+reproducing a bug against live data — the agent's credential is a different
+token, `oxyc tokens create --agent`: see [reading-data.md](reading-data.md).
+
+## What it reaches
+
+One to five named apps, and only `dev-<handle>` sandboxes it created itself —
+three at a time at most, counting ones still being deleted. Everything else
+answers `404`: production and staging, another app, someone else's sandbox,
+`/admin`, a secret's value. A publish to a channel (staging, production) or a
+promote answers `403`. `oxyc` refuses those two, and `oxyc api`, `oxyc apps`
+and `oxyc login-link`, before any request (exit `2`). **Shipping stays with a
+person.**
+
+## The loop
+
+Under the token the environment must be named: `publish`, `fn call`,
+`checks run`, `invocations list` and `logs` are refused without
+`--app-env dev-<handle>` (exit `2`). Run `publish` from the app directory: it
+reads the app from the `oxy-app.json` there. Every other command takes
+`<org>/<app>`.
+
+```bash
+# 1. Create it. It starts with no build. `url` in the answer is the sandbox's link.
+oxyc env create <org>/<app> dev-x --env <deployment> --token-env OXY_TOKEN --json
+# 2. Build + publish into it. Success: "channel":"sandbox" and "environment":"dev-x".
+oxyc publish --app-env dev-x --env <deployment> --token-env OXY_TOKEN --json
+# Optional: a secret of the sandbox's own, read from a variable.
+oxyc env secret set <org>/<app> KEY --app-env dev-x --value-env VAR --env <deployment> --token-env OXY_TOKEN
+# 3. Call what you changed. Success: exit 0 and "ok":true. Then run the app's checks.
+oxyc fn call <org>/<app> <function> --app-env dev-x --data '{}' --env <deployment> --token-env OXY_TOKEN --json
+oxyc checks run <org>/<app> --app-env dev-x --env <deployment> --token-env OXY_TOKEN --json
+# 4. Read back: what ran (a row's id is `id`), what it held instead of writing, its logs.
+oxyc invocations list <org>/<app> --app-env dev-x --env <deployment> --token-env OXY_TOKEN --json
+oxyc invocations held <org>/<app> <invocation-id> --env <deployment> --token-env OXY_TOKEN --json
+oxyc logs <org>/<app> --app-env dev-x --env <deployment> --token-env OXY_TOKEN --json
+# 5. When the task is done: delete, then revoke, in that order.
+oxyc env delete <org>/<app> dev-x --yes --wait --env <deployment> --token-env OXY_TOKEN --json
+oxyc tokens revoke --current --env <deployment> --token-env OXY_TOKEN
+```
+
+`dev-x` is `dev-<handle>`: 1–12 characters of `a-z`, `0-9` and single hyphens,
+not starting or ending with one. Name it after the task
+(`dev-<short-task-slug>`), one per agent and task, never reused across
+unrelated tasks, so parallel agents do not collide. If your runtime speaks
+MCP, the same loop is served as tools — see [Over MCP](#over-mcp).
+
+## Publishing into it
+
+Three things to know before the first publish:
+
+- **`missing org: the app's base path needs it` (exit `2`).** `publish` takes
+  the org from `--org`, `OXY_ORG`, the `orgSlug` in the directory's
+  `oxy-app.json`, else the folder under an `apps/<org>/<app>/` path. An app
+  whose manifest names no org, outside such a path, has none. An app that
+  keeps its manifest in `public/` gets the folder name, which is wrong
+  wherever the folder is not the slug. In both cases add `--org <org-slug>`,
+  and `--app <slug>` when the directory has no manifest. Pass the slug, never
+  a UUID: the asset base path is baked from it.
+- **`pnpm install` stops with `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`
+  (exit `1`).** The default install step is `pnpm install`; pnpm wants to
+  rebuild `node_modules` and your shell has no terminal for it to ask on. Run
+  the same command with `CI=true` in front.
+- **A broken build costs an approval.** `oxyc publish --build-only` builds and
+  bundles with no credential, so run it before you ask for a token (it takes
+  `--org` too). `oxyc publish --dir out --prebuilt --app-env dev-x …` then
+  publishes that build without building again.
+
+## What a sandbox does with a call
+
+Reads hit production data. A write lands in a home of the sandbox's own, or it
+is *held*: recorded in `invocations held` and not performed. A held write is
+the expected answer outside production. Report it. Unless the task asks for
+it, do not edit `nonProduction` in the manifest to make the write land:
+staging and every other sandbox share that map. A sandbox's schedules are off
+unless staff turned them on, and your token cannot turn them on: to test a
+scheduled function, run it once as its schedule would — `oxyc fn run
+<org>/<app> <function> --app-env dev-x --as-schedule --env <deployment>
+--token-env OXY_TOKEN --json` (no `--data`; `oxy_fn_run` with `asSchedule:
+true` over MCP). It runs as the system, with the function's retry policy, and
+answers `409 not_scheduled` (exit `6`) for a function with no `schedule`. The
+`fn call` result carries the function's `logs`; `oxyc logs` shows the same
+lines about 30 seconds later.
+To watch a run you do not call yourself — a check on the worker fleet, a slow
+function — start `oxyc logs <org>/<app> --app-env dev-x --follow --timeout 300
+--env <deployment> --token-env OXY_TOKEN --json` in the background first. It
+prints one JSON event per line (`open`, then `start` / `log` / `finish`),
+needs no observability capture, and exits `0` on `done`. A `dropped` event
+means lines were lost, not that the function failed.
+
+## When a command fails
+
+Branch on the exit code and the JSON fields, not on the text:
+
+| Exit | From | It means | Do |
+| --- | --- | --- | --- |
+| `1` | `publish` | The build or the Oxy Function lint failed. | Fix what the error names, or see [Publishing into it](#publishing-into-it). |
+| `1` | `fn call` | The function threw or answered a non-2xx: `"ok": false`. | Read `body` and `logs` in the result. It is your code. |
+| `1` | `checks run` | The app declares no checks (no function has `"check": true`). | Not a failure. Verify with `fn call`, and report that the app has no checks. |
+| `2` | any | The command was wrong, or the token may not do it. Nothing was sent. | Read the message. Do not retry it unchanged. |
+| `4` | any | `OXY_TOKEN is not set`: the command lost the variable. Any other message: the token expired, was revoked, or your engineer lost access to the app. | Set the variable and run it again. Otherwise stop and report. Never log in. |
+| `5` | any | Not found: the app, the sandbox, the function or the invocation, or one your token does not reach. From `fn call` before the first publish: the sandbox has no build. | Check the slugs and `--env` once. Do not try other spellings. From `env delete` it means already gone. |
+| `6` | `env create` | The name is taken or reserved, a sandbox of that name is still tearing down, the app is at its 20-sandbox limit, or your token already holds three (`token_sandbox_limit`; one still being deleted counts). | Pick another handle, or delete one of yours with `--wait` first. Do not retry the same name. |
+| `7` | any | Unavailable (network, 5xx), or a `--wait` deadline ran out. | Run it once more. If `env delete --wait` exits `7` twice, report the sandbox as not deleted. |
+| `8` | `env delete` | Refused: it had no `--yes` and no terminal to ask on. | Add `--yes`. |
+| `8` | anything else | A refusal. | Stop and report. Do not retry with another credential or flag. |
+| `9` | `checks run` | A check failed or timed out. | Read `checks[].error`, then `invocations held` for that check's `invocationId` before assuming the function is broken: a held write can be the expected answer. |
+
+## Rules
+
+- **Never borrow another credential.** Do not run `oxyc login`, read the login
+  cache (`credentials.json`, `oxyc token`), or use an engineer's personal
+  token or API key. What the token does not reach is a person's step: ask your
+  engineer. Exit `4` under the token means it expired, was revoked, or your
+  engineer lost access to the app: stop and report.
+- **Never put an Oxy credential into a sandbox secret.** The server refuses a
+  value shaped like one (`400 credential_shaped_value`). Set a secret with
+  `oxyc env secret set` (`oxy_env_secret_set`), never a hand-built request,
+  and never try to read a value back.
+- **Never pass `--promote`, never run `oxyc promote` or `oxyc rollback`, and
+  never publish without `--app-env`.** When the sandbox build is right, say so
+  and leave the ship step to your engineer: they promote that build to staging
+  (`oxyc promote <app> --from dev-<handle>`), then to production. Your token is
+  refused both verbs anyway. Never use `production` as `--app-env` to "check" something:
+  reads already hit production.
+- **A held write is information to report**, not an error to engineer around.
+- **Clean up, even when a step failed.** Delete every sandbox you created,
+  then revoke your token — in that order, because the delete needs the token.
+  A sandbox you could not delete is removed a day after its token ends.
+- **Leave the sandbox up when your engineer has to look at it**: they asked
+  for its link, or the change shows on a page. Say that it is still up, and
+  revoke the token once you will publish nothing more. The sandbox stays for a
+  day after its token ends, and your engineer can delete it sooner with the
+  `env delete` command on their own login.
+
+## You cannot open a page
+
+The token signs no browser in, and the sandbox's host answers only a signed-in
+staff session. So you verify the functions (`fn call`, `checks run`,
+`invocations held`, `logs`) and your engineer verifies what a person sees. Do
+not log in to get a session, and do not drive the app's production URL
+instead: it does not serve your build. What your engineer does with the link
+is in [verifying-in-the-browser.md](verifying-in-the-browser.md).
+
+## What to hand back
+
+Whether the task worked or not:
+
+- the deployment and the sandbox's name, and its link: `url` from
+  `env create`, `environment_url` from `publish` (`null` means the sandbox has
+  no host: say so);
+- the build id(s) the publish answered;
+- each function you called, with its input and whether it was `ok`; each
+  check's name and `passed`, or that the app declares no checks;
+- every held write (`op`, `plane`, `table`, `note`);
+- what you did not verify: under this token, everything on the page;
+- the cleanup: the sandbox deleted or still up, and the token revoked.
+
+Copy what you need out of `invocations` and `logs` into the report before you
+delete the sandbox: read-back is not permanent. Never put the token in the
+report.
+
+## When you cannot get a token
+
+Stop and ask your engineer. Do not fall back to their login in any of these
+cases:
+
+- **`oxyc` rejects `--sandbox-agent` as an unknown option (exit `2`).** The
+  CLI is too old. Ask your engineer to update `@oxy-hq/cli`.
+- **Exit `8`.** The deployment did not return the token you asked for: it
+  predates sandbox agent tokens, or returned one for other apps. Nothing was
+  printed, and what it minted was revoked.
+- **Exit `7`.** Nobody approved in time (five minutes, or ten with
+  `--no-browser`). Ask your engineer what the page said. Only Oxy staff
+  holding `develop_apps` and `manage_apps` over the app's org can approve: if
+  the page refused, report what it said and stop. If they missed it, run the
+  command once more. If you named an `--approver`, say so: the request went to
+  that person's phone and inbox, so they may have missed the notice rather
+  than the page.
+- **Exit `4`.** The approval code was rejected and nothing was minted. Run the
+  command once more, with fewer `--hours` if an organization caps a token's
+  lifetime. With `--no-browser`, exit `4` with `access_denied` means your
+  engineer declined, or the page refused the request: the reason is printed.
+  Report it and stop.
+- **`--no-browser` is an unknown option (exit `2`), or the deployment has no
+  device-code approval (exit `8`).** The CLI or the deployment is too old for
+  a machine no browser can reach. Ask your engineer to update, or to run the
+  command on a machine with a browser and hand you the token.
+- **`--approver` is an unknown option (exit `2`).** The CLI predates it. Run
+  without it and give your engineer the URL and the code yourself.
+
+## Over MCP
+
+If your runtime speaks MCP, `oxyc mcp --env <deployment>` 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.
+
+## A sandbox isolates the app, not the workspace
+
+The semantic model, automations and Airway pipelines a sandbox 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>`.