Fix README

Signed-off-by: nopeitsnothing <no@anonymousplanet.org>

.github/workflows/build-pdf.yml

@@ -1,4 +1,4 @@
-name: 🚀 Build guide PDF
+name: 📖 Build PDF
 
 on:
   workflow_dispatch:
@@ -18,38 +18,120 @@ on:
       - ".github/workflows/build-pdf.yml"
 
 permissions:
-  contents: read
+  contents: write
+  id-token: write
 
 jobs:
   pdf:
-    name: MkDocs + print to PDF
+    name: PDF build and sign
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - name: 🛠️ Checkout
         uses: actions/checkout@v4
 
-      - name: Set up Python
+      - name: 🐍 Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
-      - name: Install MkDocs Material
+      - name: 📦 Install MkDocs Material
         run: pip install mkdocs-material
 
-      - name: Install Chromium
+      - name: 🌐 Install Chromium
         run: |
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends chromium
 
-      - name: Build PDF
+      - name: 🔑 Install GPG tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install gnupg
+
+      - name: 🖨️ Build PDF
         env:
           CI: true
-        run: python scripts/build_guide_pdf.py
+        run: python scripts/build_guide_pdf.py --both
 
-      - name: Upload PDF artifact
+      - name: 🔢 Generate SHA256 hashes for root directory
+        run: |
+          cd ${{ github.workspace }}
+          sha256sum export/thgtoa.pdf > sha256sum-light.txt
+          sha256sum export/thgtoa-dark.pdf >> sha256sum-light.txt
+
+          # Create separate hash files for each PDF
+          sha256sum export/thgtoa.pdf > thgtoa.pdf.sha256
+          sha256sum export/thgtoa-dark.pdf > thgtoa-dark.pdf.sha256
+
+      - name: 🔒 Sign PDFs with GPG key
+        env:
+          GPG_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+        run: |
+          cd ${{ github.workspace }}
+
+          # Import GPG key
+          echo "$GPG_KEY" | gpg --batch --import 2>/dev/null || true
+
+          # Sign the PDFs (detach signature)
+          gpg --batch --yes --armor --detach-sign --output export/thgtoa.pdf.sig export/thgtoa.pdf
+          gpg --batch --yes --armor --detach-sign --output export/thgtoa-dark.pdf.sig export/thgtoa-dark.pdf
+
+          # Also sign the hash files
+          gpg --batch --yes --armor --detach-sign --output sha256sum-light.txt.sig sha256sum-light.txt
+
+  upload:
+    name: Upload artifacts
+    runs-on: ubuntu-latest
+    needs: pdf
+    steps:
+      - name: 📤 Upload PDF artifact (Light Mode)
         uses: actions/upload-artifact@v4
         with:
-          name: guide-pdf
+          name: light-pdf-files
-          path: export/guide.pdf
+          path: |
+            export/thgtoa.pdf
+            export/thgtoa.pdf.sig
+            thgtoa.pdf.sha256
+          archive: false
           if-no-files-found: error
           retention-days: 90
+
+      - name: 📤 Upload PDF artifact (Dark Mode)
+        uses: actions/upload-artifact@v4
+        with:
+          name: dark-pdf-files
+          path: |
+            export/thgtoa-dark.pdf
+            export/thgtoa-dark.pdf.sig
+            thgtoa-dark.pdf.sha256
+          archive: false
+          if-no-files-found: error
+          retention-days: 90
+
+      - name: 📤 Upload combined hash file to root
+        uses: actions/upload-artifact@v4
+        with:
+          name: hash-files
+          path: |
+            sha256sum-light.txt
+          archive: false
+          if-no-files-found: error
+          retention-days: 90
+
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    needs: pdf
+    steps:
+      - name: 🚀 Create Release (if tag exists)
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            export/thgtoa.pdf
+            export/thgtoa-dark.pdf
+            export/thgtoa.pdf.sig
+            export/thgtoa-dark.pdf.sig
+            sha256sum-light.txt
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/vt-scan.yml

@@ -0,0 +1,77 @@
+name: '🦠 VirusTotal Scan'
+
+on:
+    workflow_dispatch:
+    push:
+      branches:
+        - 'main'
+      tags:
+        - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: '📦 Checkout'
+        uses: actions/checkout@v6
+
+      - name: '🔍 Download PDF artifacts from build workflow'
+        uses: actions/download-artifact@v7
+        with:
+          pattern: light-pdf-files,dark-pdf-files
+          path: pdfs
+          merge-multiple: true
+
+      - name: '🦠 Scan PDF files using VT'
+        uses: crazy-max/ghaction-virustotal@v5
+        with:
+          vt_api_key: ${{ secrets.VT_API_KEY }}
+          update_release_body: false  # We'll handle this manually in the next step
+          files: |
+            ./pdfs/thgtoa.pdf
+            ./pdfs/thgtoa-dark.pdf
+
+      - name: '📊 Extract VT scan results'
+        id: vt-scan
+        run: |
+          echo "scan completed" >> $GITHUB_OUTPUT
+
+      - name: '🔗 Generate VT report links'
+        run: |
+          # Create a markdown file with VT scan results and links
+          cat > vt-results.md << EOF
+          ## VirusTotal Scan Results
+
+          **Scan Date:** $(date -u +"%Y-%m-%d %H:%M UTC")
+
+          ### thgtoa.pdf (Light Mode)
+          - **VT Report:** https://www.virustotal.com/gui/file/$(sha256sum pdfs/thgtoa.pdf | cut -d' ' -f1)
+
+          ### thgtoa-dark.pdf (Dark Mode)
+          - **VT Report:** https://www.virustotal.com/gui/file/$(sha256sum pdfs/thgtoa-dark.pdf | cut -d' ' -f1)
+
+          ---
+          *Scan performed automatically by GitHub Actions*
+          EOF
+
+      - name: '📝 Update release with VT results (if tag exists)'
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          # Get the latest release notes
+          RELEASE_NOTES=$(gh release view ${{ github.ref_name }} --json body --jq .body 2>/dev/null || echo "")
+
+          # Append VT results to release notes
+          if [ -n "$RELEASE_NOTES" ]; then
+            echo "" >> vt-results.md
+            echo "---" >> vt-results.md
+            echo "### Previous Release Notes" >> vt-results.md
+            echo "$RELEASE_NOTES" >> vt-results.md
+          fi
+
+          # Update the release with VT results
+          gh release edit ${{ github.ref_name }} --notes-file vt-results.md

.gitignore

@@ -19,4 +19,9 @@ ENV/
 site/
 _site/
 _site_test/
-export/
+build/
+
+# Export directory - but track hash files and signatures
+export/thgtoa.pdf.sha256
+export/thgtoa-dark.pdf.sha256
+*.sig

CHANGELOG.md

@@ -7,11 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add ways to verify the files
+
+### Changed
+
+- Refactored GitHub Actions workflow **Build PDF** (`scripts\build_guide_pdf.py`): now builds both light and dark mode PDFs (`export/thgtoa.pdf` and `export/thgtoa-dark.pdf` respectively).
+- Restored previous VT scans workflow **VirusTotal Scan** (`.github/workflows/vt-scan.yml`): submit files to VT for malware scanning. Links will be published on the site.
+
+## Fixed
+
+- `docs/about/index.md`: replace broken reference-style internal links
+- `docs/guide/index.md`: Appendix A6: comment out deprecated ODT information because we don't and probably won't use it in the future
+
+### Feature
+
+- Updated `scripts/build_guide_pdf.py` to use `--print-to-pdf` instead of `--save-as` for PDF generation, and added a new `--dark-mode` flag to generate dark mode PDFs. The script now supports generating both light and dark mode PDFs with a single command invocation by using the `--both` flag. This change improves the PDF generation process and provides better support for dark mode users. Save your eyes - you only get one pair.
+
 ## [1.2.1] - 2026-04-11
 
 ### Added
 
