fix(devcontainer): make repository setup work

[saphid]

What Changed

• Fixes one concrete outcome: opening the repository in the checked-in devcontainer now produces the environment the repo documents and Linux CI uses, instead of a container that cannot run the documented setup. Includes a follow-up fix: the vp install location is pinned through the installer's VP_BIN_DIR/VP_DATA_DIR/VP_CACHE_DIR override group, because the installer's XDG-default bin directory moved between releases and broke the first build of this branch.
• Changes: .devcontainer/devcontainer.json rebuilt on mcr.microsoft.com/devcontainers/base:ubuntu-24.04 with Node 24, Rust stable, and GitHub CLI features; new .devcontainer/on-create.sh (installs the global vp CLI, writes a first-run notice) and .devcontainer/update-content.sh (vp i, Electron exec-bit repair, Vite dep-cache warmup); named volumes for the pnpm store and root node_modules; forwards ports 5733/13773 with pairing guidance; pins T3CODE_HOME to the workspace's gitignored .t3; runs as vscode. Adds docs/internals/devcontainer.md and a pointer in docs/internals/scripts.md.
• Preserves: all application code, contracts, providers, CI workflows, server semantics, and connection modes. Bun stays out, per docs/internals/scripts.md ("nothing in contributor setup needs it").
• Intentionally does not change: anything user-visible in the app — there is no user-facing change, so the UI Changes section is omitted as the template permits; host-only Electron and native-mobile workflows; vp run dev --share (no tailscale in the image); CI workflow files.

Why

Reproduction:

1. At the PR base (11f051373), open the repo in the checked-in devcontainer (Debian bookworm with bun/Node/Python features, no remoteUser, no port forwarding).
2. Let the lifecycle finish, then try the documented setup from docs/internals/scripts.md.
3. vp does not exist; the only install path is bun install --frozen-lockfile, which does not resolve the workspace's pnpm catalog: dependencies (used by the root, apps/server, apps/web, packages/contracts) or its patchedDependencies; there is no Rust toolchain for native/resource-monitor; and the shell is root.

Actual: a root Debian container whose bootstrap cannot install the monorepo, matching neither the documented setup nor Linux CI.

Expected: a container matching Linux CI (ubuntu-24.04, Node ^24.13.1 from package.json, Rust stable, gh) with the documented vp i bootstrap done before the first attach.

Cause: .devcontainer/devcontainer.json predates the pnpm/vp setup. It was introduced in #1791 and last touched in #2208, and both versions install with bun install, forward no ports, and define no non-root user.

Why this owner and approach: .devcontainer/ owns the contributor environment, so the fix rebuilds that definition to mirror the versions CI pins rather than inventing a parallel setup. Lifecycle steps follow devcontainer semantics: one-time toolchain work in onCreateCommand (baked into prebuilds), content-dependent installs in updateContentCommand so prebuild refreshes stay warm. The contributor doc lives beside the others in docs/internals/. The five files are one unit — the scripts and doc do not exist without the config — which is why the patch is not split further.

Refs: #1791, #2208

Verification

Environment: Dev Container CLI 0.88.0, Docker 29.5.2 (colima, Apple Silicon, linux/arm64), cold caches. Two VM shapes were used: 2 vCPU / 4 GiB, and 4 vCPU / 8 GiB — the config's declared hostRequirements. Evidence captured at head 1656e3ee with the identical tree content.

• shellcheck .devcontainer/on-create.sh .devcontainer/update-content.sh — exit 0; bash -n on both — exit 0
• devcontainer build --workspace-folder . — exit 0 twice, cold: 3m 45s (2 vCPU / 4 GiB) and 2m 58s (4 vCPU / 8 GiB)
• devcontainer up — onCreateCommand exit 0 on both VMs. In-container: whoami → vscode; vp --version → vp v0.3.0, with /usr/local/bin/vp resolving into the pinned install directory; node → v24.20.0; pnpm → 11.10.0; cargo → 1.98.0; rustfmt → 1.9.0-stable; gh → 2.98.0; the first-run notice is written.
• cargo fmt --manifest-path native/resource-monitor/Cargo.toml -- --check inside the container — exit 0
• updateContentCommand starts correctly (volume ownership repair, then vp i resolves the lockfile — 1809 packages — and passes its supply-chain policy check), but a completed first install was not observed on this machine: on the 4 GiB VM the kernel OOM-killed vp i at ~3.7 GiB RSS (below the declared 8 GiB floor), and on the 8 GiB VM the VM's disk layer failed mid-install (ERR_PNPM_EIO, then containerd metadata write EIO) with the host Mac under 7 GB free. Retrying was stopped deliberately rather than fill the developer's nearly-full disk; both failures are environment limits, and the script's own steps ran.
• vp run --filter @t3tools/contracts typecheck inside the container — not run: it needs the dependency tree from the install above, which never completed here.
• CI at this head: green so far — Check, Test, Test Server 1/3, Rust, Release Smoke, Macroscope correctness, Label PR size (Test Server 2 and the bot-review checks were still running at writing; no failures other than the Vercel authorization gate below). CI's ubuntu install path is the same vp i sequence update-content.sh runs.
• Authorization/skipped gates: the Vercel check fails only for want of deploy authorization for the external fork; EAS Preview, Mobile Native Static Analysis, [code]smith, and the desktop/web preview jobs are skipped gates.
• Not run: Codespaces and prebuilds; x86_64, native Linux, and Windows Docker hosts; vp run dev inside the container (headless image; windowed Electron is documented host-only); the autoreview pass (skill not installed in this harness).

Risks and limitations

• Base drift: this branch is 144 commits behind main (2 ahead). GitHub reports it MERGEABLE with no conflicts; the drift is recorded here and not rebased in this pass. If main touches .devcontainer/ or docs/internals/ before merge, refresh first.
• The memory floor is real: on a 4 GiB host, vp i is OOM-killed — the declared 8 GiB hostRequirements should not be lowered.
• onCreateCommand fetches the vp installer from the network (https://vite.plus); container creation needs egress, and the installer is a moving target — mitigated by pinning its install location, at the cost of depending on the VP_*_DIR override group staying supported.
• Validated on Apple Silicon Docker via colima only. Codespaces, prebuilds, and other host shapes were not exercised; Codespaces prebuild snapshots exclude the caching volumes (documented in docs/internals/devcontainer.md).
• Rollback: revert commits 3927926b and 1656e3ee; nothing else depends on the added files.

Checklist

• This PR is small and focused (one outcome; 5 files, +159/−23)
• I explained what changed and why
• I included before/after screenshots for any UI changes (none — no user-visible app change)
• I included a video for animation/interaction changes (none — no user-visible app change)
• The linked issue has maintainer alignment when this is non-trivial work (no owning issue; scoped maintenance fix)
• The branch contains no unrelated, generated, personal, or private files
• Every stated validation result is a real current result captured at head 1656e3ee, with anything that could not be run named and why

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1f6509bc-6853-4ecd-9001-384c0afcd16a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved at 1656e3e

Macroscope's review found this PR approvable — The changes are confined to devcontainer lifecycle setup and contributor documentation, adding isolated tooling, dependency caching, and development-state configuration without changing shipped product behavior or product defaults.

^{You can add or adjust custom eligibility rules. Learn more.}