ShadowfetchLinux · ShadowfetchLinux · Aug 21, 2026
diff --git a/.github/CI-SECRETS.md b/.github/CI-SECRETS.md
@@ -5,22 +5,31 @@ The release pipeline (`.github/workflows/build-iso.yml`) needs these secrets con
 
 | Secret | What | Where to get it |
 |---|---|---|
-| `RELEASE_GITHUB_TOKEN` | GitHub PAT used by `softprops/action-gh-release` to create signed releases. Needs `contents:write` on this repo. | github.com → Settings → Developer settings → Personal access tokens. **Already set.** |
-| `SHADOWFETCH_GPG_PRIVATE_KEY` | ASCII-armored private key for the Shadowfetch APT/ISO signing key (fingerprint `8F13CE1535EE1F4A2916A1F73C5C900B7BE80CA1`). Used to sign the ISO and the reprepro repo. | Export from the build host with: `gpg --armor --export-secret-keys signing@shadowfetch.com`. **Not yet set.** |
-| `R2_ACCESS_KEY_ID` | Access Key ID for an R2 API token scoped to `shadowfetch-linux` bucket (Object Read & Write). | Cloudflare dashboard → R2 → Manage R2 API Tokens → Create. **Not yet set.** (Old token used for manual publish should be rotated.) |
-| `R2_SECRET_ACCESS_KEY` | Secret Access Key paired with `R2_ACCESS_KEY_ID`. | Shown once when token is created. **Not yet set.** |
-| `CLOUDFLARE_API_TOKEN` | Cloudflare API token used by `wrangler deploy` to publish the `shadowfetch-linux` Worker. Needs Workers Scripts:Edit + Workers Routes:Edit + Workers KV:Edit on the account, on zone `shadowfetch.com`. | Cloudflare dashboard → My Profile → API Tokens → Create. **Not yet set.** |
+| `RELEASE_GITHUB_TOKEN` | GitHub PAT used by `softprops/action-gh-release` to create signed releases. Needs `contents:write` on this repo. | github.com → Settings → Developer settings → Personal access tokens. |
+| `SHADOWFETCH_GPG_PRIVATE_KEY` | ASCII-armored private key for the Shadowfetch APT/ISO signing key (fingerprint `8F13CE1535EE1F4A2916A1F73C5C900B7BE80CA1`). Used to sign the ISO and the reprepro repo. | Export from the build host with: `gpg --armor --export-secret-keys signing@shadowfetch.com`. |
+| `R2_ACCESS_KEY_ID` | Access Key ID for an R2 API token scoped to `shadowfetch-linux` bucket (Object Read & Write). | Cloudflare dashboard → R2 → Manage R2 API Tokens → Create. Rotate any token that was used for manual publish. |
+| `R2_SECRET_ACCESS_KEY` | Secret Access Key paired with `R2_ACCESS_KEY_ID`. | Shown once when the token is created. |
+| `CLOUDFLARE_API_TOKEN` | Cloudflare API token used by `wrangler deploy` to publish the `shadowfetch-linux` Worker. Needs Workers Scripts:Edit + Workers Routes:Edit + Workers KV:Edit on the account, on zone `shadowfetch.com`. | Cloudflare dashboard → My Profile → API Tokens → Create. |
+
+This file names secrets. It does not contain secret values. Do not paste key
+material, tokens, or `.env` contents into issues, PRs, or this document.
+
+The ISO itself is **not** uploaded to GitHub Releases (2 GiB per-file limit;
+2.1.5 is 3.97 GB). The workflow attaches only `.iso.sha256` and `.iso.asc`.
 
 ## How the workflow triggers
 
-- **Tag push (`v*`)**: full release pipeline — build ISO, sign, publish to R2, deploy Worker, create draft GitHub release.
-- **Manual dispatch (`workflow_dispatch`)**: build only by default; choose `publish=true` to also publish + deploy. Useful for dry-runs.
+- **Tag push (`v*`):** full release pipeline — build ISO, sign, publish to R2, deploy Worker, create draft GitHub release.
+- **Manual dispatch (`workflow_dispatch`):** build only by default; choose `publish=true` to also publish + deploy. Useful for dry-runs.
 
 ## Cutting a release
 
 ```sh
-git tag v1.0.1
-git push origin v1.0.1
+git tag v2.1.5
+git push origin v2.1.5
 ```
 
