chore: bump version to 5.31.20260518.1457

.gitattributes

@@ -0,0 +1,3 @@
+# Normalize all text files to LF in the repo and working tree.
+# git's auto-detection keeps binary files untouched.
+* text=auto eol=lf

.github/workflows/bump-version.yml

@@ -2,23 +2,26 @@
 # On every PR merge to main this workflow:
 #   1. Collects all fragment files from changes/*.md and prepends them to
 #      CHANGES.md, then deletes the fragments.
-#   2. Increments the Minor version in setup/IdentityAtlas.psd1 and updates
-#      the timestamp.
+#   2. Increments Minor and updates the timestamp → Major.Minor.yyyyMMdd.HHmm
 #
 # Branches never touch CHANGES.md or the version file directly — each branch
 # creates a uniquely named fragment file in changes/ instead, so merge
 # conflicts on those two files are eliminated.
 #
 # After the commit lands, docker-publish.yml is triggered via workflow_run
-# so Docker images are always tagged with the new (post-bump) version.
+# so Docker images are always tagged with the new (post-bump) version (:edge).
+#
+# Releases are handled separately via git tags (Actions → Cut Release),
+# not by this workflow.
 # ─────────────────────────────────────────────────────────────────────────────
 
 name: Bump version on PR merge
 
 on:
   pull_request:
     types: [closed]
-    branches: [main]
+    branches:
+      - main
 
 jobs:
   bump-version:
@@ -28,10 +31,17 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
         with:
           ref: main
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ steps.bot-token.outputs.token }}
 
       - name: Merge changelog fragments and bump version
         shell: pwsh
@@ -49,7 +59,7 @@ jobs:
             Write-Host "No changelog fragments found in changes/ -- skipping CHANGES.md update"
           }
 
-          # ── 2. Bump Minor version in setup/IdentityAtlas.psd1 ─────────────
+          # ── 2. Increment Minor + update timestamp → Major.Minor.yyyyMMdd.HHmm
           $content = Get-Content setup/IdentityAtlas.psd1 -Raw
           if ($content -match "ModuleVersion\s*=\s*'(\d+)\.(\d+)\.\d+\.\d+'") {
             $major  = $Matches[1]

.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 2 * * 1' # Weekly on Monday at 02:00 UTC
+
+jobs:
+  analyze:
+    name: Analyze (javascript)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: javascript-typescript
+          queries: security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: /language:javascript-typescript

.github/workflows/cut-hotfix.yml

@@ -0,0 +1,85 @@
+# ─── Cut a Hotfix Release ─────────────────────────────────────────────────────
+# Manually triggered. Tags the HEAD of a hotfix branch with a new patch version,
+# triggering docker-publish to build :latest + :X.Y.Z.0.
+#
+# Usage:
+#   1. git checkout -b bugfixes/fix-foo v5.2.0   ← branch from the release tag
+#   2. Fix the bug, push the branch
+#   3. Go to Actions → Cut Hotfix → Run workflow
+#   4. Enter the branch name and new version (e.g. "5.2.1")
+#   5. After the hotfix ships, open a PR to cherry-pick the fix into main
+# ─────────────────────────────────────────────────────────────────────────────
+
+name: Cut Hotfix
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Hotfix branch name (e.g. bugfixes/fix-login-crash)'
+        required: true
+      version:
+        description: 'New version (major.minor.patch, e.g. "5.2.1")'
+        required: true
+
+jobs:
+  cut-hotfix:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Validate version input
+        run: |
+          if ! echo "${{ github.event.inputs.version }}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::Version must be in Major.Minor.Patch format (e.g. 5.2.1)"
+            exit 1
+          fi
+
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.branch }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Create and push hotfix tag
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          TAG="v${VERSION}"
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Hotfix release $TAG"
+          git push origin "$TAG"
+          echo "TAG=$TAG" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+          COMMIT=$(git rev-parse --short HEAD)
+          echo "COMMIT=$COMMIT" >> "$GITHUB_ENV"
+          echo "✅ Tagged ${TAG} on ${COMMIT}"
+
+      - name: Post run summary
+        run: |
+          cat >> "$GITHUB_STEP_SUMMARY" << EOF
+          ## ✅ Hotfix tagged
+
+          | | |
+          |---|---|
+          | **Tag** | \`${TAG}\` |
+          | **Version** | \`${VERSION}.0\` |
+          | **Branch** | \`${{ github.event.inputs.branch }}\` |
+          | **Commit** | \`${COMMIT}\` |
+
+          docker-publish is now building \`:latest\` + \`:${VERSION}.0\` — check the [Actions tab](../../actions) for progress.
+
+          ### Next step — cherry-pick to main
+          \`\`\`bash
+          git checkout main && git pull
+          git cherry-pick ${COMMIT}
+          gh pr create --base main --title "fix: cherry-pick hotfix from ${TAG}"
+          \`\`\`
+          EOF

.github/workflows/cut-release.yml

@@ -0,0 +1,84 @@
+# ─── Cut a Release ────────────────────────────────────────────────────────────
+# Manually triggered. Tags the current main HEAD with vX.Y.Z and lets
+# docker-publish (triggered by the tag push) build and push :latest + :X.Y.Z.0.
+#
+# Usage:
+#   1. Go to Actions → Cut Release → Run workflow
+#   2. Enter the version (e.g. "5.2.0" — major.minor.patch)
+#   3. The workflow creates tag v5.2.0 on the current main HEAD
+#   4. docker-publish builds and pushes :latest + :5.2.0.0
+#
+# Hotfixes (shipping a bugfix without including features already on main):
+#   1. git checkout -b bugfixes/fix-foo v5.2.0   ← branch from the tag, not main
+#   2. Fix the bug, push the branch
+#   3. Run Actions → Cut Hotfix with the branch name and new version (e.g. 5.2.1)
+# ─────────────────────────────────────────────────────────────────────────────
+
+name: Cut Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version (major.minor.patch, e.g. "5.2.0")'
+        required: true
+
+jobs:
+  cut-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Validate version input
+        run: |
+          if ! echo "${{ github.event.inputs.version }}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::Version must be in Major.Minor.Patch format (e.g. 5.2.0)"
+            exit 1
+          fi
+
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Create and push release tag
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          TAG="v${VERSION}"
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+          echo "TAG=$TAG" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+          echo "✅ Tagged ${TAG} on $(git rev-parse --short HEAD)"
+
+      - name: Post run summary
+        run: |
+          cat >> "$GITHUB_STEP_SUMMARY" << EOF
+          ## ✅ Release tagged
+
+          | | |
+          |---|---|
+          | **Tag** | \`${TAG}\` |
+          | **Version** | \`${VERSION}.0\` |
+          | **Commit** | \`$(git rev-parse --short HEAD)\` |
+
+          docker-publish is now building \`:latest\` + \`:${VERSION}.0\` — check the [Actions tab](../../actions) for progress.
+
+          ### Hotfix workflow (if a bug is found in this release)
+          \`\`\`bash
+          git checkout -b bugfixes/fix-foo ${TAG}   # branch from the tag, not main
+          # fix the bug, commit, push
+          git push origin bugfixes/fix-foo
+          # then run Actions → Cut Hotfix
+          \`\`\`
+          EOF