@milesroxas/design-hub 0.1.2 → 0.2.0

package/dist/scripts/bootstrap.d.ts

@@ -29,6 +29,10 @@ export declare const spec: {
             readonly type: 'string';
             readonly description: 'Link this Vercel project and set the password gate env on it.';
         };
+        readonly team: {
+            readonly type: 'string';
+            readonly description: 'The Vercel team (its slug) the project lives in or is created in. Absent, the CLI’s current team.';
+        };
         readonly 'gate-password': {
             readonly type: 'string';
             readonly description: 'The share password (8+ characters). Given again, it rotates.';
@@ -40,6 +44,18 @@ export declare const spec: {
     };
     readonly output: '{ ok, node, port, install, typesafe, conductor?, vercel?, share?, review?, warnings }';
 };
+/**
+ * What `design-hub dev`, `open` and `preview` run first, so a fresh clone or
+ * worktree starts in any harness without a bootstrap: the harness's port when
+ * it gave one, else this folder's claim, else a free port claimed now. A .env
+ * copied from another checkout carries that checkout's claim, so this folder
+ * gets its own. `claimed` is true when the port is new.
+ */
+export declare function ensurePort(): {
+    port: number;
+    claimed: boolean;
+    warnings: string[];
+};
 /** The gate's values: the password given, kept, or made, and the secret kept or made. */
 export declare function gateValues(given: string | undefined, env: Record<string, string>): {
     password: string;

package/dist/scripts/bootstrap.js

@@ -8,11 +8,11 @@ import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { readEnv, writeEnv } from '../server/env.js';
+import { harnessPort, readEnv, writeEnv } from '../server/env.js';
 import { ROOT, TEMPLATES } from '../server/paths.js';
 import { CliError } from './lib/cli.js';
 import { holderOf, pickPort, readClaims, writeClaim } from './lib/ports.js';
-import { ENVIRONMENTS, envNames, linkedProject, STORE_ENV, setEnv, vercel, } from './lib/vercel.js';
+import { ENVIRONMENTS, envNames, linkedOrg, linkedProject, STORE_ENV, setEnv, vercel, } from './lib/vercel.js';
 export const spec = {
     name: 'bootstrap',
     summary: 'Set the project up on this machine, and optionally on Vercel. Safe to run again.',
@@ -26,6 +26,10 @@ export const spec = {
         conductor: { type: 'boolean', description: 'Write .conductor/settings.toml for Conductor workspaces.' },
         branch: { type: 'string', default: 'main', description: 'The branch Conductor workspaces land on.' },
         vercel: { type: 'string', description: 'Link this Vercel project and set the password gate env on it.' },
+        team: {
+            type: 'string',
+            description: 'The Vercel team (its slug) the project lives in or is created in. Absent, the CLI’s current team.',
+        },
         'gate-password': {
             type: 'string',
             description: 'The share password (8+ characters). Given again, it rotates.',
@@ -60,17 +64,16 @@ function checkNode() {
     return process.versions.node;
 }
 function choosePort(wanted, current, warnings) {
-    const conductor = process.env.CONDUCTOR_PORT;
-    if (conductor) {
-        // Conductor owns its workspace ports; they never go in the machine registry.
-        const port = Number(conductor);
-        const held = holderOf(port);
+    const harness = harnessPort();
+    if (harness) {
+        // The harness owns its worktree ports; they never go in the machine registry.
+        const held = holderOf(harness.port);
         if (held && held.cwd !== ROOT)
-            throw new CliError(`Conductor's port ${port} is taken.`, {
+            throw new CliError(`Port ${harness.port} from $${harness.from} is taken.`, {
                 holder: held,
                 fix: 'Stop that server; never use another port.',
             });
-        return port;
+        return harness.port;
     }
     const choice = pickPort({ dir: ROOT, wanted, current, claims: readClaims(), holder: holderOf });
     if (!choice.ok)
@@ -79,11 +82,57 @@ function choosePort(wanted, current, warnings) {
     writeClaim(ROOT, choice.port);
     return choice.port;
 }
-/** Keeps .claude/launch.json on the same port, when the project has one. */
+/** Settles the port and records it where the dev server and the preview tools read it. */
+function settlePort(wanted, current, warnings) {
+    const port = choosePort(wanted, current, warnings);
+    // A harness port belongs to that run; .env keeps the folder's own claim.
+    if (!harnessPort())
+        writeEnv(ROOT, { PORT: String(port) });
+    writeLaunch(port);
+    return port;
+}
+function envPort(env) {
+    return env.PORT ? Number(env.PORT) : undefined;
+}
+/**
+ * What `design-hub dev`, `open` and `preview` run first, so a fresh clone or
+ * worktree starts in any harness without a bootstrap: the harness's port when
+ * it gave one, else this folder's claim, else a free port claimed now. A .env
+ * copied from another checkout carries that checkout's claim, so this folder
+ * gets its own. `claimed` is true when the port is new.
+ */
+export function ensurePort() {
+    const warnings = [];
+    const harness = harnessPort();
+    if (harness)
+        return { port: harness.port, claimed: false, warnings };
+    const current = envPort(readEnv(ROOT));
+    if (current !== undefined && readClaims()[ROOT] === current)
+        return { port: current, claimed: false, warnings };
+    const port = settlePort(undefined, current, warnings);
+    return { port, claimed: port !== current, warnings };
+}
+/** Claude Code's preview servers for this folder: start the hub, or attach to one already running. */
+function defaultLaunch(port) {
+    return {
+        version: '0.0.1',
+        configurations: [
+            { name: 'prototypes', runtimeExecutable: 'pnpm', runtimeArgs: ['dev'], port },
+            { name: 'prototypes-attach', url: `http://localhost:${port}`, port },
+        ],
+    };
+}
+/**
+ * Keeps .claude/launch.json on this folder's port, writing it when missing.
+ * It is per folder like .env, and gitignored, so worktrees never conflict on it.
+ */
 function writeLaunch(port) {
     const file = join(ROOT, '.claude', 'launch.json');
-    if (!existsSync(file))
+    if (!existsSync(file)) {
+        mkdirSync(join(ROOT, '.claude'), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(defaultLaunch(port), null, 2)}\n`);
         return;
+    }
     const launch = JSON.parse(readFileSync(file, 'utf8'));
     for (const c of launch.configurations) {
         if ('port' in c)
@@ -120,13 +169,15 @@ function cli(args, input) {
         });
     return out.stdout;
 }
-function link(project, warnings) {
+function link(project, team, warnings) {
     const current = linkedProject(ROOT);
     if (current === project)
         return 'kept';
     if (current)
         warnings.push(`.vercel/project.json pointed at ${current}; relinked to ${project}.`);
-    cli(['link', '--yes', '--project', project]);
+    // A new project is created in the scope given; without one the CLI's current team wins, which
+    // is whichever team the user last switched to, not necessarily where this project belongs.
+    cli(['link', '--yes', '--project', project, ...(team ? ['--scope', team] : [])]);
     return 'ran';
 }
 /** Sets each value where it is missing; `rotate` names the ones given again, which replace what is there. */
@@ -169,7 +220,21 @@ function pullValues(target, names) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
-function provisionReview(project, warnings) {
+/** `--scope` for the commands that name the project instead of reading the link. */
+const scopeArgs = (team) => {
+    const scope = team ?? linkedOrg(ROOT);
+    return scope ? ['--scope', scope] : [];
+};
+/**
+ * Vercel Authentication is on for every new project on a team, and it sends each
+ * visitor to a Vercel login before the gate. The gate is the protection, so it goes
+ * off. Idempotent: disabling twice is fine.
+ */
+function protection(project, team) {
+    cli(['project', 'protection', 'disable', project, '--sso', ...scopeArgs(team)]);
+    return 'off';
+}
+function provisionReview(project, team, warnings) {
     const names = envNames(ROOT, 'production');
     let store = 'kept';
     if (!names || !STORE_ENV.every((n) => names.has(n))) {
@@ -186,6 +251,8 @@ function provisionReview(project, warnings) {
             '-e',
             'development',
             '--no-env-pull',
+            // Unlike env and deploy, this command ignores the project link and takes the CLI's current team.
+            ...scopeArgs(team),
         ]);
         if (out?.status !== 0)
             throw new CliError('Could not add the Upstash for Redis store.', {
@@ -226,7 +293,7 @@ export function gateValues(given, env) {
     return { password, secret, rotated: given !== undefined && given !== env.GATE_PASSWORD };
 }
 function setUpVercel(project, flags, env, typesafeKey, warnings) {
-    const linked = link(project, warnings);
+    const linked = link(project, flags.team, warnings);
     const { password, secret, rotated } = gateValues(flags['gate-password'], env);
     writeEnv(ROOT, { GATE_PASSWORD: password, GATE_SECRET: secret });
     const values = { GATE_PASSWORD: password, GATE_SECRET: secret };
@@ -236,13 +303,18 @@ function setUpVercel(project, flags, env, typesafeKey, warnings) {
     if (rotated)
         warnings.push('The password changed: every visitor signs in again.');
     const result = {
-        vercel: { project, linked, env: ensureEnv(values, new Set(rotated ? ['GATE_PASSWORD'] : [])) },
+        vercel: {
+            project,
+            linked,
+            protection: protection(project, flags.team),
+            env: ensureEnv(values, new Set(rotated ? ['GATE_PASSWORD'] : [])),
+        },
         share: { password },
     };
     if (!flags.review)
         return result;
     warnings.push('Redeploy so the new env reaches the site; then design-hub people invite --name "<you>" --role editor.');
-    return { ...result, review: provisionReview(project, warnings) };
+    return { ...result, review: provisionReview(project, flags.team, warnings) };
 }
 function envIgnored(warnings) {
     try {
@@ -251,6 +323,12 @@ function envIgnored(warnings) {
     catch {
         warnings.push('.env is not gitignored; it holds secrets. Add `.env` to .gitignore before committing.');
     }
+    // Projects made before 0.2.0 committed it; each worktree then rewrites a tracked file.
+    const tracked = spawnSync('git', ['-C', ROOT, 'ls-files', '--error-unmatch', '.claude/launch.json'], {
+        stdio: 'ignore',
+    });
+    if (tracked.status === 0)
+        warnings.push('.claude/launch.json is committed but holds this folder’s port. Run `git rm --cached .claude/launch.json` and add it to .gitignore.');
 }
 export function main({ flags }) {
     if (flags.review && !flags.vercel)
@@ -258,9 +336,7 @@ export function main({ flags }) {
     const warnings = [];
     const node = checkNode();
     const env = readEnv(ROOT);
-    const port = choosePort(flags.port, env.PORT ? Number(env.PORT) : undefined, warnings);
-    writeEnv(ROOT, { PORT: String(port) });
-    writeLaunch(port);
+    const port = settlePort(flags.port, envPort(env), warnings);
     const installed = install(flags['no-install']);
     const typesafeKey = typesafe(flags['typesafe-key'], env.TYPESAFE_API_KEY);
     const result = {

package/dist/scripts/dev.d.ts

@@ -2,7 +2,7 @@
 import type { Args } from './lib/cli.ts';
 export declare const spec: {
     readonly name: 'dev';
-    readonly summary: 'Serve the hub, every prototype and the review panel on the port in .env.';
+    readonly summary: "Serve the hub, every prototype and the review panel: on $DESIGN_HUB_PORT or $CONDUCTOR_PORT when a harness sets one, else this folder's port in .env, claimed on first run.";
     readonly flags: {
         readonly open: {
             readonly type: 'boolean';
@@ -19,7 +19,7 @@ export declare const buildSpec: {
 };
 export declare const previewSpec: {
     readonly name: 'preview';
-    readonly summary: 'Serve dist/ as built, on the port in .env.';
+    readonly summary: 'Serve dist/ as built, on the same port as `design-hub dev`.';
     readonly flags: {};
     readonly output: "Vite's own log; the command runs until stopped.";
 };

package/dist/scripts/dev.js

@@ -8,9 +8,10 @@ import { createServer, build as viteBuild, preview as vitePreview } from 'vite';
 import { devPort, readEnv } from '../server/env.js';
 import { ROOT } from '../server/paths.js';
 import { hubConfig } from '../vite/plugin.js';
+import { ensurePort } from './bootstrap.js';
 export const spec = {
     name: 'dev',
-    summary: 'Serve the hub, every prototype and the review panel on the port in .env.',
+    summary: "Serve the hub, every prototype and the review panel: on $DESIGN_HUB_PORT or $CONDUCTOR_PORT when a harness sets one, else this folder's port in .env, claimed on first run.",
     flags: { open: { type: 'boolean', description: 'Open the browser once the server is up.' } },
     output: "Vite's own log; the command runs until stopped.",
 };
@@ -22,7 +23,7 @@ export const buildSpec = {
 };
 export const previewSpec = {
     name: 'preview',
-    summary: 'Serve dist/ as built, on the port in .env.',
+    summary: 'Serve dist/ as built, on the same port as `design-hub dev`.',
     flags: {},
     output: "Vite's own log; the command runs until stopped.",
 };
@@ -42,7 +43,16 @@ function openBrowser(url) {
         .on('error', () => { })
         .unref();
 }
+/** A port before Vite starts; a new claim is said on stderr, beside Vite's own log. */
+function settlePort() {
+    const { port, claimed, warnings } = ensurePort();
+    for (const warning of warnings)
+        console.error(`design-hub: ${warning}`);
+    if (claimed)
+        console.error(`design-hub: claimed port ${port} for this folder and wrote it to .env.`);
+}
 async function serve(open) {
+    settlePort();
     const server = await createServer(hubConfig({ root: ROOT }, 'serve'));
     await server.listen();
     server.printUrls();
@@ -69,6 +79,7 @@ export async function build() {
     }
 }
 export async function previewBuilt() {
+    settlePort();
     const server = await vitePreview(hubConfig({ root: ROOT }, 'build'));
     server.printUrls();
     await new Promise(() => { });

package/dist/scripts/lib/vercel.d.ts

@@ -8,7 +8,9 @@ export type Run = {
     stderr: string;
 };
 export declare function vercel(cwd: string, args: string[], input?: string): Run | null;
-export declare function linkedProject(cwd: string): string | null;
+export declare const linkedProject: (cwd: string) => string | null;
+/** The team the linked project belongs to. The commands that take a project name instead of the link need it as `--scope`. */
+export declare const linkedOrg: (cwd: string) => string | null;
 /** The variable names set for a target, read from `vercel env ls`'s table. */
 export declare function envNames(cwd: string, target: Target): Set<string> | null;
 /** Sets one variable for one target; `force` replaces a value that is already there. */

package/dist/scripts/lib/vercel.js

@@ -15,17 +15,20 @@ export function vercel(cwd, args, input) {
         return null;
     return { status: out.status ?? 1, stdout: out.stdout ?? '', stderr: out.stderr ?? '' };
 }
-export function linkedProject(cwd) {
+function readLink(cwd) {
     const file = join(cwd, '.vercel', 'project.json');
     if (!existsSync(file))
         return null;
     try {
-        return JSON.parse(readFileSync(file, 'utf8')).projectName ?? null;
+        return JSON.parse(readFileSync(file, 'utf8'));
     }
     catch {
         return null;
     }
 }
+export const linkedProject = (cwd) => readLink(cwd)?.projectName ?? null;
+/** The team the linked project belongs to. The commands that take a project name instead of the link need it as `--scope`. */
+export const linkedOrg = (cwd) => readLink(cwd)?.orgId ?? null;
 /** The variable names set for a target, read from `vercel env ls`'s table. */
 export function envNames(cwd, target) {
     const out = vercel(cwd, ['env', 'ls', target]);

package/dist/scripts/skills.js

@@ -15,12 +15,16 @@ export const spec = {
     output: '{ ok, installed: [name], into }',
 };
 const GLOBAL_ONLY = new Set(['miles-design-hub']);
+/** Skills the package no longer ships, removed from a project on update. miles-conductor became miles-worktrees in 0.2.0. */
+const RETIRED = ['miles-conductor'];
 export function installSkills(from = PACKAGE_SKILLS, into = SKILLS) {
     const names = readdirSync(from, { withFileTypes: true })
         .filter((d) => d.isDirectory() && d.name.startsWith('miles-') && !GLOBAL_ONLY.has(d.name))
         .map((d) => d.name)
         .sort();
     mkdirSync(into, { recursive: true });
+    for (const name of RETIRED)
+        rmSync(join(into, name), { recursive: true, force: true });
     for (const name of names) {
         const dest = join(into, name);
         if (existsSync(dest))

package/dist/server/env.d.ts

@@ -1,8 +1,20 @@
 export declare function readEnv(dir: string): Record<string, string>;
 export declare function writeEnv(dir: string, updates: Record<string, string>): void;
+/** The variables a harness (Conductor, T3 Code, a script) may hand a worktree its port in, first wins. */
+declare const HARNESS_PORT_VARS: readonly ['DESIGN_HUB_PORT', 'CONDUCTOR_PORT'];
 /**
- * The dev server's port. Inside a Conductor workspace, Conductor's own port
- * wins, because its Open button always points there; everywhere else it is
- * the PORT that `pnpm bootstrap` wrote to .env.
+ * The port a harness gave this process, and the variable it came in. A
+ * harness owns these ports: they never enter the machine registry. A bare
+ * `PORT` is not one: shells and other tools export it for their own servers.
+ */
+export declare function harnessPort(processEnv?: Record<string, string | undefined>): {
+    port: number;
+    from: (typeof HARNESS_PORT_VARS)[number];
+} | null;
+/**
+ * The dev server's port: the harness's when one gave it, because its Open
+ * button points there; else the PORT in .env, which `design-hub dev` and
+ * `design-hub bootstrap` claim for this folder.
  */
 export declare function devPort(fileEnv: Record<string, string>, processEnv?: Record<string, string | undefined>): number | undefined;
+export {};

package/dist/server/env.js

@@ -46,12 +46,30 @@ export function writeEnv(dir, updates) {
     const text = next.join('\n').replace(/\n*$/, '\n');
     writeFileSync(file, text, { mode: 0o600 });
 }
+/** The variables a harness (Conductor, T3 Code, a script) may hand a worktree its port in, first wins. */
+const HARNESS_PORT_VARS = ['DESIGN_HUB_PORT', 'CONDUCTOR_PORT'];
+function asPort(value) {
+    const port = Number(value);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+}
 /**
- * The dev server's port. Inside a Conductor workspace, Conductor's own port
- * wins, because its Open button always points there; everywhere else it is
- * the PORT that `pnpm bootstrap` wrote to .env.
+ * The port a harness gave this process, and the variable it came in. A
+ * harness owns these ports: they never enter the machine registry. A bare
+ * `PORT` is not one: shells and other tools export it for their own servers.
+ */
+export function harnessPort(processEnv = process.env) {
+    for (const from of HARNESS_PORT_VARS) {
+        const port = asPort(processEnv[from]);
+        if (port !== undefined)
+            return { port, from };
+    }
+    return null;
+}
+/**
+ * The dev server's port: the harness's when one gave it, because its Open
+ * button points there; else the PORT in .env, which `design-hub dev` and
+ * `design-hub bootstrap` claim for this folder.
  */
 export function devPort(fileEnv, processEnv = process.env) {
-    const port = Number(processEnv.CONDUCTOR_PORT || fileEnv.PORT);
-    return Number.isInteger(port) && port > 0 ? port : undefined;
+    return harnessPort(processEnv)?.port ?? asPort(fileEnv.PORT);
 }

package/dist/vite/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { InlineConfig, PluginOption } from 'vite';
+import { type InlineConfig, type PluginOption } from 'vite';
 export type HubOptions = {
     /** The project: the folder with prototypes/, kit/ and docs/. */
     root: string;
@@ -7,8 +7,8 @@ export type HubOptions = {
 export declare function designHub({ root }: HubOptions): PluginOption[];
 /**
  * The whole config `design-hub dev` and `design-hub build` run on. One port per
- * project: Conductor's per-workspace port when it runs us, else the PORT
- * `design-hub bootstrap` wrote to .env. strictPort refuses a taken port rather
+ * folder: the harness's ($DESIGN_HUB_PORT, $CONDUCTOR_PORT) when one runs us,
+ * else the PORT `design-hub dev` or `bootstrap` claimed in .env. strictPort refuses a taken port rather
  * than drifting to the next one, because a fallback silently serves the wrong
  * project. A build needs no port, so Vercel builds without a .env.
  */

package/dist/vite/plugin.js

@@ -9,6 +9,7 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import react from '@vitejs/plugin-react';
+import { searchForWorkspaceRoot } from 'vite';
 import { devReview } from '../server/dev.js';
 import { devPort, readEnv } from '../server/env.js';
 import { PACKAGE, PACKAGE_KIT, SHELL } from '../server/paths.js';
@@ -61,15 +62,15 @@ export function designHub({ root }) {
 }
 /**
  * The whole config `design-hub dev` and `design-hub build` run on. One port per
- * project: Conductor's per-workspace port when it runs us, else the PORT
- * `design-hub bootstrap` wrote to .env. strictPort refuses a taken port rather
+ * folder: the harness's ($DESIGN_HUB_PORT, $CONDUCTOR_PORT) when one runs us,
+ * else the PORT `design-hub dev` or `bootstrap` claimed in .env. strictPort refuses a taken port rather
  * than drifting to the next one, because a fallback silently serves the wrong
  * project. A build needs no port, so Vercel builds without a .env.
  */
 export function hubConfig({ root }, command) {
     const port = devPort(readEnv(root));
     if (command === 'serve' && port === undefined)
-        throw new Error('PORT is not set. Run `design-hub bootstrap` once to pick a free port and write it to .env.');
+        throw new Error('PORT is not set. `design-hub dev` claims one; a config of your own runs `design-hub bootstrap` first.');
     return {
         configFile: false,
         root: SHELL,
@@ -79,7 +80,9 @@ export function hubConfig({ root }, command) {
         plugins: designHub({ root }),
         resolve: { dedupe: ['react', 'react-dom'] },
         optimizeDeps: { entries: [join(SHELL, 'index.html'), join(root, 'prototypes', '*', 'index.tsx')] },
-        server: { port, strictPort: true, fs: { allow: [root, PACKAGE] } },
+        // A linked package (a checkout of this repo) keeps its dependencies in
+        // the checkout's node_modules, outside both; its workspace root covers them.
+        server: { port, strictPort: true, fs: { allow: [root, PACKAGE, searchForWorkspaceRoot(PACKAGE)] } },
         preview: port === undefined ? undefined : { port, strictPort: true },
         build: { outDir: join(root, 'dist'), emptyOutDir: true },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milesroxas/design-hub",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The Design Hub product: the hub that lists and serves prototypes, the review panel and its API, the password gate, the kit, and the design-hub CLI. A project installs it and keeps only its prototypes, kit materials and docs.",
   "license": "MIT",
   "repository": {

package/skills/miles-deploy/SKILL.md

@@ -34,11 +34,12 @@ Never send the link with a failed step, and never skip one with `--skip` without
 1. The user signs in once, in their own terminal: `vercel login`. It is interactive; never run it for them.
 2. From the project root:
    ```bash
-   pnpm bootstrap --vercel <project-name>
+   pnpm bootstrap --vercel <project-name> --team <team-slug>
    ```
-   It links the project, writes `GATE_PASSWORD` (12 readable characters, or `--gate-password <word>`) and a fresh `GATE_SECRET` to `.env` and to Production and Preview, and prints the password in `share.password`. A second run keeps what is set.
+   `--team` is the Vercel team the project is created in (`vercel teams ls` lists them); without it the CLI's current team wins, which is often not the one the user means. It links the project, writes `GATE_PASSWORD` (12 readable characters, or `--gate-password <word>`) and a fresh `GATE_SECRET` to `.env` and to Production and Preview, and prints the password in `share.password`. A second run keeps what is set.
 3. `pnpm preflight`, then push `main` (or `vercel --prod` from the project root).
-4. The handover message, in one message: the URL, the password, which prototype to open (the sprint's slug), the walkthrough at `/guide/<feature>/`, and that Controls is the round button at the top of the page. A reviewer who is not told about Controls reviews one state. Never send `GATE_SECRET`.
+4. On a Pro team Vercel turns Vercel Authentication on for every new project, which sends each visitor to a Vercel login before the gate. Turn it off for Production once: Project Settings, Deployment Protection, Vercel Authentication, set to Only Preview Deployments or Disabled. The hub's gate is the protection. Test by opening the production URL in a private window: the password page must appear, not vercel.com.
+5. The handover message, in one message: the URL, the password, which prototype to open (the sprint's slug), the walkthrough at `/guide/<feature>/`, and that Controls is the round button at the top of the page. A reviewer who is not told about Controls reviews one state. Never send `GATE_SECRET`.
 
 ## Comments
 

package/skills/miles-worktrees/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: miles-worktrees
+description: "Run this project in more than one checkout at once: git worktrees, T3 Code, Conductor, Claude Code, Cursor, or any harness that gives each agent its own folder. A port per folder, the harness port variables, the machine port registry, Conductor's settings file, and what checkouts never share. Load when the user mentions worktrees, workspaces, parallel agents, a harness, or a dev server that answers with the wrong project. Triggers on: worktree, worktrees, workspace, workspaces, parallel agents, Conductor, T3 Code, CONDUCTOR_PORT, DESIGN_HUB_PORT, port taken, port collision, wrong site, ports.json, port registry."
+---
+
+# Worktrees and parallel agents
+
+Every checkout of this project is its own folder with its own dev server and its own port: the main clone, each `git worktree`, each harness workspace. Two folders on one port is the failure everything here prevents. The second server refuses to start, or the browser shows the other folder's prototypes with no error.
+
+## Start a new checkout
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Nothing else is needed, in any harness. On its first start `pnpm dev` claims a free port for the folder and writes it to `.env` and `.claude/launch.json`; later starts reuse it. Both files are gitignored because they belong to the folder, so worktrees never conflict on them. `pnpm bootstrap` remains the full setup (TypeSafe key, Vercel) but is not needed to run.
+
+Some harnesses copy `.env` from the main checkout. That is fine: the copied `PORT` is claimed by the other folder, so this folder gets its own and the dev server says so on stderr. The copied `GATE_*` and `TYPESAFE_API_KEY` keep working.
+
+## Ports
+
+```
+Which port does the dev server use?
+├── $DESIGN_HUB_PORT set → that port. Any harness or script that hands out ports sets this.
+├── $CONDUCTOR_PORT set  → that port. Conductor sets it per workspace.
+└── neither              → this folder's PORT in .env, claimed in the machine registry
+                           (~/.config/design-hub/ports.json; $DESIGN_HUB_PORTS moves it).
+                           A port another folder claims is skipped, running or not.
+```
+
+A harness port never enters `.env` or the registry: the harness owns that range. A bare `$PORT` is ignored on purpose. Why: shells and other tools export it for their own servers, and the hub would start on it.
+
+A claim lasts as long as its folder. A deleted worktree's claim is dropped the next time any folder claims a port.
+
+On a taken port, `pnpm dev` refuses to start (`strictPort`) and `pnpm bootstrap` names the process and its folder. Then:
+
+1. Never pass another port. Why: the harness's Open button, `.env` and `.claude/launch.json` keep pointing at the configured one, so a second port is a server nobody opens.
+2. Find the holder: `lsof -nP -iTCP:<port> -sTCP:LISTEN`, then `lsof -a -p <pid> -d cwd` for its folder.
+3. An orphaned server of this folder: stop it. A server of another folder or project: ask the user before stopping it.
+
+## Harnesses
+
+- **T3 Code, Claude Code worktrees, Cursor, plain `git worktree add`.** Nothing to configure. A harness setup step needs only `pnpm install`. A harness that starts the server itself and picks ports sets `DESIGN_HUB_PORT`.
+- **Conductor.**
+  1. From the project root: `pnpm bootstrap --conductor --branch <integration branch>`. It writes `.conductor/settings.toml`: setup installs and bootstraps each new workspace, run starts `pnpm dev`, and the preview URL is the workspace's `$CONDUCTOR_PORT`. A file the user has edited is kept, and the JSON warns that it differs.
+  2. Commit `.conductor/settings.toml`. `.conductor/settings.local.toml` is gitignored, for one person's overrides.
+  3. Tell the user to add the repository in Conductor and set its base branch to the same branch. Conductor keeps that setting in its app only, so nothing in the repo can set or check it.
+
+  Conductor never checks that its port is free. Why it matters: a server orphaned in another project can hold it, and the Open button then shows that project. The bootstrap in the workspace's setup fails loudly when that happens.
+
+## Nothing shared
+
+Checkouts share no database and no container. The review store's local copy is a file in each checkout's `.design-hub/`, and the deployed store is remote, so two checkouts never see each other's local comments.
+
+When the user keeps their own record of which project owns which port, add this folder's port to it too.

package/skills/miles-conductor/SKILL.md

@@ -1,37 +0,0 @@
----
-name: miles-conductor
-description: "Run this project in Conductor (conductor.build) workspaces: the settings file, a port per workspace, and the machine port registry that keeps projects off each other's ports. Load when the user mentions Conductor, workspaces, parallel agents, or a dev server that answers with the wrong project. Triggers on: Conductor, workspace, workspaces, CONDUCTOR_PORT, parallel agents, port taken, port collision, wrong site, ports.json, port registry."
----
-
-# Conductor
-
-Conductor gives each workspace its own `$CONDUCTOR_PORT`, but never checks that the port is free. A dev server orphaned in another project can still hold it, and the workspace's Open button then shows the other project with no error. Everything here exists to make that failure loud.
-
-## Set up
-
-1. From the project root: `pnpm bootstrap --conductor --branch <integration branch>`. It writes `.conductor/settings.toml`: setup runs `pnpm bootstrap` in each new workspace, run starts `pnpm dev`, and the preview URL is the workspace's port. A file the user has edited is kept, and the JSON warns that it differs.
-2. Commit `.conductor/settings.toml`. `.conductor/settings.local.toml` is gitignored, for one person's overrides.
-3. Tell the user to add the repository in Conductor and set its base branch to the same branch. Conductor keeps that setting in its app only, so nothing in the repo can set or check it.
-
-## Ports
-
-```
-Where is the dev server running?
-├── A Conductor workspace → $CONDUCTOR_PORT, always. The dev server reads it before .env.
-│                           It never enters the machine registry: Conductor owns that range.
-└── A main checkout       → the port pnpm bootstrap picked, written to .env and claimed in
-                            ~/.config/design-hub/ports.json ($DESIGN_HUB_PORTS overrides the path).
-                            Bootstrap skips every port another project claims, running or not.
-```
-
-On a taken port, `pnpm dev` refuses to start (`strictPort`) and `pnpm bootstrap` names the process and its folder. Then:
-
-1. Never pass another port. Why: the Open button and `.claude/launch.json` keep pointing at the configured one, so a second port is a server nobody opens.
-2. Find the holder: `lsof -nP -iTCP:<port> -sTCP:LISTEN`, then `lsof -a -p <pid> -d cwd` for its folder.
-3. An orphaned server of this project: stop it. A server of another project: ask the user before stopping it.
-
-When the user keeps their own record of which project owns which port, add this project's port to it too.
-
-## Nothing shared
-
-Workspaces share no database and no container. The review store's local copy is a file in each checkout's `.design-hub/`, and the deployed store is remote, so two workspaces never see each other's local comments.