From c8e006c1a5f785abdeaeea4d919a66bed7e857be Mon Sep 17 00:00:00 2001
From: Patrick Lewis <4015312+locus313@users.noreply.github.com>
Date: Sun, 21 Jun 2026 12:58:47 -0700
Subject: [PATCH 1/2] feat: make repo AI-ready
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add AGENTS.md — project overview, directory map, build/run, conventions, adding-a-new-script guide
- Add CHANGELOG.md — full history from initial commit (2021) through today
- Add .mcp.json — GitHub MCP server config for Copilot CLI
- Add .github/workflows/ci.yml — shellcheck on all .sh files for every PR
- Add .github/workflows/copilot-setup-steps.yml — pre-installs jq, shellcheck, gitleaks for cloud agent
- Add .github/ISSUE_TEMPLATE/bug_report.yml + feature_request.yml
- Add .github/PULL_REQUEST_TEMPLATE.md — checklist derived from script conventions
- Add .github/dependabot.yml — monthly GitHub Actions version updates
- Update .github/copilot-instructions.md — append maintenance matrix
- Update README.md — add Contributing section and AI-Ready badge

Before: 2/12 assets (Getting Started)
After:  12/12 assets (AI-Ready)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/ISSUE_TEMPLATE/bug_report.yml      |  77 ++++++++
 .github/ISSUE_TEMPLATE/feature_request.yml |  47 +++++
 .github/PULL_REQUEST_TEMPLATE.md           |  34 ++++
 .github/copilot-instructions.md            |  75 ++++++++
 .github/dependabot.yml                     |   8 +
 .github/workflows/ci.yml                   |  35 ++++
 .github/workflows/copilot-setup-steps.yml  |  29 +++
 .mcp.json                                  |   9 +
 AGENTS.md                                  | 207 +++++++++++++++++++++
 CHANGELOG.md                               | 131 +++++++++++++
 README.md                                  |  31 ++-
 11 files changed, 681 insertions(+), 2 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/copilot-setup-steps.yml
 create mode 100644 .mcp.json
 create mode 100644 AGENTS.md
 create mode 100644 CHANGELOG.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..68ee537
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,77 @@
+name: Bug Report
+description: Report a broken or incorrect script behaviour
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in as much detail as possible so it can be reproduced and fixed quickly.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the incorrect behaviour.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands and environment variable exports used (redact the token value).
+      placeholder: |
+        export GITHUB_TOKEN=ghp_REDACTED
+        export ORG=my-org
+        ./org-admin/github-get-repo-list/github-get-repo-list.sh
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What should the script have done?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual output
+      description: Paste the full terminal output (redact any sensitive values).
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: script
+    attributes:
+      label: Affected script
+      description: Which script is affected?
+      placeholder: org-admin/github-get-repo-list/github-get-repo-list.sh
+    validations:
+      required: true
+
+  - type: dropdown
+    id: target
+    attributes:
+      label: GitHub target
+      options:
+        - github.com
+        - GitHub Enterprise Server (GHES)
+        - GitHub Enterprise Cloud (GHEC)
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, bash version, jq version
+      placeholder: |
+        OS: macOS 14 / Ubuntu 22.04
+        bash: 5.2
+        jq: 1.7
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..c57b28f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,47 @@
+name: Feature Request
+description: Suggest a new script or an improvement to an existing one
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Got an idea for a new script or a useful improvement? Describe it below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the GitHub admin task you're trying to automate.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the script or change you'd like to see, including what env vars it would accept and what it would output.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: domain
+    attributes:
+      label: Script domain
+      description: Which folder would this belong in?
+      options:
+        - org-admin
+        - enterprise
+        - reporting
+        - personal
+        - lib (shared utility)
+        - not sure
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches or existing tools you evaluated?
+    validations:
+      required: false
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..402ace5
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,34 @@
+## Description
+
+<!-- What does this PR do? Why is it needed? -->
+
+## Changes
+
+<!-- List the scripts added, modified, or removed. -->
+
+- [ ] New script: `<domain>/github-<name>/github-<name>.sh`
+- [ ] Modified: `lib/github-common.sh`
+- [ ] Other:
+
+## How to test
+
+```bash
+export GITHUB_TOKEN=ghp_REDACTED
+export ORG=test-org
+./path/to/script.sh [--dry-run]
+```
+
+<!-- Describe the expected output and any edge cases tested. -->
+
+## Checklist
+
+- [ ] `set -euo pipefail` is the first executable line after the `# ===` header
+- [ ] Script sources `lib/github-common.sh` via `SCRIPT_DIR`
+- [ ] All required env vars validated with `require_env_var`
+- [ ] Token validated with `validate_github_token` (or `validate_token` for secondary tokens)
+- [ ] User-supplied slugs validated with `validate_slug`
+- [ ] `sleep` added between repo-level operations to respect rate limits
+- [ ] README.md updated with the new/changed script (env var table + usage example)
+- [ ] Script header comment matches README documentation
+- [ ] Tested on a non-production org before production
+- [ ] shellcheck passes (`shellcheck --severity=warning --exclude=SC2034,SC1091 --shell=bash <script>`)
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 6b2f935..559d6ac 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -99,13 +99,24 @@ For enterprise-level org iteration (GraphQL), use cursor-based pagination — se
 ### Rate Limiting
 
 Rate limiting delays are calibrated per operation type:
+- **Repo-level operations** (permission grants, archival): `sleep 5` between each repository.
+- **Code search** (`github-dockerfile-discovery`): configurable via `SEARCH_SLEEP` (default 2 s) and `CONTENT_SLEEP` (default 1 s).
+- **gh_api helper** (lib): auto-retries up to 5 times on HTTP 403/429, sleeping 60 s before each retry.
 
 ### Authentication Headers
 
+- **Standard org/repo REST endpoints**: `Authorization: token ${GITHUB_TOKEN}`
+- **Enterprise endpoints and GraphQL**: `Authorization: Bearer ${GITHUB_TOKEN}`
+- **`gh_api` helper** (lib): always uses `Bearer`; pass `"bearer"` to `validate_github_token` for enterprise-level scripts.
+- **`validate_github_token`** wrapper: call without arguments for token auth, or pass `"bearer"` for Bearer auth.
 
 ### Accept Headers (Media Types)
 
 Different endpoints require specific Accept headers:
+- **Standard REST**: `Accept: application/vnd.github+json` (used by `gh_api` helper and newer scripts)
+- **Legacy REST** (older scripts): `Accept: application/vnd.github.v3+json`
+- **GraphQL**: no Accept header required; POST to `/graphql` with `Content-Type: application/json`
+- **All modern API calls**: include `X-GitHub-Api-Version: 2022-11-28` (or `2026-03-10` for Copilot usage-metrics endpoints)
 
 ### Enterprise Org Lookup Strategy
 
@@ -126,36 +137,80 @@ Scripts follow this validation sequence:
 
 ### `github-add-enterprise-team-read-permissions`
 
+Uses GraphQL cursor-based pagination to enumerate all enterprise orgs, then assigns the `all_repo_read` org role (configurable via `ALL_REPO_READ_ROLE_NAME`) to the enterprise team in each org. Requires Bearer token authentication with `admin:enterprise` scope. The `ENTERPRISE_TEAM_SLUG` is the slug without the `"ent:"` prefix.
+
 ### `github-add-repo-collaborators-by-pattern`
 
+Adds individual collaborators to org repos whose names match `REPO_NAME_REGEX` (ERE). Accepts a comma-separated `COLLABORATORS` list and an optional `REPO_EXCLUDE_REGEX` to skip matching repos. Uses `token` auth for all REST calls. Iterates all org repos paginated at 100 per page.
+
 ### `github-add-repo-permissions`
 
+Grants team permissions across all repos in an org. Reads five space-separated team-slug lists (`REPO_ADMIN`, `REPO_MAINTAIN`, `REPO_PUSH`, `REPO_TRIAGE`, `REPO_PULL`). Optionally filters repos by name prefix via `REPO_NAME_FILTER`. Sleeps 5 s between each repo to stay within rate limits. Uses legacy `Accept: application/vnd.github.v3+json` and `token` auth.
+
 ### `github-archive-old-repos`
 
+Calculates a cutoff date based on `YEARS_THRESHOLD` (default 5). Generates a timestamped CSV report under `reports/`, shows the top 10 oldest repos, and prompts for confirmation before archiving. Handles both BSD (`date -v`, macOS) and GNU (`date -d`, Linux) date syntax for cross-platform compatibility.
+
 ### `github-auto-repo-creation`
 
