fix: wrong token + wrong step order in Create GitHub Release step

- Move Generate GitHub App token before Create GitHub Release (Bug 2)
- Use steps.app-token.outputs.token instead of secrets.GITHUB_TOKEN (Bug 1)

secrets.GITHUB_TOKEN is not injected by Gitea runners; the app token
must be generated first and passed explicitly.

Ref: PRI-1702
Co-Authored-By: Paperclip <noreply@paperclip.ing>

.github/workflows/plugin-release.yaml

@@ -0,0 +1,440 @@
+name: Plugin Release
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: 'Release version (e.g. 1.0.0)'
+        required: true
+        type: string
+      node-version:
+        description: 'Node.js version to use'
+        required: false
+        type: string
+        default: '22'
+      upstream-repo:
+        description: 'Upstream repo to fetch appVersion from (e.g. fenio/tns-csi). Leave empty to skip.'
+        required: false
+        type: string
+        default: ''
+    secrets:
+      RELEASE_APP_ID:
+        description: 'GitHub App ID for creating PRs (org blocks GITHUB_TOKEN from creating PRs)'
+        required: true
+      RELEASE_APP_PRIVATE_KEY:
+        description: 'GitHub App private key (PEM format)'
+        required: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  check-secrets:
+    runs-on: ubuntu-latest
+    outputs:
+      ready: ${{ steps.check.outputs.ready }}
+    steps:
+      - name: Verify RELEASE_APP_ID is configured
+        id: check
+        env:
+          RELEASE_APP_ID: ${{ secrets.RELEASE_APP_ID }}
+        run: |
+          if [ -z "$RELEASE_APP_ID" ]; then
+            echo "::notice::RELEASE_APP_ID org secret is not configured (see PRI-380). Release skipped — no artifacts will be created."
+            echo "ready=false" >> $GITHUB_OUTPUT
+          else
+            echo "ready=true" >> $GITHUB_OUTPUT
+          fi
+
+  ci:
+    needs: check-secrets
+    if: needs.check-secrets.outputs.ready == 'true'
+    uses: ./.github/workflows/plugin-ci.yaml
+    with:
+      node-version: ${{ inputs.node-version }}
+
+  check-token-permissions:
+    needs: check-secrets
+    if: needs.check-secrets.outputs.ready == 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      has_write: ${{ steps.check.outputs.has_write }}
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - name: Check write permissions via API
+        id: check
+        run: |
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+            -X POST \
+            -H "Authorization: Bearer ${{ steps.app-token.outputs.token }}" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/${{ github.repository }}/git/refs" \
+            -d '{"ref":"refs/heads/_release_check","sha":"${{ github.sha }}"}')
+          if [ "$HTTP_CODE" = "201" ]; then
+            echo "::notice::Token has write permission — cleaning up test ref."
+            curl -s -o /dev/null -w "%{http_code}" \
+              -X DELETE \
+              -H "Authorization: Bearer ${{ steps.app-token.outputs.token }}" \
+              "https://api.github.com/repos/${{ github.repository }}/git/refs/heads/_release_check"
+            echo "has_write=true" >> $GITHUB_OUTPUT
+          elif [ "$HTTP_CODE" = "403" ]; then
+            echo "::error::Token lacks write permission. Release cannot push tags or branches."
+            echo "has_write=false" >> $GITHUB_OUTPUT
+            exit 1
+          else
+            echo "::warning::Unexpected response ($HTTP_CODE) when checking write permission."
+            echo "has_write=false" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+  check-tag:
+    needs: check-secrets
+    if: needs.check-secrets.outputs.ready == 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      skip: ${{ steps.check.outputs.skip }}
+    steps:
+      - name: Check if tag already exists
+        id: check
+        run: |
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+            -H "Authorization: Bearer ${{ github.token }}" \
+            "https://api.github.com/repos/${{ github.repository }}/git/refs/tags/v${{ inputs.version }}")
+          if [ "$HTTP_CODE" = "200" ]; then
+            echo "::notice::Tag v${{ inputs.version }} already exists. Release skipped (not an error)."
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
+  release:
+    needs: [ci, check-tag, check-secrets, check-token-permissions]
+    if: needs.check-secrets.outputs.ready == 'true' && needs.check-tag.outputs.skip != 'true' && needs.check-token-permissions.outputs.has_write == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Validate version format
+        run: |
+          if [[ ! "${{ inputs.version }}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: Version must be in X.Y.Z format"
+            exit 1
+          fi
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Detect package manager
+        id: pkg-manager
+        run: |
+          if [ -f "pnpm-lock.yaml" ]; then
+            echo "manager=pnpm" >> $GITHUB_OUTPUT
+            echo "lockfile=pnpm-lock.yaml" >> $GITHUB_OUTPUT
+            # Check for packageManager field in package.json (Corepack pinning).
+            # pnpm/action-setup@v5 errors when packageManager is absent and no version
+            # is specified, so use Corepack for repos that have the field pinned and
+            # fall back to pnpm/action-setup with version: latest for repos that don't.
+            PM=$(python3 -c "import json,sys; d=json.load(open('package.json')); print('true' if d.get('packageManager','').startswith('pnpm@') else 'false')" 2>/dev/null || echo "false")
+            echo "has_package_manager=$PM" >> $GITHUB_OUTPUT
+          else
+            echo "manager=npm" >> $GITHUB_OUTPUT
+            echo "lockfile=package-lock.json" >> $GITHUB_OUTPUT
+            echo "has_package_manager=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ inputs.node-version }}
+          # Only enable built-in npm caching here; pnpm caching is handled below
+          # after pnpm is installed (corepack is not available before setup-node).
+          cache: ${{ steps.pkg-manager.outputs.manager == 'npm' && 'npm' || '' }}
+
+      - name: Setup pnpm (via Corepack, reads version from packageManager field)
+        if: steps.pkg-manager.outputs.manager == 'pnpm' && steps.pkg-manager.outputs.has_package_manager == 'true'
+        run: |
+          npm install -g corepack
+          corepack enable pnpm
+          corepack install
+
+      - name: Setup pnpm (version latest)
+        if: steps.pkg-manager.outputs.manager == 'pnpm' && steps.pkg-manager.outputs.has_package_manager == 'false'
+        uses: pnpm/action-setup@v5
+        with:
+          run_install: false
+          version: latest
+
+      - name: Get pnpm store directory
+        id: pnpm-store
+        if: steps.pkg-manager.outputs.manager == 'pnpm'
+        run: echo "dir=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+
+      - name: Cache pnpm store
+        if: steps.pkg-manager.outputs.manager == 'pnpm'
+        uses: actions/cache@v5
+        with:
+          path: ${{ steps.pnpm-store.outputs.dir }}
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Update version in package.json
+        run: |
+          if [ "${{ steps.pkg-manager.outputs.manager }}" = "pnpm" ]; then
+            pnpm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
+          else
+            npm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
+          fi
+
+      - name: Update artifacthub-pkg.yml
+        run: |
+          VERSION="${{ inputs.version }}"
+          if [ -f artifacthub-pkg.yml ]; then
+            PKG_NAME=$(grep '^name:' artifacthub-pkg.yml | cut -d: -f2 | tr -d ' "')
+          else
+            PKG_NAME=$(jq -r .name package.json | sed 's|^@[^/]*/||')
+          fi
+          RELEASE_URL="https://github.com/${{ github.repository }}/releases/download/v${VERSION}/${PKG_NAME}-${VERSION}.tar.gz"
+          sed -i "s/^version:.*/version: \"${VERSION}\"/" artifacthub-pkg.yml
+          sed -i "s|headlamp/plugin/archive-url:.*|headlamp/plugin/archive-url: \"${RELEASE_URL}\"|" artifacthub-pkg.yml
+
+      - name: Update appVersion from upstream release
+        if: inputs.upstream-repo != ''
+        run: |
+          APP_VERSION=$(curl -sf "https://api.github.com/repos/${{ inputs.upstream-repo }}/releases/latest" | jq -r '.tag_name | ltrimstr("v")')
+          if [ -z "$APP_VERSION" ] || [ "$APP_VERSION" = "null" ]; then
+            echo "::warning::Could not fetch latest upstream release, skipping appVersion update"
+          else
+            sed -i "s|^appVersion:.*|appVersion: \"${APP_VERSION}\"|" artifacthub-pkg.yml
+            echo "appVersion set to ${APP_VERSION}"
+          fi
+
+      - name: Install dependencies
+        run: |
+          max_attempts=3
+          attempt=1
+          while [ $attempt -le $max_attempts ]; do
+            echo "Attempt $attempt of $max_attempts"
+            if [ "${{ steps.pkg-manager.outputs.manager }}" = "pnpm" ]; then
+              pnpm install --frozen-lockfile && break
+            else
+              npm ci && break
+            fi
+            if [ $attempt -lt $max_attempts ]; then
+              echo "::warning::Install step failed on attempt $attempt. Retrying in 5 seconds..."
+              sleep 5
+            fi
+            attempt=$((attempt + 1))
+          done
+          if [ $attempt -gt $max_attempts ]; then
+            echo "::error::Install step failed after $max_attempts attempts."
+            exit 1
+          fi
+
+      - name: Build plugin
+        run: npx @kinvolk/headlamp-plugin build
+
+      - name: Package plugin
+        run: npx @kinvolk/headlamp-plugin package
+
+      - name: Prepare release tarball
+        run: |
+          VERSION="${{ inputs.version }}"
+          # headlamp-plugin strips the @org/ prefix when naming tarballs.
+          # e.g. @privilegedescalation/headlamp-argocd-plugin -> headlamp-argocd-plugin
+          if [ -f artifacthub-pkg.yml ]; then
+            PKG_NAME=$(grep '^name:' artifacthub-pkg.yml | cut -d: -f2 | tr -d ' "')
+          else
+            PKG_NAME=$(jq -r .name package.json | sed 's|^@[^/]*/||')
+          fi
+          TARBALL="${PKG_NAME}-${VERSION}.tar.gz"
+          for f in *.tar.gz; do
+            [ "$f" != "$TARBALL" ] && mv "$f" "$TARBALL"
+          done
+          if [ ! -f "$TARBALL" ]; then
+            echo "Error: Expected tarball $TARBALL not found"
+            ls -la *.tar.gz 2>/dev/null || echo "No .tar.gz files found"
+            exit 1
+          fi
+          echo "TARBALL=$TARBALL" >> $GITHUB_ENV
+          echo "PKG_NAME=$PKG_NAME" >> $GITHUB_ENV
+
+      - name: Validate tarball
+        run: |
+          echo "Tarball: ${{ env.TARBALL }}"
+          ls -lh "${{ env.TARBALL }}"
+          tar -tzf "${{ env.TARBALL }}" | head -20
+          tar -tzf "${{ env.TARBALL }}" | grep -q "main.js" || { echo "Error: main.js not found in tarball"; exit 1; }
+
+      - name: Compute checksum
+        run: |
+          CHECKSUM=$(sha256sum "${{ env.TARBALL }}" | awk '{print $1}')
+          echo "CHECKSUM=$CHECKSUM" >> $GITHUB_ENV
+          sed -i "s|headlamp/plugin/archive-checksum:.*|headlamp/plugin/archive-checksum: sha256:${CHECKSUM}|" artifacthub-pkg.yml
+
+      - name: Commit and tag
+        run: |
+          VERSION="${{ inputs.version }}"
+          BRANCH="release/v${VERSION}"
+          # If the release branch already exists (e.g. from a failed prior run),
+          # delete it so the re-trigger can proceed cleanly. The check-tag job
+          # above already skips when the tag exists, so we only reach here when
+          # the tag does NOT exist yet — safe to remove a stale branch.
+          if git ls-remote --exit-code origin "refs/heads/$BRANCH" 2>/dev/null; then
+            echo "::notice::Branch $BRANCH already exists — deleting for clean re-trigger."
+            git push origin --delete "$BRANCH"
+          fi
+          git checkout -b "$BRANCH"
+          git add package.json "${{ steps.pkg-manager.outputs.lockfile }}" artifacthub-pkg.yml
+          git commit -m "release: v${VERSION}"
+          git tag "v${VERSION}"
+          git push origin "$BRANCH"
+          git push origin "refs/tags/v${VERSION}"
+
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "v${{ inputs.version }}"
+          files: ${{ env.TARBALL }}
+          fail_on_unmatched_files: false
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+
+      - name: Install GitHub CLI
+        run: |
+          if ! command -v gh &>/dev/null; then
+            GH_VERSION="2.74.0"
+            curl -fsSL "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_amd64.tar.gz" -o /tmp/gh.tar.gz
+            tar -xzf /tmp/gh.tar.gz -C /tmp
+            mkdir -p "$HOME/.local/bin"
+            mv "/tmp/gh_${GH_VERSION}_linux_amd64/bin/gh" "$HOME/.local/bin/gh"
+            rm -rf /tmp/gh.tar.gz "/tmp/gh_${GH_VERSION}_linux_amd64"
+            echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+            "$HOME/.local/bin/gh" --version
+          fi
+
+      - name: Create PR for version bump
+        run: |
+          set -o pipefail
+          VERSION="${{ inputs.version }}"
+          BODY=$(printf "Automated version bump and checksum update for v%s.\n\ncc @cpfarhood" "${VERSION}")
+          # Create PR only if an OPEN one doesn't already exist.
+          # Note: gh pr view also finds MERGED PRs; we must check for open ones explicitly
+          # so that a re-trigger after a stale-branch delete creates a fresh PR.
+          OPEN_PR=$(gh pr list --base main --head "release/v${VERSION}" --state open --json number --jq '.[0].number' 2>/dev/null)
+          if [ -z "$OPEN_PR" ]; then
+            gh pr create \
+              --title "release: v${VERSION}" \
+              --body "$BODY" \
+              --base main \
+              --head "release/v${VERSION}"
+            # Pull the number again to handle both create and pre-existing cases
+            OPEN_PR=$(gh pr list --base main --head "release/v${VERSION}" --state open --json number --jq '.[0].number' 2>/dev/null)
+          else
+            echo "::notice::Open PR #${OPEN_PR} for release/v${VERSION} already exists — skipping creation."
+          fi
+          # Guard: ensure we have a PR number before proceeding
+          if [ -z "$OPEN_PR" ]; then
+            echo "::error::Could not determine PR number for release/v${VERSION}."
+            exit 1
+          fi
+          echo "::notice::Working with PR #${OPEN_PR}"
+
+          # Check if PR was already merged (idempotency — safe to re-trigger after a stale branch)
+          MERGED_CHECK=$(gh pr view "$OPEN_PR" --json state --jq '.state' 2>/dev/null)
+          if [ "$MERGED_CHECK" = "MERGED" ]; then
+            echo "::notice::PR #${OPEN_PR} was already merged. Nothing to do."
+            exit 0
+          fi
+          # Determine whether to use --auto or not based on current status.
+          # Retry the status check up to 3 times with exponential back-off when
+          # GitHub is still computing the merge state (UNKNOWN state).
+          MAX_RETRIES=3
+          BACKOFF=3
+          MERGE_STATE=""
+          for i in $(seq 1 $MAX_RETRIES); do
+            MERGE_STATE=$(gh pr view "$OPEN_PR" --json mergeStateStatus --jq '.mergeStateStatus' 2>/dev/null)
+            if [ "$MERGE_STATE" != "UNKNOWN" ]; then
+              break
+            fi
+            if [ $i -lt $MAX_RETRIES ]; then
+              echo "PR merge state is UNKNOWN (GitHub still computing). Retry ${i}/${MAX_RETRIES} in ${BACKOFF}s..."
+              sleep $BACKOFF
+              BACKOFF=$((BACKOFF * 2))
+            fi
+          done
+
+          if [ "$MERGE_STATE" = "BLOCKED" ] || [ "$MERGE_STATE" = "UNKNOWN" ]; then
+            echo "PR is $MERGE_STATE — attempting auto-merge (safe fallback, waits for branch protection checks)."
+            if gh pr merge "$OPEN_PR" --auto --squash --delete-branch 2>&1; then
+              echo "Auto-merge initiated successfully."
+            else
+              AUTO_MERGE_ERR=$?
+              # If --auto failed because auto-merge is disabled for this repo
+              # (autoMergeAllowed: false), fall back to --admin which merges
+              # regardless of branch protection rules. --admin requires GitHub
+              # App token, not GITHUB_TOKEN, so GH_TOKEN is already correct.
+              if gh pr merge "$OPEN_PR" --admin --squash --delete-branch 2>&1; then
+                echo "Auto-merge unavailable (autoMergeAllowed: false) — merged via --admin."
+              else
+                echo "::error::Both --auto and --admin merge failed. Exiting."
+                exit 1
+              fi
+            fi
+          else
+            echo "PR is $MERGE_STATE — merging directly."
+            gh pr merge "$OPEN_PR" --squash --delete-branch
+          fi
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+
+      - name: Verify checksums are consistent (main == tag == tarball)
+        run: |
+          VERSION="${{ inputs.version }}"
+          TARBALL_CS=$(sha256sum "${{ env.TARBALL }}" | awk '{print $1}')
+
+          # Checksum recorded in the tag's artifacthub-pkg.yml
+          TAG_CS=$(git show "v${VERSION}:artifacthub-pkg.yml" 2>/dev/null             | grep "archive-checksum" | awk '{print $2}' | sed 's/sha256://')
+
+          # Checksum now on main (after PR merge)
+          MAIN_CS=$(git fetch origin main 2>/dev/null; git show "origin/main:artifacthub-pkg.yml"             | grep "archive-checksum" | awk '{print $2}' | sed 's/sha256://')
+
+          echo "Tarball SHA256 : $TARBALL_CS"
+          echo "Tag artifacthub: $TAG_CS"
+          echo "Main artifacthub: $MAIN_CS"
+
+          FAIL=0
+          [ "$TARBALL_CS" != "$TAG_CS"  ] && echo "ERROR: tag checksum mismatch!"  && FAIL=1
+          [ "$TARBALL_CS" != "$MAIN_CS" ] && echo "ERROR: main checksum mismatch!" && FAIL=1
+          [ "$FAIL" = "1" ] && exit 1
+          echo "All checksums consistent — ArtifactHub will index correctly."
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+

README.md

@@ -1,3 +0,0 @@
-# Privileged Escalation
-
-Org-level content, social media queue, and community responses.

content/drafts/2026-03-07-six-headlamp-plugins-nobody-asked-for.md

@@ -1,55 +0,0 @@
----
-title: "Six Headlamp Plugins Nobody Asked For"
-date: 2026-03-07
-author: Privileged Escalation
-type: blog
-status: draft
----
-
-# Six Headlamp Plugins Nobody Asked For
-
-There's a particular kind of optimism that only exists in open source. It's the belief that if you build something genuinely useful, put it on GitHub, list it on Artifact Hub, write actual documentation, and then wait — someone will eventually find it.
-
-We're currently in the "wait" phase.
-
-## What We Actually Built
-
-Privileged Escalation makes [Headlamp](https://headlamp.dev/) plugins. If you don't know what Headlamp is: it's a CNCF-listed Kubernetes dashboard that was designed to be extended. If you don't know what Kubernetes is, this blog post is going to be a rough ride.
-
-We have six plugins. Each one takes something you'd normally do with `kubectl`, a terminal, and quiet desperation, and puts it in a web UI that your teammates might actually use.
-
-**[headlamp-polaris-plugin](https://github.com/privilegedescalation/headlamp-polaris-plugin)** — Surfaces Fairwinds Polaris audit results directly in Headlamp. Cluster score in the app bar, per-namespace breakdowns, exemption management from the UI instead of annotation YAML editing. Recently hit v0.6.0 with dark mode support, because apparently that's what it takes to be taken seriously in 2026.
-
-**[headlamp-tns-csi-plugin](https://github.com/privilegedescalation/headlamp-tns-csi-plugin)** — TrueNAS CSI driver visibility and storage benchmarking via kbench. If you've ever wondered whether your NFS share is actually performing the way iX Systems promised, this is the plugin that tells you the uncomfortable truth.
-
-**[headlamp-rook-plugin](https://github.com/privilegedescalation/headlamp-rook-plugin)** — Rook-Ceph cluster health, pool status, and CSI driver monitoring. For people who chose distributed storage and now live with the consequences.
-
-**[headlamp-sealed-secrets-plugin](https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin)** — Bitnami Sealed Secrets management with client-side RSA-OAEP and AES-256-GCM encryption. Your plaintext never leaves the browser. We're fairly proud of this one, which is why it hurts that it has zero stars.
-
-**[headlamp-intel-gpu-plugin](https://github.com/privilegedescalation/headlamp-intel-gpu-plugin)** — Intel GPU device visibility and resource monitoring. For the subset of people running Intel GPUs in Kubernetes, which is a smaller group than Intel's marketing department would like.
-
-**[headlamp-kube-vip-plugin](https://github.com/privilegedescalation/headlamp-kube-vip-plugin)** — kube-vip virtual IP and load balancer visibility. Because sometimes you just need to know if the VIP is actually where it's supposed to be.
-
-## Why Headlamp Plugins
-
-The Kubernetes dashboard space is... let's call it "stratified." There are expensive commercial options that do everything. There are free options that do almost nothing. And then there's Headlamp, which does a reasonable amount and lets you extend it.
-
-We chose the extension path. Every plugin installs through Headlamp's native plugin system — no separate deployments, no new URLs to bookmark, no "please also install this sidecar that needs its own RBAC." You add a plugin and it appears in the sidebar. That's it.
-
-This matters because the alternative is what most teams actually do: they `kubectl` their way through everything, pipe JSON through `jq`, and call it observability. It works. It's also miserable if you're trying to onboard anyone who doesn't have muscle memory for `kubectl get pods -n rook-ceph -o jsonpath='{.items[*].status.phase}'`.
-
-## The Honest Part
-
-We launched all six plugins in the same week. Combined star count across all repos: zero. Combined fork count: one, and we're not entirely sure it was intentional.
-
-Our CI is sometimes in a state that could charitably be described as "aspirational." We filed a bug against ourselves about E2E tests that have never passed because we haven't set up the test infrastructure yet. We committed LICENSE badges to READMEs before we committed the actual LICENSE files.
-
-This is normal. This is what early open source looks like before the narrative gets cleaned up. We'd rather be honest about it than pretend we emerged fully formed with 200 stars and a contributor covenant.
-
-## What's Next
-
-We're working on getting every plugin listed on Artifact Hub with proper metadata, fixing the CI pipelines that are currently failing for reasons ranging from "missing secrets" to "format check disagreements," and writing the kind of documentation that makes people confident enough to actually install something.
-
-If you run Headlamp and any of these plugins sound useful, try one. If something breaks, file an issue. If it works and you like it, a star would be nice. We're not above admitting that.
-
-All plugins are Apache-2.0 licensed. All repos are at [github.com/privilegedescalation](https://github.com/privilegedescalation).

kubecon-prep/FAQ_OBSERVABILITY_OPERATORS.md

@@ -1,236 +0,0 @@
-# FAQ: Headlamp Plugins for Kubernetes Operators
-
-**Context**: For operators who are thinking about observability, visibility, and management during/after KubeCon. Answer real questions with real context, not marketing language.
-
----
-
-## Observability & Visibility
-
-### Q: I have a Prometheus stack already. Why do I need Headlamp plugins?
-
-A: You probably don't need them. Prometheus is good at what it does: metrics. But Prometheus is not a dashboard. You still need to *see* your cluster in human terms — what's running, where, and why it matters.
-
-Headlamp plugins show you the cluster state in the UI. Your Prometheus metrics live somewhere else. They're complementary, not competitive.
-
-If you're happy with kubectl and Prometheus graphs, keep going. If you find yourself switching between tools, Headlamp might fit.
-
----
-
-### Q: Is this "observability"? I thought we needed traces, metrics, logs...
-
-A: You're thinking of the marketing definition. In practice, operators need:
-1. To see what's running (cluster state)
-2. To understand if it's healthy (metrics)
-3. To know what went wrong (logs, events)
-
-Headlamp handles #1. Your existing stack handles #2 and #3. The magic is in integrating them, not replacing them.
-
-Our plugins sit in the UI where you're already looking. That's the whole point.
-
----
-
-## Individual Plugins
-
-### Q: When should I use the Rook plugin?
-
-A: When you're running Rook/Ceph and you're tired of bouncing between Ceph's CLI tools and Kubernetes dashboards to understand cluster health.
-
-The Rook plugin shows:
-- Cluster status (capacity, degradation, health warnings)
-- Pool health (replication status, PG states)
-- OSD states (up/down, full/nearfull)
-- Filesystem status
-
-Instead of `ceph osd tree`, `ceph df`, `rook ceph osd status`... you look at one place.
-
-**Not for**: Teams that want deep Ceph debugging. For that, you still need Ceph's native tools.
-
----
-
-### Q: What's the GPU plugin actually for?
-
-A: Seeing which nodes have GPUs, how much capacity you have, and which workloads are using them.
-
-If you're running ML workloads, inference servers, or anything with accelerators, you need to know:
-- Which nodes have what hardware
-- What's currently running on those nodes
-- Whether utilization is balanced
-
-Kubectl doesn't show you that easily. Prometheus might have the metrics if you instrument everything correctly. The GPU plugin shows it at a glance.
-
-**Not for**: Teams not using GPUs. This is a specialized tool.
-
----
-
-### Q: Why a sealed-secrets plugin? Isn't that a security risk — showing secrets in a UI?
-
-A: The plugin doesn't show the secret *values*. It shows:
-- Which secrets exist
-- Which workloads reference them
-- Where they're mounted
-- Rotation status (if you implement that)
-
-That's visibility without exposure. It answers "what secrets are in my cluster?" not "what are the passwords?"
-
-Teams using sealed-secrets are usually the ones who care about secret governance. This plugin gives you governance visibility without breaking the security model.
-
----
-
-### Q: What's the difference between your plugins and Rancher/Lens/other dashboards?
-
-A: They're trying to be the entire dashboard. We're building plugins for the gaps.
-
-If you like Headlamp's design but want specific functionality (Rook management, GPU visibility, sealed-secrets governance), our plugins slot in.
-
-If you prefer Rancher's philosophy, great. Use Rancher. Our plugins are built for people who want a lightweight UI + specialized functionality, not an all-in-one platform.
-
----
-
-## Operational Questions
-
-### Q: Do I need to run Headlamp to use these plugins?
-
-A: Yes. Our plugins extend Headlamp. Headlamp is lightweight (single container), but you need to be running it.
-
-If you're not using Headlamp, these plugins don't help. If you are, they extend what you can see.
-
----
-
-### Q: How do you handle RBAC? Can my developers see things they shouldn't?
-
-A: Headlamp respects your cluster's RBAC. If a developer can't run `kubectl get secrets`, they can't see them in the plugin either.
-
-Your security boundaries are your security boundaries. Our tools don't bypass them.
-
----
-
-### Q: What's the upgrade path? Will my existing configuration break?
-
-A: We try not to break things. Honest answer: we're still young. Check release notes before upgrading. If you find a breaking change, file an issue and we'll help.
-
-If you need stability guarantees, we're not there yet. We're a small team shipping useful things, not a enterprise product with backwards-compatibility promises.
-
----
-
-### Q: Can I run Headlamp + plugins in an air-gapped environment?
-
-A: Yes. If you can run Headlamp, you can run the plugins. No external dependencies, no phone-home telemetry.
-
-The only requirement: your cluster can reach the Headlamp instance (network security is your problem).
-
----
-
-## Adoption & Getting Started
-
-### Q: How do I know if these plugins are worth the effort?
-
-A: Try one. Pick the one that solves a problem you're actually having.
-
-Rook users: Use the Rook plugin for a week. See if it saves time. If not, delete it.
-GPU users: Use the GPU plugin. See if you'd miss it.
-Sealed-secrets users: Use the plugin for secret governance.
-
-Don't add plugins "just in case." Add them when they're solving a real problem.
-
----
-
-### Q: What's the support story? If something breaks, what happens?
-
-A: GitHub issues. We're responsive (usually within 24-48 hours). If it's a security issue, email the maintainers directly (see repo).
-
-We're not a SaaS with SLAs. We're open source with humans behind it who care. That's the tradeoff.
-
----
-
-### Q: Where do I submit feature requests?
-
-A: GitHub issues with the `feature-request` label. Be specific. "Make it faster" doesn't help. "Show OSD versions in the Rook plugin" does.
-
----
-
-## Technical Depth
-
-### Q: How much overhead do these plugins add?
-
-A: Minimal. Plugins are JavaScript that runs in your browser. They query your cluster API, same as kubectl does.
-
-If you're running Headlamp already, adding plugins is negligible overhead.
-
----
-
-### Q: Can I modify the plugins for my own use?
-
-A: Yes. All plugins are Apache-2.0 licensed. Fork, modify, deploy. We appreciate improvements back in PRs, but no obligation.
-
----
-
-### Q: Do these plugins work with managed Kubernetes (EKS, GKE, AKS)?
-
-A: If Headlamp works with your platform, the plugins work. Headlamp just needs API access.
-
-We develop against standard Kubernetes. If you hit a managed-service-specific issue, let us know.
-
----
-
-## When to Say No
-
-### Q: Should I use these in production?
-
-A: Depends on what you mean by "production." If you mean "will it crash my cluster," no. Headlamp + plugins are read-only.
-
-If you mean "is this enterprise-grade," probably not yet. We're under 1 year old. We're useful, not bulletproof.
-
-Try it. Monitor it. Have a fallback (you do have kubectl, right?). If it fails, switch back.
-
----
-
-### Q: Can these plugins replace my existing monitoring stack?
-
-A: No. Don't try. This is visibility, not comprehensive monitoring.
-
-You still need logs, metrics, traces, alerting. We're the UI layer for cluster state + specialized views.
-
----
-
-## Getting Help
-
-### Q: I found a bug. What do I do?
-
-A: GitHub issue with:
-- What you were doing
-- What happened
-- What you expected to happen
-- Your Kubernetes version
-- Your Headlamp version
-- Plugin version
-
-Specificity helps. "It doesn't work" doesn't. "When I click the Rook tab, I get a 403 error" does.
-
----
-
-### Q: I want to contribute. Where do I start?
-
-A: GitHub issues with `good first issue` label. Read the CONTRIBUTING.md in each repo. Start small.
-
-We're a small team. contributions that improve things make a real difference.
-
----
-
-## The Honest Version
-
-Headlamp plugins are for people who:
-- Are already running Kubernetes in production
-- Understand their observability gaps
-- Want small, focused tools instead of monolithic platforms
-- Are comfortable with "good enough" software from small teams
-
-If you need enterprise support, SLAs, and hand-holding, we're not it (yet). If you want useful tools that respect your workflow and don't try to be everything, we might be.
-
-Try us. If we don't fit, no hard feelings. There are plenty of other dashboards. Find the one that works for your team.
-
----
-
-**Last updated**: March 13, 2026
-**Audience**: Kubernetes operators, platform engineers, storage admins
-**Tone**: Honest, not salesy, specific, realistic about limitations
-

kubecon-prep/KUBECON_RESPONSE_TEMPLATES.md

@@ -1,176 +0,0 @@
-# KubeCon EU 2026 — Response & Tactical Post Templates
-
-**Status**: Ready-to-deploy. Update dates/times as conference progresses. Use if conversations align with these narratives.
-
----
-
-## Pre-KubeCon (March 21-22)
-
-### Template 1: The Headlamp Moment
-
-**Platform**: Twitter/X
-**Trigger**: When #KubeCon hashtag begins heating up, someone mentions "dashboard" or "UI"
-
-**Post**:
-if you're heading to #KubeCon and you're thinking "I wish I could see what's actually happening in my cluster without opening 6 different tools," we have 6 plugins for that.
-
-see you in Amsterdam.
-
-**CMO Note**: Soft sell. Positions us as understaters. Uses first-person ("we have") rather than "check out." Timing: Friday-Saturday before conference opens.
-
----
-
-### Template 2: The "Cold Take" on Platform Engineering
-
-**Platform**: Bluesky
-**Trigger**: Platform engineering talks announced, or engineering teams mention "observability as a competitive advantage"
-
-**Post**:
-Platform teams spend 2024 building observability. They spent 2025 fighting with it. KubeCon 2026 is about finally making it *work*.
-
-(Hint: Headlamp makes the "finally" part easier.)
-
-**CMO Note**: Positions us as people who understand the maturity curve. Not condescending. Acknowledges that good observability is *work* not just tooling. Implies we've thought about this problem space.
-
----
-
-## Main Conference (March 23-26)
-
-### Template 3: The "We're Not Doing That" Take
-
-**Platform**: Twitter/X
-**Trigger**: Someone tweets about "AI-powered monitoring" hype, or a vendor announces overly complex AI-observability features
-
-**Post**:
-watched a demo of AI observability that required 3 new dashboards and 2 vendor contracts to set up.
-
-the goal of observability is seeing what's wrong. if your tool gets in the way of that, it's not observability.
-
-(we kept ours simple.)
-
-**CMO Note**: Leans into Headlamp's philosophy (small, focused plugins) vs. sprawling observability stacks. Not attacking anyone. Just stating our bias. Safe because we actually *do* keep our approach simple.
-
----
-
-### Template 4: Real-Time Response to "How Do You Monitor [X]"
-
-**Platform**: Twitter/X (Thread)
-**Trigger**: Someone asks "how do you monitor GPU usage" or "how do you track CSI performance"
-
-**Thread Option A** (GPU):
-Q: How do you monitor GPU usage in Kubernetes?
-
-Short answer: You look at actual metrics. Not dashboards about dashboards. Not vendor abstractions. You look at what your hardware is actually doing.
-
-Headlamp + intel-gpu plugin. See your GPU. No middleman. [link to docs]
-
-**Thread Option B** (Storage):
-Q: How do you track Rook/Ceph performance?
-
-Real answer: Stop thinking about monitoring as a separate system. Rook is part of your cluster. You need visibility into it from the same place you look at everything else.
-
-That's the whole reason we built the Rook plugin. [link to docs]
-
-**CMO Note**: These are hyperspecific. Only deploy if question arises. Shows expertise without being pushy. Links to actual docs (once we have them on GH pages).
-
----
-
-### Template 5: The "We Attend Quietly" Take
-
-**Platform**: Mastodon
-**Trigger**: General KubeCon reflection mid-conference (March 24-25)
-
-**Post**:
-KubeCon observation: Nobody is pretending their observability stack is simple anymore. Everyone admits it's complex. The conversation has shifted from "we have visibility" to "how do we make visibility manageable."
-
-We have a thesis on that. (It involves not adding more layers.)
-
-**CMO Note**: Intellectual positioning. Suggests we have *design philosophy* not just tools. Mastodon audience appreciates meta-commentary about industry trends. Doesn't mention product directly until the last line.
-
----
-
-## If External Events (March 21-27)
-
-### Template 6: Security/Supply Chain Angle
-
-**Trigger**: If a security incident, CVE, or supply chain story breaks during conference
-
-**Platform**: Twitter/X
-**Post**:
-[Current incident] is why we built sealed-secrets plugin.
-
-Not because we think we're special. Because operators shouldn't have to choose between "use secrets" and "know where they're being stored."
-
-If you're at #KubeCon, stop by and we can talk about it. [link]
-
-**CMO Note**: Shows we're paying attention. Ties conference energy to our actual products. Empathetic (don't position as saviors, just problem-solvers). Only use if an actual security story breaks.
-
----
-
-### Template 7: Cost Angle
-
-**Trigger**: If cost/efficiency is a hot KubeCon keynote theme, or someone discusses "cost-aware monitoring"
-
-**Platform**: LinkedIn
-**Post**:
-KubeCon theme observation: "Cost-aware observability" is trending because teams are finally admitting that monitoring infrastructure is expensive.
-
-The plugin approach (small, focused, optional) is inherently cost-aware. You don't pay for observability you don't use.
-
-This is intentional design.
-
-**CMO Note**: Positions Headlamp's modular philosophy as a *feature*. Not "we're cheaper" but "we're more efficient by design." Works if cost is a main theme.
-
----
-
-## Post-KubeCon (March 27+)
-
-### Template 8: The Recap
-
-**Platform**: Twitter/X
-**Trigger**: March 27-28, after conference ends
-
-**Post**:
-KubeCon takeaway: The best tools are the ones your team forgets they're using because they just work.
-
-We built Headlamp plugins like that. Small. Focused. Invisible until you need them.
-
-Did we miss you in Amsterdam? [link to plugin docs]
-
-**CMO Note**: Humble, unsalesy. Doesn't claim we nailed it, just states our design goal. Bridges back to self-directed learning/documentation (not aggressive marketing).
-
----
-
-## General Guidelines for Day-Of Responses
-
-1. **Monitor, don't dominate**: Respond to conversations, don't start them.
-2. **Listen for pain, not keywords**: "I can't see X" beats "person mentioned dashboard."
-3. **Be helpful first**: Answer questions. Mention our stuff only if relevant.
-4. **Keep it real**: If someone asks a question we don't have a good answer for, say so.
-5. **Timing**: Responses should go out within 2-4 hours of trigger, not instant (not trying too hard).
-6. **Tone check**: Every response should pass the "would an actual operator write this" test.
-
----
-
-## Tools & Hashtags
-
-**Primary hashtag**: #KubeCon (volume 24-26 March)
-**Secondary hashtags**: #KubeCon2026, #cloudnative, #kubernetes
-**Response hashtags**: #observability, #k8s, #platform-engineering (context-specific)
-
-**Monitoring tools** (if CMO provides access):
-- Twitter search: `#KubeCon`
-- Bluesky search: `KubeCon`
-- Reddit: r/kubernetes, r/devops, r/SRE (watch for questions)
-- Slack (if we're in cloud-native Slack): #kubecon-2026
-
----
-
-## Notes
-
-- These are *optional* responses, not a mandate to post daily
-- Only deploy if you believe the response is valuable (not hitting publish for metric's sake)
-- If conference energy is low or our voice doesn't fit the conversation, that's fine
-- Post-KubeCon reflection is most important; day-of is engagement sugar
-- If something unexpected breaks (security issue, major outage), escalate to CMO before responding
-

skills/coding-standards/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: coding-standards
+description: >
+  Engineering quality bar for GroomBook code: priority ordering of correctness
+  vs. clarity vs. maintainability vs. performance vs. elegance, PR and test
+  requirements, no-hardcoded-values rules, branch discipline, and the no-self-
+  merge contract.
+---
+
+# Coding Standards
+
+These rules apply to any GroomBook agent that writes, reviews, or merges code.
+
+## Priority ordering
+
+When making technical decisions, prioritize in this order:
+
+1. **Correctness** — does it work? Does it handle edge cases? Have you proven it, not assumed it?
+2. **Clarity** — will another engineer understand this without context in 6 months?
+3. **Maintainability** — will it be safe to change?
+4. **Performance** — fast enough for the use case? Profile before optimizing.
+5. **Elegance** — nice if free; never trade any of the above for it.
+
+## Pull request discipline
+
+* All changes go through a PR. **Never push directly to `dev`, `uat`, or `main`.**
+* No agent merges their own PR.
+* Always include `cc @cpfarhood` at the bottom of the PR body for visibility (not as a reviewer).
+
+## Test requirements
+
+* **Every PR must include tests** for new code paths. No exceptions for "small" changes.
+* Run unit tests, type check, and lint locally (or rely on CI) **before** requesting review.
+* A PR without passing tests does not get approval.
+* New code paths require coverage. No coverage = no approval.
+
+## Code review tone
+
+Hold a high bar. PRs with obvious mistakes, missing tests, hardcoded values, or policy violations get firm, specific review comments citing what's wrong and what the fix is. Cite the file and line. Suggest the fix when you know it. Don't sugarcoat — but be professional and constructive. "This looks wrong" is not a review comment.
+
+## Hardcoded values
+
+* **Colors** use CSS variables / theme tokens. Never raw hex in components.
+* **Strings** use constants or i18n. No magic strings.
+* **Numbers** that aren't trivially obvious go in named constants.
+* **No magic numbers** in business logic.
+
+## Secrets in code
+
+Secrets never touch source. See the `safety` skill for the SealedSecrets workflow. If your implementation requires a Kubernetes secret you cannot create, file an issue for the agent who owns the SealedSecrets workflow rather than committing a plaintext value.
+
+## Releases and versioning
+
+All releases use CalVer (`YYYY.MMDD.PATCH`, e.g. `2026.0504.0`). No SemVer, no custom schemes.
+
+## Container images
+
+Push to `ghcr.io` only. Never Docker Hub for first-party images.
+
+## When uncertain
+
+If a code-quality call isn't covered above and you can't decide cleanly, escalate to the CTO via comment rather than guessing.

skills/safety/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: safety
+description: >
+  Non-negotiable safety rules for all GroomBook agents. Covers secret handling,
+  destructive-action gating, the SealedSecrets workflow, kubectl scope limits,
+  and the escalation protocol when an action's safety is uncertain.
+---
+
+# Safety
+
+The following rules apply to every GroomBook agent without exception.
+
+## Non-negotiable rules
+
+* **Never exfiltrate secrets or private data.** This includes API keys, tokens, PEM files, database credentials, kubeconfig contents, and any value sourced from a secret reference in your adapter config. Never log, comment, or return these values in any output — including PR descriptions, issue comments, and chat responses.
+
+* **Seek board approval before destructive actions.** "Destructive" means: deleting resources, dropping tables, wiping namespaces, force-pushing branches, resetting git history, removing secrets, or any operation that cannot be undone without restoring from backup. Use `request_board_approval` and set the source issue to `blocked` until approved.
+
+* **Never commit plaintext secrets.** Kubernetes secrets go through Bitnami Sealed Secrets (`kubeseal`). Application credentials go in environment variables injected at runtime — never hardcoded in source.
+
+* **Never `kubectl apply` against production (`groombook`).** The production namespace is Flux-managed. Manifest changes go through a PR to `groombook/infra` and are reconciled by Flux. The `groombook-dev` and `groombook-uat` namespaces permit direct kubectl use for iteration; secrets at every environment still follow the SealedSecrets pattern.
+
+* **Never `kubectl create secret` in production.** All secrets — at every environment — go through SealedSecrets, encrypted with `kubeseal`, committed as `SealedSecret` resources to `groombook/infra`.
+
+* **Never bypass the merge gate.** No self-merging PRs. No pushing directly to `dev`, `uat`, or `main`. Every change goes through a PR with the reviews required by the `sdlc` skill.
+
+* **Never run `tofu` directly.** Terraform / OpenTofu goes through the Flux OpenTofu Controller via a PR to `groombook/infra`.
+
+## If you are unsure
+
+If you are unsure whether an action is safe, **stop**. Post a comment on the Paperclip issue explaining what you are about to do and why you are uncertain, set the issue to `blocked`, and escalate to your manager. Do not guess.

skills/sdlc/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: sdlc
+description: >
+  Software development lifecycle for GroomBook. Covers Gitea authentication,
+  branch strategy across Dev/UAT/Prod, the four-phase SDLC pipeline with
+  product analysis intake, PR review and merge policy, the handoff protocol,
+  status semantics, infrastructure layout, the canonical tools list, the
+  Gitea-origin issue board-approval gate, the cc-cpfarhood visibility rule,
+  the scheduled penetration testing program, and delegation model tier policy.
+---
+
+# Software Development Lifecycle
+
+## Gitea authentication
+
+**Use the `tea` CLI** with the `GITEA_TOKEN` environment variable for all Gitea operations. Configure it once:
+
+```bash
+tea login add --url https://git.farh.net --token $GITEA_TOKEN --name groombook
+```
+
+Gitea is the **primary source of truth**. Every Paperclip issue should have a corresponding Gitea issue (create one if missing). Both stay open until the work is completed, reviewed, approved, merged, and QA-verified.
+
+## Gitea-origin issue policy — board approval required
+
+If a task originated from Gitea (`originKind: "gitea"`), **do not begin work**. Immediately create a board approval:
+
+```
+POST /api/companies/{companyId}/approvals
+{
+  "type": "request_board_approval",
+  "requestedByAgentId": "{your-agent-id}",
+  "issueIds": ["{issueId}"],
+  "payload": {
+    "title": "Board approval required: Gitea issue",
+    "summary": "Summarize what the Gitea issue requests.",
+    "recommendedAction": "Approve to begin work.",
+    "risks": ["Work begins without board review if approved."]
+  }
+}
+```
+
+Set the issue to `blocked` with a comment linking to the approval. Only proceed once `PAPERCLIP_APPROVAL_ID` is set and `PAPERCLIP_APPROVAL_STATUS` indicates approval.
+
+## Branch strategy
+
+Three long-lived branches map to the three deployment environments:
+
+| Branch | Environment | Who merges |
+|--------|-------------|-----------|
+| `dev`  | Dev         | CTO (after QA approval)            |
+| `uat`  | UAT         | CTO (promotes `dev` → `uat`)        |
+| `main` | Production  | CEO (promotes `uat` → `main`)       |
+
+**Engineers always target `dev`** — never `uat` or `main` directly. Feature branches: `<agent-name>/<short-description>`.
+
+## Pull requests
+
+All changes happen via pull request. Always include `cc @cpfarhood` at the bottom of the PR body for visibility — never as a reviewer.
+
+```bash
+tea pr create --base dev --title "..." --body "... cc @cpfarhood"
+```
+
+## PR review & merge policy
+
+### Dev branch (`dev`)
+
+- **QA** (Lint Roller) reviews the PR. Approve → hand to CTO. Fail → back to engineer directly with exact details.
+- **CTO** (The Dogfather) reviews. Approve → CTO merges the `dev` PR. Fail → back to engineer.
+
+### UAT branch (`uat`)
+
+- **CTO** opens and merges a `dev` → `uat` PR.
+
+### Main branch (`main`)
+
+- **CEO** (Scrubs McBarkley) reviews and merges the `uat` → `main` PR.
+
+`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer.
+
+## SDLC pipeline
+
+### Phase 0 — Product analysis (feature intake)
+
+* Feature requests arrive at the CEO via Paperclip or Gitea Issues.
+* CEO delegates to CMPO (Pawla Abdul) for review.
+* CMPO returns one of three decisions:
+  * **Accepted** → CEO routes to CTO for work breakdown.
+  * **Backlogged** → CEO handles prioritization.
+  * **Denied** → CEO closes as unplanned.
+* CTO breaks accepted work into atomic tasks and assigns to Engineering.
+
+### Phase 1 — Dev
+
+1. **Engineer** (Flea Flicker) branches from `dev`, writes code. GitOps deploys to dev on demand.
+2. **Engineer** opens a PR against `dev`. CI must pass.
+3. **QA (Lint Roller)** reviews the PR. Fail → back to engineer.
+4. QA approves and hands off to CTO.
+5. **CTO (The Dogfather)** reviews the PR. Fail → back to engineer.
+6. **CTO** merges the dev PR.
+7. **CI** builds and deploys automatically to Dev (`https://dev.groombook.dev`).
+
+### Phase 2 — UAT promotion
+
+8. **CTO** opens and merges a PR from `dev` to `uat`.
+9. **CI** builds and deploys automatically to UAT (`https://uat.groombook.dev`).
+10. **CTO** creates a UAT regression task for **Shedward Scissorhands** immediately after promoting.
+
+### Phase 3 — UAT testing & security
+
+11. **UAT (Shedward Scissorhands)** runs full regression against UAT — every feature, no exceptions.
+12. UAT fail → CTO redistributes to engineer (return to Phase 1).
+13. UAT pass → **Security Engineer (Barkley Trimsworth)** performs a security code review of the changes.
+14. Security fail → CTO redistributes to engineer (return to Phase 1).
+
+### Phase 4 — Production
+
+15. Security pass → **CEO (Scrubs McBarkley)** reviews and merges the production PR (`uat → main`). Fail → back to CTO.
+16. **CI** deploys automatically to Production (`https://demo.groombook.dev`).
+
+### Hierarchy rules
+
+* CTO rejections at Dev go directly to the engineer (not back through QA).
+* UAT failures (Shedward) go to CTO — CTO cascades to engineer.
+* Security failures (Barkley) go to CTO — CTO cascades to engineer.
+* CEO rejections at Prod go to CTO.
+
+> **Penetration testing.** Barkley performs scheduled penetration testing against Production (`demo.groombook.dev`) and Demo independently of the PR workflow. Board-authorized; not triggered per-PR. Findings get filed as Paperclip issues with severity (`CRITICAL` / `HIGH` / `MEDIUM` / `LOW`) and routed to CTO for engineer redistribution.
+
+## Delegation model tier
+
+When creating subtasks for other agents, set `modelProfile: "cheap"` only for:
+- Mechanical refactors or repetitive operations
+- Basic information lookups
+- Well-specified, bounded updates
+
+Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review.
+
+When in doubt, leave it unset.
+
+## Handoff protocol — mandatory
+
+Every handoff to another agent requires ALL THREE steps:
+
+### 1. Explicit assignment
+
+`PATCH /api/issues/{id}` with `assigneeAgentId: "<target-agent-uuid>"`. Mentioning is NOT a handoff — the agent won't wake without explicit assignment.
+
+### 2. Status = `todo`
+
+Every handoff sets `status: "todo"`. Never `in_review`, never `backlog` — both are invisible in inbox-lite and the receiver won't wake.
+
+### 3. Release checkout
+
+```
+POST /api/issues/{issueId}/release
+Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+```
+
+Without this release, the receiving agent cannot check out the issue.
+
+**Saying you are reassigning a task is NOT the same as reassigning it.** Verify the PATCH succeeded (200) before posting a comment claiming the handoff is done.
+
+## Infrastructure
+
+* **Production / Demo:** namespace `groombook`, FQDN `demo.groombook.dev`
+* **UAT:** namespace `groombook-uat`, FQDN `uat.groombook.dev`
+* **Dev:** namespace `groombook-dev`, FQDN `dev.groombook.dev`
+* **Cluster:** Kubernetes — cluster-wide read; read/write on `groombook-dev` and `groombook-uat`; read-only on `groombook` (production).
+* **Gateways:** `istio-external` (publicly accessible) and `istio-internal` (internal only) in `gateway-system`.
+* **Container registry:** `ghcr.io/groombook/<service>` only.
+
+## Authentication
+
+* **Framework:** Better-Auth.
+* **Social login:** Google and Apple OAuth.
+* **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret).
+* **Never build custom authentication.**
+
+## Deployment — 2-stage Flux GitOps
+
+**Stage 1 — CI (Gitea Actions, uses GitHub Actions-compatible YAML syntax, runs in each application repo):**
+- Triggered automatically on every merge to `main`
+- Builds and tags the Docker image
+- Pushes tagged images to `ghcr.io/groombook/<service>`
+
+**Stage 2 — GitOps (Flux, managed externally):**
+- Flux watches `groombook/infra` as the **target** GitRepository — it is **not** a Flux bootstrap/cluster repo.
+- Reconciles Kustomize overlays: `apps/overlays/dev` → `groombook-dev`, `apps/overlays/uat` → `groombook-uat`, `apps/overlays/prod` → `groombook`.
+
+**Policy — Flux Image Tag Automation is DENIED.** Do NOT use `ImageRepository`, `ImagePolicy`, or `ImageUpdateAutomation` Flux resources. Image tag updates must be made intentionally via a PR to `groombook/infra`.
+
+**To deploy a change:**
+1. Merge code to `main` in the app repo — CI builds and pushes a new image automatically.
+2. Open a PR against `groombook/infra` to update the relevant overlay; merge after kustomize CI passes.
+3. Flux reconciles `groombook/infra` on merge and rolls out the updated pods.
+
+**To force a rollout** (pick up new `:latest` on stuck pods):
+```bash
+kubectl rollout restart deployment/<name> -n <namespace>
+```
+
+## Infrastructure as Code
+
+Terraform / OpenTofu is deployed via the **Flux OpenTofu Controller** in a GitOps fashion. Submit configurations via a PR to `groombook/infra` — the tofu controller reconciles them on merge.
+
+**Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only.
+
+## Tools (canonical, not alternatives)
+
+These are the only acceptable choices — alternatives are policy violations:
+
+* **Secret management:** Bitnami Sealed Secrets Controller — no plain Kubernetes secrets.
+* **Database:** CloudNativePG Operator (Postgres) — no SQLite, MariaDB, or MySQL.
+* **Cache / pub-sub:** DragonflyDB Operator — no Redis.
+* **Authentication:** Better-Auth + Google + Apple + Authentik (see Authentication section). Never build custom auth.
+* **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.**
+* **Container registry:** `ghcr.io/groombook/<service>` — no Docker Hub for first-party images.
+
+If a task requires deviating from any of the above, treat it as a destructive action: stop, file an issue with rationale, request board approval.
+
+## External communication
+
+When communicating in any context visible outside the GroomBook agent team (external users, human reviewers, non-agent entities), include `cc @cpfarhood` for visibility — never as a reviewer.
+
+## No self-merge
+
+No agent merges their own PR. The merger is always the next role up the SDLC ladder (CTO for `dev` and `uat`, CEO for `main`).

social/queue/2026-03-07-first-batch.md

@@ -1,85 +0,0 @@
-# Social Media Batch - 2026-03-07
-
-## Strategic Summary
-
-First-ever social batch for Privileged Escalation. The org has 6 Headlamp plugins across storage, security, and infrastructure -- all freshly released, all at zero stars. The play here is name recognition and curiosity: make people encounter "Privileged Escalation" in their feed and wonder what it is before they click. Leading with the sealed-secrets plugin (client-side crypto angle) and the absurdity of launching 6 plugins to zero fanfare.
-
----
-
-## 1. Ready to Post
-
-### Post 1
-
-**Platform**: Twitter/X
-**Post**:
-We shipped 6 Kubernetes Headlamp plugins and nobody noticed.
-
-Storage benchmarking, Rook-Ceph visibility, Polaris auditing, Sealed Secrets with actual client-side encryption, Intel GPU monitoring, and kube-vip dashboards.
-
-Zero stars across the board. We are crushing it.
-
-github.com/privilegedescalation
-**CMO Note**: Self-deprecating launch acknowledgment. The honesty about zero stars is the hook -- it reads as human, not corporate. Links to the org for curious clicks.
-
----
-
-### Post 2
-
-**Platform**: Bluesky
-**Post**:
-the sealed secrets headlamp plugin does client-side RSA-OAEP + AES-256-GCM encryption so your plaintext never leaves the browser.
-
-someone forked it last month. we have our first user. or our first person who accidentally clicked fork. either way, we are celebrating.
-**CMO Note**: Technical specificity makes it credible. The fork joke (sm-moshi, Feb 22) is real and plays well on Bluesky's irony-friendly audience. Seeds curiosity about what Headlamp plugins are.
-
----
-
-### Post 3
-
-**Platform**: Mastodon
-**Post**:
-Genuine question for the fediverse: if you have 6 open source projects and zero stars on any of them, are you a software company or just a guy with a lot of repos?
-
-Asking for a friend. The friend is github.com/privilegedescalation.
-**CMO Note**: Mastodon audience appreciates self-aware humor. This is pure slow-burn -- raises the question of what Privileged Escalation is without explaining it. The link is there for anyone curious enough to click.
-
----
-
-## 2. Risky but Worth Discussing
-
-### Post 4
-
-**Platform**: Twitter/X
-**Post**:
-Every Kubernetes UI either costs money or looks like it was designed during a mass layoff event.
-
-We've been building Headlamp plugins that make the free one actually useful. Rook-Ceph dashboards, Polaris auditing, storage benchmarks -- the stuff you duct-tape together with kubectl and regret.
-
-github.com/privilegedescalation
-**CMO Note**: Mildly spicy take on the K8s UI landscape. Does not name competitors directly but the implication is clear. Could rub Lens/Rancher people the wrong way. Worth discussing tone.
-
----
-
-## 3. Backlog (Evergreen)
-
-### Post 5
-
-**Platform**: LinkedIn
-**Post**:
-We just audited our own GitHub repos and found that 4 out of 6 were missing LICENSE files.
-
-They all had Apache-2.0 badges in the README. The actual license text? Not present. Technically, anyone using our code was operating on vibes and good faith.
-
-Fixed now. But if your open source project has a license badge and no LICENSE file, maybe go check. We'll wait.
-**CMO Note**: Honest product personality at work. Admitting a real flaw (that we just fixed) builds trust and is genuinely useful advice. LinkedIn audience will share practical open source governance content.
-
----
-
-### Post 6
-
-**Platform**: Twitter/X
-**Post**:
-TIL "Privileged Escalation" as a GitHub org name gets flagged by approximately zero security scanners.
-
-We checked.
-**CMO Note**: Pure name recognition play. The org name is inherently memorable and slightly provocative -- leaning into that. Short enough for easy engagement.

social/queue/2026-03-10-why-we-built-these.md

@@ -1,137 +0,0 @@
-# Social Media Batch - 2026-03-10
-
-## Strategic Summary
-
-Six plugins. Each one exists because we had a specific problem in production with no good visibility. This batch is about "why" before "what" — explaining the actual Kubernetes pain point each plugin addresses, from our own experience. It's educational content that works pre-KubeCon: people don't need to know what Headlamp is to understand "oh, that problem sounds familiar." Also serves as support content for the KubeCon campaign dropping next week.
-
----
-
-## 1. Ready to Post
-
-### Post 1: Rook-Ceph Problem
-
-**Platform**: Twitter/X
-
-**Post**:
-You deploy Ceph because it's the right choice for distributed storage. Then you're staring at `ceph status` in a terminal wondering which pool is actually filling up, what the OSD rebalance is doing, and why your capacity projections are off by 40%.
-
-We built headlamp-rook-plugin to see inside Ceph from a dashboard instead of grep-ing logs.
-
-github.com/privilegedescalation
-
-**CMO Note**: Opens with a relatable pain point (Ceph deployment without visibility), then delivers the specific solution (dashboards instead of CLI). No "exciting to announce" language. The problem-first framing resonates with people already running Ceph.
-
----
-
-### Post 2: Sealed Secrets Problem
-
-**Platform**: Bluesky
-
-**Post**:
-Your team has a pattern:
-
-1. Someone generates a secret
-2. They echo it in Slack "here's the password"
-3. It's in the channel history forever
-4. Someone rotates it, forgets to tell the database
-5. 2am incident
-
-We built headlamp-sealed-secrets-plugin so the secret never leaves the browser and stays encrypted in your cluster. The plaintext never transits anywhere someone can screenshot it.
-
-**CMO Note**: Captures the actual workflow failure that sealed-secrets solves. The numbering of the failure pattern is specific and darkly funny. Bluesky audience appreciates the "this is how we actually mess up" honesty.
-
----
-
-### Post 3: Polaris Problem
-
-**Platform**: Mastodon
-
-**Post**:
-Kubernetes best practices are things you know about the week after you've already deployed your application with none of them.
-
-Polaris audits your workloads against security and reliability policies. It shows you what you're doing wrong before it becomes a 3am outage.
-
-We built the headlamp-polaris-plugin so you can actually see the audit results in your dashboard instead of waiting for the automated security scan email you never read.
-
-**CMO Note**: Self-aware about human nature (learning best practices after deployment fails). Polaris is the solution. Mastodon audience gets the candor. Not preachy, just practical.
-
----
-
-### Post 4: Intel GPU Problem
-
-**Platform**: Twitter/X
-
-**Post**:
-You provisioned Intel GPUs in your K8s cluster for ML workloads. Cool.
-
-Now: which node has available GPU? How hot are they running? Is the scheduler actually placing workloads on GPU nodes or just on CPU? Is anything actually using them?
-
-We built headlamp-intel-gpu-plugin to answer those questions from a dashboard instead of kernel logs.
-
-github.com/privilegedescalation
-
-**CMO Note**: Chains questions that GPU cluster operators actually have. Each question hints at a real visibility gap. The solution (dashboard instead of logs) is matter-of-fact. Specific pain point without corporate language.
-
----
-
-### Post 5: TrueNAS CSI Problem
-
-**Platform**: Bluesky
-
-**Post**:
-Your storage driver is configured. Your benchmark says it can do 10k IOPS.
-
-But what's actually happening in production? You're scheduling workloads, moving data around, and your I/O profile looks nothing like the benchmark.
-
-We built headlamp-tns-csi-plugin so you can see kbench storage metrics live in your cluster dashboard. No "apply a manifest and wait for email," just see what your storage is actually doing.
-
-**CMO Note**: Contrasts lab conditions (benchmark) with production reality (actual I/O profile). Storage visibility without waiting. Appeal to operators frustrated with "set it and hope" storage management.
-
----
-
-### Post 6: kube-vip Problem
-
-**Platform**: Twitter/X
-
-**Post**:
-You've got a load balancer. You've got virtual IPs floating around your cluster. And someone's asking "which service is that IP mapped to?"
-
-Now what? Grep the config? Check the VirtualIP manifest? It's 2025 and you're hunting through YAML.
-
-We built headlamp-kube-vip-plugin so virtual IPs and load balancer status show up in your dashboard where you can actually see them.
-
-github.com/privilegedescalation
-
-**CMO Note**: Specific frustration: answering "which service" requires config hunting. The solution is dashboard visibility. Dry tone emphasizing the absurdity of 2025-era manual lookups.
-
----
-
-## 2. Risky but Worth Discussing
-
-### Post 7: Meta Comment (Optional)
-
-**Platform**: Twitter/X
-
-**Post**:
-Six Kubernetes plugins, and the common thread isn't "advanced observability" or "enterprise features."
-
-It's: we had a problem. The CLI wasn't good enough. The logs were hard to parse. So we built a dashboard for it.
-
-Sometimes the answer to "why do we exist" is "we got frustrated with grep."
-
-**CMO Note**: Self-aware meta-commentary on why all six plugins exist. The "we got frustrated with grep" line is the voice we're known for. Could feel slightly salty to some, but earns credibility with operators who've been there. Optional amplification of the whole batch theme.
-
----
-
-## 3. Backlog (Evergreen)
-
-None for this batch — these posts work best as a thematic set posted over 3-5 days while driving toward KubeCon, then are less relevant after.
-
----
-
-## Notes
-
-- Suggested posting schedule: 1 post per day starting tomorrow (March 11), finishing by March 15, giving time for engagement before KubeCon campaign drops March 21
-- Each post stands alone but builds narrative collectively
-- Educational angle differentiates from release announcements and provides value even for non-adopters
-- Heavy on problem framing, light on pitch — fits the voice and builds trust