From f0fb693bec9a52a74b69dcfde1523058f5e44983 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Fri, 12 Dec 2025 14:59:33 -0500
Subject: [PATCH 01/49] feat: added new workflows and updated package.json

---
 .github/workflows/preview-release.yml  | 335 +++++++++++++++++++++++++
 .github/workflows/snapshot-release.yml |  97 +++++++
 package.json                           |   2 +
 3 files changed, 434 insertions(+)
 create mode 100644 .github/workflows/preview-release.yml
 create mode 100644 .github/workflows/snapshot-release.yml

diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
new file mode 100644
index 000000000..d65863ebd
--- /dev/null
+++ b/.github/workflows/preview-release.yml
@@ -0,0 +1,335 @@
+name: Preview Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      custom_suffix:
+        description: 'Custom suffix (overrides branch name)'
+        type: string
+        required: false
+      skip_npm:
+        description: 'Skip NPM publishing'
+        type: boolean
+        default: false
+      skip_docker:
+        description: 'Skip Docker builds'
+        type: boolean
+        default: false
+      force_pr_comment:
+        description: 'Force PR comment even if no PR detected'
+        type: boolean
+        default: false
+
+concurrency:
+  group: prerelease-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  validate-and-prepare:
+    name: Validate Branch & Prepare
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    if: github.repository == 'namehash/ensnode'
+    outputs:
+      branch-suffix: ${{ steps.prepare.outputs.branch-suffix }}
+      dist-tag: ${{ steps.prepare.outputs.dist-tag }}
+      snapshot-tag: ${{ steps.prepare.outputs.snapshot-tag }}
+      docker-tag-base: ${{ steps.prepare.outputs.docker-tag-base }}
+      commit-sha: ${{ steps.prepare.outputs.commit-sha }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate branch
+        run: |
+          if [[ "${{ github.ref_name }}" == "main" ]]; then
+            echo "❌ Cannot run prerelease workflow on main branch"
+            echo "Use the snapshot workflow instead for main branch previews"
+            exit 1
+          fi
+          echo "✅ Branch validation passed: ${{ github.ref_name }}"
+
+      - name: Prepare tags and identifiers
+        id: prepare
+        run: |
+          # Get short commit SHA
+          COMMIT_SHA=$(git rev-parse --short HEAD)
+
+          # Sanitize branch name for use in versions and tags
+          if [[ -n "${{ inputs.custom_suffix }}" ]]; then
+            BRANCH_SUFFIX="${{ inputs.custom_suffix }}"
+          else
+            BRANCH_SUFFIX="${{ github.ref_name }}"
+            # Replace / with -
+            BRANCH_SUFFIX="${BRANCH_SUFFIX//\//-}"
+            # Replace special characters with -
+            BRANCH_SUFFIX="${BRANCH_SUFFIX//[^a-zA-Z0-9-]/-}"
+            # Convert to lowercase
+            BRANCH_SUFFIX=$(echo "$BRANCH_SUFFIX" | tr '[:upper:]' '[:lower:]')
+            # Remove consecutive dashes (repeat until no more changes)
+            while [[ "$BRANCH_SUFFIX" =~ --+ ]]; do
+              BRANCH_SUFFIX="${BRANCH_SUFFIX//--/-}"
+            done
+            # Truncate to 30 characters
+            BRANCH_SUFFIX="${BRANCH_SUFFIX:0:30}"
+            # Remove trailing dashes
+            BRANCH_SUFFIX="${BRANCH_SUFFIX%-}"
+            # Remove leading dashes
+            BRANCH_SUFFIX="${BRANCH_SUFFIX#-}"
+          fi
+
+          # Create dist-tag (NPM doesn't allow dots in tags)
+          DIST_TAG="preview-${BRANCH_SUFFIX}"
+
+          # Snapshot tag for changesets (used in version string)
+          SNAPSHOT_TAG="preview-${BRANCH_SUFFIX}"
+
+          # Docker tag base (no version, just branch)
+          DOCKER_TAG_BASE="preview-${BRANCH_SUFFIX}"
+
+          echo "branch-suffix=${BRANCH_SUFFIX}" >> $GITHUB_OUTPUT
+          echo "dist-tag=${DIST_TAG}" >> $GITHUB_OUTPUT
+          echo "snapshot-tag=${SNAPSHOT_TAG}" >> $GITHUB_OUTPUT
+          echo "docker-tag-base=${DOCKER_TAG_BASE}" >> $GITHUB_OUTPUT
+          echo "commit-sha=${COMMIT_SHA}" >> $GITHUB_OUTPUT
+
+          echo "🏷️  NPM dist-tag: ${DIST_TAG}"
+          echo "📸 Snapshot tag: ${SNAPSHOT_TAG}"
+          echo "🐳 Docker tag base: ${DOCKER_TAG_BASE}"
+          echo "📝 Commit SHA: ${COMMIT_SHA}"
+
+  build-and-publish-npm:
+    name: Build & Publish NPM
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    needs: validate-and-prepare
+    if: inputs.skip_npm != true
+    permissions:
+      contents: read
+      id-token: write
+    outputs:
+      published-version: ${{ steps.publish.outputs.published-version }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: useblacksmith/setup-node@v5
+        with:
+          node-version-file: .nvmrc
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm packages:prepublish
+
+      - name: Version packages with changesets (snapshot)
+        run: |
+          # Use changesets to create snapshot versions
+          # The snapshot tag will be used as part of the version string
+          pnpm changeset version --snapshot ${{ needs.validate-and-prepare.outputs.snapshot-tag }}
+
+          echo "📦 Packages versioned with snapshot tag: ${{ needs.validate-and-prepare.outputs.snapshot-tag }}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish packages with changesets
+        id: publish
+        run: |
+          # Publish with changesets using snapshot mode
+          # --no-git-tag: Don't create git tags for preview releases
+          # --snapshot: Publish as snapshot/preview release
+          # --tag: Use our custom dist-tag
+          pnpm changeset publish --no-git-tag --snapshot --tag ${{ needs.validate-and-prepare.outputs.dist-tag }}
+
+          # Extract published version from package.json
+          PUBLISHED_VERSION=$(node -p "require('./packages/ensnode-sdk/package.json').version")
+          echo "published-version=${PUBLISHED_VERSION}" >> $GITHUB_OUTPUT
+
+          echo "✅ Published packages with version: ${PUBLISHED_VERSION}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  build-docker-images:
+    name: Build Docker Images
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    needs: [validate-and-prepare, build-and-publish-npm]
+    if: inputs.skip_docker != true
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        app: [ensindexer, ensadmin, ensapi, ensrainbow]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Build & Push Docker Image
+        uses: ./.github/actions/build_docker_image
+        with:
+          image: ghcr.io/${{ github.repository }}/${{ matrix.app }}
+          dockerfile: apps/${{ matrix.app }}/Dockerfile
+          registry_user: ${{ github.actor }}
+          registry_token: ${{ secrets.GITHUB_TOKEN }}
+          tags: |
+            type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}
+            type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+
+  detect-pr-and-comment:
+    name: Update PR Comment
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    needs: [validate-and-prepare, build-and-publish-npm, build-docker-images]
+    if: always() && (needs.build-and-publish-npm.result == 'success' || needs.build-docker-images.result == 'success' || inputs.force_pr_comment == true)
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Detect PR
+        id: detect-pr
+        run: |
+          # Try to find PR for this branch
+          PR_DATA=$(gh pr list --state=open --head="${{ github.ref_name }}" --base=main --json number,title,url --limit 1)
+
+          if [[ "$PR_DATA" != "[]" && -n "$PR_DATA" ]]; then
+            PR_NUMBER=$(echo "$PR_DATA" | jq -r '.[0].number')
+            PR_TITLE=$(echo "$PR_DATA" | jq -r '.[0].title')
+            PR_URL=$(echo "$PR_DATA" | jq -r '.[0].url')
+
+            echo "pr-number=${PR_NUMBER}" >> $GITHUB_OUTPUT
+            echo "pr-title=${PR_TITLE}" >> $GITHUB_OUTPUT
+            echo "pr-url=${PR_URL}" >> $GITHUB_OUTPUT
+            echo "has-pr=true" >> $GITHUB_OUTPUT
+
+            echo "✅ Found PR #${PR_NUMBER}: ${PR_TITLE}"
+          else
+            echo "has-pr=false" >> $GITHUB_OUTPUT
+            echo "ℹ️  No open PR found for branch ${{ github.ref_name }}"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate comment body
+        id: comment
+        if: steps.detect-pr.outputs.has-pr == 'true' || inputs.force_pr_comment == true
+        run: |
+          # Build timestamp for display
+          BUILD_TIME=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
+
+          # Start building comment
+          COMMENT_BODY="## 🚀 Preview Packages - \`${{ github.ref_name }}\`
+
+          "
+
+          # NPM section
+          if [[ "${{ needs.build-and-publish-npm.result }}" == "success" ]]; then
+            COMMENT_BODY+="**NPM Packages:**
+          \`\`\`bash
+          # Install latest preview for this branch
+          pnpm add @ensnode/datasources@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ensnode-react@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ensrainbow-sdk@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ensnode-schema@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ensnode-sdk@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ponder-subgraph@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ponder-metadata@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ens-referrals@${{ needs.validate-and-prepare.outputs.dist-tag }}
+
+          # Or install specific version
+          pnpm add @ensnode/ensnode-sdk@${{ needs.build-and-publish-npm.outputs.published-version }}
+          \`\`\`
+
+          "
+          fi
+
+          # Docker section
+          if [[ "${{ needs.build-docker-images.result }}" == "success" ]]; then
+            COMMENT_BODY+="**Docker Images:**
+          \`\`\`bash
+          docker pull ghcr.io/namehash/ensnode/ensindexer:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+          docker pull ghcr.io/namehash/ensnode/ensadmin:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+          docker pull ghcr.io/namehash/ensnode/ensapi:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+          docker pull ghcr.io/namehash/ensnode/ensrainbow:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+          \`\`\`
+
+          "
+          fi
+
+          # Build info
+          COMMENT_BODY+="**Build Info:**
+          - 📦 Version: \`${{ needs.build-and-publish-npm.outputs.published-version }}\`
+          - 📝 Commit: \`${{ needs.validate-and-prepare.outputs.commit-sha }}\`
+          - 🌿 Branch: \`${{ github.ref_name }}\`
+          - ⏰ Built: \`${BUILD_TIME}\`
+          - 🔗 [Workflow Run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+
+          ---
+          *🤖 This comment will be updated on subsequent preview builds*
+
+          > **Note:** Preview packages are managed by changesets. NPM dist-tags can be cleaned up manually using \`npm dist-tag rm @ensnode/ensnode-sdk ${{ needs.validate-and-prepare.outputs.dist-tag }}\`"
+
+          # Save to file for proper multiline handling
+          echo "$COMMENT_BODY" > comment_body.txt
+          echo "comment-file=comment_body.txt" >> $GITHUB_OUTPUT
+
+      - name: Find existing comment
+        id: find-comment
+        if: steps.detect-pr.outputs.has-pr == 'true'
+        run: |
+          # Look for existing comment from github-actions bot
+          COMMENT_ID=$(gh pr view ${{ steps.detect-pr.outputs.pr-number }} --json comments --jq '.comments[] | select(.author.login == "github-actions" and (.body | contains("🚀 Preview Packages"))) | .id' | head -1)
+
+          if [[ -n "$COMMENT_ID" ]]; then
+            echo "existing-comment-id=${COMMENT_ID}" >> $GITHUB_OUTPUT
+            echo "✅ Found existing comment ID: ${COMMENT_ID}"
+          else
+            echo "ℹ️  No existing comment found, will create new one"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Update or create PR comment
+        if: steps.detect-pr.outputs.has-pr == 'true'
+        run: |
+          if [[ -n "${{ steps.find-comment.outputs.existing-comment-id }}" ]]; then
+            # Update existing comment
+            gh pr comment ${{ steps.detect-pr.outputs.pr-number }} --edit-last --body-file ${{ steps.comment.outputs.comment-file }}
+            echo "✅ Updated existing PR comment"
+          else
+            # Create new comment
+            gh pr comment ${{ steps.detect-pr.outputs.pr-number }} --body-file ${{ steps.comment.outputs.comment-file }}
+            echo "✅ Created new PR comment"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log summary
+        run: |
+          echo "## 📋 Preview Release Summary"
+          echo "- Branch: ${{ github.ref_name }}"
+          echo "- Published version: ${{ needs.build-and-publish-npm.outputs.published-version }}"
+          echo "- NPM dist-tag: ${{ needs.validate-and-prepare.outputs.dist-tag }}"
+          echo "- Docker tag: ${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}"
+          echo "- NPM publish: ${{ needs.build-and-publish-npm.result }}"
+          echo "- Docker build: ${{ needs.build-docker-images.result }}"
+          echo "- PR detected: ${{ steps.detect-pr.outputs.has-pr }}"
+          if [[ "${{ steps.detect-pr.outputs.has-pr }}" == "true" ]]; then
+            echo "- PR number: #${{ steps.detect-pr.outputs.pr-number }}"
+          fi
diff --git a/.github/workflows/snapshot-release.yml b/.github/workflows/snapshot-release.yml
new file mode 100644
index 000000000..db004ffcc
--- /dev/null
+++ b/.github/workflows/snapshot-release.yml
@@ -0,0 +1,97 @@
+name: Snapshot Release (@next)
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  snapshot:
+    name: Publish Snapshot
+    if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main')
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    permissions:
+      contents: read
+      id-token: write
+    outputs:
+      hasChanges: ${{ steps.snapshot.outputs.hasChanges }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: useblacksmith/setup-node@v5
+        with:
+          node-version-file: .nvmrc
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm packages:prepublish
+
+      - name: Version snapshot
+        id: snapshot
+        run: |
+          pnpm changeset:next
+          # Check if there are any changes to publish
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "hasChanges=true" >> $GITHUB_OUTPUT
+          else
+            echo "hasChanges=false" >> $GITHUB_OUTPUT
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish snapshot
+        if: steps.snapshot.outputs.hasChanges == 'true'
+        run: pnpm changeset-publish:next
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  build-and-push-snapshot-docker-images:
+    name: Build Snapshot Docker Images
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main') && needs.snapshot.outputs.hasChanges == 'true'
+    needs: [snapshot]
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        app: [ensindexer, ensadmin, ensrainbow, ensapi]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Generate snapshot tag
+        id: snapshot-tag
+        run: |
+          TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          SNAPSHOT_TAG="next-${TIMESTAMP}-${SHORT_SHA}"
+          echo "tag=$SNAPSHOT_TAG" >> $GITHUB_OUTPUT
+
+      - name: Build & Push
+        uses: ./.github/actions/build_docker_image
+        with:
+          image: ghcr.io/${{ github.repository }}/${{ matrix.app }}
+          dockerfile: apps/${{ matrix.app }}/Dockerfile
+          registry_user: ${{ github.actor }}
+          registry_token: ${{ secrets.GITHUB_TOKEN }}
+          tags: |
+            type=raw,value=next
+            type=raw,value=${{ steps.snapshot-tag.outputs.tag }}
diff --git a/package.json b/package.json
index 1c82ae5e6..999baac65 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,9 @@
     "test": "vitest --silent passed-only",
     "typecheck": "pnpm -r --parallel --aggregate-output typecheck",
     "changeset": "changeset",
+    "changeset:next": "changeset version --snapshot next",
     "changeset-publish": "changeset publish",
+    "changeset-publish:next": "changeset publish --no-git-tag --snapshot --tag next",
     "packages:prepublish": "pnpm -r prepublish",
     "docker:build:ensnode": "pnpm run -w --parallel \"/^docker:build:.*/\"",
     "docker:build:ensindexer": "docker build -f apps/ensindexer/Dockerfile -t ghcr.io/namehash/ensnode/ensindexer:latest .",

From 514cb5131ef182bc4c4e8e74736a33e7e0f9b19c Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Fri, 12 Dec 2025 15:09:41 -0500
Subject: [PATCH 02/49] chore: updated docs

---
 .../docs/docs/contributing/releases.mdx       | 21 ++++++++-----------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index ce5a6e62e..7189099f1 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -29,19 +29,16 @@ The `changesets/bot` will automatically comment on your PR to either remind you
 
 Upon the publishing of a new release, your change will be included in the produced packages/images and your contributions will be referenced in the GitHub Release notes.
 
-## Publishing Release Candidates (RC) of packages to NPM
+## Preview Releases
 
-Publishing release candidates (RCs) of packages to NPM supports apps outside of the ENSNode monorepo to make use of prerelease packages for testing new ENSNode versions before making a full ENSNode release. Package RCs are published to NPM with the `rc` dist-tag:
+Commits to `main` automatically publish prerelease versions with the `next` dist-tag to NPM. These allow testing of changes before an official release.
 
-1. Ensure your changesets are committed to `main`
-2. Navigate to [Actions > Release NPM RC](https://github.com/namehash/ensnode/actions/workflows/npm-release-rc.yml)
-3. Click "Run workflow" and select the `main` branch
-4. RC packages are published to NPM with the `rc` tag (e.g., `1.0.0-rc.0`)
-5. Install RCs with: `npm install @ensnode/package-name@rc`
+To manually trigger a preview release for a branch that has not been merged to `main`, follow these steps:
+
+1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/preview-release.yml)
+2. Click "Run workflow" and select the target branch
+3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`
 
 **Important notes:**
-- NPM Package RC versions are ephemeral - they don't create commits or modify the repository
-- Each workflow run increments the RC version (rc.0, rc.1, rc.2, etc.)
-- Docker images are NOT built for RCs
-- No GitHub releases or tags are created for RCs
-- The `main` branch remains unchanged with regular versions
+- Preview versions are ephemeral and don't create commits or modify the repository
+- No GitHub releases or tags are created for Preview Releases

From ddd2468707a5ea094c98632169a5d08fb6befdb6 Mon Sep 17 00:00:00 2001
From: Steve Simkins <73185218+stevedylandev@users.noreply.github.com>
Date: Sun, 14 Dec 2025 11:17:47 -0500
Subject: [PATCH 03/49] chore: Apply suggestions from code review

Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
Co-authored-by: Tomek Kopacki <tomasz@kopacki.net>
---
 .github/workflows/preview-release.yml         | 54 +++++++++----------
 .github/workflows/snapshot-release.yml        |  2 +-
 .../docs/docs/contributing/releases.mdx       |  4 +-
 3 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
index d65863ebd..22a0b9f4b 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview-release.yml
@@ -8,11 +8,11 @@ on:
         type: string
         required: false
       skip_npm:
-        description: 'Skip NPM publishing'
+        description: 'Skip preview release of packages to NPM'
         type: boolean
         default: false
       skip_docker:
-        description: 'Skip Docker builds'
+        description: 'Skip preview release of docker images to GitHub'
         type: boolean
         default: false
       force_pr_comment:
@@ -61,23 +61,23 @@ jobs:
             BRANCH_SUFFIX="${{ inputs.custom_suffix }}"
           else
             BRANCH_SUFFIX="${{ github.ref_name }}"
-            # Replace / with -
-            BRANCH_SUFFIX="${BRANCH_SUFFIX//\//-}"
-            # Replace special characters with -
-            BRANCH_SUFFIX="${BRANCH_SUFFIX//[^a-zA-Z0-9-]/-}"
-            # Convert to lowercase
-            BRANCH_SUFFIX=$(echo "$BRANCH_SUFFIX" | tr '[:upper:]' '[:lower:]')
-            # Remove consecutive dashes (repeat until no more changes)
-            while [[ "$BRANCH_SUFFIX" =~ --+ ]]; do
-              BRANCH_SUFFIX="${BRANCH_SUFFIX//--/-}"
-            done
-            # Truncate to 30 characters
-            BRANCH_SUFFIX="${BRANCH_SUFFIX:0:30}"
-            # Remove trailing dashes
-            BRANCH_SUFFIX="${BRANCH_SUFFIX%-}"
-            # Remove leading dashes
-            BRANCH_SUFFIX="${BRANCH_SUFFIX#-}"
           fi
+          # Replace / with -
+          BRANCH_SUFFIX="${BRANCH_SUFFIX//\//-}"
+          # Replace special characters with -
+          BRANCH_SUFFIX="${BRANCH_SUFFIX//[^a-zA-Z0-9-]/-}"
+          # Convert to lowercase
+          BRANCH_SUFFIX=$(echo "$BRANCH_SUFFIX" | tr '[:upper:]' '[:lower:]')
+          # Remove consecutive dashes (repeat until no more changes)
+          while [[ "$BRANCH_SUFFIX" =~ --+ ]]; do
+            BRANCH_SUFFIX="${BRANCH_SUFFIX//--/-}"
+          done
+          # Truncate to 30 characters
+          BRANCH_SUFFIX="${BRANCH_SUFFIX:0:30}"
+          # Remove trailing dashes
+          BRANCH_SUFFIX="${BRANCH_SUFFIX%-}"
+          # Remove leading dashes
+          BRANCH_SUFFIX="${BRANCH_SUFFIX#-}"
 
           # Create dist-tag (NPM doesn't allow dots in tags)
           DIST_TAG="preview-${BRANCH_SUFFIX}"
@@ -94,13 +94,13 @@ jobs:
           echo "docker-tag-base=${DOCKER_TAG_BASE}" >> $GITHUB_OUTPUT
           echo "commit-sha=${COMMIT_SHA}" >> $GITHUB_OUTPUT
 
-          echo "🏷️  NPM dist-tag: ${DIST_TAG}"
+          echo "🏷️ NPM dist-tag: ${DIST_TAG}"
           echo "📸 Snapshot tag: ${SNAPSHOT_TAG}"
           echo "🐳 Docker tag base: ${DOCKER_TAG_BASE}"
           echo "📝 Commit SHA: ${COMMIT_SHA}"
 
   build-and-publish-npm:
-    name: Build & Publish NPM
+    name: Build & Publish Packages to NPM
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: validate-and-prepare
     if: inputs.skip_npm != true
@@ -140,7 +140,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Publish packages with changesets
+      - name: Publish packages to NPM with changesets
         id: publish
         run: |
           # Publish with changesets using snapshot mode
@@ -153,14 +153,14 @@ jobs:
           PUBLISHED_VERSION=$(node -p "require('./packages/ensnode-sdk/package.json').version")
           echo "published-version=${PUBLISHED_VERSION}" >> $GITHUB_OUTPUT
 
-          echo "✅ Published packages with version: ${PUBLISHED_VERSION}"
+          echo "✅ Published packages to NPM with version: ${PUBLISHED_VERSION}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-  build-docker-images:
-    name: Build Docker Images
+  build-and-publish-ghcr:
+    name: Build & Publish Docker Images to GHCR
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: [validate-and-prepare, build-and-publish-npm]
     if: inputs.skip_docker != true
@@ -177,7 +177,7 @@ jobs:
         with:
           fetch-depth: 1
 
-      - name: Build & Push Docker Image
+      - name: Build & Publish Docker Image
         uses: ./.github/actions/build_docker_image
         with:
           image: ghcr.io/${{ github.repository }}/${{ matrix.app }}
@@ -259,7 +259,7 @@ jobs:
           "
           fi
 
-          # Docker section
+          # GHCR section
           if [[ "${{ needs.build-docker-images.result }}" == "success" ]]; then
             COMMENT_BODY+="**Docker Images:**
           \`\`\`bash
@@ -328,7 +328,7 @@ jobs:
           echo "- NPM dist-tag: ${{ needs.validate-and-prepare.outputs.dist-tag }}"
           echo "- Docker tag: ${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}"
           echo "- NPM publish: ${{ needs.build-and-publish-npm.result }}"
-          echo "- Docker build: ${{ needs.build-docker-images.result }}"
+          echo "- GHCR publish: ${{ needs.build-docker-images.result }}"
           echo "- PR detected: ${{ steps.detect-pr.outputs.has-pr }}"
           if [[ "${{ steps.detect-pr.outputs.has-pr }}" == "true" ]]; then
             echo "- PR number: #${{ steps.detect-pr.outputs.pr-number }}"
diff --git a/.github/workflows/snapshot-release.yml b/.github/workflows/snapshot-release.yml
index db004ffcc..dc4482865 100644
--- a/.github/workflows/snapshot-release.yml
+++ b/.github/workflows/snapshot-release.yml
@@ -9,7 +9,7 @@ concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
   snapshot:
-    name: Publish Snapshot
+    name: Publish Snapshot of Packages to NPM
     if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main')
     runs-on: blacksmith-4vcpu-ubuntu-2204
     permissions:
diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 7189099f1..520caac76 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -31,7 +31,7 @@ Upon the publishing of a new release, your change will be included in the produc
 
 ## Preview Releases
 
-Commits to `main` automatically publish prerelease versions with the `next` dist-tag to NPM. These allow testing of changes before an official release.
+Commits to `main` automatically publish prerelease package versions with the `next` dist-tag to NPM. These enable testing of package changes before an official release.
 
 To manually trigger a preview release for a branch that has not been merged to `main`, follow these steps:
 
@@ -40,5 +40,5 @@ To manually trigger a preview release for a branch that has not been merged to `
 3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`
 
 **Important notes:**
-- Preview versions are ephemeral and don't create commits or modify the repository
+- Preview releases are ephemeral and don't create commits or modify the repository
 - No GitHub releases or tags are created for Preview Releases

From cc05a10507b3d7efc5e301060620a60e283e79d9 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 09:15:52 -0500
Subject: [PATCH 04/49] chore: redacted NODE_AUTH_TOKEN

---
 .github/workflows/preview-release.yml  | 1 -
 .github/workflows/snapshot-release.yml | 1 -
 2 files changed, 2 deletions(-)

diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
index 22a0b9f4b..455940062 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview-release.yml
@@ -156,7 +156,6 @@ jobs:
           echo "✅ Published packages to NPM with version: ${PUBLISHED_VERSION}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   build-and-publish-ghcr:
diff --git a/.github/workflows/snapshot-release.yml b/.github/workflows/snapshot-release.yml
index dc4482865..f5a08b5bf 100644
--- a/.github/workflows/snapshot-release.yml
+++ b/.github/workflows/snapshot-release.yml
@@ -56,7 +56,6 @@ jobs:
         run: pnpm changeset-publish:next
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   build-and-push-snapshot-docker-images:

From 89a4dd0f2e99440f42fb1f925b293caa76201cc7 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 09:20:54 -0500
Subject: [PATCH 05/49] chore: removed unused files

---
 .github/workflows/build_ensnode.yml  | 36 --------------------
 .github/workflows/release-npm-rc.yml | 51 ----------------------------
 2 files changed, 87 deletions(-)
 delete mode 100644 .github/workflows/build_ensnode.yml
 delete mode 100644 .github/workflows/release-npm-rc.yml

diff --git a/.github/workflows/build_ensnode.yml b/.github/workflows/build_ensnode.yml
deleted file mode 100644
index 29bfb8f46..000000000
--- a/.github/workflows/build_ensnode.yml
+++ /dev/null
@@ -1,36 +0,0 @@
-name: "Build: ENSNode Images"
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Image Version (Docker Tag)"
-        type: string
-        required: true
-
-jobs:
-  build-and-push-ensnode:
-    name: ${{ matrix.app }}
-    runs-on: blacksmith-4vcpu-ubuntu-2204
-    strategy:
-      fail-fast: false
-      matrix:
-        app: [ensindexer, ensadmin, ensrainbow, ensapi]
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Build & Push
-        uses: ./.github/actions/build_docker_image
-        with:
-          image: ghcr.io/${{ github.repository }}/${{ matrix.app }}
-          dockerfile: apps/${{ matrix.app }}/Dockerfile
-          registry_user: ${{ github.actor }}
-          registry_token: ${{ secrets.GITHUB_TOKEN }}
-          tags: |
-            type=semver,pattern={{version}},value=${{ inputs.version }}
-            type=ref,event=branch
-            type=sha
diff --git a/.github/workflows/release-npm-rc.yml b/.github/workflows/release-npm-rc.yml
deleted file mode 100644
index 841035ca0..000000000
--- a/.github/workflows/release-npm-rc.yml
+++ /dev/null
@@ -1,51 +0,0 @@
-name: Release NPM RC
-
-on:
-  workflow_dispatch:
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  publish-rc:
-    name: Publish Release Candidate Packages to NPM
-    if: github.repository == 'namehash/ensnode'
-    runs-on: blacksmith-4vcpu-ubuntu-2204
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: useblacksmith/setup-node@v5
-        with:
-          node-version-file: .nvmrc
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Enter pre-release mode
-        run: pnpm changeset pre enter rc
-
-      - name: Version packages
-        run: pnpm changeset version
-
-      - name: Build packages
-        run: pnpm packages:prepublish
-
-      - name: Publish to NPM with rc tag
-        run: pnpm changeset publish --tag rc
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Summary
-        run: |
-          echo "✅ Release candidate packages published to NPM with 'rc' tag"
-          echo ""
-          echo "Install with: pnpm install @ensnode/package-name@rc"
-

From ea0ecc0eac344f1e70e5c075dd6d9e65b619493d Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 09:32:49 -0500
Subject: [PATCH 06/49] chore: redacted force_pr_comment and logic

---
 .github/workflows/preview-release.yml | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
index 455940062..b10b00c04 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview-release.yml
@@ -15,10 +15,6 @@ on:
         description: 'Skip preview release of docker images to GitHub'
         type: boolean
         default: false
-      force_pr_comment:
-        description: 'Force PR comment even if no PR detected'
-        type: boolean
-        default: false
 
 concurrency:
   group: prerelease-${{ github.ref_name }}
@@ -191,7 +187,7 @@ jobs:
     name: Update PR Comment
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: [validate-and-prepare, build-and-publish-npm, build-docker-images]
-    if: always() && (needs.build-and-publish-npm.result == 'success' || needs.build-docker-images.result == 'success' || inputs.force_pr_comment == true)
+    if: always() && (needs.build-and-publish-npm.result == 'success' || needs.build-docker-images.result == 'success')
     permissions:
       contents: read
       pull-requests: write
@@ -227,7 +223,7 @@ jobs:
 
       - name: Generate comment body
         id: comment
-        if: steps.detect-pr.outputs.has-pr == 'true' || inputs.force_pr_comment == true
+        if: steps.detect-pr.outputs.has-pr == 'true'
         run: |
           # Build timestamp for display
           BUILD_TIME=$(date -u +"%Y-%m-%d %H:%M:%S UTC")

From 713001f93d268ab79d6870faa7051ce3d5ad970f Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 10:02:44 -0500
Subject: [PATCH 07/49] chore: updated workflow options

---
 .github/workflows/preview-release.yml | 50 ++++++++++++++++++---------
 1 file changed, 33 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
index b10b00c04..c1f56a198 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview-release.yml
@@ -7,14 +7,14 @@ on:
         description: 'Custom suffix (overrides branch name)'
         type: string
         required: false
-      skip_npm:
-        description: 'Skip preview release of packages to NPM'
-        type: boolean
-        default: false
-      skip_docker:
-        description: 'Skip preview release of docker images to GitHub'
-        type: boolean
-        default: false
+      publish_target:
+        description: 'Choose to publish just to NPM or NPM + ghcr'
+        type: choice
+        required: true
+        default: 'npm-and-ghcr'
+        options:
+          - npm-only
+          - npm-and-ghcr
 
 concurrency:
   group: prerelease-${{ github.ref_name }}
@@ -99,7 +99,7 @@ jobs:
     name: Build & Publish Packages to NPM
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: validate-and-prepare
-    if: inputs.skip_npm != true
+    if: inputs.publish_target == 'npm-only' || inputs.publish_target == 'npm-and-ghcr'
     permissions:
       contents: read
       id-token: write
@@ -158,7 +158,7 @@ jobs:
     name: Build & Publish Docker Images to GHCR
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: [validate-and-prepare, build-and-publish-npm]
-    if: inputs.skip_docker != true
+    if: inputs.publish_target == 'npm-and-ghcr'
     permissions:
       contents: read
       packages: write
@@ -186,8 +186,8 @@ jobs:
   detect-pr-and-comment:
     name: Update PR Comment
     runs-on: blacksmith-4vcpu-ubuntu-2204
-    needs: [validate-and-prepare, build-and-publish-npm, build-docker-images]
-    if: always() && (needs.build-and-publish-npm.result == 'success' || needs.build-docker-images.result == 'success')
+    needs: [validate-and-prepare, build-and-publish-npm, build-and-publish-ghcr]
+    if: always() && needs.build-and-publish-npm.result == 'success'
     permissions:
       contents: read
       pull-requests: write
@@ -233,7 +233,7 @@ jobs:
 
           "
 
-          # NPM section
+          # NPM section - always present since both options include NPM
           if [[ "${{ needs.build-and-publish-npm.result }}" == "success" ]]; then
             COMMENT_BODY+="**NPM Packages:**
           \`\`\`bash
@@ -254,8 +254,8 @@ jobs:
           "
           fi
 
-          # GHCR section
-          if [[ "${{ needs.build-docker-images.result }}" == "success" ]]; then
+          # GHCR section - only if ghcr was requested and succeeded
+          if [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" && "${{ needs.build-and-publish-ghcr.result }}" == "success" ]]; then
             COMMENT_BODY+="**Docker Images:**
           \`\`\`bash
           docker pull ghcr.io/namehash/ensnode/ensindexer:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
@@ -264,11 +264,24 @@ jobs:
           docker pull ghcr.io/namehash/ensnode/ensrainbow:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
           \`\`\`
 
+          "
+          elif [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" && "${{ needs.build-and-publish-ghcr.result }}" != "success" ]]; then
+            COMMENT_BODY+="**Docker Images:** ❌ Build failed - see [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+
           "
           fi
 
+          # Publish target info
+          PUBLISH_TARGET_DISPLAY=""
+          if [[ "${{ inputs.publish_target }}" == "npm-only" ]]; then
+            PUBLISH_TARGET_DISPLAY="📦 NPM packages only"
+          elif [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" ]]; then
+            PUBLISH_TARGET_DISPLAY="📦 NPM packages + 🐳 Docker images"
+          fi
+
           # Build info
           COMMENT_BODY+="**Build Info:**
+          - 🎯 Target: \`${PUBLISH_TARGET_DISPLAY}\`
           - 📦 Version: \`${{ needs.build-and-publish-npm.outputs.published-version }}\`
           - 📝 Commit: \`${{ needs.validate-and-prepare.outputs.commit-sha }}\`
           - 🌿 Branch: \`${{ github.ref_name }}\`
@@ -319,11 +332,14 @@ jobs:
         run: |
           echo "## 📋 Preview Release Summary"
           echo "- Branch: ${{ github.ref_name }}"
+          echo "- Publish target: ${{ inputs.publish_target }}"
           echo "- Published version: ${{ needs.build-and-publish-npm.outputs.published-version }}"
           echo "- NPM dist-tag: ${{ needs.validate-and-prepare.outputs.dist-tag }}"
-          echo "- Docker tag: ${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}"
+          if [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" ]]; then
+            echo "- Docker tag: ${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}"
+            echo "- GHCR publish: ${{ needs.build-and-publish-ghcr.result }}"
+          fi
           echo "- NPM publish: ${{ needs.build-and-publish-npm.result }}"
-          echo "- GHCR publish: ${{ needs.build-docker-images.result }}"
           echo "- PR detected: ${{ steps.detect-pr.outputs.has-pr }}"
           if [[ "${{ steps.detect-pr.outputs.has-pr }}" == "true" ]]; then
             echo "- PR number: #${{ steps.detect-pr.outputs.pr-number }}"

From 55f3c3390dcfa7b03c611d64be99cacbc163e150 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 13:49:10 -0500
Subject: [PATCH 08/49] chore: updates based on review comments

---
 .github/workflows/release.yml          | 1 -
 .github/workflows/snapshot-release.yml | 4 ++--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 68726e7db..3c1b54d0f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,7 +1,6 @@
 name: Release
 
 on:
-  workflow_dispatch:
   push:
     branches:
       - main
diff --git a/.github/workflows/snapshot-release.yml b/.github/workflows/snapshot-release.yml
index f5a08b5bf..e4af9e053 100644
--- a/.github/workflows/snapshot-release.yml
+++ b/.github/workflows/snapshot-release.yml
@@ -58,8 +58,8 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-  build-and-push-snapshot-docker-images:
-    name: Build Snapshot Docker Images
+  build-and-publish-ghcr:
+    name: Build & Publish Snapshot Docker Imagess to GHCR
     runs-on: blacksmith-4vcpu-ubuntu-2204
     if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main') && needs.snapshot.outputs.hasChanges == 'true'
     needs: [snapshot]

From a57985147707ce3063f1c4dfebb20e1a65ff6fc0 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 14:15:17 -0500
Subject: [PATCH 09/49] chore: refactored and streamlined node + pnpm setup

---
 .../actions/setup-node-environment/action.yml | 26 +++++++++++++++++
 .github/workflows/preview-release.yml         | 11 ++-----
 .github/workflows/release.yml                 | 11 ++-----
 .github/workflows/snapshot-release.yml        | 11 ++-----
 .github/workflows/test_ci.yml                 | 29 ++++++-------------
 5 files changed, 41 insertions(+), 47 deletions(-)
 create mode 100644 .github/actions/setup-node-environment/action.yml

diff --git a/.github/actions/setup-node-environment/action.yml b/.github/actions/setup-node-environment/action.yml
new file mode 100644
index 000000000..30926897a
--- /dev/null
+++ b/.github/actions/setup-node-environment/action.yml
@@ -0,0 +1,26 @@
+name: 'Setup Node Environment'
+description: 'Sets up pnpm, Node.js, and optionally installs dependencies'
+inputs:
+  install-dependencies:
+    description: 'Run pnpm install --frozen-lockfile'
+    required: false
+    default: 'false'
+  registry-url:
+    description: 'Optional registry URL for npm publishing (passed to setup-node). Required for publishing, not for general CI scripting.'
+    required: false
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup pnpm
+      uses: pnpm/action-setup@v4
+
+    - name: Setup Node.js
+      uses: useblacksmith/setup-node@v5
+      with:
+        node-version-file: .nvmrc
+        registry-url: ${{ inputs.registry-url }}
+
+    - name: Install dependencies
+      if: inputs.install-dependencies == 'true'
+      shell: bash
+      run: pnpm install --frozen-lockfile
diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
index c1f56a198..b8391104a 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview-release.yml
@@ -111,18 +111,11 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
+          install-dependencies: 'true'
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
       - name: Build packages
         run: pnpm packages:prepublish
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3c1b54d0f..9b27ac494 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -25,16 +25,9 @@ jobs:
         with:
           fetch-depth: 1
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+          install-dependencies: 'true'
 
       - name: Create Release Pull Request or Publish to npm
         uses: changesets/action@v1.4.10
diff --git a/.github/workflows/snapshot-release.yml b/.github/workflows/snapshot-release.yml
index e4af9e053..da8e11be7 100644
--- a/.github/workflows/snapshot-release.yml
+++ b/.github/workflows/snapshot-release.yml
@@ -23,18 +23,11 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
+          install-dependencies: 'true'
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
       - name: Build packages
         run: pnpm packages:prepublish
 
diff --git a/.github/workflows/test_ci.yml b/.github/workflows/test_ci.yml
index cb0b82812..6cb35604b 100644
--- a/.github/workflows/test_ci.yml
+++ b/.github/workflows/test_ci.yml
@@ -13,10 +13,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: useblacksmith/setup-node@v5
-        with:
-          node-version-file: .nvmrc
+      - uses: ./.github/actions/setup-node-environment
       - run: pnpm audit --audit-level=moderate
 
   prepublish:
@@ -24,11 +21,9 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
-      - run: pnpm install --frozen-lockfile
+          install-dependencies: 'true'
       - run: pnpm packages:prepublish
 
   static-analysis:
@@ -36,11 +31,9 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
-      - run: pnpm install --frozen-lockfile
+          install-dependencies: 'true'
 
       - name: Run Biome CI
         run: pnpm lint:ci
@@ -56,11 +49,9 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
-      - run: pnpm install --frozen-lockfile
+          install-dependencies: 'true'
       - run: pnpm test
 
   integrity-check:
@@ -83,11 +74,9 @@ jobs:
           --health-retries 5
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: useblacksmith/setup-node@v5
+      - uses: ./.github/actions/setup-node-environment
         with:
-          node-version-file: .nvmrc
-      - run: pnpm install --frozen-lockfile
+          install-dependencies: 'true'
 
       # This will run the dev command in background, and wait up to
       # HEALTH_CHECK_TIMEOUT seconds. It will monitor the log output to

From 9186579b28211aed2d7cbdc523e0adda35aef983 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 14:55:21 -0500
Subject: [PATCH 10/49] chore: updated hosted docs

---
 .../docs/docs/contributing/releases.mdx       | 27 ++++++++++++++-----
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 520caac76..84a8876cf 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -29,16 +29,31 @@ The `changesets/bot` will automatically comment on your PR to either remind you
 
 Upon the publishing of a new release, your change will be included in the produced packages/images and your contributions will be referenced in the GitHub Release notes.
 
-## Preview Releases
+## Previews for Releases
 
-Commits to `main` automatically publish prerelease package versions with the `next` dist-tag to NPM. These enable testing of package changes before an official release.
+There are curently two separate flows for previewing a release: Release Snapshots and Release Previews.
+
+### Release Snapshot
+
+Each commit to `main` will trigger the `snapshot-release.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone who wants to test a package before the stable release. To use snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`. If the `@latest` tag is used then it will only install or run the latest stable release.
+
+**Important notes:**
+- Release snapshots are automatic and cannot be triggered manually.
+- Release snapshots are considered a preview of what will come in a stable release, so there may be unforeseen side effects or bugs that have not been addressed yet.
+
+### Release Preveiw
 
 To manually trigger a preview release for a branch that has not been merged to `main`, follow these steps:
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/preview-release.yml)
-2. Click "Run workflow" and select the target branch
-3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`
+2. Click "Run workflow" and select from the following options:
+ - Which branch you would like to run the preview release workflow on, ideally the branch for an open PR.
+ - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
+ - (Optional) Provide a custom suffix for the preview release package tag. For example, using `my-feature` would result in a tag name of `@ensnode/package-name@preview-my-feature`.
+3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 
 
 **Important notes:**
-- Preview releases are ephemeral and don't create commits or modify the repository
-- No GitHub releases or tags are created for Preview Releases
+- Release previews can only be triggered by authorized NameHash team members.
+- Release previews are ephemeral and don't create commits or modify the repository.
+- Release previews are built off branches that are still under active development. There may be unforeseen side effects or bugs that have not been fixed yet.
+- No GitHub releases or tags are created for Preview Releases.

From 5b696f3b77b7b17fd87b85defe0782faa0a67718 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 15:52:30 -0500
Subject: [PATCH 11/49] chore: updated action and workflow names to snake_case

---
 .../action.yml                                         |  0
 .../{preview-release.yml => preview_release.yml}       |  2 +-
 .github/workflows/release.yml                          |  2 +-
 .../{snapshot-release.yml => snapshot_release.yml}     |  2 +-
 .github/workflows/test_ci.yml                          | 10 +++++-----
 5 files changed, 8 insertions(+), 8 deletions(-)
 rename .github/actions/{setup-node-environment => setup_node_environment}/action.yml (100%)
 rename .github/workflows/{preview-release.yml => preview_release.yml} (99%)
 rename .github/workflows/{snapshot-release.yml => snapshot_release.yml} (98%)

diff --git a/.github/actions/setup-node-environment/action.yml b/.github/actions/setup_node_environment/action.yml
similarity index 100%
rename from .github/actions/setup-node-environment/action.yml
rename to .github/actions/setup_node_environment/action.yml
diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview_release.yml
similarity index 99%
rename from .github/workflows/preview-release.yml
rename to .github/workflows/preview_release.yml
index b8391104a..1428d3170 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview_release.yml
@@ -111,7 +111,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
           registry-url: 'https://registry.npmjs.org'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 9b27ac494..af365153b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -25,7 +25,7 @@ jobs:
         with:
           fetch-depth: 1
 
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
 
diff --git a/.github/workflows/snapshot-release.yml b/.github/workflows/snapshot_release.yml
similarity index 98%
rename from .github/workflows/snapshot-release.yml
rename to .github/workflows/snapshot_release.yml
index da8e11be7..cd4a3d0d8 100644
--- a/.github/workflows/snapshot-release.yml
+++ b/.github/workflows/snapshot_release.yml
@@ -23,7 +23,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
           registry-url: 'https://registry.npmjs.org'
diff --git a/.github/workflows/test_ci.yml b/.github/workflows/test_ci.yml
index 6cb35604b..17af1dc42 100644
--- a/.github/workflows/test_ci.yml
+++ b/.github/workflows/test_ci.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
       - run: pnpm audit --audit-level=moderate
 
   prepublish:
@@ -21,7 +21,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
       - run: pnpm packages:prepublish
@@ -31,7 +31,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
 
@@ -49,7 +49,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
       - run: pnpm test
@@ -74,7 +74,7 @@ jobs:
           --health-retries 5
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup-node-environment
+      - uses: ./.github/actions/setup_node_environment
         with:
           install-dependencies: 'true'
 

From bf0e259bd72d1830d59beb34da05be5b1e4d881b Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 15:56:10 -0500
Subject: [PATCH 12/49] chore: refactored setup_node_environment and affected
 files

---
 .github/actions/setup_node_environment/action.yml | 10 ----------
 .github/workflows/preview_release.yml             |  3 ---
 .github/workflows/release.yml                     |  2 --
 .github/workflows/snapshot_release.yml            |  3 ---
 .github/workflows/test_ci.yml                     |  8 --------
 5 files changed, 26 deletions(-)

diff --git a/.github/actions/setup_node_environment/action.yml b/.github/actions/setup_node_environment/action.yml
index 30926897a..e9638bc81 100644
--- a/.github/actions/setup_node_environment/action.yml
+++ b/.github/actions/setup_node_environment/action.yml
@@ -1,13 +1,5 @@
 name: 'Setup Node Environment'
 description: 'Sets up pnpm, Node.js, and optionally installs dependencies'
-inputs:
-  install-dependencies:
-    description: 'Run pnpm install --frozen-lockfile'
-    required: false
-    default: 'false'
-  registry-url:
-    description: 'Optional registry URL for npm publishing (passed to setup-node). Required for publishing, not for general CI scripting.'
-    required: false
 runs:
   using: 'composite'
   steps:
@@ -18,9 +10,7 @@ runs:
       uses: useblacksmith/setup-node@v5
       with:
         node-version-file: .nvmrc
-        registry-url: ${{ inputs.registry-url }}
 
     - name: Install dependencies
-      if: inputs.install-dependencies == 'true'
       shell: bash
       run: pnpm install --frozen-lockfile
diff --git a/.github/workflows/preview_release.yml b/.github/workflows/preview_release.yml
index 1428d3170..c68558d98 100644
--- a/.github/workflows/preview_release.yml
+++ b/.github/workflows/preview_release.yml
@@ -112,9 +112,6 @@ jobs:
           fetch-depth: 0
 
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
-          registry-url: 'https://registry.npmjs.org'
 
       - name: Build packages
         run: pnpm packages:prepublish
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index af365153b..f4068fb6a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,8 +26,6 @@ jobs:
           fetch-depth: 1
 
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
 
       - name: Create Release Pull Request or Publish to npm
         uses: changesets/action@v1.4.10
diff --git a/.github/workflows/snapshot_release.yml b/.github/workflows/snapshot_release.yml
index cd4a3d0d8..2aa73adc8 100644
--- a/.github/workflows/snapshot_release.yml
+++ b/.github/workflows/snapshot_release.yml
@@ -24,9 +24,6 @@ jobs:
           fetch-depth: 0
 
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
-          registry-url: 'https://registry.npmjs.org'
 
       - name: Build packages
         run: pnpm packages:prepublish
diff --git a/.github/workflows/test_ci.yml b/.github/workflows/test_ci.yml
index 17af1dc42..1e4419d58 100644
--- a/.github/workflows/test_ci.yml
+++ b/.github/workflows/test_ci.yml
@@ -22,8 +22,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
       - run: pnpm packages:prepublish
 
   static-analysis:
@@ -32,8 +30,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
 
       - name: Run Biome CI
         run: pnpm lint:ci
@@ -50,8 +46,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
       - run: pnpm test
 
   integrity-check:
@@ -75,8 +69,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup_node_environment
-        with:
-          install-dependencies: 'true'
 
       # This will run the dev command in background, and wait up to
       # HEALTH_CHECK_TIMEOUT seconds. It will monitor the log output to

From 4ef19709aacc145f8fb47453c6c82d9c68ca204b Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 15:59:42 -0500
Subject: [PATCH 13/49] chore: added type=sha for ghcr publishing

---
 .github/workflows/preview_release.yml  | 1 +
 .github/workflows/snapshot_release.yml | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.github/workflows/preview_release.yml b/.github/workflows/preview_release.yml
index c68558d98..a58287017 100644
--- a/.github/workflows/preview_release.yml
+++ b/.github/workflows/preview_release.yml
@@ -172,6 +172,7 @@ jobs:
           tags: |
             type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}
             type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+            type=sha
 
   detect-pr-and-comment:
     name: Update PR Comment
