@sequenceholdings/studio-cli 0.1.10 → 0.1.11

package/README.md

@@ -6,9 +6,10 @@ any repo against the platform over HTTP — no monorepo checkout required.
 
 ```
 seq-studio process lint
-seq-studio process plan -e staging
-seq-studio process apply -e staging
-seq-studio artifact deploy -e staging
+seq-studio process plan -e <env>
+seq-studio process apply -e <env>
+seq-studio artifact deploy -e <env>
+seq-studio envs list
 seq-studio doctor
 ```
 
@@ -62,7 +63,7 @@ secret and `seq-studio` mints a token via the Auth0 client-credentials grant
 
 ```bash
 export AUTH0_M2M_CLIENT_SECRET=...   # provided by your platform administrator
-seq-studio artifact deploy -e staging
+seq-studio artifact deploy -e <env>
 ```
 
 The secret is read at runtime — never commit it. M2M carries app scopes but
@@ -72,17 +73,35 @@ 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.
 
-## Environments (`~/.config/lattice/config.toml`)
+## Environments
 
-Environment names map to platform URLs. Your deployment's URLs are configured
-in `~/.config/lattice/config.toml`:
+The CLI ships with a single built-in environment, `local`
+(`http://localhost:5001`). The other environments your identity may target
+are **discovered** after you authenticate: the CLI calls the platform's
+environment-discovery endpoint and caches the result at
+`~/.config/lattice/environments.json`.
+
+```bash
+seq-studio login            # or: export AUTH0_M2M_CLIENT_SECRET=...
+seq-studio envs refresh     # fetch the environments visible to your identity
+seq-studio envs list        # show them (name, URL, source)
+```
+
+Discovery also happens lazily: the first time you pass an `-e <env>` that
+isn't cached yet, the CLI refreshes the catalog before failing. What you can
+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):
 
 ```toml
 [env.local]
 url = "http://localhost:5001"
 
-[env.staging]
-url = "https://staging.example.com"
+[env.my-atlas]
+url = "https://atlas.example.com"
 
 default_env = "local"
 ```
@@ -191,17 +210,16 @@ any username, PAT as password). **You do not need `seqapi`.**
 
 ### Everyone (recommended) — Atlas UI
 
-1. Open **Settings → Tokens** in Atlas for your environment, e.g.
-   - Staging: https://staging.atlas.seqholdings.com/settings/tokens
-   - Production: https://atlas.seqholdings.com/settings/tokens
-   - BankSouth: https://banksouth.seqholdings.com/settings/tokens
+1. Open **Settings → Tokens** in Atlas for your environment
+   (`<your-atlas-url>/settings/tokens` — run `seq-studio envs list` for the
+   URLs visible to your identity)
 2. **New token** → scopes `repo:read` (add `repo:write` for push) → copy once
 3. Export and clone:
 
 ```bash
 export ATLAS_GIT_PAT=atlas_git_…
-seq-studio repos clone artifacts/ai-fluency -e staging
-# or: git clone https://git:$ATLAS_GIT_PAT@staging.atlas.seqholdings.com/api/git-service/repos/<id>/git
+seq-studio repos clone <namespace>/<repo> -e <env>
+# or: git clone https://git:$ATLAS_GIT_PAT@<your-atlas-host>/api/git-service/repos/<id>/git
 ```
 
 You can also open **Repositories → Access tokens** / the clone popover’s
@@ -213,12 +231,12 @@ Requires Auth0 login. Same identity as the UI:
 
 ```bash
 seq-studio login
-seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e staging
+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
 
-seq-studio auth pat list -e staging
-seq-studio auth pat revoke <id> -e staging --yes
+seq-studio auth pat list -e <env>
+seq-studio auth pat revoke <id> -e <env> --yes
 ```
 
 The raw token is printed **once** on create.

package/dist/artifact/delegate.js

@@ -11,8 +11,9 @@
  *      is shared with the rest of `seq-studio`.
  *   4. Forward all remaining argv to `runCli`.
  */