+Creates private repos from a comma-separated `REPO_NAMES` list. Configures branch protection on the default branch, creates a CODEOWNERS file (Base64-encoded via API), and grants admin access to comma-separated `ADMIN_TEAMS`. All slug values in `REPO_NAMES`, `ADMIN_TEAMS`, and `REPO_OWNERS` are validated before use. Requires `base64` in addition to `curl` and `jq`.
+
 ### `github-close-archived-repo-security-alerts`
 
+Dismisses open Dependabot, code-scanning, and secret-scanning alerts on all archived repos. Supports `--type` to target a single alert type and `--dry-run` to preview without changes. Generates a timestamped CSV report under `reports/`. Requires a token with `security_events` and `repo` scopes.
+
 ### `github-dockerfile-discovery`
 
+Uses GitHub code-search API to find Dockerfiles across all enterprise orgs, then fetches and parses each file to extract `FROM` instructions (including multi-stage builds). Produces three timestamped reports in `REPORT_DIR`: a detail CSV, a summary CSV, and a plain-text summary. Supports `ORGS` override, `ORG_FILTER`/`ORG_EXCLUDE` regex filters (validated as syntactically correct ERE before use), and configurable sleep intervals (`SEARCH_SLEEP`, `CONTENT_SLEEP`).
+
 ### `github-enable-issues`
 
+Iterates all non-archived repos in an org and enables the Issues feature on any repo where it is disabled. Supports `--dry-run` to list affected repos without making changes.
+
 ### `github-get-consumed-licenses`
 
+Calls the enterprise consumed-licenses endpoint using Bearer authentication. Requires `read:enterprise` scope. Returns seat consumption and purchase counts. Token-only script; no pagination or retry logic beyond what the single API call provides.
+
 ### `github-get-public-repos`
 
+Discovers all enterprise orgs (three-tier fallback via `get_enterprise_orgs`), fetches all repos in each, and filters to public visibility in `jq` (does not rely on `?type=public` query param, which is unreliable for enterprise-managed orgs). Writes a timestamped CSV to `REPORT_DIR`. Supports `ORGS` override and `ORG_FILTER`/`ORG_EXCLUDE` ERE regex filters.
+
 ### `github-get-repo-list`
 
+Outputs a CSV row per repository (full name, owner, visibility, URL, description, fork flag, pushed/created/updated timestamps) to stdout. Pagination handled at 100 repos per page via `get_repo_page_count`.
+
 ### `github-import-repo`
 
+Performs a full bare clone (`git clone --mirror`) of a source repo and pushes all branches, tags, and history to a new private destination repo. Validates `GIT_URL_PREFIX` against a GitHub-host allowlist before running any git operations to prevent credential leakage. Repo names and `OWNER_USERNAME` are validated as slugs.
+
 ### `github-migrate-internal-repos-to-private`
 
+Fetches all repos with internal visibility (paginated) and converts each to private via PATCH. Logs success or failure per repo. This operation cannot be undone via the API — converting internal to private removes access from members of other enterprise orgs.
+
 ### `github-monthly-issues-report`
 
+Generates an HTML report of issues created in a date range (`MONTH_START`/`MONTH_END`), filtered by a hardcoded label (`Linked [AC]` — edit the script to change). Uses the timeline API to track who applied labels. URL-encodes labels for API calls (e.g., `Linked [AC]` → `Linked%20[AC]`). Outputs to `output.txt`.
+
 ### `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.
+
 ### `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.
+
+### `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`.
+
+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.
+
+Uses API version `2026-03-10` and the new usage-metrics NDJSON endpoints (signed download links). The legacy `/copilot/metrics` and `/copilot/usage` endpoints were closed Apr 2, 2026.
+
 ## Development Guidelines
 
 ### Adding New Scripts
@@ -188,3 +243,23 @@ Keep new scripts dependency-minimal; document any non-standard dependencies expl
 7. **URL encoding:** Labels in API calls must be URL-encoded (`Linked [AC]` → `Linked%20[AC]`)
 8. **Public repo filtering:** Do not rely on `?type=public` for enterprise-managed orgs — fetch all and filter in jq
 9. **macOS vs Linux date:** `github-archive-old-repos.sh` handles both BSD `date -v` (macOS) and GNU `date -d` (Linux)