diff --git a/.github/workflows/snapshot_release.yml b/.github/workflows/snapshot_release.yml
index 2aa73adc8..2cd1f1a25 100644
--- a/.github/workflows/snapshot_release.yml
+++ b/.github/workflows/snapshot_release.yml
@@ -84,3 +84,4 @@ jobs:
           tags: |
             type=raw,value=next
             type=raw,value=${{ steps.snapshot-tag.outputs.tag }}
+            type=sha

From 19a50eae3b30038f38455d81431a07b6a73cf782 Mon Sep 17 00:00:00 2001
From: Steve Simkins <73185218+stevedylandev@users.noreply.github.com>
Date: Mon, 15 Dec 2025 19:45:04 -0500
Subject: [PATCH 14/49] chore: Apply suggestions from code review

Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
---
 .github/workflows/preview_release.yml                | 12 ++++++------
 .github/workflows/snapshot_release.yml               |  2 +-
 .../src/content/docs/docs/contributing/releases.mdx  |  4 ++--
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/preview_release.yml b/.github/workflows/preview_release.yml
index a58287017..5f8e43dbe 100644
--- a/.github/workflows/preview_release.yml
+++ b/.github/workflows/preview_release.yml
@@ -8,7 +8,7 @@ on:
         type: string
         required: false
       publish_target:
