@productbrain/cli 0.1.0-beta.94 → 0.1.0-beta.9413

package/dist/__tests__/config.test.js

@@ -1,17 +1,19 @@
 /**
  * Tests for config resolution — WP-303 Slice 0.
  *
- * Tests resolveConfig(), getConfigSafe(), and .productbrain/config.json reading.
+ * Tests resolveConfig(), getConfigSafe(), findProjectRoot(), and config file reading.
  * Uses temp directories and mocks to isolate from real config on the filesystem.
  */
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { mkdirSync, writeFileSync, rmSync } from 'fs';
-import { resolve } from 'path';
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from 'fs';
+import { dirname, resolve } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 // Mock the profiles module to prevent real profile config from leaking in
 vi.mock('../lib/profiles.js', () => ({
     resolveProfileConfig: vi.fn(() => null),
+    resolveNamedProfileConfig: vi.fn(() => null),
+    getGlobalActiveProfile: vi.fn(() => null),
 }));
 // Mock os.homedir to prevent reading real ~/.config/productbrain/.env
 vi.mock('os', async (importOriginal) => {
@@ -28,9 +30,13 @@ describe('config resolution', () => {
     const envKeys = ['PRODUCTBRAIN_API_KEY', 'CONVEX_SITE_URL', 'PB_PROFILE', 'PB_ENV'];
     // Import after mock setup
     let resolveConfig;
+    let getConfig;
     let getConfigSafe;
     let resetConfigCache;
+    let findProjectRoot;
     beforeEach(async () => {
+        // Reset all mocks first to prevent queued mockReturnValueOnce state leakage between tests
+        vi.resetAllMocks();
         // Save and clear relevant env vars
         for (const key of envKeys) {
             savedEnv[key] = process.env[key];
@@ -44,8 +50,10 @@ describe('config resolution', () => {
         // Dynamic import to get module with mocks applied
         const config = await import('../lib/config.js');
         resolveConfig = config.resolveConfig;
+        getConfig = config.getConfig;
         getConfigSafe = config.getConfigSafe;
         resetConfigCache = config.resetConfigCache;
+        findProjectRoot = config.findProjectRoot;
         // Reset envLoaded state before each test
         resetConfigCache();
     });
@@ -69,22 +77,208 @@ describe('config resolution', () => {
             // ignore
         }
     });
+    describe('findProjectRoot()', () => {
+        it('finds .productbrain/ in the start directory', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), '{}');
+            const result = findProjectRoot(tempDir);
+            expect(result).toBe(tempDir);
+        });
+        it('finds .productbrain/ in a parent directory', () => {
+            // Create .productbrain/ in tempDir with a config file
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), '{}');
+            // Create a subdirectory and search from there
+            const subDir = resolve(tempDir, 'src', 'commands');
+            mkdirSync(subDir, { recursive: true });
+            const result = findProjectRoot(subDir);
+            expect(result).toBe(tempDir);
+        });
+        it('skips a projection-only .productbrain/ subtree and walks to the config-bearing root', () => {
+            // Repo root has a config-bearing .productbrain.
+            const rootPbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(rootPbDir, { recursive: true });
+            writeFileSync(resolve(rootPbDir, 'config.json'), '{}');
+            // A subrepo has a projection-only .productbrain (handshake artifacts, no config files).
+            const subRepo = resolve(tempDir, 'packages', 'cli');
+            const subPbDir = resolve(subRepo, '.productbrain');
+            mkdirSync(subPbDir, { recursive: true });
+            writeFileSync(resolve(subPbDir, 'briefing.md'), '# briefing');
+            writeFileSync(resolve(subPbDir, 'context.md'), '# context');
+            // Walking up from inside the subrepo must skip the projection and reach the root.
+            const result = findProjectRoot(subRepo);
+            expect(result).toBe(tempDir);
+        });
+        it('accepts a sub-tree .productbrain/ that does carry its own config', () => {
+            // Intentional sub-config is respected (e.g. a nested CLI project).
+            const subRepo = resolve(tempDir, 'sub');
+            const subPbDir = resolve(subRepo, '.productbrain');
+            mkdirSync(subPbDir, { recursive: true });
+            writeFileSync(resolve(subPbDir, 'config.local.json'), '{}');
+            const result = findProjectRoot(subRepo);
+            expect(result).toBe(subRepo);
+        });
+        it('returns null when no .productbrain/ found up to home', () => {
+            // tempDir is under the real system tmpdir. The mocked homedir() returns a
+            // path that is NOT an ancestor of tempDir, so the walk will exhaust all
+            // ancestors of tempDir up to the filesystem root and return null because
+            // neither tempDir nor any ancestor has .productbrain/ AND the mocked home
+            // is never reached (it's a sibling branch, not a parent).
+            // We use a fresh subdir under tempDir so there is definitely no .productbrain/.
+            const searchDir = resolve(tempDir, 'no-pb-here', 'subdir');
+            mkdirSync(searchDir, { recursive: true });
+            const result = findProjectRoot(searchDir);
+            expect(result).toBeNull();
+        });
+        it('stops walking at the home directory', () => {
+            // The mocked homedir() returns a fake path outside tempDir.
+            // Create a fresh dir inside tempDir (no .productbrain/ present).
+            // findProjectRoot will walk up from it, never find .productbrain/,
+            // and eventually stop — returning null.
+            const deepDir = resolve(tempDir, 'deeply', 'nested', 'project');
+            mkdirSync(deepDir, { recursive: true });
+            const result = findProjectRoot(deepDir);
+            expect(result).toBeNull();
+        });
+    });
     describe('resolveConfig()', () => {
-        it('returns project config.json values when env vars are absent', () => {
+        it('returns project config.local.json profile values when env vars absent', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_local_profile_key',
+                siteUrl: 'https://local-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'my-workspace' }));
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_local_profile_key');
+            expect(result.siteUrl).toBe('https://local-profile.example.com');
+            expect(result.source).toBe('project');
+        });
+        it('config.local.json profile beats global profile', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_local_profile_key',
+                siteUrl: 'https://local-profile.example.com',
+            });
+            resolveProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'local-workspace' }));
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_local_profile_key');
+            expect(result.source).toBe('project');
+        });
+        it('FAILS CLOSED on a dangling repo-local pin — never silently falls through to the global active profile', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            // Pin names a profile that no longer resolves (deleted, or never fully set up).
+            resolveNamedProfileConfig.mockReturnValue(null);
+            // A perfectly usable global profile is available — and must NOT be adopted.
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'deleted-workspace' }));
+            expect(() => resolveConfig()).toThrow(/pinned to profile "deleted-workspace"/);
+        });
+        it('dangling repo-local pin throws AUTH_MISSING rather than returning a foreign credential', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            // Pin resolves to a profile file that exists but carries no API key.
+            resolveNamedProfileConfig.mockReturnValue({
+                siteUrl: 'https://pinned.example.com',
+            });
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'keyless-workspace' }));
+            let caught;
+            try {
+                resolveConfig();
+            }
+            catch (e) {
+                caught = e;
+            }
+            expect(caught?.code).toBe('AUTH_MISSING');
+        });
+        it('getConfig() refuses a dangling pin — the loadEnv() cascade must not adopt the global profile', async () => {
+            // This is the door ~98 command modules use, and it is a SEPARATE cascade from
+            // resolveConfig() — loadEnv() mutates process.env rather than returning a value.
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue(null);
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'deleted-workspace' }));
+            expect(() => getConfig()).toThrow(/pinned to profile "deleted-workspace"/);
+            // The foreign credential must never become the live binding.
+            expect(process.env.PRODUCTBRAIN_API_KEY).toBeUndefined();
+        });
+        it('a pin whose profile has a malformed key is a broken pin, not a credential', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'not-a-pb-key',
+                siteUrl: 'https://pinned.example.com',
+            });
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
-            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ apiKey: 'pb_sk_project_key', siteUrl: 'https://custom.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'malformed-workspace' }));
+            // Names the pin, rather than deferring to a generic "no API key, run pb login".
+            expect(() => resolveConfig()).toThrow(/pinned to profile "malformed-workspace"/);
+        });
+        it('getConfigSafe() REPORTS a dangling pin instead of throwing — diagnostics must still render', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue(null);
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'deleted-workspace' }));
+            // `pb doctor` and the bare-`pb` dashboard go through here; they must diagnose, not die.
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            expect(result.reason).toMatch(/pinned to profile "deleted-workspace"/);
+        });
+        it('a pin with no URL of its own goes to DEFAULT_SITE_URL, never config.json siteUrl (TEN-4500)', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_pinned_key',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://project-gateway.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
             const result = resolveConfig();
-            expect(result.apiKey).toBe('pb_sk_project_key');
-            expect(result.siteUrl).toBe('https://custom.example.com');
+            expect(result.apiKey).toBe('pb_sk_pinned_key');
+            expect(result.siteUrl).toBe('https://gateway.productbrain.io');
+            expect(result.siteUrlSource).toBe('default');
             expect(result.source).toBe('project');
         });
