diff --git a/integrations/isolation/images/devenv/Dockerfile b/integrations/isolation/images/devenv/Dockerfile
index b97349e3..45c2521a 100644
--- a/integrations/isolation/images/devenv/Dockerfile
+++ b/integrations/isolation/images/devenv/Dockerfile
@@ -5,9 +5,11 @@
 ARG BASE_IMAGE=docker/sandbox-templates:shell-docker
 FROM ${BASE_IMAGE}
 
-# devenv/direnv nixpkgs pin (nixos-25.05). Bump this and VERSION together —
-# unpinned `nixpkgs#…` tracks unstable HEAD and drifts per build.
-ARG NIXPKGS_REV=ac62194c3917d5f474c1a844b6fd6da2db95077d
+# devenv/direnv nixpkgs pin (nixos-26.05 → devenv 2.1.2). Bump this and
+# VERSION together — unpinned `nixpkgs#…` tracks unstable HEAD and drifts per
+# build. The devenv major is part of the image contract: a major change here
+# is a major VERSION bump.
+ARG NIXPKGS_REV=0d9e9b832d03ac387417e16ce1febf73b2e631e1
 
 # Checksum pin for the installer script below (release assets are mutable);
 # bump together with the installer version.
diff --git a/integrations/isolation/images/devenv/README.md b/integrations/isolation/images/devenv/README.md
index daf0ad68..7a473e74 100644
--- a/integrations/isolation/images/devenv/README.md
+++ b/integrations/isolation/images/devenv/README.md
@@ -34,6 +34,43 @@ The image contains only the base-agnostic toolchain: Nix (single-user store
 owned by `agent`), devenv + direnv pinned to a nixpkgs rev, flakes enabled,
 and the bash wiring that puts the Nix profile and direnv hook in every shell.
 
+The devenv major is part of the image contract: `1.x` tags ship devenv 1.x
+(nixos-25.05), `2.x` tags ship devenv 2.x (nixos-26.05). devenv 2.x bundles
+its own Nix for evaluation and builds and shares the single-user store with
+the installer's Nix on `PATH`; both read and write the same store database.
+
+## devenv 2.x notes for consuming repos
+
+A 2.x image runs a repo's `devenv.nix` with the modules pinned by that repo's
+`devenv.lock` (the `devenv` input), so a 1.x-locked repo keeps its 1.x module
+semantics until someone runs `devenv update`. What the CLI major changes
+regardless of the lock:
+
+- The `git-hooks` input is no longer implicit. A repo using `git-hooks.hooks`
+  fails with `git-hooks or pre-commit-hooks input required` until it declares
+  the input in `devenv.yaml`.
+- `devenv shell` rewrites `devenv.lock` to drop the implicit `git-hooks`,
+  `pre-commit-hooks`, and `flake-compat` nodes; a 1.x CLI adds them back at
+  current HEAD. Teams mixing 1.x CI with 2.x sandboxes see lock churn until
+  `git-hooks` is declared explicitly, which makes both majors agree.
+- `.devenv/` written by either major is reusable by the other (the eval cache
+  is keyed on the devenv version).
+- `devenv up -d` works; `devenv processes down` may time out and SIGKILL the
+  process group without stopping the service's children.
+- `.devenv/` lives in the project root, so in a sandbox it is part of the
+  workspace and persists with it. Under `--clone` the workspace is inside the
+  sandbox, and a recreate discards `.devenv/state` along with any service data
+  it holds (a Postgres database, for example).
+- Once a repo moves to 2.x modules, built-in services (Postgres, Redis, and
+  others) pick the next free port when their base port is taken. Set
+  `strict_ports: true` in `devenv.yaml` when a kit publishes or another tool
+  expects a fixed port, so a conflict fails instead of silently moving the
+  service.
+- SecretSpec is opt-in (`secretspec.enable` in `devenv.yaml`, or
+  `SECRETSPEC_PROVIDER`/`SECRETSPEC_PROFILE`). On missing secrets it prompts
+  only when stdin is a terminal, which an agent's PTY can be; otherwise it
+  fails.
+
 Everything else is a kit's job:
 
 - **Runtime CA trust** — e.g. the `zscaler-ca-certificate` kit; the image pins
@@ -53,6 +90,7 @@ docker build --build-arg EXTRA_CA_CERT="$(cat proxy-root-ca.crt)" .
 ## Versioning
 
 [`VERSION`](VERSION) is the published tag, bumped together with any toolchain
-change (`NIXPKGS_REV`, installer version, base image); tags are never reused —
+change (`NIXPKGS_REV`, installer version, base image), with a major bump when
+the devenv major changes; tags are never reused —
 the workflow refuses to republish an existing version tag. A moving `latest`
 also exists — pin the version tag in anything durable.
diff --git a/integrations/isolation/images/devenv/VERSION b/integrations/isolation/images/devenv/VERSION
index 3eefcb9d..227cea21 100644
--- a/integrations/isolation/images/devenv/VERSION
+++ b/integrations/isolation/images/devenv/VERSION
@@ -1 +1 @@
-1.0.0
+2.0.0