@oxy-hq/cli 0.7.0 → 0.9.0

package/skills/oxy-automations/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: oxy-automations
-description: Use when writing, debugging, or reviewing an Oxy automation (a `.automation.yml` / legacy `.procedure.yml` workflow — tasks, loops, variables, schedules) in a customer workspace, or when an automation *run* misbehaves: an `http_request` task that works locally and fails in cloud, a file that is silently not an automation, or an automation run landing `completed_with_errors`. Covers the file-naming trap, task-type gotchas, and where the authoritative reference lives.
+description: >-
+  Use when writing, debugging, or reviewing an Oxy automation (a `.automation.yml` / legacy
+  `.procedure.yml` workflow — tasks, loops, variables, schedules) in a customer workspace, or when
+  an automation *run* misbehaves: an `http_request` task that works locally and fails in cloud, a
+  file that is silently not an automation, a task that validates but fails with "unknown task
+  type", SQL that receives JSON instead of a table, or an automation run landing
+  `completed_with_errors`. Covers the file-naming trap, task-type gotchas, running SQL and
+  automations from the `oxy` CLI, and where the authoritative reference lives.
 ---
 
 # Oxy automations
@@ -18,12 +25,13 @@ The canonical extension is **`.automation.yml`**.
 
 - `.procedure.yml` is the **legacy** name. It is still accepted, so a workspace
   full of it keeps working and nothing warns you — which is exactly why it
-  spreads. Poke House's workspace has 18 automations, and every one of them is
-  still `.procedure.yml`.
+  spreads. One production workspace has 18 automations, and every one of them
+  is still `.procedure.yml`.
 - `.workflow.yml` is **no longer a recognised file kind at all**. A file with
-  that name is silently not an automation.
-- `oxy migrate-automations` exists to rename legacy files. It is the only thing
-  that reads them for that purpose.
+  that name is silently not an automation, and `oxy run` refuses it.
+- `oxy migrate-automations` renames legacy files (and rewrites references to
+  them); `--dry-run` previews. It is the only thing that reads `.workflow.yml`
+  files for that purpose.
 
 **Write new files as `.automation.yml`.** Do not copy the extension from a
 neighbouring file in the workspace you are editing — that is how the legacy name
@@ -32,16 +40,31 @@ propagated in the first place.
 ## Naming, and why the code disagrees with the docs
 
 "Automation" is the current name for what used to be called a Procedure, and
-before that a Workflow. The Rust types still say `Workflow*` / `Procedure*`, and
-`type: workflow` plus the `agentic_workflow_state` table are **wire and storage
-contracts** — they are not stale naming to be tidied up. Seeing `workflow` in the
-code or in a payload does not mean you are looking at something deprecated.
+before that a Workflow. The sub-automation task is still `type: workflow`, and
+API payloads and stored run records still say `workflow` — those are **wire and
+storage contracts**, not stale naming to be tidied up. Seeing `workflow` in a
+payload does not mean you are looking at something deprecated.
 
 Routes follow the same split: `/automations/:id` is canonical;
 `/workflows/:id`, `/procedures`, and `/agentic-workflows` are aliases.
 
 ## Task-type gotchas
 
+- **A misspelled `type:` passes validation and fails only at run time.** An
+  unrecognised task type — `type: sql`, `type: execute` — is read as an
+  "unknown" step rather than rejected, so `oxy validate` reports the file valid
+  and the run fails on that step with `unknown task type`. Check every `type:`
+  against the task-types page by eye, then *run* the automation; validation
+  alone proves nothing here. (A wrong *field* inside a known type, such as
+  `query:` instead of `sql_query:`, does fail validation.)
+- **`{{ step_name }}` renders as JSON rows, not as a table.** A prior SQL
+  step's result renders into a template as a compact JSON list of row objects
+  (`[{"region": "west", "total": 42}, …]`). That is what an `agent` or
+  `formatter` prompt wants, and what a loop iterates over — but `SELECT … FROM
+  {{ extract }}` sends that JSON to the warehouse as SQL and fails. To chain SQL
+  steps, either inline the earlier query as a CTE in the later step, or have
+  the earlier step write a table (`CREATE OR REPLACE TABLE …`) and read the
+  table by name.
 - **`http_request` is HTTPS-only and blocks private egress.** Requests to
   localhost, cloud-metadata endpoints, and private IP ranges are refused unless
   that task opts in with `allow_hosts`. A task that works locally and fails in
@@ -50,17 +73,40 @@ Routes follow the same split: `/automations/:id` is canonical;
   as `completed_with_errors`, not as a failed run. Code and dashboards that only
   check for "failed" will report it as a success.
 
+## Running locally with `oxy run`
+
+`oxy run <file>` takes a `.sql` file, an `.automation.yml`, or a
+`.procedure.yml` — nothing else.
+
+- **SQL files:** `oxy run report.sql --database warehouse -v start=2024-01-01
+  -v region=west`. `--database` picks a database from `config.yml` (default:
+  the configured default database). `-v` / `--variables` fills Jinja
+  placeholders, and those `-v` values are the **entire** template context —
+  nothing else (no database or schema objects) is available inside the SQL.
+  `--dry-run` previews the rendered SQL without executing it.
+- **No `-v` means no rendering at all.** Run a templated `.sql` file without a
+  single `-v` and its `{{ … }}` placeholders reach the warehouse literally, as
+  a syntax error. Pass at least one variable whenever the file has
+  placeholders.
+- **`--dry-run` and `-v` are ignored for automations.** Both apply to `.sql`
+  files only. `oxy run x.automation.yml --dry-run` executes the automation for
+  real — every write, every `http_request` — and uses the file's own
+  `variables:` defaults whatever `-v` says. To check an automation without side
+  effects, run its SQL files individually with `--dry-run`.
+- `--retry` and `--retry-from <step>` are accepted but currently have no effect
+  on an automation run; a failed run is re-run from the top.
+
 ## Before you write one
 
 Check whether the work belongs in an automation at all. Scheduled data movement
 is usually an Airway pipeline (`.airway.yml`); a question answered from the