-import { getAccessToken, tryGetAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { getAccessToken, M2mTokenError, tryGetAccessToken } from '../auth.js';
+import { readConfig, resolveEnvWithDiscovery } from '../config.js';
+import { fetchCatalog, readCachedCatalog } from '../env-catalog.js';
 import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
 import { PREVIEW_DOMAIN, PREVIEW_PROJECT, resolvePreviewByPr } from '../preview.js';
 const ARTIFACT_USAGE = `usage:
@@ -31,7 +32,8 @@ const ARTIFACT_USAGE = `usage:
   seq-studio artifact whoami -e <env>
   seq-studio artifact env list
 
-  Built-in envs: local, staging, production, banksouth.
+  Environments: see \`seq-studio envs list\` (built-in: local; more are
+  discovered after you authenticate).
 
   Source for build/plan/deploy: a local [dir] (default), a platform git-service
   repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a
@@ -78,6 +80,12 @@ export async function runArtifactCommand(sub, rest) {
         console.log(ARTIFACT_USAGE);
         return sub ? 0 : 1;
     }
+    // `artifact env list` renders the tier-aware discovered catalog instead of
+    // artifact-studio's built-in (local-only) list.
+    if (sub === 'env' && rest[0] === 'list') {
+        const { runEnvsCommand } = await import('../envs/commands.js');
+        return runEnvsCommand('list', []);
+    }
     // Normalize `-e <env>` / `-e=<env>` to `--env <env>` because
     // artifact-studio's argv parser (`shared/services/artifact-studio/src/cli.ts`)
     // only recognizes long flags. Without this rewrite `seq-studio
@@ -93,6 +101,7 @@ export async function runArtifactCommand(sub, rest) {
     let resolved;
     let argvForCli = forwardRest;
     if (envUrl !== undefined) {
+        await requireSequenceTier('--env-url');
         const validated = validatePreviewEnvUrl(envUrl);
         // Explicit override wins over everything. Keep the user's --env name if
         // they gave one, else label it `preview`.
@@ -100,13 +109,13 @@ export async function runArtifactCommand(sub, rest) {
         argvForCli = ensureEnvFlag(forwardRest, resolved.name);
     }
     else if (prNumber !== undefined) {
+        await requireSequenceTier('--pr');
         const preview = await resolvePreviewByPr({ pr: prNumber });
         resolved = { name: `preview:${preview.slug}`, url: preview.url };
         argvForCli = ensureEnvFlag(forwardRest, resolved.name);
     }
     else if (requested) {
-        const config = await readConfig();
-        resolved = resolveEnv({ config, requested });
+        resolved = await resolveEnvWithDiscovery({ requested });
         // For `preview:<slug>` normalize the forwarded --env to the canonical name.
         if (resolved.name !== requested)
             argvForCli = ensureEnvFlag(forwardRest, resolved.name);
@@ -119,6 +128,13 @@ export async function runArtifactCommand(sub, rest) {
         if (isPreviewUrl(resolved.url))
             applyPreviewAccessHeader();
     }
+    // Always hand artifact-studio the env map visible to this identity
+    // (discovered catalog + config.toml). Commands that resolve an env *name*
+    // without an explicit --env flag — the stored `.artifact-studio/config.json`
+    // defaultEnv, `artifact env set <name>` — would otherwise fall back to
+    // artifact-studio's built-in local-only map and fail on deployed envs.
+    const { envs } = await readConfig();
+    process.env['ARTIFACT_STUDIO_ENV_URLS'] = JSON.stringify(Object.fromEntries(Object.entries(envs).map(([name, { url }]) => [name, url])));
     // An explicit `--token <jwt>` is the manual escape hatch and must win over
     // everything, including a configured-but-failing M2M credential (which
     // `tryGetAccessToken({ failClosedForM2m: true })` would otherwise turn into
@@ -164,6 +180,31 @@ export async function runArtifactCommand(sub, rest) {
     }
     return runArtifactStudio([sub, ...argvForCli]);
 }
+/**
+ * Preview targeting (`preview:<slug>`, `--pr`, `--env-url`) is a
+ * Sequence-staff surface. The tier comes from the cached discovery catalog;
+ * refresh it lazily so a just-logged-in engineer isn't blocked on a stale
+ * anonymous cache.
+ */
+async function requireSequenceTier(flag) {
+    let { tier } = await readConfig();
+    if (tier !== 'sequence') {
+        try {
+            tier = (await fetchCatalog())?.tier ?? 'anonymous';
+        }
+        catch (err) {
+            // Broken CI credentials must surface as the Auth0 error, not as a
+            // misleading "Sequence-staff surface" rejection.
+            if (err instanceof M2mTokenError)
+                throw err;
+            tier = (await readCachedCatalog())?.tier ?? 'anonymous';
+        }
+    }
+    if (tier !== 'sequence') {
+        throw new Error(`${flag} targets per-PR preview environments, a Sequence-staff surface. ` +
+            'Authenticate with `seq-studio login` and run `seq-studio envs refresh`.');
+    }
+}
 /**
  * Strip the seq-studio-only `--pr <number>` and `--env-url <url>` flags from
  * argv and return the rest (forwarded to artifact-studio) plus the parsed

package/dist/auth-cmds/commands.d.ts

@@ -1,7 +1,7 @@
 import type { ParsedArgs } from '../process/commands.js';
 declare const PAT_SCOPES: readonly ["repo:read", "repo:write", "repo:admin"];
 type PatScope = (typeof PAT_SCOPES)[number];
-export declare const AUTH_USAGE = "usage:\n  seq-studio auth pat create --name <n> [--scopes repo:read,repo:write] [-e env]\n                             [--expires 7d|30d|90d|1y|never] [--store-credentials]\n  seq-studio auth pat list [-e env]\n  seq-studio auth pat revoke <id> [-e env] [--yes]\n\n  Issue a personal access token for git clone / git push against the platform\n  git service.\n\n  Authenticate with `seq-studio login`, then run `auth pat create`.\n  Alternatively, open Atlas \u2192 Settings \u2192 Tokens:\n    https://<atlas-host>/settings/tokens\n  Sign in, create a token (repo:read / repo:write), copy once, then:\n    export ATLAS_GIT_PAT=<token>\n\n  On create the raw token is printed ONCE \u2014 store it; Atlas cannot re-show it.\n  Git Basic auth: any username (e.g. git), PAT as the password.\n\n  Flags: -e/--env <local|staging|production|banksouth>\n";
+export declare const AUTH_USAGE = "usage:\n  seq-studio auth pat create --name <n> [--scopes repo:read,repo:write] [-e env]\n                             [--expires 7d|30d|90d|1y|never] [--store-credentials]\n  seq-studio auth pat list [-e env]\n  seq-studio auth pat revoke <id> [-e env] [--yes]\n\n  Issue a personal access token for git clone / git push against the platform\n  git service.\n\n  Authenticate with `seq-studio login`, then run `auth pat create`.\n  Alternatively, open Atlas \u2192 Settings \u2192 Tokens:\n    https://<atlas-host>/settings/tokens\n  Sign in, create a token (repo:read / repo:write), copy once, then:\n    export ATLAS_GIT_PAT=<token>\n\n  On create the raw token is printed ONCE \u2014 store it; Atlas cannot re-show it.\n  Git Basic auth: any username (e.g. git), PAT as the password.\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n";
 export declare function parsePatScopes(raw: string | undefined): PatScope[];
 /**
  * Map UI-style duration choices to an absolute ISO-8601 expiresAt, or undefined

package/dist/auth-cmds/commands.js

@@ -11,9 +11,23 @@
 import { deleteNoContent, getJson, postJson } from '../atlas-client.js';
 import { printCliError } from '../cli-errors.js';
 import { buildContext, clientOptions, flagBool, LOG, } from '../functions/commands.js';
+import { readConfig } from '../config.js';
 import { confirmYes } from '../prompt.js';
 import { storeGitCredentials } from '../repos/git-clone.js';
 import { formatPatSetupHint, settingsTokensUrl } from '../pat-hints.js';
+/**
+ * Tokens-page URLs rendered from the environments visible to this identity
+ * (discovered catalog + config.toml). Anonymous users get a generic pointer
+ * instead of a hardcoded list of internal hosts.
+ */
+async function settingsTokensLines() {
+    const config = await readConfig().catch(() => null);
+    const remote = Object.entries(config?.envs ?? {}).filter(([name]) => name !== 'local');
+    if (remote.length === 0) {
+        return ['Tokens page: <your Atlas deployment URL>/settings/tokens'];
+    }
+    return remote.map(([name, { url }]) => `${name}: ${settingsTokensUrl(url)}`);
+}
 const PAT_SCOPES = ['repo:read', 'repo:write', 'repo:admin'];
 function stringFlag(flags, key) {
     const value = flags[key];
@@ -41,26 +55,26 @@ export const AUTH_USAGE = `usage:
   On create the raw token is printed ONCE — store it; Atlas cannot re-show it.
   Git Basic auth: any username (e.g. git), PAT as the password.
 
-  Flags: -e/--env <local|staging|production|banksouth>
+  Flags: -e/--env <env>  (see: seq-studio envs list)
 `;
 async function authContext(args) {
     if (args.flags.env === true || args.flags.e === true) {
-        throw new Error('-e/--env requires a value (local|staging|production|banksouth|preview:<slug>).');
+        throw new Error('-e/--env requires a value — see: seq-studio envs list.');
     }
     try {
         return await buildContext(args);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        // buildContext failed before we know the env URL; offer CLI login and point
-        // at the common Atlas hosts as an alternative.
+        // buildContext failed before we know the env URL; offer CLI login and
+        // render the tokens-page URLs from the environments visible to this
+        // identity (third-party / OpCo developers only see their own hosts).
+        const tokenUrls = await settingsTokensLines();
         throw new Error(`${message}\n` +
             `  Run \`seq-studio login\`, then retry \`auth pat create\`.\n` +
             `  Or mint a PAT in the Atlas UI (Settings → Tokens), then:\n` +
             `    export ATLAS_GIT_PAT=<token>\n` +
-            `  Staging: https://staging.atlas.seqholdings.com/settings/tokens\n` +
-            `  Production: https://atlas.seqholdings.com/settings/tokens\n` +
-            `  BankSouth: https://banksouth.seqholdings.com/settings/tokens`);
+            tokenUrls.map((line) => `  ${line}`).join('\n'));
     }
 }
 export function parsePatScopes(raw) {

package/dist/auth.d.ts

@@ -26,6 +26,14 @@ export interface SeqapiTokens {
     access_token?: string;
     expires_at?: number;
 }
+/**
+ * A configured M2M credential failed to mint a token. Typed so callers that
+ * normally swallow discovery errors (lazy catalog refresh) can still surface
+ * broken CI credentials instead of a misleading "unknown env" message.
+ */
+export declare class M2mTokenError extends Error {
+    readonly name = "M2mTokenError";
+}
 export declare function seqapiTokenDir(): string;
 export declare function seqapiTokenPath(): string;
 export declare class NotLoggedInError extends Error {
@@ -52,4 +60,16 @@ export declare function tryGetAccessToken(options?: {
      */
     failClosedForM2m?: boolean;
 }): Promise<string | null>;
+/**
+ * Decode the `sub` claim from a JWT without verification. Verification is the
+ * server's job — this is only used to compare identities locally (e.g. to
+ * bind the cached environment catalog to the identity that fetched it).
+ */
+export declare function decodeJwtSub(token: string): string | null;
+/**
+ * The Auth0 subject the CLI would authenticate as right now, without any
+ * network call: the fixed M2M client subject when the secret is configured,
+ * else the `sub` of the cached user token, else null (anonymous).
+ */
+export declare function currentIdentitySubject(): Promise<string | null>;
 export declare function saveTokens(tokens: SeqapiTokens): Promise<void>;

package/dist/auth.js

@@ -33,6 +33,14 @@ const AUTH0_M2M_CLIENT_ID = '5TLffZqvLq4ztLDjZhwKVJCpB5VNrWj0';
 // `_m2m_cache`). Reused while > 60s from expiry to avoid re-minting on every
 // call within a single process (e.g. a long `artifact dev` watch).
 let m2mCache = null;
+/**
+ * A configured M2M credential failed to mint a token. Typed so callers that
+ * normally swallow discovery errors (lazy catalog refresh) can still surface
+ * broken CI credentials instead of a misleading "unknown env" message.
+ */
+export class M2mTokenError extends Error {
+    name = 'M2mTokenError';
+}
 /**
  * Mint an M2M access token via the Auth0 client-credentials grant when
  * `AUTH0_M2M_CLIENT_SECRET` is set. Returns null when the secret is unset
@@ -57,11 +65,11 @@ async function getM2mToken() {
         }),
     });
     if (!response.ok) {
-        throw new Error(`Auth0 M2M token request failed (${response.status}): ${await response.text()}`);
+        throw new M2mTokenError(`Auth0 M2M token request failed (${response.status}): ${await response.text()}`);
     }
     const data = (await response.json());
     if (!data.access_token) {
-        throw new Error('Auth0 M2M response missing access_token');
+        throw new M2mTokenError('Auth0 M2M response missing access_token');
     }
     m2mCache = {
         accessToken: data.access_token,
@@ -146,6 +154,38 @@ export async function tryGetAccessToken(options) {
         return null;
     }
 }
+/**
+ * Decode the `sub` claim from a JWT without verification. Verification is the
+ * server's job — this is only used to compare identities locally (e.g. to
+ * bind the cached environment catalog to the identity that fetched it).
+ */
+export function decodeJwtSub(token) {
+    const payload = token.split('.')[1];
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        const sub = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'sub') : null;
+        return typeof sub === 'string' && sub ? sub : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The Auth0 subject the CLI would authenticate as right now, without any
+ * network call: the fixed M2M client subject when the secret is configured,
+ * else the `sub` of the cached user token, else null (anonymous).
+ */
+export async function currentIdentitySubject() {
+    if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
+        return `${AUTH0_M2M_CLIENT_ID}@clients`;
+    }
+    const tokens = await loadTokens();
+    if (!tokens?.access_token)
+        return null;
+    return decodeJwtSub(tokens.access_token);
+}
 async function loadTokens() {
     const path = seqapiTokenPath();
     if (!existsSync(path))

package/dist/config.d.ts

@@ -1,8 +1,11 @@
+import { type EnvTier } from './env-catalog.js';
 /**
  * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
  * without a config.toml entry. The slug after the prefix is run through the
  * canonical branch→slug transform (see `preview.ts`). PR-number resolution and
  * the Cloudflare WAF bypass header live in `artifact/delegate.ts`.
+ * Preview targeting is a Sequence-staff surface — resolveEnv gates it on the
+ * discovered tier.
  */
 export declare const PREVIEW_ENV_PREFIX = "preview:";
 export declare const ENV_NAMES: string[];
@@ -11,19 +14,22 @@ export interface LatticeConfig {
         url: string;
     }>;
     defaultEnv: string;
+    /** Discovered identity tier; `anonymous` when no catalog is cached. */
+    tier: EnvTier;
 }
 export declare function globalConfigDir(): string;
 export declare function configPath(): string;
 export declare function defaultConfig(): LatticeConfig;
 /**
- * Read the config from disk. If the file does not exist, return defaults
- * — no auto-write, since seq-studio should work out of the box without
- * any state on disk. The user can run `seq-studio config init` (future)
- * if they want a customizable file.
+ * Read the effective config. Merge precedence (later wins):
  *
- * User-supplied envs are merged on top of the built-ins, so an override
- * for `local` (say, pointing at a different port) takes effect, and net
- * new envs (e.g. `staging-2`) are picked up.
+ *   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)
+ *
+ * If the config.toml file does not exist, defaults are returned — no
+ * auto-write, since seq-studio should work out of the box without any
+ * state on disk.
  */
 export declare function readConfig(): Promise<LatticeConfig>;
 /** Write the config to disk, creating the dir if missing. */
@@ -33,12 +39,22 @@ export interface ResolvedEnv {
     url: string;
 }
 /**
- * Resolve `--env <name>` against the user's config. Falls back to the
- * config's `defaultEnv` when no name is passed. Throws a clear error
- * when the name does not match any known env so users see a list of
- * what's available rather than a confusing 404 later.
+ * Resolve `--env <name>` against the effective config. Falls back to the
+ * config's `defaultEnv` when no name is passed. Throws a clear error when
+ * the name does not resolve at the caller's tier, listing only the envs
+ * that are actually visible.
  */
 export declare function resolveEnv({ config, requested, }: {
     config: LatticeConfig;
     requested?: string;
 }): ResolvedEnv;
+/**
+ * Async resolveEnv with lazy discovery: when the requested name doesn't
+ * resolve from the current config (built-ins + cached catalog + toml),
+ * refresh the catalog once — a logged-in identity that never ran
+ * `seq-studio envs refresh` (or fresh CI with AUTH0_M2M_CLIENT_SECRET)
+ * gets its environments on first use — then retry.
+ */
+export declare function resolveEnvWithDiscovery({ requested, }: {
+    requested?: string;
+}): Promise<ResolvedEnv>;

package/dist/config.js

@@ -3,25 +3,27 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { M2mTokenError } from './auth.js';
+import { fetchCatalog, readCachedCatalog, } from './env-catalog.js';
 import { resolvePreviewFromSlug } from './preview.js';
 /**
  * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
  * without a config.toml entry. The slug after the prefix is run through the
  * canonical branch→slug transform (see `preview.ts`). PR-number resolution and
  * the Cloudflare WAF bypass header live in `artifact/delegate.ts`.
+ * Preview targeting is a Sequence-staff surface — resolveEnv gates it on the
+ * discovered tier.
  */
 export const PREVIEW_ENV_PREFIX = 'preview:';
 /**
- * Environment URLs match the existing seqapi + artifact-studio mapping so
- * an engineer's mental model is the same across all three tools. `local`
- * is the dev / `make dev-all` URL — kept named `local` (not `dev`) so it
- * lines up with `seqapi -e local` and `artifact-studio --env local`.
+ * Only `local` ships in the published package. Additional environments are
+ * discovered per-identity from the authenticated catalog endpoint (see
+ * `env-catalog.ts`) or added by the user in config.toml. `local` is the
+ * dev / `make dev-all` URL — kept named `local` (not `dev`) so it lines up
+ * with `seqapi -e local` and `artifact-studio --env local`.
  */
 const BUILT_IN_ENV_URLS = {
     local: 'http://localhost:5001',
-    staging: 'https://staging.atlas.seqholdings.com',
-    production: 'https://atlas.seqholdings.com',
-    banksouth: 'https://banksouth.seqholdings.com',
 };
 export const ENV_NAMES = Object.keys(BUILT_IN_ENV_URLS);
 export function globalConfigDir() {
@@ -35,24 +37,32 @@ export function defaultConfig() {
     for (const [name, url] of Object.entries(BUILT_IN_ENV_URLS)) {
         envs[name] = { url };
     }
-    return { envs, defaultEnv: 'local' };
+    return { envs, defaultEnv: 'local', tier: 'anonymous' };
 }
 /**
- * Read the config from disk. If the file does not exist, return defaults
- * — no auto-write, since seq-studio should work out of the box without
- * any state on disk. The user can run `seq-studio config init` (future)
- * if they want a customizable file.
+ * Read the effective config. Merge precedence (later wins):
  *
- * User-supplied envs are merged on top of the built-ins, so an override
- * for `local` (say, pointing at a different port) takes effect, and net
- * new envs (e.g. `staging-2`) are picked up.
+ *   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)
+ *
+ * If the config.toml file does not exist, defaults are returned — no
+ * auto-write, since seq-studio should work out of the box without any
+ * state on disk.
  */
 export async function readConfig() {
+    const merged = defaultConfig();
+    const catalog = await readCachedCatalog();
+    if (catalog) {
+        merged.tier = catalog.tier;
+        for (const env of catalog.environments) {
+            merged.envs[env.name] = { url: env.url };
+        }
+    }
     const path = configPath();
     if (!existsSync(path))
-        return defaultConfig();
+        return merged;
     const raw = parseToml(await readFile(path, 'utf8'));
-    const merged = defaultConfig();
     if (raw.env) {
         for (const [name, value] of Object.entries(raw.env)) {
             if (typeof value?.url === 'string') {
@@ -81,15 +91,22 @@ export async function writeConfig(config) {
     lines.push(`default_env = "${config.defaultEnv}"`);
     await writeFile(path, lines.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
 }
+/** Shared hint appended to visibility errors at the anonymous/partner tiers. */
+const DISCOVERY_HINT = 'If you expect more environments, authenticate (seq-studio login, or set ' +
+    'AUTH0_M2M_CLIENT_SECRET) and run: seq-studio envs refresh';
 /**
- * Resolve `--env <name>` against the user's config. Falls back to the
- * config's `defaultEnv` when no name is passed. Throws a clear error
- * when the name does not match any known env so users see a list of
- * what's available rather than a confusing 404 later.
+ * Resolve `--env <name>` against the effective config. Falls back to the
+ * config's `defaultEnv` when no name is passed. Throws a clear error when
+ * the name does not resolve at the caller's tier, listing only the envs
+ * that are actually visible.
  */
 export function resolveEnv({ config, requested, }) {
     const name = requested ?? config.defaultEnv;
     if (name.startsWith(PREVIEW_ENV_PREFIX)) {
+        if (config.tier !== 'sequence') {
+            throw new Error(`Preview environments (${PREVIEW_ENV_PREFIX}<branch>) are a Sequence-staff ` +
+                `surface. ${DISCOVERY_HINT}`);
+        }
         const { slug, url } = resolvePreviewFromSlug(name.slice(PREVIEW_ENV_PREFIX.length));
         return { name: `${PREVIEW_ENV_PREFIX}${slug}`, url };
     }
@@ -97,7 +114,40 @@ export function resolveEnv({ config, requested, }) {
     if (!env) {
         const known = Object.keys(config.envs).join(', ');
         throw new Error(`Unknown env "${name}". Known envs: ${known}. ` +
-            `Pass --env <name> or set default_env in ${configPath()}.`);
+            `Pass --env <name> or set default_env in ${configPath()}. ${DISCOVERY_HINT}`);
     }
     return { name, url: env.url };
 }
+/**
+ * Async resolveEnv with lazy discovery: when the requested name doesn't
+ * resolve from the current config (built-ins + cached catalog + toml),
+ * refresh the catalog once — a logged-in identity that never ran
+ * `seq-studio envs refresh` (or fresh CI with AUTH0_M2M_CLIENT_SECRET)
+ * gets its environments on first use — then retry.
+ */
+export async function resolveEnvWithDiscovery({ requested, }) {
+    const config = await readConfig();
+    try {
+        return resolveEnv({ config, requested });
+    }
+    catch (err) {
+        let catalog;
+        try {
+            catalog = await fetchCatalog();
+        }
+        catch (fetchErr) {
+            // A configured-but-broken M2M credential is the real failure — CI must
+            // see the Auth0 error, not a misleading "unknown env" message.
+            if (fetchErr instanceof M2mTokenError)
+                throw fetchErr;
+            // Network/server errors: fall back to whatever is cached, else
+            // surface the original resolve error.
+            catalog = await readCachedCatalog();
+        }
+        if (!catalog)
+            throw err;
+        // Retry against the refreshed catalog; if the name still doesn't
+        // resolve, the retry throws an error rendered from the fresh state.
+        return resolveEnv({ config: await readConfig(), requested });
+    }
+}

package/dist/env-catalog.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tiered environment discovery.
+ *
+ * The published package ships with only the `local` environment baked in.
+ * Every other deployment URL is *discovered* from the authenticated
+ * `GET /api/platform/environments` endpoint and cached on disk:
+ *
+ *   - `anonymous` — no usable token (or the endpoint rejected it):
+ *     `local` only, no catalog cached.
+ *   - `sequence`  — Sequence staff / trusted M2M: full catalog
+ *     (local, staging, production, banksouth) + preview targeting.
+ *   - `partner`   — any other authenticated identity: local + their
+ *     deployment(s).
+ *
+ * This is a visibility/UX layer, not access control — every deployment
+ * still enforces Auth0 + FGA per request. A user who knows a URL can
+ * always add it to config.toml; the server rejecting their token is the
+ * real gate.
+ *
+ * One bootstrap hostname is baked into the package for the discovery
+ * call itself. All deployments share the same Auth0 audience, so any
+ * identity's token validates there; the endpoint 401s anonymously.
+ */
+export type EnvTier = 'anonymous' | 'sequence' | 'partner';
+export interface CatalogEnvironment {
+    name: string;
+    url: string;
+}
+export interface EnvCatalog {
+    tier: Exclude<EnvTier, 'anonymous'>;
+    environments: CatalogEnvironment[];
+    /** Unix ms timestamp of the successful fetch. */
+    fetchedAt: number;
+    /**
+     * Auth0 `sub` of the identity that fetched this catalog. Reads ignore the
+     * cache when the current identity differs (logout, seqapi re-login as
+     * someone else), so one user's tier never carries over to another.
+     */
+    subject: string;
+}
+/** The host the discovery call goes to. Override for tests / self-hosting. */
+export declare function bootstrapUrl(): string;
+export declare function catalogPath(): string;
+/**
+ * Read the cached catalog from disk. Returns null when missing, malformed,
+ * or fetched by a *different* identity than the one the CLI would
+ * authenticate as right now — callers treat all of those as tier
+ * `anonymous`. The subject check means a logout (token file removed) or a
+ * re-login as someone else invalidates the cache immediately, without
+ * waiting for the next discovery call.
+ */
+export declare function readCachedCatalog(): Promise<EnvCatalog | null>;
+export declare function clearCatalog(): Promise<void>;
+/**
+ * Fetch the environment catalog from the discovery endpoint and cache it.
+ *
+ * Returns the fresh catalog, or null when the caller is effectively
+ * anonymous: no token available, or the endpoint rejected the token
+ * (401/403 — the stale cache is cleared so visibility downgrades too).
+ * Network/server errors leave any existing cache in place and rethrow so
+ * callers can distinguish "offline" from "not authorized".
+ */
+export declare function fetchCatalog(): Promise<EnvCatalog | null>;

package/dist/env-catalog.js

@@ -0,0 +1,111 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { currentIdentitySubject, decodeJwtSub, tryGetAccessToken } from './auth.js';
+const DEFAULT_BOOTSTRAP_URL = 'https://atlas.seqholdings.com';
+/** The host the discovery call goes to. Override for tests / self-hosting. */
+export function bootstrapUrl() {
+    return (process.env['SEQ_STUDIO_DISCOVERY_URL']?.trim().replace(/\/+$/, '') ||
+        DEFAULT_BOOTSTRAP_URL);
+}
+export function catalogPath() {
+    return join(homedir(), '.config', 'lattice', 'environments.json');
+}
+function isValidCatalog(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return ((candidate.tier === 'sequence' || candidate.tier === 'partner') &&
+        Array.isArray(candidate.environments) &&
+        candidate.environments.every((env) => typeof env === 'object' &&
+            env !== null &&
+            typeof env.name === 'string' &&
+            typeof env.url === 'string') &&
+        typeof candidate.fetchedAt === 'number' &&
+        typeof candidate.subject === 'string' &&
+        candidate.subject.length > 0);
+}
+/**
+ * Read the cached catalog from disk. Returns null when missing, malformed,
+ * or fetched by a *different* identity than the one the CLI would
+ * authenticate as right now — callers treat all of those as tier
+ * `anonymous`. The subject check means a logout (token file removed) or a
+ * re-login as someone else invalidates the cache immediately, without
+ * waiting for the next discovery call.
+ */
+export async function readCachedCatalog() {
+    const path = catalogPath();
+    if (!existsSync(path))
+        return null;
+    let catalog;
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        catalog = isValidCatalog(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+    if (!catalog)
+        return null;
+    const subject = await currentIdentitySubject();
+    if (subject === null || subject !== catalog.subject)
+        return null;
+    return catalog;
+}
+async function saveCatalog(catalog) {
+    const path = catalogPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(catalog, null, 2) + '\n', {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export async function clearCatalog() {
+    await rm(catalogPath(), { force: true });
+}
+/**
+ * Fetch the environment catalog from the discovery endpoint and cache it.
+ *
+ * Returns the fresh catalog, or null when the caller is effectively
+ * anonymous: no token available, or the endpoint rejected the token
+ * (401/403 — the stale cache is cleared so visibility downgrades too).
+ * Network/server errors leave any existing cache in place and rethrow so
+ * callers can distinguish "offline" from "not authorized".
+ */
+export async function fetchCatalog() {
+    // Fail closed when an M2M secret is configured but minting fails, so
+    // headless callers (CI) see the real Auth0 error instead of a silent
+    // downgrade to the anonymous tier.
+    const token = await tryGetAccessToken({ failClosedForM2m: true });
+    if (!token) {
+        await clearCatalog();
+        return null;
+    }
+    const response = await fetch(`${bootstrapUrl()}/api/platform/environments`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (response.status === 401 || response.status === 403) {
+        await clearCatalog();
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Environment discovery failed (${response.status}) against ${bootstrapUrl()}.`);
+    }
+    const body = (await response.json());
+    if ((body.tier !== 'sequence' && body.tier !== 'partner') ||
+        !Array.isArray(body.environments)) {
+        throw new Error('Environment discovery returned an unexpected response shape.');
+    }
+    const catalog = {
+        tier: body.tier,
+        environments: body.environments,
+        fetchedAt: Date.now(),
+        // Bind the cache to the identity that fetched it. `unknown` never
+        // matches a real subject, so an undecodable token yields a catalog
+        // that works for this invocation but is not trusted from disk later.
+        subject: decodeJwtSub(token) ?? 'unknown',
+    };
+    await saveCatalog(catalog);
+    return catalog;
+}

package/dist/envs/commands.d.ts

@@ -0,0 +1 @@
+export declare function runEnvsCommand(sub: string | undefined, _rest: string[]): Promise<number>;

package/dist/envs/commands.js

@@ -0,0 +1,74 @@
+import { readConfig, configPath } from '../config.js';
+import { bootstrapUrl, fetchCatalog, readCachedCatalog, } from '../env-catalog.js';
+const ENVS_USAGE = `usage:
+  seq-studio envs list      show the environments visible to your identity
+  seq-studio envs refresh   re-fetch the environment catalog for your identity
+
+  The published CLI ships with only the "local" environment. After you
+  authenticate (seq-studio login, or AUTH0_M2M_CLIENT_SECRET for headless use),
+  "envs refresh" discovers the environments your identity may target; the
+  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.
+`;
+export async function runEnvsCommand(sub, _rest) {
+    switch (sub) {
+        case 'list':
+            return listCommand();
+        case 'refresh':
+            return refreshCommand();
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(ENVS_USAGE);
+            return sub ? 0 : 1;
+        default:
+            console.error(`unknown envs command: ${sub}`);
+            console.error(ENVS_USAGE);
+            return 1;
+    }
+}
+async function listCommand() {
+    const [config, catalog] = await Promise.all([readConfig(), readCachedCatalog()]);
+    const discovered = new Set(catalog?.environments.map((env) => env.name) ?? []);
+    console.log(`tier: ${config.tier}`);
+    if (catalog) {
+        console.log(`catalog fetched: ${new Date(catalog.fetchedAt).toISOString()}`);
+    }
+    console.log('');
+    const width = Math.max(...Object.keys(config.envs).map((name) => name.length));
+    for (const [name, { url }] of Object.entries(config.envs)) {
+        const source = name === 'local' && !discovered.has(name)
+            ? 'built-in'
+            : discovered.has(name)
+                ? 'discovered'
+                : 'config.toml';
+        console.log(`  ${name.padEnd(width)}  ${url}  (${source})`);
+    }
+    if (config.tier === 'anonymous') {
+        console.log('');
+        console.log('Not authenticated — only "local" is visible. Authenticate with ' +
+            '`seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET), then run: seq-studio envs refresh');
+    }
+    return 0;
+}
+async function refreshCommand() {
+    let catalog;
+    try {
+        catalog = await fetchCatalog();
+    }
+    catch (err) {
+        console.error(`envs refresh: FAIL — ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!catalog) {
+        console.log(`Not authenticated against ${bootstrapUrl()} — catalog cleared; only ` +
+            '"local" (plus any config.toml entries) is visible.\n' +
+            'Authenticate with `seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET) and retry.');
+        return 0;
+    }
+    console.log(`tier: ${catalog.tier} — ${catalog.environments.length} environment(s) cached.`);
+    return listCommand();
+}

package/dist/functions/commands.d.ts

@@ -82,5 +82,5 @@ export declare function functionsRollbackCommand(args: ParsedArgs): Promise<numb
 /** Minimal dotenv parser — KEY=VALUE lines, quotes stripped, comments skipped. */
 export declare function parseDotenv(content: string): Record<string, string>;
 export declare function functionsDeleteCommand(args: ParsedArgs): Promise<number>;
-export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy [-e env] [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list [-e env] [--match-local]  functions visible on the environment\n  seq-studio functions show [-e env] [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs [-e env] [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> [-e env]     make a version live\n  seq-studio functions rollback [<version>] [-e env]  redeploy a prior version\n  seq-studio functions delete [--yes]                 archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <local|staging|production|banksouth|preview:<slug>> \u00B7 --fn <slug> \u00B7 --dir <path>\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a\n  branch/tag/commit (default: the repo's default branch). Remote sources record\n  the pinned commit as provenance (never dirty) and NEVER read a repo-committed\n  .env for secret values \u2014 provision secrets server-side or pass a local\n  --from-env-file (resolved against your cwd).\n\n  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT\n  (repo:read scope \u2014 `seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). It's the same token you clone the repo with;\n  --env + seq-studio login are still needed to resolve the repo and deploy.\n";
+export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy [-e env] [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list [-e env] [--match-local]  functions visible on the environment\n  seq-studio functions show [-e env] [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs [-e env] [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> [-e env]     make a version live\n  seq-studio functions rollback [<version>] [-e env]  redeploy a prior version\n  seq-studio functions delete [--yes]                 archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <env|preview:<slug>> (see: seq-studio envs list) \u00B7 --fn <slug> \u00B7 --dir <path>\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a\n  branch/tag/commit (default: the repo's default branch). Remote sources record\n  the pinned commit as provenance (never dirty) and NEVER read a repo-committed\n  .env for secret values \u2014 provision secrets server-side or pass a local\n  --from-env-file (resolved against your cwd).\n\n  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT\n  (repo:read scope \u2014 `seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). It's the same token you clone the repo with;\n  --env + seq-studio login are still needed to resolve the repo and deploy.\n";
 export declare function runFunctionsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/functions/commands.js

@@ -7,7 +7,7 @@ import { createInterface } from 'node:readline';
 import { Writable } from 'node:stream';
 import { load as parseYaml } from 'js-yaml';
 import { getAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { resolveEnvWithDiscovery } from '../config.js';
 import { AtlasApiError, deleteJson, getJson, postJson } from '../atlas-client.js';
 import { clarifyApplyFailureReason, printCliError } from '../cli-errors.js';
 import { confirmYes } from '../prompt.js';
@@ -24,10 +24,9 @@ export function flagBool(flags, ...keys) {
     return keys.some((key) => flags[key] === true || flags[key] === 'true');
 }
 export async function buildContext(args) {
-    const config = await readConfig();
     const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
         (typeof args.flags.e === 'string' ? args.flags.e : undefined);
-    const env = resolveEnv({ config, requested });
+    const env = await resolveEnvWithDiscovery({ requested });
     const token = await getAccessToken();
     return { env, token };
 }
@@ -309,7 +308,7 @@ export async function functionsInitCommand(args) {
     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 staging  # upload, apply secrets, then deploy');
+    console.log('  seq-studio functions deploy -e <env>  # upload, apply secrets, then deploy');
     return 0;
 }
 // ---------------------------------------------------------------------------
@@ -942,7 +941,7 @@ export const FUNCTIONS_USAGE = `usage:
   seq-studio functions delete [--yes]                 archive function + tear down GCP resources
                                                       (version history is retained)
 
-  Flags: -e/--env <local|staging|production|banksouth|preview:<slug>> · --fn <slug> · --dir <path>
+  Flags: -e/--env <env|preview:<slug>> (see: seq-studio envs list) · --fn <slug> · --dir <path>
          --from-env-file <path>  (default: .env) source file for secret values
          --no-wait · --yes
          --no-provision  (deploy) update-only: error instead of registering a new

package/dist/login.js

@@ -5,6 +5,7 @@ import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_DOMAIN, saveTokens, seqapiTokenPath, } from './auth.js';
+import { clearCatalog, fetchCatalog } from './env-catalog.js';
 const DEFAULT_REDIRECT_PORT = 5099;
 const DEFAULT_LOGIN_TIMEOUT_MS = 300_000;
 function base64Url(input) {
@@ -195,6 +196,22 @@ export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBro
 export async function login() {
     await loginWithPkce({});
     console.log(`Authenticated. Tokens saved to ${seqapiTokenPath()}.`);
+    // Refresh the environment catalog for the new identity immediately, so a
+    // previously cached catalog from another identity (or tier) never lingers
+    // past a login. Drop the old cache first — if the refresh below fails, the
+    // prior identity's catalog must not survive the login either.
+    // Best-effort: discovery being unreachable must not fail login.
+    await clearCatalog();
+    try {
+        const catalog = await fetchCatalog();
+        if (catalog) {
+            console.log(`Environment catalog refreshed (tier: ${catalog.tier}, ` +
+                `${catalog.environments.length} environment(s)).`);
+        }
+    }
+    catch {
+        console.log('Could not refresh the environment catalog — run: seq-studio envs refresh');
+    }
 }
 /**
  * Pre-unification artifact-studio token file. `seq-studio artifact` commands
@@ -209,5 +226,8 @@ function legacyArtifactTokenPath() {
 export async function logout() {
     await rm(seqapiTokenPath(), { force: true });
     await rm(legacyArtifactTokenPath(), { force: true });
+    // Drop the cached environment catalog so visibility downgrades with the
+    // identity — a logged-out terminal must not keep the old tier's env list.
+    await clearCatalog();
     console.log('Logged out of seq-studio and seqapi.');
 }

package/dist/main.d.ts

@@ -8,6 +8,7 @@
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
  *   seq-studio auth <sub>         manage git-service PATs
+ *   seq-studio envs <sub>         list/refresh discovered environments
  *   seq-studio login              authenticate interactively with Auth0
  *   seq-studio logout             remove cached user tokens
  *   seq-studio doctor             check token + env + writer gate

package/dist/main.js

@@ -8,6 +8,7 @@
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
  *   seq-studio auth <sub>         manage git-service PATs
+ *   seq-studio envs <sub>         list/refresh discovered environments
  *   seq-studio login              authenticate interactively with Auth0
  *   seq-studio logout             remove cached user tokens
  *   seq-studio doctor             check token + env + writer gate
@@ -25,13 +26,15 @@ const TOP_LEVEL_USAGE = `usage:
   seq-studio repos <sub> [args]      list | namespaces | show | create | clone | pull | delete
   seq-studio auth <sub> [args]       pat create | pat list | pat revoke
   seq-studio orm <sub> [args]        init | validate | plan | apply
+  seq-studio envs <sub>              list | refresh — environments visible to your identity
   seq-studio login                   authenticate in the browser
   seq-studio logout                  remove cached user tokens
   seq-studio doctor [-e <env>]       diagnose config, auth, and writer gate
   seq-studio help                    show this message
 
   Authenticate with: seq-studio login
-  Env URLs come from ~/.config/lattice/config.toml (built-ins: local, staging, production, banksouth).
+  Built-in env: local. Authenticated identities discover more via
+  \`seq-studio envs refresh\`; custom entries live in ~/.config/lattice/config.toml.
 `;
 const PROCESS_USAGE = `usage:
   seq-studio process init <dir>
@@ -82,6 +85,10 @@ export async function run(argv = process.argv.slice(2)) {
             const { runOrmCommand } = await import('./orm/delegate.js');
             return runOrmCommand(sub, rest);
         }
+        case 'envs': {
+            const { runEnvsCommand } = await import('./envs/commands.js');
+            return runEnvsCommand(sub, rest);
+        }
         case 'login':
         case 'logout':
             return runSessionCommand({ argument: sub, command: namespace });

package/dist/orm/delegate.js

@@ -6,16 +6,17 @@
  * SEQUENCE_ORM_BASE_URL, share the seqapi token, forward argv.
  */
 import { getAccessToken, tryGetAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { resolveEnvWithDiscovery } from '../config.js';
 import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
 const ORM_USAGE = `usage:
   seq-studio orm init <dir>            scaffold a namespace directory
-  seq-studio orm validate [dir]        parse + validate definitions, print the content hash
+  seq-studio orm validate [dir]        parse + validate definitions and verify committed migrations are in sync
   seq-studio orm plan [dir] -e <env>   compile definitions and diff against the registry
-  seq-studio orm diff [dir]            write the next committed migration (--check verifies, --allow-destructive consents)
-  seq-studio orm apply [dir] -e <env>  register the definitions and apply them to the env
+  seq-studio orm apply [dir] -e <env>  author the migration, register, apply, and refresh types.gen.ts (the everyday command)
+  seq-studio orm diff [dir]            write/verify the committed migration standalone (--check is the offline CI gate; --allow-destructive consents)
 
-  Built-in envs: local, staging, production, banksouth.
+  Environments: see \`seq-studio envs list\` (built-in: local; more are
+  discovered after you authenticate).
   Authenticate with: seq-studio login
 `;
 export async function runOrmCommand(sub, rest) {
@@ -26,8 +27,7 @@ export async function runOrmCommand(sub, rest) {
     const normalized = normalizeShortEnvFlag(rest);
     const requested = readEnvFromArgv(normalized);
     if (requested) {
-        const config = await readConfig();
-        const resolved = resolveEnv({ config, requested });
+        const resolved = await resolveEnvWithDiscovery({ requested });
         process.env['SEQUENCE_ORM_BASE_URL'] = resolved.url;
     }
     const token = await tryGetAccessToken({ failClosedForM2m: true });

package/dist/process/commands.js

@@ -12,7 +12,7 @@ import { forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
 import { getJson, getJsonOr404, postJson, AtlasApiError } from '../atlas-client.js';
 import { generateProcessFiles } from './codegen.js';
 import { getAccessToken, NotLoggedInError } from '../auth.js';
-import { ENV_NAMES, readConfig, resolveEnv } from '../config.js';
+import { readConfig, resolveEnvWithDiscovery } from '../config.js';
 import { buildBundleFromProcesses, summarizeBundle } from './build.js';
 import { buildResolveProcessPinFromEnv } from './resolve-process-pin.js';
 import { loadBundleForPublish } from './local-bundle.js';
@@ -92,9 +92,8 @@ const SHORT_FLAG_ALIASES = {
     '-o': 'out',
 };
 async function getEnvAndToken(args) {
-    const config = await readConfig();
     const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
-    const env = resolveEnv({ config, requested });
+    const env = await resolveEnvWithDiscovery({ requested });
     let token;
     try {
         token = await getAccessToken();
@@ -667,16 +666,16 @@ export async function doctorCommand(args) {
     }
     else {
         lines.push(`config: ok — default_env=${config.defaultEnv}, envs=${Object.keys(config.envs).join(',')}`);
+        lines.push(`tier: ${config.tier}` +
+            (config.tier === 'anonymous'
+                ? ' — authenticate and run `seq-studio envs refresh` to discover more environments'
+                : ''));
     }
     const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
-    if (requested && !ENV_NAMES.includes(requested) && config && !(requested in config.envs)) {
-        lines.push(`env "${requested}": FAIL — not in built-ins (${ENV_NAMES.join(',')}) or config`);
-        ok = false;
-    }
     let env = null;
     if (config) {
         try {
-            env = resolveEnv({ config, requested });
+            env = await resolveEnvWithDiscovery({ requested });
             lines.push(`env: ok — ${env.name} (${env.url})`);
         }
         catch (err) {

package/dist/repos/commands.d.ts

@@ -45,5 +45,5 @@ export declare function reposCloneCommand(args: ParsedArgs, deps?: {
  */
 export declare function normalizeCloneUrl(raw: string, env: ResolvedEnv): string;
 export declare function reposDeleteCommand(args: ParsedArgs): Promise<number>;
-export declare const REPOS_USAGE = "usage:\n  seq-studio repos list [-e env] [--namespace <slug>] [--mine]      repos visible on the environment\n  seq-studio repos namespaces [create <slug>] [-e env]              list or create namespaces\n  seq-studio repos show <ns>/<name> [-e env]                        repo detail (branches, clone URL)\n  seq-studio repos create <ns>/<name> [-e env] [--default-branch b] create an empty repo\n  seq-studio repos clone <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n  seq-studio repos clone --url <https://\u2026/repos/<id>/git> [-e env] [--ref r] [--out dir]\n  seq-studio repos clone --id <uuid> [-e env] [--ref r] [--out dir]\n                                                                    smart-HTTP when ATLAS_GIT_PAT is set;\n                                                                    otherwise JSON materialize (<ns>/<name>)\n  seq-studio repos pull <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n                                                                    materialize the tree at a ref (JSON API)\n  seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)\n\n  Flags: -e/--env <local|staging|production|banksouth>\n\n  clone prefers real git clone (PAT via askpass \u2014 never written into the remote\n  URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints\n  how to get a PAT (seq-studio or Atlas UI /settings/tokens).\n  PAT without Auth0 login: use --url from Repositories \u2192 Clone (or --id <uuid>).\n  --ref accepts a branch, tag, or commit SHA (SHA \u2192 clone then checkout).\n\n  Authenticate JSON API calls with: seq-studio login\n  Authenticate git clone/push with: ATLAS_GIT_PAT (from Atlas Settings \u2192 Tokens)\n";
+export declare const REPOS_USAGE = "usage:\n  seq-studio repos list [-e env] [--namespace <slug>] [--mine]      repos visible on the environment\n  seq-studio repos namespaces [create <slug>] [-e env]              list or create namespaces\n  seq-studio repos show <ns>/<name> [-e env]                        repo detail (branches, clone URL)\n  seq-studio repos create <ns>/<name> [-e env] [--default-branch b] create an empty repo\n  seq-studio repos clone <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n  seq-studio repos clone --url <https://\u2026/repos/<id>/git> [-e env] [--ref r] [--out dir]\n  seq-studio repos clone --id <uuid> [-e env] [--ref r] [--out dir]\n                                                                    smart-HTTP when ATLAS_GIT_PAT is set;\n                                                                    otherwise JSON materialize (<ns>/<name>)\n  seq-studio repos pull <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n                                                                    materialize the tree at a ref (JSON API)\n  seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n\n  clone prefers real git clone (PAT via askpass \u2014 never written into the remote\n  URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints\n  how to get a PAT (seq-studio or Atlas UI /settings/tokens).\n  PAT without Auth0 login: use --url from Repositories \u2192 Clone (or --id <uuid>).\n  --ref accepts a branch, tag, or commit SHA (SHA \u2192 clone then checkout).\n\n  Authenticate JSON API calls with: seq-studio login\n  Authenticate git clone/push with: ATLAS_GIT_PAT (from Atlas Settings \u2192 Tokens)\n";
 export declare function runReposCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/repos/commands.js

@@ -24,7 +24,7 @@ import { buildContext, clientOptions, flagBool, LOG, } from '../functions/comman
 import { resolveGitPatFromEnv, runGitClone, } from './git-clone.js';
 import { formatPatSetupHint } from '../pat-hints.js';
 import { tryGetAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { resolveEnvWithDiscovery } from '../config.js';
 const PAGE_SIZE = 200;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -60,7 +60,7 @@ export function stringFlag(flags, key) {
  */
 async function reposContext(args) {
     if (args.flags.env === true || args.flags.e === true) {
-        throw new Error('-e/--env requires a value (local|staging|production|banksouth|preview:<slug>).');
+        throw new Error('-e/--env requires a value — see: seq-studio envs list.');
     }
     const ctx = await buildContext(args);
     const secret = process.env.PREVIEW_ACCESS_HEADER?.trim();
@@ -414,12 +414,11 @@ export async function reposCloneCommand(args, deps = {}) {
 /** Resolve -e/--env without requiring Auth0 (for PAT-only --url/--id clones). */
 async function resolveEnvOnly(args) {
     if (args.flags.env === true || args.flags.e === true) {
-        throw new Error('-e/--env requires a value (local|staging|production|banksouth|preview:<slug>).');
+        throw new Error('-e/--env requires a value — see: seq-studio envs list.');
     }
-    const config = await readConfig();
     const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
         (typeof args.flags.e === 'string' ? args.flags.e : undefined);
-    return resolveEnv({ config, requested });
+    return resolveEnvWithDiscovery({ requested });
 }
 /**
  * Validate clone URL shape and that the origin matches the resolved Atlas env
@@ -502,7 +501,7 @@ export const REPOS_USAGE = `usage:
                                                                     materialize the tree at a ref (JSON API)
   seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)
 
-  Flags: -e/--env <local|staging|production|banksouth>
+  Flags: -e/--env <env>  (see: seq-studio envs list)
 
   clone prefers real git clone (PAT via askpass — never written into the remote
   URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints

package/dist/secrets/commands.d.ts

@@ -20,5 +20,5 @@ export declare function secretsSetDefaultCommand(args: ParsedArgs): Promise<numb
  * UI: pin + redeploy the function's active version / pin only / cancel.
  */
 export declare function secretsPinCommand(args: ParsedArgs): Promise<number>;
-export declare const SECRETS_USAGE = "usage:\n  seq-studio secrets create <NAME> [--description text]   register an org-owned secret\n  seq-studio secrets set <NAME>                             set the shared default value (write-only)\n  seq-studio secrets list [-e env]                          secrets you can see (never values)\n  seq-studio secrets attach <NAME> --fn <slug>              mount default on a function env var\n  seq-studio secrets detach <NAME> --fn <slug>              remove attachment\n  seq-studio secrets apply --from-env-file .env [-e env]    push defaults + attach (keys default from manifest)\n  seq-studio secrets versions <NAME>                        value version history (never values)\n  seq-studio secrets set-default <NAME> [version]           point the default at a prior version (editor)\n  seq-studio secrets pin <NAME> --fn <slug> [version]       pin one function to a version (sticky; --unpin clears)\n\n  Note: for the common deploy loop, secrets declared in managed-function.yml are\n  reconciled automatically by `seq-studio functions deploy` using a local .env.\n  Use `secrets` commands for CI (no .env), bulk/multi-function ops, or write-only\n  value changes without a redeploy.\n\n  Flags: -e/--env <local|staging|production|banksouth>\n         --fn <slug> \u00B7 --env-var <NAME> \u00B7 --yes\n         --functions <f1,f2> \u00B7 --keys <K1,K2> \u00B7 --all (override key selection)\n         set-default: [version|version-row-id] (defaults to the most recent non-default) \u00B7 --yes\n         pin: [version|version-row-id] (defaults to the current default) \u00B7 --unpin \u00B7 --yes (redeploy) \u00B7 --yes --no-redeploy\n";
+export declare const SECRETS_USAGE = "usage:\n  seq-studio secrets create <NAME> [--description text]   register an org-owned secret\n  seq-studio secrets set <NAME>                             set the shared default value (write-only)\n  seq-studio secrets list [-e env]                          secrets you can see (never values)\n  seq-studio secrets attach <NAME> --fn <slug>              mount default on a function env var\n  seq-studio secrets detach <NAME> --fn <slug>              remove attachment\n  seq-studio secrets apply --from-env-file .env [-e env]    push defaults + attach (keys default from manifest)\n  seq-studio secrets versions <NAME>                        value version history (never values)\n  seq-studio secrets set-default <NAME> [version]           point the default at a prior version (editor)\n  seq-studio secrets pin <NAME> --fn <slug> [version]       pin one function to a version (sticky; --unpin clears)\n\n  Note: for the common deploy loop, secrets declared in managed-function.yml are\n  reconciled automatically by `seq-studio functions deploy` using a local .env.\n  Use `secrets` commands for CI (no .env), bulk/multi-function ops, or write-only\n  value changes without a redeploy.\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n         --fn <slug> \u00B7 --env-var <NAME> \u00B7 --yes\n         --functions <f1,f2> \u00B7 --keys <K1,K2> \u00B7 --all (override key selection)\n         set-default: [version|version-row-id] (defaults to the most recent non-default) \u00B7 --yes\n         pin: [version|version-row-id] (defaults to the current default) \u00B7 --unpin \u00B7 --yes (redeploy) \u00B7 --yes --no-redeploy\n";
 export declare function runSecretsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/secrets/commands.js

@@ -658,7 +658,7 @@ export const SECRETS_USAGE = `usage:
   Use \`secrets\` commands for CI (no .env), bulk/multi-function ops, or write-only
   value changes without a redeploy.
 
-  Flags: -e/--env <local|staging|production|banksouth>
+  Flags: -e/--env <env>  (see: seq-studio envs list)
          --fn <slug> · --env-var <NAME> · --yes
          --functions <f1,f2> · --keys <K1,K2> · --all (override key selection)
          set-default: [version|version-row-id] (defaults to the most recent non-default) · --yes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/studio-cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Unified Sequence Studio CLI — `seq-studio process` (Lattice), `seq-studio artifact` (Artifact Studio), `seq-studio functions` / `secrets`, `seq-studio repos` (platform git-service), and `seq-studio auth pat` (git-service PATs). Includes Auth0 browser login shared with seqapi.",
   "license": "UNLICENSED",
   "repository": {
@@ -40,11 +40,11 @@
     "smol-toml": "^1.4.2",
     "tsx": "^4.20.3",
     "zod": "^4.1.13",
-    "@sequenceholdings/artifact-studio": "0.1.10",
-    "@sequenceholdings/lattice": "0.1.0"
+    "@sequenceholdings/artifact-studio": "0.1.11",
+    "@sequenceholdings/lattice": "0.1.1"
   },
   "peerDependencies": {
-    "@sequenceholdings/orm": "0.1.0"
+    "@sequenceholdings/orm": "0.1.1"
   },
   "peerDependenciesMeta": {
     "@sequenceholdings/orm": {
@@ -56,7 +56,7 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.5",
-    "@sequenceholdings/orm": "0.1.0"
+    "@sequenceholdings/orm": "0.1.1"
   },
   "engines": {
     "node": ">=20"