@oxy-hq/cli 0.9.0 → 0.10.0

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

@@ -50,6 +50,7 @@ works), but hand-rolling means owning the base-path + dev-proxy wiring yourself.
 
    ```json
    {
+     "$schema": "https://unpkg.com/@oxy-hq/sdk/schema/oxy-app.schema.json",
      "schemaVersion": 2,
      "slug": "url-slug",
      "orgSlug": "your-org",
@@ -57,18 +58,38 @@ works), but hand-rolling means owning the base-path + dev-proxy wiring yourself.
    }
    ```
 
-   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, and so does
@@ -304,13 +325,68 @@ 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).
 
+## Run a function locally
+
+`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.
+
+```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
+```
+
+- **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
 
-**These commands are a person's.** `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, publish into your own sandbox
-([references/sandbox-agent-loop.md](references/sandbox-agent-loop.md)) and
-leave the ship step to your engineer.
+**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:
@@ -318,24 +394,45 @@ 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 → bundle functions → 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
 ```
 
+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
-  `--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** needs `--project <workspace-uuid>` (unless
-  the app was registered in the admin UI): the build-config lookup can't
-  resolve a project until the app exists. A pinned workspace also supplies
-  the org. Drop the flag after the first publish — it's auto-resolved from
-  then on.
+  `"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.
+  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
@@ -365,10 +462,87 @@ 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.
+- **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
 
 A sandbox (`dev-<handle>`, 1-12 lowercase letters/digits/hyphens, no leading,
@@ -377,10 +551,16 @@ 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; a held write's `note` field in
 `invocations held` names the manifest key that would make it land instead).
-Schedules and webhooks do not fire in a sandbox: call the function. 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.
+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
@@ -388,17 +568,21 @@ 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`.)
 
 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.

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

@@ -15,9 +15,17 @@ my-app/
 └── tsconfig.json
 ```
 
-`oxy-app.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
-{ "schemaVersion": 2, "slug": "my-app", "orgSlug": "your-org", "name": "My App" }
+{
+  "$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`:

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

@@ -94,6 +94,52 @@ false` stops only the *client* runtime — Oxy still records one view row per na
 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

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

@@ -23,11 +23,29 @@ oxyc tokens create --sandbox-agent --app <org>/<app> --env <deployment>
   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, keep the value and set `OXY_TOKEN` on each command.
-  `oxyc` writes nothing to the credentials file. Never write the token to a
-  file, a commit or your report.
+  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
@@ -127,9 +145,21 @@ 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. Schedules and webhooks do not
-fire in a sandbox: call the function. The `fn call` result carries the
-function's `logs`; `oxyc logs` shows the same lines about 30 seconds later.
+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
 
@@ -160,9 +190,11 @@ Branch on the exit code and the JSON fields, not on the text:
   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`, and never publish without `--app-env`.** A sandbox
-  build is never promoted. When it is right, say so and leave the ship step to
-  your engineer. Never use `production` as `--app-env` to "check" something:
+- **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,
@@ -211,16 +243,24 @@ cases:
 - **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 within five minutes. 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.
+- **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.
-- **No browser on this machine can open the page** (a remote container, a CI
-  job). The page answers to a local port on the machine `oxyc` runs on, so it
-  cannot be approved from another one.
+  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
 

package/template/.claude/hooks/oxyc-cloud-session.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# SessionStart hook for Claude Code cloud sessions (claude.ai/code): makes
+# `oxyc` usable with no browser on this machine — installed, routed through the
+# session's egress proxy, and given a credential that survives between Bash
+# calls. A local session exits at once.
+#
+# stdout is read by Claude, so it says only what is missing and the one thing
+# to do about it. The cloud *environment* still needs the Oxy hosts allowed
+# (Network access → Custom): the oxy-custom-apps skill, "Headless and cloud
+# sessions".
+#
+# Two copies, kept identical by a test: oxygen-internal's own, and the one in
+# sdk/cli/template/ that `oxyc update` writes into every customer repo (it is
+# managed there — edit it in oxygen-internal, not in the customer repo).
+
+[ "${CLAUDE_CODE_REMOTE:-}" = "true" ] || exit 0
+cat >/dev/null 2>&1 || true
+
+# Where a minted agent token is kept: the one `export OXY_TOKEN=…` line that
+# `oxyc tokens create --agent` prints on stdout.
+TOKEN_FILE="$HOME/.config/oxy/agent-token.env"
+ENV="${OXY_ENV:-production}"
+case "$ENV" in
+  production) HOST=app.oxygen-hq.com ;;
+  staging) HOST=aip.staging.oxy.tech ;;
+  dev) HOST=aip.dev.oxy.tech ;;
+  *) HOST="" ;;
+esac
+
+if ! command -v oxyc >/dev/null 2>&1; then
+  npm install -g @oxy-hq/cli >/dev/null 2>&1 \
+    || echo "oxyc: 'npm install -g @oxy-hq/cli' failed — run it before any oxyc command."
+fi
+
+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
+  {
+    # Node's fetch ignores HTTPS_PROXY without this, and every request out of
+    # this VM goes through one. A current oxyc sets it itself; older ones don't.
+    echo 'export NODE_USE_ENV_PROXY=1'
+    # Runs before every Bash command, so a token minted mid-session reaches
+    # every command after it — an `export` in one call would not.
+    echo "[ -f \"$TOKEN_FILE\" ] && . \"$TOKEN_FILE\""
+  } >>"$CLAUDE_ENV_FILE"
+fi
+
+if [ -n "$HOST" ] && ! curl -fsS --max-time 10 -o /dev/null "https://$HOST/api/health" 2>/dev/null; then
+  echo "oxyc: https://$HOST is unreachable from this session. The cloud environment's network"
+  echo "  access must allow it (Custom: app.oxygen-hq.com, *.oxy.tech) — ask the user to add it."
+fi
+
+if [ -n "${OXY_TOKEN:-}" ]; then
+  echo "oxyc: credential is OXY_TOKEN from the environment."
+elif [ -s "$TOKEN_FILE" ]; then
+  echo "oxyc: credential is the agent token in $TOKEN_FILE (it expires: on exit 4, mint again)."
+else
+  cat <<EOF
+oxyc: no Oxy credential yet. Before you publish or promote, mint an agent token — a person
+  approves it once from any device, nothing opens here. Run this in the background:
+    mkdir -p ~/.config/oxy && (umask 077; oxyc tokens create --agent --no-browser --env $ENV >$TOKEN_FILE)
+  and give the user the URL and code it prints. --approver <their email> (or OXY_APPROVER) also
+  pushes the request to them. Once approved, every later command has OXY_TOKEN.
+  It reaches what the approver's org memberships do, never staff access: staff shipping a
+  customer's app need another path. See the oxy-custom-apps skill, "Headless and cloud sessions".
+EOF
+fi
+exit 0

