From 8f46c6d3d7acfb9ad5748d058aebfebe88f58f05 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <admin@thomashoneyman.com>
Date: Mon, 20 Jul 2026 20:07:55 +0000
Subject: [PATCH 1/5] Add Amp orb lifecycle setup

---
 .agents/resume |  9 +++++++++
 .agents/setup  | 31 +++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100755 .agents/resume
 create mode 100755 .agents/setup

diff --git a/.agents/resume b/.agents/resume
new file mode 100755
index 00000000..16326960
--- /dev/null
+++ b/.agents/resume
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Nix supplies the repository's complete development toolchain. Repair its
+# daemon after an orb pause if systemd did not restore it automatically.
+if systemctl is-enabled --quiet nix-daemon.service \
+  && ! systemctl is-active --quiet nix-daemon.service; then
+  sudo systemctl start nix-daemon.service
+fi
diff --git a/.agents/setup b/.agents/setup
new file mode 100755
index 00000000..2c60d26f
--- /dev/null
+++ b/.agents/setup
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "Installing orb prerequisites..."
+if ! command -v direnv >/dev/null 2>&1; then
+  sudo apt-get update
+  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y direnv
+fi
+
+if ! command -v nix >/dev/null 2>&1 \
+  && [ ! -x /nix/var/nix/profiles/default/bin/nix ]; then
+  curl --proto '=https' --tlsv1.2 -fsSL https://install.determinate.systems/nix \
+    | sh -s -- install --no-confirm
+fi
+
+# The installer updates future login shells, but this setup process also needs Nix.
+if [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+  # shellcheck disable=SC1091
+  source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+fi
+
+# Amp commands use non-login shells, so expose Nix on their existing PATH too.
+mkdir -p "$HOME/.local/bin"
+ln -sfn /nix/var/nix/profiles/default/bin/nix "$HOME/.local/bin/nix"
+
+echo "Preparing the pinned Nix development environment..."
+direnv allow .
+direnv exec . npm ci
+direnv exec . spago build
+
+echo "Orb setup complete."

From ba15fe1bda39a022e67bf382522adae505b8ad29 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <admin@thomashoneyman.com>
Date: Mon, 20 Jul 2026 20:07:55 +0000
Subject: [PATCH 2/5] Keep orb resume hook minimal

---
 .agents/resume | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/.agents/resume b/.agents/resume
index 16326960..414f43e4 100755
--- a/.agents/resume
+++ b/.agents/resume
@@ -1,9 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Nix supplies the repository's complete development toolchain. Repair its
-# daemon after an orb pause if systemd did not restore it automatically.
-if systemctl is-enabled --quiet nix-daemon.service \
-  && ! systemctl is-active --quiet nix-daemon.service; then
-  sudo systemctl start nix-daemon.service
-fi
+# The repository has no persistent local services to repair after an orb wake.
+:

From 99e5450b11e7bd2d2ab79c71b0dc1736daa1d329 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <admin@thomashoneyman.com>
Date: Mon, 20 Jul 2026 20:07:55 +0000
Subject: [PATCH 3/5] Document orb development environment usage

---
 .agents/resume | 4 +++-
 AGENTS.md      | 7 +++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/.agents/resume b/.agents/resume
index 414f43e4..cc551fc9 100755
--- a/.agents/resume
+++ b/.agents/resume
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# The repository has no persistent local services to repair after an orb wake.
+# The repository currently has no persistent local services to repair after an
+# orb wake. If services are added, declare them in .amp/services.yaml and run
+# `amp orb services ensure` here rather than starting unmanaged processes.
 :
diff --git a/AGENTS.md b/AGENTS.md
index 4347a244..150c031c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,6 +13,13 @@ We use Nix with direnv. Expect to be in a Nix shell automatically, but if you ar
 nix develop
 ```
 
+In Amp orbs, non-login command shells do not automatically load `.envrc`. Prefix commands that need the development environment with `direnv exec .`, for example:
+
+```sh
+direnv exec . spago build
+direnv exec . spago test
+```
+
 ### Nix Quirks
 
 - If Nix tries to fetch from git during a build and fails, then most likely `spago.yaml` files have been changed but the lockfiles were not updated. Update them with `spago build`.

From 2102568c5585246a29132855d397679700defa6b Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <admin@thomashoneyman.com>
Date: Mon, 20 Jul 2026 20:07:55 +0000
Subject: [PATCH 4/5] Activate Nix environment in orb terminals

---
 .agents/setup | 6 ++++++
 AGENTS.md     | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/.agents/setup b/.agents/setup
index 2c60d26f..8f90092f 100755
--- a/.agents/setup
+++ b/.agents/setup
@@ -7,6 +7,12 @@ if ! command -v direnv >/dev/null 2>&1; then
   sudo DEBIAN_FRONTEND=noninteractive apt-get install -y direnv
 fi
 
+# Make the repository's existing .envrc activate in interactive orb terminals.
+direnv_hook='eval "$(direnv hook bash)"'
+if ! grep -Fqx "$direnv_hook" "$HOME/.bashrc"; then
+  printf '\n%s\n' "$direnv_hook" >> "$HOME/.bashrc"
+fi
+
 if ! command -v nix >/dev/null 2>&1 \
   && [ ! -x /nix/var/nix/profiles/default/bin/nix ]; then
   curl --proto '=https' --tlsv1.2 -fsSL https://install.determinate.systems/nix \
diff --git a/AGENTS.md b/AGENTS.md
index 150c031c..eaefab60 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,7 @@ We use Nix with direnv. Expect to be in a Nix shell automatically, but if you ar
 nix develop
 ```
 
-In Amp orbs, non-login command shells do not automatically load `.envrc`. Prefix commands that need the development environment with `direnv exec .`, for example:
+Orb setup configures interactive terminals to load `.envrc` automatically, so bare commands such as `spago build` work there. Amp's non-login command shells do not load `.envrc`; in those shells, prefix commands that need the development environment with `direnv exec .`, for example:
 
 ```sh
 direnv exec . spago build

From c922cc079dd50524ba0af046a86e6aa1f66b623d Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <admin@thomashoneyman.com>
Date: Mon, 20 Jul 2026 20:07:55 +0000
Subject: [PATCH 5/5] Enter Nix environment during orb setup

---
 .agents/setup | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.agents/setup b/.agents/setup
index 8f90092f..8653fe95 100755
--- a/.agents/setup
+++ b/.agents/setup
@@ -31,7 +31,8 @@ ln -sfn /nix/var/nix/profiles/default/bin/nix "$HOME/.local/bin/nix"
 
 echo "Preparing the pinned Nix development environment..."
 direnv allow .
-direnv exec . npm ci
-direnv exec . spago build
+eval "$(direnv export bash)"
+npm ci
+spago build
 
 echo "Orb setup complete."