+
+## Maintenance Matrix
+
+When you change one of these files, you must also update the files in the "Also update" column.
+
+| When you change… | Also update |
+|------------------|-------------|
+| `lib/github-common.sh` — any public function signature or behaviour | All 19 scripts that source it; verify each caller still passes the right arguments. Check with: `grep -r "source.*github-common" . --include="*.sh"` |
+| `lib/github-common.sh` — add a new helper function | `AGENTS.md` shared library table; `README.md` if the function affects usage |
+| Any script's required env vars | That script's `# ===` header comment; the corresponding README.md section's env var table |
+| Any script's optional env vars or defaults | Same as above |
+| Any script's `--dry-run` or CLI flag behaviour | README.md usage example for that script |
+| `README.md` — script documentation | Verify the script's `# ===` header comment still matches (env vars, options, requirements) |
+| `.githooks/pre-commit` | `install-hooks.sh` if hook path or installation instructions change; README.md Best Practices section |
+| `install-hooks.sh` | README.md Installation section |
+| Add a new script | `README.md` (add use case, env var table, usage example); `CHANGELOG.md` under `[Unreleased]` |
+| Add a new domain folder | `README.md` top-level structure description; `AGENTS.md` Repository Structure section |
+| `.github/workflows/ci.yml` — shellcheck flags | `.githooks/pre-commit` shellcheck invocation (keep them in sync) |
+| `.github/workflows/copilot-setup-steps.yml` — tool versions | `AGENTS.md` Tech Stack table |
+| `AGENTS.md` | No cascade — but keep in sync with `copilot-instructions.md` if architecture changes |
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..53e9dff
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: chore
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..7671390
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.github/FUNDING.yml'
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.github/FUNDING.yml'
+
+jobs:
+  shellcheck:
+    name: Shellcheck
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install shellcheck
+        run: sudo apt-get update -qq && sudo apt-get install -y shellcheck
+
+      - name: Run shellcheck on all scripts
+        run: |
+          find . -name "*.sh" -not -path "./.git/*" | sort | xargs shellcheck \
+            --severity=warning \
+            --exclude=SC2034,SC1091 \
+            --shell=bash
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
new file mode 100644
index 0000000..ad0a7e5
--- /dev/null
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -0,0 +1,29 @@
+name: Copilot Setup Steps
+
+on:
+  workflow_dispatch:
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install jq
+        run: sudo apt-get update -qq && sudo apt-get install -y jq
+
+      - name: Install shellcheck
+        run: sudo apt-get install -y shellcheck
+
+      - name: Install gitleaks
+        run: |
+          GITLEAKS_VERSION=$(curl -s https://api.github.com/repos/gitleaks/gitleaks/releases/latest | jq -r .tag_name)
+          curl -sSL "https://github.com/gitleaks/gitleaks/releases/download/${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION#v}_linux_x64.tar.gz" \
+            | sudo tar -xz -C /usr/local/bin gitleaks
+
+      - name: Verify tools
+        run: |
+          jq --version
+          shellcheck --version
+          gitleaks version
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..0f8ace5
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "gh",
+      "args": ["mcp", "serve"],
+      "env": {}
+    }
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5e035f6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,207 @@
+# GitHub API Scripts — Agent Guide
+
+## Project Overview
+
+A collection of **standalone bash automation scripts** for GitHub organization and enterprise administration. Each script is a self-contained, self-validating CLI utility that interacts with the GitHub REST and GraphQL APIs using `curl` + `jq`. A shared utility library (`lib/github-common.sh`) provides common validation, output, and API helpers.
+
+**Key principle:** Scripts are independent — they are never imported or called by each other. Every script manages its own validation, error handling, and environment variable requirements.
+
+---
+
+## Repository Structure
+
+```
+github-api-scripts/
+├── lib/
+│   └── github-common.sh          # Shared helpers (source this, never execute directly)
+├── org-admin/                    # Organization-level administration scripts
+│   └── github-<name>/
+│       └── github-<name>.sh
+├── enterprise/                   # Enterprise-level scripts
+│   └── github-<name>/
+│       └── github-<name>.sh
+├── reporting/                    # Reporting and audit scripts
+│   └── github-<name>/
+│       └── github-<name>.sh
+├── personal/                     # Personal GitHub utility scripts
+│   └── github-<name>/
+│       └── github-<name>.sh
+├── .githooks/
+│   └── pre-commit                # Secret scanning (gitleaks) + shellcheck
+├── .github/
+│   ├── copilot-instructions.md   # Detailed AI agent conventions
+│   ├── agents/                   # Custom agent profiles
+│   ├── skills/                   # Custom skills
+│   └── instructions/             # Path-scoped instruction files
+├── install-hooks.sh              # Installs .githooks/pre-commit via git config
+├── LICENSE                       # MIT
+└── README.md                     # Full script documentation with usage examples
+```
+
+---
+
+## Tech Stack
+
+| Tool | Role |
+|------|------|
+| 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` |
+| 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) |
+| gitleaks | Secret scanning (pre-commit hook) |
+
+---
+
+## Build & Run
+
+There is no build step. Scripts run directly:
+
+```bash
+# Install the pre-commit hook (one-time setup)
+./install-hooks.sh
+
+# Run any script directly after exporting required env vars
+export GITHUB_TOKEN=ghp_yourtoken
+export ORG=my-org
+./org-admin/github-get-repo-list/github-get-repo-list.sh
+```
+
+**Lint all scripts:**
+```bash
+find . -name "*.sh" | xargs shellcheck --severity=warning --exclude=SC2034,SC1091 --shell=bash
+```
+
+---
+
+## Testing
+
+There is no automated test suite. The validation approach is:
+
+1. **Pre-commit hook** — shellcheck on every staged `.sh` file; gitleaks secret scan
+2. **Dry-run flags** — several scripts support `--dry-run` to preview changes without applying them:
+   - `github-close-archived-repo-security-alerts`
+   - `github-enable-issues`
+   - `github-organize-stars`
+3. **Test org first** — always run against a non-production GitHub org before production
+
+---
+
+## Key Patterns and Conventions
+
+### Script anatomy
+
+Every script begins with a `# ===` header (exactly 79 `=` chars), then immediately `set -euo pipefail`:
+
+```bash
+#!/bin/bash
+# =============================================================================
+# github-<name>.sh
+#
+# <description>
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ORG=my-org
+#   ./github-<name>.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN    Required. PAT with <scope> scope
+#   ORG             Required. GitHub organization name
+#   API_URL_PREFIX  Optional. GitHub API base URL (default: https://api.github.com)
+#
+# Requirements:
+#   - curl
+#   - jq
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../lib/github-common.sh
+source "${SCRIPT_DIR}/../../lib/github-common.sh"
+```
+
+### Sourcing the shared library
+
+Always use `SCRIPT_DIR` to build the path to `lib/github-common.sh`. The library is two directory levels up from any script (`../../lib/github-common.sh`). Never hardcode absolute paths.
+
+### Authentication
+
+- Standard org/repo REST calls: `Authorization: token ${GITHUB_TOKEN}`
+- Enterprise endpoints and GraphQL: `Authorization: Bearer ${GITHUB_TOKEN}`
+- The `gh_api` helper in `lib/github-common.sh` always uses Bearer; pass `"bearer"` to `validate_github_token` for enterprise scripts
+
+### Shared library helpers
+
+| Function | Purpose |
+|----------|---------|
+| `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 |
+| `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 |
+| `get_enterprise_orgs` | Three-tier enterprise org resolver (REST → GraphQL → /user/orgs) |
+| `get_repo_page_count <url>` | Returns total pages for a paginated endpoint |
+
+### Error handling sequence
+
+1. `require_env_var` all required variables
+2. `validate_github_token` (or `validate_token` for secondary tokens)
+3. Validate additional inputs with `validate_slug` where needed
+4. Proceed with main logic
+
+### Pagination (REST)
+
+```bash
+for PAGE in $(seq "$(get_repo_page_count "${API_URL_PREFIX}/orgs/${ORG}/repos?per_page=100")"); do
+  # process page
+done
+```
+
+### Rate limiting
+
+- Repo-level operations (permission grants, archival): `sleep 5` between each repo
+- Code search: configurable `SEARCH_SLEEP` (default 2s) and `CONTENT_SLEEP` (default 1s)
+- `gh_api` auto-retries on HTTP 403/429 with 60s sleep
+
+---
+
+## Adding a New Script
+
+1. **Create the directory:** `<domain>/github-<verb-noun>/`
+2. **Create the script:** `github-<verb-noun>.sh` (name must match the directory)
+3. **Copy the header template** from Script Anatomy above — fill in description, all env vars, requirements
+4. **Source the shared library** using `SCRIPT_DIR`
+5. **Validate all inputs** before any API calls
+6. **Add to README.md** — follow the existing format: use case, env var table, usage example, output format
+7. Place in the correct domain:
+   - `org-admin/` — organization-level operations (repos, teams, members)
+   - `enterprise/` — enterprise-level operations (licenses, org enumeration)
+   - `reporting/` — read-only reports and audits
+   - `personal/` — personal GitHub utilities (stars, profile)
+
+---
+
+## CI/CD
+
+- **Pre-commit hook:** `.githooks/pre-commit` — runs gitleaks + shellcheck on staged `.sh` files
+- **Install:** `./install-hooks.sh` or `git config core.hooksPath .githooks`
+- **Bypass (emergency only):** `git commit --no-verify`
+- **CI:** shellcheck runs on all `.sh` files on every PR (`.github/workflows/ci.yml`)
+
+---
+
+## Common Pitfalls
+
+- **Team slugs vs names:** API uses slugs (lowercase, hyphenated). "Platform Team" → `platform-team`
+- **Bearer vs token auth:** Enterprise endpoints need `Bearer`; standard org/repo endpoints use `token`
+- **Space-separated lists:** `REPO_ADMIN` and similar accept multiple space-separated values — loop with `for item in ${VAR}`
+- **Comma-separated lists:** `COLLABORATORS`, `REPO_NAMES`, `ORGS` use commas — split with `IFS=','`
+- **URL encoding:** Labels in API calls must be URL-encoded (e.g., `Linked [AC]` → `Linked%20[AC]`)
+- **Public repo filtering:** Do not rely on `?type=public` for enterprise-managed orgs — fetch all and filter in `jq`
+- **macOS vs Linux date:** `github-archive-old-repos.sh` handles both BSD `date -v` and GNU `date -d`
+- **`set -euo pipefail`:** Must be the first executable line after the header — never omit it
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..92c53cb
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+### Added
+- `AGENTS.md` — AI agent guide with project overview, directory map, build/run, key patterns, and adding-a-new-script walkthrough
+- `.github/workflows/ci.yml` — shellcheck CI on all `.sh` files for every PR
+- `.github/workflows/copilot-setup-steps.yml` — pre-installs jq, shellcheck, and gitleaks for Copilot cloud agent
+- `.github/ISSUE_TEMPLATE/bug_report.yml` — structured bug report form
+- `.github/ISSUE_TEMPLATE/feature_request.yml` — structured feature request form
+- `.github/PULL_REQUEST_TEMPLATE.md` — PR checklist derived from script conventions
+- `.github/dependabot.yml` — monthly GitHub Actions version updates
+- `.mcp.json` — GitHub MCP server configuration for Copilot CLI
+- Maintenance matrix section in `.github/copilot-instructions.md`
+
+---
+
+## [2026-06-21]
+
+### Added
+- `github-copilot-report`: NDJSON usage-metrics endpoints, Entra ID enrichment via `az rest`, auto-detection of credits per seat with promo/standard table, `--no-entra` flag
+- README: GitHub Actions integration examples (workflow_dispatch, artifact upload, environment protection)
+
+### Changed
+- Validated all required environment variables across all scripts before any API calls
+- Improved error handling with descriptive exit messages throughout
+
+---
+
+## [2026-06-20]
+
+### Added
+- `github-add-repo-permissions`: `REPO_NAME_FILTER` option to restrict permission grants to repos matching a name prefix
+
+### Changed
+- Enhanced validation for user-supplied inputs (slugs, regex patterns, date formats) across multiple scripts
+- Improved payload handling and JSON construction in enterprise scripts
+
+---
+
+## [2026-06-19]
+
+### Added
+- `github-copilot-report` — Copilot usage report with per-user seat data, AI credit calculations, and optional Entra ID department/job-title enrichment
+- `github-repo-permissions-report` — CSV report of all user/team permissions and branch-protection bypass actors for a given repo and branch; uses `gh` CLI
+- `.githooks/pre-commit` — secret scanning (gitleaks or built-in regex) + shellcheck on staged `.sh` files
+- `install-hooks.sh` — one-command hook installer (`git config core.hooksPath .githooks`)
+
+### Changed
+- Standardized all scripts to the `# ===` 79-char header block with full env-var and requirements documentation
+- Added `--dry-run` flag documentation to `github-close-archived-repo-security-alerts` and `github-enable-issues`
+
+---
+
+## [2026-06-18]
+
+### Added
+- `lib/github-common.sh` — shared utility library: `print_status/success/warning/error`, `require_env_var`, `require_command`, `validate_github_token`, `validate_token`, `validate_slug`, `gh_api` (Bearer auth + 5-retry rate-limit handling), `get_repo_page_count`, `get_enterprise_orgs` (three-tier fallback)
+- `github-enable-issues` — enables GitHub Issues on all repos in an org that have it disabled; supports `--dry-run`
+- `github-get-repo-list` — exports a CSV of all repos in an org (visibility, URL, timestamps)
+- `github-get-public-repos` — discovers all public repos across all enterprise orgs; writes timestamped CSV
+- `github-migrate-internal-repos-to-private` — bulk-converts internal repos to private via PATCH
+- `github-archive-old-repos` — archives repos not pushed to in N years; generates CSV report; prompts for confirmation
+- `github-auto-repo-creation` — creates private repos with branch protection, CODEOWNERS, and admin team grants
+- `github-close-archived-repo-security-alerts` — dismisses open Dependabot, code-scanning, and secret-scanning alerts on archived repos; supports `--type` and `--dry-run`
+- `github-add-enterprise-team-read-permissions` — grants `all_repo_read` org role to an enterprise team across all enterprise orgs via GraphQL pagination
+- `github-dockerfile-discovery` — code-searches all enterprise orgs for Dockerfiles, extracts `FROM` instructions, produces detail + summary CSVs
+- Reorganized all scripts into domain subdirectories: `org-admin/`, `enterprise/`, `reporting/`, `personal/`
+- `.github` instructions and agent profiles for Copilot
+
+### Changed
+- All scripts refactored to source `lib/github-common.sh` for shared validation and output helpers
+- `github-repo-from-template`: added `CD_GITHUB_TOKEN` auto-accept collaborator invitation flow
+- `github-add-repo-collaborators-by-pattern` (formerly `github-add-repo-admin`): expanded to support `REPO_EXCLUDE_REGEX` and comma-separated `COLLABORATORS`
+- README: comprehensive rewrite with per-script env var tables, usage examples, and GitHub Actions integration guide
+
+---
+
+## [2026-03-12]
+
+### Added
+- `github-organize-stars` — fetches all starred repos via `gh` CLI GraphQL, categorizes by language/topic/name-keyword rules, and adds repos to GitHub Lists in batches of 25; supports `--dry-run`, `-y`, `--show-repos`, `--no-cache`
+
+---
+
+## [2025-10-31]
+
+### Added
+- `github-add-repo-permissions` — grants configurable team permissions (`admin`, `maintain`, `push`, `triage`, `pull`) across all repos in an org
+- `.github/copilot-instructions.md` — initial AI agent instructions with architecture overview, API patterns, script-specific behaviors, and common pitfalls
+
+### Changed
+- Standardized shebang to `#!/bin/bash` and improved `GITHUB_TOKEN` validation across all scripts
+- Enhanced error messages for missing environment variables
+- Improved output formatting and readability
+
+---
+
+## [2025-03-26]
+
+### Added
+- `github-get-consumed-licenses` — calls the enterprise consumed-licenses endpoint to return seat consumption and purchase counts
+
+---
+
+## [2024-09-02]
+
+### Changed
+- `github-repo-from-template`: improved handling of template repo options and team permission assignment
+
+---
+
+## [2021-07-09]
+
+### Added
+- `github-add-repo-admin` (later renamed `github-add-repo-collaborators-by-pattern`) — adds collaborators to repos matching a name pattern
+
+---
+
+## [2021-07-04] — Initial release
+
+### Added
+- `github-import-repo` — bare-clones a source repo and mirror-pushes to a new private destination repo
+- `github-repo-from-template` — creates a private repo from a template, assigns admin teams, and invites a CD user
+- `github-monthly-issues-report` — generates an HTML report of issues created in a date range with label/timeline tracking
+- README with project overview and installation instructions
+
diff --git a/README.md b/README.md
index 365c79e..8613ac6 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
 # GitHub API Scripts
 
