docs: update all docs to reflect dual-auth support

- README: prerequisites for repo-permissions-report and copilot-report
  updated from gh CLI to curl; az marked as optional; available actions
  table includes both new scripts; usage examples updated
- AGENTS.md: shared library table adds configure_gh_auth and
  gh_api_paginate; tech stack row for gh CLI updated to only list
  github-organize-stars; error handling sequence documents the
  auto-resolution side-effect
- copilot-instructions.md: script descriptions for repo-permissions-report
  and copilot-report updated to reflect curl usage; copilot-report az
  requirement noted as optional/runtime-checked

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: locus313

.github/copilot-instructions.md

@@ -193,19 +193,19 @@ Generates an HTML report of issues created in a date range (`MONTH_START`/`MONTH
 
 ### `github-organize-stars`
 
-Uses `gh` CLI GraphQL (not `curl`) to fetch all starred repos. Categorizes by primary language, GitHub topics, and name keywords using a `RULES` array (pipe-delimited: `List Name|LANGUAGES|TOPICS|NAME_KEYWORDS`; first matching rule wins). Caches stars at `~/.cache/gh-star-organizer/stars.json`. Supports `--dry-run`, `-y` (skip confirm), `--show-repos`, and `--no-cache`. Adds repos to Lists in batches of 25.
+Uses `gh` CLI GraphQL (not `curl`) to fetch all starred repos. Accepts `GITHUB_TOKEN` env var or an active `gh` auth session for authentication. Categorizes by primary language, GitHub topics, and name keywords using a `RULES` array (pipe-delimited: `List Name|LANGUAGES|TOPICS|NAME_KEYWORDS`; first matching rule wins). Caches stars at `~/.cache/gh-star-organizer/stars.json`. Supports `--dry-run`, `-y` (skip confirm), `--show-repos`, and `--no-cache`. Adds repos to Lists in batches of 25.
 
 ### `github-repo-from-template`
 
 Creates a private repo from `TEMPLATE_REPO` (including all branches), assigns admin permissions to space-separated `REPO_ADMIN` teams, write permissions to `REPO_WRITE` teams, then invites `CD_USERNAME` as a collaborator using `CD_GITHUB_TOKEN` and auto-accepts the invitation. All slug values are validated before use.
 
 ### `github-repo-permissions-report`
 
-Uses `gh` CLI (not `curl`/`GITHUB_TOKEN`) for all API calls. Accepts `-r OWNER/REPO`, `-b BRANCH`, and `-o FILE` flags. Outputs a CSV with two record types: `permission` (all users/teams) and `bypass_actor` (explicit PR approval bypass entries). Reports both branch protection rules and repository rulesets. Requires `gh auth login` before running — no `GITHUB_TOKEN` env var needed.
+Uses `curl` for all API calls. Accepts `GITHUB_TOKEN` env var or an active `gh` auth session (token auto-resolved at lib source time) for authentication. Accepts `-r OWNER/REPO`, `-b BRANCH`, and `-o FILE` flags. Outputs a CSV with two record types: `permission` (all users/teams) and `bypass_actor` (explicit PR approval bypass entries). Reports both branch protection rules and repository rulesets.
 
 ### `github-copilot-report`
 
-Uses `gh` CLI (not `curl`/`GITHUB_TOKEN`) for all GitHub API calls; requires `gh auth refresh --scopes "read:enterprise,manage_billing:enterprise"`. Also requires `az` to be **installed** (not just logged in) — the script calls `require_command az` unconditionally before checking `--no-entra`. When `az` is logged in, enriches each user with Entra ID department and job title via `az rest`.
+Uses `curl` for all GitHub API calls. Accepts `GITHUB_TOKEN` env var (PAT with `read:enterprise` and `manage_billing:enterprise` scopes) or an active `gh` auth session (token auto-resolved at lib source time) for authentication. Also requires `az` to be **installed** when Entra ID enrichment is needed — `az` is checked at runtime only if `--no-entra` is not set and `az` is not already skipped. If `az` is not installed or not logged in, Entra lookup is silently skipped. When `az` is logged in, enriches each user with Entra ID department and job title via `az rest`.
 
 Auto-detects credits per seat from a promo/standard table keyed on plan type and today's date (promo period Jun 1 – Sep 1, 2026); override with `--credits N` or `$CREDITS_PER_SEAT_OVERRIDE`. Credits are pooled enterprise-wide, not per-user buckets. Code completions are not billed in AI credits.
 

AGENTS.md

@@ -47,7 +47,7 @@ github-api-scripts/
 | bash 4+ | All scripts |
 | curl | GitHub REST and GraphQL API calls |
 | jq | JSON parsing and transformation |
-| gh CLI | Used in `github-organize-stars` and `github-repo-permissions-report` |
+| gh CLI | Used in `github-organize-stars` |
 | base64 | Used in `github-auto-repo-creation` for CODEOWNERS encoding |
 | git | Used in `github-import-repo` for bare clone + mirror push |
 | shellcheck | Linting (pre-commit hook + CI) |
@@ -142,9 +142,11 @@ Always use `SCRIPT_DIR` to build the path to `lib/github-common.sh`. The library
 | `print_status` / `print_success` / `print_warning` / `print_error` | Colored output |
 | `require_env_var <VAR>` | Exit with message if variable unset/empty |
 | `require_command <cmd>` | Exit if binary not in PATH |
+| `configure_gh_auth [scope_hint]` | Bridge GITHUB_TOKEN→GH_TOKEN or verify gh auth session |
 | `validate_github_token [bearer]` | Verify GITHUB_TOKEN via /user endpoint |
 | `validate_slug <value> <label>` | Reject values with non-alphanumeric/hyphen/underscore chars |
 | `gh_api <path> [curl args...]` | Bearer-auth REST helper with 5-retry rate-limit handling |
+| `gh_api_paginate <path> [filter] [version]` | Paginated REST helper, follows Link headers, streams items |
 | `get_enterprise_orgs` | Three-tier enterprise org resolver (REST → GraphQL → /user/orgs) |
 | `get_repo_page_count <url>` | Returns total pages for a paginated endpoint |
 
@@ -155,6 +157,8 @@ Always use `SCRIPT_DIR` to build the path to `lib/github-common.sh`. The library
 3. Validate additional inputs with `validate_slug` where needed
 4. Proceed with main logic
 
+> **Note on token auto-resolution:** Sourcing `lib/github-common.sh` automatically populates `GITHUB_TOKEN` from an active `gh` auth session if the variable is unset. This means `require_env_var GITHUB_TOKEN` may pass even when no explicit token was provided by the caller — the token was silently resolved from `gh auth token`. Script headers should document `GITHUB_TOKEN` as "Required (or provided by an active gh auth session)". Scripts that use the `gh` CLI instead of `curl` should call `configure_gh_auth` instead of step 2 above.
+
 ### Pagination (REST)
 
 ```bash

README.md

@@ -516,11 +516,12 @@ cd reporting/github-monthly-issues-report
 Exports repository user/team permissions to CSV and identifies who can bypass pull request approval requirements, from both branch protection rules and repository rulesets.
 
 **Prerequisites:**
-- **[gh](https://cli.github.com)** — GitHub CLI (authenticated via `gh auth login`)
+- **[curl](https://curl.se)** — HTTP client
 - **[jq](https://stedolan.github.io/jq)** — JSON processor
 
 **Usage:**
 ```bash
+export GITHUB_TOKEN=ghp_yourtoken   # or resolved automatically from an active gh auth session
 cd reporting/github-repo-permissions-report
 ./github-repo-permissions-report.sh -r OWNER/REPO
 ./github-repo-permissions-report.sh -r OWNER/REPO -b main -o report.csv
@@ -540,9 +541,6 @@ cd reporting/github-repo-permissions-report
 - Identifies every principal that can bypass PR approval requirements
 - Produces a CSV with two record types: `permission` (all users/teams) and `bypass_actor` (explicit bypass entries)
 
-> [!NOTE]
-> Uses the `gh` CLI for all API calls. Authenticate via `gh auth login` before running.
-
 ---
 
 ### Copilot Enterprise Report
@@ -552,14 +550,18 @@ cd reporting/github-repo-permissions-report
 Generates a GitHub Copilot Enterprise licence and usage report. Shows every licensed user, their plan type, pool credit contribution, and actual AI credit consumption for the current billing month. Optionally enriches data with Entra ID department information.
 
 **Prerequisites:**
-- **[gh](https://cli.github.com)** — GitHub CLI authenticated with `read:enterprise` and `manage_billing:enterprise` scopes
-- **[az](https://learn.microsoft.com/en-us/cli/azure/)** — Azure CLI (must be installed; login required only for Entra ID department enrichment — pass `--no-entra` to skip the login requirement)
+- **[curl](https://curl.se)** — HTTP client
+- **[az](https://learn.microsoft.com/en-us/cli/azure/)** — Azure CLI (optional; required only for Entra ID department enrichment — pass `--no-entra` or omit az to skip)
 - **[jq](https://stedolan.github.io/jq)** — JSON processor
 
 **Required variables:**
 ```bash
 export GITHUB_ENTERPRISE="your-enterprise-slug"
 
+# GitHub auth — use one of:
+export GITHUB_TOKEN=ghp_yourtoken    # PAT with read:enterprise and manage_billing:enterprise scopes
+# OR: token is resolved automatically from an active gh auth session with the required scopes
+
 # Optional: Entra ID UPN domain for users without a public GitHub email
 export UPN_DOMAIN="example.com"        # e.g. 'john_example' → john@example.com
 
@@ -571,9 +573,7 @@ export CREDITS_PER_SEAT_OVERRIDE="1900"
 ```bash
 cd reporting/github-copilot-report
 
-# Authenticate first
-gh auth refresh --scopes "read:enterprise,manage_billing:enterprise"
-az login   # required to be installed; login needed only for department enrichment
+az login   # optional; needed only for Entra ID department enrichment
 
 ./github-copilot-report.sh -e YOUR-ENTERPRISE
 ./github-copilot-report.sh -e YOUR-ENTERPRISE -d example.com
@@ -599,10 +599,10 @@ az login   # required to be installed; login needed only for department enrichme
 - Outputs a CSV and a formatted console summary with department breakdown and model usage tables
 
 > [!IMPORTANT]
-> Requires an enterprise owner or billing manager token. Run `gh auth refresh --scopes "read:enterprise,manage_billing:enterprise"` before executing.
+> Requires a PAT with `read:enterprise` and `manage_billing:enterprise` scopes — the built-in `GITHUB_TOKEN` cannot grant enterprise-level access. Set `GITHUB_TOKEN` before executing (or have an active `gh` auth session with those scopes so the lib can auto-resolve the token).
 
 > [!NOTE]
-> Uses the `gh` CLI and (optionally) the `az` CLI. The Entra ID enrichment is skipped automatically if `az` is not logged in, or can be disabled with `--no-entra`.
+> The Entra ID enrichment is skipped automatically if `az` is not logged in, or can be disabled with `--no-entra`.
 
 ---
 
@@ -802,7 +802,7 @@ cd enterprise/github-get-public-repos
 Fetches all your starred repositories and organizes them into GitHub Lists using customizable categorization rules.
 
 **Prerequisites:**
-- **[gh](https://cli.github.com)** - GitHub CLI (authenticated via `gh auth login`)
+- **[gh](https://cli.github.com)** - GitHub CLI (authenticated via `GITHUB_TOKEN` env var or `gh auth login`)
 - **[jq](https://stedolan.github.io/jq)** - Command-line JSON processor
 
 **Usage:**
@@ -835,7 +835,7 @@ Edit the `RULES` array in the script. Each rule is a `|`-delimited string:
 The **first matching rule wins**, so order matters. Place more specific rules (e.g., AI) before general ones (e.g., Security).
 
 > [!NOTE]
-> This script uses the `gh` CLI for all API calls (GraphQL) rather than `curl`. Ensure you are authenticated via `gh auth login` before running.
+> This script uses the `gh` CLI for all API calls (GraphQL) rather than `curl`. Authenticate by setting `GITHUB_TOKEN` or by running `gh auth login`.
 
 ## Shared Library: `lib/github-common.sh`
 
@@ -921,6 +921,8 @@ Each script is published as a **composite action**, so you can reference it dire
 | `org-admin/github-migrate-internal-repos-to-private` | Convert all internal-visibility repositories to private |
 | `org-admin/github-repo-from-template` | Create a repository from a template with team permissions and a CI/CD collaborator |
 | `reporting/github-monthly-issues-report` | Generate an HTML report of issues created within a date range |
+| `reporting/github-repo-permissions-report` | Export repository collaborator/team permissions and branch-approval bypass actors to CSV |
+| `reporting/github-copilot-report` | GitHub Copilot Enterprise licence and AI credit usage report, optionally enriched with Entra ID department data |
 
 ---