diff --git a/.agents/setup b/.agents/setup
new file mode 100755
index 0000000000..68571288bd
--- /dev/null
+++ b/.agents/setup
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Prepares a fresh Amp orb: Rust stable, Python 3.12 and the locked uv environment with the
+# native extension built. Idempotent; a warm run on a restored snapshot only re-verifies.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+step() {
+  local name="$1"
+  shift
+  local start=$SECONDS
+  echo "==> ${name}"
+  "$@"
+  echo "<== ${name} ($((SECONDS - start))s)"
+}
+
+# One persistent Cargo target directory per worktree, outside the repository (see AGENTS.md).
+target_dir="$HOME/.cache/cargo-target/$(basename "$repo_root")"
+export CARGO_TARGET_DIR="$target_dir"
+export PATH="$HOME/.cargo/bin:$PATH"
+
+install_rust() {
+  if ! command -v rustup >/dev/null 2>&1; then
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+      | sh -s -- -y --no-modify-path --profile minimal --default-toolchain stable \
+        --component clippy --component rustfmt
+  else
+    # CI lints with the latest stable toolchain.
+    rustup update stable --no-self-update
+    rustup component add clippy rustfmt --toolchain stable
+  fi
+}
+
+persist_env() {
+  local marker="# sqlbuild orb environment (${repo_root})"
+  if ! grep -Fqx "$marker" "$HOME/.bash_profile" 2>/dev/null; then
+    cat >>"$HOME/.bash_profile" <<EOF
+
+$marker
+export PATH="\$HOME/.cargo/bin:\$PATH"
+export CARGO_TARGET_DIR="$target_dir"
+EOF
+  fi
+}
+
+step "Rust stable toolchain" install_rust
+step "Persist shell environment" persist_env
+step "Python 3.12" uv python install 3.12
+step "uv sync (builds native extension)" uv sync --locked --all-groups --all-extras --python 3.12
+
+echo "Setup complete: $(rustc --version), $(uv run --no-sync python --version)"
diff --git a/.gitignore b/.gitignore
index dc92e3bbcf..3bf9e0897f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,6 +57,7 @@ target/
 *.pyd
 *.dylib
 .dlt/
+.amp/portals/*
 
 # Local SQLBuild overrides
 sqlbuild_local.yml