-        description: 'Choose to publish just to NPM or NPM + ghcr'
+        description: 'Where should the release preview be published?'
         type: choice
         required: true
         default: 'npm-and-ghcr'
@@ -96,7 +96,7 @@ jobs:
           echo "📝 Commit SHA: ${COMMIT_SHA}"
 
   build-and-publish-npm:
-    name: Build & Publish Packages to NPM
+    name: Build & Publish Release Preview Packages to NPM
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: validate-and-prepare
     if: inputs.publish_target == 'npm-only' || inputs.publish_target == 'npm-and-ghcr'
@@ -126,7 +126,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Publish packages to NPM with changesets
+      - name: Publish release preview packages to NPM with changesets
         id: publish
         run: |
           # Publish with changesets using snapshot mode
@@ -139,7 +139,7 @@ jobs:
           PUBLISHED_VERSION=$(node -p "require('./packages/ensnode-sdk/package.json').version")
           echo "published-version=${PUBLISHED_VERSION}" >> $GITHUB_OUTPUT
 
-          echo "✅ Published packages to NPM with version: ${PUBLISHED_VERSION}"
+          echo "✅ Published release preview packages to NPM with version: ${PUBLISHED_VERSION}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -212,7 +212,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Generate comment body
+      - name: Generate PR comment body
         id: comment
         if: steps.detect-pr.outputs.has-pr == 'true'
         run: |
@@ -280,7 +280,7 @@ jobs:
           - 🔗 [Workflow Run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
 
           ---
-          *🤖 This comment will be updated on subsequent preview builds*
+          *🤖 This comment will be updated on subsequent publishing of release previews from the branch associated with this PR*
 
           > **Note:** Preview packages are managed by changesets. NPM dist-tags can be cleaned up manually using \`npm dist-tag rm @ensnode/ensnode-sdk ${{ needs.validate-and-prepare.outputs.dist-tag }}\`"
 
diff --git a/.github/workflows/snapshot_release.yml b/.github/workflows/snapshot_release.yml
index 2cd1f1a25..00f54b00f 100644
--- a/.github/workflows/snapshot_release.yml
+++ b/.github/workflows/snapshot_release.yml
@@ -49,7 +49,7 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   build-and-publish-ghcr:
-    name: Build & Publish Snapshot Docker Imagess to GHCR
+    name: Build & Publish Snapshot Docker Images to GHCR
     runs-on: blacksmith-4vcpu-ubuntu-2204
     if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main') && needs.snapshot.outputs.hasChanges == 'true'
     needs: [snapshot]
diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 84a8876cf..a0fec7c4d 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -35,13 +35,13 @@ There are curently two separate flows for previewing a release: Release Snapshot
 
 ### Release Snapshot
 
-Each commit to `main` will trigger the `snapshot-release.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone who wants to test a package before the stable release. To use snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`. If the `@latest` tag is used then it will only install or run the latest stable release.
+Each commit to `main` will trigger the `snapshot-release.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`. If the `@latest` tag is used then it will only install or run the latest stable release.
 
 **Important notes:**
 - Release snapshots are automatic and cannot be triggered manually.
 - Release snapshots are considered a preview of what will come in a stable release, so there may be unforeseen side effects or bugs that have not been addressed yet.
 
-### Release Preveiw
+### Release Preview
 
 To manually trigger a preview release for a branch that has not been merged to `main`, follow these steps:
 

From 81e692fca5442b4f966b1dab0131af082a955639 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 19:45:50 -0500
Subject: [PATCH 15/49] chore: renamed workflows

---
 .github/workflows/preview_release.yml  | 2 +-
 .github/workflows/snapshot_release.yml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/preview_release.yml b/.github/workflows/preview_release.yml
index 5f8e43dbe..ae1a1825f 100644
--- a/.github/workflows/preview_release.yml
+++ b/.github/workflows/preview_release.yml
@@ -1,4 +1,4 @@
-name: Preview Release
+name: Release Preview (@preview)
 
 on:
   workflow_dispatch:
diff --git a/.github/workflows/snapshot_release.yml b/.github/workflows/snapshot_release.yml
index 00f54b00f..e3bd6fd1d 100644
--- a/.github/workflows/snapshot_release.yml
+++ b/.github/workflows/snapshot_release.yml
@@ -1,4 +1,4 @@
-name: Snapshot Release (@next)
+name: Release Snapshot (@next)
 
 on:
   push:

From c9027f17e026dec536322267a45b4277cbcdb839 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Mon, 15 Dec 2025 19:47:34 -0500
Subject: [PATCH 16/49] chore: updated description for custom_suffix

---
 .github/workflows/preview_release.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/preview_release.yml b/.github/workflows/preview_release.yml
index ae1a1825f..5379893d1 100644
--- a/.github/workflows/preview_release.yml
+++ b/.github/workflows/preview_release.yml
@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       custom_suffix:
-        description: 'Custom suffix (overrides branch name)'
+        description: 'Optional custom suffix to append to the tag assigned to all assets published in the release preview. If not defined, defaults to the name of the branch associated with the release preview.'
         type: string
         required: false
       publish_target:

From e886445157c40e8023a72039146931bc00b4ad7d Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Tue, 16 Dec 2025 11:07:40 -0500
Subject: [PATCH 17/49] chore: updated docs

---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index a0fec7c4d..820791362 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -47,9 +47,9 @@ To manually trigger a preview release for a branch that has not been merged to `
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/preview-release.yml)
 2. Click "Run workflow" and select from the following options:
- - Which branch you would like to run the preview release workflow on, ideally the branch for an open PR.
+ - Which branch you would like to run the preview release workflow on, ideally the branch for an open PR. The workflow needs a target branch to build and publish for.
  - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
- - (Optional) Provide a custom suffix for the preview release package tag. For example, using `my-feature` would result in a tag name of `@ensnode/package-name@preview-my-feature`.
+ - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting package name would be `@ensnode/package-name@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 
 
 **Important notes:**

From 774406d8e84a6358e6fab8a61a8222414067ffb0 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 17:16:36 -0500
Subject: [PATCH 18/49] chore: update action description

---
 .github/actions/setup_node_environment/action.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/actions/setup_node_environment/action.yml b/.github/actions/setup_node_environment/action.yml
index e9638bc81..081702cae 100644
--- a/.github/actions/setup_node_environment/action.yml
+++ b/.github/actions/setup_node_environment/action.yml
@@ -1,5 +1,5 @@
 name: 'Setup Node Environment'
-description: 'Sets up pnpm, Node.js, and optionally installs dependencies'
+description: 'Sets up pnpm, Node.js, and installs dependencies'
 runs:
   using: 'composite'
   steps:

From f53896c9855a83bf5124d12513e06e403ce9d994 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 17:19:57 -0500
Subject: [PATCH 19/49] chore: renamed workflow files

---
 .github/workflows/{preview_release.yml => release_preview.yml}   | 0
 .github/workflows/{snapshot_release.yml => release_snapshot.yml} | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 rename .github/workflows/{preview_release.yml => release_preview.yml} (100%)
 rename .github/workflows/{snapshot_release.yml => release_snapshot.yml} (100%)

diff --git a/.github/workflows/preview_release.yml b/.github/workflows/release_preview.yml
similarity index 100%
rename from .github/workflows/preview_release.yml
rename to .github/workflows/release_preview.yml
diff --git a/.github/workflows/snapshot_release.yml b/.github/workflows/release_snapshot.yml
similarity index 100%
rename from .github/workflows/snapshot_release.yml
rename to .github/workflows/release_snapshot.yml

From f08cfe2bc137aa444a7ac24fd2f7f2aeb607046d Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 17:21:49 -0500
Subject: [PATCH 20/49] chore: updated workflow names in docs

---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 820791362..ece31b2d1 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -35,7 +35,7 @@ There are curently two separate flows for previewing a release: Release Snapshot
 
 ### Release Snapshot
 
-Each commit to `main` will trigger the `snapshot-release.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`. If the `@latest` tag is used then it will only install or run the latest stable release.
+Each commit to `main` will trigger the `release_snapshot.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`. If the `@latest` tag is used then it will only install or run the latest stable release.
 
 **Important notes:**
 - Release snapshots are automatic and cannot be triggered manually.
@@ -45,7 +45,7 @@ Each commit to `main` will trigger the `snapshot-release.yml` workflow to build
 
 To manually trigger a preview release for a branch that has not been merged to `main`, follow these steps:
 
-1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/preview-release.yml)
+1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
  - Which branch you would like to run the preview release workflow on, ideally the branch for an open PR. The workflow needs a target branch to build and publish for.
  - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).

From f530d998af229ec3adb9ffb78fc689b2bc7c705b Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 20:58:37 -0500
Subject: [PATCH 21/49] chore: update docs for releases

---
 .../docs/docs/contributing/releases.mdx       | 111 +++++++++++++++---
 1 file changed, 97 insertions(+), 14 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index ece31b2d1..6e6039c28 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -25,35 +25,118 @@ The `changesets/bot` will automatically comment on your PR to either remind you
 - You don't need a changeset for documentation changes or internal refactoring
 - All our packages use "fixed" versioning - they all share the same version number regardless of which package triggered the version bump
 
-## Upon a New Release
+# Creating a Release
 
-Upon the publishing of a new release, your change will be included in the produced packages/images and your contributions will be referenced in the GitHub Release notes.
+Upon the publishing of a new release, your change will be included in the produced packages/images and your contributions will be referenced in the GitHub Release notes. There are three different types of releases that your changes can be included in for produced packages/images.
 
-## Previews for Releases
+## Full Release
 
-There are curently two separate flows for previewing a release: Release Snapshots and Release Previews.
+Workflow File: [release.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release.yml)
 
-### Release Snapshot
+If your PR includes a changeset and is merged to `main` then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to `main` the Release PR will continue to update. Once the Release PR is merged into `main` then it will trigger a stable release with all of the included changesets. It will also create a release on GitHub with autogenerated release notes. When a full release runs it will build and publish packages to NPM and Docker images to GitHub Container Registry (ghcr).
 
-Each commit to `main` will trigger the `release_snapshot.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`. If the `@latest` tag is used then it will only install or run the latest stable release.
+**Important Notes:**
+- Among all release types, only Full Releases are considered stable.
+- Full releases will include the `@latest` tag for published packages/images.
+- All ENSNode packages use "fixed" versioning. Once a full release is published they will all advance to the version indicated in the Release PR based on the included changesets.
+- Only members of the NameHash Labs `ensnode` team have the required permissions to merge the Release PR to `main`.
+- Full releases will create GitHub tags and release notes.
+
+## Snapshot Release
+
+Workflow File: [release_snapshot.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_snapshot.yml)
+
+Each commit to `main` will automatically trigger the `release_snapshot.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`.
 
 **Important notes:**
+- Snapshot releases are part of the pre-stable state of the `main` branch and should be installed with caution until a [full release](#full-release) is published.
 - Release snapshots are automatic and cannot be triggered manually.
-- Release snapshots are considered a preview of what will come in a stable release, so there may be unforeseen side effects or bugs that have not been addressed yet.
+- Snapshot releases will include the `@next` tag for published packages/images.
+- Published packages/images will advance to the version that was included in the changeset of the PR merged to `main`.
+- The `main` branch of `ensnode` is protected. Only PRs approved by the `ensnode` team can be merged to `main` and trigger a snapshot release.
+- No GitHub releases or tags are created for snapshot releases.
 
-### Release Preview
+## Preview Release
 
-To manually trigger a preview release for a branch that has not been merged to `main`, follow these steps:
+Workflow File: [release_preview.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_preview.yml)
+
+In the event that a package needs to be tested with or installed before it is merged into `main` then a preview release can be used. To manually trigger a preview release for a branch, follow these steps:
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - Which branch you would like to run the preview release workflow on, ideally the branch for an open PR. The workflow needs a target branch to build and publish for.
+ - Which branch you would like to run the preview release workflow on. You can choose any branch and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR.
  - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
- - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting package name would be `@ensnode/package-name@preview-users-route`.
+ - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/package-name@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 
 
 **Important notes:**
-- Release previews can only be triggered by authorized NameHash team members.
-- Release previews are ephemeral and don't create commits or modify the repository.
-- Release previews are built off branches that are still under active development. There may be unforeseen side effects or bugs that have not been fixed yet.
+- Preview releases are generally built and published from branches with active PRs. They are not guaranteed to be stable as they are still under active development.
+- Preview releases will include the `@preview-*` tag for published packages/images, followed by either the name of the branch or the custom suffix chosen during in the action trigger.
+- Preview releases can only be triggered by authorized NameHash team members.
+- Preview releases are ephemeral and don't create commits or modify the repository.
 - No GitHub releases or tags are created for Preview Releases.
+
+# Selecting a Release for Deployment or Installation
+
+When installing ENSNode NPM packages or Docker images, you have several release types to choose from depending on your needs and risk tolerance.
+
+## Where to Find Releases
+
+- **NPM Packages**: Available on the [npm registry](https://www.npmjs.com/search?q=%40ensnode) under the `@ensnode` organization
+- **Docker Images**: Available on [GitHub Container Registry](https://github.com/orgs/namehash/packages?repo_name=ensnode)
+- **GitHub Releases**: Full releases are documented with release notes on the [ENSNode GitHub releases page](https://github.com/namehash/ensnode/releases)
+
+## Choosing the Right Release Type
+
+### For Production Use: `@latest` (Full Releases)
+```bash
+npm install @ensnode/package-name@latest
+docker run ghcr.io/namehash/ensnode:latest
+```
+
+**When to use:**
+- When you need maximum stability and reliability
+- When you want thoroughly tested features
+
+**What to expect:**
+- Stable, well-tested releases
+- Complete release notes and changelog entries
+
+### For Development/Testing: `@next` (Snapshot Releases)
+```bash
+npm install @ensnode/package-name@next  
+docker run ghcr.io/namehash/ensnode:next
+```
+
+**When to use:**
+- Development environments
+- When you want to test upcoming features before they're stable
+
+**What to expect:**
+- Latest features and bug fixes from the main branch
+- May contain breaking changes or unstable features
+- More frequent updates (every commit to main)
+
+### For Feature Testing: `@preview-*` (Preview Releases)
+```bash
+npm install @ensnode/package-name@preview-branch-name
+docker run ghcr.io/namehash/ensnode:preview-branch-name
+```
+
+**When to use:**
+- Testing specific features before they're merged
+- Collaborating on development work
+- Validating fixes for specific issues
+
+**What to expect:**
+- Experimental and potentially unstable
+- Built from active development branches
+- May not be compatible with other packages
+
+## Version Selection Best Practices
+
+- Check the GitHub releases page for the latest stable version and release notes
+- Pin specific versions in your integrations rather than using tags like `@latest`
+- Use full releases (`@latest`) as much as possible for stability
+- Only use snapshot releases (`@next`) for experimenting with new features
+- Avoid using preview releases (`@preview`) unless you are actively contributing through a PR

From 64455e36cf998e6795cde106588d42259bb9e9b0 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 21:10:55 -0500
Subject: [PATCH 22/49] chore: updated bullet under preview release docs

---
 docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 6e6039c28..80c8777f0 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -64,7 +64,7 @@ In the event that a package needs to be tested with or installed before it is me
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - Which branch you would like to run the preview release workflow on. You can choose any branch and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR.
+ - Which branch you would like to run the preview release workflow on. You can choose any branch and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR. The GitHub comment will contain helpful installation info such as the generated release tag, which would otherwise have to be located manually through the action logs or the publishing registries.
  - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
  - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/package-name@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 

From f780170480b70d0d30126b49521e8f5921756fdc Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 22:37:39 -0500
Subject: [PATCH 23/49] chore: small docs updates

---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 80c8777f0..d90ce8ef5 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -60,7 +60,7 @@ Each commit to `main` will automatically trigger the `release_snapshot.yml` work
 
 Workflow File: [release_preview.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_preview.yml)
 
-In the event that a package needs to be tested with or installed before it is merged into `main` then a preview release can be used. To manually trigger a preview release for a branch, follow these steps:
+In the event that a package needs to be tested or installed before it is merged into `main`, a preview release can be used. To manually trigger a preview release for a branch, follow these steps:
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
@@ -71,7 +71,7 @@ In the event that a package needs to be tested with or installed before it is me
 
 **Important notes:**
 - Preview releases are generally built and published from branches with active PRs. They are not guaranteed to be stable as they are still under active development.
-- Preview releases will include the `@preview-*` tag for published packages/images, followed by either the name of the branch or the custom suffix chosen during in the action trigger.
+- Preview releases will include the `@preview-*` tag for published packages/images, followed by either the name of the branch or the custom suffix chosen during the action trigger.
 - Preview releases can only be triggered by authorized NameHash team members.
 - Preview releases are ephemeral and don't create commits or modify the repository.
 - No GitHub releases or tags are created for Preview Releases.

From ac6f6d5c4dae3207bd333cddfd224305776e0634 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 22:45:19 -0500
Subject: [PATCH 24/49] chore: small docs updates

---
 docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index d90ce8ef5..50da03b60 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -64,7 +64,7 @@ In the event that a package needs to be tested or installed before it is merged
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - Which branch you would like to run the preview release workflow on. You can choose any branch and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR. The GitHub comment will contain helpful installation info such as the generated release tag, which would otherwise have to be located manually through the action logs or the publishing registries.
+ - Which branch you would like to run the preview release workflow on. You can choose any branch other than `main` and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR. The GitHub comment will contain helpful installation info such as the generated release tag, which would otherwise have to be located manually through the action logs or the publishing registries.
  - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
  - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/package-name@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 

From 9d82bab9e213cddf6d2da3c6eb76ecd44c550a04 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 17 Dec 2025 22:45:35 -0500
Subject: [PATCH 25/49] chore: add docs comments to workflow files

---
 .github/workflows/release.yml          | 31 +++++++++++++++++++
 .github/workflows/release_preview.yml  | 41 ++++++++++++++++++++++++++
 .github/workflows/release_snapshot.yml | 38 ++++++++++++++++++++++++
 3 files changed, 110 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f4068fb6a..b8eaf3e0c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,3 +1,34 @@
+# Full Release Workflow (@latest)
+#
+# This workflow creates stable releases of ENSNode packages and Docker images.
+# It is triggered automatically when the Changesets Release PR is merged to main.
+#
+# How it works:
+# 1. When PRs with changesets are merged to main, the Changesets bot creates/updates a Release PR
+# 2. When the Release PR is merged, this workflow:
+#    - Publishes NPM packages with @latest tag
+#    - Builds and publishes Docker images to GitHub Container Registry with @latest tag
+#    - Creates a GitHub release with version tags and release notes
+#    - Sends Slack notification
+#
+# Published artifacts:
+# - NPM packages: @ensnode/* packages published to npm registry with @latest tag
+# - Docker images: ensindexer, ensadmin, ensapi, ensrainbow published to ghcr.io with @latest tag
+# - GitHub Release: Created with version tag (e.g., v1.2.3) and autogenerated release notes
+#
+# Version management:
+# - All ENSNode packages use "fixed" versioning - they all advance to the same version
+# - The version is determined by the changesets included in the Release PR
+# - Version bump type (major/minor/patch) is based on the changeset severity levels
+#
+# Important notes:
+# - Only Full Releases are considered stable for production use
+# - Only NameHash Labs ensnode team members can merge the Release PR
+# - This workflow does NOT run on regular commits to main (see release_snapshot.yml for that)
+# - GitHub releases and tags are only created for Full Releases
+#
+# Documentation: https://github.com/namehash/ensnode/blob/main/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+
 name: Release
 
 on:
diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index 5379893d1..f053eff6e 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -1,3 +1,44 @@
+# Preview Release Workflow (@preview-*)
+#
+# This workflow creates preview releases for testing features before they are merged to main.
+# It must be triggered manually via GitHub Actions UI.
+#
+# How to trigger:
+# 1. Navigate to Actions > Release Preview in GitHub
+# 2. Click "Run workflow" and select:
+#    - Branch: The branch you want to create a preview release from (typically an active PR branch)
+#    - Publish target: npm-only or npm-and-ghcr (NPM packages + Docker images)
+#    - Custom suffix (optional): Custom tag suffix instead of branch name
+#
+# What it does:
+# 1. Validates the branch (cannot run on main)
+# 2. Generates a sanitized tag from the branch name or custom suffix (e.g., @preview-feat-add-api-route)
+# 3. Versions packages using changesets in snapshot mode
+# 4. Publishes NPM packages with @preview-* dist-tag
+# 5. Optionally builds and publishes Docker images with preview-* tag
+# 6. Posts/updates a comment on the associated PR with installation instructions
+#
+# Published artifacts:
+# - NPM packages: Published with @preview-{branch-name} or @preview-{custom-suffix} tag
+# - Docker images (optional): Published with preview-{branch-name} or preview-{custom-suffix} tag
+# - No GitHub releases or tags are created
+#
+# Use cases:
+# - Testing features before merging to main
+# - Collaborating on development work
+# - Validating fixes for specific issues
+# - QA testing of work-in-progress features
+#
+# Important notes:
+# - Preview releases are NOT stable and should not be used in production
+# - They are ephemeral and don't modify the repository (no commits/tags)
+# - Only authorized NameHash team members can trigger preview releases
+# - Preview releases are built from active development branches
+# - Installation: npm install @ensnode/package-name@preview-branch-name
+# - Cleanup: Use npm dist-tag rm to manually remove preview tags when no longer needed
+#
+# Documentation: https://github.com/namehash/ensnode/blob/main/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+
 name: Release Preview (@preview)
 
 on:
diff --git a/.github/workflows/release_snapshot.yml b/.github/workflows/release_snapshot.yml
index e3bd6fd1d..a0a319873 100644
--- a/.github/workflows/release_snapshot.yml
+++ b/.github/workflows/release_snapshot.yml
@@ -1,3 +1,41 @@
+# Snapshot Release Workflow (@next)
+#
+# This workflow automatically creates snapshot releases for every commit to main.
+# It allows users to install and test the latest features before they become stable releases.
+#
+# How it works:
+# 1. Triggered automatically on every push to main (except Release PR merges)
+# 2. Builds all packages
+# 3. Versions packages using changesets based on the merged PR's changeset
+# 4. Publishes NPM packages with @next tag
+# 5. Builds and publishes Docker images with @next tag to GitHub Container Registry
+#
+# Published artifacts:
+# - NPM packages: All @ensnode/* packages published with @next tag
+# - Docker images: ensindexer, ensadmin, ensapi, ensrainbow published with @next tag
+# - No GitHub releases or tags are created
+#
+# Version behavior:
+# - Packages advance to the version indicated in the changeset of the merged PR
+# - All packages use "fixed" versioning and advance together
+# - Each snapshot represents the pre-stable state of main
+#
+# Use cases:
+# - Development and testing environments
+# - Testing upcoming features before stable release
+# - Experimenting with new functionality
+# - Integration testing with latest main branch
+#
+# Important notes:
+# - Snapshot releases are NOT stable and should be used with caution
+# - Only use @next for development/testing, not production
+# - Automatically triggered - cannot be run manually
+# - Only runs if there are changes to publish (hasChanges check)
+# - Requires PR to be approved by ensnode team (main branch is protected)
+# - Installation: npm install @ensnode/package-name@next
+#
+# Documentation: https://github.com/namehash/ensnode/blob/main/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+
 name: Release Snapshot (@next)
 
 on:

From 1042510aa6a33059358be628893706b534529b8a Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 18 Dec 2025 10:19:48 -0500
Subject: [PATCH 26/49] chore: small docs updates

---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 50da03b60..5be945684 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -37,6 +37,7 @@ If your PR includes a changeset and is merged to `main` then it will automatical
 
 **Important Notes:**
 - Among all release types, only Full Releases are considered stable.
+- Full releases are triggered through merging the Release PR to `main`.
 - Full releases will include the `@latest` tag for published packages/images.
 - All ENSNode packages use "fixed" versioning. Once a full release is published they will all advance to the version indicated in the Release PR based on the included changesets.
 - Only members of the NameHash Labs `ensnode` team have the required permissions to merge the Release PR to `main`.
@@ -71,9 +72,10 @@ In the event that a package needs to be tested or installed before it is merged
 
 **Important notes:**
 - Preview releases are generally built and published from branches with active PRs. They are not guaranteed to be stable as they are still under active development.
+- Preview releases can only be triggered manually.
 - Preview releases will include the `@preview-*` tag for published packages/images, followed by either the name of the branch or the custom suffix chosen during the action trigger.
+- Published packages/images will advance to the version that was included in the changeset of the selected branch.
 - Preview releases can only be triggered by authorized NameHash team members.
-- Preview releases are ephemeral and don't create commits or modify the repository.
 - No GitHub releases or tags are created for Preview Releases.
 
 # Selecting a Release for Deployment or Installation

From 09630640e57b409054c022d8f1c08825a5d775d9 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 18 Dec 2025 10:24:12 -0500
Subject: [PATCH 27/49] chore: small docs updates

---
 .../src/content/docs/docs/contributing/releases.mdx         | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 5be945684..e567bae48 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -35,7 +35,7 @@ Workflow File: [release.yml](https://github.com/namehash/ensnode/blob/main/.gith
 
 If your PR includes a changeset and is merged to `main` then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to `main` the Release PR will continue to update. Once the Release PR is merged into `main` then it will trigger a stable release with all of the included changesets. It will also create a release on GitHub with autogenerated release notes. When a full release runs it will build and publish packages to NPM and Docker images to GitHub Container Registry (ghcr).
 
-**Important Notes:**
+**Important notes:**
 - Among all release types, only Full Releases are considered stable.
 - Full releases are triggered through merging the Release PR to `main`.
 - Full releases will include the `@latest` tag for published packages/images.
@@ -47,7 +47,7 @@ If your PR includes a changeset and is merged to `main` then it will automatical
 
 Workflow File: [release_snapshot.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_snapshot.yml)
 
-Each commit to `main` will automatically trigger the `release_snapshot.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`.
+Each commit to `main` will automatically trigger the `release_snapshot.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the NPM packages or Docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`.
 
 **Important notes:**
 - Snapshot releases are part of the pre-stable state of the `main` branch and should be installed with caution until a [full release](#full-release) is published.
@@ -104,7 +104,7 @@ docker run ghcr.io/namehash/ensnode:latest
 - Stable, well-tested releases
 - Complete release notes and changelog entries
 
-### For Development/Testing: `@next` (Snapshot Releases)
+### For Development/Testing: `@next` (Snapshot releases)
 ```bash
 npm install @ensnode/package-name@next  
 docker run ghcr.io/namehash/ensnode:next

