ci: unbreak main, gate pull requests, and close the factory drift

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,46 @@
+name: "Bug report"
+description: "Something is broken. You are the only person who can confirm it."
+labels: ["1-triage"]
+type: "Bug"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Run `ujust report` before submitting. It captures your image, kernel, hardware, and logs — paste the gist URL below and we likely have everything we need.
+
+  - type: checkboxes
+    id: clanker-opt-in
+    attributes:
+      label: "Agent assistance"
+      options:
+        - label: "Opt-in to making a clanker figure this out"
+          required: false
+
+  - type: input
+    id: report-link
+    attributes:
+      label: "ujust report gist URL"
+      placeholder: "https://gist.github.com/..."
+    validations:
+      required: false
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: "What happened?"
+      description: "What did you see? What did you expect? Be specific — hardware model, exact error text, what you were doing."
+      placeholder: |
+        Bluetooth disappears from the panel after suspend on my Framework 13 AMD.
+        The indicator is gone until I reboot. journalctl shows "hci0: Bluetooth host wakeup failed".
+        Expected it to reconnect automatically, as it does on Fedora 42.
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: "Extra context"
+      description: "Optional — upstream bug links, 'works on X but not Y', anything that narrows the cause."
+      placeholder: "Works fine on the Intel NUC in the same setup. Appears on both 6.14 and 6.15 kernels."
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,44 @@
+name: "Feature request"
+description: "Propose something new. Specific proposals ship. Vague ones wait."
+labels: ["1-triage"]
+type: "Feature"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The bottleneck is almost never implementation — it is clarity. Contributors can ship well-scoped work fast, but only if the finish line is clear.
+
+  - type: checkboxes
+    id: clanker-opt-in
+    attributes:
+      label: "Agent assistance"
+      options:
+        - label: "Opt-in to making a clanker figure this out"
+          required: false
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "What would you like to see?"
+      description: "What is missing, broken, or annoying? Be specific — name the command, the file, the workflow step."
+      placeholder: "Add this feature or ask for a design review"
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: "What does done look like?"
+      description: "What command do you run? What do you see? What file changes?"
+      placeholder: "I should be able to set up Docker in one command"
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: "Extra context"
+      description: "Optional — related issues, upstream references, or files you think are affected."
+      placeholder: "related issues, upstream references, or files you think are affected"
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/help-this-project.yml

@@ -0,0 +1,64 @@
+name: "Help this project"
+description: "Donate agent time — point at a repo, issue, or PR and get a high-signal report back."
+labels: ["1-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Point an agent at a repo, issue, or PR and get a report back. Be specific — "look at this repo" produces a shallow overview, a focused question produces something actionable.
+
+  - type: checkboxes
+    id: clanker-opt-in
+    attributes:
+      label: "Agent assistance"
+      options:
+        - label: "Opt-in to making a clanker figure this out"
+          required: false
+
+  - type: input
+    id: target-url
+    attributes:
+      label: "Target URL"
+      description: "Repo, issue, PR, roadmap, or docs page. Must be publicly accessible."
+      placeholder: "https://github.com/owner/repo"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: flow
+    attributes:
+      label: "What kind of help?"
+      description: "This routes the right agent to the right task."
+      options:
+        - "Project report — survey a repo or org and summarize what needs attention"
+        - "Issue review — read a linked issue and recommend next steps"
+        - "PR review — audit a linked PR for correctness and completeness"
+    validations:
+      required: true
+
+  - type: textarea
+    id: goal
+    attributes:
+      label: "What specifically should the agent focus on?"
+      description: "The more specific you are, the more useful the report. One to three sentences."
+      placeholder: |
+        Check whether the CI pipeline for this repo has any reliability issues that would
+        explain the flaky validate failures we have been seeing. Focus on the BST cache
+        interactions and the bst2 container pin check.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Extra context"
+      description: "Optional. Known problem areas, related Dakota issues, or constraints the agent should respect."
+      placeholder: "Related to #503. The agent should not suggest changes that require a new external dependency."
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        ---
+        Hive will route this to the right agent based on the flow type above. The agent files its report as a comment on this issue.

.github/actions/vm-boot-test/action.yml

@@ -0,0 +1,64 @@
+name: VM guest boot test
+description: >
+  Install QEMU plus UEFI firmware for one architecture and boot-test the
+  podman-vm guest disk in dist-vm/ with tests/vm-boot.sh. Shared by the
+  release pipeline (vm-guest.yml) and the pull-request gate (build.yml) so the
+  gate can never drift from what actually guards publication.
+
+inputs:
+  arch:
+    description: Guest architecture to boot (x86_64 or aarch64).
+    required: true
+
+runs:
+  using: composite
+  steps:
+    # QEMU loads efi-virtio.rom for the consumer's `if=virtio` topology;
+    # ipxe-qemu provides that ROM on both architectures.
+    - name: Install QEMU and UEFI firmware
+      shell: bash
+      env:
+        ARCH: ${{ inputs.arch }}
+      run: |
+        set -euo pipefail
+        sudo apt-get update
+        case "${ARCH}" in
+          x86_64)  sudo apt-get install -y --no-install-recommends qemu-system-x86 qemu-utils ovmf ipxe-qemu ;;
+          aarch64) sudo apt-get install -y --no-install-recommends qemu-system-arm qemu-utils qemu-efi-aarch64 ipxe-qemu ;;
+          *) echo "ERROR: unsupported arch '${ARCH}'" >&2; exit 1 ;;
+        esac
+
+    # GitHub's x86_64 Linux runners expose /dev/kvm, but only to the kvm
+    # group. Widening it lets the boot test run accelerated instead of falling
+    # back to TCG. Best effort, and deliberately not a gate: tests/vm-boot.sh
+    # detects a usable /dev/kvm itself and raises its own timeout when it has
+    # to fall back to software emulation.
+    - name: Make /dev/kvm usable by the runner user
+      shell: bash
+      env:
+        ARCH: ${{ inputs.arch }}
+      run: |
+        set -euo pipefail
+        [ "${ARCH}" = x86_64 ] || exit 0
+        {
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
+            | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+        } || echo "note: could not widen /dev/kvm permissions; the boot test will use TCG"
+
+    - name: Boot-test the ${{ inputs.arch }} disk under QEMU
+      shell: bash
+      run: tests/vm-boot.sh
+
+    # tests/vm-boot.sh copies the captured serial console to tests/artifacts/
+    # on every run and dumps it to stderr on failure; keep the file too, since
+    # a truncated job log is the usual reason a boot failure is hard to read.
+    - name: Upload the captured serial console on failure
+      if: failure()
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v7.0.1
+      with:
+        name: vm-boot-serial-${{ inputs.arch }}
+        path: tests/artifacts/
+        if-no-files-found: ignore
+        retention-days: 7

