instabox 0.4.2 → 0.5.0

package/README.md

@@ -1,19 +1,22 @@
 # instabox (npm)
 
 ```
-npx instabox@latest
+npx instabox@latest      # sign in, install the CLI and the agent skills
+npx instabox@latest sh   # the same, then start a new box and SSH into it
 ```
 
-Signs you in to instabox in your browser (first run only; Google by default, `--github` for GitHub), lets you pick one of your boxes or start a new one (no boxes yet: a new one, no question; `--box NAME` skips the question), installs the `instabox` CLI already signed in or updates an out-of-date one (macOS/Linux; skip with `--no-cli`), installs or updates the agent skills from [`../skills`](../skills) in `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and drops you into the box over SSH. `npx instabox@latest sh` does the same.
+`npx instabox@latest` signs you in to instabox in your browser (first run only; confirm its current Instabox account or choose another), installs the `instabox` CLI already signed in or updates an out-of-date one (macOS/Linux; skip with `--no-cli`), installs or updates the agent skills from [`../skills`](../skills) in `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and prints the next steps. It does not touch your boxes.
 
-Google and GitHub sign-ins are separate instabox accounts, each with its own boxes. The CLI's own `instabox login` signs in with GitHub by default (`--provider google` for Google), so when the CLI needs a new sign-in, `instabox login --provider google` keeps you in the account you used here with Google.
+`npx instabox@latest sh` does all that, then starts a new box (`box-<hex>`) and drops you into it over SSH, no questions. Run by an agent (no terminal), it starts the box and prints `instabox ssh <box> -- <command>` instead of opening a shell. At the box limit it starts nothing and lists your boxes, to remove one (`instabox rm <box>`) or open one (`instabox ssh <box>`).
+
+A GitHub and a Google sign-in are separate instabox accounts, each with its own boxes. Both this entry point and `instabox login` let the browser confirm the account. Explicit `--github` or `--google` starts that provider directly, as does `instabox login --provider github|google`.
 
 Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox)): `npx instabox@latest ls` runs `instabox ls`, installing the CLI first if it is missing.
 
 ## How it works
 
 - `bin/instabox.mjs` runs instabox's loopback sign-in (RFC 8252 + PKCE) and saves the tokens where the CLI keeps its own, `~/.config/instabox/credentials.json`, so both are signed in at once. There is one copy on purpose: the server rotates refresh tokens and ends the session when a rotated one comes back.
-- The box list is `instabox ls`: running boxes first, then newest. A suspended or stopped box is resumed or started; its settings (timeout, auto-suspend) are left alone. Without a terminal to ask (an agent running it), it lists the boxes, installs the CLI and skills, and stops; `--box NAME` or `instabox create` takes it from there.
+- `sh` always starts a new box, with no timeout and no idle auto-suspend of its own. An existing box is entered with the CLI: `instabox ssh <box>`.
 - An installed CLI is checked against what the server's `/install.sh` would install: the binary's sha256 against the server's `/dl/SHA256SUMS` (release builds are named after a commit, so their versions do not sort). One the server no longer serves is replaced in place through the same installer; a development build (`instabox dev`, or `-dirty`) is left alone with a one-line notice of the install command.
 - Skills are written only over copies marked `installed-by: instabox`; the output says which were installed, updated, already up to date, or kept because they are the user's own.
 - The bin is also called `instabox`, so `lib/cli.mjs` finds the real CLI the way the insta CLI does: PATH without `node_modules` dirs and without links back to this script, then the installer's own targets.
@@ -26,7 +29,7 @@ npm ci
 npm test
 npm run format:check
 npm pack            # copies ../skills, then builds instabox-<version>.tgz