From f9db2f3ee47442fb9b9a2b8ce34ebbbba635e2f4 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 18 Dec 2025 10:31:18 -0500
Subject: [PATCH 28/49] chore: updated documentation links in workflow files

---
 .github/workflows/release.yml          | 2 +-
 .github/workflows/release_preview.yml  | 2 +-
 .github/workflows/release_snapshot.yml | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b8eaf3e0c..23fb50f1a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -27,7 +27,7 @@
 # - This workflow does NOT run on regular commits to main (see release_snapshot.yml for that)
 # - GitHub releases and tags are only created for Full Releases
 #
-# Documentation: https://github.com/namehash/ensnode/blob/main/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+# Documentation: https://ensnode.io/docs/contributing/releases#full-release
 
 name: Release
 
diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index f053eff6e..b543ed43d 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -37,7 +37,7 @@
 # - Installation: npm install @ensnode/package-name@preview-branch-name
 # - Cleanup: Use npm dist-tag rm to manually remove preview tags when no longer needed
 #
-# Documentation: https://github.com/namehash/ensnode/blob/main/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+# Documentation: https://ensnode.io/docs/contributing/releases#preview-release
 
 name: Release Preview (@preview)
 
diff --git a/.github/workflows/release_snapshot.yml b/.github/workflows/release_snapshot.yml
index a0a319873..f6e8f64cb 100644
--- a/.github/workflows/release_snapshot.yml
+++ b/.github/workflows/release_snapshot.yml
@@ -34,7 +34,7 @@
 # - Requires PR to be approved by ensnode team (main branch is protected)
 # - Installation: npm install @ensnode/package-name@next
 #
-# Documentation: https://github.com/namehash/ensnode/blob/main/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+# Documentation: https://ensnode.io/docs/contributing/releases#snapshot-release
 
 name: Release Snapshot (@next)
 

From dd241067de6fbea1422fccd4ed9ea7ff9ecf3e1a Mon Sep 17 00:00:00 2001
From: "lightwalker.eth" <126201998+lightwalker-eth@users.noreply.github.com>
Date: Fri, 19 Dec 2025 12:19:26 +0400
Subject: [PATCH 29/49] Refine terminology

---
 .github/workflows/release_snapshot.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/release_snapshot.yml b/.github/workflows/release_snapshot.yml
index f6e8f64cb..44e9ad9e0 100644
--- a/.github/workflows/release_snapshot.yml
+++ b/.github/workflows/release_snapshot.yml
@@ -1,10 +1,10 @@
-# Snapshot Release Workflow (@next)
+# Release Snapshot Workflow (@next)
 #
 # This workflow automatically creates snapshot releases for every commit to main.
-# It allows users to install and test the latest features before they become stable releases.
+# It allows users to install and test the latest features before they become full releases.
 #
 # How it works:
-# 1. Triggered automatically on every push to main (except Release PR merges)
+# 1. Triggered automatically on every push to main (except (full) Release PR merges)
 # 2. Builds all packages
 # 3. Versions packages using changesets based on the merged PR's changeset
 # 4. Publishes NPM packages with @next tag
@@ -47,7 +47,7 @@ concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
   snapshot:
-    name: Publish Snapshot of Packages to NPM
+    name: Build & Publish Snapshot Packages to NPM
     if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main')
     runs-on: blacksmith-4vcpu-ubuntu-2204
     permissions:

From 2aea319b693eccb2def97fe8c133376c53e48686 Mon Sep 17 00:00:00 2001
From: "lightwalker.eth" <126201998+lightwalker-eth@users.noreply.github.com>
Date: Fri, 19 Dec 2025 12:25:10 +0400
Subject: [PATCH 30/49] Refine terminology

---
 .github/workflows/release_snapshot.yml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/release_snapshot.yml b/.github/workflows/release_snapshot.yml
index 44e9ad9e0..edddacac3 100644
--- a/.github/workflows/release_snapshot.yml
+++ b/.github/workflows/release_snapshot.yml
@@ -46,7 +46,7 @@ on:
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
-  snapshot:
+  build-and-publish-npm:
     name: Build & Publish Snapshot Packages to NPM
     if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main')
     runs-on: blacksmith-4vcpu-ubuntu-2204
@@ -63,10 +63,10 @@ jobs:
 
       - uses: ./.github/actions/setup_node_environment
 
-      - name: Build packages
+      - name: Build snapshot packages
         run: pnpm packages:prepublish
 
-      - name: Version snapshot
+      - name: Version snapshot packages
         id: snapshot
         run: |
           pnpm changeset:next
@@ -79,7 +79,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Publish snapshot
+      - name: Publish snapshot packages to NPM
         if: steps.snapshot.outputs.hasChanges == 'true'
         run: pnpm changeset-publish:next
         env:
@@ -90,7 +90,7 @@ jobs:
     name: Build & Publish Snapshot Docker Images to GHCR
     runs-on: blacksmith-4vcpu-ubuntu-2204
     if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main') && needs.snapshot.outputs.hasChanges == 'true'
-    needs: [snapshot]
+    needs: [build-and-publish-npm]
     permissions:
       contents: read
       packages: write
@@ -104,7 +104,7 @@ jobs:
         with:
           fetch-depth: 1
 
-      - name: Generate snapshot tag
+      - name: Generate docker image snapshot tag
         id: snapshot-tag
         run: |
           TIMESTAMP=$(date +%Y%m%d-%H%M%S)
@@ -112,7 +112,7 @@ jobs:
           SNAPSHOT_TAG="next-${TIMESTAMP}-${SHORT_SHA}"
           echo "tag=$SNAPSHOT_TAG" >> $GITHUB_OUTPUT
 
-      - name: Build & Push
+      - name: Build and publish snapshot docker images to GHCR
         uses: ./.github/actions/build_docker_image
         with:
           image: ghcr.io/${{ github.repository }}/${{ matrix.app }}

From a33b1f2d0d7263ec16fb98cb86d2cb66342e4309 Mon Sep 17 00:00:00 2001
From: "lightwalker.eth" <126201998+lightwalker-eth@users.noreply.github.com>
Date: Fri, 19 Dec 2025 12:33:24 +0400
Subject: [PATCH 31/49] Refine terminology

---
 .github/workflows/release_preview.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index b543ed43d..fe07776de 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -1,18 +1,18 @@
-# Preview Release Workflow (@preview-*)
+# Release Preview Workflow (@preview-*)
 #
 # This workflow creates preview releases for testing features before they are merged to main.
-# It must be triggered manually via GitHub Actions UI.
+# It must be triggered manually via the GitHub Actions UI.
 #
 # How to trigger:
 # 1. Navigate to Actions > Release Preview in GitHub
 # 2. Click "Run workflow" and select:
 #    - Branch: The branch you want to create a preview release from (typically an active PR branch)
 #    - Publish target: npm-only or npm-and-ghcr (NPM packages + Docker images)
-#    - Custom suffix (optional): Custom tag suffix instead of branch name
+#    - Custom tag suffix (optional): Custom tag suffix instead of branch name
 #
 # What it does:
 # 1. Validates the branch (cannot run on main)
-# 2. Generates a sanitized tag from the branch name or custom suffix (e.g., @preview-feat-add-api-route)
+# 2. Generates a sanitized tag from the branch name or custom tag suffix (e.g., @preview-feat-add-api-route)
 # 3. Versions packages using changesets in snapshot mode
 # 4. Publishes NPM packages with @preview-* dist-tag
 # 5. Optionally builds and publishes Docker images with preview-* tag
@@ -31,7 +31,7 @@
 #
 # Important notes:
 # - Preview releases are NOT stable and should not be used in production
-# - They are ephemeral and don't modify the repository (no commits/tags)
+# - They are ephemeral and don't modify the repository (no commits/tags in git)
 # - Only authorized NameHash team members can trigger preview releases
 # - Preview releases are built from active development branches
 # - Installation: npm install @ensnode/package-name@preview-branch-name

From 875137ac72995157aac0a8ef931d0af056d60f9b Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Fri, 19 Dec 2025 16:01:03 -0500
Subject: [PATCH 32/49] chore: docs updates

---
 .../docs/docs/contributing/releases.mdx       | 28 ++++++++++---------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index e567bae48..0bba60dc3 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -38,7 +38,6 @@ If your PR includes a changeset and is merged to `main` then it will automatical
 **Important notes:**
 - Among all release types, only Full Releases are considered stable.
 - Full releases are triggered through merging the Release PR to `main`.
-- Full releases will include the `@latest` tag for published packages/images.
 - All ENSNode packages use "fixed" versioning. Once a full release is published they will all advance to the version indicated in the Release PR based on the included changesets.
 - Only members of the NameHash Labs `ensnode` team have the required permissions to merge the Release PR to `main`.
 - Full releases will create GitHub tags and release notes.
@@ -80,7 +79,7 @@ In the event that a package needs to be tested or installed before it is merged
 
 # Selecting a Release for Deployment or Installation
 
-When installing ENSNode NPM packages or Docker images, you have several release types to choose from depending on your needs and risk tolerance.
+When installing ENSNode NPM packages or Docker images, you have several release types to choose from.
 
 ## Where to Find Releases
 
@@ -90,19 +89,22 @@ When installing ENSNode NPM packages or Docker images, you have several release
 
 ## Choosing the Right Release Type
 
-### For Production Use: `@latest` (Full Releases)
+### For Production Deployments: Pinned Full Release Versions
 ```bash
-npm install @ensnode/package-name@latest
-docker run ghcr.io/namehash/ensnode:latest
+npm install @ensnode/package-name@1
+docker run ghcr.io/namehash/ensnode:1
 ```
 
 **When to use:**
-- When you need maximum stability and reliability
-- When you want thoroughly tested features
+- Production deployments and any critical infrastructure
+- When you need maximum stability and control over updates
 
 **What to expect:**
