@sequenceholdings/studio-cli 0.1.13 → 0.1.21

package/README.md

@@ -1,21 +1,27 @@
 # `@sequenceholdings/studio-cli` — `seq-studio`
 
-Standalone CLI for the Sequence platform: Lattice processes, Artifact Studio
-apps, Managed Functions, Managed Secrets, and platform git repos. Runs from
-any repo against the platform over HTTP — no monorepo checkout required.
+Standalone CLI for the Sequence platform: typed agents, Lattice processes, Artifact Studio
+apps, Managed Functions, Managed Secrets, ORM namespaces, Data Pipelines stage
+specs, and platform git repos. Runs from any repo against the platform over
+HTTP — no monorepo checkout required.
 
 ```
 seq-studio process lint
 seq-studio process plan -e <env>
 seq-studio process apply -e <env>
+seq-studio agents validate
+seq-studio agents plan -e <env>
 seq-studio artifact deploy -e <env>
+seq-studio orm init lending
+seq-studio pipeline validate
 seq-studio envs list
 seq-studio doctor
 ```
 
 > **Note:** all network commands require a Sequence platform account with the
 > appropriate permissions. Without one, only the offline commands
-> (`init`, `lint`, `simulate`, `build`, `bundle inspect`) work.
+> (`init`, `lint`, `simulate`, `build`, `bundle inspect`, `agents init`,
+> `agents validate`, offline `agents plan`, `pipeline init`, `pipeline validate`) work.
 > Sequence-internal contributors: see `INTERNAL.md` in the monorepo for
 > rollout SOPs, preview environments, and publishing docs.
 
@@ -44,34 +50,43 @@ releases install immediately.)
 
 ## Authenticate
 
-Run the built-in browser login once. `seq-studio` and `seqapi` share the
-resulting tokens at `~/.config/sequence-api/tokens.json`, so logging in with
-either CLI authenticates both.
+Run the built-in browser login. `seq-studio` and `seqapi` share short-lived
+access tokens at `~/.config/sequence-api/tokens.json`, so logging in with either
+CLI authenticates both. Refresh tokens are neither requested nor persisted;
+interactive commands perform a bounded PKCE login again after expiry.
 
 ```bash
-seq-studio login
-seq-studio doctor   # confirms config + auth + authorization
+seq-studio login                              # built-in Sequence environments
+seq-studio envs add bsm-staging <tenant-url>  # one-time tenant registration
+seq-studio login --env bsm-staging            # registered OpCo tenant realm
+seq-studio doctor                             # confirms config + auth + authorization
 ```
 
-Use `seq-studio logout` to remove the shared cached tokens.
+Use `seq-studio logout` to remove the shared Sequence session, or
+`seq-studio logout --env bsm-staging` to remove only that OpCo realm's session.
 
 ### Headless auth (CI) — M2M
 
 When there's no interactive login (CI, automation), set the service-account
-secret and `seq-studio` mints a token via the Auth0 client-credentials grant
-(M2M wins when the secret is set, otherwise the cached user token is used):
+secret and `seq-studio` mints a token via the Auth0 client-credentials grant.
+A valid cached user session wins over an ambient M2M secret (common under
+Doppler `atlas/dev`); force the service account with `SEQAPI_AUTH_MODE=m2m`:
 
 ```bash
-export AUTH0_M2M_CLIENT_SECRET=...   # provided by your platform administrator
+export AUTH0_M2M_CLIENT_SECRET=...              # built-in Sequence environments
+export AUTH0_M2M_CLIENT_SECRET_BSM_STAGING=...  # registered bsm-staging realm
+export SEQAPI_AUTH_MODE=m2m                     # optional: ignore a leftover user session
 seq-studio artifact deploy -e <env>
 ```
 
-The secret is read at runtime — never commit it. M2M carries app scopes but
+Registered OpCo environment names are upper-snaked in the variable suffix
+(`bsm-staging` → `BSM_STAGING`). Secrets are read at runtime — never commit them.
+M2M carries app access but
 **no user identity / workspace membership**, so it's blind to
 user-scoped/private resources.
 