-semantic layer is usually an agent or a Data App. Automations are for
+semantic model is usually an agent or a Data App. Automations are for
 multi-step orchestration you want to run on a schedule or trigger.
 
-**But "usually a pipeline" is not "never an automation", and the seam is
-undocumented.** There is a `type: airway` task that runs a pipeline as a step —
-absent from the task-types page — and a step completes only once the pipeline's
-end-of-load fold has committed. That is what makes the standard
+**But "usually a pipeline" is not "never an automation".** A `type: airway`
+task runs a pipeline as a step, and the step completes only once the
+pipeline's load has committed — the task-types page documents the task, but not
+why that guarantee matters. It is what makes the standard
 ingest-then-aggregate automation safe: `type: airway` followed by
 `type: execute_sql` building a rollup table. Reach for it whenever a dashboard
 would otherwise aggregate at query time. **`oxy-data-architecture`** owns that

package/skills/oxy-cli/SKILL.md

@@ -68,13 +68,21 @@ never sent to the server as a literal.
 
     oxyc validate                  # check the workspace YAML — no network, no token
     oxyc proxy --env dev           # local app dev against cloud data
+    oxyc login-link --next /ide    # one-time URL that signs a browser in as your token
     oxyc guide                     # this page, to paste into a context file
 
 `oxyc validate` is the one command that works entirely offline. It checks
 `config.yml`, `.automation.yml`, `.agentic.yml`, `.app.yml` and
 `.agent.test.yml` against the schemas the Rust config types generate. It is
-STRUCTURAL only — `oxy validate` also resolves `databases:` and `llm.ref`, and
-wins where the two disagree.
+STRUCTURAL only — `oxy validate` additionally checks an automation's or app's
+`database:` names against `config.yml`, but it too is structural for
+`.agentic.yml` (`databases:` and `llm.ref` are not resolved), so an agent both
+accept can still fail at run time.
+
+To look at a deployed environment in a browser, navigate your browser tool to
+`$(oxyc login-link --env dev --next /ide)`. It is a one-time link that signs
+the browser in as your token — no OAuth, no inbox — and it needs a personal
+access token: an agent token (below) is one, and so is what `oxyc login` stores.
 
 If your runtime speaks MCP, `oxyc mcp` serves the same API surface as four
 tools (`oxy_routes`, `oxy_schema`, `oxy_request`, `oxy_whoami`) instead. It
@@ -82,6 +90,31 @@ reads its credential from `OXY_TOKEN` only — with the variable unset it exits
 `4` rather than using the machine's `oxyc login`; `oxyc mcp --login` opts
 into that. The same holds for any command given `--token-env <VAR>`.
 
+## An agent's own credential
+
+If you are an agent, run on your own token — never on the person's
+`oxyc login`. Mint the one that fits the task; your operator approves it once
+in the browser, and it is printed once and stored nowhere.
+
+    eval "$(oxyc tokens create --sandbox-agent --app <org>/<app> --env <deployment>)"   # building a custom app in a sandbox
+    eval "$(oxyc tokens create --agent --env <deployment>)"                             # everything else
+
+- **Sandbox agent token** (`oxy_sbx_…`): the sandboxes of the apps it names,
+  and nothing else on the deployment.
+- **Agent token** (`oxy_pat_…`): everything your operator can reach, for hours
+  (`--hours`, default 8). Add `--standing` only when the task needs their staff
+  or partner access: they decide on the page, where it starts off, and a token
+  that comes back without it is still a success.
+- **After a mint, pass `--token-env OXY_TOKEN` to every command.** A named
+  token variable is the only source, so a command that lost the variable (a new
+  shell, a subprocess started without it) exits `4` instead of silently running
+  on the person's cached login.
+- `oxyc whoami --token-env OXY_TOKEN` says what you hold and when it ends.
+  `oxyc tokens revoke --current --token-env OXY_TOKEN` ends it when the task is
+  done.
+- **Exit `4` on your own token means it expired or was revoked. Stop and
+  report.** Do not run `oxyc login`, and do not look for another credential.
+
 ## Custom apps: what is live, healthy, used
 
 Read-only — every request is a GET. `<app>` is `<org-slug>/<app-slug>` or an
@@ -111,7 +144,7 @@ app UUID; each command takes `--json`.
 | --- | --- |
 | `0` | fine |
 | `2` | you called it wrong — fix the command, do not retry |
-| `4` | not authenticated → `oxyc login --env <env>`, or the token expired |
+| `4` | not authenticated. A person: `oxyc login --env <env>`. An agent on its own token: the token ended — stop and report, never log in |
 | `5` | 404 — check the path with `oxyc routes`. In an **admin** surface a 404 can be a scope boundary, not a missing row. |
 | `6` | the request was malformed — check `oxyc schema` |
 | `7` | 5xx / timeout / network — **retryable** |
@@ -134,7 +167,7 @@ app UUID; each command takes `--json`.
 - **A listed route can still 404** if it is `ide-only` or `worker-only`; those
   are hidden by default and shown by `oxyc routes --all`.
 - **Pick the environment deliberately.** `--env local|dev|staging|production`
-  (default production), or paste a URL: `--env https://poke-house.oxygen-hq.com`
+  (default production), or paste a URL: `--env https://your-org.oxygen-hq.com`
   targets that deployment *and* sets `{org}`.
 - **Staff hitting a tenant surface need an assume-role session.** A 403 there
   usually means no active session, not a mis-modeled role — check with