From b1aada9b0efef29be97c1a5b6f8b848333797ce5 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Sat, 31 Jan 2026 19:57:30 +0000
Subject: [PATCH] docs: add project scope to gh auth setup

- Add read:project,project scopes to gh auth in install scripts
- Update troubleshooting docs for missing scopes
- Enable GitHub Projects access for workspace management

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md                |  4 ++--
 README.md                |  6 +++---
 scripts/install-deps.ps1 | 22 ++++++++++++++++++++++
 scripts/install-deps.sh  | 20 +++++++++++++++-----
 4 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c5393e3..5f30b11 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -136,8 +136,8 @@ Defined in `repos.yaml`:
 ## Troubleshooting
 
 - **"core: command not found"** → `make install-core` (builds from https://github.com/host-uk/core)
-- **"gh: command not found"** → `brew install gh && gh auth login -h github.com -p https -s workflow,repo,read:org`
-- **"refusing to allow an OAuth App to create or update workflow"** → `gh auth refresh -h github.com -s workflow`
+- **"gh: command not found"** → `brew install gh && gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project`
+- **"refusing to allow..." or "missing required scopes"** → `gh auth refresh -h github.com -s workflow,read:project,project`
 - **Clone failures** → `ssh -T git@github.com` to verify SSH keys
 
 ## This Repo's Scope
diff --git a/README.md b/README.md
index 8593673..8aa82cf 100644
--- a/README.md
+++ b/README.md
@@ -136,12 +136,12 @@ make install-core
 
 **"gh: command not found"**
 ```bash
-brew install gh && gh auth login -h github.com -p https -s workflow,repo,read:org
+brew install gh && gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project
 ```
 
-**"refusing to allow an OAuth App to create or update workflow"**
+**"refusing to allow an OAuth App to create or update workflow"** or **"missing required scopes"**
 ```bash
-gh auth refresh -h github.com -s workflow
+gh auth refresh -h github.com -s workflow,read:project,project
 ```
 
 **Clone failures**
diff --git a/scripts/install-deps.ps1 b/scripts/install-deps.ps1
index e3573c6..d7530c6 100644
--- a/scripts/install-deps.ps1
+++ b/scripts/install-deps.ps1
@@ -102,6 +102,28 @@ function Main {
     }
 
     Write-Info "Dependencies installed!"
+    Write-Host ""
+
+    # Configure GitHub CLI if not already authenticated
+    if (Test-Command gh) {
+        $authStatus = gh auth status 2>&1 | Out-String
+        if ($authStatus -match "not logged in") {
+            Write-Info "Configuring GitHub CLI..."
+            Write-Host "You'll need to authenticate with GitHub."
+            gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project
+        } else {
+            # Check for missing scopes
+            $missingScopes = @()
+            if ($authStatus -notmatch "workflow") { $missingScopes += "workflow" }
+            if ($authStatus -notmatch "read:project") { $missingScopes += "read:project,project" }
+
+            if ($missingScopes.Count -gt 0) {
+                Write-Warn "GitHub CLI missing scopes: $($missingScopes -join ', ')"
+                Write-Host "Run: gh auth refresh -h github.com -s workflow,read:project,project"
+            }
+        }
+    }
+
     Write-Host ""
     Write-Host "Next: Run '.\scripts\install-core.ps1' to install the core CLI"
 }
diff --git a/scripts/install-deps.sh b/scripts/install-deps.sh
index b803871..eae6cfc 100755
--- a/scripts/install-deps.sh
+++ b/scripts/install-deps.sh
@@ -295,12 +295,22 @@ main() {
             echo "You'll need to authenticate with GitHub."
             echo "When prompted, select HTTPS and add the 'workflow' scope."
             echo ""
-            gh auth login -h github.com -p https -s workflow,repo,read:org
+            gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project
         else
-            # Check if workflow scope is present
-            if ! gh auth status 2>&1 | grep -q workflow; then
-                warn "GitHub CLI missing 'workflow' scope (needed for pushing repos with GitHub Actions)"
-                echo "Run: gh auth refresh -h github.com -s workflow"
+            # Check if required scopes are present
+            local auth_status=$(gh auth status 2>&1)
+            local missing_scopes=""
+
+            if ! echo "$auth_status" | grep -q workflow; then
+                missing_scopes="workflow"
+            fi
+            if ! echo "$auth_status" | grep -q "read:project"; then
+                missing_scopes="$missing_scopes read:project project"
+            fi
+
+            if [[ -n "$missing_scopes" ]]; then
+                warn "GitHub CLI missing scopes:$missing_scopes"
+                echo "Run: gh auth refresh -h github.com -s workflow,read:project,project"
             fi
         fi
     fi