-**Manual escape hatch:** any `artifact` command also accepts an explicit
-`--token <jwt>`, which wins over both the M2M and cached-user paths.
+Artifact commands do not accept bearer tokens through argv or environment.
+Use interactive login or the realm-specific M2M secret above.
 
 ## Environments
 
@@ -82,7 +97,7 @@ environment-discovery endpoint and caches the result at
 `~/.config/lattice/environments.json`.
 
 ```bash
-seq-studio login            # or: export AUTH0_M2M_CLIENT_SECRET=...
+seq-studio login            # or use the matching M2M secret described above
 seq-studio envs refresh     # fetch the environments visible to your identity
 seq-studio envs list        # show them (name, URL, source)
 ```
@@ -93,8 +108,12 @@ see depends on who you are — unauthenticated installs get `local` only, and
 authenticated identities get the deployments they're entitled to. Visibility
 is not access control: every request is still authorized server-side.
 
-You can always add or override environments yourself in
-`~/.config/lattice/config.toml` (user entries win over discovered ones):
+You can add or override trusted environments yourself in
+`~/.config/lattice/config.toml` (user entries win over discovered ones).
+Authenticated requests accept only HTTPS origins at `seqholdings.com` or its
+subdomains, plus HTTP loopback origins for local development. The CLI
+revalidates that exact origin immediately before attaching credentials and
+never follows authenticated redirects.
 
 ```toml
 # Must come before any [env.*] table — TOML attaches bare keys to the
@@ -105,7 +124,7 @@ default_env = "local"
 url = "http://localhost:5001"
 
 [env.my-atlas]
-url = "https://atlas.example.com"
+url = "https://my-atlas.seqholdings.com"
 ```
 
 Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
@@ -115,6 +134,101 @@ Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
 the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 `artifact link` / `artifact env use`).
 
+## Agent commands
+
+Typed agent repositories export one or more `defineAgent(...)` values from files
+named `agent.ts`. Definitions are compiled in a credential-scrubbed child process,
+validated with the published `@sequenceholdings/agent-spec` contract, normalized,
+and hashed before deployment. Apply creates or updates only the definitions in the
+bundle; it never implicitly deletes agents.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio agents init <dir>` | Scaffold a standalone typed agent repository |
+| `seq-studio agents validate [--dir <dir>] [--target <APP_ENV>]` | Compile and validate locally, without API access |
+| `seq-studio agents plan [--dir <dir>]` | Offline compile/hash plan |
+| `seq-studio agents plan [--dir <dir>] -e <env> [--target <APP_ENV>]` | Diff creates, updates, and unchanged definitions against an environment |
+| `seq-studio agents apply [--dir <dir>] -e <env> [--target <APP_ENV>] [--yes]` | Apply creates and updates after showing the plan |
+| `seq-studio agents list -e <env>` | List visible runtime agents |
+| `seq-studio agents show <id> -e <env>` | Show one runtime agent |
+
+An optional `deploy-manifest.json` targets definitions by deployment identity:
+
+```json
+{
+  "schemaVersion": 1,
+  "definitions": [
+    {
+      "id": "680000000000000000000001",
+      "path": "support/agent.ts",
+      "environments": ["local", "staging", "production"]
+    }
+  ]
+}
+```
+
+Standalone workflow:
+
+```bash
+pnpm dlx @sequenceholdings/studio-cli agents init support-agent
+cd support-agent
+pnpm install
+pnpm exec seq-studio agents validate
+pnpm exec seq-studio agents plan
+# Authenticate only when ready to inspect or apply an environment:
+pnpm exec seq-studio login
+pnpm exec seq-studio agents plan -e <env>
+pnpm exec seq-studio agents apply -e <env>
+```
+
+Use `--repo agents/<name> [--ref <ref>]` or `--git-url <url>` instead of
+`--dir` to materialize reviewed source from the platform git service.
+
+## ORM commands
+
+`seq-studio orm` authors and deploys governed ORM v2 namespaces: TypeScript
+table definitions and policies plus named GraphQL documents compiled into
+persisted operations.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio orm init <dir>` | Scaffold one v2 namespace package (`sequence.config.ts`, `schema/*.ts`, `graphql/**`, and codegen config). |
+| `seq-studio orm generate [dir]` | Generate `schema.graphql`, `operations.manifest.json`, `typePolicies.gen.ts`, and consumer codegen when `codegen.ts` is present. |
+| `seq-studio orm validate [dir]` | Parse and compile the namespace, then verify its committed migration chain is current. |
+| `seq-studio orm plan [dir] -e <env>` | Compare the compiled namespace with registry state without applying database changes. |
+| `seq-studio orm diff [dir] [--check]` | Author the next committed migration, or verify the migration/snapshot chain offline for CI. |
+| `seq-studio orm apply [dir] -e <env>` | Author a migration if needed, register/apply the namespace, activate its operation set, publish roles/capabilities, and refresh generated outputs. |
+| `seq-studio orm migrate-from-yaml <dir>` | Convert a legacy YAML namespace to TypeScript authoring while preserving its committed migrations. |
+
+The everyday loop is:
+
+```bash
+seq-studio orm init lending
+cd lending
+pnpm install
+
+# Edit sequence.config.ts, schema/*.ts, and graphql/**/*.ts.
+seq-studio orm generate .
+seq-studio orm plan . -e local
+seq-studio orm apply . -e local
+seq-studio orm validate .
+```
+
+`apply --dry-run` rehearses a migration against a disposable branch copy of
+the target environment's data. `apply --no-create` is the CI guard that refuses
+to provision a missing namespace. Destructive DDL requires explicit
+`--allow-destructive` consent.
+
+> **ORM v2 branch status:** the scaffold currently depends on
+> `@sequenceholdings/orm@^2.0.0`, which is not published yet; the registry's
+> latest release is the v1 `0.1.1` package. A clean standalone scaffold cannot
+> complete `pnpm install` until the v2 ORM dependency chain is released. Do not
+> use monorepo workspace links as evidence that the external workflow is ready.
+> Sequence contributors should see
+> [`docs/platform/orm-v2.md`](../../../docs/platform/orm-v2.md) for the branch
+> architecture, internal verification workflow, demo, and remaining rollout
+> gates.
+
 ## Process commands
 
 | Command | What it does |
