instabox 0.5.0 → 0.5.2

package/skills/instabox-basic-setup/scripts/scan.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// Read-only inventory of the basic setup that can go into the instabox Vault:
+// tokens (by name and place, never values), git config, editor and terminal
+// config. Prints JSON.
+//
+//   node scan.mjs > scan.json
+//
+// Nothing is written. Shell files are read for the names of the variables
+// they export, never their values.
+import { realpathSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import {
+  MACOS_ONLY,
+  SECRET_VALUE,
+  VAULT_MAX_VALUE,
+  WELL_KNOWN,
+  hasCommand,
+  isMain,
+  isSecretName,
+  listFiles,
+  readText,
+  run,
+  statOrNull,
+  vaultEnvNameOK,
+  vaultFileName,
+  vaultPathOK,
+} from './lib.mjs';
+
+// Shell startup files: read for exported tokens only. They do not move.
+export const SHELL_RC = ['.zshenv', '.zprofile', '.zshrc', '.bash_profile', '.bash_login', '.profile', '.bashrc', '.bash_aliases'];
+
+// nvim: config files only. Plugin managers' checkouts and editor state stay behind.
+const NVIM_SKIP = new Set(['.git', 'node_modules', 'pack', 'plugged', 'bundle', 'site', 'undo', 'backup', 'swap', 'sessions', 'spell', '.repro']);
+const NVIM_MAX_FILES = 40;
+const NVIM_MAX_BYTES = 128 * 1024;
+
+// `export NAME=value` / `NAME=value` lines of a shell file: names, line numbers and flags only.
+function shellAssignments(text) {
+  const out = [];
+  text.split('\n').forEach((line, i) => {
+    const m = line.match(/^\s*(?:export\s+|declare\s+-x\s+|typeset\s+-x\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!m) return;
+    out.push({ name: m[1], line: i + 1, secretValue: SECRET_VALUE.test(m[2]), keychain: MACOS_ONLY.test(m[2]) });
+  });
+  return out;
+}
+
+function scanTokens({ home, env, procEnv }) {
+  const items = [];
+  const manual = [];
+  const byName = new Map();
+  const add = (name, source, from, extra = {}) => {
+    if (byName.has(name)) return; // the first place a name is found wins: the Vault holds one value per name
+    const item = { id: `env:${name}`, section: 'tokens', kind: 'env', name, source, from, checked: true, ...extra };
+    byName.set(name, item);
+    items.push(item);
+  };
+  const unvaultable = new Set();
+
+  // gh: the token gh keeps (keychain or hosts.yml), read with `gh auth token` at push time.
+  if (hasCommand('gh', env)) {
+    const st = run(['gh', 'auth', 'status', '--hostname', 'github.com'], { env });
+    if (st.ok) {
+      const who = (st.stdout + st.stderr).match(/account (\S+)/)?.[1] || null;
+      add('GH_TOKEN', { type: 'cmd', argv: ['gh', 'auth', 'token', '--hostname', 'github.com'] }, '`gh auth token`', {
+        note: `${who ? `GitHub account ${who}; ` : ''}gh, and git over HTTPS to GitHub, use it on the box`,
+      });
+    }
+  }
+
+  // Shell startup files: exported tokens.
+  for (const f of SHELL_RC) {
+    const text = readText(join(home, f));
+    if (text === null) continue;
+    for (const a of shellAssignments(text)) {
+      if (!WELL_KNOWN.has(a.name) && !isSecretName(a.name) && !a.secretValue) continue;
+      if (!vaultEnvNameOK(a.name)) {
+        if (!unvaultable.has(a.name)) {
+          unvaultable.add(a.name);
+          manual.push({
+            what: `${a.name} (~/${f}:${a.line})`,
+            why: 'the Vault does not take env items with this name (INSTABOX_*, SSH_* and a few system names)',
+            todo: `if a box needs it, set it there by hand`,
+          });
+        }
+        continue;
+      }
+      const extra = {};
+      if (a.keychain) {
+        extra.checked = false;
+        extra.reason = 'your shell reads it from the macOS keychain: checking it runs that lookup once, at push time';
+      } else if (!WELL_KNOWN.has(a.name)) {
+        extra.checked = false;
+        extra.reason = 'not a well-known model or service token: check it if every box should have it';
+      }
+      add(a.name, { type: 'rc', file: join(home, f), name: a.name }, `~/${f}:${a.line}`, extra);
+    }
+  }
+  // Well-known tokens in the environment the scan runs in (set some other way than a shell file).
+  for (const name of Object.keys(procEnv).sort()) {
+    if (!WELL_KNOWN.has(name) || !procEnv[name]) continue;
+    add(name, { type: 'env', name }, 'this shell’s environment');
+  }
+
+  if (!byName.has('GH_TOKEN'))
+    manual.push({
+      what: 'GitHub token (GH_TOKEN)',
+      why: hasCommand('gh', env) ? 'gh is not signed in on this machine' : 'gh is not installed on this machine',
+      todo: 'sign in here with `gh auth login` and run this again; or put a token in yourself: `instabox vault set GH_TOKEN` (it prompts without echo)',
+    });
+  if (!byName.has('CLAUDE_CODE_OAUTH_TOKEN'))
+    manual.push({
+      what: 'Claude Code sign-in (CLAUDE_CODE_OAUTH_TOKEN)',
+      why: 'not found in your shell files; the sign-in on this machine is in the macOS keychain, and is never read',
+      todo:
+        'run `claude setup-token` yourself (it prints a token that lasts a year), then `instabox vault set CLAUDE_CODE_OAUTH_TOKEN` and paste it at the prompt' +
+        (byName.has('ANTHROPIC_API_KEY') ? ' (or skip it: ANTHROPIC_API_KEY is in the plan, and Claude Code uses that)' : '; or `claude`, then /login, on each box'),
+    });
+  if (!byName.has('OPENAI_API_KEY') && (hasCommand('codex', env) || statOrNull(join(home, '.codex'))))
+    manual.push({
+      what: 'Codex sign-in',
+      why: 'no OPENAI_API_KEY in your shell files; a ChatGPT sign-in cannot be copied (its refresh token rotates)',
+      todo: 'on each box: `codex login --device-auth`; or `instabox vault set OPENAI_API_KEY` once for every box',
+    });
+  return { items, manual };
+}
+
+// A home-relative path for a file, or null when it is outside HOME or not one the Vault takes.
+function homePath(home, p) {
+  const rel = relative(home, p);
+  return rel && !rel.startsWith('..') && vaultPathOK(rel) ? rel : null;
+}
+
+function fileEntry(home, section, rel, transform, extra = {}) {
+  const src = join(home, rel);
+  const st = statOrNull(src);
+  if (!st?.isFile()) return null;
+  const file = { path: rel, name: vaultFileName(rel), src, transform, bytes: st.size };
+  const e = { id: `file:${rel}`, section, kind: 'file', path: rel, files: [file], bytes: st.size, checked: true, ...extra };
+  if (st.size > VAULT_MAX_VALUE) {
+    e.checked = false;
+    e.reason = `${st.size} bytes: over the Vault's 64 KiB per item`;
+  }
+  return e;
+}
+
+function scanGit({ home, env }) {
+  const out = [];
+  const gc = fileEntry(home, 'git', '.gitconfig', 'gitconfig', {
+    note: 'osxkeychain and other macOS-only lines, credentials and commit signing left out',
+  });
+  if (gc) out.push(gc);
+  const xdg = fileEntry(home, 'git', '.config/git/config', 'gitconfig', { note: 'macOS-only lines and credentials left out' });
+  if (xdg) out.push(xdg);
+  // The global gitignore: core.excludesfile, else git's default.
+  let ignore = null;
+  const r = run(['git', 'config', '--global', '--get', 'core.excludesfile'], { env: { ...env, HOME: home } });
+  const v = r.ok ? r.stdout.trim() : '';
+  if (v) {
+    const abs = v.startsWith('~/') ? join(home, v.slice(2)) : v.replace(/^\$HOME(?=\/)/, home);
+    if (abs.startsWith('/')) ignore = homePath(home, abs);
+  }
+  if (!ignore && statOrNull(join(home, '.config/git/ignore'))) ignore = '.config/git/ignore';
+  if (ignore) {
+    const e = fileEntry(home, 'git', ignore, 'text', { note: 'your global gitignore' });
+    if (e) out.push(e);
+  }
+  return out;
+}
+
+function scanEditor({ home }) {
+  const out = [];
+  for (const rel of ['.vimrc', '.tmux.conf', '.config/tmux/tmux.conf']) {
+    const e = fileEntry(home, 'editor', rel, 'text');
+    if (e) out.push(e);
+  }
+  // nvim: init.lua / init.vim and the config files around it, never plugin checkouts.
+  const nvimDir = join(home, '.config', 'nvim');
+  let real = nvimDir;
+  try {
+    real = realpathSync(nvimDir);
+  } catch {}
+  if (statOrNull(real)?.isDirectory()) {
+    const files = [];
+    const left = [];
+    for (const f of listFiles(real, (n) => NVIM_SKIP.has(n))) {
+      const top = !f.includes('/');
+      const keep = /\.(?:lua|vim)$/.test(f) || (top && f === 'lazy-lock.json');
+      if (!keep) continue;
+      const rel = `.config/nvim/${f}`;
+      const st = statOrNull(join(real, f));
+      if (!vaultPathOK(rel) || !st) continue;
+      if (st.size > VAULT_MAX_VALUE) {
+        left.push(`${f} (${st.size} bytes)`);
+        continue;
+      }
+      files.push({ path: rel, name: vaultFileName(rel), src: join(real, f), transform: f.endsWith('.json') ? 'raw' : 'text', bytes: st.size });
+    }
+    if (files.some((f) => /^\.config\/nvim\/init\.(?:lua|vim)$/.test(f.path))) {
+      const bytes = files.reduce((s, f) => s + f.bytes, 0);
+      const e = { id: 'files:.config/nvim', section: 'editor', kind: 'file', path: '.config/nvim', files, bytes, checked: true };
+      const notes = ['plugins are not copied: your plugin manager installs them on the box'];
+      if (left.length) notes.push(`left out, over 64 KiB: ${left.join(', ')}`);
+      e.note = notes.join('; ');
+      if (files.length > NVIM_MAX_FILES || bytes > NVIM_MAX_BYTES) {
+        e.checked = false;
+        e.reason = `${files.length} files: a big share of the Vault's 100 items and 256 KiB`;
+      }
+      out.push(e);
+    }
+  }
+  return out;
+}
+
+// Two paths can map to one item name (a-b.lua and a/b.lua): the second gets -2, -3...
+function uniqueNames(entries) {
+  const used = new Set();
+  for (const e of entries) {
+    if (e.kind === 'env') used.add(e.name);
+    for (const f of e.files || []) {
+      let n = f.name;
+      for (let i = 2; used.has(n); i++) n = `${f.name}-${i}`;
+      f.name = n;
+      used.add(n);
+    }
+  }
+}
+
+export function scan(opts = {}) {
+  const env = opts.env || process.env;
+  const home = resolve(opts.home || env.HOME);
+  const tokens = scanTokens({ home, env, procEnv: opts.procEnv || env });
+  const items = [...tokens.items, ...scanGit({ home, env }), ...scanEditor({ home })];
+  uniqueNames(items);
+  return { version: 2, home, platform: opts.platform || process.platform, items, manual: tokens.manual };
+}
+
+function main() {
+  if (process.argv.length > 2) {
+    process.stderr.write('usage: scan.mjs > scan.json\n');
+    process.exit(2);
+  }
+  process.stdout.write(JSON.stringify(scan(), null, 2) + '\n');
+}
+
+if (isMain(import.meta)) main();

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

@@ -0,0 +1,193 @@
+---
+name: instabox-move-repo
+description: Use when the user wants to move the repo they are working in onto instabox — "move this repo to instabox", "migrate this repo to a box", "continue this work in the cloud", "move my project to a box". Copies the current git repo and all its worktrees exactly (uncommitted, untracked, stashed and unpushed work; no build output or dependencies), moves its Claude Code / Codex conversations so they resume on the box, then installs the project's dependencies there.
+metadata:
+  installed-by: instabox
+---
+
+# Move a local repo to instabox
+
+Moves the git repo of the current directory, with its worktrees, into one new box (see the `instabox` skill for the CLI). The box ends up with the same `git status`, HEAD, branches, stashes and worktrees, the agent conversations about the repo, and its dependencies installed.
+
+Three scripts in `scripts/` next to this file do the parts that must be exact (Node 18+ and bash, nothing to install):
+
+| Script | Does |
+| --- | --- |
+| `repo-files.mjs` | The plan: the main checkout and each linked worktree, where each lands on the box, sizes before and after, what is left out. `--list0 PATH`: the files of one checkout for `tar`. Names and sizes only, never contents. |
+| `history.mjs` | Stages the Claude Code and Codex sessions of those paths with every path rewritten to the box path. Prints counts and session ids, never contents. |
+| `deps.sh` | Runs on the box: detects the toolchain, installs missing runtimes and the dependencies, runs an obvious build. |
+
+What goes over:
+
+- All of the main checkout's `.git` (branches, tags, stashes, unpushed commits, the index so staged changes stay staged, each worktree's own HEAD and index), every tracked file, and every untracked file git does not ignore, in the main checkout and in each linked worktree.
+- **Never build output or dependencies**, even when the repo forgot to ignore them: `node_modules`, `target`, `dist`, `build`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.cache`, `coverage`, `__pycache__`, `.venv`, `venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.gradle`, `bazel-*`, `*.egg-info`, `*.o`, `*.so`, `*.pyc`, `*.class`, ... (the full list is `EXCLUDED_DIRS` and `EXCLUDED_FILES` in `repo-files.mjs`). Files git ignores stay too. A **tracked** file always goes, even under such a name, so `git status` matches. `--keep NAME` copies an excluded name anyway, for a repo whose source really lives in, say, `build/` (pass it to every `repo-files.mjs` run, step 1 and step 3, through `KEEP`). It does not bring back an untracked `.env`: those only go through the Vault (step 7).
+- Claude Code and Codex conversations for the repo and its worktrees (on by default, the user can opt out).
+
+Not moved: `.env` files that are not committed (they go through the Vault, step 7), credentials stored outside the repo (git credential helpers, gh, cloud, API keys in your environment), other local tools and config, other repos. A `.env` that is committed or staged is in `.git` and goes with it. Everything inside `.git` goes, including `.git/config` and so a remote URL with a token embedded in it (`https://x-access-token:TOKEN@...`); and only `.env`-named untracked files are held back, so an untracked `.npmrc` with a token, a `*.pem` or a `secrets.yaml` that git does not ignore goes too.
+
+**Never read, print or paste a credential value yourself**: not a `.env`, not `gh auth token`, not `echo $SOME_KEY`.
+
+Before starting, tell the user plainly:
+
+- **git push/pull from the box will not work until they set up credentials there** (for example `instabox ssh <box>` then `gh auth login`; the `instabox-basic-setup` skill, where installed, puts tokens and git config into the Vault).
+- **The copied conversation history may contain secrets they pasted earlier** (tokens, keys, passwords). It goes by default; ask whether to skip it (or only Codex / only Claude Code).
+- Their local copy stays as it is, and nothing keeps the two in sync afterwards.
+
+## 1. The plan
+
+Run with **bash**, anywhere inside the repo or one of its worktrees:
+
+```bash
+instabox whoami                                   # signed in? otherwise: instabox login
+S=~/.claude/skills/instabox-move-repo/scripts     # or ~/.agents/skills/instabox-move-repo/scripts: wherever this file is
+W=$(mktemp -d)
+node "$S/repo-files.mjs"                          # the plan, for you and the user
+```
+
+It always plans the **main checkout plus its linked worktrees** (from `git worktree list`), even when run from inside a worktree: a worktree alone is half a repo. For each it shows the branch (or detached HEAD), uncommitted changes, locked state, where it lands, and the sizes:
+
+- `before`: everything in the directory on disk, and what "`.git` plus every file git does not ignore" would be.
+- `left out`: build output and dependencies git does not ignore, biggest first, and `.env` files.
+- `after`: what is actually sent.
+
+Where things land: the main checkout in `/data/workspace/<repo-name>` (`/data` is the box's persistent disk; HOME is `/data/home`); a worktree inside it (such as `.claude/worktrees/<name>`) at the same relative path; any other worktree in `/data/workspace/<repo-name>.worktrees/<its directory name>`. Pass `--dest /data/workspace/<other>` if the user wants another name. Prunable worktrees (directory gone) are listed as not moved and stay behind.
+
+Show the user the plan in short: the worktrees with their sizes and state, the total sent, the biggest things left out, the `.env` files. If there are worktrees, ask which to leave behind (in Claude Code, AskUserQuestion with multiSelect); each one left behind is a `--skip-worktree PATH`. Ask about the history (above). Then write the final plan:
+
+```bash
+SKIP=()            # one --skip-worktree per worktree the user unchecked: SKIP+=(--skip-worktree /path/to/it)
+KEEP=()            # one --keep per excluded name the user wants copied anyway: KEEP+=(--keep build)
+node "$S/repo-files.mjs" "${SKIP[@]}" "${KEEP[@]}" --json > "$W/plan.json"
+DEST=$(jq -r .main.box "$W/plan.json")
+jq -r '.totals' "$W/plan.json"                    # sendBytes must fit well inside /data: instabox usage
+```
+
+Submodules: their history comes along inside `.git/modules`; run `git submodule update --init` on the box. Uncommitted changes inside a submodule, and an untracked nested repo's files, are not copied. A bare repo with worktrees is refused: move its worktrees one by one by hand.
+
+## 2. Create the box
+
+```bash
+instabox ls                                       # pick a box name that is not taken
+BOX=<box>
+instabox create --name "$BOX" --meta repo="$(basename "$DEST")"
+```
+
+Box names are lowercase letters, digits and `-`. Every box is the same size. The default template (`universal`) has git, Node.js 22, Python (uv), Go, Rust, a C toolchain and Docker. Do not add a kill timeout: this box is meant to stay (offer `instabox timeout <box> 8h --on-timeout pause` if the user wants it to pause itself). The `repo=` label lets Vault items (step 7) reach this box only.
+
+## 3. Copy the repo and its worktrees
+
+The main checkout first (it carries `.git`), then each worktree, each as its own `tar` stream:
+
+```bash
+export COPYFILE_DISABLE=1                                   # macOS tar: no ._ AppleDouble files
+X='tar -xzf - --warning=no-unknown-keyword'                 # the box runs GNU tar
+jq -r '.main, (.worktrees[] | select(.move)) | [.src, .box] | @tsv' "$W/plan.json" |
+while IFS=$'\t' read -r src box; do
+  echo "== $src -> $box"
+  node "$S/repo-files.mjs" --list0 "$src" "${SKIP[@]}" "${KEEP[@]}" </dev/null |
+    tar -C "$src" --null --no-recursion -T - -czf - |
+    instabox ssh "$BOX" -- "mkdir -p '$box' && $X -C '$box'"
+done
+```
+
+Then point the worktrees at their new places (each worktree's `.git` file and `.git/worktrees/<id>/gitdir` still name the local paths; `git worktree repair` with the new paths rewrites both sides):
+
+```bash
+WTS=$(jq -r '[.worktrees[] | select(.move) | .box] | join(" ")' "$W/plan.json")
+[ -z "$WTS" ] || instabox ssh "$BOX" -- "cd '$DEST' && git worktree repair $WTS"
+```
+
+Box paths contain only letters, digits and `._-/`, so they are safe unquoted there.
+
+Check that every checkout has the same state, and the same worktrees:
+
+```bash
+jq -r '.main, (.worktrees[] | select(.move)) | [.src, .box] | @tsv' "$W/plan.json" |
+while IFS=$'\t' read -r src box; do
+  echo "== $box"
+  diff <(cd "$src" && { git status --porcelain | sort; git rev-parse HEAD; }) \
+       <(instabox exec "$BOX" --cwd "$box" -- 'git status --porcelain | sort; git rev-parse HEAD' </dev/null)
+done
+git worktree list; instabox exec "$BOX" --cwd "$DEST" -- git worktree list
+```
+
+The only allowed differences are `<` lines starting with `??` for what the plan left out (a build directory, an untracked `.env`, or a whole `?? dir/` that held only those), and ` M <submodule>` for a submodule with uncommitted changes inside it (those are not copied: note it for step 8). A name passed with `--keep` must not show up as a `??` difference: it was meant to go. HEADs must match, and the box's `git worktree list` must show the same branches, detached HEADs and `locked` marks at the box paths, without the worktrees left behind. Anything else: stop and look before going on.
+
+## 4. Conversation history (unless the user opted out)
+
+```bash
+H=$(mktemp -d)
+node "$S/history.mjs" --plan "$W/plan.json" --out "$H" > "$W/history.json"   # --no-claude / --no-codex to skip one
+jq '{claude: .claude | {sessions, bytes, recent}, codex: .codex | {sessions, bytes, recent}}' "$W/history.json"   # null: skipped
+tar -C "$H" -czf - $(jq -r '.entries[]' "$W/history.json") | instabox ssh "$BOX" -- "$X --no-overwrite-dir -C ~"
+instabox ssh "$BOX" -- 'bash ~/.cache/instabox-move-repo/apply-history.sh'
+rm -rf "$H"
+```
+
+What it moves, for the main checkout, each moved worktree, and any directory under them:
+
+- Claude Code: `~/.claude/projects/<path with every non-alphanumeric character as ->/` (sessions, subagent transcripts, tool results). Which path a directory belongs to is read from the `cwd` its sessions recorded, so `/a/app-2` is never taken for `/a/app`. On the box it is stored under the box path's name, so `claude --continue` and `claude --resume` in that directory find it. The prompt history lines (`~/.claude/history.jsonl`) for those paths are appended.
+- Codex: the `rollout-*.jsonl` files under `~/.codex/sessions` (and `archived_sessions`) whose `cwd` is one of those paths, and their lines of `~/.codex/history.jsonl`.
+- In every copied file each local path is replaced by its box path (a longer name such as `/a/app-2` is not touched), so the sessions' `cwd` and the file paths in them point at the box. File times are kept, so the latest session stays the latest. The local files are not changed.
+
+Do not write any notes about the move into `CLAUDE.md`, `AGENTS.md` or settings files on the box, global or in the repo.
+
+## 5. Install dependencies
+
+```bash
+instabox ssh "$BOX" -- 'mkdir -p ~/.cache/instabox-move-repo && cat > ~/.cache/instabox-move-repo/deps.sh' < "$S/deps.sh"
+instabox ssh "$BOX" -- "bash -l ~/.cache/instabox-move-repo/deps.sh '$DEST'"      # --dry-run first if you want to see the steps
+```
+
+Over `ssh`, which has no time limit (installs and builds take minutes; `instabox exec` stops at 600 seconds). It looks at the repo root and each first-level subdirectory with a lockfile of its own:
+
+| Found | Runtime, installed only when missing or another version is pinned | Install | Smoke |
+| --- | --- | --- | --- |
+| `.tool-versions`, `mise.toml` | mise | `mise install` | |
+| `package.json` + `pnpm-lock.yaml` / `yarn.lock` / `bun.lock(b)` / `package-lock.json` (or `packageManager`) | Node per `.nvmrc` / `.node-version` (nvm), pnpm/yarn via corepack, bun | `pnpm install --frozen-lockfile`, `yarn install --immutable` (berry) or `--frozen-lockfile`, `bun install --frozen-lockfile`, `npm ci`; no lockfile: `npm install --no-package-lock` | `<pm> run build` if there is a `build` script |
+| `uv.lock`, `poetry.lock`, `Pipfile.lock`, `pdm.lock`, `requirements*.txt`, `pyproject.toml` / `setup.py` | uv (it fetches the Python in `.python-version`), poetry/pipenv/pdm via `uv tool` | `uv sync --frozen`, `poetry install`, `pipenv sync --dev`, `pdm sync`, `uv venv && uv pip install -r ...`, `uv pip install -e .` | |
+| `Cargo.toml` | rustup (follows `rust-toolchain`) | `cargo fetch [--locked]` | `cargo build` |
+| `go.mod` | Go (newer `go` lines are fetched by Go itself) | `go mod download` | `go build ./...` |
+| `Gemfile` | ruby-full, bundler (apt, gem) | `bundle install` (gems in `~/.bundle/gems`) | |
+| `pom.xml` / `build.gradle(.kts)` | JDK, Maven (apt) | `./mvnw` or `mvn dependency:go-offline` | `compile`, `./gradlew assemble` |
+| `composer.json` | PHP, composer (apt) | `composer install` | |
+| `mix.exs`, `deno.json`, `*.csproj`, `Package.swift`, `pubspec.yaml`, compose files | | noted, not installed | |
+
+It never rewrites a lockfile (frozen installs only), carries on past a failed step, lists every step as ok or FAILED, adds notes (an expected `.env`, compose services not started, git status changed by an install), and exits 1 if anything failed. Failures are not the end: read each one, fix it on the box (a system library with `sudo apt-get install -y ...`, another toolchain version, a step from the README or CI config in `.github/workflows`), and run the step again, until it builds. Run tests if the project defines them and they do not need services or secrets. For a script you send over stdin instead, give anything that might prompt `-y` or `</dev/null`. Stop and ask the user when something needs a secret (private registry token, `.env` values) or a choice only they can make.
+
+Worktrees: install only in the main checkout unless the user wants a worktree ready too (`deps.sh '<its box path>'`); each install takes disk space.
+
+## 6. Check git did not change
+
+```bash
+instabox exec "$BOX" --cwd "$DEST" -- 'git status --porcelain | sort; git rev-parse HEAD'
+```
+
+Compare with step 3. New `??` lines from the installs (for example a lockfile the project does not commit) are worth a mention; a modified tracked file is not expected: find which step did it.
+
+## 7. `.env` files: through the Vault, never copied
+
+The plan's `envLeftOut` lists them by name (`jq -r '.main.envLeftOut, (.worktrees[] | select(.move) | .envLeftOut) | .[]' "$W/plan.json"`). Do not open them. If the user wants them on the box, the Vault carries them as files under HOME, and a link puts each into the repo. With their go-ahead, per file (the CLI reads the file; nothing passes through you):
+
+```bash
+R=$(basename "$DEST")
+instabox vault set-file ".config/instabox-move-repo/env/$R/<path in repo>" --from "<local path>" --selector repo="$R"
+instabox vault push "$BOX"
+instabox exec "$BOX" -- "mkdir -p '$DEST/<dir in repo>' && ln -sfn ~/.config/instabox-move-repo/env/$R/<path in repo> '$DEST/<path in repo>'"
+```
+
+The `--selector repo=<name>` keeps the file to boxes created with `--meta repo=<name>` (step 2). For tokens, git config and editor setup across all boxes, point the user to the `instabox-basic-setup` skill.
+
+## 8. Tell the user
+
+- The box name and where the repo is: `instabox ssh <box>`, then `cd /data/workspace/<name>`; each worktree with its box path and branch; worktrees left behind and why.
+- Uncommitted work inside a submodule (a ` M <submodule>` line in step 3) did not come over: name each such submodule so the user can commit or copy that work themselves.
+- Sizes: on disk before, sent after, and the biggest things left out (they were rebuilt or reinstalled on the box).
+- What was installed, whether build and tests pass, and anything left to do (each FAILED step and note from `deps.sh` that is not fixed).
+- Again: git push/pull needs credentials set up on the box. Ignored files, build output and untracked `.env` files were not copied. Secrets in committed or staged files, anywhere in `.git` (such as a token in a remote URL in `.git/config`), in untracked files not named `.env*`, or in the copied history, did go over.
+- How to pick up old conversations, kept short, with the session ids from step 4:
+  - Claude Code, in the repo (or worktree) directory on the box: `claude --continue` (latest) or `claude --resume` (picker, or `claude --resume <id>`).
+  - Codex, in that directory: `codex resume` (picker for this directory), `codex resume --last`, or `codex resume <id>`.
+- The local copy is untouched; nothing keeps the two in sync after this.
+
+Delete `$W` when done (plans and lists, no values).