-- Stable, well-tested releases
-- Complete release notes and changelog entries
+- Stable, well-tested releases with complete release notes
+- The version will never change - you control when to upgrade
+- No unexpected breaking changes or behavior changes
+
+**Important:** Never use the `latest` tag for Docker deployments (e.g., `ghcr.io/namehash/ensnode:latest` or `ghcr.io/namehash/ensnode`). The `latest` tag is a mutable pointer that will automatically pull different versions over time, causing unexpected updates and potential breaking changes in your deployment. Always pin to a specific version number from the [GitHub releases page](https://github.com/namehash/ensnode/releases).
 
 ### For Development/Testing: `@next` (Snapshot releases)
 ```bash
@@ -137,8 +139,8 @@ docker run ghcr.io/namehash/ensnode:preview-branch-name
 
 ## Version Selection Best Practices
 
-- Check the GitHub releases page for the latest stable version and release notes
-- Pin specific versions in your integrations rather than using tags like `@latest`
-- Use full releases (`@latest`) as much as possible for stability
-- Only use snapshot releases (`@next`) for experimenting with new features
+- **Always pin Docker deployments to specific version numbers** (e.g., `1.2.3`) - never use `latest` or omit the tag
+- Check the [GitHub releases page](https://github.com/namehash/ensnode/releases) to find the specific version number you need
+- Review release notes before upgrading to understand what changed
+- Use snapshot releases (`@next`) only in development environments for testing upcoming features
 - Avoid using preview releases (`@preview`) unless you are actively contributing through a PR

From cdcdbc44b786a354dd68d5bae471dd5d8cd56cfb Mon Sep 17 00:00:00 2001
From: Steve Simkins <73185218+stevedylandev@users.noreply.github.com>
Date: Mon, 22 Dec 2025 07:58:56 -0500
Subject: [PATCH 33/49] chore: Update
 docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx

Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
---
 docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 0bba60dc3..0339450d5 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -142,5 +142,5 @@ docker run ghcr.io/namehash/ensnode:preview-branch-name
 - **Always pin Docker deployments to specific version numbers** (e.g., `1.2.3`) - never use `latest` or omit the tag
 - Check the [GitHub releases page](https://github.com/namehash/ensnode/releases) to find the specific version number you need
 - Review release notes before upgrading to understand what changed
-- Use snapshot releases (`@next`) only in development environments for testing upcoming features
+- Use snapshot releases (`@next`) only in development or staging environments for testing upcoming features
 - Avoid using preview releases (`@preview`) unless you are actively contributing through a PR

From 10b0c518c81d3441f3a399c4f206ad58d7feca8d Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Tue, 30 Dec 2025 14:14:48 -0500
Subject: [PATCH 34/49] chore: refactored release docs page

---
 .../docs/docs/contributing/releases.mdx       | 76 ++++++++-----------
 1 file changed, 31 insertions(+), 45 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 0339450d5..c03a8e133 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -13,17 +13,17 @@ We use [changesets](https://github.com/changesets/changesets) to manage version
 
 When you open a PR with feature or bug fix changes, you'll need to include a changeset file that documents your changes:
 
-1. Run `changeset` or `pnpm changeset` in the repository root
-2. Select the packages/apps your changes affect using the interactive prompt
+1. Run `changeset` or `pnpm changeset` in the repository root.
+2. Select the packages/apps your changes affect using the interactive prompt.
 3. Choose whether your changes are "major" (breaking changes), "minor" (features), or "patch" (bug fixes).
-4. Write a clear description of your changes - this will appear in the release notes
+4. Write a clear description of your changes - this will appear in the release notes.
 
 The `changesets/bot` will automatically comment on your PR to either remind you to add a changeset or confirm the version changes that will happen when your PR is merged.
 
 **Important notes:**
-- Changesets are only required for user-facing changes (features, bug fixes)
-- You don't need a changeset for documentation changes or internal refactoring
-- All our packages use "fixed" versioning - they all share the same version number regardless of which package triggered the version bump
+- Changesets are only required for user-facing changes (features, bug fixes).
+- You don't need a changeset for documentation changes or internal refactoring.
+- All our packages use "fixed" versioning - they all share the same version number regardless of which package triggered the version bump.
 
 # Creating a Release
 
@@ -60,11 +60,11 @@ Each commit to `main` will automatically trigger the `release_snapshot.yml` work
 
 Workflow File: [release_preview.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_preview.yml)
 
-In the event that a package needs to be tested or installed before it is merged into `main`, a preview release can be used. To manually trigger a preview release for a branch, follow these steps:
+To test or install a package before merging it into `main`, a preview release can be used. To manually trigger a preview release for a branch, follow these steps:
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - Which branch you would like to run the preview release workflow on. You can choose any branch other than `main` and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR. The GitHub comment will contain helpful installation info such as the generated release tag, which would otherwise have to be located manually through the action logs or the publishing registries.
+ - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information.
  - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
  - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/package-name@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 
@@ -89,58 +89,44 @@ When installing ENSNode NPM packages or Docker images, you have several release
 
 ## Choosing the Right Release Type
 
-### For Production Deployments: Pinned Full Release Versions
+### Pinned Full Release Versions
+:::note
+The example version below of `1.0.0` is a placeholder. Visit the [Releases Page](https://github.com/namehash/ensnode/releases) to pick a pinned full release.
+:::
 ```bash
-npm install @ensnode/package-name@1
-docker run ghcr.io/namehash/ensnode:1
+npm install @ensnode/package-name@1.0.0
+docker run ghcr.io/namehash/ensnode:1.0.0
 ```
 
-**When to use:**
-- Production deployments and any critical infrastructure
-- When you need maximum stability and control over updates
+Pinned full releases are recommended for those who want to start using ENSNode packages or Docker images. By using a pinned version you can maintain full control over features or patches that might be included. Feview the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
 
-**What to expect:**
-- Stable, well-tested releases with complete release notes
-- The version will never change - you control when to upgrade
-- No unexpected breaking changes or behavior changes
+:::caution
+Never use the `latest` tag for Docker deployments (e.g., `ghcr.io/namehash/ensnode:latest` or `ghcr.io/namehash/ensnode`). The `latest` tag is a mutable pointer that will automatically pull different versions over time, causing unexpected updates and potential breaking changes in your deployment. Always pin to a specific version number from the [GitHub releases page](https://github.com/namehash/ensnode/releases).
+:::
 
-**Important:** Never use the `latest` tag for Docker deployments (e.g., `ghcr.io/namehash/ensnode:latest` or `ghcr.io/namehash/ensnode`). The `latest` tag is a mutable pointer that will automatically pull different versions over time, causing unexpected updates and potential breaking changes in your deployment. Always pin to a specific version number from the [GitHub releases page](https://github.com/namehash/ensnode/releases).
-
-### For Development/Testing: `@next` (Snapshot releases)
+### Snapshot Releases
 ```bash
 npm install @ensnode/package-name@next  
 docker run ghcr.io/namehash/ensnode:next
 ```
 
-**When to use:**
-- Development environments
-- When you want to test upcoming features before they're stable
+Snapshot releases should be used by those who need to test features or patches before they are included in full releases. These releases follow the `main` branch and are not referenced in the GitHub Releases page. Instead they are installed by using the `next` tag for NPM packages or Docker images. 
 
-**What to expect:**
-- Latest features and bug fixes from the main branch
-- May contain breaking changes or unstable features
-- More frequent updates (every commit to main)
+:::caution
+Snapshot releases may contain unstable changes and should only be used in development environments.
+:::
 
-### For Feature Testing: `@preview-*` (Preview Releases)
+### Preview Releases
+:::note
+The example below is a mock of what a preview release might look like. Read [preview releases section](#preview-release) for more information.
+:::
 ```bash
 npm install @ensnode/package-name@preview-branch-name
 docker run ghcr.io/namehash/ensnode:preview-branch-name
 ```
 
-**When to use:**
-- Testing specific features before they're merged
-- Collaborating on development work
-- Validating fixes for specific issues
-
-**What to expect:**
-- Experimental and potentially unstable
-- Built from active development branches
-- May not be compatible with other packages
-
-## Version Selection Best Practices
+Preview releases are designed to test features or patches on a branch that have not been merged to the `main` branch, which means they can contain experimental and unstable changes. Therefore preview releases should be avoided unless you are actively contributing through a PR and need to test work on a branch. 
 
-- **Always pin Docker deployments to specific version numbers** (e.g., `1.2.3`) - never use `latest` or omit the tag
-- Check the [GitHub releases page](https://github.com/namehash/ensnode/releases) to find the specific version number you need
-- Review release notes before upgrading to understand what changed
-- Use snapshot releases (`@next`) only in development or staging environments for testing upcoming features
-- Avoid using preview releases (`@preview`) unless you are actively contributing through a PR
+:::caution
+Avoid using preview releases unless you are actively contributing to ENSNode and need to test changes on an active branch.
+:::

From 01fb85da22f7550fc96daa9fa55e731812e1d4fb Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Tue, 30 Dec 2025 15:41:06 -0500
Subject: [PATCH 35/49] chore: added lambda build and publish to snapshot and
 preview releases

---
 .github/workflows/release_preview.yml  | 23 ++++++++++++++++++++++-
 .github/workflows/release_snapshot.yml | 21 +++++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index fe07776de..e50a442ef 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -215,10 +215,31 @@ jobs:
             type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
             type=sha
 
+  build-and-publish-lambdas:
+    name: Build & Publish Preview Lambdas
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    needs: [validate-and-prepare, build-and-publish-npm]
+    if: inputs.publish_target == 'npm-only' || inputs.publish_target == 'npm-and-ghcr'
+    strategy:
+      fail-fast: false
+      matrix:
+        lambda: [fallback-ensapi]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Build and Publish Lambda
+        uses: ./.github/actions/build_and_publish_lambda
+        with:
+          name: ${{ matrix.lambda }}
+          version: ${{ needs.validate-and-prepare.outputs.dist-tag }}
+
   detect-pr-and-comment:
     name: Update PR Comment
     runs-on: blacksmith-4vcpu-ubuntu-2204
-    needs: [validate-and-prepare, build-and-publish-npm, build-and-publish-ghcr]
+    needs: [validate-and-prepare, build-and-publish-npm, build-and-publish-ghcr, build-lambdas]
     if: always() && needs.build-and-publish-npm.result == 'success'
     permissions:
       contents: read
diff --git a/.github/workflows/release_snapshot.yml b/.github/workflows/release_snapshot.yml
index edddacac3..aab1a1f06 100644
--- a/.github/workflows/release_snapshot.yml
+++ b/.github/workflows/release_snapshot.yml
@@ -123,3 +123,24 @@ jobs:
             type=raw,value=next
             type=raw,value=${{ steps.snapshot-tag.outputs.tag }}
             type=sha
+
+  build-and-publish-lambdas:
+    name: Build & Publish Snapshot Lambdas
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    if: github.repository == 'namehash/ensnode' && !contains(github.event.head_commit.message, 'changeset-release/main') && needs.snapshot.outputs.hasChanges == 'true'
+    needs: [build-and-publish-npm]
+    strategy:
+      fail-fast: false
+      matrix:
+        lambda: [fallback-ensapi]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Build and Publish Lambda
+        uses: ./.github/actions/build_and_publish_lambda
+        with:
+          name: ${{ matrix.lambda }}
+          version: next

From 7dde353ef7849435fc0dfb849879f33767ce031f Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Tue, 30 Dec 2025 15:59:23 -0500
Subject: [PATCH 36/49] chore: corrected run name

---
 .github/workflows/release_preview.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index e50a442ef..d5da5905d 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -239,7 +239,7 @@ jobs:
   detect-pr-and-comment:
     name: Update PR Comment
     runs-on: blacksmith-4vcpu-ubuntu-2204
-    needs: [validate-and-prepare, build-and-publish-npm, build-and-publish-ghcr, build-lambdas]
+    needs: [validate-and-prepare, build-and-publish-npm, build-and-publish-ghcr, build-and-publish-lambdas]
     if: always() && needs.build-and-publish-npm.result == 'success'
     permissions:
       contents: read

From 5898bcea5fb2d081a499b30563aeca268a277946 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Tue, 30 Dec 2025 16:02:35 -0500
Subject: [PATCH 37/49] chore: refactored docs page to include lambdas

---
 .../docs/docs/contributing/releases.mdx       | 43 ++++++++++---------
 1 file changed, 22 insertions(+), 21 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index c03a8e133..ea0d901cf 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -7,7 +7,7 @@ sidebar:
 
 import { LinkCard } from '@astrojs/starlight/components';
 
-We use [changesets](https://github.com/changesets/changesets) to manage version bumps and release notes for our NPM packages and Docker images (ENSIndexer, ENSAdmin, and ENSRainbow).
+We use [changesets](https://github.com/changesets/changesets) to manage version bumps and release notes for our monorepo's artifacts (NPM packages, Docker images, and Lambda zips).
 
 ## Adding a Changeset to Your PR
 
@@ -27,13 +27,13 @@ The `changesets/bot` will automatically comment on your PR to either remind you
 
 # Creating a Release
 
-Upon the publishing of a new release, your change will be included in the produced packages/images and your contributions will be referenced in the GitHub Release notes. There are three different types of releases that your changes can be included in for produced packages/images.
+Upon the publishing of a new release, your change will be included in the produced artifacts and your contributions will be referenced in the GitHub Release notes. There are three different types of releases that your changes can be included in for produced artifacts.
 
 ## Full Release
 
 Workflow File: [release.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release.yml)
 
-If your PR includes a changeset and is merged to `main` then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to `main` the Release PR will continue to update. Once the Release PR is merged into `main` then it will trigger a stable release with all of the included changesets. It will also create a release on GitHub with autogenerated release notes. When a full release runs it will build and publish packages to NPM and Docker images to GitHub Container Registry (ghcr).
+If your PR includes a changeset and is merged to `main` then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to `main` the Release PR will continue to update. Once the Release PR is merged into `main` then it will trigger a stable release with all of the included changesets. It will also create a release on GitHub with autogenerated release notes. When a full release runs it will build and publish all of the monorepo's artifacts (NPM packages, Docker images, and Lambda zips).
 
 **Important notes:**
 - Among all release types, only Full Releases are considered stable.
@@ -46,13 +46,13 @@ If your PR includes a changeset and is merged to `main` then it will automatical
 
 Workflow File: [release_snapshot.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_snapshot.yml)
 
-Each commit to `main` will automatically trigger the `release_snapshot.yml` workflow to build and publish packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag `@next`, allowing anyone to use the NPM packages or Docker images associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/package-name@next` or `docker run ghcr.io/namehash/ensnode:next`.
+Each commit to `main` will automatically trigger the `release_snapshot.yml` workflow to build and publish all of the monorepo's artifacts. These public releases will be under the tag `@next`, allowing anyone to use the artifacts associated with each commit to main. To install snapshot releases run `pnpm install @ensnode/[package-name]@next` or `docker run ghcr.io/namehash/ensnode/[app-name]:next`.
 
 **Important notes:**
 - Snapshot releases are part of the pre-stable state of the `main` branch and should be installed with caution until a [full release](#full-release) is published.
 - Release snapshots are automatic and cannot be triggered manually.
-- Snapshot releases will include the `@next` tag for published packages/images.
-- Published packages/images will advance to the version that was included in the changeset of the PR merged to `main`.
+- Snapshot releases will include the `@next` tag for published artifacts.
+- Published artifacts will advance to the version that was included in the changeset of the PR merged to `main`.
 - The `main` branch of `ensnode` is protected. Only PRs approved by the `ensnode` team can be merged to `main` and trigger a snapshot release.
 - No GitHub releases or tags are created for snapshot releases.
 
@@ -64,28 +64,29 @@ To test or install a package before merging it into `main`, a preview release ca
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information.
- - Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
- - (Optional) Provide a custom suffix for the preview release package tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/package-name@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/package-name@preview-users-route`.
-3. Install preview packages with: `npm install @ensnode/package-name@preview-branch-name`. 
+ - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information. If multiple preview releases are triggered for the same brach/PR, the GitHub comment will update with the latest release.
+ - Choose which artifacts to build and publish (NPM packages, Docker images, Lambda zips, or any combination).
+ - (Optional) Provide a custom suffix for the preview release tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/[package-name]@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/[package-name]@preview-users-route`.
+3. Install preview packages with: `npm install @ensnode/[package-name]@preview-branch-name`. 
 
 **Important notes:**
 - Preview releases are generally built and published from branches with active PRs. They are not guaranteed to be stable as they are still under active development.
 - Preview releases can only be triggered manually.
-- Preview releases will include the `@preview-*` tag for published packages/images, followed by either the name of the branch or the custom suffix chosen during the action trigger.
-- Published packages/images will advance to the version that was included in the changeset of the selected branch.
+- Preview releases will include the `@preview-*` tag for published artifacts, followed by either the name of the branch or the custom suffix chosen during the action trigger.
+- Published artifacts will advance to the version that was included in the changeset of the selected branch.
 - Preview releases can only be triggered by authorized NameHash team members.
 - No GitHub releases or tags are created for Preview Releases.
 
 # Selecting a Release for Deployment or Installation
 
-When installing ENSNode NPM packages or Docker images, you have several release types to choose from.
+When using ENSNode artifacts, you have several release types to choose from.
 
 ## Where to Find Releases
 
 - **NPM Packages**: Available on the [npm registry](https://www.npmjs.com/search?q=%40ensnode) under the `@ensnode` organization
 - **Docker Images**: Available on [GitHub Container Registry](https://github.com/orgs/namehash/packages?repo_name=ensnode)
 - **GitHub Releases**: Full releases are documented with release notes on the [ENSNode GitHub releases page](https://github.com/namehash/ensnode/releases)
+- **Lambda Zip Artifacts**: Available in the Artifact section of a successful workflow run
 
 ## Choosing the Right Release Type
 
@@ -94,11 +95,11 @@ When installing ENSNode NPM packages or Docker images, you have several release
 The example version below of `1.0.0` is a placeholder. Visit the [Releases Page](https://github.com/namehash/ensnode/releases) to pick a pinned full release.
 :::
 ```bash
-npm install @ensnode/package-name@1.0.0
-docker run ghcr.io/namehash/ensnode:1.0.0
+npm install @ensnode/[package-name]@1.0.0
+docker run ghcr.io/namehash/ensnode/[app-name]:1.0.0
 ```
 
-Pinned full releases are recommended for those who want to start using ENSNode packages or Docker images. By using a pinned version you can maintain full control over features or patches that might be included. Feview the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
+Pinned full releases are recommended for those who want to start using ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
 
 :::caution
 Never use the `latest` tag for Docker deployments (e.g., `ghcr.io/namehash/ensnode:latest` or `ghcr.io/namehash/ensnode`). The `latest` tag is a mutable pointer that will automatically pull different versions over time, causing unexpected updates and potential breaking changes in your deployment. Always pin to a specific version number from the [GitHub releases page](https://github.com/namehash/ensnode/releases).
@@ -106,11 +107,11 @@ Never use the `latest` tag for Docker deployments (e.g., `ghcr.io/namehash/ensno
 
 ### Snapshot Releases
 ```bash
-npm install @ensnode/package-name@next  
-docker run ghcr.io/namehash/ensnode:next
+npm install @ensnode/[package-name]@next  
+docker run ghcr.io/namehash/ensnode/[app-name]:next
 ```
 
-Snapshot releases should be used by those who need to test features or patches before they are included in full releases. These releases follow the `main` branch and are not referenced in the GitHub Releases page. Instead they are installed by using the `next` tag for NPM packages or Docker images. 
+Snapshot releases should be used by those who need to test features or patches before they are included in full releases. These releases follow the `main` branch and are not referenced in the GitHub Releases page. Instead they are installed by using the `next` tag for published artifacts. 
 
 :::caution
 Snapshot releases may contain unstable changes and should only be used in development environments.
@@ -121,8 +122,8 @@ Snapshot releases may contain unstable changes and should only be used in develo
 The example below is a mock of what a preview release might look like. Read [preview releases section](#preview-release) for more information.
 :::
 ```bash
-npm install @ensnode/package-name@preview-branch-name
-docker run ghcr.io/namehash/ensnode:preview-branch-name
+npm install @ensnode/[package-name]@[preview-branch-name]
+docker run ghcr.io/namehash/ensnode/[app-name]:[preview-branch-name]
 ```
 
 Preview releases are designed to test features or patches on a branch that have not been merged to the `main` branch, which means they can contain experimental and unstable changes. Therefore preview releases should be avoided unless you are actively contributing through a PR and need to test work on a branch. 

From e4e417bd6a634cae20a6ef8e0b5a865743698a1d Mon Sep 17 00:00:00 2001
From: Steve Simkins <73185218+stevedylandev@users.noreply.github.com>
Date: Wed, 31 Dec 2025 10:33:31 -0500
Subject: [PATCH 38/49] chore: Apply suggestions from code review

Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
---
 .../src/content/docs/docs/contributing/releases.mdx    | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index ea0d901cf..4e08eedd2 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -23,7 +23,8 @@ The `changesets/bot` will automatically comment on your PR to either remind you
 **Important notes:**
 - Changesets are only required for user-facing changes (features, bug fixes).
 - You don't need a changeset for documentation changes or internal refactoring.
-- All our packages use "fixed" versioning - they all share the same version number regardless of which package triggered the version bump.
+- All our apps and packages (with an exception as noted below) use "fixed" versioning - they all share the same version number regardless of which app or package triggered the version bump.
+- An exception to the above "fixed" versioning is the "fallback-ensapi" app. This is a Lambda containing logic specific to NameHash deployments of ENSNode and is versioned independently.
 
 # Creating a Release
 
@@ -33,7 +34,10 @@ Upon the publishing of a new release, your change will be included in the produc
 
 Workflow File: [release.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release.yml)
 
-If your PR includes a changeset and is merged to `main` then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to `main` the Release PR will continue to update. Once the Release PR is merged into `main` then it will trigger a stable release with all of the included changesets. It will also create a release on GitHub with autogenerated release notes. When a full release runs it will build and publish all of the monorepo's artifacts (NPM packages, Docker images, and Lambda zips).
+If your PR includes a changeset and is merged to `main` then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to `main` the Release PR will continue to update. Once a Release PR is merged into `main` it triggers a "full" release that will:
+
+- Build and publish all of the monorepo's artifacts (NPM packages, Docker images, and Lambda zips).
+- Create a release on GitHub with autogenerated release notes from all the included changesets.
 
 **Important notes:**
 - Among all release types, only Full Releases are considered stable.
@@ -64,7 +68,7 @@ To test or install a package before merging it into `main`, a preview release ca
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information. If multiple preview releases are triggered for the same brach/PR, the GitHub comment will update with the latest release.
+ - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information. If multiple preview releases are triggered for the same branch/PR, the GitHub comment on the associated PR will update with the latest preview release.
  - Choose which artifacts to build and publish (NPM packages, Docker images, Lambda zips, or any combination).
  - (Optional) Provide a custom suffix for the preview release tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/[package-name]@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/[package-name]@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/[package-name]@preview-branch-name`. 

From 601872352832db26bcd54f51325928de7da0bcb6 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 31 Dec 2025 10:43:06 -0500
Subject: [PATCH 39/49] chore: updated preview workflow to include new options

---
 .github/workflows/release_preview.yml         | 64 +++++++++++++++----
 .../docs/docs/contributing/releases.mdx       |  6 +-
 2 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index d5da5905d..f3048457f 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -7,7 +7,11 @@
 # 1. Navigate to Actions > Release Preview in GitHub
 # 2. Click "Run workflow" and select:
 #    - Branch: The branch you want to create a preview release from (typically an active PR branch)
-#    - Publish target: npm-only or npm-and-ghcr (NPM packages + Docker images)
+#    - Publish target:
+#      - npm-only: NPM packages only
+#      - npm-and-lambdas: NPM packages + Lambda functions
+#      - npm-and-ghcr: NPM packages + Docker images
+#      - all: NPM packages + Lambda functions + Docker images
 #    - Custom tag suffix (optional): Custom tag suffix instead of branch name
 #
 # What it does:
@@ -15,11 +19,13 @@
 # 2. Generates a sanitized tag from the branch name or custom tag suffix (e.g., @preview-feat-add-api-route)
 # 3. Versions packages using changesets in snapshot mode
 # 4. Publishes NPM packages with @preview-* dist-tag
-# 5. Optionally builds and publishes Docker images with preview-* tag
-# 6. Posts/updates a comment on the associated PR with installation instructions
+# 5. Optionally builds and publishes Lambda functions as GitHub Actions artifacts
+# 6. Optionally builds and publishes Docker images with preview-* tag
+# 7. Posts/updates a comment on the associated PR with installation instructions
 #
 # Published artifacts:
 # - NPM packages: Published with @preview-{branch-name} or @preview-{custom-suffix} tag
+# - Lambda functions (optional): Published as GitHub Actions artifacts
 # - Docker images (optional): Published with preview-{branch-name} or preview-{custom-suffix} tag
 # - No GitHub releases or tags are created
 #
@@ -52,10 +58,12 @@ on:
         description: 'Where should the release preview be published?'
         type: choice
         required: true
-        default: 'npm-and-ghcr'
+        default: 'all'
         options:
           - npm-only
+          - npm-and-lambdas
           - npm-and-ghcr
+          - all
 
 concurrency:
   group: prerelease-${{ github.ref_name }}
@@ -140,7 +148,7 @@ jobs:
     name: Build & Publish Release Preview Packages to NPM
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: validate-and-prepare
-    if: inputs.publish_target == 'npm-only' || inputs.publish_target == 'npm-and-ghcr'
+    if: inputs.publish_target == 'npm-only' || inputs.publish_target == 'npm-and-lambdas' || inputs.publish_target == 'npm-and-ghcr' || inputs.publish_target == 'all'
     permissions:
       contents: read
       id-token: write
@@ -189,7 +197,7 @@ jobs:
     name: Build & Publish Docker Images to GHCR
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: [validate-and-prepare, build-and-publish-npm]
-    if: inputs.publish_target == 'npm-and-ghcr'
+    if: inputs.publish_target == 'npm-and-ghcr' || inputs.publish_target == 'all'
     permissions:
       contents: read
       packages: write
@@ -219,7 +227,7 @@ jobs:
     name: Build & Publish Preview Lambdas
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: [validate-and-prepare, build-and-publish-npm]
-    if: inputs.publish_target == 'npm-only' || inputs.publish_target == 'npm-and-ghcr'
+    if: inputs.publish_target == 'npm-and-lambdas' || inputs.publish_target == 'all'
     strategy:
       fail-fast: false
       matrix:
@@ -307,9 +315,29 @@ jobs:
           "
           fi
 
-          # GHCR section - only if ghcr was requested and succeeded
-          if [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" && "${{ needs.build-and-publish-ghcr.result }}" == "success" ]]; then
-            COMMENT_BODY+="**Docker Images:**
+          # Lambdas section - only if lambdas were requested
+          if [[ "${{ inputs.publish_target }}" == "npm-and-lambdas" || "${{ inputs.publish_target }}" == "all" ]]; then
+            if [[ "${{ needs.build-and-publish-lambdas.result }}" == "success" ]]; then
+              COMMENT_BODY+="**Lambda Functions:**
+          \`\`\`
+          Published as GitHub Actions artifacts:
+          - fallback-ensapi-${{ needs.validate-and-prepare.outputs.dist-tag }}
+
+          Download from: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          \`\`\`
+
+          "
+            else
+              COMMENT_BODY+="**Lambda Functions:** ❌ Build failed - see [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+
+          "
+            fi
+          fi
+
+          # GHCR section - only if ghcr was requested
+          if [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" || "${{ inputs.publish_target }}" == "all" ]]; then
+            if [[ "${{ needs.build-and-publish-ghcr.result }}" == "success" ]]; then
+              COMMENT_BODY+="**Docker Images:**
           \`\`\`bash
           docker pull ghcr.io/namehash/ensnode/ensindexer:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
           docker pull ghcr.io/namehash/ensnode/ensadmin:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
@@ -318,18 +346,23 @@ jobs:
           \`\`\`
 
           "
-          elif [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" && "${{ needs.build-and-publish-ghcr.result }}" != "success" ]]; then
-            COMMENT_BODY+="**Docker Images:** ❌ Build failed - see [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+            else
+              COMMENT_BODY+="**Docker Images:** ❌ Build failed - see [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
 
           "
+            fi
           fi
 
           # Publish target info
           PUBLISH_TARGET_DISPLAY=""
           if [[ "${{ inputs.publish_target }}" == "npm-only" ]]; then
             PUBLISH_TARGET_DISPLAY="📦 NPM packages only"
+          elif [[ "${{ inputs.publish_target }}" == "npm-and-lambdas" ]]; then
+            PUBLISH_TARGET_DISPLAY="📦 NPM packages + ⚡ Lambda functions"
           elif [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" ]]; then
             PUBLISH_TARGET_DISPLAY="📦 NPM packages + 🐳 Docker images"
+          elif [[ "${{ inputs.publish_target }}" == "all" ]]; then
+            PUBLISH_TARGET_DISPLAY="📦 NPM packages + ⚡ Lambda functions + 🐳 Docker images"
           fi
 
           # Build info
@@ -388,11 +421,14 @@ jobs:
           echo "- Publish target: ${{ inputs.publish_target }}"
           echo "- Published version: ${{ needs.build-and-publish-npm.outputs.published-version }}"
           echo "- NPM dist-tag: ${{ needs.validate-and-prepare.outputs.dist-tag }}"
-          if [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" ]]; then
+          echo "- NPM publish: ${{ needs.build-and-publish-npm.result }}"
+          if [[ "${{ inputs.publish_target }}" == "npm-and-lambdas" || "${{ inputs.publish_target }}" == "all" ]]; then
+            echo "- Lambda publish: ${{ needs.build-and-publish-lambdas.result }}"
+          fi
+          if [[ "${{ inputs.publish_target }}" == "npm-and-ghcr" || "${{ inputs.publish_target }}" == "all" ]]; then
             echo "- Docker tag: ${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}"
             echo "- GHCR publish: ${{ needs.build-and-publish-ghcr.result }}"
           fi
-          echo "- NPM publish: ${{ needs.build-and-publish-npm.result }}"
           echo "- PR detected: ${{ steps.detect-pr.outputs.has-pr }}"
           if [[ "${{ steps.detect-pr.outputs.has-pr }}" == "true" ]]; then
             echo "- PR number: #${{ steps.detect-pr.outputs.pr-number }}"
diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 4e08eedd2..5c0dcdf0e 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -69,7 +69,11 @@ To test or install a package before merging it into `main`, a preview release ca
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
  - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information. If multiple preview releases are triggered for the same branch/PR, the GitHub comment on the associated PR will update with the latest preview release.
- - Choose which artifacts to build and publish (NPM packages, Docker images, Lambda zips, or any combination).
+ - Choose which artifacts to build and publish:
+   - `npm-only`: NPM packages only
+   - `npm-and-lambdas`: NPM packages + Lambda functions
+   - `npm-and-ghcr`: NPM packages + Docker images
+   - `all`: NPM packages + Lambda functions + Docker images
  - (Optional) Provide a custom suffix for the preview release tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/[package-name]@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/[package-name]@preview-users-route`.
 3. Install preview packages with: `npm install @ensnode/[package-name]@preview-branch-name`. 
 

From 9e37e918c7bfd2c215e3485e928faf0e458296d7 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 31 Dec 2025 11:21:27 -0500
Subject: [PATCH 40/49] chore: updates to releases.mdx per feedback

---
 .../src/content/docs/docs/contributing/releases.mdx | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 5c0dcdf0e..7e83e3994 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -100,18 +100,15 @@ When using ENSNode artifacts, you have several release types to choose from.
 
 ### Pinned Full Release Versions
 :::note
-The example version below of `1.0.0` is a placeholder. Visit the [Releases Page](https://github.com/namehash/ensnode/releases) to pick a pinned full release.
+In the Docker example below, `[version]` is a placeholder that must be replaced with a specific version number from the [Releases Page](https://github.com/namehash/ensnode/releases). Pinning to specific versions is critical for Docker images because the `latest` tag is a mutable pointer. Each time you pull or redeploy, you may receive a different version, introducing unexpected breaking changes or bugs into your running deployment without warning.
 :::
+
 ```bash
-npm install @ensnode/[package-name]@1.0.0
-docker run ghcr.io/namehash/ensnode/[app-name]:1.0.0
+npm install @ensnode/[package-name]@latest
+docker run ghcr.io/namehash/ensnode/[app-name]:[version]
 ```
 
-Pinned full releases are recommended for those who want to start using ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
-
-:::caution
-Never use the `latest` tag for Docker deployments (e.g., `ghcr.io/namehash/ensnode:latest` or `ghcr.io/namehash/ensnode`). The `latest` tag is a mutable pointer that will automatically pull different versions over time, causing unexpected updates and potential breaking changes in your deployment. Always pin to a specific version number from the [GitHub releases page](https://github.com/namehash/ensnode/releases).
-:::
+Pinned full releases are required for those who want to use ENSNode Docker Images. By using a pinned version you can maintain full control over features or patches that might be included. This is specifically important for ENSNode as a new version might require updates to environment variables such as `DATABASE_SCHEMA` or change how ENSNode apps work together. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
 
 ### Snapshot Releases
 ```bash

From b855b3cd00399a9a1c4af54ae98ceb34ce3336d2 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 31 Dec 2025 11:29:43 -0500
Subject: [PATCH 41/49] chore: updated where to find releases

---
 .../src/content/docs/docs/contributing/releases.mdx       | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 7e83e3994..30642e26c 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -91,10 +91,10 @@ When using ENSNode artifacts, you have several release types to choose from.
 
 ## Where to Find Releases
 
-- **NPM Packages**: Available on the [npm registry](https://www.npmjs.com/search?q=%40ensnode) under the `@ensnode` organization
-- **Docker Images**: Available on [GitHub Container Registry](https://github.com/orgs/namehash/packages?repo_name=ensnode)
-- **GitHub Releases**: Full releases are documented with release notes on the [ENSNode GitHub releases page](https://github.com/namehash/ensnode/releases)
-- **Lambda Zip Artifacts**: Available in the Artifact section of a successful workflow run
+- **NPM Packages**: Available on the [npm registry](https://www.npmjs.com/search?q=%40ensnode) under the `@ensnode` organization.
+- **Docker Images**: Available on [GitHub Container Registry](https://github.com/orgs/namehash/packages?repo_name=ensnode).
+- **GitHub Releases**: Full releases are documented with release notes on the [ENSNode GitHub releases page](https://github.com/namehash/ensnode/releases).
+- **Lambda Zip Artifacts**: Available in the [Artifact section](https://github.com/actions/upload-artifact?tab=readme-ov-file#where-does-the-upload-go) of a successful workflow run. These Action Artifacts are [retained for 90 days](https://github.com/actions/upload-artifact?tab=readme-ov-file#retention-period).
 
 ## Choosing the Right Release Type
 

From 16775e2bfbaca8f38113cac9402fe126f836ebaf Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 31 Dec 2025 11:44:16 -0500
Subject: [PATCH 42/49] chore: made PR requirement for preview releases,
 updated docs

---
 .github/workflows/release_preview.yml         | 79 ++++++++++---------
 .../docs/docs/contributing/releases.mdx       | 21 ++---
 2 files changed, 53 insertions(+), 47 deletions(-)

diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index f3048457f..946c31736 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -3,10 +3,14 @@
 # This workflow creates preview releases for testing features before they are merged to main.
 # It must be triggered manually via the GitHub Actions UI.
 #
+# Requirements:
+# - The branch must have an open PR targeting main
+# - Cannot be run on the main branch
+#
 # How to trigger:
 # 1. Navigate to Actions > Release Preview in GitHub
 # 2. Click "Run workflow" and select:
-#    - Branch: The branch you want to create a preview release from (typically an active PR branch)
+#    - Branch: The branch you want to create a preview release from (must have an open PR)
 #    - Publish target:
 #      - npm-only: NPM packages only
 #      - npm-and-lambdas: NPM packages + Lambda functions
@@ -15,13 +19,13 @@
 #    - Custom tag suffix (optional): Custom tag suffix instead of branch name
 #
 # What it does:
-# 1. Validates the branch (cannot run on main)
+# 1. Validates the branch (cannot run on main) and verifies an open PR exists
 # 2. Generates a sanitized tag from the branch name or custom tag suffix (e.g., @preview-feat-add-api-route)
 # 3. Versions packages using changesets in snapshot mode
 # 4. Publishes NPM packages with @preview-* dist-tag
 # 5. Optionally builds and publishes Lambda functions as GitHub Actions artifacts
 # 6. Optionally builds and publishes Docker images with preview-* tag
-# 7. Posts/updates a comment on the associated PR with installation instructions
+# 7. Posts/updates a comment on the PR with installation instructions
 #
 # Published artifacts:
 # - NPM packages: Published with @preview-{branch-name} or @preview-{custom-suffix} tag
@@ -30,16 +34,17 @@
 # - No GitHub releases or tags are created
 #
 # Use cases:
-# - Testing features before merging to main
+# - Testing PR features before merging to main
 # - Collaborating on development work
 # - Validating fixes for specific issues
 # - QA testing of work-in-progress features
 #
 # Important notes:
+# - Preview releases require an open PR targeting main
 # - Preview releases are NOT stable and should not be used in production
 # - They are ephemeral and don't modify the repository (no commits/tags in git)
 # - Only authorized NameHash team members can trigger preview releases
-# - Preview releases are built from active development branches
+# - Each preview release will update the PR comment with installation instructions
 # - Installation: npm install @ensnode/package-name@preview-branch-name
 # - Cleanup: Use npm dist-tag rm to manually remove preview tags when no longer needed
 #
@@ -86,7 +91,9 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Validate branch
+      - name: Validate branch and PR
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           if [[ "${{ github.ref_name }}" == "main" ]]; then
             echo "❌ Cannot run prerelease workflow on main branch"
@@ -95,6 +102,20 @@ jobs:
           fi
           echo "✅ Branch validation passed: ${{ github.ref_name }}"
 
+          # Require an open PR for this branch
+          PR_DATA=$(gh pr list --state=open --head="${{ github.ref_name }}" --base=main --json number,title --limit 1)
+
+          if [[ "$PR_DATA" == "[]" || -z "$PR_DATA" ]]; then
+            echo "❌ No open PR found for branch '${{ github.ref_name }}'"
+            echo "Preview releases require an open PR targeting main."
+            echo "Please create a PR for this branch before running a preview release."
+            exit 1
+          fi
+
+          PR_NUMBER=$(echo "$PR_DATA" | jq -r '.[0].number')
+          PR_TITLE=$(echo "$PR_DATA" | jq -r '.[0].title')
+          echo "✅ Found PR #${PR_NUMBER}: ${PR_TITLE}"
+
       - name: Prepare tags and identifiers
         id: prepare
         run: |
@@ -244,7 +265,7 @@ jobs:
           name: ${{ matrix.lambda }}
           version: ${{ needs.validate-and-prepare.outputs.dist-tag }}
 
-  detect-pr-and-comment:
+  update-pr-comment:
     name: Update PR Comment
     runs-on: blacksmith-4vcpu-ubuntu-2204
     needs: [validate-and-prepare, build-and-publish-npm, build-and-publish-ghcr, build-and-publish-lambdas]
@@ -258,33 +279,22 @@ jobs:
         with:
           fetch-depth: 1
 
-      - name: Detect PR
-        id: detect-pr
+      - name: Get PR number
+        id: get-pr
         run: |
-          # Try to find PR for this branch
-          PR_DATA=$(gh pr list --state=open --head="${{ github.ref_name }}" --base=main --json number,title,url --limit 1)
-
-          if [[ "$PR_DATA" != "[]" && -n "$PR_DATA" ]]; then
-            PR_NUMBER=$(echo "$PR_DATA" | jq -r '.[0].number')
-            PR_TITLE=$(echo "$PR_DATA" | jq -r '.[0].title')
-            PR_URL=$(echo "$PR_DATA" | jq -r '.[0].url')
-
-            echo "pr-number=${PR_NUMBER}" >> $GITHUB_OUTPUT
-            echo "pr-title=${PR_TITLE}" >> $GITHUB_OUTPUT
-            echo "pr-url=${PR_URL}" >> $GITHUB_OUTPUT
-            echo "has-pr=true" >> $GITHUB_OUTPUT
-
-            echo "✅ Found PR #${PR_NUMBER}: ${PR_TITLE}"
-          else
-            echo "has-pr=false" >> $GITHUB_OUTPUT
-            echo "ℹ️  No open PR found for branch ${{ github.ref_name }}"
-          fi
+          # PR is guaranteed to exist (validated in validate-and-prepare job)
+          PR_DATA=$(gh pr list --state=open --head="${{ github.ref_name }}" --base=main --json number,title --limit 1)
+          PR_NUMBER=$(echo "$PR_DATA" | jq -r '.[0].number')
+          PR_TITLE=$(echo "$PR_DATA" | jq -r '.[0].title')
+
+          echo "pr-number=${PR_NUMBER}" >> $GITHUB_OUTPUT
+          echo "pr-title=${PR_TITLE}" >> $GITHUB_OUTPUT
+          echo "✅ Updating PR #${PR_NUMBER}: ${PR_TITLE}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Generate PR comment body
         id: comment
-        if: steps.detect-pr.outputs.has-pr == 'true'
         run: |
           # Build timestamp for display
           BUILD_TIME=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
@@ -385,10 +395,9 @@ jobs:
 
       - name: Find existing comment
         id: find-comment
-        if: steps.detect-pr.outputs.has-pr == 'true'
         run: |
           # Look for existing comment from github-actions bot
-          COMMENT_ID=$(gh pr view ${{ steps.detect-pr.outputs.pr-number }} --json comments --jq '.comments[] | select(.author.login == "github-actions" and (.body | contains("🚀 Preview Packages"))) | .id' | head -1)
+          COMMENT_ID=$(gh pr view ${{ steps.get-pr.outputs.pr-number }} --json comments --jq '.comments[] | select(.author.login == "github-actions" and (.body | contains("🚀 Preview Packages"))) | .id' | head -1)
 
           if [[ -n "$COMMENT_ID" ]]; then
             echo "existing-comment-id=${COMMENT_ID}" >> $GITHUB_OUTPUT
@@ -400,15 +409,14 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Update or create PR comment
-        if: steps.detect-pr.outputs.has-pr == 'true'
         run: |
           if [[ -n "${{ steps.find-comment.outputs.existing-comment-id }}" ]]; then
             # Update existing comment
-            gh pr comment ${{ steps.detect-pr.outputs.pr-number }} --edit-last --body-file ${{ steps.comment.outputs.comment-file }}
+            gh pr comment ${{ steps.get-pr.outputs.pr-number }} --edit-last --body-file ${{ steps.comment.outputs.comment-file }}
             echo "✅ Updated existing PR comment"
           else
             # Create new comment
-            gh pr comment ${{ steps.detect-pr.outputs.pr-number }} --body-file ${{ steps.comment.outputs.comment-file }}
+            gh pr comment ${{ steps.get-pr.outputs.pr-number }} --body-file ${{ steps.comment.outputs.comment-file }}
             echo "✅ Created new PR comment"
           fi
         env:
@@ -418,6 +426,7 @@ jobs:
         run: |
           echo "## 📋 Preview Release Summary"
           echo "- Branch: ${{ github.ref_name }}"
+          echo "- PR: #${{ steps.get-pr.outputs.pr-number }}"
           echo "- Publish target: ${{ inputs.publish_target }}"
           echo "- Published version: ${{ needs.build-and-publish-npm.outputs.published-version }}"
           echo "- NPM dist-tag: ${{ needs.validate-and-prepare.outputs.dist-tag }}"
@@ -429,7 +438,3 @@ jobs:
             echo "- Docker tag: ${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}"
             echo "- GHCR publish: ${{ needs.build-and-publish-ghcr.result }}"
           fi
-          echo "- PR detected: ${{ steps.detect-pr.outputs.has-pr }}"
-          if [[ "${{ steps.detect-pr.outputs.has-pr }}" == "true" ]]; then
-            echo "- PR number: #${{ steps.detect-pr.outputs.pr-number }}"
-          fi
diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 30642e26c..b75b01823 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -64,26 +64,27 @@ Each commit to `main` will automatically trigger the `release_snapshot.yml` work
 
 Workflow File: [release_preview.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/release_preview.yml)
 
-To test or install a package before merging it into `main`, a preview release can be used. To manually trigger a preview release for a branch, follow these steps:
+To test or install a package before merging it into `main`, a preview release can be used. Each preview release is associated with a PR, and the PR will receive a comment with installation instructions. To manually trigger a preview release, follow these steps:
 
 1. Navigate to [Actions > Release Preview](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml)
 2. Click "Run workflow" and select from the following options:
- - The branch on which to run the preview release workflow. Any branch other than `main` can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information. If multiple preview releases are triggered for the same branch/PR, the GitHub comment on the associated PR will update with the latest preview release.
+ - The branch on which to run the preview release workflow. The branch must have an open PR.
  - Choose which artifacts to build and publish:
    - `npm-only`: NPM packages only
    - `npm-and-lambdas`: NPM packages + Lambda functions
    - `npm-and-ghcr`: NPM packages + Docker images
    - `all`: NPM packages + Lambda functions + Docker images
  - (Optional) Provide a custom suffix for the preview release tag. For example, if you had a branch called `feat/add-api-route` and left this custom suffix field blank, the preview release would be `@ensnode/[package-name]@preview-feat-add-api-route`. If you fill in the custom suffix field with `users-route` then the resulting tag name would be `@ensnode/[package-name]@preview-users-route`.
-3. Install preview packages with: `npm install @ensnode/[package-name]@preview-branch-name`. 
+3. The workflow will post a comment on the PR with installation instructions. If multiple preview releases are triggered for the same PR, the comment will update with the latest release info.
+4. Install preview packages with: `npm install @ensnode/[package-name]@preview-branch-name`. 
 
 **Important notes:**
-- Preview releases are generally built and published from branches with active PRs. They are not guaranteed to be stable as they are still under active development.
-- Preview releases can only be triggered manually.
+- Preview releases require an open PR. The workflow will abort if no PR exists for the branch.
+- Preview releases are not guaranteed to be stable as they are still under active development.
+- Preview releases can only be triggered manually by authorized NameHash team members.
 - Preview releases will include the `@preview-*` tag for published artifacts, followed by either the name of the branch or the custom suffix chosen during the action trigger.
 - Published artifacts will advance to the version that was included in the changeset of the selected branch.
-- Preview releases can only be triggered by authorized NameHash team members.
-- No GitHub releases or tags are created for Preview Releases.
+- No GitHub releases or tags are created for preview releases.
 
 # Selecting a Release for Deployment or Installation
 
@@ -124,15 +125,15 @@ Snapshot releases may contain unstable changes and should only be used in develo
 
 ### Preview Releases
 :::note
-The example below is a mock of what a preview release might look like. Read [preview releases section](#preview-release) for more information.
+The example below is a mock of what a preview release might look like. Read the [preview releases section](#preview-release) for more information.
 :::
 ```bash
 npm install @ensnode/[package-name]@[preview-branch-name]
 docker run ghcr.io/namehash/ensnode/[app-name]:[preview-branch-name]
 ```
 
-Preview releases are designed to test features or patches on a branch that have not been merged to the `main` branch, which means they can contain experimental and unstable changes. Therefore preview releases should be avoided unless you are actively contributing through a PR and need to test work on a branch. 
+Preview releases are designed to test features or patches on a PR branch before it is merged to `main`. Each preview release is associated with a PR, and the PR will have a comment with installation instructions. Since preview releases can contain experimental and unstable changes, they should be avoided unless you are actively contributing through a PR and need to test work on a branch.
 
 :::caution
-Avoid using preview releases unless you are actively contributing to ENSNode and need to test changes on an active branch.
+Avoid using preview releases unless you are actively contributing to ENSNode and need to test changes on an active PR.
 :::

From 7848555151390ddcdc261b940db1ff7f6a978d17 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 31 Dec 2025 15:04:03 -0500
Subject: [PATCH 43/49] chore: rename build_ensnode workflow

---
 .github/workflows/build_ensnode.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/build_ensnode.yml b/.github/workflows/build_ensnode.yml
index 586ec35a2..4c081e7ce 100644
--- a/.github/workflows/build_ensnode.yml
+++ b/.github/workflows/build_ensnode.yml
@@ -1,4 +1,4 @@
-name: "Build: ENSNode"
+name: "[Deprecated] Build: ENSNode"
 
 on:
   workflow_dispatch:

From 556d877a94b1bc514e6cbd37f52c8cdca30b4fc4 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Wed, 31 Dec 2025 15:10:32 -0500
Subject: [PATCH 44/49] chore: added caution block for snapshot releases

---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index b75b01823..0ce856299 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -112,6 +112,10 @@ docker run ghcr.io/namehash/ensnode/[app-name]:[version]
 Pinned full releases are required for those who want to use ENSNode Docker Images. By using a pinned version you can maintain full control over features or patches that might be included. This is specifically important for ENSNode as a new version might require updates to environment variables such as `DATABASE_SCHEMA` or change how ENSNode apps work together. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
 
 ### Snapshot Releases
+:::caution
+The `next` tag is a floating pointer that always references the most recent snapshot release. When using Docker images with the `next` tag, you must run `docker pull` to update your local Docker cache if you want to get the actual latest image. Without pulling, you may continue using an older cached version.
+:::
+
 ```bash
 npm install @ensnode/[package-name]@next  
 docker run ghcr.io/namehash/ensnode/[app-name]:next

From 801c6f92cfa01c6099633c514ca736c03e5607f6 Mon Sep 17 00:00:00 2001
From: Steve Simkins <73185218+stevedylandev@users.noreply.github.com>
Date: Thu, 1 Jan 2026 12:57:32 -0500
Subject: [PATCH 45/49] chore: Apply suggestions from code review

Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 0ce856299..a3e8ffcaa 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -101,7 +101,7 @@ When using ENSNode artifacts, you have several release types to choose from.
 
 ### Pinned Full Release Versions
 :::note
-In the Docker example below, `[version]` is a placeholder that must be replaced with a specific version number from the [Releases Page](https://github.com/namehash/ensnode/releases). Pinning to specific versions is critical for Docker images because the `latest` tag is a mutable pointer. Each time you pull or redeploy, you may receive a different version, introducing unexpected breaking changes or bugs into your running deployment without warning.
+In the installation examples below, `[version]` is a placeholder that must be replaced with a specific version number from the [Releases Page](https://github.com/namehash/ensnode/releases). Pinning to specific versions is critical for all published assets because the `latest` tag is a mutable pointer. Each time you pull or redeploy, you may receive a different version, introducing unexpected breaking changes or bugs into your running deployment without warning.
 :::
 
 ```bash
@@ -109,7 +109,7 @@ npm install @ensnode/[package-name]@latest
 docker run ghcr.io/namehash/ensnode/[app-name]:[version]
 ```
 
-Pinned full releases are required for those who want to use ENSNode Docker Images. By using a pinned version you can maintain full control over features or patches that might be included. This is specifically important for ENSNode as a new version might require updates to environment variables such as `DATABASE_SCHEMA` or change how ENSNode apps work together. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
+Pinned full releases are required for those who want to use any published ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. This is specifically important for ENSNode as a new version might require updates to environment variables such as `DATABASE_SCHEMA` or change how ENSNode apps work together. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
 
 ### Snapshot Releases
 :::caution

From 67dfba89e0d8857f50d47a15e645d51ad12e2eff Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 1 Jan 2026 13:05:16 -0500
Subject: [PATCH 46/49] chore: added caution block regarding semver

---
 .../src/content/docs/docs/contributing/releases.mdx           | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index a3e8ffcaa..a6a495844 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -88,6 +88,10 @@ To test or install a package before merging it into `main`, a preview release ca
 
 # Selecting a Release for Deployment or Installation
 
+:::caution
+ENSNode is currently not using [Semantic Versioning](https://semver.org/). Patches and minor releases may include breaking changes.
+:::
+
 When using ENSNode artifacts, you have several release types to choose from.
 
 ## Where to Find Releases

From 3d3780c789fe20fd7f530ad03746c88de310c822 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 1 Jan 2026 13:07:44 -0500
Subject: [PATCH 47/49] chore: refactored logic for fetching PR data in preview
 release

---
 .github/workflows/release_preview.yml | 27 +++++++++------------------
 1 file changed, 9 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/release_preview.yml b/.github/workflows/release_preview.yml
index 946c31736..42cc199fb 100644
--- a/.github/workflows/release_preview.yml
+++ b/.github/workflows/release_preview.yml
@@ -85,6 +85,8 @@ jobs:
       snapshot-tag: ${{ steps.prepare.outputs.snapshot-tag }}
       docker-tag-base: ${{ steps.prepare.outputs.docker-tag-base }}
       commit-sha: ${{ steps.prepare.outputs.commit-sha }}
+      pr-number: ${{ steps.validate.outputs.pr-number }}
+      pr-title: ${{ steps.validate.outputs.pr-title }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -92,6 +94,7 @@ jobs:
           fetch-depth: 0
 
       - name: Validate branch and PR
+        id: validate
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -114,6 +117,8 @@ jobs:
 
           PR_NUMBER=$(echo "$PR_DATA" | jq -r '.[0].number')
           PR_TITLE=$(echo "$PR_DATA" | jq -r '.[0].title')
+          echo "pr-number=${PR_NUMBER}" >> $GITHUB_OUTPUT
+          echo "pr-title=${PR_TITLE}" >> $GITHUB_OUTPUT
           echo "✅ Found PR #${PR_NUMBER}: ${PR_TITLE}"
 
       - name: Prepare tags and identifiers
@@ -279,20 +284,6 @@ jobs:
         with:
           fetch-depth: 1
 
-      - name: Get PR number
-        id: get-pr
-        run: |
-          # PR is guaranteed to exist (validated in validate-and-prepare job)
-          PR_DATA=$(gh pr list --state=open --head="${{ github.ref_name }}" --base=main --json number,title --limit 1)
-          PR_NUMBER=$(echo "$PR_DATA" | jq -r '.[0].number')
-          PR_TITLE=$(echo "$PR_DATA" | jq -r '.[0].title')
-
-          echo "pr-number=${PR_NUMBER}" >> $GITHUB_OUTPUT
-          echo "pr-title=${PR_TITLE}" >> $GITHUB_OUTPUT
-          echo "✅ Updating PR #${PR_NUMBER}: ${PR_TITLE}"
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Generate PR comment body
         id: comment
         run: |
@@ -397,7 +388,7 @@ jobs:
         id: find-comment
         run: |
           # Look for existing comment from github-actions bot
-          COMMENT_ID=$(gh pr view ${{ steps.get-pr.outputs.pr-number }} --json comments --jq '.comments[] | select(.author.login == "github-actions" and (.body | contains("🚀 Preview Packages"))) | .id' | head -1)
+          COMMENT_ID=$(gh pr view ${{ needs.validate-and-prepare.outputs.pr-number }} --json comments --jq '.comments[] | select(.author.login == "github-actions" and (.body | contains("🚀 Preview Packages"))) | .id' | head -1)
 
           if [[ -n "$COMMENT_ID" ]]; then
             echo "existing-comment-id=${COMMENT_ID}" >> $GITHUB_OUTPUT
@@ -412,11 +403,11 @@ jobs:
         run: |
           if [[ -n "${{ steps.find-comment.outputs.existing-comment-id }}" ]]; then
             # Update existing comment
-            gh pr comment ${{ steps.get-pr.outputs.pr-number }} --edit-last --body-file ${{ steps.comment.outputs.comment-file }}
+            gh pr comment ${{ needs.validate-and-prepare.outputs.pr-number }} --edit-last --body-file ${{ steps.comment.outputs.comment-file }}
             echo "✅ Updated existing PR comment"
           else
             # Create new comment
-            gh pr comment ${{ steps.get-pr.outputs.pr-number }} --body-file ${{ steps.comment.outputs.comment-file }}
+            gh pr comment ${{ needs.validate-and-prepare.outputs.pr-number }} --body-file ${{ steps.comment.outputs.comment-file }}
             echo "✅ Created new PR comment"
           fi
         env:
@@ -426,7 +417,7 @@ jobs:
         run: |
           echo "## 📋 Preview Release Summary"
           echo "- Branch: ${{ github.ref_name }}"
-          echo "- PR: #${{ steps.get-pr.outputs.pr-number }}"
+          echo "- PR: #${{ needs.validate-and-prepare.outputs.pr-number }}"
           echo "- Publish target: ${{ inputs.publish_target }}"
           echo "- Published version: ${{ needs.build-and-publish-npm.outputs.published-version }}"
           echo "- NPM dist-tag: ${{ needs.validate-and-prepare.outputs.dist-tag }}"

From c99e883ee6635ddb37278433dc7fa923f42cff81 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 1 Jan 2026 13:13:57 -0500
Subject: [PATCH 48/49] chore: updated npm tag from latest to [version]

---
 docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index a6a495844..8caceb4b9 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -109,7 +109,7 @@ In the installation examples below, `[version]` is a placeholder that must be re
 :::
 
 ```bash
-npm install @ensnode/[package-name]@latest
+npm install @ensnode/[package-name]@[version]
 docker run ghcr.io/namehash/ensnode/[app-name]:[version]
 ```
 

From 7e778f8aa0a375f15271f9db21d98647ea9fb0b7 Mon Sep 17 00:00:00 2001
From: Steve <contact@stevedylan.dev>
Date: Thu, 1 Jan 2026 13:57:21 -0500
Subject: [PATCH 49/49] chore: updated pinned full release versions section

---
 .../docs/docs/contributing/releases.mdx       | 28 ++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
index 8caceb4b9..def6d65e7 100644
--- a/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
+++ b/docs/ensnode.io/src/content/docs/docs/contributing/releases.mdx
@@ -104,16 +104,36 @@ When using ENSNode artifacts, you have several release types to choose from.
 ## Choosing the Right Release Type
 
 ### Pinned Full Release Versions
-:::note
-In the installation examples below, `[version]` is a placeholder that must be replaced with a specific version number from the [Releases Page](https://github.com/namehash/ensnode/releases). Pinning to specific versions is critical for all published assets because the `latest` tag is a mutable pointer. Each time you pull or redeploy, you may receive a different version, introducing unexpected breaking changes or bugs into your running deployment without warning.
-:::
+
+When deploying ENSNode to production environments, it is advisable to use a Pinned Full Release. Pinned full releases are required for those who want to use any published ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
 
 ```bash
 npm install @ensnode/[package-name]@[version]
 docker run ghcr.io/namehash/ensnode/[app-name]:[version]
 ```
 
-Pinned full releases are required for those who want to use any published ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. This is specifically important for ENSNode as a new version might require updates to environment variables such as `DATABASE_SCHEMA` or change how ENSNode apps work together. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install.
+:::caution
+When installing NPM packages for use in production environments, it is also advisable to pin a specific Pinned Full Release version number. ENSNode patch version increments MAY include breaking changes, so the usage of exact version package specifiers is encouraged.
+
+For example:
+
+✅ `"@ensnode/[package-name]": "1.0.0"`  
+❌ `"@ensnode/[package-name]": "^1.0.0"`
+
+And when installing from the command line:
+
+✅ `pnpm install @ensnode/[package-name]@1.0.0`  
+❌ `pnpm install @ensnode/[package-name]`
+:::
+
+:::caution
+In particular, when deploying ENSNode to production environments, using the `latest` Docker tag without strict pull policies could result in a version mismatch between interdependent ENSNode apps (which will helpfully crash at startup). Due to this, we highly recommend using a specific Pinned Full Release version number tag like `1.0.0` instead of the tag `latest`, which could point to different versions of the ENSNode app depending on the platform's pull policy.
+:::
+
+:::caution
+Each ENSIndexer version update is likely to produce an updated [Ponder Build Id](https://ponder.sh/docs/api-reference/ponder/database). When updating your ENSIndexer version, you should expect to update the `DATABASE_SCHEMA` environment variable to point to a new Postgres Database Schema for a complete reindexing with the new Ponder Build Id. A complete reindexing may take over 24 hours depending on your configuration. ENSNode version updates require special coordination and should not be assumed to be a simple version bump.
+:::
+
 
 ### Snapshot Releases
 :::caution