package/template/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/oxyc-cloud-session.sh\"",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.github/workflows/publish.yaml

@@ -160,7 +160,7 @@ env:
   # service account are honoured from 0.7.0, which tries them first and falls
   # back to the publisher. A pin older than that still publishes, through the
   # publisher alone.
-  OXYC_VERSION: "0.9.0"
+  OXYC_VERSION: "0.10.0"
 
 jobs:
   build:

package/template/.oxyc-managed

@@ -180,6 +180,11 @@ managed   .github/scripts/*.sh
 # app locally", and it is meant to improve for everyone at once.
 managed   scripts/*.sh
 
+# The Claude Code cloud-session hook: installs oxyc and wires its proxy and
+# credential so an agent with no browser can publish. It tracks oxyc's own
+# behaviour, and a test keeps it byte-identical to oxygen-internal's copy.
+managed   .claude/hooks/*.sh
+
 # The merge rule for the generated memory index. It is a statement about how
 # oxyc's own generated file behaves, so oxyc owns it.
 managed   .gitattributes
@@ -246,6 +251,10 @@ mixed     .gitignore
 # script somebody decided on is the customer's.
 mixed     pnpm-workspace.yaml
 
+# The SessionStart entry that runs the hook above is the tool's; any other
+# hook, permission or plugin a team adds beside it is theirs.
+mixed     .claude/settings.json
+
 # --- scope: which tree each file describes ----------------------------------
 #
 # Grouped by answer rather than written beside the role above, so that the two
@@ -263,6 +272,10 @@ scope-repo       .gitattributes
 scope-repo       .oxyc-managed
 scope-repo       .oxyc-template.json
 
+# Claude Code reads `.claude/` from the root of the repo it opened.
+scope-repo       .claude/hooks/*.sh
+scope-repo       .claude/settings.json
+
 # The PNPM workspace and the git working tree, which are root things in a repo
 # whose Oxy workspace is somewhere else. `pnpm dev` is run from the repo root;
 # `packages: apps/*` names directories at the repo root, which is also where