-Workflow runs in CI. When it finishes (~60 min), publish the draft release in the GitHub UI.
+The tag name must match `VERSION` in the Makefile (`v2.1.5` for the current
+tree). Workflow runs in CI. When it finishes, publish the draft release in the
+GitHub UI. Paste verify URLs from `docs/GITHUB-RELEASE.md` if the generated
+body is too thin.
diff --git a/.github/DISCUSSION_TEMPLATE/support.yml b/.github/DISCUSSION_TEMPLATE/support.yml
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -6,14 +6,14 @@ body:
   - type: markdown
     attributes:
       value: |
-        Use Discussions for support questions. Use this form for reproducible bugs.
+        Use this form for reproducible bugs. Hardware compatibility notes belong on the Hardware report form.
         Do not attach password CSVs, secrets, tokens, or unredacted private logs.
   - type: input
     id: iso
     attributes:
       label: ISO filename
       description: Exact ISO filename you downloaded or installed from.
-      placeholder: shadowfetch-2.1.1-amd64.iso
+      placeholder: shadowfetch-2.1.5-amd64.iso
     validations:
       required: true
   - type: dropdown

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,11 +1,11 @@
-blank_issues_enabled: false
+blank_issues_enabled: true
 contact_links:
-  - name: Support questions and install help
-    url: https://github.com/ShadowfetchLinux/shadowfetch-linux/discussions
-    about: Use Discussions for questions, install reports, and hardware notes that are not reproducible bugs.
   - name: Verification guide
     url: https://www.shadowfetchlinux.org/verify
     about: Verify the ISO checksum, detached signature, and signing key before installing.
   - name: Security model
     url: https://www.shadowfetchlinux.org/security
-    about: Read the Shadowfetch Linux security model and reporting guidance.
+    about: Read the Shadowfetch Linux security model. Report vulnerabilities privately to shadowfetchlinux@gmail.com.
+  - name: Canonical website
+    url: https://www.shadowfetchlinux.org
+    about: Download page, install guide, known issues, and the current 2.1.5 release notes.
diff --git a/.github/ISSUE_TEMPLATE/hardware_report.yml b/.github/ISSUE_TEMPLATE/hardware_report.yml
@@ -6,8 +6,16 @@ body:
   - type: markdown
     attributes:
       value: |
-        Hardware reports help build the community test matrix. Use Discussions for support questions before opening a bug.
+        Hardware reports help build the community test matrix. Reproducible bugs belong on the Bug report form.
         Do not attach secrets, password CSVs, or unredacted private diagnostics.
+  - type: input
+    id: iso
+    attributes:
+      label: ISO filename
+      description: Exact ISO filename you downloaded or installed from.
+      placeholder: shadowfetch-2.1.5-amd64.iso
+    validations:
+      required: true
   - type: input
     id: computer_model
     attributes:

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,13 @@
+## What this PR changes
+
+- [ ] `make source-gate` passes locally (or I explain why it cannot run here)
+- [ ] No ISO, torrent, `.deb`, GPG private key, Cloudflare token, or secret leaked in the diff
+- [ ] Docs and comments match 2.1.5 if they mention the current stable
+
+## How to test
+
+<!-- commands, ISO filename, or "docs only" -->
+
+## Notes
+
+<!-- hardware, follow-ups, or why product behavior is untouched -->
diff --git a/.github/workflows/build-iso.yml b/.github/workflows/build-iso.yml
@@ -99,6 +99,27 @@ jobs:
           npm install -g wrangler
           cd web/shadowfetch-linux-worker && wrangler deploy
 