+[![AI Ready](https://img.shields.io/badge/AI--Ready-yes-brightgreen?style=flat)](https://github.com/johnpapa/ai-ready)
 [![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
 ![Shell](https://img.shields.io/badge/Shell-Bash-89e051?style=flat-square&logo=gnu-bash&logoColor=white)
 [![GitHub API](https://img.shields.io/badge/GitHub_API-v3-blue?style=flat-square&logo=github)](https://docs.github.com/en/rest)
@@ -552,7 +553,7 @@ Generates a GitHub Copilot Enterprise licence and usage report. Shows every lice
 
 **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 (optional, for Entra ID department enrichment)
+- **[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)
 - **[jq](https://stedolan.github.io/jq)** — JSON processor
 
 **Required variables:**
@@ -572,13 +573,24 @@ cd reporting/github-copilot-report
 
 # Authenticate first
 gh auth refresh --scopes "read:enterprise,manage_billing:enterprise"
-az login   # optional, for department enrichment
+az login   # required to be installed; login needed only for department enrichment
 
 ./github-copilot-report.sh -e YOUR-ENTERPRISE
 ./github-copilot-report.sh -e YOUR-ENTERPRISE -d example.com
 ./github-copilot-report.sh -e YOUR-ENTERPRISE --no-entra
+./github-copilot-report.sh -e YOUR-ENTERPRISE --credits 1900 --output report.csv
 ```
 
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-e, --enterprise SLUG` | GitHub Enterprise slug (or `$GITHUB_ENTERPRISE`) | — |
+| `-d, --upn-domain DOM` | Email domain for Entra lookup when GitHub carries no email (or `$UPN_DOMAIN`) | — |
+| `--credits N` | Override credits-per-seat value (or `$CREDITS_PER_SEAT_OVERRIDE`) | Auto-detected |
+| `--output FILE` | Output CSV filename | `copilot-report-YYYYMMDD.csv` |
+| `--no-entra` | Skip Entra ID department lookup | — |
+
 **What it does:**
 - Fetches all Copilot seats across the enterprise (deduplicated by user)
 - Fetches per-user AI credit consumption for the current billing month
@@ -1096,3 +1108,18 @@ export GIT_URL_PREFIX="https://github.company.com"
 - [jq Manual](https://stedolan.github.io/jq/manual/)
 - [GitHub API Rate Limits](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
 - [GitHub Actions Documentation](https://docs.github.com/en/actions)
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. **Fork** this repo and create a branch: `git checkout -b feat/my-new-script`
+2. **Install the pre-commit hook:** `./install-hooks.sh`
+3. **Add your script** following the conventions in [AGENTS.md](AGENTS.md):
+   - Create `<domain>/github-<name>/github-<name>.sh`
+   - Start with the `# ===` header and `set -euo pipefail`
+   - Source `lib/github-common.sh` and validate all inputs
+4. **Update README.md** with the env var table and usage example for your script
+5. **Run shellcheck:** `shellcheck --severity=warning --exclude=SC2034,SC1091 --shell=bash your-script.sh`
+6. **Test on a non-production org** before submitting
+7. **Open a PR** — the PR template will guide you through the checklist

From 8e1633fc3eab140a4b5e0059748b3e7d71e155b5 Mon Sep 17 00:00:00 2001
From: Patrick Lewis <4015312+locus313@users.noreply.github.com>
Date: Sun, 21 Jun 2026 13:09:22 -0700
Subject: [PATCH 2/2] fix: declare local variable separately to fix SC2155
 shellcheck warning

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 personal/github-organize-stars/github-organize-stars.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/personal/github-organize-stars/github-organize-stars.sh b/personal/github-organize-stars/github-organize-stars.sh
index cf720a7..0a81d98 100644
--- a/personal/github-organize-stars/github-organize-stars.sh
+++ b/personal/github-organize-stars/github-organize-stars.sh
@@ -164,7 +164,8 @@ fetch_stars() {
   while [[ "$has_next" == "true" ]]; do
     printf "  Fetching page %d...\r" "$page" >&2
 
-    local page_file="$tmp_dir/page$(printf '%03d' $page).json"
+    local page_file
+    page_file="$tmp_dir/page$(printf '%03d' $page).json"
     if [[ -z "$cursor" ]]; then
       gh api graphql -f query='
         query { viewer { starredRepositories(first: 100) {