From b7d89468ad61e092d9e73620c528f501dbaa4af2 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:18:14 -0600
Subject: [PATCH 1/2] Add Amp orb setup: pinned Node/pnpm via mise, deps,
 dev-server service

.agents/setup installs mise, the Node and pnpm versions pinned in
.tool-versions, and pnpm dependencies, and exposes the toolchain to
login shells. .agents/resume confirms the toolchain on each wake.
.amp/services.yaml lets Amp run the Next.js dev server as a portal.

Amp-Thread-ID: https://ampcode.com/threads/T-01a07559-806b-70af-a96d-7281168ade61
Co-authored-by: Amp <amp@ampcode.com>
---
 .agents/resume     |  9 +++++++++
 .agents/setup      | 44 ++++++++++++++++++++++++++++++++++++++++++++
 .amp/services.yaml |  7 +++++++
 .gitignore         |  3 +++
 4 files changed, 63 insertions(+)
 create mode 100755 .agents/resume
 create mode 100755 .agents/setup
 create mode 100644 .amp/services.yaml

diff --git a/.agents/resume b/.agents/resume
new file mode 100755
index 000000000..2eff8e6a5
--- /dev/null
+++ b/.agents/resume
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Runs on every orb wake. Nothing to authenticate or reconnect; just confirm the
+# toolchain from .agents/setup still resolves so a broken snapshot fails loudly.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+eval "$("$HOME/.local/bin/mise" -C "$repo_root" env -s bash)"
+node --version
+pnpm --version
diff --git a/.agents/setup b/.agents/setup
new file mode 100755
index 000000000..beb6e9199
--- /dev/null
+++ b/.agents/setup
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Prepares a fresh Amp orb: the Node and pnpm versions pinned in .tool-versions,
+# then the pnpm dependencies. Idempotent: Amp reruns it on stale snapshots.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+step() { printf '\n==> %s (%s)\n' "$1" "$(date +%T)"; }
+
+mise_bin="$HOME/.local/bin/mise"
+step "Install mise"
+if [ ! -x "$mise_bin" ]; then
+	curl -fsSL https://mise.run | sh
+fi
+
+step "Install pinned toolchain from .tool-versions"
+"$mise_bin" install --yes
+# The installer cannot change this running script's environment.
+eval "$("$mise_bin" env -s bash)"
+
+step "Expose the toolchain to login shells"
+profile_marker="# sourcegraph/docs: pinned Node and pnpm from mise"
+if ! grep -Fqx "$profile_marker" "$HOME/.bash_profile" 2>/dev/null; then
+	cat >>"$HOME/.bash_profile" <<EOF
+
+$profile_marker
+[ -d "$repo_root" ] && eval "\$("$mise_bin" -C "$repo_root" env -s bash)"
+EOF
+fi
+
+step "Install dependencies"
+pnpm install --frozen-lockfile
+
+step "Write orb agent guidance"
+mkdir -p "$HOME/.config/amp"
+cat >"$HOME/.config/amp/AGENTS.md" <<'EOF'
+# Inside the Orb
+
+- Node and pnpm come from mise (`.tool-versions`); `.agents/setup` puts them on PATH for login shells. Use `pnpm`, not `npm`.
+- Dev server: `amp orb services ensure` starts `pnpm dev` from `.amp/services.yaml` and returns a portal link.
+EOF
+
+step "Done: node $(node --version), pnpm $(pnpm --version)"
diff --git a/.amp/services.yaml b/.amp/services.yaml
new file mode 100644
index 000000000..cccb74b59
--- /dev/null
+++ b/.amp/services.yaml
@@ -0,0 +1,7 @@
+services:
+  docs:
+    command: pnpm dev --hostname 0.0.0.0 --port "$PORT"
+    health: /
+    portal:
+      url: /
+      title: Sourcegraph Docs
diff --git a/.gitignore b/.gitignore
index 968a8330e..ff9bc8266 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,4 +52,7 @@ public/changelog.rss
 # env file
 .env
 
+# amp orb portal state
+.amp/portals/
+
 public/technical-changelog.rss

From 44278f5ebade9ce7bb30f2780981d9a9ec6c8009 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:25:59 -0600
Subject: [PATCH 2/2] Run pnpm install with CI=true so setup never waits on a
 TTY

---
 .agents/setup | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.agents/setup b/.agents/setup
index beb6e9199..5ca196193 100755
--- a/.agents/setup
+++ b/.agents/setup
@@ -30,7 +30,9 @@ EOF
 fi
 
 step "Install dependencies"
-pnpm install --frozen-lockfile
+# CI=true: without a TTY, pnpm otherwise aborts if a stale snapshot's
+# node_modules was built by a different pnpm version and must be recreated.
+CI=true pnpm install --frozen-lockfile
 
 step "Write orb agent guidance"
 mkdir -p "$HOME/.config/amp"