@sequenceholdings/studio-cli 0.1.24 → 0.1.26

package/dist/auth.js

@@ -40,6 +40,12 @@ const AUTH0_M2M_CLIENT_ID = '5TLffZqvLq4ztLDjZhwKVJCpB5VNrWj0';
  * also the implicit realm of the legacy flat fields in tokens.json. */
 export const SEQUENCE_REALM = 'sequence';
 const SEQUENCE_BUILTIN_ENVS = new Set(['local', 'staging', 'production', 'banksouth']);
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+const SEQUENCE_STAGING_AUTH0_AUDIENCE = 'https://staging.sequence.seqholdings.com/api';
+const TRUSTED_LOOPBACK_AUTH0_AUDIENCES = new Set([
+    AUTH0_AUDIENCE,
+    SEQUENCE_STAGING_AUTH0_AUDIENCE,
+]);
 export function isSequenceAuthEnvName(envName) {
     return (envName === SEQUENCE_REALM ||
         SEQUENCE_BUILTIN_ENVS.has(envName) ||
@@ -76,14 +82,116 @@ export const SEQUENCE_AUTH_REALM = {
 function seqapiConfigPath() {
     return join(seqapiTokenDir(), 'config.json');
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isLoopbackEnvName(envName) {
+    return envName === 'local' || envName.startsWith('local:');
+}
+function loopbackTargetUrl({ configuredTargetUrl, envName, }) {
+    if (configuredTargetUrl)
+        return configuredTargetUrl;
+    return envName === 'local' ? 'http://localhost:5001' : undefined;
+}
+function optionalString({ field, value, }) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    throw new Error(`Local Auth0 discovery returned invalid '${field}'.`);
+}
+function parseDiscoveredAuth0(payload) {
+    const auth0 = isRecord(payload) ? Reflect.get(payload, 'auth0') : undefined;
+    const auth0Record = isRecord(auth0) ? auth0 : {};
+    const domain = Reflect.get(auth0Record, 'domain');
+    const clientId = Reflect.get(auth0Record, 'clientId');
+    const audience = Reflect.get(auth0Record, 'audience');
+    if (typeof domain !== 'string' ||
+        !domain ||
+        typeof clientId !== 'string' ||
+        !clientId ||
+        typeof audience !== 'string' ||
+        !audience) {
+        throw new Error('Local Auth0 discovery returned incomplete required config.');
+    }
+    return {
+        domain,
+        clientId,
+        audience,
+        organization: optionalString({
+            field: 'organization',
+            value: Reflect.get(auth0Record, 'organization'),
+        }),
+        m2mClientId: optionalString({
+            field: 'm2mClientId',
+            value: Reflect.get(auth0Record, 'm2mClientId'),
+        }),
+    };
+}
+async function discoverLoopbackRealm({ envName, fetchImpl = fetch, targetUrl, }) {
+    const baseUrl = validateDeploymentBaseUrl(targetUrl);
+    const hostname = new URL(baseUrl).hostname.toLowerCase();
+    if (!LOOPBACK_HOSTNAMES.has(hostname))
+        return SEQUENCE_AUTH_REALM;
+    let response;
+    try {
+        response = await fetchImpl(`${baseUrl}/api/auth/cli-config`, {
+            redirect: 'error',
+            signal: AbortSignal.timeout(2_000),
+        });
+    }
+    catch {
+        // Preserve the historical realm choice while local Atlas is stopped. The
+        // subsequent API request reports that the local server is unavailable.
+        return SEQUENCE_AUTH_REALM;
+    }
+    if (!response.ok) {
+        throw new Error(`Could not discover Auth0 config for local environment '${envName}': ` +
+            `${baseUrl}/api/auth/cli-config returned HTTP ${response.status}.`);
+    }
+    const payload = await response.json();
+    const { audience, clientId, domain, m2mClientId, organization } = parseDiscoveredAuth0(payload);
+    if (!TRUSTED_LOOPBACK_AUTH0_AUDIENCES.has(audience)) {
+        throw new Error(`Untrusted Auth0 audience '${audience}' for local environment '${envName}'.`);
+    }
+    const trustedDomain = validateAuth0Domain(domain);
+    if (clientId === AUTH0_CLIENT_ID && audience === AUTH0_AUDIENCE) {
+        return SEQUENCE_AUTH_REALM;
+    }
+    return {
+        name: 'local',
+        domain: trustedDomain,
+        clientId,
+        audience,
+        organization,
+        m2mClientId,
+    };
+}
+async function maybeDiscoverLoopbackRealm({ envName, options, }) {
+    if (!envName || !isLoopbackEnvName(envName))
+        return undefined;
+    const targetUrl = loopbackTargetUrl({
+        configuredTargetUrl: options.targetUrl,
+        envName,
+    });
+    if (!targetUrl)
+        return undefined;
+    return discoverLoopbackRealm({
+        envName,
+        fetchImpl: options.fetchImpl,
+        targetUrl,
+    });
+}
 /**
  * Resolve the auth realm for an environment name. Undefined, built-ins, and
- * per-PR preview targets map to the shared Sequence realm. Preview URLs are
- * constrained to Sequence's preview domain by the environment resolver. Every
- * other explicit name must have a valid seqapi registry entry; otherwise fail
- * closed so a shared Sequence bearer token can never be sent to a tenant URL.
+ * per-PR preview targets map to the shared Sequence realm, except loopback
+ * targets can advertise the isolated Sequence-staging realm used by contractor
+ * local dev. Every other explicit name must have a valid seqapi registry entry.
  */
-export async function realmForEnv(envName) {
+export async function realmForEnv(envName, options = {}) {
+    const discoveredRealm = await maybeDiscoverLoopbackRealm({ envName, options });
+    if (discoveredRealm)
+        return discoveredRealm;
     if (!envName || isSequenceAuthEnvName(envName)) {
         return SEQUENCE_AUTH_REALM;
     }
@@ -303,7 +411,12 @@ function validateRealmTarget({ realm, targetUrl, }) {
     try {
         const baseUrl = validateDeploymentBaseUrl(targetUrl);
         if (realm.name !== SEQUENCE_REALM) {
-            validateDeploymentAudience({ audience: realm.audience, baseUrl });
+            const hostname = new URL(baseUrl).hostname.toLowerCase();
+            const isReviewedLoopbackRealm = LOOPBACK_HOSTNAMES.has(hostname) &&
+                TRUSTED_LOOPBACK_AUTH0_AUDIENCES.has(realm.audience);
+            if (!isReviewedLoopbackRealm) {
+                validateDeploymentAudience({ audience: realm.audience, baseUrl });
+            }
         }
     }
     catch (error) {
@@ -312,7 +425,7 @@ function validateRealmTarget({ realm, targetUrl, }) {
     }
 }
 export async function getAccessTokenWithMode(options) {
-    const realm = await realmForEnv(options?.env);
+    const realm = await realmForEnv(options?.env, { targetUrl: options?.targetUrl });
     if (options?.targetUrl)
         validateRealmTarget({ realm, targetUrl: options.targetUrl });
     const forceM2m = authModePrefersM2m();
@@ -377,7 +490,7 @@ export async function tryGetAccessTokenWithMode(options) {
             // Do not replace an invalid tenant registration with the Sequence realm:
             // that could hide a rejected discovery token host or inspect the wrong
             // M2M secret. Config-resolution errors must surface unchanged.
-            const realm = await realmForEnv(options.env);
+            const realm = await realmForEnv(options.env, { targetUrl: options.targetUrl });
             if (process.env[m2mSecretEnvName(realm)]?.trim())
                 throw err;
         }

package/dist/config.d.ts

@@ -24,14 +24,18 @@ export declare function defaultConfig(): LatticeConfig;
  * Read the effective config. Merge precedence (later wins):
  *
  *   1. built-in `local`
- *   2. the cached discovered catalog (`~/.config/lattice/environments.json`)
- *   3. user entries in config.toml (an override for `local`, or net-new envs)
- *   4. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
+ *   2. local worktrees discovered from `.wt.env`
+ *   3. the cached discovered catalog (`~/.config/lattice/environments.json`)
+ *   4. user entries in config.toml (an override for `local`, or net-new envs)
+ *   5. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
  *
  * Registered OpCo routes are authoritative for their names so a lower-trust
  * config.toml override cannot send a tenant token to another origin.
  */
 export declare function readConfig(): Promise<LatticeConfig>;
+export declare function localAuthRealmOptions(envName?: string): Promise<{
+    targetUrl?: string;
+}>;
 /** Write the config to disk, creating the dir if missing. */
 export declare function writeConfig(config: LatticeConfig): Promise<void>;
 export interface ResolvedEnv {

package/dist/config.js

@@ -1,7 +1,9 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { promisify } from 'node:util';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { M2mTokenError } from './auth.js';
 import { fetchCatalog, readCachedCatalog, } from './env-catalog.js';
@@ -26,7 +28,69 @@ export const PREVIEW_ENV_PREFIX = 'preview:';
 const BUILT_IN_ENV_URLS = {
     local: 'http://localhost:5001',
 };
+const execFileAsync = promisify(execFile);
+const WORKTREE_ENV_PREFIX = 'local:';
+const WORKTREE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 export const ENV_NAMES = Object.keys(BUILT_IN_ENV_URLS);
+async function atlasPortFromWorktreeEnv(directory) {
+    let text;
+    try {
+        text = await readFile(join(directory, '.wt.env'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const value = text
+        .split('\n')
+        .map((line) => line.split('=', 2))
+        .find(([key]) => key?.trim() === 'ATLAS_PORT')?.[1]
+        ?.trim();
+    if (!value || !/^\d+$/.test(value))
+        return undefined;
+    const port = Number(value);
+    return port >= 1 && port <= 65_535 ? port : undefined;
+}
+async function worktreeDirectories() {
+    const root = process.env.WT_ROOT ?? join(homedir(), 'studio-worktrees');
+    const directories = [];
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        directories.push(...entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(root, entry.name)));
+    }
+    catch {
+        // The default worktree root is optional.
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain']);
+        const gitWorktrees = stdout
+            .split('\n')
+            .filter((line) => line.startsWith('worktree '))
+            .map((line) => line.slice('worktree '.length))
+            .slice(1);
+        directories.push(...gitWorktrees);
+    }
+    catch {
+        // Global CLI use outside a git checkout still supports WT_ROOT discovery.
+    }
+    return [...new Set(directories)];
+}
+async function worktreeEnvironmentUrls() {
+    const environments = {};
+    for (const directory of await worktreeDirectories()) {
+        const name = basename(directory);
+        if (!WORKTREE_NAME_PATTERN.test(name))
+            continue;
+        const port = await atlasPortFromWorktreeEnv(directory);
+        if (port === undefined)
+            continue;
+        environments[`${WORKTREE_ENV_PREFIX}${name}`] ??= {
+            url: `http://localhost:${port}`,
+        };
+    }
+    return environments;
+}
 export function globalConfigDir() {
     return join(homedir(), '.config', 'lattice');
 }
@@ -44,15 +108,17 @@ export function defaultConfig() {
  * Read the effective config. Merge precedence (later wins):
  *
  *   1. built-in `local`
- *   2. the cached discovered catalog (`~/.config/lattice/environments.json`)
- *   3. user entries in config.toml (an override for `local`, or net-new envs)
- *   4. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
+ *   2. local worktrees discovered from `.wt.env`
+ *   3. the cached discovered catalog (`~/.config/lattice/environments.json`)
+ *   4. user entries in config.toml (an override for `local`, or net-new envs)
+ *   5. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
  *
  * Registered OpCo routes are authoritative for their names so a lower-trust
  * config.toml override cannot send a tenant token to another origin.
  */
 export async function readConfig() {
     const merged = defaultConfig();
+    Object.assign(merged.envs, await worktreeEnvironmentUrls());
     const catalog = await readCachedCatalog();
     if (catalog) {
         merged.tier = catalog.tier;
@@ -80,6 +146,12 @@ export async function readConfig() {
     }
     return merged;
 }
+export async function localAuthRealmOptions(envName) {
+    if (!envName || (envName !== 'local' && !envName.startsWith('local:'))) {
+        return {};
+    }
+    return { targetUrl: (await readConfig()).envs[envName]?.url };
+}
 /** Write the config to disk, creating the dir if missing. */
 export async function writeConfig(config) {
     const path = configPath();

package/dist/envs/commands.js

@@ -14,7 +14,8 @@ const ENVS_USAGE = `usage:
   catalog is cached at ~/.config/lattice/environments.json and also refreshes
   lazily the first time you pass an -e <env> that isn't cached yet.
 
-  Custom entries in ${configPath()} are always honored on top.
+  Local worktrees are discovered from their .wt.env files. Custom entries in
+  ${configPath()} are always honored on top.
 `;
 export async function runEnvsCommand(sub, rest) {
     switch (sub) {
@@ -97,11 +98,13 @@ async function listCommand() {
     for (const [name, { url }] of Object.entries(config.envs)) {
         const source = name === 'local' && !discovered.has(name)
             ? 'built-in'
-            : discovered.has(name)
-                ? 'discovered'
-                : registeredNames.has(name)
-                    ? 'registered'
-                    : 'config.toml';
+            : name.startsWith('local:')
+                ? 'worktree'
+                : discovered.has(name)
+                    ? 'discovered'
+                    : registeredNames.has(name)
+                        ? 'registered'
+                        : 'config.toml';
         console.log(`  ${name.padEnd(width)}  ${url}  (${source})`);
     }
     if (config.tier === 'anonymous') {

package/dist/functions/bundle.js

@@ -59,13 +59,13 @@ export async function validateLocalBundle({ rootDir, files, }) {
         if (existsSync(join(rootDir, 'package-lock.json')) || existsSync(join(rootDir, 'yarn.lock'))) {
             issues.push({
                 level: 'warning',
-                message: 'Found a non-pnpm lockfile (package-lock.json / yarn.lock). It is ignored — the deploy worker resolves dependencies against Chainguard, Sequence\'s internal registry. With Chainguard credentials, `pnpm install` produces a pinned lockfile for a faster deploy; without them this is fine as-is.',
+                message: 'Found a non-pnpm lockfile (package-lock.json / yarn.lock). It is ignored; dependencies are resolved server-side at deploy time.',
             });
         }
         else {
             issues.push({
                 level: 'info',
-                message: 'No pnpm-lock.yaml — the deploy worker will resolve dependencies against Chainguard, Sequence\'s internal registry. With Chainguard credentials, `pnpm install` produces a pinned lockfile for a faster deploy; without them this is fine as-is.',
+                message: 'No pnpm-lock.yaml — dependencies are resolved server-side at deploy time.',
             });
         }
     }
@@ -76,7 +76,7 @@ export async function validateLocalBundle({ rootDir, files, }) {
         if (classifyLockfileOrigin(lockfileText) !== 'chainguard') {
             issues.push({
                 level: 'warning',
-                message: 'pnpm-lock.yaml was not resolved against Chainguard — the deploy worker will discard it and re-resolve (slower, and versions may differ). This is expected without Chainguard credentials; with them, regenerate against Chainguard (registry=https://libraries.cgr.dev/javascript/) for a fast, pinned deploy.',
+                message: 'pnpm-lock.yaml cannot be used for this deployment, so dependencies are resolved server-side at deploy time. Resolved versions may differ.',
             });
         }
     }

package/dist/functions/commands.js

@@ -202,6 +202,12 @@ limits:
   max_instances: 3
   invoke_rate_per_minute: 60
 
+# Optional source-IP gate, checked before invocation permissions. Omit or leave
+# empty for unrestricted source IPs.
+# invocation:
+#   allowed_ip_ranges:
+#     - 203.0.113.0/24
+
 # Env-var names the function expects (UPPER_SNAKE_CASE). Values are read
 # from a local .env file at deploy time — they are never committed or bundled.
 secrets: []
@@ -325,10 +331,6 @@ export async function functionsInitCommand(args) {
     console.log('');
     console.log('Next steps (init is only needed when creating a function from scratch):');
     console.log(`  cd ${target}`);
-    console.log('  pnpm install                         # installs deps for local dev + pins versions via Chainguard.');
-    console.log('                                       # Requires Chainguard credentials (Sequence-internal). Without');
-    console.log('                                       # them this 401s — delete the scaffolded .npmrc and install from');
-    console.log('                                       # public npm instead (the deploy worker re-resolves server-side).');
     console.log('  seq-studio functions build           # local pre-flight checks');
     console.log('  # Add secret names to managed-function.yml (secrets: [MY_SECRET]) and values to .env');
     console.log('  seq-studio functions deploy -e <env>  # upload, apply secrets, then deploy');
@@ -387,6 +389,15 @@ async function buildFromResolvedSource({ spec, source, }) {
 // ---------------------------------------------------------------------------
 // deploy
 // ---------------------------------------------------------------------------
+function buildInvocationIpPreviewLines({ ranges }) {
+    if (ranges.length === 0) {
+        return [`${LOG}   invocation IPs: unrestricted`];
+    }
+    return [
+        `${LOG}   invocation IPs:`,
+        ...ranges.map((range) => `${LOG}     ${range}`),
+    ];
+}
 async function getFunctionDetail(ctx, functionId) {
     try {
         return await getJson({
@@ -561,7 +572,9 @@ async function deployFromResolvedSource({ args, spec, ctx: earlyCtx, source, })
     preview.push(...buildEgressPreviewLines(LOG, [
         ...manifestEgressHosts(manifest.egress),
         ...manifestEgressIpRanges(manifest.egress),
-    ]));
+    ]), ...buildInvocationIpPreviewLines({
+        ranges: manifest.invocation.allowed_ip_ranges,
+    }));
     if (undeclaredEnvKeys.length > 0) {
         preview.push(`${LOG}   note: .env has ${undeclaredEnvKeys.join(', ')} — not declared in manifest, ignored`);
     }

package/dist/functions/manifest.d.ts

@@ -70,6 +70,9 @@ export declare const managedFunctionManifestSchema: z.ZodObject<{
         max_instances: z.ZodDefault<z.ZodNumber>;
         invoke_rate_per_minute: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    invocation: z.ZodDefault<z.ZodObject<{
+        allowed_ip_ranges: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
     egress: z.ZodDefault<z.ZodArray<z.ZodString>>;
     service_account: z.ZodOptional<z.ZodString>;

package/dist/functions/manifest.js

@@ -1,3 +1,4 @@
+import { isIP } from 'node:net';
 import { z } from 'zod';
 /**
  * CLI-side mirror of the server manifest schema at
@@ -515,6 +516,43 @@ const SERVICE_ACCOUNT_REF_RE = /^([a-z][a-z0-9-]{1,98}|[0-9a-fA-F]{8}-[0-9a-fA-F
  * atlas/src/server/services/managed-functions/manifest.ts.
  */
 const GRAPHQL_OPERATION_NAME_RE = /^[_A-Za-z][_0-9A-Za-z]*$/;
+/**
+ * Fast local validation for the declarative invocation policy. Atlas remains
+ * authoritative and canonicalizes network addresses during version upload;
+ * this mirror prevents a malformed bundle from reaching the network.
+ */
+const invocationIpRangeSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .superRefine((value, ctx) => {
+    const parts = value.split('/');
+    if (parts.length > 2) {
+        ctx.addIssue({ code: 'custom', message: `invalid IP address or CIDR range: ${value}` });
+        return;
+    }
+    const [address, prefixText] = parts;
+    const family = isIP(address ?? '');
+    if (family === 0) {
+        ctx.addIssue({ code: 'custom', message: `invalid IP address or CIDR range: ${value}` });
+        return;
+    }
+    if (prefixText === undefined)
+        return;
+    if (!/^\d+$/.test(prefixText)) {
+        ctx.addIssue({ code: 'custom', message: `invalid CIDR prefix: ${value}` });
+        return;
+    }
+    const prefix = Number(prefixText);
+    const maxPrefix = family === 4 ? 32 : 128;
+    if (prefix < 1 || prefix > maxPrefix) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `CIDR prefix must be between 1 and ${maxPrefix}: ${value}`,
+        });
+    }
+});
 export const managedFunctionManifestSchema = z.object({
     schema_version: z.literal(1).default(1),
     function: z.object({
@@ -552,6 +590,16 @@ export const managedFunctionManifestSchema = z.object({
         max_instances: 3,
         invoke_rate_per_minute: 60,
     }),
+    /**
+     * Source-IP gate applied by the Atlas invocation gateway before FGA.
+     * Empty or omitted means unrestricted. The policy is versioned with the
+     * bundle and becomes live atomically with that version.
+     */
+    invocation: z
+        .object({
+        allowed_ip_ranges: z.array(invocationIpRangeSchema).max(64).default([]),
+    })
+        .default({ allowed_ip_ranges: [] }),
     secrets: z
         .array(z.string().regex(SECRET_NAME_RE, 'secret names must be UPPER_SNAKE_CASE'))
         .max(32)

package/dist/login.js

@@ -5,7 +5,7 @@ import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { deleteRealmTokens, realmForEnv, saveTokens, seqapiTokenPath, SEQUENCE_AUTH_REALM, SEQUENCE_REALM, verifyTokenMatchesRealm, } from './auth.js';
-import { manualEnvConfigHint } from './config.js';
+import { localAuthRealmOptions, manualEnvConfigHint } from './config.js';
 import { bootstrapUrl, clearCatalog, fetchCatalog } from './env-catalog.js';
 const DEFAULT_REDIRECT_PORT = 5099;
 const DEFAULT_LOGIN_TIMEOUT_MS = 300_000;
@@ -216,7 +216,7 @@ export async function refreshCatalogAfterLogin() {
     console.log(manualEnvConfigHint());
 }
 export async function login(envName) {
-    const realm = await realmForEnv(envName);
+    const realm = await realmForEnv(envName, await localAuthRealmOptions(envName));
     if (envName && realm.name === SEQUENCE_REALM && envName !== SEQUENCE_REALM) {
         // A name that only exists in the Sequence catalog (staging, banksouth…)
         // resolves to the Sequence realm — one login covers all of those. A typo'd
@@ -241,7 +241,7 @@ function legacyArtifactTokenPath() {
     return join(homedir(), '.config', 'sequence-artifact-studio', 'tokens.json');
 }
 export async function logout(envName) {
-    const realm = await realmForEnv(envName);
+    const realm = await realmForEnv(envName, await localAuthRealmOptions(envName));
     await deleteRealmTokens(realm.name);
     if (realm.name === SEQUENCE_REALM) {
         await rm(legacyArtifactTokenPath(), { force: true });

package/dist/pipeline/commands.js

@@ -38,13 +38,17 @@ const PIPELINE_USAGE = `usage:
       module (default export, authoring, or silverlakeAuthoring export name)
 
   seq-studio pipeline plan --repo pipelines/<slug> --ref <sha|branch> -e <env> [--target <id>] [--json]
+      enqueue a durable plan, poll progress, then print the completed
       materialize + SDK/graph + compile + live-diff + provision findings
       (no Databricks CLI / DAB validate on Atlas); exit 1 on destructive findings
 
   seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha|branch> -e <env>
-                            [--target <id>] [--approved-by <sub>] [--no-wait] [--json]
+                            [--target <id>] [--approved-by <sub>] [--run-now] [--no-wait] [--json]
       plan then enqueue Trigger deploy (DAB bundle validate hard-gates before
-      bundle deploy); use a full 40-hex SHA for explicit rollback deployments
+      bundle deploy). Default is plant-only: jobs/pipelines are created, not
+      run. Pass --run-now to run in-unit producer roots after bundle deploy
+      and wait before serving sync create. Use a full 40-hex SHA for explicit
+      rollback deployments
 
   seq-studio pipeline promote --stage <slug> --version <v> -e <env>
                               [--target <id>] [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]