-        it('env vars override project config.json', () => {
+        it('env vars override project config.local.json', () => {
             process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
             process.env.CONVEX_SITE_URL = 'https://env.example.com';
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
-            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ apiKey: 'pb_sk_project_key', siteUrl: 'https://project.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'some-workspace' }));
             const result = resolveConfig();
             expect(result.apiKey).toBe('pb_sk_env_key');
             expect(result.siteUrl).toBe('https://env.example.com');
@@ -96,14 +290,18 @@ describe('config resolution', () => {
             expect(result.siteUrl).toBe('https://gateway.productbrain.io');
             expect(result.source).toBe('default');
         });
-        it('handles partial project config (only siteUrl, no apiKey)', () => {
+        it('ignores profile field in config.json (legacy migration) — not a pin, so the project has no tenant', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            // Old config.json with profile field — must be ignored, not treated as a pin
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://project.example.com', profile: 'should-be-ignored' }));
+            expect(() => resolveConfig()).toThrow(/no tenant pin/i);
+        });
+        it('a declared project with only siteUrl and no pin refuses rather than falling through', () => {
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
             writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://partial.example.com' }));
-            const result = resolveConfig();
-            // No apiKey in project config, so it should fall through to default
-            expect(result.apiKey).toBeUndefined();
-            expect(result.source).toBe('default');
+            expect(() => resolveConfig()).toThrow(/no tenant pin/i);
         });
     });
     describe('getConfigSafe()', () => {
@@ -115,6 +313,211 @@ describe('config resolution', () => {
                 expect(result.reason).toContain('No API key');
             }
         });
+        it('names the FILE, not CONVEX_SITE_URL, when a file supplied the non-HTTPS URL', () => {
+            // A file-sourced siteUrl outranks CONVEX_SITE_URL everywhere except an env-key override, so
+            // "set CONVEX_SITE_URL" would send the operator back through the same failure.
+            process.env.CONVEX_SITE_URL = 'https://this-would-never-win.example.com';
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'http://insecure.example.com',
+                preview: true,
+            }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.reason).toMatch(/must use HTTPS/i);
+                // The binding supplies its own URL, so the repair is that file alone — naming a profile
+                // it may also pin would point at something that does not control this URL.
+                expect(result.guidance).toContain('.productbrain/config.local.json');
+                expect(result.guidance).not.toMatch(/profile/i);
+                expect(result.guidance).not.toMatch(/CONVEX_SITE_URL/);
+            }
+        });
+        it('names CONVEX_SITE_URL when the environment did supply the non-HTTPS URL', () => {
+            process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+            process.env.CONVEX_SITE_URL = 'http://insecure.example.com';
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('CONVEX_SITE_URL');
+            }
+        });
+        // ── The URL's origin is NOT the credential's origin ────────────────────────────────────
+        //
+        // A key travels only with the URL beside it (TEN-4500), so the repair names that source —
+        // never config.json, whose siteUrl no longer routes any key, and never a sibling file that
+        // happens to sit in the same directory.
+        it('a non-HTTPS config.json siteUrl never reaches a pinned key (TEN-4500)', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pinned_key',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'http://insecure.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(true);
+            if (result.ok)
+                expect(result.siteUrl).toBe('https://gateway.productbrain.io');
+        });
+        it('names the pin — not config.json or a CWD .env — when the pinned profile supplied the URL', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pinned_key',
+                siteUrl: 'http://pin.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'http://insecure.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+            writeFileSync(resolve(tempDir, '.env'), 'PRODUCTBRAIN_API_KEY=pb_sk_cwd_key\nCONVEX_SITE_URL=https://cwd-would-have-been-fine.example.com\n');
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.reason).toContain('http://pin.example.com');
+                expect(result.guidance).toContain('pinned by .productbrain/config.local.json');
+                expect(result.guidance).not.toContain('.productbrain/config.json');
+                expect(result.guidance).not.toMatch(/\.env file/);
+            }
+        });
+        it('names the profile the repo pin points at, not just "the profile it pins"', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pinned_key_0123456789',
+                siteUrl: 'http://insecure.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'pinned-workspace' }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('pinned-workspace');
+            }
+        });
+        it('names the CWD env file that actually won, not the generic .env', () => {
+            // CWD_ENV_PATHS scans .env.mcp first, so a generic "the .env file" label would send the
+            // operator to edit a file the cascade never read.
+            writeFileSync(resolve(tempDir, '.env.mcp'), 'PRODUCTBRAIN_API_KEY=pb_sk_cwd_key\nCONVEX_SITE_URL=http://insecure.example.com\n');
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('.env.mcp');
+            }
+        });
+        it('tells the operator to unset PRODUCTBRAIN_API_KEY — not to run pb login — for a bad exported key', () => {
+            // An exported key wins step 1 of the cascade, and `pb login` writes to a profile or the
+            // legacy home file — both of which lose to it. "Run pb login" would loop forever.
+            process.env.PRODUCTBRAIN_API_KEY = 'bad_prefix_key';
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-key');
+                expect(result.guidance).toMatch(/Unset PRODUCTBRAIN_API_KEY|replace it/);
+                // `pb login` may only be named to explain why it cannot help — never as the instruction.
+                expect(result.guidance).not.toMatch(/Run `pb login`/);
+                expect(result.guidance).toMatch(/cannot repair/);
+                expect(result.nextCommand).not.toBe('pb login');
+            }
+        });
+        it('still points a stored malformed key at pb login — login CAN repair that one', async () => {
+            const { resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'bad_prefix_key',
+                siteUrl: 'https://profile.example.com',
+            });
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-key');
+                expect(result.guidance).toMatch(/pb login/);
+                expect(result.nextCommand).toBe('pb login');
+            }
+        });
+        // ── Which profile actually supplied it ──────────────────────────────────────────────────
+        //
+        // resolveProfileConfig() reaches a credential four ways — PB_PROFILE, the active-profile
+        // marker, a `default` fallback, and the legacy ~/.config/productbrain/.env — and reports the
+        // winner's name. A fixed "the active profile" label sends the operator to edit a profile that
+        // supplied nothing, so the same failure comes straight back.
+        it('names the PB_PROFILE-selected profile, not "the active profile", for its non-HTTPS URL', async () => {
+            const { resolveProfileConfig, getGlobalActiveProfile } = await import('../lib/profiles.js');
+            // A DIFFERENT profile is globally active. PB_PROFILE outranks it in profiles.ts, which
+            // returns the selected name alongside the credential (profiles.ts resolveProfileConfig 1).
+            getGlobalActiveProfile.mockReturnValue('main-workspace');
+            process.env.PB_PROFILE = 'preview-workspace';
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_selected_profile_key',
+                siteUrl: 'http://insecure.example.com',
+                profileName: 'preview-workspace',
+            });
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('the profile "preview-workspace"');
+                expect(result.guidance).not.toContain('the active profile');
+                // The globally active profile did not supply this URL and must not be named.
+                expect(result.guidance).not.toContain('main-workspace');
+            }
+        });
+        it('names the `default` fallback profile for a malformed stored key', async () => {
+            const { resolveProfileConfig } = await import('../lib/profiles.js');
+            // No PB_PROFILE and no active-profile marker: profiles.ts falls back to `default`, which is
+            // a real file the operator can open — "the active profile" is not.
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'bad_prefix_key',
+                siteUrl: 'https://profile.example.com',
+                profileName: 'default',
+            });
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-key');
+                expect(result.reason).toContain('the profile "default"');
+                expect(result.reason).not.toContain('the active profile');
+            }
+        });
+        it('does NOT call the legacy home config "the active profile" — it is not a named profile', async () => {
+            // resolveConfig() step 4 labels the legacy ~/.config/productbrain/.env `profile`, but it
+            // carries no profile name at all, so naming a profile there would be a fabrication.
+            const { HOME_ENV_PATH } = await import('../lib/config.js');
+            mkdirSync(dirname(HOME_ENV_PATH), { recursive: true });
+            writeFileSync(HOME_ENV_PATH, 'PRODUCTBRAIN_API_KEY=bad_prefix_key\n');
+            try {
+                resetConfigCache();
+                const result = getConfigSafe();
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.kind).toBe('invalid-key');
+                    expect(result.reason).not.toContain('the active profile');
+                    expect(result.reason).toContain('the stored profile configuration');
+                }
+            }
+            finally {
+                // The fake home is shared by every test in this file; a stray legacy .env would supply a
+                // credential to the cases that assert none is found.
+                rmSync(HOME_ENV_PATH, { force: true });
+            }
+        });
         it('returns { ok: true } with correct source when key exists in env', () => {
             process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_test_key';
             process.env.CONVEX_SITE_URL = 'https://test.example.com';
@@ -127,10 +530,15 @@ describe('config resolution', () => {
                 expect(result.source).toBe('env');
             }
         });
-        it('returns { ok: true } with project source when key in config.json', () => {
+        it('returns { ok: true } with project source when key in config.local.json profile', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_proj_safe',
+                siteUrl: 'https://proj.example.com',
+            });
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
-            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ apiKey: 'pb_sk_proj_safe', siteUrl: 'https://proj.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'test-workspace' }));
             resetConfigCache();
             const result = getConfigSafe();
             expect(result.ok).toBe(true);
@@ -139,16 +547,51 @@ describe('config resolution', () => {
                 expect(result.source).toBe('project');
             }
         });
+        it('SF-3: preview binding overrides a stale CONVEX_SITE_URL exported in the shell', () => {
+            // Real-dev URL exported but no PRODUCTBRAIN_API_KEY — the realistic dogfood shell.
+            process.env.CONVEX_SITE_URL = 'https://trustworthy-kangaroo-277.convex.site';
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            // Preview key must NEVER be paired with the stale real-dev URL — that would
+            // route a preview credential to a non-preview gateway (STD-261).
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.apiKey).toBe('pb_sk_preview_key_0123456789abcdef');
+                expect(result.siteUrl).toBe('https://my-preview.convex.site');
+            }
+        });
     });
     describe('.productbrain/config.json error handling', () => {
-        it('warns but does not crash on invalid JSON', () => {
+        it('warns on invalid JSON, and still refuses — a damaged declaration is not an escape hatch', () => {
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
             writeFileSync(resolve(pbDir, 'config.json'), '{ invalid json!!!');
+            // The file is unreadable but PRESENT, so the repo has still declared itself a project.
+            // Falling through here would hand the global profile a workspace precisely when the
+            // committed declaration is corrupt — the wrong-tenant substitution WP-694 S2 closes.
+            //
+            // No stderr assertion: the refusal is reached on the file's EXISTENCE, so nothing parses
+            // config.json on this path and the "invalid JSON" warning never fires. Refusing outright
+            // supersedes warning-then-using-someone-else's-workspace. The sibling test below still
+            // covers the warn-and-continue path for a malformed config.local.json.
+            expect(() => resolveConfig()).toThrow(/no tenant pin/i);
+        });
+        it('warns but does not crash on invalid config.local.json', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), '{ invalid json!!!');
             // Capture stderr
             const stderrWrite = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
             const result = resolveConfig();
-            // Should have warned
+            // Should have warned about config.local.json
             expect(stderrWrite).toHaveBeenCalledWith(expect.stringContaining('invalid JSON'));
             // Should fall through to default
             expect(result.apiKey).toBeUndefined();
@@ -162,5 +605,481 @@ describe('config resolution', () => {
             expect(result.source).toBe('default');
         });
     });
+    describe('directory walking', () => {
+        it('resolveConfig reads config.local.json from a parent directory', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_parent_key',
+                siteUrl: 'https://parent.example.com',
+            });
+            // Create .productbrain in tempDir
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'parent-workspace' }));
+            // Set CWD to a subdirectory
+            const subDir = resolve(tempDir, 'src', 'lib');
+            mkdirSync(subDir, { recursive: true });
+            process.cwd = () => subDir;
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_parent_key');
+            expect(result.source).toBe('project');
+        });
+    });
+    describe('setLocalProfilePin', () => {
+        it('creates config.local.json with the profile pin', async () => {
+            const { setLocalProfilePin, readLocalProjectConfig } = await import('../lib/config.js');
+            mkdirSync(resolve(tempDir, '.productbrain'), { recursive: true });
+            setLocalProfilePin(tempDir, 'preview-ws');
+            expect(readLocalProjectConfig()?.profile).toBe('preview-ws');
+        });
+        it('preserves sibling keys when updating the pin', async () => {
+            const { setLocalProfilePin } = await import('../lib/config.js');
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'old', somethingElse: 1 }));
+            setLocalProfilePin(tempDir, 'new');
+            const parsed = JSON.parse(readFileSync(resolve(pbDir, 'config.local.json'), 'utf8'));
+            expect(parsed).toEqual({ profile: 'new', somethingElse: 1 });
+        });
+        it('overwrites corrupt JSON and writes only the new pin', async () => {
+            const { setLocalProfilePin } = await import('../lib/config.js');
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), '{ this is not valid json!!!');
+            setLocalProfilePin(tempDir, 'new');
+            const parsed = JSON.parse(readFileSync(resolve(pbDir, 'config.local.json'), 'utf8'));
+            expect(parsed).toEqual({ profile: 'new' });
+        });
+    });
+    describe('resolveEffectiveProfile', () => {
+        it('returns env source when PB_PROFILE is set', async () => {
+            process.env.PB_PROFILE = 'from-env';
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: 'from-env', source: 'env' });
+        });
+        it('returns local source when a repo pin exists', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'repo-pin' }));
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: 'repo-pin', source: 'local' });
+        });
+        // The pin's key is bound by resolveConfig() step 2b / loadEnv() step 1b before the profile
+        // system reads PB_PROFILE, so the env name never supplies the credential here. Reporting it
+        // would label every identity surface with a workspace the CLI is not operating against.
+        it('prefers the repo pin over PB_PROFILE, matching which profile supplies the credential', async () => {
+            process.env.PB_PROFILE = 'from-env';
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'repo-pin' }));
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: 'repo-pin', source: 'local' });
+        });
+        it('returns global source from the active-profile file when no local pin', async () => {
+            const profiles = await import('../lib/profiles.js');
+            profiles.getGlobalActiveProfile.mockReturnValue('global-ws');
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: 'global-ws', source: 'global' });
+        });
+        it('returns none when nothing is configured', async () => {
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: null, source: 'none' });
+        });
+        it('returns default source when no env/local/global but default profile resolves', async () => {
+            // No PB_PROFILE env var (cleared by beforeEach)
+            // No config.local.json in tempDir (tempDir is fresh per beforeEach)
+            const profiles = await import('../lib/profiles.js');
+            profiles.getGlobalActiveProfile.mockReturnValue(null);
+            profiles.resolveNamedProfileConfig.mockReturnValue({ apiKey: 'pb_live_x' });
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: 'default', source: 'default' });
+        });
+    });
+    // ─── Preview binding (Slice B) ───────────────────────────────────────────────
+    describe('resolveConfig() — direct preview binding in config.local.json', () => {
+        it('returns preview key + siteUrl when config.local.json has a direct apiKey', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_preview_key_0123456789abcdef');
+            expect(result.siteUrl).toBe('https://my-preview.convex.site');
+            expect(result.source).toBe('project');
+        });
+        it('env var still wins over direct preview binding', () => {
+            process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_override';
+            process.env.CONVEX_SITE_URL = 'https://env.example.com';
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_should_be_ignored',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+            }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_env_override');
+            expect(result.siteUrl).toBe('https://env.example.com');
+            expect(result.source).toBe('env');
+        });
+        it('profile pin still works when no direct apiKey present', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_profile_key',
+                siteUrl: 'https://profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'my-workspace' }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_profile_key');
+            expect(result.source).toBe('project');
+        });
+        it('rejects a preview binding whose apiKey does not start with API_KEY_PREFIX', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'sk_bad_prefix_key',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+            }));
+            resetConfigCache();
+            // A present-but-malformed key is unusable, not absent — the refusal must say so, or the
+            // operator goes looking for a key that is sitting right there in the file.
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*not a valid pb_sk_ key/i);
+        });
+        it('SF-3: does NOT bind a preview apiKey that has no siteUrl (never borrows config.json gateway)', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            // Committed config.json pins the real-dev gateway.
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://trustworthy-kangaroo-277.convex.site' }));
+            // Preview key present but its OWN siteUrl is absent (hand-edit / partial preview.json).
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'pb_sk_preview_key_0123456789abcdef', preview: true }));
+            resetConfigCache();
+            // The preview key must NOT be bound or allowed to fall through. Pairing it with
+            // config.json's real-dev gateway would send a preview credential to the wrong deployment.
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+        });
+        it('S5: an incomplete preview binding is diagnosed before a sibling profile pin', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue(null);
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                profile: 'repo-pin',
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            resetConfigCache();
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+            expect(() => getConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+        });
+        // ── Marker-less bindings: the claim is the credential, not the `preview` stamp ──────────
+        //
+        // A config.local.json carrying an apiKey is asserting which workspace this repo talks to
+        // whether or not `pb:preview` stamped `preview: true` — a hand-written or partially-scrubbed
+        // file is exactly the case that must not be skipped.
+        it('binds a marker-less apiKey + siteUrl pair and does NOT defer to a sibling profile pin', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            // A perfectly resolvable pin sits in the same file — it names a DIFFERENT tenant, so
+            // adopting it would silently retarget every read and write.
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_sibling_pin_key',
+                siteUrl: 'https://sibling-pin.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                profile: 'sibling-pin',
+                apiKey: 'pb_sk_markerless_key_0123456789',
+                siteUrl: 'https://markerless.convex.site',
+                // no `preview: true` marker
+            }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_markerless_key_0123456789');
+            expect(result.siteUrl).toBe('https://markerless.convex.site');
+            expect(result.source).toBe('project');
+        });
+        it('refuses a marker-less apiKey with no siteUrl instead of resolving to the default gateway', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'pb_sk_markerless_key_0123456789' }));
+            resetConfigCache();
+            // Silently falling through would send this credential to the production gateway (STD-261).
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+        });
+        it('S5: the marker-less refusal also holds through the loadEnv() cascade', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'pb_sk_markerless_key_0123456789' }));
+            resetConfigCache();
+            expect(() => getConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+            // The refusal must not leave a half-bound credential behind for the next caller.
+            expect(process.env.PRODUCTBRAIN_API_KEY).toBeUndefined();
+        });
+        // A present-but-non-string apiKey is a corrupt or hand-written binding, not an absent one.
+        // Treating it as absent would let the sibling profile pin supply a DIFFERENT tenant's
+        // credential — the workspace substitution this path exists to prevent.
+        it.each([
+            ['a number', 12345],
+            ['an empty string', ''],
+            ['a boolean', true],
+            ['an object', { key: 'pb_sk_nested' }],
+        ])('refuses a marker-less binding whose apiKey is %s, rather than adopting the sibling pin', async (_label, apiKey) => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            // A perfectly resolvable pin naming a DIFFERENT tenant sits in the same file.
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_sibling_pin_key',
+                siteUrl: 'https://sibling-pin.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'sibling-pin', apiKey, siteUrl: 'https://markerless.convex.site' }));
+            resetConfigCache();
+            expect(() => resolveConfig()).toThrow(/not a valid pb_sk_ key/i);
+        });
+        it('treats an explicitly null apiKey as absent — JSON null means "no value"', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pin_key',
+                siteUrl: 'https://pinned.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'pinned-workspace', apiKey: null }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_pin_key');
+            expect(result.source).toBe('project');
+        });
+        it('leaves the ordinary pin-only path untouched — the widened claim test must not swallow it', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pin_only_key',
+                siteUrl: 'https://pinned-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            // Committed config.json + a pin whose profile stores its own URL: the pin path's normal
+            // shape (pb connect writes the URL into the profile). config.json's siteUrl routes nothing.
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://project-gateway.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'pin-only-workspace' }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_pin_only_key');
+            expect(result.siteUrl).toBe('https://pinned-profile.example.com');
+            expect(result.source).toBe('project');
+        });
+    });
+    describe('readLocalProjectConfig() — apiKey validity', () => {
+        it('withholds a malformed apiKey and flags it so diagnostics can name the fault', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'sk_bad_prefix_key', siteUrl: 'https://my-preview.convex.site' }));
+            const { readLocalProjectConfig } = await import('../lib/config.js');
+            const local = readLocalProjectConfig();
+            // Withheld from `apiKey` so it can never bind, but not reported as absent either.
+            expect(local?.apiKey).toBeUndefined();
+            expect(local?.apiKeyMalformed).toBe(true);
+        });
+        it('loads a valid apiKey with no malformed flag', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+            }));
+            const { readLocalProjectConfig } = await import('../lib/config.js');
+            const local = readLocalProjectConfig();
+            expect(local?.apiKey).toBe('pb_sk_preview_key_0123456789abcdef');
+            expect(local?.apiKeyMalformed).toBeUndefined();
+        });
+    });
+    describe('getPreviewBinding()', () => {
+        it('returns null when no config.local.json exists', async () => {
+            const { getPreviewBinding } = await import('../lib/config.js');
+            const result = getPreviewBinding();
+            expect(result).toBeNull();
+        });
+        it('returns null when config.local.json has no preview flag', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'some-workspace' }));
+            const { getPreviewBinding } = await import('../lib/config.js');
+            expect(getPreviewBinding()).toBeNull();
+        });
+        it('returns { workspaceName } when preview:true is set', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            const { getPreviewBinding } = await import('../lib/config.js');
+            const result = getPreviewBinding();
+            expect(result).not.toBeNull();
+            expect(result?.workspaceName).toBe('Preview Workspace');
+        });
+        it('returns { workspaceName: null } when preview:true but no workspaceName', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+            }));
+            const { getPreviewBinding } = await import('../lib/config.js');
+            const result = getPreviewBinding();
+            expect(result).not.toBeNull();
+            expect(result?.workspaceName).toBeNull();
+        });
+        it('returns null when preview:true but no apiKey (SF-3 mirror)', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            const { getPreviewBinding } = await import('../lib/config.js');
+            expect(getPreviewBinding()).toBeNull();
+        });
+        it('returns null when preview:true but no siteUrl (SF-3 mirror)', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            const { getPreviewBinding } = await import('../lib/config.js');
+            expect(getPreviewBinding()).toBeNull();
+        });
+        it('returns null when PRODUCTBRAIN_API_KEY env var overrides preview binding', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_real_chain_key';
+            const { getPreviewBinding } = await import('../lib/config.js');
+            expect(getPreviewBinding()).toBeNull();
+        });
+        it('returns null when config.local.json has invalid JSON (never throws)', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), '{ this is not valid json');
+            const stderrWrite = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+            const { getPreviewBinding } = await import('../lib/config.js');
+            expect(() => getPreviewBinding()).not.toThrow();
+            expect(getPreviewBinding()).toBeNull();
+            stderrWrite.mockRestore();
+        });
+    });
+    // ── TEN-4500 / TASK-640: a key travels only with the site URL stored or exported beside it ──
+    //
+    // `.productbrain/config.json` is committed, so a cloned repo controls its siteUrl. A key from
+    // anywhere else must never be sent there: with no URL of its own it goes to DEFAULT_SITE_URL.
+    describe('a key travels only with its own site URL (TEN-4500)', () => {
+        const DEFAULT = 'https://gateway.productbrain.io';
+        const COMMITTED = 'https://cloned-repo.example.com';
+        function commitProjectSiteUrl() {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: COMMITTED }));
+            return pbDir;
+        }
+        it('an exported key with no exported site URL is sent to DEFAULT_SITE_URL, never config.json siteUrl', () => {
+            process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+            commitProjectSiteUrl();
+            expect(getConfig().siteUrl).toBe(DEFAULT);
+        });
+        it('loadEnv and resolveConfig name the same site URL for the same inputs', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            const named = resolveNamedProfileConfig;
+            const active = resolveProfileConfig;
+            const cases = [
+                {
+                    name: 'env key, no env URL, committed config.json',
+                    arrange: () => {
+                        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+                        commitProjectSiteUrl();
+                    },
+                    expected: DEFAULT,
+                },
+                {
+                    name: 'env key with env URL, committed config.json',
+                    arrange: () => {
+                        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                        commitProjectSiteUrl();
+                    },
+                    expected: 'https://env.example.com',
+                },
+                {
+                    name: 'pinned profile with its own URL, exported URL, committed config.json',
+                    arrange: () => {
+                        named.mockReturnValue({ apiKey: 'pb_sk_pinned_key', siteUrl: 'https://pinned.example.com' });
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                        const pbDir = commitProjectSiteUrl();
+                        writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+                    },
+                    expected: 'https://pinned.example.com',
+                },
+                {
+                    name: 'pinned profile with no URL, committed config.json',
+                    arrange: () => {
+                        named.mockReturnValue({ apiKey: 'pb_sk_pinned_key' });
+                        const pbDir = commitProjectSiteUrl();
+                        writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+                    },
+                    expected: DEFAULT,
+                },
+                {
+                    name: 'unpinned profile with its own URL, exported URL',
+                    arrange: () => {
+                        active.mockReturnValue({ apiKey: 'pb_sk_profile_key', siteUrl: 'https://profile.example.com', profileName: 'p' });
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                    },
+                    expected: 'https://profile.example.com',
+                },
+                {
+                    name: 'unpinned profile with no URL, exported URL',
+                    arrange: () => {
+                        active.mockReturnValue({ apiKey: 'pb_sk_profile_key', profileName: 'p' });
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                    },
+                    expected: DEFAULT,
+                },
+            ];
+            const observed = cases.map(({ name, arrange }) => {
+                named.mockReset();
+                active.mockReset();
+                delete process.env.PRODUCTBRAIN_API_KEY;
+                delete process.env.CONVEX_SITE_URL;
+                rmSync(resolve(tempDir, '.productbrain'), { recursive: true, force: true });
+                arrange();
+                const resolved = resolveConfig().siteUrl;
+                resetConfigCache();
+                const loaded = getConfig().siteUrl;
+                return { name, resolved, loaded };
+            });
+            expect(observed).toEqual(cases.map(({ name, expected }) => ({ name, resolved: expected, loaded: expected })));
+        });
+    });
 });
 //# sourceMappingURL=config.test.js.map