handoff-app 2.0.0-7 → 2.0.0-8

package/src/app/pages/account/tokens.tsx

@@ -120,7 +120,9 @@ function RegistryTokensPage() {
         <Card>
           <CardHeader>
             <CardTitle>Create access token</CardTitle>
-            <CardDescription>Use tokens for CI or integrations that cannot complete the browser device login.</CardDescription>
+            <CardDescription>
+              Connect a workspace, a CI job, or an integration. This is the same credential the CLI login issues.
+            </CardDescription>
           </CardHeader>
           <form onSubmit={create}>
             <CardContent className="space-y-4">

package/src/app-builder/build.ts

@@ -443,13 +443,21 @@ After migrations and deployment, open \`/install\` immediately and create the in
 The installer verifies the deployment but never changes the schema. An exposed, uninstalled registry
 can be claimed by its first visitor, so do not leave this step unattended.
 
-Once installation completes, sign in and authorize a workspace:
+Once installation completes, sign in and authorize a workspace. Either approve the CLI in the
+browser:
 
 \`\`\`bash
 handoff-app login --url https://registry.example.com
 \`\`\`
 
-The browser approval issues a revocable, user-owned credential. The former
+or create a token under Account > Access tokens and set it in the workspace environment:
+
+\`\`\`bash
+HANDOFF_REGISTRY_URL=https://registry.example.com
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_…
+\`\`\`
+
+Both produce the same revocable, user-owned credential. The former
 \`HANDOFF_REGISTRY_API_TOKEN\` fixed server secret is no longer accepted.
 
 ## Run it (self-hosting)

package/src/app-builder/client-config.ts

@@ -5,7 +5,7 @@ import { getClientConfig, isMcpEnabled } from '../config';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
 import { resolveAuthenticatedRegistryConnection } from '../registry/connection';
 import { resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
-import type { Config, RuntimeMode } from '../types/config';
+import type { ResolvedConfig, RuntimeMode } from '../types/config';
 import { getAppPath } from './paths';
 
 /**
@@ -53,7 +53,7 @@ export const generateTokensApi = async (handoff: Handoff) => {
  * var) to back the registry-mode docs read API. These are non-secret — the connection-string value
  * itself is never persisted, only resolved from the env var at request time.
  */
-const buildServerRuntimeConfig = (config: Config, modeOverride?: RuntimeMode) => {
+const buildServerRuntimeConfig = (config: ResolvedConfig, modeOverride?: RuntimeMode) => {
   const assetStorage = resolveAssetStorageFromConfig(config);
   return {
     mode: modeOverride ?? config?.runtime?.mode ?? 'workspace',
@@ -100,7 +100,9 @@ export const persistClientConfig = async (handoff: Handoff, options: PersistClie
   // registry URL resolves — from config/env or a saved device login — so `login` alone surfaces
   // the publish/checkout UI without also requiring HANDOFF_REGISTRY_URL.
   const connected =
-    mode === 'registry' ? false : Boolean((await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath)).url);
+    mode === 'registry'
+      ? false
+      : Boolean((await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath, handoff.getProfile())).url);
   clientConfig.runtime = { ...clientConfig.runtime, mode, connected };
 
   await fs.writeJson(path.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });

package/src/app-builder/watchers.ts

@@ -250,21 +250,31 @@ export const watchRuntimeConfiguration = (handoff: Handoff, state: WatcherState)
               const handle =
                 entryBefore && strategy ? strategy.capture(handoff, entryBefore.entityId) : undefined;
 
-              handoff.reload();
-              await persistClientConfig(handoff);
+              let reloadFailed = false;
+              try {
+                handoff.reload();
+                await persistClientConfig(handoff);
+              } catch (e) {
+                // A failed reload leaves the last config that loaded on the instance, so the
+                // re-arm below still names the file that just broke. Without it the file drops
+                // out of the watch set - chokidar stops tracking a watched file once it is
+                // deleted - and a later valid save is never seen.
+                reloadFailed = true;
+                Logger.error('Error reloading runtime configuration:', e);
+              }
+
               watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
               watchRuntimeConfiguration(handoff, state);
 
-              const entryAfter = handoff.getConfigFileEntry(changedFile);
+              if (reloadFailed) {
+                return;
+              }
 
-              const normalizedChanged = normalizePathForCompare(changedFile);
-              const normalizedMainConfig = handoff.getMainConfigFilePath()
-                ? normalizePathForCompare(handoff.getMainConfigFilePath() as string)
-                : undefined;
+              const entryAfter = handoff.getConfigFileEntry(changedFile);
 
               const kindChanged = !!entryBefore && !!entryAfter && entryBefore.kind !== entryAfter.kind;
 
-              if (normalizedMainConfig && normalizedChanged === normalizedMainConfig) {
+              if (handoff.isMainConfigFile(changedFile)) {
                 await processComponents(handoff);
               } else if (kindChanged) {
                 // The declaration switched between an implementation and a composition. A targeted

package/src/cache/build-cache.ts

@@ -48,7 +48,11 @@ export interface BuildCache {
  * Gets the path to the build cache file
  */
 export function getCachePath(handoff: Handoff): string {
-  return path.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', 'build-cache.json');
+  // Two profiles share one project id and can build different output, so the profile has to name
+  // the cache file. One shared cache would serve the other profile's components.
+  const profile = handoff.getProfile();
+  const fileName = profile ? `build-cache.${profile}.json` : 'build-cache.json';
+  return path.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', fileName);
 }
 
 /**

package/src/cli/auth/device.ts

@@ -31,6 +31,8 @@ interface Envelope<T> {
 
 export interface LoginOptions {
   openBrowser?: boolean;
+  /** Profile the issued credential is saved under. Omitted, it is the default profile. */
+  profile?: string;
 }
 
 const sleep = (milliseconds: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, milliseconds));
@@ -71,7 +73,10 @@ const shouldOpenBrowser = (options: LoginOptions): boolean => {
 const positiveNumberOr = (value: unknown, fallback: number): number =>
   typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
 
-/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+/**
+ * Complete the device grant and persist the one-time plaintext access token for this workspace,
+ * under the selected profile.
+ */
 export const loginWithDevice = async (workingPath: string, remoteUrl: string, options: LoginOptions = {}): Promise<CliAuth> => {
   const baseUrl = normalizeRegistryUrl(remoteUrl);
   let deviceResponse: Response;
@@ -98,7 +103,7 @@ export const loginWithDevice = async (workingPath: string, remoteUrl: string, op
   const verificationUrl = assertRegistryOriginUrl(
     baseUrl,
     device.verification_uri_complete ||
-      `${device.verification_uri}${device.verification_uri.includes('?') ? '&' : '?'}user_code=${encodeURIComponent(device.user_code)}`,
+      `${device.verification_uri}${device.verification_uri.includes('?') ? '&' : '?'}user_code=${encodeURIComponent(device.user_code)}`
   );
 
   Logger.log('');
@@ -142,7 +147,7 @@ export const loginWithDevice = async (workingPath: string, remoteUrl: string, op
         accessToken: token.access_token,
         expiresAtMs: Date.now() + expiresIn * 1000,
       };
-      await writeCliAuth(workingPath, auth);
+      await writeCliAuth(workingPath, auth, options.profile);
       return auth;
     }
 

package/src/cli/auth/store.ts

@@ -9,9 +9,17 @@ export interface CliAuth {
   expiresAtMs: number;
 }
 
+/** Name a login is saved under when no profile is selected. */
+export const DEFAULT_LOGIN_PROFILE = 'default';
+
 const AUTH_DIRECTORY = '.handoff';
 const AUTH_FILE = 'cli-auth.json';
 
+/** The credential file: one login per profile name, so a workspace can hold several registries. */
+interface CliAuthFile {
+  logins: Record<string, CliAuth>;
+}
+
 /**
  * Canonicalize a registry URL for both HTTP requests and exact credential matching.
  * Base paths are retained; query strings, fragments, credentials, and trailing slashes are not.
@@ -58,38 +66,67 @@ export const assertRegistryOriginUrl = (baseUrl: string, candidate: string): str
 
 export const cliAuthFilePath = (workingPath: string): string => path.resolve(workingPath, AUTH_DIRECTORY, AUTH_FILE);
 
-const isCliAuth = (value: unknown): value is CliAuth => {
-  if (!value || typeof value !== 'object') return false;
+/** An invalid or partial entry reads as no login, so one bad entry cannot hide the others. */
+const toCliAuth = (value: unknown): CliAuth | null => {
+  if (!value || typeof value !== 'object') return null;
   const auth = value as Partial<CliAuth>;
-  return (
-    typeof auth.remoteUrl === 'string' &&
-    typeof auth.accessToken === 'string' &&
-    auth.accessToken.length > 0 &&
-    typeof auth.expiresAtMs === 'number' &&
-    Number.isFinite(auth.expiresAtMs)
-  );
-};
+  if (typeof auth.remoteUrl !== 'string') return null;
+  if (typeof auth.accessToken !== 'string' || auth.accessToken.length === 0) return null;
+  if (typeof auth.expiresAtMs !== 'number' || !Number.isFinite(auth.expiresAtMs)) return null;
 
-/** Invalid or partial credential files are treated as unauthenticated. */
-export const readCliAuth = async (workingPath: string): Promise<CliAuth | null> => {
   try {
-    const value = (await fs.readJson(cliAuthFilePath(workingPath))) as unknown;
-    if (!isCliAuth(value)) return null;
-    return { ...value, remoteUrl: normalizeRegistryUrl(value.remoteUrl) };
+    return { remoteUrl: normalizeRegistryUrl(auth.remoteUrl), accessToken: auth.accessToken, expiresAtMs: auth.expiresAtMs };
   } catch {
     return null;
   }
 };
 
+const toLogins = (value: unknown): Record<string, CliAuth> => {
+  const logins = (value as Partial<CliAuthFile> | null)?.logins;
+  if (!logins || typeof logins !== 'object') return {};
+
+  const result: Record<string, CliAuth> = {};
+  for (const [profile, entry] of Object.entries(logins as Record<string, unknown>)) {
+    const auth = toCliAuth(entry);
+    if (auth) result[profile] = auth;
+  }
+  return result;
+};
+
+/** Every saved login, keyed by profile name. A missing or unreadable file reads as no logins. */
+export const readCliLogins = async (workingPath: string): Promise<Record<string, CliAuth>> => {
+  try {
+    return toLogins((await fs.readJson(cliAuthFilePath(workingPath))) as unknown);
+  } catch {
+    return {};
+  }
+};
+
+/** The login saved under one profile name. Never falls back to another profile. */
+export const readCliAuth = async (workingPath: string, profile: string = DEFAULT_LOGIN_PROFILE): Promise<CliAuth | null> =>
+  (await readCliLogins(workingPath))[profile] ?? null;
+
+/**
+ * Profile names that have a saved login. Synchronous because config loading is, and the loader needs
+ * these names to decide whether a selected profile resolves.
+ */
+export const loginProfileNames = (workingPath: string): string[] => {
+  try {
+    return Object.keys(toLogins(fs.readJsonSync(cliAuthFilePath(workingPath)) as unknown));
+  } catch {
+    return [];
+  }
+};
+
 /**
  * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
  * whose filesystems do not support POSIX modes.
  */
-export const writeCliAuth = async (workingPath: string, auth: CliAuth): Promise<void> => {
+const writeCliLogins = async (workingPath: string, logins: Record<string, CliAuth>): Promise<void> => {
   const filePath = cliAuthFilePath(workingPath);
   const directory = path.dirname(filePath);
   const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  const value: CliAuth = { ...auth, remoteUrl: normalizeRegistryUrl(auth.remoteUrl) };
+  const value: CliAuthFile = { logins };
 
   await fs.ensureDir(directory, 0o700);
   try {
@@ -117,7 +154,27 @@ export const writeCliAuth = async (workingPath: string, auth: CliAuth): Promise<
   }
 };
 
-export const clearCliAuth = async (workingPath: string): Promise<void> => {
+/** Save the login for one profile and leave the other profiles in place. */
+export const writeCliAuth = async (workingPath: string, auth: CliAuth, profile: string = DEFAULT_LOGIN_PROFILE): Promise<void> => {
+  const logins = await readCliLogins(workingPath);
+  logins[profile] = { ...auth, remoteUrl: normalizeRegistryUrl(auth.remoteUrl) };
+  await writeCliLogins(workingPath, logins);
+};
+
+/** Remove the login for one profile, and the file itself once no login is left. */
+export const clearCliAuth = async (workingPath: string, profile: string = DEFAULT_LOGIN_PROFILE): Promise<void> => {
+  const logins = await readCliLogins(workingPath);
+  delete logins[profile];
+
+  if (Object.keys(logins).length === 0) {
+    await clearAllCliAuth(workingPath);
+    return;
+  }
+  await writeCliLogins(workingPath, logins);
+};
+
+/** Remove every saved login. */
+export const clearAllCliAuth = async (workingPath: string): Promise<void> => {
   const filePath = cliAuthFilePath(workingPath);
   if (await fs.pathExists(filePath)) {
     await fs.remove(filePath);

package/src/commands/login/index.ts

@@ -1,6 +1,6 @@
 import { CommandModule } from 'yargs';
 import { loginWithDevice } from '../../cli/auth/device';
-import { cliAuthFilePath } from '../../cli/auth/store';
+import { cliAuthFilePath, DEFAULT_LOGIN_PROFILE, readCliAuth } from '../../cli/auth/store';
 import { resolveRegistryConnection } from '../../registry/connection';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
@@ -11,6 +11,11 @@ export interface LoginArgs extends SharedArgs {
   browser?: boolean;
 }
 
+/**
+ * Saves one registry credential per profile, so a workspace can hold a login for every registry it
+ * publishes to. The name is independent of the config profiles, and `login` is the one command that
+ * accepts a profile nothing else knows yet.
+ */
 const command: CommandModule<{}, LoginArgs> = {
   command: 'login',
   describe: 'Sign in to a registry using browser device authorization',
@@ -26,17 +31,26 @@ const command: CommandModule<{}, LoginArgs> = {
         describe: 'Open the approval URL in the default browser (disable with --no-browser)',
       }),
   handler: async (args: LoginArgs) => {
-    const handoff = createHandoff(args);
+    const handoff = createHandoff(args, { profileWithoutConfig: 'any' });
+    const profile = handoff.getProfile() ?? DEFAULT_LOGIN_PROFILE;
     try {
       const configured = resolveRegistryConnection(handoff.config);
-      const remoteUrl = args.url?.trim() || configured.url;
+      // Resolved in the order publish and checkout use, so a login always targets the registry those
+      // commands would reach.
+      const saved = await readCliAuth(handoff.workingPath, profile);
+      const remoteUrl = args.url?.trim() || configured.url || saved?.remoteUrl;
       if (!remoteUrl) {
         throw new Error(`Pass --url <registry-url>, configure runtime.registryConnection.url, or set "${configured.urlEnv}".`);
       }
 
-      await loginWithDevice(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false });
-      Logger.success(`Logged in. Credentials saved to ${cliAuthFilePath(handoff.workingPath)}.`);
-      Logger.info('Publish and checkout commands will use this login for the matching registry URL.');
+      await loginWithDevice(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false, profile });
+      const named = profile === DEFAULT_LOGIN_PROFILE ? '' : ` under profile "${profile}"`;
+      Logger.success(`Logged in. Credentials saved to ${cliAuthFilePath(handoff.workingPath)}${named}.`);
+      Logger.info(
+        profile === DEFAULT_LOGIN_PROFILE
+          ? 'Publish and checkout commands will use this login for the matching registry URL.'
+          : `Publish and checkout commands will use this login when they run with --profile ${profile}.`
+      );
     } catch (error) {
       Logger.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;

package/src/commands/logout/index.ts

@@ -1,45 +1,99 @@
 import { CommandModule } from 'yargs';
 import { revokeAccessToken } from '../../cli/auth/device';
-import { clearCliAuth, cliAuthFilePath, cliAuthMatchesRegistry, normalizeRegistryUrl, readCliAuth } from '../../cli/auth/store';
+import {
+  type CliAuth,
+  clearAllCliAuth,
+  clearCliAuth,
+  cliAuthFilePath,
+  cliAuthMatchesRegistry,
+  DEFAULT_LOGIN_PROFILE,
+  normalizeRegistryUrl,
+  readCliAuth,
+  readCliLogins,
+} from '../../cli/auth/store';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
 import { createHandoff, getSharedOptions } from '../utils';
 
 export interface LogoutArgs extends SharedArgs {
   url?: string;
+  all?: boolean;
 }
 
+/** Remote revocation is best effort: the local credential goes either way. */
+const revoke = async (auth: CliAuth): Promise<void> => {
+  try {
+    await revokeAccessToken(auth);
+  } catch (error) {
+    Logger.warn(
+      `Could not revoke the registry token for ${auth.remoteUrl} (${error instanceof Error ? error.message : String(error)}). ` +
+        'It will still be removed from this workspace.'
+    );
+  }
+};
+
+/**
+ * `handoff-app logout` removes the login of the selected profile, leaving every other profile signed
+ * in. `--all` removes them all.
+ */
 const command: CommandModule<{}, LogoutArgs> = {
   command: 'logout',
   describe: 'Revoke and remove saved registry credentials',
   builder: (yargs) =>
-    getSharedOptions(yargs).option('url', {
-      type: 'string',
-      describe: 'Revoke credentials only when they belong to this exact registry URL',
-    }),
+    getSharedOptions(yargs)
+      .option('url', {
+        type: 'string',
+        describe: 'Revoke credentials only when they belong to this exact registry URL',
+      })
+      .option('all', {
+        type: 'boolean',
+        describe: 'Revoke and remove the saved credentials for every profile',
+      })
+      .conflicts('all', 'url'),
   handler: async (args: LogoutArgs) => {
-    const handoff = createHandoff(args);
-    const auth = await readCliAuth(handoff.workingPath);
-    if (args.url && auth && !cliAuthMatchesRegistry(auth, args.url)) {
-      Logger.error(`The saved login belongs to ${auth.remoteUrl}, not ${normalizeRegistryUrl(args.url)}. No credentials were changed.`);
-      process.exitCode = 1;
-      return;
-    }
+    const handoff = createHandoff(args, { profileWithoutConfig: 'saved-login' });
+    const profile = handoff.getProfile() ?? DEFAULT_LOGIN_PROFILE;
+    const named = profile === DEFAULT_LOGIN_PROFILE ? '' : ` for profile "${profile}"`;
+
+    if (args.all) {
+      const logins = await readCliLogins(handoff.workingPath);
+      const names = Object.keys(logins);
+      if (!names.length) {
+        Logger.info('No saved logins.');
+        return;
+      }
 
-    if (auth) {
+      for (const name of names) {
+        await revoke(logins[name]);
+      }
       try {
-        await revokeAccessToken(auth);
+        await clearAllCliAuth(handoff.workingPath);
+        Logger.success(`Logged out of every saved profile: ${names.join(', ')}. Removed ${cliAuthFilePath(handoff.workingPath)}.`);
       } catch (error) {
-        Logger.warn(
-          `Could not revoke the registry token remotely (${error instanceof Error ? error.message : String(error)}). ` +
-            'It will still be removed from this workspace.'
-        );
+        Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
       }
+      return;
+    }
+
+    const auth = await readCliAuth(handoff.workingPath, profile);
+    if (!auth) {
+      Logger.info(`No saved login${named}.`);
+      return;
     }
+    if (args.url && !cliAuthMatchesRegistry(auth, args.url)) {
+      Logger.error(
+        `The saved login${named} belongs to ${auth.remoteUrl}, not ${normalizeRegistryUrl(args.url)}. No credentials were changed.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    await revoke(auth);
 
     try {
-      await clearCliAuth(handoff.workingPath);
-      Logger.success(`Logged out. Removed ${cliAuthFilePath(handoff.workingPath)}.`);
+      await clearCliAuth(handoff.workingPath, profile);
+      Logger.success(`Logged out of ${auth.remoteUrl}${named}. Removed the saved credentials.`);
     } catch (error) {
       Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 1;

package/src/commands/types.ts

@@ -3,6 +3,8 @@ import { Arguments } from 'yargs';
 export interface SharedArgs extends Arguments {
   /** Explicit config file, replacing the usual `handoff.config.*` lookup. */
   config?: string;
+  /** Config profile merged onto the base config; overrides `HANDOFF_PROFILE`. */
+  profile?: string;
   force?: boolean;
   debug?: boolean;
   /**

package/src/commands/utils.ts

@@ -1,5 +1,5 @@
 import { Argv } from 'yargs';
-import Handoff from '../';
+import Handoff, { HandoffOptions } from '../';
 import { REGISTRY_ENTITY_KINDS } from '../registry/content-kinds';
 import { Logger } from '../utils/logger';
 import { SharedArgs } from './types';
@@ -20,22 +20,26 @@ export type RegistryTargetKind = (typeof REGISTRY_TARGET_KINDS)[number];
 export const COMPAT_TARGET_KINDS = [...REGISTRY_ENTITY_KINDS, 'all'] as const;
 export type CompatTargetKind = (typeof COMPAT_TARGET_KINDS)[number];
 
-export const createHandoff = (args: SharedArgs): Handoff =>
+export const createHandoff = (args: SharedArgs, options: Pick<HandoffOptions, 'profileWithoutConfig'> = {}): Handoff =>
   new Handoff({
     debug: args.debug,
     force: args.force,
     configPath: args.config,
+    profile: args.profile,
     dryRun: args.dryRun,
     // yargs gives `--no-build` as `build: false`; anything else leaves the build in place.
     skipBuild: args.build === false,
+    ...options,
   });
 
 /**
- * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
- * surface as one actionable line and a non-zero exit rather than a stack trace.
+ * Run a registry command against a fresh Handoff. A selected profile may name a saved login instead
+ * of a config file, because here the profile selects the registry. Registry failures are the
+ * user's to act on, so they surface as one actionable line and a non-zero exit rather than a stack
+ * trace.
  */
 export const runRegistryCommand = async (args: SharedArgs, run: (handoff: Handoff) => Promise<unknown>): Promise<void> => {
-  const handoff = createHandoff(args);
+  const handoff = createHandoff(args, { profileWithoutConfig: 'saved-login' });
   try {
     await run(handoff);
   } catch (error) {
@@ -61,6 +65,11 @@ export const getSharedOptions = (yargs: Argv) => {
       type: 'boolean',
       description: 'Enable debug mode',
     },
+    profile: {
+      type: 'string',
+      description:
+        'Config profile merged onto the base config (handoff.config.<profile>.*), and the saved login that registry commands use; overrides HANDOFF_PROFILE',
+    },
   });
 };
 

package/src/config/README.md

@@ -7,10 +7,15 @@ Handles loading, validation, and resolution of handoff configuration.
 | File | Purpose |
 |------|---------|
 | `defaults.ts` | Default config values and `getClientConfig()` for the Next.js app |
-| `loader.ts` | `initConfig()` — reads `handoff.config.ts/.js/.cjs/.json` (in that order), warns on conflicts, and merges overrides |
+| `from-env.ts` | JSON-compatible environment markers and public types |
+| `resolve-env.ts` | Resolves merged environment references and guards reference-only properties |
+| `errors.ts` | Shared `HandoffConfigError` |
+| `env.ts` | Reads `.env` at load, then `loadProfileEnv()` applies `.env.<profile>` on top |
+| `loader.ts` | `initConfig()` — reads `handoff.config.ts/.js/.cjs/.json` (in that order) plus the selected profile sidecar, warns on conflicts, and merges every layer |
 | `runtime.ts` | `initRuntimeConfig()` — one pass over every registered catalog directory: loads each declaration, normalizes it into a component or pattern record, skips a declaration with a taken id, resolves SCSS/JS paths and transformer options |
 | `catalog-include.ts` | `isIncluded()` / `addToCatalog()` — registers a directory under `catalog.include` |
 | `validator.ts` | `validateConfig()` — ensures required Figma credentials are present |
+| `helpers.ts` | `defineConfig()` — typed authoring; maps camelCase keys to the runtime keys |
 | `index.ts` | Barrel re-exports |
 
 ## Usage
@@ -31,3 +36,58 @@ When multiple main config files exist in the project root, Handoff picks the fir
 2. `handoff.config.js`
 3. `handoff.config.cjs`
 4. `handoff.config.json`
+
+## Profiles
+
+`--profile <name>`, or `HANDOFF_PROFILE` when the flag is absent, adds one sidecar file. It sits beside the resolved base config: the base file name without its extension, then the profile name, then any config extension. So `handoff.config.ts` pairs with `handoff.config.<name>.*`, and a config named through `-c` keeps its own name. The same four extensions are probed in the same order. A selected profile that does not resolve is a `HandoffConfigError`.
+
+`ConfigLoadContext.knownProfiles` widens what resolving means: a listed name loads the base config unchanged instead of failing. The CLI passes the saved registry login names for `login`, `logout`, `publish`, and `checkout`, where a profile selects the registry rather than a config layer. `profileNotFoundHint` is the caller's sentence for a name that matches neither. Everything else keeps the strict rule, so a typo cannot silently run with the base config.
+
+## Environment Files
+
+`.env` is read once when `env.ts` loads, before the first `Handoff` is constructed. A selected profile then adds an optional `.env.<profile>` from the same directory. Precedence is the process environment, then the profile env file, then `.env`. The keys present at startup are recorded before `.env` is read and are never overwritten, so an inline `VAR=… handoff-app …` still wins.
+
+`loadProfileEnv()` runs twice: in `Handoff.construct()` before `Logger.init()`, so the log level can come from a profile, and in `initConfigWithMetadata()` before the merged environment references resolve. Applying it twice changes nothing.
+
+## Layer Precedence
+
+Every loaded file is normalized, then the layers are merged in this order:
+
+1. `defaultConfig()`
+2. Base config file
+3. Profile file
+4. Programmatic override (`HandoffOptions.config`)
+
+Plain objects merge recursively. Arrays, scalars, `null`, and functions replace. `undefined` is skipped.
+
+## Environment references
+
+Import `fromEnv` from `handoff-app`. `fromEnv('OUTPUT_DIR', { default: 'exported' })` creates
+`{ $env: 'OUTPUT_DIR', default: 'exported' }` without reading the environment. JSON configs use
+that same object. Without a default, an unset variable raises `HandoffConfigError` with the
+property path, variable name, and active profile. Invalid names and rejected literals are never echoed.
+
+`EnvValue<T>` accepts a literal or reference. `EnvSecret<T>` accepts only a reference and resolves
+at config load. Secret defaults can only be empty or null, for optional credentials.
+`RuntimeEnvReference<T>` accepts only a reference with no default. Its name survives config loading and
+is read in the deployed process. Database URLs and asset-storage tokens are deferred.
+
+The loader resolves references once after all layers merge, before other config guards.
+References replace whole values, including earlier references and their defaults. A profile can
+replace an ordinary reference with a literal. Functions in hooks and pipeline remain functions.
+Defaults retain the existing `HANDOFF_*` seeds: a higher-layer literal beats a seed, and an explicit
+reference beats every lower layer. Only the winning reference reads the environment.
+
+Environment values are strings. A numeric or boolean default selects conversion; the built-in
+numeric and boolean properties also retain their default's conversion when a reference omits its
+fallback. Booleans are true only for `true`. Numbers must be finite. A lower-layer fallback never
+becomes the fallback for a replacement reference.
+
+`runtime.registry.assetStorage.options` is for non-secret values only. Its resolved contents are
+JSON-encoded into the bundle, so the loader rejects an environment reference anywhere inside it
+(`BAKED_PATHS`). For custom adapter secrets, put a variable name in options and read it through the
+adapter factory's `env` argument at runtime. A per-environment literal belongs in a profile.
+
+`ResolvedConfig` narrows eager properties by hand. Adding an eager property requires its `Config`
+member and resolved narrowing. A secret also needs a `SECRET_PATHS` entry for untyped configs.
+Adding a deferred property requires its member and a `DEFERRED_PATHS` entry.

package/src/config/catalog-include.ts

@@ -14,13 +14,13 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { Config } from '../types/config';
+import { ResolvedConfig } from '../types/config';
 import { arePathsEqual } from '../utils/path';
 import { getComponentsForPath } from './runtime';
 
 /** Minimal handoff shape needed here; avoids importing the full Handoff class (circular dep). */
 interface ConfigContext {
-  config?: Config;
+  config?: ResolvedConfig;
   workingPath: string;
 }