-- GitHub Actions workflow **Build guide PDF** (`.github/workflows/build-pdf.yml`): installs Chromium on `ubuntu-latest`, runs `scripts/build_guide_pdf.py`, uploads `export/guide.pdf` as the `guide-pdf` artifact. Runs on `workflow_dispatch`, on pushes to `main` that touch docs or build inputs, and on matching pull requests.
+- GitHub Actions workflow **Build PDF** (`.github/workflows/build-pdf.yml`): installs Chromium on `ubuntu-latest`, runs `scripts/build_guide_pdf.py`, uploads `export/guide.pdf` as the `guide-pdf` artifact. Runs on `workflow_dispatch`, on pushes to `main` that touch docs or build inputs, and on matching pull requests.
 
 - `scripts/build_guide_pdf.py` to build the MkDocs site and render the guide to a single PDF (`export/guide.pdf` by default) using a Chromium-based browser (Chrome or Edge) headless print-to-PDF.
 - `docs/stylesheets/extra.css` and `extra_css` in `mkdocs.yml` for shared site styling.
@@ -23,7 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Guide landing layout: wrap the opening block in `docs/guide/index.md` with a `guide-intro-lead` container so the logo and first sections share one layout context for web and print.
 - `.gitignore` to exclude local build outputs `export/`, `site/`, and `_site_test/`.
 - `scripts/build_guide_pdf.py`: when the `CI` environment variable is set, pass Chromium flags (`--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`) so headless print works on typical CI images.
-- `README.md`: note the **Build guide PDF** GitHub Actions workflow and the `guide-pdf` artifact.
+- `README.md`: note the **Build PDF** GitHub Actions workflow and the `guide-pdf` artifact.
 
 ### Fixed
 

README.md

