@sequenceholdings/studio-cli 0.1.10 → 0.1.12

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/bin.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 import { run } from './main.js';
+import { maybeNotifyUpdate } from './update-check.js';
 run()
-    .then((code) => process.exit(code))
     .catch((error) => {
     console.error(error instanceof Error ? error.message : error);
-    process.exit(1);
+    return 1;
+})
+    // The update notice runs after the command so it never delays real output,
+    // and it is best-effort (never throws, never changes the exit code).
+    .then(async (code) => {
+    await maybeNotifyUpdate();
+    process.exit(code);
 });

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 });
+    }
+}