-npx --package=./instabox-0.4.2.tgz instabox --help
+npx --package=./instabox-0.4.3.tgz instabox --help
 ```
 
 `INSTABOX_API_URL` points it at another instabox server.

package/bin/instabox.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// npx instabox@latest: box + CLI + skills + SSH in; any other command goes to the instabox CLI.
+// npx instabox@latest: sign in + CLI + skills; `sh` also starts a new box and SSHes in. Anything else goes to the CLI.
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import {
@@ -16,11 +16,10 @@ import {
 import http from 'node:http';
 import { tmpdir, homedir } from 'node:os';
 import { join, dirname } from 'node:path';
-import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import { createClient } from '../lib/api.mjs';
-import { orderBoxes, parseChoice } from '../lib/boxes.mjs';
-import { boxFlag, checkCli, findCli, installCli, installCommand, isOnboarding, real, runCli } from '../lib/cli.mjs';
+import { orderBoxes } from '../lib/boxes.mjs';
+import { checkCli, findCli, installCli, installCommand, isOnboarding, real, runCli } from '../lib/cli.mjs';
 import { callbackHandler } from '../lib/login.mjs';
 import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
 
@@ -34,7 +33,9 @@ const API = (
 const IMAGE = process.env.INSTABOX_IMAGE || 'universal';
 // SSH certificate lifetime for a box with no timeout of its own.
 const CERT_MIN = 120;
-const PROVIDER = process.argv.includes('--github') ? 'github' : 'google';
+// With no provider selected, the browser confirms its existing Instabox account
+// or offers sign-in. Explicit flags still start the chosen provider directly.
+const PROVIDER = process.argv.includes('--google') ? 'google' : process.argv.includes('--github') ? 'github' : '';
 const bold = (s) => (process.stdout.isTTY ? `\x1b[1m${s}\x1b[0m` : s);
 const dim = (s) => (process.stdout.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
 const green = (s) => (process.stdout.isTTY ? `\x1b[32m${s}\x1b[0m` : s);
@@ -50,11 +51,10 @@ function usage() {
   console.log(`
   ${bold('instabox')}: a cloud box in seconds
 
-  npx instabox@latest               sign in (first time), pick one of your boxes or start a new
-                                    one, SSH into it, and install the instabox CLI and agent skills
-      --box NAME                    go straight to that box instead of asking
-      --github                      sign in with GitHub instead of Google (a separate account;
-                                    instabox login uses GitHub, --provider google for Google)
+  npx instabox@latest               sign in (first time), install the instabox CLI and agent skills
+  npx instabox@latest sh            the same, then start a new box and SSH into it
+      --github, --google            sign in directly with that provider instead of confirming
+                                    the browser's current Instabox account
       --no-cli                      do not install or update the instabox CLI
       --no-skills                   do not install the instabox agent skills
   npx instabox@latest <command>     run an instabox CLI command (instabox help lists them)
@@ -195,51 +195,17 @@ async function waitOp(op) {
   return op;
 }
 
-// The box to enter, null for a new one, or { listed: true } when there is no terminal to ask
-// which one (an agent running it): the boxes are listed and nothing is picked for it.
-async function chooseBox() {
-  const { machines = [] } = await client
-    .call('GET', '/v1/machines?limit=100')
-    .catch((e) => die(`could not list your boxes: ${e.message}`));
+// At the box limit: say so, and show the boxes there are to remove or open instead.
+async function quotaFull(err) {
+  const { machines = [] } = await client.call('GET', '/v1/machines?limit=100').catch(() => ({}));
   const boxes = orderBoxes(machines);
-  const wanted = boxFlag(process.argv.slice(2));
-  if (wanted) return boxes.find((b) => b.name === wanted || b.id === wanted) || die(`you have no box named ${wanted}`);
-  if (!boxes.length) return null;
-  const ask = process.stdin.isTTY && process.stdout.isTTY;
-  const w = Math.max(...boxes.map((b) => b.name.length));
-  console.log(`\n  ${bold('Your boxes')}`);
-  boxes.forEach((b, i) =>
-    console.log(
-      `    ${ask ? `${i + 1}) ` : ''}${b.name.padEnd(w)}  ${b.state.padEnd(9)} ${dim(`${b.template?.id || ''}  created ${new Date(b.createdAt).toLocaleString()}`)}`,
-    ),
-  );
-  if (!ask) return { listed: true };
-  console.log(`    ${boxes.length + 1}) ${green('+ new box')}`);
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    for (;;) {
-      const i = parseChoice(await rl.question('  Enter a box [1]: '), boxes.length);
-      if (i !== null) return i === boxes.length ? null : boxes[i];
-    }
-  } finally {
-    rl.close();
-  }
-}
-
-// Wakes a suspended or stopped box and leaves its settings (timeout, auto-suspend) alone.
-async function enterBox(id) {
-  const path = '/v1/machines/' + enc(id);
-  let m = await client.call('GET', path);
-  if (m.operationId) {
-    await waitOp(await client.call('GET', '/v1/operations/' + enc(m.operationId)));
-    m = await client.call('GET', path);
-  }
-  if (m.state === 'suspended' || m.state === 'stopped') {
-    await waitOp(await client.call('POST', `${path}/${m.state === 'suspended' ? 'resume' : 'start'}`));
-    return { id: m.id, resumed: true };
+  console.log(`\n  ${bold('Box limit reached')} ${dim(`(${err.message})`)}`);
+  if (boxes.length) {
+    const w = Math.max(...boxes.map((b) => b.name.length));
+    for (const b of boxes) console.log(`    ${b.name.padEnd(w)}  ${b.state}`);
   }
-  if (m.state !== 'running') throw new Error(`box ${m.name} is ${m.state}`);
-  return { id: m.id, reused: true };
+  console.log(`\n  Remove one with ${bold('instabox rm <box>')}, or open one with ${bold('instabox ssh <box>')}.\n`);
+  process.exit(1);
 }
 
 async function newBox() {
@@ -253,7 +219,7 @@ async function newBox() {
   if (img) body.imageId = img.id;
   else body.templateId = IMAGE;
   const op = await waitOp(await client.call('POST', '/v1/machines', body));
-  return { id: op.machineId, reused: false };
+  return { id: op.machineId, name: body.name };
 }
 
 // Runs while the box starts; never fatal. Returns a line to print, or null.
@@ -293,8 +259,19 @@ async function ensureCli() {
   );
 }
 
-// Agent skills shipped in this package (skills/<name>/SKILL.md) into the folders coding agents
-// read. Overwrites only copies we installed earlier (marked `installed-by: instabox`).
+// A skill directory's files, relative to it, sorted.
+function skillFiles(dir, rel = '') {
+  return readdirSync(join(dir, rel), { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((e) => {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      return e.isDirectory() ? skillFiles(dir, r) : e.isFile() ? [r] : [];
+    });
+}
+
+// Agent skills shipped in this package (skills/<name>/SKILL.md, with any scripts beside it) into
+// the folders coding agents read. Overwrites only copies we installed earlier (marked
+// `installed-by: instabox`).
 function installSkills() {
   if (process.argv.includes('--no-skills')) return null;
   const src = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
@@ -313,7 +290,6 @@ function installSkills() {
     for (const n of names) {
       const dest = join(root, n, 'SKILL.md');
       try {
-        const body = readFileSync(join(src, n, 'SKILL.md'), 'utf8');
         let what = 'installed';
         if (existsSync(dest)) {
           const old = readFileSync(dest, 'utf8');
@@ -321,11 +297,16 @@ function installSkills() {
             kept.add(n);
             continue;
           }
-          what = old === body ? 'unchanged' : 'updated';
+          what = 'unchanged';
         }
-        if (what !== 'unchanged') {
-          mkdirSync(join(root, n), { recursive: true });
-          writeFileSync(dest, body);
+        // SKILL.md and whatever else the skill ships (scripts/...).
+        for (const f of skillFiles(join(src, n))) {
+          const body = readFileSync(join(src, n, f));
+          const to = join(root, n, f);
+          if (existsSync(to) && readFileSync(to).equals(body)) continue;
+          if (what === 'unchanged') what = 'updated';
+          mkdirSync(dirname(to), { recursive: true });
+          writeFileSync(to, body);
         }
         if (rank[what] > (rank[outcome.get(n)] ?? -1)) outcome.set(n, what);
       } catch {}
@@ -348,7 +329,16 @@ async function reportInstalls(cli) {
   if (skillsLine) console.log(`  ${green('✓')} ${skillsLine}`);
 }
 
-async function sh() {
+// The commands to run next, one per line, descriptions lined up.
+function nextSteps(rows) {
+  const w = Math.max(...rows.map(([cmd]) => cmd.length));
+  console.log(`\n  ${bold('Next steps')}`);
+  for (const [cmd, what] of rows) console.log(`    ${cmd.padEnd(w)}  ${dim(what)}`);
+  console.log();
+}
+
+// Sign-in, the CLI and the skills; with `sh` (wantBox) also a new box and an SSH session in it.
+async function onboard(wantBox) {
   console.log(`\n  ${bold('instabox')} ${dim('· a cloud box in seconds')}\n`);
 
   client.use(await signedIn());
@@ -358,22 +348,40 @@ async function sh() {
   );
 
   const cli = ensureCli();
-  const picked = await chooseBox();
-  if (picked?.listed) {
+  if (!wantBox) {
     await reportInstalls(cli);
-    console.log(`\n  New box: ${bold('instabox create --name NAME')}`);
-    console.log(`  Or enter one listed above: ${bold('npx instabox@latest --box NAME')}\n`);
-    return;
+    return nextSteps([
+      ['npx instabox@latest sh', 'start a new box and SSH into it'],
+      ['instabox ls', 'list your boxes'],
+      ['instabox ssh <box>', 'open a shell in one; add -- <command> to run just that'],
+    ]);
   }
-  // Only entering a box needs OpenSSH; the list-and-stop path above runs without it.
-  for (const bin of ['ssh', 'ssh-keygen']) {
-    if (spawnSync(bin, ['-V'], { stdio: 'ignore' }).error) die(`${bin} was not found. Install OpenSSH and try again.`);
+  // An agent (no terminal) cannot use an interactive shell, so it gets the commands instead.
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty) {
+    for (const bin of ['ssh', 'ssh-keygen']) {
+      if (spawnSync(bin, ['-V'], { stdio: 'ignore' }).error)
+        die(`${bin} was not found. Install OpenSSH and try again.`);
+    }
   }
   const t0 = Date.now();
-  process.stdout.write(`\n  ${dim(picked ? `opening ${picked.name}…` : 'starting a new box…')}`);
-  const box = await (picked ? enterBox(picked.id) : newBox()).catch((e) =>
-    die(`could not start your box: ${e.message}`),
-  );
+  process.stdout.write(`\n  ${dim('starting a new box…')}`);
+  const box = await newBox().catch(async (e) => {
+    if (e.code !== 'quota_exceeded') die(`could not start your box: ${e.message}`);
+    // The way out of the limit is `instabox rm`, so the CLI and the skills land before the exit.
+    console.log();
+    await reportInstalls(cli);
+    return quotaFull(e);
+  });
+  const ready = `ready in ${((Date.now() - t0) / 1000).toFixed(1)}s`;
+  if (!tty) {
+    console.log(`\n  ${green('✓')} box ${bold(box.name)} ${ready}`);
+    await reportInstalls(cli);
+    return nextSteps([
+      [`instabox ssh ${box.name} -- <command>`, 'run a command in it'],
+      [`instabox ssh ${box.name}`, 'open a shell in it, from a terminal'],
+    ]);
+  }
 
   // A throwaway key for this session; only its public half leaves this machine.
   const dir = mkdtempSync(join(tmpdir(), 'instabox-'));
@@ -400,12 +408,7 @@ async function sh() {
   writeFileSync(join(dir, 'known_hosts'), `@cert-authority [${c.host}]:${c.port} ${c.hostTrust.publicKey}\n`);
 
   const pauses = m.timeoutAt ? dim(` · pauses itself in ${Math.max(1, Math.round(ttlSeconds / 60))} min`) : '';
-  const took = box.resumed
-    ? `resumed in ${((Date.now() - t0) / 1000).toFixed(1)}s`
-    : box.reused
-      ? 'back in'
-      : `ready in ${((Date.now() - t0) / 1000).toFixed(1)}s`;
-  process.stdout.write(`${process.stdout.isTTY ? '\r' : '\n'}  ${green('✓')} box ${bold(m.name)} ${took}${pauses}\n`);
+  process.stdout.write(`\r  ${green('✓')} box ${bold(m.name)} ${ready}${pauses}\n`);
   await reportInstalls(cli);
   console.log(dim(`  type ${'exit'} to leave · stuck? press Enter, then ~.`));
   // The box's prompt is ~37 columns; narrower terminals make bash scroll the input line sideways.
@@ -433,7 +436,7 @@ async function sh() {
   ];
   const child = spawn('ssh', args, { stdio: 'inherit' });
   child.on('exit', (code) => {
-    console.log(`\n  ${dim(`left ${m.name}. Run`)} npx instabox@latest ${dim('again to get back in.')}\n`);
+    console.log(`\n  ${dim(`left ${m.name}. Back in:`)} instabox ssh ${m.name}\n`);
     process.exit(code ?? 0);
   });
 }
@@ -441,7 +444,7 @@ async function sh() {
 // Any other command line is the CLI's, so `npm i -g instabox` still gives a working `instabox`.
 const args = process.argv.slice(2);
 if (args.length === 1 && (args[0] === '-h' || args[0] === '--help')) usage();
-else if (isOnboarding(args)) await sh();
+else if (isOnboarding(args)) await onboard(args.includes('sh'));
 else {
   let path = findCli();
   if (!path) {

package/lib/api.mjs

@@ -3,9 +3,10 @@ import { randomUUID } from 'node:crypto';
 import { loadCredentials, saveCredentials } from './credentials.mjs';
 
 export class ApiError extends Error {
-  constructor(status, message) {
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
   }
 }
 
@@ -25,7 +26,8 @@ export function createClient(
 
   const parse = async (res) => {
     const data = res.status === 204 ? null : await res.json().catch(() => null);
-    if (!res.ok) throw new ApiError(res.status, data?.error?.message || `instabox HTTP ${res.status}`);
+    if (!res.ok)
+      throw new ApiError(res.status, data?.error?.message || `instabox HTTP ${res.status}`, data?.error?.code);
     return data;
   };
 

package/lib/boxes.mjs

@@ -1,15 +1,6 @@
-// Which of your boxes to offer, in order: live ones only, running first, then newest.
+// Your boxes in the order to show them: live ones only, running first, then newest.
 export function orderBoxes(machines) {
   return machines
     .filter((m) => !['deleting', 'deleted', 'error'].includes(m.state))
     .sort((a, b) => (b.state === 'running') - (a.state === 'running') || new Date(b.createdAt) - new Date(a.createdAt));
 }
-
-// The 0-based pick from a typed answer: Enter is the first box, count itself is "new box", else null.
-export function parseChoice(answer, count) {
-  const s = answer.trim();
-  if (s === '') return 0;
-  if (!/^\d+$/.test(s)) return null;
-  const n = Number(s);
-  return n >= 1 && n <= count + 1 ? n - 1 : null;
-}

package/lib/cli.mjs

@@ -5,24 +5,11 @@ import { createReadStream, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join, sep } from 'node:path';
 
-const OUR_FLAGS = new Set(['--github', '--no-cli', '--no-skills']);
+const OUR_FLAGS = new Set(['--github', '--google', '--no-cli', '--no-skills']);
 
-// Bare `instabox` (or the old `sh`) with only our flags; anything else is a CLI command.
+// Bare `instabox` or `sh`, with only our flags; anything else is a CLI command.
 export function isOnboarding(args) {
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === '--box' && i + 1 < args.length) i++;
-    else if (a !== 'sh' && !OUR_FLAGS.has(a) && !a.startsWith('--box=')) return false;
-  }
-  return true;
-}
-
-// The box named by --box NAME or --box=NAME, else null.
-export function boxFlag(args) {
-  const i = args.indexOf('--box');
-  if (i !== -1) return args[i + 1] ?? null;
-  const eq = args.find((a) => a.startsWith('--box='));
-  return eq ? eq.slice('--box='.length) : null;
+  return args.every((a) => a === 'sh' || OUR_FLAGS.has(a));
 }
 
 export const real = (p) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A cloud box for your coding agent, the instabox CLI and its agent skills in one command: npx instabox@latest",
   "type": "module",
   "bin": {

package/skills/instabox/SKILL.md

@@ -13,10 +13,10 @@ An instabox sandbox is a Linux VM (Debian, user `dev`, sudo). It has a root disk
 
 ```sh
 instabox whoami              # who is signed in (fails if nobody)
-instabox login               # browser sign-in with GitHub; --provider google for Google
+instabox login               # confirm the browser's account, or choose GitHub / Google
 ```
 
-A GitHub sign-in and a Google sign-in are separate accounts with separate boxes, so sign in the way the user did. `npx instabox@latest` signs in with Google unless given `--github`, and the CLI shares its sign-in.
+A GitHub sign-in and a Google sign-in are separate accounts with separate boxes. Both `instabox login` and `npx instabox@latest` open account confirmation in the browser: use its current Instabox account or choose another. To go directly to a provider, use `instabox login --provider github|google`, or `npx instabox@latest --github|--google`. The CLI shares the sign-in `npx` made. Device-code sign-in (`--device`) uses GitHub.
 
 For CI or an agent without a browser, use an API key instead: `export INSTABOX_API_KEY=ibk_...` (the user creates it on the dashboard's API Keys page). Never print, commit or log a key.
 

package/skills/instabox-move-all/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: instabox-move-all
+description: Use when the user wants to move their whole local setup onto instabox, not just one repo — "move everything to instabox", "move my whole setup", "all my projects to a box", "set up a box like my laptop". Scans this machine (repos with unsaved work, agent history, credentials, dotfiles, agent config, global tools), lets the user pick from a checkbox plan, then moves the picks onto one new box. The bulk version of instabox-migrate.
+metadata:
+  installed-by: instabox
+---
+
+# Move a whole local setup to instabox
+
+The bulk version of the `instabox-migrate` skill: instead of the current repo, it moves everything the user picks onto **one new box**. Each repo goes over exactly as `instabox-migrate` moves one; this skill adds the scan, the plan, credentials and the environment around it. See the `instabox` skill for the CLI.
+
+Four scripts in `scripts/` next to this file do the parts that must be exact (Node 18+, nothing to install):
+
+| Script | Does |
+| --- | --- |
+| `scan.mjs` | Read-only inventory, as JSON. Credentials by name and place only, never values. |
+| `plan.mjs` | `write`: the checkbox plan from the scan. `parse`: reads the edited plan back, strictly, as JSON. |
+| `stage-env.mjs` | Copies the picked dotfiles and agent config into a local directory, credentials and macOS-only lines removed, plus a setup script for the box. |
+| `push-creds.mjs` | Puts the picked credentials into the Vault for this box only, piping each value from its source into `instabox vault set`. |
+
+**Never read, print or paste a credential value yourself**: not `gh auth token`, not `cat ~/.aws/credentials`, not `echo $OPENAI_API_KEY`, not a `.env`. `push-creds.mjs` is the only thing that touches values. If a credential needs something the script cannot do, tell the user the command to run themselves.
+
+Before starting, tell the user plainly:
+
+- What happens: a scan of this machine (nothing changes here), a plan file they edit, then one new box with what they checked. Their local copies stay as they are, and nothing keeps the two in sync afterwards.
+- **Agent conversation history can contain secrets they pasted into a chat.** It is a separate checkbox per repo.
+- Some sign-ins cannot move (below); the final report says what to run on the box for each.
+
+## 1. Scan
+
+```bash
+instabox whoami                                   # signed in? otherwise: instabox login
+S=~/.claude/skills/instabox-move-all/scripts      # or ~/.agents/skills/instabox-move-all/scripts: wherever this file is
+W=~/instabox-move && mkdir -p -m 700 "$W"
+node "$S/scan.mjs" > "$W/scan.json"
+```
+
+It looks for git repos under `~/Work ~/work ~/code ~/src ~/projects ~/dev ~/Developer ~/repos ~/git ~/github` (three levels down), the current directory's repo, and any repo the user's Claude Code or Codex history points at. If the user keeps code elsewhere, add `--root DIR` (repeatable); `--depth N` to look deeper; `--no-tools` to skip asking brew/npm/uv/cargo.
+
+What it finds, in four lists:
+
+- `work`: each repo with its branch, changed / untracked / stashed / unpushed counts, whether it has a remote, and its size the way `instabox-migrate` copies it (`.git` plus files git does not ignore). Its box directory is `/data/workspace/<name>`, `-2`, `-3`... when two repos share a name.
+- `history`: Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) sessions, per repo.
+- `credentials`: each with where it comes from and what it becomes: a Vault `env` item, a Vault `file` item, or `manual` (cannot move, with the reason and the command to run on the box).
+- `environment`: dotfiles, Claude Code and Codex config, skills, local MCP servers, and global tools (`brew leaves`, `npm -g`, `uv tool`, `cargo install`, `~/go/bin`).
+
+## 2. Write the plan and let the user choose
+
+Pick a box name `instabox ls` does not show (lowercase letters, digits, `-`), then:
+
+```bash
+BOX=<box>
+node "$S/plan.mjs" write --scan "$W/scan.json" --box "$BOX" > "$W/migrate-plan.md"
+```
+
+`migrate-plan.md` has three sections, Work, Credentials and Environment, one `- [x]` / `- [ ]` line per item with its size and where it goes. Defaults:
+
+- Repos with work that exists only here (uncommitted, untracked, stashed, unpushed, or no remote) are checked, with their history. Clean, pushed repos are unchecked: they can be cloned again.
+- Credentials that work as a token or a file are checked. SSH private keys are unchecked (prefer `GH_TOKEN` over HTTPS, or a new key made on the box). Sign-ins that cannot move are unchecked and marked "can't move".
+- Dotfiles, agent config and tools are checked.
+
+Show the user a short summary (how many repos and how big, which credentials, what cannot move) and the path of the file, and ask them to edit the checkboxes and the `Box:` line, then tell you to go on. In Claude Code you may first ask a few coarse questions with AskUserQuestion (multiSelect), such as "Move: repos with unsaved work / every repo / credentials / dotfiles and agent config / tools", and apply the answers to the plan by changing only `[x]` and `[ ]`; the user still gets the file for the details.
+
+When they are done, read it back:
+
+```bash
+GIB=$(instabox usage --json | jq -r '.limits.machineSpec.persistentDiskGiB // 20')
+node "$S/plan.mjs" parse --scan "$W/scan.json" --disk-gib "$GIB" "$W/migrate-plan.md" > "$W/selection.json"
+```
+
+- Exit 1: the plan has problems (a malformed checkbox, a line deleted or duplicated, an unknown id, a "can't move" item checked, history checked without its repo, a bad box name, a plan from an older scan). All are listed; show them to the user, fix or let them fix, and parse again. Never fix a plan by editing ids or deleting lines.
+- Exit 2: a usage error, e.g. `--disk-gib` is empty because `instabox usage` failed. Fix that (`instabox login`) and parse again; never drop `--disk-gib`.
+- Exit 3: too big. Every box has the same `/data` disk, and half of it stays free for dependencies and builds. Ask the user what to uncheck (the message gives the sizes), then parse again.
+- Warnings about the Vault's limits (100 items, 256 KiB in all): ask the user to uncheck some credential files.
+
+From here on, `selection.json` is the plan: `.box`, `.work`, `.history`, `.credentials`, `.environment`, `.tools`, `.manual` (what the user must do by hand) and `.bytes`.
+
+## 3. Create the box
+
+```bash
+BOX=$(jq -r .box "$W/selection.json")
+instabox create --name "$BOX" --meta migrated="$BOX"
+instabox ls --meta migrated="$BOX"                     # exactly this box
+instabox exec "$BOX" -- df -h /data                    # room for what is coming
+```
+
+The `migrated=<box>` label is what the credentials select on (next step), so they reach this box and no other. No `--timeout`: this box is meant to stay (offer `instabox timeout "$BOX" 8h --on-timeout pause` if the user wants it to pause itself).
+
+## 4. Credentials into the Vault
+
+```bash
+node "$S/push-creds.mjs" --selection "$W/selection.json" --dry-run   # names and sizes only
+node "$S/push-creds.mjs" --selection "$W/selection.json"
+instabox vault push "$BOX"
+instabox vault show "$BOX"
+```
+
+Every item gets the selector `migrated=<box>`. Values go from their source (a variable sourced from the user's shell file, `gh auth token`, a key in `~/.codex/auth.json`, a file) straight into the CLI's stdin; the output is names, sizes and outcomes. An item already in the Vault under the same name or path is left alone (it would change what other boxes get), unless it is from an earlier run of this move; the output says which. `.env` files of repos go in as Vault files under `~/.config/instabox-move/env/<repo>/` and are linked into the repo in step 5. If an item fails, tell the user what failed and the command to set it themselves, for example `instabox vault set NAME --selector migrated=<box>` (it prompts without echo).
+
+## 5. Environment
+
+```bash
+node "$S/stage-env.mjs" --selection "$W/selection.json" --out "$W/stage"
+COPYFILE_DISABLE=1 tar -C "$W/stage" -czf - . |
+  instabox ssh "$BOX" -- 'tar -xzf - --skip-old-files --no-overwrite-dir --warning=no-unknown-keyword -C ~'
+instabox ssh "$BOX" -- 'bash -l ~/.config/instabox-move/setup.sh'
+rm -rf "$W/stage"
+```
+
+What the staged copy and `setup.sh` do on the box:
+
+- Lines that look like credentials are replaced by a comment; macOS-only lines (Homebrew paths, `osxkeychain`, `UseKeychain`, `pbcopy`, ...) are commented out; this machine's HOME becomes `/data/home`. The JSON summary printed by `stage-env.mjs` counts the lines changed per file.
+- The box keeps its own startup files: `~/.bashrc` sources the user's bash files, `~/.gitconfig` includes theirs, Claude Code `settings.json` is merged (theirs wins), `CLAUDE.md` / `AGENTS.md` are appended. Files the box already has are not overwritten (`--skip-old-files`). zsh is installed when there is a `.zshrc`; bash stays the login shell.
+- Skills, commands and agents go to `~/.claude/...` and `~/.agents/skills`; local MCP servers are added with `claude mcp add-json` (their secrets come from the Vault as environment variables).
+- Tools are installed fresh: Homebrew formulae through a table of Debian packages (or `uv tool` / `npm -g`), npm globals, `uv tool`, `cargo install`, `go install`. No macOS binary is copied. Formulae without a mapping are listed in `.manual`.
+
+`setup.sh` is safe to run again. Run it over `ssh` (installs can take minutes). It carries on past a failed step, then lists every failed step and exits 1: report those to the user, fix what you can on the box and run it again. Then check the shells still parse: `instabox exec "$BOX" -- 'bash -n ~/.bashrc; [ -f ~/.zshrc ] && zsh -n ~/.zshrc'`. Fix a broken line in the staged copy under `~/.config/instabox-move/shell/` on the box.
+
+## 6. Work: each repo
+
+For each repo in `selection.json`:
+
+```bash
+jq -r '.work[] | [.path, .name] | @tsv' "$W/selection.json"
+jq -r '.history[].repo' "$W/selection.json"        # repos whose history goes too ("repo:<path>")
+```
+
+follow **steps 2, 3 and 4 of the `instabox-migrate` skill** for that repo, with two changes:
+
+- `cd` into the repo's path first, and set `NAME` to the repo's `name` from `selection.json` instead of the `basename` line, so two repos with the same name do not land in one directory.
+- Copy the Claude Code and Codex history (the second and third parts of its step 2, and its step 3) only if the repo is in `.history`.
+
+Its checks apply: the box must show the same `git status` and `HEAD`. Do the dependency installs and builds of its step 4 per repo; the tools and `.env` links from step 5 are already there.
+
+## 7. Verify and report
+
+```bash
+instabox exec "$BOX" -- 'gh auth status; git config user.name; claude --version; codex --version'
+instabox exec "$BOX" -- 'test "${GH_TOKEN+x}" = x && echo GH_TOKEN set'   # presence only; same for other names
+instabox vault show "$BOX"
+```
+
+Tell the user, in short sections:
+
+- **Moved**: the box name (`instabox ssh <box>`), each repo with its directory and whether it builds and its tests pass, the credentials now in the Vault for this box, the environment and tools installed.
+- **Skipped**: what they unchecked, and anything that failed (with the reason).
+- **To do by hand**: every entry of `.manual`, with its exact command (for example `codex login --device-auth`, `claude` then `/login`, `gcloud auth login --no-launch-browser`, `docker login ghcr.io`, `aws sso login --use-device-code`), and how to pick up old conversations (`claude --continue` in a repo; `codex resume <id>`).
+- The credentials reach only boxes with the label `migrated=<box>`; a box created later with `--meta migrated=<box>` gets them too. Remove one with `instabox vault rm NAME`.
+- Ignored files stayed behind (except the `.env` files that went to the Vault), and secrets in committed files or in the copied history went over.
+
+Delete `$W` when the user is done with it (it holds the scan and plan, no values).
+
+## What cannot move, and why
+
+- **Rotating OAuth sign-ins**: Claude Code's login, Codex's ChatGPT login (`~/.codex/auth.json` tokens), gcloud user credentials, remote MCP servers signed in with OAuth. Their refresh token changes on use, so a copy would sign one side out. Sign in again on the box.
+- **macOS keychain-bound**: Docker's `credsStore`, Claude Code on macOS, AWS `credential_process` helpers. The keychain does not exist on the box. (`gh`'s keychain token can move: it is read with `gh auth token`.)
+- **Short-lived**: AWS SSO sessions and `aws_session_token`. Sign in on the box.
+- **Too big**: a credential file over 64 KiB; the plan says how to copy it.