@@ -12,27 +12,3 @@ This guide is an open-source non-profit initiative, [licensed](LICENSE.html) und
 
 - **In your browser:** [Hitchhiker's Guide](https://www.anonymousplanet.org/guide/) (hosted site). After a local build you can also open `site/guide/index.html` directly.
 - **Local HTML preview:** from the repository root, with Python 3 and [MkDocs Material](https://squidfunk.github.io/mkdocs-material/getting-started/) installed (`pip install mkdocs-material`), run `mkdocs serve` and open the URL printed in the terminal (for example `http://127.0.0.1:8000`).
-- **PDF (local build):** from the repository root, using the same environment, run:
-
-  ```bash
-  python scripts/build_guide_pdf.py
-  ```
-
-  This runs `mkdocs build` (output defaults to `./site`), then uses **Google Chrome** or **Microsoft Edge** in headless mode to print `site/guide/index.html` to **`export/guide.pdf`** (images and styling preserved). If the site is already built: `python scripts/build_guide_pdf.py --skip-mkdocs`. Other options: `--site-dir`, `--pdf`, and `python scripts/build_guide_pdf.py --help`.
-
-  On **GitHub Actions**, the [Build guide PDF](https://github.com/Anon-Planet/thgtoa/actions/workflows/build-pdf.yml) workflow does the same using Chromium on Ubuntu when you push to `main` or open a pull request that touches the guide or build inputs; download the **`guide-pdf`** artifact from a successful run. You can also run it manually (**Actions** → **Build guide PDF** → **Run workflow**).
-- **OpenDocument (ODT):** not produced by this repository (previous hosted export removed).
-- **Raw Markdown (very large):** [docs/guide/index.md on GitHub](https://raw.githubusercontent.com/Anon-Planet/thgtoa/refs/heads/main/docs/guide/index.md)
-
-**Mirrors:**
-- <del>Hidden service: <http://thgtoa3jzy3doku7hkna32htpghjijefscwvh4dyjgfydbbjkeiohgid.onion/></del> **Host down**
-
-Feel free to submit issues using Github Issues with the repository link above. Criticism, opinions, and ideas are welcome!
-
-**Follow or contact us on:**
-
-Discussion Channels:
-- Matrix room: <https://matrix.to/#/#anonymity:anonymousplanet.net>
-- Matrix space: <https://matrix.to/#/#psa:anonymousplanet.net>
-
-Have a good read and feel free to share and/or recommend it!

docs/about/index.md

@@ -15,7 +15,7 @@ schema:
 ---
 ![Anonymous Planet logo](../media/profile.png){ align=right }
 
-**Anonymous Planet** are the maintainers of the [_Hitchhiker's Guide_](https://anonymousplanet.org/guide.html) and the [_PSA Community_](https://psa.anonymousplanet.org). It is responsible for maintaining the projects and code repositories.
+**Anonymous Planet** are the maintainers of the [_Hitchhiker's Guide_](../guide/index.md) and the [_PSA Community_](https://psa.anonymousplanet.org). It is responsible for maintaining the projects and code repositories. This project is part of our ongoing efforts to provide open-source tools and resources for the community, with regular updates and improvements added to the changelog.
 
 The purpose: providing an introduction to various online tracking techniques, online ID verification techniques, and detailed guidance to creating and maintaining (truly) anonymous online identities. It is written with the hopes that good people (e.g., activists, journalists, scientists, lawyers, whistle-blowers, etc.) will be able to fight oppression, censorship and harassment! The website and projects are free (as in freedom) and not affiliated with any donor or projects discussed.
 

docs/guide/dev-workflow.md

@@ -0,0 +1,193 @@
+# Development
+
+## Overview
+
+This repository now includes an automated workflow that handles PDF generation, verification, and distribution with the following features:
+
+??? Note "How the pipeline works"
+
+    1. **Automatic PDF Generation** - Builds both light and dark mode PDFs from MkDocs source
+    2. **SHA256 Hash Generation** - Creates hash files for integrity verification
+    3. **GPG Signature Signing** - Signs all PDFs and hash files with repository GPG key
+    4. **VirusTotal Scanning** - Automatically scans PDFs and updates release notes
+    5. **Release Automation** - Packages everything into GitHub releases
+
+## Workflow Architecture
+
+### 1. Build PDF Workflow (`build-pdf.yml`)
+
+**Trigger:** Push to main, pull requests, or manual dispatch
+
+??? Note "Steps"
+
+    - Checkout repository
+    - Set up Python 3.13 and MkDocs Material
+    - Install Chromium browser
+    - Generate both light and dark mode PDFs
+    - Create SHA256 hash files
+    - Sign all files with GPG
+    - Upload artifacts to GitHub Actions
+    - Publish release
+
+### 2. VirusTotal Scan Workflow (`vt-scan.yml`)
+
+**Trigger:** Push to main, tags, or manual dispatch (runs after build-pdf)
+
+??? Note "Steps"
+
+    - Download PDF artifacts from build workflow
+    - Scan both PDFs with VirusTotal API
+    - Extract scan results and generate report links
+    - Update release notes with VT scan status and URLs
+
+## File Structure
+
+After a successful build, the repository will contain:
+
+```
+.../
+├── export/
+│   ├── thgtoa.pdf              # Light mode PDF
+│   ├── thgtoa-dark.pdf         # Dark mode PDF
+│   ├── thgtoa.pdf.sig          # GPG signature (light)
+│   └── thgtoa-dark.pdf.sig     # GPG signature (dark)
+├── thgtoa.pdf.sha256           # Hash file (light)
+├── thgtoa-dark.pdf.sha256      # Hash file (dark)
+├── sha256sum-light.txt         # Combined hash file
+└── scripts/
+    ├── build_guide_pdf.py      # PDF generation script
+    └── verify_pdf.py           # Verification utility
+```
+
+## Security Features
+
+### 1. SHA256 Hash Verification
+
+**Purpose:** Ensure file integrity during download/transit
+
+**How it works:**
+- Each PDF gets a unique SHA256 hash calculated at build time
+- Hash stored in `.sha256` files alongside the PDFs
+- Combined `sha256sum-light.txt` for batch verification
+
+**Verification command:**
+```bash
+sha256sum -c sha256sum-light.txt
+```
+
+### 2. GPG Signature Verification
+
+**Purpose:** Verify authenticity and prevent tampering
+
+??? Note "How it works"
+
+    - Detached signatures created for each PDF and hash file
+    - Public keys available in `/pgp/` directory
+
+**Verification command:**
+```bash
+gpg --import pgp/anonymousplanet-master.asc
+gpg --verify export/thgtoa.pdf.sig export/thgtoa.pdf
+```
+
+### 3. VirusTotal Integration
+
+**Purpose:** Malware detection and security scanning
+
+??? Note "How it works"
+
+    - Automatic scan of all generated PDFs
+    - Results published in release notes with direct links
+    - Provides third-party validation of file safety
+
+## Usage Examples
+
+### Local Development
+
+```bash
+# Build PDFs locally
+python scripts/build_guide_pdf.py --both
+
+# Verify hashes
+python scripts/verify_pdf.py --hashes
+
+# Verify signatures (requires GPG installed)
+python scripts/verify_pdf.py --signatures
+
+# Full verification with VirusTotal check
+export VT_API_KEY=your_api_key
+python scripts/verify_pdf.py --all
+```
+
+### CI/CD Verification
+
+The workflows automatically verify everything during the build process. To manually trigger:
+
+1. Go to Actions tab
+2. Select "Build guide PDF" or "VirusTotal Scan"
+3. Click "Run workflow"
+4. Download artifacts from successful run
+
+## Release Process
+
+When you create a tag (e.g., `v1.0.0`):
+
+1. Push the tag: `git push origin v1.0.0`
+2. Build PDF workflow triggers automatically
+3. VirusTotal scan workflow runs after build completes
+4. Both workflows update/create GitHub release with:
+   - Light and dark mode PDFs
+   - GPG signatures for all files
+   - Hash files for verification
+   - Release notes with VT scan results
+
+## Troubleshooting
+
+### Common Issues
+
+**GPG signing fails:**
+- Check that `GPG_PRIVATE_KEY` is in ASCII armor format
+- Verify passphrase is correct
+- Ensure key has signing capability
+
+**Hash mismatch after download:**
+- Re-download the file (corruption during transfer)
+- Verify you're using the correct hash file
+- Check disk integrity
+
+**VirusTotal scan fails:**
+- Verify `VT_API_KEY` is set correctly
+- Check API quota limits (free tier: 4 requests/minute)
+- Ensure PDF files exist before scanning
+
+### Debug Mode
+
+Enable verbose output by adding to workflow:
+```yaml
+- name: Debug
+  run: |
+    echo "Current directory:" && pwd
+    echo "Files in export:" && ls -la export/
+    echo "Hash file contents:" && cat sha256sum-light.txt
+```
+
+## Best Practices
+
+1. **Always verify signatures** before opening PDFs from untrusted sources
+2. **Check VirusTotal results** for any suspicious detections
+3. **Keep GPG keys secure** - never commit private keys to repository
+4. **Monitor API usage** for VirusTotal to avoid rate limiting
+5. **Test locally** before pushing tags to production
+
+## Future Enhancements
+
+Potential improvements:
+- Multi-signature support (multiple maintainers)
+- Automated changelog generation with hashes
+- Cross-platform signature verification scripts
+- Integration with additional malware scanners
+- Automatic mirror updates with verified files
+
+---
+
+*This workflow is designed for security-conscious users who need to verify the authenticity and integrity of downloaded documents.*

docs/guide/index.md

@@ -11344,7 +11344,7 @@ If you want to compare an older version of the PDF with a newer version, conside
 
 - <https://draftable.com/compare>
 
-If you want to compare the older version of the ODT format with a newer version, use the LibreWriter compare features as explained here: <https://help.libreoffice.org/7.1/en-US/text/shared/guide/redlining_doccompare.html> <sup>[[Archive.org]](https://web.archive.org/web/https://help.libreoffice.org/7.1/en-US/text/shared/guide/redlining_doccompare.html)</sup>
+<!-- If you want to compare the older version of the ODT format with a newer version, use the LibreWriter compare features as explained here: <https://help.libreoffice.org/7.1/en-US/text/shared/guide/redlining_doccompare.html> <sup>[[Archive.org]](https://web.archive.org/web/https://help.libreoffice.org/7.1/en-US/text/shared/guide/redlining_doccompare.html)</sup> -->
 
 # Appendix A7: Crypto Swapping Services without Registration and KYC
 

docs/index.md

@@ -13,12 +13,17 @@ schema:
     - https://opencollective.com/anonymousplanetorg
     - https://mastodon.social/@anonymousplanet
 ---
+
+# **Hello, and welcome to the Hitchhiker's Guide.**
+
+**9FA5 436D 0EE3 6098 5157  3825 17EC A05F 768D EDF6**
+
+This is the master signing key fingerprint for Anonymous Planet.
+    You'll use it to [**verify the checksum** and **GPG signature** of all files for authenticity.](verify/index.md)
+    Please share this project if you enjoy it and you think it might be useful to others.
+
 ![Anonymous Planet logo](media/profile.png){ align=right }
 
-**Welcome to the Hitchhiker's Guide.**
-
-Please share this project if you enjoy it and you think it might be useful to others.
-
 Anonymous Planet is a collective of volunteers and contributors. No one person is considered more valuable than another, and no one person should be viewed as having "more impact" on Anonymous Planet.
 
 ??? person "Das Kolburn"

docs/mirrors/index.md

@@ -27,9 +27,9 @@ schema:
 
 !!! Note "PDF export (single file)"
 
-    The guide is also available as a **PDF** (images and layout preserved). It is built automatically in GitHub Actions: open [**Build guide PDF**](https://github.com/Anon-Planet/thgtoa/actions/workflows/build-pdf.yml) on the [**thgtoa** source repository](https://github.com/Anon-Planet/thgtoa), pick a successful run, and download the **`guide-pdf`** artifact. You can start a fresh build anytime (**Actions** → **Build guide PDF** → **Run workflow**).
+    The guide is also available as a **PDF** (images and layout preserved). It is built automatically in GitHub Actions: open [**Build guide PDF**](https://github.com/Anon-Planet/thgtoa/actions/workflows/build-pdf.yml) on the [**source repository**](https://github.com/Anon-Planet/thgtoa), pick a successful run, and download the **`thgtoa`** and **`thgtoa-dark`** artifacts. You can start a fresh build anytime (**Actions** → **Build guide PDF** → **Run workflow**).
 
-    To produce the same file locally, clone the repository and run `python scripts/build_guide_pdf.py` (Python, [MkDocs Material](https://squidfunk.github.io/mkdocs-material/getting-started/), and **Google Chrome** or **Microsoft Edge** required). More detail is in the [repository README](https://github.com/Anon-Planet/thgtoa#ways-to-read-or-export-the-guide).
+    To produce the same file locally, clone the repository and run `python3 scripts/build_guide_pdf.py --both` (Python, [MkDocs Material](https://squidfunk.github.io/mkdocs-material/getting-started/), and **Google Chrome** or **Microsoft Edge** required). More detail is in the [repository README](https://github.com/Anon-Planet/thgtoa#ways-to-read-or-export-the-guide).
 
 !!! Note "Our official git mirrors"
 

docs/stylesheets/dark-extra.css

@@ -0,0 +1,130 @@
+/* Generate dark mode PDF of the HTML at guide/index.html */
+
+/*
+  DARK_MODE_PDF.CSS
+  Use this stylesheet when generating a PDF from HTML.
+*/
+
+:root {
+  /* Color Palette */
+  --bg-color: #121212;           /* Deep dark grey (easier on eyes than pure black) */
+  --text-primary: #e0e0e0;       /* Off-white for readability */
+  --text-secondary: #a0a0a0;     /* Grey for captions/metadata */
+  --accent-color: #bb86fc;       /* Light purple accent (optional) */
+  --border-color: #333333;       /* Subtle borders */
+
+  /* Fonts - System fonts ensure best rendering across PDF engines */
+  --font-main: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+}
+
+/* --- RESET & BASE STYLES --- */
+* {
+  box-sizing: border-box;
+}
+
+body {
+  background-color: var(--bg-color);
+  color: var(--text-primary);
+  font-family: var(--font-main);
+  line-height: 1.6;
+  margin: 0;
+  padding: 0;
+}
+
+/* --- TYPOGRAPHY & HEADINGS --- */
+h1, h2, h3, h4, h5, h6 {
+  color: var(--text-primary);
+  font-weight: 700;
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+}
+
+p {
+  margin-bottom: 1rem;
+  color: var(--text-secondary); /* Slightly dimmer text for body copy */
+}
+
+a {
+  color: var(--accent-color);
+  text-decoration: underline;
+}
+
+/* --- CONTAINER & LAYOUT --- */
+.container {
+  max-width: 800px;
+  margin: 40px auto;
+  padding: 20px;
+}
+
+/* Cards / Sections with dark backgrounds */
+.card {
+  background-color: #1e1e1e;
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  padding: 20px;
+  margin-bottom: 20px;
+}
+
+/* --- TABLES (Common in PDFs) --- */
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 20px 0;
+  color: var(--text-primary);
+}
+
+th, td {
+  padding: 12px;
+  text-align: left;
+  border-bottom: 1px solid var(--border-color);
+}
+
+th {
+  background-color: #2c2c2c;
+  font-weight: bold;
+}
+
+tr:last-child td {
+  border-bottom: none;
+}
+
+/* --- IMAGES --- */
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  margin: 20px 0;
+  /* This ensures high contrast images don't get washed out */
+  filter: brightness(1.1);
+}
+
+/* --- CRITICAL FOR PDF GENERATORS --- */
+/* Forces the browser/PDF engine to print background colors and graphics */
+@media print {
+  @page {
+    size: A4; /* Change to 'Letter' if preferred */
+    margin: 20mm;
+  }
+
+  body {
+    background-color: var(--bg-color) !important;
+    color: var(--text-primary) !important;
+  }
+
+  .card, table th {
+    -webkit-print-color-adjust: exact !important; /* Chrome/Safari */
+    print-color-adjust: exact !important;          /* Firefox/Standard */
+    background-color: #1e1e1e !important;
+    color: var(--text-primary) !important;
+  }
+
+  /* Prevent page breaks in the middle of a sentence or card if possible */
+  .card {
+    break-inside: avoid;
+  }
+
+  /* Hide elements you don't want in PDF (like navigation bars) */
+  nav, footer, button {
+    display: none !important;
+  }
+}

docs/verify/index.md

@@ -0,0 +1,123 @@
+---
+title: "Verify"
+description: How to verify the authenticity of our files and check virus scans
+---
+
+# PDF Verification Guide
+
+## Files Provided
+
+For each PDF release, you'll receive:
+
+- **PDF file** (`thgtoa.pdf` or `thgtoa-dark.pdf`) - The actual document
+- **Signature file** (`.sig`) - GPG detached signature for authenticity verification
+- **Hash file** (`.sha256`) - SHA256 checksum for integrity verification
+
+## Quick Verification
+
+### Using Python Script (Recommended)
+
+```bash
+# Verify everything (hashes, signatures, and optionally VirusTotal)
+python scripts/verify_pdf.py --all
+
+# Only verify hashes
+python scripts/verify_pdf.py --hashes
+
+# Only verify GPG signatures
+python scripts/verify_pdf.py --signatures
+
+# Check VirusTotal scan status (requires VT_API_KEY environment variable)
+python scripts/verify_pdf.py --vt
+```
+
+### Manual Verification
+
+#### 1. Verify SHA256 Hash
+
+**Linux/macOS:**
+```bash
+cd /path/to/repo
+sha256sum -c sha256sum-light.txt
+```
+
+**Windows (PowerShell):**
+```powershell
+Get-FileHash -Algorithm SHA256 export\thgtoa.pdf | Select-Object Hash
+# Compare with the hash in thgtoa.pdf.sha256
+```
+
+#### 2. Verify GPG Signature
+
+First, import the public key:
+```bash
+gpg --import pgp/anonymousplanet-master.asc
+```
+
+Then verify the signature:
+```bash
+gpg --verify export/thgtoa.pdf.sig export/thgtoa.pdf
+gpg --verify export/thgtoa-dark.pdf.sig export/thgtoa-dark.pdf
+```
+
+Expected output for successful verification:
+```
+gpg: Signature made [date]
+gpg:                using RSA key [key-id]
+gpg: Good signature from "[owner]"
+```
+
+#### 3. Check VirusTotal Status
+
+Visit the VirusTotal report links (automatically generated in release notes):
+- Light mode: `https://www.virustotal.com/gui/file/[hash]`
+- Dark mode: `https://www.virustotal.com/gui/file/[hash]`
+
+Or use the Python script with API key:
+```bash
+export VT_API_KEY=your_vt_api_key
+python scripts/verify_pdf.py --vt
+```
+
+## Automated Verification in CI/CD
+
+The GitHub Actions workflows automatically:
+
+1. **Build PDFs** from MkDocs source
+2. **Generate SHA256 hashes** and save to root directory
+3. **Sign files with GPG** using the repository's private key
+4. **Scan with VirusTotal** and update release notes
+5. **Create releases** with all verification artifacts
+
+## Security Best Practices
+
+1. **Always verify signatures** before opening PDFs from untrusted sources
+2. **Check hashes** to ensure files weren't corrupted during download
+3. **Review VirusTotal results** for any suspicious detections
+4. **Import keys securely** - verify key fingerprints with the project maintainers
+5. **Keep verification scripts updated** to match current security standards
+
+## Troubleshooting
+
+### "Good signature" but wrong owner?
+- Ensure you imported the correct public key
+- Check the key fingerprint matches the official one from the repository
+
+### Hash mismatch?
+- Re-download the file (corruption during transfer)
+- Verify you're checking against the correct hash file
+- Check for disk errors on your system
+
+### GPG not found?
+- Install GPG: `sudo apt install gnupg` (Debian/Ubuntu) or `brew install gnupg` (macOS)
+- On Windows, use [Gpg4win](https://www.gpg4win.org/)
+
+## Key Information
+
+**Signing Key:** Anonymous Planet Master Key
+**Key ID:** See `pgp/anonymousplanet-master.asc` for details
+**Fingerprint:** Verify from the repository's official documentation
+
+---
+
+*For questions or issues with verification, please open an issue on GitHub.*

mkdocs.yml

@@ -121,5 +121,18 @@ markdown_extensions:
       permalink: true
       toc_depth: 3
 
+nav:
+  - Home: index.md
+  - About: about/index.md
+  - Verify: verify/index.md
+  - Guide:
+    - guide/index.md
+    - Workflow Documentation: guide/dev-workflow.md
+  - Code: code/index.md
+  - Contribute: contribute/index.md
+  - Constitution: constitution/index.md
+  - Mirrors: mirrors/index.md
+  - Twitter: twitter/index.md
+
 copyright: |
-  &copy; 2023-2025 <a href="https://anonymousplanet.org/"  target="_blank" rel="noopener">Anonymous Planet</a>
+  &copy; 2023-2026 <a href="https://anonymousplanet.org/"  target="_blank" rel="noopener">Anonymous Planet</a>

scripts/build_guide_pdf.py

@@ -1,161 +1,247 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
-"""Build the MkDocs site, then render docs/guide/ to a single PDF via a Chromium-based browser.
+"""Experimental dark mode support.
-
+
-Uses headless Chrome/Edge print-to-PDF (embeds images). WeasyPrint-based mkdocs-with-pdf is
+This script builds both light and dark mode MkDocs site, then renders docs/guide/ to single PDFs via Chromium.
-omitted here because it needs GTK/Pango (awkward on Windows).
+
-
+Usage:
-Usage (from repo root):
+  python scripts/build_guide_pdf.py                    # Generate light mode PDF only
-  python scripts/build_guide_pdf.py
+  python scripts/build_guide_pdf.py --dark-mode        # Generate dark mode PDF only
-  python scripts/build_guide_pdf.py --site-dir build/html --pdf export/guide.pdf
+  python scripts/build_guide_pdf.py --both             # Generate both light and dark mode PDFs
-"""
+
-
+Examples:
-from __future__ import annotations
+  python scripts/build_guide_pdf.py --site-dir build/html --pdf-light export/thgtoa.pdf
-
+  python scripts/build_guide_pdf.py --dark-mode --pdf-dark export/thgtoa-dark.pdf
-import argparse
+"""
-import os
+
-import shutil
+from __future__ import annotations
-import subprocess
+
-import sys
+import argparse
-import time
+import os
-from pathlib import Path
+import shutil
-
+import subprocess
-
+import sys
-def repo_root() -> Path:
+import time
-    return Path(__file__).resolve().parent.parent
+from pathlib import Path
-
+
-
+
-def find_chromium_executable() -> Path | None:
+def repo_root() -> Path:
-    if sys.platform == "win32":
+    return Path(__file__).resolve().parent.parent
-        paths = [
+
-            Path(os.environ.get("PROGRAMFILES(X86)", "")) / "Microsoft/Edge/Application/msedge.exe",
+
-            Path(os.environ.get("LOCALAPPDATA", "")) / "Microsoft/Edge/Application/msedge.exe",
+def find_chromium_executable() -> Path | None:
-            Path(os.environ.get("PROGRAMFILES", "")) / "Google/Chrome/Application/chrome.exe",
+    if sys.platform == "win32":
-            Path(os.environ.get("PROGRAMFILES(X86)", "")) / "Google/Chrome/Application/chrome.exe",
+        paths = [
-            Path(os.environ.get("LOCALAPPDATA", "")) / "Google/Chrome/Application/chrome.exe",
+            Path(os.environ.get("PROGRAMFILES(X86)", "")) / "Microsoft/Edge/Application/msedge.exe",
-        ]
+            Path(os.environ.get("LOCALAPPDATA", "")) / "Microsoft/Edge/Application/msedge.exe",
-        for p in paths:
+            Path(os.environ.get("PROGRAMFILES", "")) / "Google/Chrome/Application/chrome.exe",
-            if p.is_file():
+            Path(os.environ.get("PROGRAMFILES(X86)", "")) / "Google/Chrome/Application/chrome.exe",
-                return p
+            Path(os.environ.get("LOCALAPPDATA", "")) / "Google/Chrome/Application/chrome.exe",
-        for name in ("chrome", "msedge"):
+        ]
-            w = shutil.which(name)
+        for p in paths:
-            if w:
+            if p.is_file():
-                return Path(w)
+                return p
-    elif sys.platform == "darwin":
+        for name in ("chrome", "msedge"):
-        for p in (
+            w = shutil.which(name)
-            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            if w:
-            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+                return Path(w)
-            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    elif sys.platform == "darwin":
-        ):
+        for p in (
-            if os.path.isfile(p):
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-                return Path(p)
+            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-    for name in ("google-chrome-stable", "google-chrome", "chromium-browser", "chromium", "chrome"):
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
-        w = shutil.which(name)
+        ):
-        if w:
+            if os.path.isfile(p):
-            return Path(w)
+                return Path(p)
-    return None
+    for name in ("google-chrome-stable", "google-chrome", "chromium-browser", "chromium", "chrome"):
-
+        w = shutil.which(name)
-
+        if w:
-def run_mkdocs(site_dir: Path) -> None:
+            return Path(w)
-    site_dir.mkdir(parents=True, exist_ok=True)
+    return None
-    subprocess.run(
+
-        [sys.executable, "-m", "mkdocs", "build", "-d", str(site_dir)],
+
-        cwd=repo_root(),
+def run_mkdocs(site_dir: Path) -> None:
-        check=True,
+    site_dir.mkdir(parents=True, exist_ok=True)
-    )
+    subprocess.run(
-
+        [sys.executable, "-m", "mkdocs", "build", "-d", str(site_dir)],
-
+        cwd=repo_root(),
-def print_to_pdf(browser: Path, html_file: Path, pdf_out: Path) -> Path:
+        check=True,
-    """Write PDF to ``pdf_out``. Uses a temp file first so an open ``guide.pdf`` on Windows
+    )
-    does not block the build: if the final path is locked, writes ``guide-new.pdf`` instead.
+
-    """
+
-    pdf_out.parent.mkdir(parents=True, exist_ok=True)
+def print_to_pdf(browser: Path, html_file: Path, pdf_out: Path, dark_mode: bool = False) -> Path:
-    partial = pdf_out.parent / f".{pdf_out.name}.writing"
+    """Write PDF to ``pdf_out``. Uses a temp file first so an open ``guide.pdf`` on Windows
-    partial.unlink(missing_ok=True)
+    does not block the build: if the final path is locked, writes ``guide-new.pdf`` instead.
-
+
-    uri = html_file.resolve().as_uri()
+    Args:
-    # Chromium headless print; allow time for fonts/images on very large pages.
+        browser: Path to Chromium executable
-    cmd = [str(browser)]
+        html_file: Path to HTML file to convert
-    if os.environ.get("CI"):
+        pdf_out: Output PDF path
-        # GitHub Actions / other CI runners often need these for Chromium to start.
+        dark_mode: If True, use dark mode color scheme via --prefers-color-scheme flag
-        cmd += [
+    """
-            "--no-sandbox",
+    pdf_out.parent.mkdir(parents=True, exist_ok=True)
-            "--disable-setuid-sandbox",
+    partial = pdf_out.parent / f".{pdf_out.name}.writing"
-            "--disable-dev-shm-usage",
+    partial.unlink(missing_ok=True)
-        ]
+
-    cmd += [
+    uri = html_file.resolve().as_uri()
-        "--headless=new",
+
-        "--disable-gpu",
+    # Chromium headless print; allow time for fonts/images on very large pages.
-        "--no-pdf-header-footer",
+    cmd = [str(browser)]
-        f"--print-to-pdf={partial.resolve()}",
+    if os.environ.get("CI"):
-        uri,
+        # GitHub Actions / other CI runners often need these for Chromium to start.
-    ]
+        cmd += [
-    subprocess.run(cmd, check=True, timeout=600)
+            "--no-sandbox",
-    deadline = time.time() + 120
+            "--disable-setuid-sandbox",
-    while time.time() < deadline:
+            "--disable-dev-shm-usage",
-        if partial.exists() and partial.stat().st_size > 0:
+        ]
-            break
+
-        time.sleep(0.25)
+    cmd += [
-    else:
+        "--headless=new",
-        partial.unlink(missing_ok=True)
+        "--disable-gpu",
-        raise RuntimeError(f"PDF was not written to {partial}")
+        "--no-pdf-header-footer",
-
+    ]
-    try:
+
-        if pdf_out.exists():
+    # Add dark mode preference if requested
-            pdf_out.unlink()
+    if dark_mode:
-    except PermissionError:
+        cmd.append("--prefers-color-scheme=dark")
-        fallback = pdf_out.with_name(f"{pdf_out.stem}-new{pdf_out.suffix}")
+
-        fallback.unlink(missing_ok=True)
+    cmd += [
-        partial.replace(fallback)
+        f"--print-to-pdf={partial.resolve()}",
-        return fallback
+        uri,
-
+    ]
-    partial.replace(pdf_out)
+
-    return pdf_out
+    subprocess.run(cmd, check=True, timeout=600)
-
+    deadline = time.time() + 120
-
+    while time.time() < deadline:
-def main() -> int:
+        if partial.exists() and partial.stat().st_size > 0:
-    root = repo_root()
+            break
-    ap = argparse.ArgumentParser(description="Build MkDocs + single-page guide PDF.")
+        time.sleep(0.25)
-    ap.add_argument(
+    else:
-        "--site-dir",
+        partial.unlink(missing_ok=True)
-        type=Path,
+        raise RuntimeError(f"PDF was not written to {partial}")
-        default=root / "site",
+
-        help="MkDocs output directory (default: ./site)",
+    try:
-    )
+        if pdf_out.exists():
-    ap.add_argument(
+            pdf_out.unlink()
-        "--pdf",
+    except PermissionError:
-        type=Path,
+        fallback = pdf_out.with_name(f"{pdf_out.stem}-new{pdf_out.suffix}")
-        default=root / "export" / "guide.pdf",
+        fallback.unlink(missing_ok=True)
-        help="Output PDF path (default: ./export/guide.pdf)",
+        partial.replace(fallback)
-    )
+        return fallback
-    ap.add_argument("--skip-mkdocs", action="store_true", help="Reuse existing site dir; only run print-to-pdf.")
+
-    args = ap.parse_args()
+    partial.replace(pdf_out)
-
+    return pdf_out
-    guide_html = args.site_dir / "guide" / "index.html"
+
-    if not args.skip_mkdocs:
+
-        run_mkdocs(args.site_dir)
+def generate_dark_mode_html(html_file: Path, output_file: Path, dark_css_path: Path) -> None:
-    if not guide_html.is_file():
+    """Create a temporary HTML file with dark mode stylesheet applied.
-        print(f"Missing {guide_html}; run without --skip-mkdocs first.", file=sys.stderr)
+
-        return 1
+    This is used when we need to force dark mode rendering via CSS rather than browser flags.
-
+    """
-    browser = find_chromium_executable()
+    try:
-    if not browser:
+        from bs4 import BeautifulSoup
-        print(
+
-            "No Chromium-based browser found (Chrome, Edge, or Chromium). "
+        # Read the original HTML
-            "Install Google Chrome or Microsoft Edge, or add Chromium to PATH.",
+        html_content = html_file.read_text(encoding='utf-8')
-            file=sys.stderr,
+        soup = BeautifulSoup(html_content, 'html.parser')
-        )
+
-        return 1
+        # Add dark mode stylesheet link if not present
-
+        existing_links = [link.get('href', '') for link in soup.find_all('link', rel='stylesheet')]
-    out = print_to_pdf(browser, guide_html, args.pdf)
+        if not any(dark_css_path.name in link for link in existing_links):
-    size_kb = out.stat().st_size // 1024
+            head = soup.head or soup.new_tag('head')
-    print(f"Wrote {out.resolve()} ({size_kb} KiB)")
+            link_tag = soup.new_tag('link', rel='stylesheet', href=str(dark_css_path))
-    if out.resolve() != args.pdf.resolve():
+            if soup.head:
-        print(
+                soup.head.append(link_tag)
-            f"Note: {args.pdf.name} was in use; close it and rename or replace with the file above.",
+            else:
-            file=sys.stderr,
+                # Create a new head section
-        )
+                new_head = soup.new_tag('head')
-    return 0
+                new_head.append(link_tag)
-
+                soup.insert(0, new_head)
-
+
-if __name__ == "__main__":
+        # Write the modified HTML
-    raise SystemExit(main())
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        output_file.write_text(str(soup), encoding='utf-8')
+    except ImportError:
+        print("BeautifulSoup not available. Skipping CSS injection.")
+
+
+def main() -> int:
+    root = repo_root()
+    ap = argparse.ArgumentParser(description="Build MkDocs + single-page guide PDF (light and/or dark mode).")
+    ap.add_argument(
+        "--site-dir",
+        type=Path,
+        default=root / "build" / "html",
+        help="MkDocs output directory (default: ./build/html)",
+    )
+    ap.add_argument(
+        "--pdf-light",
+        type=Path,
+        default=root / "export" / "thgtoa.pdf",
+        help="Output PDF path for light mode (default: ./export/guide.pdf)",
+    )
+    ap.add_argument(
+        "--pdf-dark",
+        type=Path,
+        default=root / "export" / "thgtoa-dark.pdf",
+        help="Output PDF path for dark mode (default: ./export/guide-dark.pdf)",
+    )
+    ap.add_argument("--skip-mkdocs", action="store_true", help="Reuse existing site dir; only run print-to-pdf.")
+    ap.add_argument("--dark-mode", action="store_true", help="Generate dark mode PDF only")
+    ap.add_argument("--both", action="store_true", help="Generate both light and dark mode PDFs")
+    args = ap.parse_args()
+
+    # Determine which modes to generate
+    if args.dark_mode:
+        modes = ["dark"]
+    elif args.both:
+        modes = ["light", "dark"]
+    else:
+        modes = ["light"]
+
+    guide_html = args.site_dir / "guide" / "index.html"
+
+    if not args.skip_mkdocs or any(mode == "light" for mode in modes):
+        run_mkdocs(args.site_dir)
+
+    if not guide_html.is_file():
+        print(f"Missing {guide_html}; run without --skip-mkdocs first.", file=sys.stderr)
+        return 1
+
+    browser = find_chromium_executable()
+    if not browser:
+        print(
+            "No Chromium-based browser found (Chrome, Edge, or Chromium). "
+            "Install Google Chrome or Microsoft Edge, or add Chromium to PATH.",
+            file=sys.stderr,
+        )
+        return 1
+
+    dark_css_path = root / "docs" / "stylesheets" / "dark-extra.css"
+
+    # Generate light mode PDF (default)
+    if "light" in modes:
+        out_light = print_to_pdf(browser, guide_html, args.pdf_light, dark_mode=False)
+        size_kb = out_light.stat().st_size // 1024
+        print(f"Wrote {out_light.resolve()} ({size_kb} KiB) [Light Mode]")
+        if out_light.resolve() != args.pdf_light.resolve():
+            print(
+                f"Note: {args.pdf_light.name} was in use; close it and rename or replace with the file above.",
+                file=sys.stderr,
+            )
+
+    # Generate dark mode PDF
+    if "dark" in modes:
+        out_dark = print_to_pdf(browser, guide_html, args.pdf_dark, dark_mode=True)
+        size_kb = out_dark.stat().st_size // 1024
+        print(f"Wrote {out_dark.resolve()} ({size_kb} KiB) [Dark Mode]")
+        if out_dark.resolve() != args.pdf_dark.resolve():
+            print(
+                f"Note: {args.pdf_dark.name} was in use; close it and rename or replace with the file above.",
+                file=sys.stderr,
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/setup_workflow.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""Setup helper for PDF workflow configuration.
+
+This script helps you configure the necessary GitHub Secrets for the automated
+PDF build, signing, and VirusTotal scanning workflows.
+
+Usage:
+  python scripts/setup_workflow.py
+
+Requirements:
+  - Python 3.8+
+  - GPG installed (for key export)
+  - Access to GitHub repository settings
+
+What it does:
+  1. Validates your GPG key setup
+  2. Exports the public key for verification
+  3. Provides instructions for adding secrets to GitHub
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def check_gpg_installed() -> bool:
+    """Check if GPG is installed and accessible."""
+    try:
+        result = subprocess.run(
+            ["gpg", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def list_gpg_keys() -> list[dict]:
+    """List all GPG keys in the keyring."""
+    try:
+        result = subprocess.run(
+            ["gpg", "--list-keys", "--with-colons"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        keys = []
+        current_key = {}
+
+        for line in result.stdout.split('\n'):
+            if line.startswith('pub:'):
+                if current_key:
+                    keys.append(current_key)
+                parts = line.split(':')
+                current_key = {
+                    'type': parts[1],
+                    'key_id': parts[4],
+                    'fingerprint': parts[9] if len(parts) > 9 else None,
+                    'created': parts[5],
+                    'expires': parts[6],
+                    'uid': None,
+                }
+            elif line.startswith('uid:'):
+                parts = line.split(':')
+                current_key['uid'] = parts[9] if len(parts) > 9 else None
+
+        if current_key:
+            keys.append(current_key)
+
+        return keys
+
+    except subprocess.CalledProcessError as e:
+        print(f"Error listing GPG keys: {e}")
+        return []
+
+
+def export_public_key(key_id: str, output_file: Path | None = None) -> str | None:
+    """Export a public key in ASCII armor format."""
+    try:
+        result = subprocess.run(
+            ["gpg", "--armor", "--export", key_id],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        if output_file:
+            output_file.write_text(result.stdout)
+            print(f"✓ Public key exported to {output_file}")
+
+        return result.stdout
+
+    except subprocess.CalledProcessError as e:
+        print(f"Error exporting public key: {e}")
+        return None
+
+
+def export_private_key(key_id: str, output_file: Path | None = None) -> str | None:
+    """Export a private key in ASCII armor format (requires passphrase)."""
+    try:
+        # This will prompt for passphrase interactively
+        result = subprocess.run(
+            ["gpg", "--armor", "--export-secret-keys", key_id],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        if output_file:
+            output_file.write_text(result.stdout)
+            print(f"✓ Private key exported to {output_file}")
+
+        return result.stdout
+
+    except subprocess.CalledProcessError as e:
+        print(f"Error exporting private key: {e}")
+        return None
+
+
+def validate_gpg_key(key_id: str) -> bool:
+    """Validate that a GPG key has signing capability."""
+    try:
+        result = subprocess.run(
+            ["gpg", "--list-keys", "--with-colons", key_id],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        # Check for 's' (signing) in the pub line
+        for line in result.stdout.split('\n'):
+            if line.startswith('pub:'):
+                flags = line.split(':')[1]
+                return 's' in flags
+
+        return False
+
+    except subprocess.CalledProcessError:
+        return False
+
+
+def print_setup_instructions():
+    """Print instructions for configuring GitHub Secrets."""
+    print("\n" + "="*70)
+    print("GITHUB SECRETS SETUP INSTRUCTIONS")
+    print("="*70)
+
+    print("""
+To enable the automated PDF workflow, you need to add three secrets to your
+GitHub repository:
+
+1. GPG_PRIVATE_KEY
+   - Your GPG private key in ASCII armor format
+   - Used to sign PDFs and hash files
+   - IMPORTANT: Keep this secret! Never commit it publicly
+
+2. GPG_PASSPHRASE
+   - The passphrase for your GPG private key
+   - Required to unlock the private key for signing
+
+3. VT_API_KEY (optional but recommended)
+   - VirusTotal API key for malware scanning
+   - Get a free key at: https://www.virustotal.com/gui/join-us
+
+
+HOW TO ADD SECRETS:
+
+1. Go to your repository on GitHub
+2. Click 'Settings' → 'Secrets and variables' → 'Actions'
+3. Click 'New repository secret' for each secret below:
+
+   Secret Name          | Value Format
+   ---------------------|--------------------------------------------------
+   GPG_PRIVATE_KEY      | Paste the entire ASCII armored key (BEGIN PGP...)
+   GPG_PASSPHRASE       | Your key's passphrase (no special characters issues)
+   VT_API_KEY           | Your VirusTotal API key
+
+
+VERIFYING YOUR SETUP:
+
+After adding secrets, you can test by:
+1. Going to 'Actions' tab
+2. Selecting 'Build guide PDF' workflow
+3. Clicking 'Run workflow'
+4. Checking if the workflow completes successfully
+
+
+TROUBLESHOOTING:
+
+- If GPG signing fails: Check that your key has signing capability ('s' flag)
+- If passphrase is wrong: Verify you're using the correct passphrase
+- If VT scan fails: Ensure API key is valid and within rate limits
+
+
+SECURITY NOTES:
+
+⚠ NEVER share your private key or passphrase publicly
+⚠ Always use repository secrets, never hardcode in scripts
+⚠ Rotate keys periodically if compromised
+⚠ Use strong passphrases (12+ characters recommended)
+""")
+
+
+def main() -> int:
+    print("\n" + "="*70)
+    print("PDF WORKFLOW SETUP HELPER")
+    print("="*70)
+
+    # Check GPG installation
+    if not check_gpg_installed():
+        print("⚠ WARNING: GPG is not installed or not in PATH")
+        print("Please install GPG before continuing:")
+        print("  - Linux: sudo apt install gnupg")
+        print("  - macOS: brew install gnupg")
+        print("  - Windows: https://www.gpg4win.org/")
+        print("\nContinuing anyway...")
+
+    # List available keys
+    print("\n🔑 Available GPG Keys:")
+    print("-" * 70)
+
+    keys = list_gpg_keys()
+
+    if not keys:
+        print("No GPG keys found in your keyring.")
+        print("Generate a key with: gpg --full-generate-key")
+        return 1
+
+    for i, key in enumerate(keys, 1):
+        status = "✓" if validate_gpg_key(key['key_id']) else "✗"
+        print(f"\n{i}. {status} Key ID: {key['key_id']}")
+        print(f"   Fingerprint: {key.get('fingerprint', 'N/A')}")
+        print(f"   UID: {key.get('uid', 'Unknown')}")
+        print(f"   Created: {key.get('created', 'Unknown')}")
+
+        if key.get('expires'):
+            print(f"   Expires: {key['expires']}")
+
+    # Ask user to select key
+    print("\n" + "-" * 70)
+    try:
+        choice = input("\nEnter the number of the key you want to use (1-{}): ".format(len(keys)))
+        selected_index = int(choice) - 1
+
+        if not (0 <= selected_index < len(keys)):
+            print("Invalid selection!")
+            return 1
+
+    except ValueError:
+        print("Invalid input! Please enter a number.")
+        return 1
+
+    selected_key = keys[selected_index]
+
+    # Validate key has signing capability
+    if not validate_gpg_key(selected_key['key_id']):
+        print(f"\n⚠ WARNING: Selected key does not have signing capability!")
+        print("You need a key with 's' (signing) flag for PDF signatures.")
+        confirm = input("Continue anyway? (y/N): ")
+        if confirm.lower() != 'y':
+            return 1
+
+    # Export public key
+    print(f"\n📤 Exporting public key for {selected_key['uid']}...")
+    public_key_file = repo_root() / "pgp" / "workflow-public.asc"
+
+    public_key = export_public_key(selected_key['key_id'], public_key_file)
+
+    if not public_key:
+        print("Failed to export public key!")
+        return 1
+
+    # Show public key info
+    print("\n✓ Public Key Information:")
+    print("-" * 70)
+    for line in public_key.split('\n')[:5]:
+        print(line)
+    print("...")
+
+    # Instructions for private key export
+    print("\n🔐 Private Key Export:")
+    print("-" * 70)
+    print("""
+To get your private key for the GPG_PRIVATE_KEY secret:
+
+1. Run this command (you'll be prompted for passphrase):
+   gpg --armor --export-secret-keys {} > workflow-private.asc
+
+2. Copy the ENTIRE output including BEGIN and END lines
+
+3. Add it to GitHub Secrets as 'GPG_PRIVATE_KEY'
+
+⚠ IMPORTANT: Keep your private key secure! Never commit it publicly.
+""".format(selected_key['key_id']))
+
+    # Print setup instructions
+    print_setup_instructions()
+
+    print("\n" + "="*70)
+    print("SETUP COMPLETE!")
+    print("="*70)
+    print(f"\nPublic key saved to: {public_key_file}")
+    print("Next steps:")
+    print("1. Export your private key (see instructions above)")
+    print("2. Add all three secrets to GitHub repository settings")
+    print("3. Test the workflow by triggering a manual build")
+    print("\nFor more information, see: docs/guide/pdf-workflow.md\n")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/verify_pdf.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Verification script for PDF files.
+
+This script verifies:
+1. SHA256 hash integrity of PDF files
+2. GPG signature authenticity
+3. VirusTotal scan status (optional)
+
+Usage:
+  python scripts/verify_pdf.py --all                    # Verify everything
+  python scripts/verify_pdf.py --hashes                 # Only verify hashes
+  python scripts/verify_pdf.py --signatures             # Only verify signatures
+  python scripts/verify_pdf.py --vt                     # Check VT status (requires API key)
+
+Examples:
+  python scripts/verify_pdf.py --all
+  python scripts/verify_pdf.py --hashes --file export/thgtoa.pdf
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def calculate_sha256(file_path: Path) -> str:
+    """Calculate SHA256 hash of a file."""
+    sha256_hash = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        for byte_block in iter(lambda: f.read(4096), b""):
+            sha256_hash.update(byte_block)
+    return sha256_hash.hexdigest()
+
+
+def verify_hash(file_path: Path, expected_hash: str) -> bool:
+    """Verify file hash against expected value."""
+    actual_hash = calculate_sha256(file_path)
+    is_valid = actual_hash == expected_hash
+    status = "✓ PASS" if is_valid else "✗ FAIL"
+    print(f"{status}: {file_path.name}")
+    print(f"  Expected: {expected_hash}")
+    print(f"  Actual:   {actual_hash}")
+    return is_valid
+
+
+def verify_signature(file_path: Path, sig_file: Path) -> bool:
+    """Verify GPG signature of a file."""
+    if not sig_file.exists():
+        print(f"✗ FAIL: Signature file not found: {sig_file}")
+        return False
+
+    try:
+        result = subprocess.run(
+            ["gpg", "--verify", str(sig_file), str(file_path)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+        if result.returncode == 0:
+            print(f"✓ PASS: {file_path.name} signature verified")
+            # Extract key info from GPG output
+            for line in result.stdout.split('\n'):
+                if 'Good signature' in line or 'key ID' in line.lower():
+                    print(f"  {line.strip()}")
+            return True
+        else:
+            print(f"✗ FAIL: {file_path.name} signature verification failed")
+            print(f"  Error: {result.stderr}")
+            return False
+
+    except FileNotFoundError:
+        print("⚠ WARNING: GPG not installed. Skipping signature verification.")
+        return None
+
+
+def verify_from_hash_file(file_path: Path, hash_file: Path) -> bool:
+    """Verify file hash from a hash file."""
+    if not hash_file.exists():
+        print(f"✗ FAIL: Hash file not found: {hash_file}")
+        return False
+
+    expected_hash = None
+    with open(hash_file, 'r') as f:
+        for line in f:
+            parts = line.strip().split()
+            if len(parts) >= 2 and parts[1] == str(file_path):
+                expected_hash = parts[0]
+                break
+
+    if not expected_hash:
+        print(f"✗ FAIL: Hash not found in {hash_file.name} for {file_path.name}")
+        return False
+
+    return verify_hash(file_path, expected_hash)
+
+
+def check_virustotal(file_hash: str, api_key: str | None = None) -> dict | None:
+    """Check VirusTotal scan status for a file hash."""
+    if not api_key:
+        print("⚠ WARNING: VT_API_KEY not set. Skipping VirusTotal check.")
+        return None
+
+    try:
+        import urllib.request
+        import json
+
+        url = f"https://www.virustotal.com/api/v3/files/{file_hash}"
+        request = urllib.request.Request(url, headers={"x-apikey": api_key})
+
+        with urllib.request.urlopen(request, timeout=30) as response:
+            data = json.loads(response.read().decode())
+
+            stats = data.get('data', {}).get('attributes', {}).get('last_analysis_stats', {})
+            total = sum(stats.values()) if stats else 0
+
+            print(f"\n🦠 VirusTotal Results for {file_hash[:16]}...")
+            print(f"  Total scans: {total}")
+
+            if stats:
+                print(f"  Malicious:    {stats.get('malicious', 0)}")
+                print(f"  Suspicious:   {stats.get('suspicious', 0)}")
+                print(f"  Undetected:   {stats.get('undetected', 0)}")
+                print(f"  Clean:        {stats.get('harmless', 0)}")
+
+            return data
+
+    except Exception as e:
+        print(f"⚠ ERROR checking VirusTotal: {e}")
+        return None
+
+
+def main() -> int:
+    root = repo_root()
+    ap = argparse.ArgumentParser(description="Verify PDF files (hashes, signatures, VT).")
+
+    # File paths
+    ap.add_argument(
+        "--light-pdf",
+        type=Path,
+        default=root / "export" / "thgtoa.pdf",
+        help="Light mode PDF file",
+    )
+    ap.add_argument(
+        "--dark-pdf",
+        type=Path,
+        default=root / "export" / "thgtoa-dark.pdf",
+        help="Dark mode PDF file",
+    )
+    ap.add_argument(
+        "--hash-file",
+        type=Path,
+        default=root / "sha256sum-light.txt",
+        help="Hash file to verify against",
+    )
+
+    # Verification modes
+    group = ap.add_mutually_exclusive_group()
+    group.add_argument("--all", action="store_true", help="Verify everything")
+    group.add_argument("--hashes", action="store_true", help="Only verify hashes")
+    group.add_argument("--signatures", action="store_true", help="Only verify signatures")
+    ap.add_argument("--vt", action="store_true", help="Check VirusTotal status")
+
+    args = ap.parse_args()
+
+    # Determine what to verify
+    if not any([args.all, args.hashes, args.signatures, args.vt]):
+        args.all = True
+
+    all_passed = True
+
+    pdf_files = [
+        ("Light", args.light_pdf),
+        ("Dark", args.dark_pdf),
+    ]
+
+    for mode_name, pdf_file in pdf_files:
+        if not pdf_file.exists():
+            print(f"⚠ WARNING: {pdf_file.name} not found. Skipping.")
+            continue
+
+        print(f"\n{'='*60}")
+        print(f"Verifying {mode_name} PDF: {pdf_file.name}")
+        print('='*60)
+
+        # Verify hash if requested
+        if args.all or args.hashes:
+            if not verify_from_hash_file(pdf_file, args.hash_file):
+                all_passed = False
+
+        # Verify signature if requested
+        if args.all or args.signatures:
+            sig_file = pdf_file.with_suffix(pdf_file.suffix + ".sig")
+            result = verify_signature(pdf_file, sig_file)
+            if result is False:  # None means skipped (GPG not installed)
+                all_passed = False
+
+        # Check VirusTotal if requested
+        if args.all or args.vt:
+            file_hash = calculate_sha256(pdf_file)
+            api_key = os.environ.get("VT_API_KEY")
+            check_virustotal(file_hash, api_key)
+
+    print(f"\n{'='*60}")
+    if all_passed:
+        print("✓ All verifications PASSED")
+        return 0
+    else:
+        print("✗ Some verifications FAILED")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())