@@ -123,9 +237,9 @@ the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 | `seq-studio process lint` | Static checks (graph, return contracts, agent schema, timeouts) |
 | `seq-studio process plan -e <env>` | Build bundle, diff against currently-active version |
 | `seq-studio process apply -e <env> [--only <id1,id2>]` | Build → register bundle → promote each process. `--only` promotes just the named process ids (the bundle still contains the whole root — registration is inert) |
-| `seq-studio process apply --repo processes/<name> [--ref <r>] -e <env> [--only <id1,id2>]` | Same as above, but materializes the source from a platform git-service repo. Pinned commit SHA is injected as bundle provenance. Requires `ATLAS_GIT_PAT` (or `AUTH0_M2M_CLIENT_SECRET` for CI) |
+| `seq-studio process apply --repo processes/<name> [--ref <r>] -e <env> [--only <id1,id2>]` | Same as above, but materializes the source from a platform git-service repo. Pinned commit SHA is injected as bundle provenance. Requires `ATLAS_GIT_PAT` (or the target realm's M2M secret for CI) |
 | `seq-studio process test -e <env>` | CI wrapper: lint + plan, non-zero exit on errors or BREAKING diffs |
-| `seq-studio process simulate <id>` | In-process walk with stubbed runners (offline) |
+| `seq-studio process simulate <id>` | Isolated child-process walk with stubbed runners (offline) |
 | `seq-studio process bundle build [-o file.json]` | Build a bundle locally |
 | `seq-studio process bundle pull <hash> [-e <env>] [-o file.json]` | Fetch a stored bundle |
 | `seq-studio process bundle inspect <bundle.json>` | Show a saved bundle's summary |
@@ -149,7 +263,16 @@ temp tree is cleaned up — even on error. Only the `processes` namespace is
 accepted; other namespaces (artifacts, managed-functions) are rejected.
 
 Auth: same as `artifact deploy --repo` — `ATLAS_GIT_PAT` for the smart-HTTP
-clone path, or `AUTH0_M2M_CLIENT_SECRET` for CI's JSON materialize path.
+clone path, or the target realm's M2M secret for CI's JSON materialize path.
+Those credentials remain in the parent CLI and are not forwarded to dependency
+installation or process build tooling. Each install uses fresh temporary
+package-manager caches that are removed after the invocation.
+
+This is ambient-credential isolation, not an OS security sandbox. Build workers
+still run as the caller's uid, so hostile source may inspect other same-uid
+processes or readable files on platforms that permit it (for example, Linux
+`/proc`). Build reviewed source only; use a dedicated ephemeral runner with no
+unrelated credentials when the source is not trusted.
 
 ### Process discovery
 
@@ -171,6 +294,47 @@ cd my-processes
 seq-studio process lint     # finds both processes
 ```
 
+## Managed Function commands
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio functions init <dir>` | Scaffold one standalone TypeScript managed function |
+| `seq-studio functions build [--dir <dir>]` | Validate a local manifest, bundle, lockfile, and size |
+| `seq-studio functions deploy --dir <dir> -e <env>` | Preview secrets and deploy a local function |
+| `seq-studio functions build --repo managed-functions/<name> [--path <dir>] -e <env>` | Materialize and validate a function from the platform Git Service |
+| `seq-studio functions deploy --repo managed-functions/<name> [--path <dir>] -e <env>` | Materialize and deploy a function from the platform Git Service |
+
+A normal function repo keeps `managed-function.yml` at its root and omits
+`--path`. A repo may also contain related, independently deployed functions:
+
+```text
+functions/
+  get-loan/
+    managed-function.yml
+    package.json
+    pnpm-lock.yaml
+    index.ts
+  update-loan/
+    managed-function.yml
+    package.json
+    pnpm-lock.yaml
+    index.ts
+```
+
+Select exactly one function directory for each build or deploy:
+
+```bash
+seq-studio functions build --repo managed-functions/encompass \
+  --path functions/get-loan -e staging
+seq-studio functions deploy --repo managed-functions/encompass \
+  --path functions/get-loan -e staging
+```
+
+Each selected directory is a self-contained function package. Functions in the
+same repo share Git review and commit provenance, but keep separate manifests,
+versions, runtime resources, secrets, and permissions. `--path` accepts only a
+canonical relative directory inside a remote repo; use `--dir` for local source.
+
 ## Artifact commands
 
 `seq-studio artifact <sub>` is the entry point for Artifact Studio. It runs
@@ -183,11 +347,11 @@ routed through `~/.config/lattice/config.toml` and the shared seqapi token.
 | `seq-studio artifact link [dir] -e <env> [--project <id>]` | `link [dir] --env <env>` |
 | `seq-studio artifact build [dir]` | `build [dir]` |
 | `seq-studio artifact plan [dir] -e <env>` | `plan [dir] --env <env>` |
-| `seq-studio artifact deploy [dir] -e <env> [--skip-unchanged] [--no-create] [--project <id>]` | `deploy [dir] --env <env>` — `--skip-unchanged` no-ops (before building) when the remote active deployment's `sourceHash` already matches the local source; `--no-create` errors instead of creating a missing project; `--project <id>` targets a project directly when duplicate slugs make the lookup ambiguous (slug must still match the manifest) |
+| `seq-studio artifact deploy [dir] -e <env> [--skip-unchanged] [--no-create] [--project <id>]` | `deploy [dir] --env <env>` — `--skip-unchanged` no-ops (before building) when the remote active deployment's `sourceHash` **and** CLI/atlas-ui peer versions already match; `--no-create` errors instead of creating a missing project; `--project <id>` targets a project directly when duplicate slugs make the lookup ambiguous (slug must still match the manifest) |
 | `seq-studio artifact dev [dir] -e <env>` | `dev [dir] --env <env>` |
 | `seq-studio artifact pull <project-id> -e <env> [--out <dir>]` | `pull <project-id> --env <env> [--out <dir>]` |
 | `seq-studio artifact list -e <env>` | `list --env <env>` — projects visible on the environment (slug, id, active version, visibility) |
-| `seq-studio artifact show <slug-or-id> -e <env>` | `show <slug-or-id> --env <env>` — one project's detail incl. active deployment + git provenance |
+| `seq-studio artifact show <slug-or-id> -e <env>` | `show <slug-or-id> --env <env>` — one project's detail incl. active deployment, git provenance, and (for newer deployments) the building `artifact-studio` / force-aliased `atlas-ui` versions |
 | `seq-studio artifact promote <deployment-id> -e <env>` | `promote <deployment-id> --env <env>` |
 | `seq-studio artifact rollback <deployment-id> -e <env>` | `rollback <deployment-id> --env <env>` |
 
@@ -197,6 +361,18 @@ routed through `~/.config/lattice/config.toml` and the shared seqapi token.
 directory's `.artifact-studio/config.json` — run them from the linked artifact
 folder (or run `seq-studio artifact link` first).
 
+**Active (official) deploys require a clean `main` checkout with a resolved
+git commit** for both Git Service (`--repo`) and local sources. Feature
+branches, dirty trees, non-git sources, and detached checkouts that cannot be
+attributed to `main` are preview-only
+(`seq-studio artifact dev` / preview channel); promotion applies the same
+provenance check.
+
+**CLI atlas-ui stamp (DES-254):** builds force-alias `@sequenceholdings/atlas-ui`
+to the CLI's copy — not the artifact's declared semver. Deployments record
+`cliVersion` + `atlasUiVersion`. Contract:
+`@sequenceholdings/artifact-studio` → `VERSION-PIN.md`.
+
 ### Source for `build` / `plan` / `deploy`
 
 These three commands read their source tree from one of three places — the rest
@@ -206,14 +382,28 @@ of the pipeline (build → upload) is identical regardless of origin:
 |------|--------|
 | _(none)_ / `[dir]` | a local folder (default, unchanged) |
 | `--repo <ns>/<name>` | a repo in the platform Git Service, e.g. `--repo artifacts/accounts` |
-| `--git-url <url>` | any git URL (cloned to a temp dir) |
+| `--git-url <url>` | a public, credential-free HTTPS git URL (cloned to a temp dir) |
 
-`--ref <branch\|tag\|commit>` selects the revision (default: the repo's default
-branch). A remote source is materialized to a temp dir, built, and torn down;
+`--ref <branch\|tag\|commit>` selects the revision for `build` and `plan`
+(default: the repo's default branch). Active `deploy` requires `main`; other
+refs are preview-only. A remote source is materialized to a temp dir, built,
+and torn down;
 the target project is resolved from the source's `artifact.bundle.yml`
 `project_id`. The deployment records the resolved commit as its `git_commit`
-provenance. `--repo` needs `-e <env>` + a platform login; `--git-url` needs git
-credentials for private repos. `dev` is local-only.
+provenance. `--repo` needs `-e <env>` + a platform login. M2M/CI builds accept
+only platform-managed `--repo` sources; `--git-url` is interactive-only and
+rejects embedded credentials, query tokens, SSH/file URLs, and Git remote
+helpers. `dev` is local-only.
+
+Artifact builds, dependency installs, process-definition imports, and local
+process simulations run in short-lived children with an allowlisted runtime
+environment and a synthetic home/config directory. Parent bearer tokens, Auth0
+M2M secrets, Doppler tokens, cloud credentials, GitHub tokens, and user config
+files are not inherited. The platform Git Service clone path passes only its
+single scoped PAT to `git` through an ephemeral askpass helper.
+This is a credential-inheritance boundary, not an OS filesystem sandbox:
+child code still runs as the invoking user and must be treated as trusted to
+read files that it names explicitly outside the synthetic home.
 
 ## Pull / clone / deploy — which path?
 
@@ -252,7 +442,7 @@ You can also open **Repositories → Access tokens** / the clone popover’s
 Requires Auth0 login. Same identity as the UI:
 
 ```bash
-seq-studio login
+seq-studio login   # add --env <registered-opco-env> for a tenant realm
 seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e <env>
 # optional: --expires 7d|30d|90d|1y|never  (default 30d)
 # optional: --store-credentials   # git credential approve for the env host
@@ -270,18 +460,48 @@ JSON API — the same repos `--repo <ns>/<name>` sources build from.
 
 | Command | What it does |
 |---------|--------------|
-| `seq-studio repos list [-e <env>] [--namespace <slug>] [--mine]` | repos visible on the environment (permission-filtered) |
-| `seq-studio repos namespaces [create <slug>] [-e <env>]` | list namespaces, or create one (creator becomes owner) |
-| `seq-studio repos show <ns>/<name> [-e <env>]` | detail: id, branches, clone URL; artifact project id when slug matches |
-| `seq-studio repos create <ns>/<name> [-e <env>] [--default-branch <b>]` | create an empty repo (needs namespace write) |
-| `seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> [-e <env>] [--ref <r>] [--out <dir>] [--force]` | smart-HTTP `git clone` when `ATLAS_GIT_PAT` is set (`--url`/`--id` need no seqapi); otherwise JSON materialize + PAT hint |
-| `seq-studio repos pull <ns>/<name> [-e <env>] [--ref <r>] [--out <dir>] [--force]` | always materialize via JSON API (no `.git` dir); refuses a non-empty destination unless `--force` |
-| `seq-studio repos delete <ns>/<name> [-e <env>] [--yes]` | delete a repo — interactive confirm unless `--yes` |
+| `seq-studio repos list -e <env> [--namespace <slug>] [--mine]` | repos visible on the environment (permission-filtered) |
+| `seq-studio repos namespaces [create <slug>] -e <env>` | list namespaces, or create one (creator becomes owner) |
+| `seq-studio repos show <ns>/<name> -e <env>` | detail: id, branches, clone URL; artifact project id when slug matches |
+| `seq-studio repos create <ns>/<name> -e <env> [--default-branch <b>]` | create an empty repo (needs namespace write) |
+| `seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> -e <env> [--ref <r>] [--out <dir>] [--force]` | smart-HTTP `git clone` when `ATLAS_GIT_PAT` is set (`--url`/`--id` need no seqapi); otherwise JSON materialize + PAT hint |
+| `seq-studio repos pull <ns>/<name> -e <env> [--ref <r>] [--out <dir>] [--force]` | always materialize via JSON API (no `.git` dir); refuses a non-empty destination unless `--force` |
+| `seq-studio repos delete <ns>/<name> -e <env> [--yes]` | delete a repo — interactive confirm unless `--yes` |
 
 `show` prints the smart-HTTP clone URL (`…/repos/<id>/git`). Basic auth:
 any username, PAT as password. Prefer `repos clone` over hand-rolling the
 tree API.
 
+## Pipeline commands
+
+`seq-studio pipeline <sub>` authors and validates Data Pipelines **stage
+specs** — the typed contracts (`<name>.stage.yml`) a Pipeline repo
+(`pipelines/<domain>`) is made of. Validation logic lives in
+`@sequenceholdings/pipeline-spec` (an optional peer, like `@sequenceholdings/orm`);
+install it alongside the CLI to use this family.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>]` | Scaffold `<name>.stage.yml` (commented per-kind template) plus a `src/` entrypoint stub (serving stages are declarative — no stub). Refuses to overwrite an existing spec |
+| `seq-studio pipeline validate [dir] [--assets <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Exit 0/1 |
+| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
+| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha> -e <env> [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Production/banksouth require a pinned 40-hex SHA (client + server) |
+| `seq-studio pipeline run-now --stage <slug> -e <env> [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
+| `seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Promote a validated version to another environment. Prod/banksouth require `--approved-by` naming the authenticated caller (approvals are self-recorded); `--repo` disambiguates a slug that exists in multiple Pipelines |
+| `seq-studio pipeline rollback --stage <slug> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Redeploy the previously retired deployment's version. Prod/banksouth require `--approved-by` — approvals are explicit even for rollbacks |
+
+`validate` is offline — no network or database. `--assets` supplies a
+registry **asset export** (JSON) so inputs referencing other Pipelines'
+assets resolve; pass a local file or an authenticated URL. `--json` emits a
+stable machine shape (`{ ok, stages, findings[] }` with machine-readable
+finding codes and consumer lists) for CI annotation — the
+`pipeline-verify.yml` workflow runs exactly this on PRs touching
+`pipelines/**`.
+
+For local Atlas development, `-e local` uses the server's isolated `dev`
+deployment target. Plan, deploy, and `run-now` therefore operate on the same
+personal dev Databricks catalog and Lakebase branch configured for local Atlas.
+
 ## Authorization
 
 The CLI carries no permissions of its own: every request is authorized

package/dist/agents/apply-chunks.d.ts

@@ -0,0 +1,13 @@
+import { type AgentDefinition } from '@sequenceholdings/agent-spec';
+import { type CommandContext } from '../functions/commands.js';
+export interface ApplySummary {
+    created: number;
+    updated: number;
+    unchanged: number;
+}
+/** Each chunk is hashed over its own definitions — the apply route validates the body it received. */
+export declare function applyInChunks({ context, definitions, source, }: {
+    context: CommandContext;
+    definitions: AgentDefinition[];
+    source: string;
+}): Promise<ApplySummary>;

package/dist/agents/apply-chunks.js

@@ -0,0 +1,43 @@
+import { hashAgentBundle, } from '@sequenceholdings/agent-spec';
+import { postJson } from '../atlas-client.js';
+import { clientOptions } from '../functions/commands.js';
+const LOG = '[seq-studio]';
+// Chunked to stay inside the HTTP client's timeout; each agent commits independently anyway.
+const APPLY_CHUNK_SIZE = 20;
+/** Each chunk is hashed over its own definitions — the apply route validates the body it received. */
+export async function applyInChunks({ context, definitions, source, }) {
+    const chunks = [];
+    for (let i = 0; i < definitions.length; i += APPLY_CHUNK_SIZE) {
+        chunks.push(definitions.slice(i, i + APPLY_CHUNK_SIZE));
+    }
+    const total = { created: 0, updated: 0, unchanged: 0 };
+    let applied = 0;
+    for (const [index, chunk] of chunks.entries()) {
+        try {
+            const result = await postJson({
+                ...clientOptions(context),
+                path: '/api/agents/deploy/apply',
+                body: {
+                    definitions: chunk,
+                    bundleHash: hashAgentBundle({ definitions: chunk }),
+                    source,
+                },
+            });
+            total.created += result.summary.created;
+            total.updated += result.summary.updated;
+            total.unchanged += result.summary.unchanged;
+            applied += chunk.length;
+            if (chunks.length > 1) {
+                console.log(`${LOG} batch ${index + 1}/${chunks.length}: ${applied} of ${definitions.length} agents`);
+            }
+        }
+        catch (error) {
+            // Name what already landed. Without it a mid-run failure reads as a total
+            // failure, and the operator cannot tell which agents are already on the
+            // new definition.
+            console.error(`${LOG} batch ${index + 1}/${chunks.length} failed after ${applied} of ${definitions.length} agents applied — re-run to resume`);
+            throw error;
+        }
+    }
+    return total;
+}

package/dist/agents/commands.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedArgs } from '../process/commands.js';
+import { agentsInitCommand } from './scaffold.js';
+export { agentsInitCommand };
+export declare function agentsValidateCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsPlanCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsApplyCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsListCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsShowCommand(args: ParsedArgs): Promise<number>;
+export declare const AGENTS_USAGE = "usage:\n  seq-studio agents init <dir>                         scaffold a typed agent\n  seq-studio agents validate [--dir d] [--target app] offline compile + validation\n  seq-studio agents plan [--dir d] [-e <env>]          offline bundle plan or live diff\n  seq-studio agents apply [--dir d] -e <env> [--yes]  apply creates/updates; never deletes\n  seq-studio agents list -e <env>                      list visible agents\n  seq-studio agents show <id> -e <env>                 show one agent\n\n  Source: local --dir (default .), --repo agents/<name>, or --git-url <url>.\n  Use --ref for remote sources. --target selects the deployment APP_ENV when it\n  differs from the CLI environment alias (notably OpCo registrations).\n";
+export declare function runAgentsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;