From 84059354ee8365452b84c5070206197d889d7ad3 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 13:39:19 +0000
Subject: [PATCH 1/2] Initial plan


From 87a9ea62e491b6d44832c90ff9cb6b76e644c93f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 13:42:07 +0000
Subject: [PATCH 2/2] Handle missing legacy metrics token in workflow

---
 .github/workflows/generate-stats.yml |  8 ++++++++
 SETUP.md                             | 21 ++++++++++++---------
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/generate-stats.yml b/.github/workflows/generate-stats.yml
index c458c8a..37e97a5 100644
--- a/.github/workflows/generate-stats.yml
+++ b/.github/workflows/generate-stats.yml
@@ -17,8 +17,14 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v4
 
+      - name: Check METRICS_TOKEN format
+        if: ${{ !startsWith(secrets.METRICS_TOKEN, 'github_pat_') }}
+        run: |
+          echo "::warning::METRICS_TOKEN is missing or uses a legacy format. Add a fine-grained personal access token (github_pat_) as the METRICS_TOKEN secret to generate stats cards."
+
       # ── Card 1: General Stats ──────────────────────────────────────────────
       - name: Generate Stats Card
+        if: ${{ startsWith(secrets.METRICS_TOKEN, 'github_pat_') }}
         uses: lowlighter/metrics@latest
         with:
           token: ${{ secrets.METRICS_TOKEN }}
@@ -34,6 +40,7 @@ jobs:
 
       # ── Card 2: Top Languages ──────────────────────────────────────────────
       - name: Generate Languages Card
+        if: ${{ startsWith(secrets.METRICS_TOKEN, 'github_pat_') }}
         uses: lowlighter/metrics@latest
         with:
           token: ${{ secrets.METRICS_TOKEN }}
@@ -50,6 +57,7 @@ jobs:
 
       # ── Card 3: Contribution Calendar ─────────────────────────────────────
       - name: Generate Isometric Calendar
+        if: ${{ startsWith(secrets.METRICS_TOKEN, 'github_pat_') }}
         uses: lowlighter/metrics@latest
         with:
           token: ${{ secrets.METRICS_TOKEN }}
diff --git a/SETUP.md b/SETUP.md
index e4f0ca7..2fea599 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -3,17 +3,19 @@
 
 ---
 
-### Step 1 — Create a Personal Access Token
+### Step 1 — Create a Fine-Grained Personal Access Token
 
-1. Go to **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)**
-2. Click **"Generate new token (classic)"**
+1. Go to **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens**
+2. Click **"Generate new token"**
 3. Name it: `METRICS_TOKEN`
 4. Set expiration: **No expiration** (or 1 year)
-5. Select these scopes:
-   - ✅ `read:user`
-   - ✅ `repo` (needed to count private commits)
-   - ✅ `read:org`
-6. Click **Generate token** — copy it immediately, you won't see it again
+5. Set repository access to this repository (`whozahm3d/whozahm3d`)
+6. Grant repository permissions:
+   - ✅ **Contents: Read and write**
+7. Grant account permissions:
+   - ✅ **Profile: Read-only**
+   - ✅ **Metadata: Read-only**
+8. Click **Generate token** — copy it immediately, you won't see it again
 
 ---
 
@@ -70,6 +72,7 @@ No maintenance needed.
 
 | Problem | Fix |
 |---|---|
-| Action fails with "403 forbidden" | Token scopes are wrong — regenerate with `read:user`, `repo`, `read:org` |
+| Action fails with "legacy or invalid token" | Regenerate a **fine-grained** PAT (`github_pat_...`) and save it as `METRICS_TOKEN` |
+| Action fails with "403 forbidden" | Token permissions are wrong — ensure **Contents: Read and write** plus profile/metadata read access |
 | Action fails with "Resource not accessible" | Go to repo Settings → Actions → General → set Workflow permissions to "Read and write" |
 | SVGs show but look wrong | Run the workflow again manually; first run sometimes has caching issues |