+      - name: Compose GitHub release notes
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION=$(awk '/^VERSION[[:space:]]*\?=/{print $3; exit}' Makefile)
+          ISO="shadowfetch-${VERSION}-amd64.iso"
+          SHA=$(awk '{print $1; exit}' "${ISO}.sha256")
+          cat > /tmp/github-release-body.md <<EOF
+          GitHub does not host the ISO (this image is larger than GitHub's 2 GiB per-file limit). Download the signed image from the freeze host, then verify it.
+
+          - **ISO:** https://www.shadowfetch.com/linux/download/${ISO}
+          - **SHA-256:** \`${SHA}\`
+          - **Checksum sidecar:** https://www.shadowfetch.com/linux/download/${ISO}.sha256
+          - **Signature:** https://www.shadowfetch.com/linux/download/${ISO}.asc
+          - **Signing key:** https://www.shadowfetch.com/linux/shadowfetch.gpg.asc
+          - **Fingerprint:** \`8F13 CE15 35EE 1F4A 2916  A1F7 3C5C 900B 7BE8 0CA1\`
+          - **Verify guide:** https://www.shadowfetchlinux.org/verify
+          - **Download page:** https://www.shadowfetchlinux.org/download
+
+          This draft also attaches the small \`.iso.sha256\` and \`.iso.asc\` files. Do not attach the ISO itself.
+          EOF
+
       - name: Create GitHub release on tag
         if: startsWith(github.ref, 'refs/tags/v')
         uses: softprops/action-gh-release@v2
@@ -108,10 +129,7 @@ jobs:
           name: ${{ github.ref_name }}
           draft: true
           generate_release_notes: true
-          body: |
-            The signed ISO is hosted on Shadowfetch's release storage because
-            GitHub release assets have a 2 GiB per-file limit. Verify the R2
-            download with the attached checksum and detached signature.
+          body_path: /tmp/github-release-body.md
           files: |
             *.iso.sha256
             *.iso.asc
diff --git a/.gitignore b/.gitignore
@@ -110,3 +110,20 @@ packages/shadowfetch-welcome/debian/shadowfetch-welcome/
 # QA evidence + release scratch (regenerable; matches the /work/qa-2.1.4 precedent)
 /work/
 /live-build/binary.contents
+
+# Release blobs that must not land in git (ISO bodies already match *.iso)
+*.torrent
+*.iso.torrent
+
+# Extra Debian binary leftovers
+*.udeb
+*.ddeb
+
+# OpenPGP private material. Public ASCII-armored keys (shadowfetch-release.asc,
+# SHA256SUMS.asc) are committed on purpose.
+private-keys-v1.d/
+openpgp-revocs.d/
+secring.*
+*.secret.asc
+id_rsa
+id_ed25519
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,39 @@
+# Contributing
+
+Pull requests to the build scripts, in-house packages, docs, QA gates, and the
+release Worker are welcome. Feature work that changes Control Center, Buzz,
+Phoenix, Fireproof, or the first-run agent installers should come with a
+reproducer or a `make source-gate` failure that the change fixes.
+
+## Before you open a PR
+
+```sh
+make source-gate
+```
+
+That is the same source/test/secret gate the Makefile documents. You do not
+need the signing key or Cloudflare credentials to run it.
+
+Do not commit:
+
+- ISO images, torrents, or other multi-gigabyte release blobs
+- `.deb` / `dpkg-buildpackage` artifacts
+- GPG private keys, Cloudflare tokens, R2 keys, or `.env` files
+- password CSVs, unredacted `shadowfetch-health` dumps, or private logs
+
+## Bugs and hardware reports
+
+Use GitHub Issues with the **Bug report** or **Hardware report** form:
+
+https://github.com/ShadowfetchLinux/shadowfetch-linux/issues
+
+A good bug report includes the exact ISO filename and whether the checksum
+matched, UEFI vs BIOS and Secure Boot state, CPU/GPU/RAM/disk/Wi-Fi, and
+redacted `shadowfetch-health --json` output.
+
+## License
+
+By contributing you agree your changes ship under this repository's licenses:
+GPL-3.0-or-later for the tree (see `LICENSE`), plus each package's
+`debian/copyright`. The Shadowfetch and Umbra names, logos, and wallpapers
+remain reserved; see `TRADEMARKS.md`.
diff --git a/README.md b/README.md
@@ -59,6 +59,8 @@ Shadowfetch Linux is young and honest about its rough edges. If you want a borin
 
 ## Verify first, then install
 
+Guides live on **https://www.shadowfetchlinux.org**. The signed ISO, checksum sidecar, detached signature, GPG key, and APT repo are served from the freeze host **https://www.shadowfetch.com/linux/** — that is the path that actually returns the 3.97 GB image (the `.org` site does not host the ISO bytes).
+
 These commands download the current ISO, its checksum, its detached signature and the signing key, then verify authenticity and integrity. **They do not write to a USB stick.**
 
 ```sh
@@ -75,8 +77,13 @@ A GPG *"not certified with a trusted signature"* warning only means you have not
 
 `8F13 CE15 35EE 1F4A 2916  A1F7 3C5C 900B 7BE8 0CA1`
 
+The same checksum is recorded in [`SHA256SUMS`](SHA256SUMS) in this repository. The public key copy is [`shadowfetch-release.asc`](shadowfetch-release.asc).
+
+**GitHub Releases do not attach the ISO.** GitHub's per-file limit is 2 GiB; this image is 3.97 GB. Tag [v2.1.5](https://github.com/ShadowfetchLinux/shadowfetch-linux/releases/tag/v2.1.5) is the source snapshot plus release notes. Download the image from the freeze host above, or from a mirror.
+
 **Mirrors (same ISO, same checksums):**
-- Primary: https://www.shadowfetchlinux.org/download
+- Download page: https://www.shadowfetchlinux.org/download
+- Freeze host ISO: https://www.shadowfetch.com/linux/download/shadowfetch-2.1.5-amd64.iso
 - Archive.org: https://archive.org/details/shadowfetch-linux-2-1-5 (ISO, `SHA256SUMS`, `.asc`, torrent)
 
 **Guides:** [Install](https://www.shadowfetchlinux.org/install) · [Verify](https://www.shadowfetchlinux.org/verify) · [Security model](https://www.shadowfetchlinux.org/security) · [Known issues](https://www.shadowfetchlinux.org/known-issues)
@@ -185,13 +192,14 @@ See [`SECURITY.md`](SECURITY.md), the [security model](https://www.shadowfetchli
 
 ## Support & contributing
 
-- **GitHub Issues** — bugs, installation reports, hardware notes, and patches: https://github.com/ShadowfetchLinux/shadowfetch-linux/issues
+- **GitHub Issues** — bugs, installation reports, hardware notes, and patches: https://github.com/ShadowfetchLinux/shadowfetch-linux/issues (use the Bug report or Hardware report form)
+- **Contributing** — [`CONTRIBUTING.md`](CONTRIBUTING.md). Run `make source-gate` before opening a pull request.
 
 A good **bug report** includes: exact ISO filename and whether the checksum matched; UEFI vs legacy BIOS and Secure Boot state; CPU/GPU/RAM/disk layout/Wi-Fi chipset; for installer failures, where Calamares stopped and whether the live session worked; and redacted `shadowfetch-health --json` output.
 
 A good **hardware report** includes: computer model + firmware/boot mode; CPU/GPU/RAM/storage/Wi-Fi/Bluetooth; whether the live session booted; and whether install, first login, updates, local-AI setup, audio, Wi-Fi, Bluetooth, suspend/resume and GPU acceleration worked — plus anything you had to change by hand.
 
-Pull requests to the build scripts, packages, docs and Worker are welcome. Run `make source-gate` before submitting. By contributing you agree your changes ship under the project's licenses (below).
+Pull requests to the build scripts, packages, docs and Worker are welcome. By contributing you agree your changes ship under the project's licenses (below).
 
 ---
 
@@ -207,5 +215,6 @@ Shadowfetch Linux is an **aggregate**: the ISO bundles many upstream Debian pack
 ## Release notes & links
 
 - Current: [`docs/RELEASE-2.1.5.md`](docs/RELEASE-2.1.5.md) · previous: [`docs/RELEASE-2.1.4.md`](docs/RELEASE-2.1.4.md)
+- GitHub tag notes (paste template): [`docs/GITHUB-RELEASE.md`](docs/GITHUB-RELEASE.md)
 - [Download](https://www.shadowfetchlinux.org/download) · [Verify](https://www.shadowfetchlinux.org/verify) · [Install](https://www.shadowfetchlinux.org/install) · [Security](https://www.shadowfetchlinux.org/security) · [Known issues](https://www.shadowfetchlinux.org/known-issues) · [Docs](https://www.shadowfetchlinux.org/docs)
 - Changelog / release feed: https://www.shadowfetchlinux.org/releases.json