.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+# FSDK Containers Copilot Instructions
+
+Read [`AGENTS.md`](../AGENTS.md) and `docs/skills/README.md` first.
+Use the shared [label workflow](https://github.com/projectbluefin/common/blob/main/docs/skills/label-workflow.md):
+humans triage and approve, agents claim `status/queued`, and Clankers only
+transports Hive assignments. Never write to `ublue-os/*`.

.github/workflows/actionlint.yml

@@ -0,0 +1,38 @@
+name: actionlint
+
+# The delivery pipeline is ~25KB of workflow YAML plus a composite action, and
+# a typo in it is only discovered by a red release run. Lint it like code.
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/**'
+      - '.github/actions/**'
+  push:
+    branches: [main]
+    paths:
+      - '.github/workflows/**'
+      - '.github/actions/**'
+
+permissions: {}
+
+jobs:
+  actionlint:
+    name: Lint GitHub Actions
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # reviewdog's github-pr-check reporter annotates the PR.
+      checks: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run actionlint
+        uses: reviewdog/action-actionlint@50842263c20a7c46bd0065b9e624d3c569db061e # v1.73.0
+        with:
+          reporter: github-pr-check
+          fail_on_error: true

.github/workflows/auto-update-fsdk.yml

@@ -9,15 +9,23 @@ concurrency:
   group: auto-update-fsdk
   cancel-in-progress: true
 
+# All writes (branch push, PR creation, repository_dispatch) use a Mergeraptor
+# app token, so this workflow needs no write permissions of its own.
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
 
 jobs:
   update-fsdk:
     runs-on: ubuntu-24.04
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # The branch is pushed with the app token below, never with the
+          # workflow's own credentials: a push made with GITHUB_TOKEN does not
+          # trigger the build workflow, so the bump PR would sit there with no
+          # checks on it.
+          persist-credentials: false
 
       - uses: taiki-e/install-action@16b05812d776ae1dfaabc8277e421fb6d2506419 # v2
         with:
@@ -43,11 +51,12 @@ jobs:
         run: |
           just validate
 
-      # PATs are banned org-wide; the default GITHUB_TOKEN cannot trigger
-      # downstream workflows. Use a Mergeraptor App installation token so the
-      # repository_dispatch actually starts the build workflow (see
-      # docs/skills/ci-tooling.md). Requires MERGERAPTOR_APP_ID and
-      # MERGERAPTOR_PRIVATE_KEY repository secrets to be configured.
+      # PATs are banned org-wide, and the default GITHUB_TOKEN cannot trigger
+      # downstream workflows. Mergeraptor is an org-level GitHub App whose
+      # permissions are already granted, so this mints a short-lived
+      # installation token from the existing MERGERAPTOR_APP_ID and
+      # MERGERAPTOR_PRIVATE_KEY secrets -- no PAT, no new secret, no new
+      # permission (see docs/skills/ci-tooling.md).
       - name: Get mergeraptor token
         if: steps.check_changes.outputs.changes == 'true'
         id: app-token
@@ -60,6 +69,7 @@ jobs:
         if: steps.check_changes.outputs.changes == 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPOSITORY: ${{ github.repository }}
         run: |
           set -euo pipefail
           BRANCH="auto/update-fsdk"
@@ -73,8 +83,13 @@ jobs:
           git add elements/freedesktop-sdk.bst
           git commit -m "chore: bump freedesktop-sdk point release" -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
 
-          # Force push to overwrite any previous update branch
-          git push --force origin "$BRANCH"
+          # Push with the app token, not the workflow's own credentials: a
+          # branch pushed with GITHUB_TOKEN does not trigger the build
+          # workflow, so the bump PR would carry no checks at all. Force push
+          # to overwrite any previous update branch.
+          git push --force \
+            "https://x-access-token:${GH_TOKEN}@github.com/${REPOSITORY}.git" \
+            "HEAD:refs/heads/${BRANCH}"
 
           # Create pull request if it doesn't already exist
           EXISTING_PR=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null || true)
@@ -91,6 +106,6 @@ jobs:
 
           # Send a repository dispatch to trigger the multi-arch build workflow on the PR branch
           echo "==> Sending repository dispatch to test the new FSDK point release..."
-          gh api repos/${{ github.repository }}/dispatches \
+          gh api "repos/${REPOSITORY}/dispatches" \
             -f event_type="fsdk-updated" \
             -F "client_payload[ref]=refs/heads/$BRANCH"