Refactor code structure for improved readability and maintainability

Author: CalinL

README.md

@@ -20,18 +20,20 @@ Comprehensive L400-level technical documentation for GitHub Enterprise Cloud adm
 
 ### Repository Governance
 - [📦 Repository Governance](docs/07-repository-governance.md) - Rulesets, branch protection, templates
-- [🔒 Security & Compliance](docs/08-security-compliance.md) - GHAS, code scanning, audit logs
+- [🔒 Security & Compliance](docs/08-security-compliance.md) - GHAS split SKUs (Secret Protection + Code Security), code scanning, secret scanning, dependency review, audit logs
 
 ### Best Practices & Architecture
-- [✅ Best Practices & WAF](docs/09-best-practices-waf.md) - GitHub Well-Architected Framework principles
+- [✅ Best Practices & WAF](docs/09-best-practices-waf.md) - Azure WAF pillars applied to GitHub Enterprise Cloud (Reliability, Security, Operational Excellence, Performance Efficiency, Cost Optimization); see also wellarchitected.github.com for GitHub's native WAF
 - [🏗️ Reference Architecture](docs/10-reference-architecture.md) - Architecture diagrams and patterns
 
 ### Security Policies
 - [🛡️ Security-by-Default Policies](docs/11-security-by-default-policies.md) - Comprehensive security settings and policy recommendations for Enterprise, Organization, and Repository levels
 - [⚠️ GitHub Actions Security: Echo Command Injection](docs/17-github-actions-security-echo-command-injection.md) - Echo command injection vulnerability (HackerBot Claw attack) prevention in GitHub Actions workflows
 
 ### AI & Copilot Governance
-- [🤖 GitHub Copilot Governance](docs/12-github-copilot-governance.md) - Enterprise Copilot policies, settings, content exclusions, license management, and best practices
+- [🤖 GitHub Copilot Governance](docs/12-github-copilot-governance.md) - Enterprise Copilot policies, settings, content exclusions, license management, and best practices, including Copilot cloud agent governance and Copilot Spaces (formerly Knowledge Bases)
+- [💳 GitHub Copilot Usage-Based Billing Research](docs/GitHub-Copilot-Usage-Based-Billing-Research.md) - Premium requests, AI credits, cost-center allocation, and budget controls for Copilot consumption
+- [📊 GitHub Chargeback System Design](docs/22-github-chargeback-system-design.md) - Internal cost allocation framework for GitHub Enterprise spend (seats, Actions minutes, Copilot premium requests, GHAS committers)
 - [🔄 GitHub Organization Rename Impact](docs/18-github-rename-org-impact.md) - Impact analysis of renaming a GitHub organization on Copilot, EMU authentication, and post-rename actions
 
 ### Implementation Guides
@@ -48,6 +50,7 @@ Comprehensive L400-level technical documentation for GitHub Enterprise Cloud adm
 - [� Azure Pipelines with GitHub Repos Integration](docs/15-azure-pipelines-github-repos-integration.md) - Impact analysis of using Azure Pipelines with GitHub repositories after migration
 - [🔍 Azure DevOps to GitHub Migration Analysis](docs/16-azure-devops-to-github-migration-analysis.md) - Detailed technical analysis of the migration process
 - [🔑 ADO REST API Authentication Without PATs](docs/ado-rest-api-auth-without-pat.md) - Alternatives to Personal Access Tokens for Azure DevOps REST API authentication in CI/CD pipelines
+- [🧹 ADO Tenant & Org Cleanup](docs/ADO-Tenant-Org-Cleanup.md) - Post-migration cleanup of Azure DevOps tenant connections, PAT policies, orphaned orgs
 - [❓ ADO to GitHub Migration Q&A Guide](docs/ADO-to-GitHub-Migration-QA.md) - Detailed questions and answers about migrating from Azure DevOps to GitHub using GEI
 - [💬 Workshop FAQ](docs/FAQ-workshop.md) - Frequently asked questions from GitHub Enterprise Admin workshops, including migration-related topics
 
@@ -81,16 +84,16 @@ Practical exercises to reinforce GitHub administration concepts.
 > Additional resources to continue your GitHub Admin learning journey.
 
 ### Learning GitHub Admin
-- [Microsoft Learn - GitHub Administration Collection](https://docs.microsoft.com/en-us/users/githubtraining/collections/mom7u1gzjdxw03)
-- [GitHub Enterprise Onboarding Guide](https://resources.github.com/getting-started/enterprise/)
+- [Microsoft Learn - GitHub Administration Collection](https://learn.microsoft.com/en-us/users/githubtraining/collections/mom7u1gzjdxw03)
+- [GitHub Enterprise Onboarding Guide](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) (Enterprise Cloud)
 - [The Book on GitHub Enterprise Cloud Adoption](https://resources.github.com/devops/get-started-with-github-enterprise-cloud/)
 - [GitHub Skills](https://skills.github.com/)
 
 ### GitHub Admin Documentation
 - [Enterprise administrators](https://docs.github.com/en/enterprise-cloud@latest/admin)
 - [Organizations](https://docs.github.com/en/enterprise-cloud@latest/organizations)
 - [Repositories](https://docs.github.com/en/enterprise-cloud@latest/repositories)
-- [Roles in an organization](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permission-levels-for-an-organization)
+- [Roles in an organization](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#about-predefined-organization-roles)
 - [Configuring SCIM provisioning for Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users)
 - [About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users)
 - [Managing a branch protection rule](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule)
@@ -103,17 +106,18 @@ Practical exercises to reinforce GitHub administration concepts.
 - [admin Archives | The GitHub Blog](https://github.blog/changelog/label/admin/)
 
 ### Videos
+> Note: The videos below are from GitHub Universe 2021 and may show superseded UI. For current sessions see https://www.youtube.com/githubtraining .
 - [What's new for GitHub Enterprise - GitHub Universe 2021 - YouTube](https://www.youtube-nocookie.com/embed/ZZviWZgrqhM)
 - [GitHub in the Enterprise - GitHub Universe 2021 - YouTube](https://www.youtube.com/watch?v=1-i39RqaxRs)
 - [Enforcing information security policy through GitHub Enterprise - GitHub Universe 2021 - YouTube](https://www.youtube-nocookie.com/embed/DCu-ZTT7WTI)
 - [GitHub Universe](https://githubuniverse.com/)
 
 ### Articles & Guides
 - [Best practices for organizations and teams using GitHub Enterprise Cloud](https://github.blog/2023-08-02-best-practices-for-organizations-and-teams-using-github-enterprise-cloud/)
-- [Everything new from GitHub Universe 2022](https://github.blog/2022-11-09-everything-new-from-github-universe-2022/)
+- [Everything new from GitHub Universe 2022](https://github.blog/2022-11-09-everything-new-from-github-universe-2022/) (2022 — refer to GitHub's blog for more recent announcements)
 - [Improved management for GitHub Enterprise owners | The GitHub Blog](https://github.blog/2022-03-10-improved-management-github-enterprise-owners/)
 - [How to secure your GitHub organization and enterprise account | The GitHub Blog](https://github.blog/2020-07-23-how-to-secure-your-github-organization-and-enterprise-account/)
-- [Connect GitHub Enterprise Cloud to Defender for Cloud Apps | Microsoft Docs](https://docs.microsoft.com/en-us/defender-cloud-apps/connect-github-ec)
-- [How Defender for Cloud Apps helps protect your GitHub Enterprise environment | Microsoft Docs](https://docs.microsoft.com/en-us/defender-cloud-apps/protect-github)
-- [GitHub Workflow Guide](https://github.github.com/services-workflow-guide/#/)
+- [Connect GitHub Enterprise Cloud to Defender for Cloud Apps | Microsoft Docs](https://learn.microsoft.com/en-us/defender-cloud-apps/connect-github-ec)
+- [How Defender for Cloud Apps helps protect your GitHub Enterprise environment | Microsoft Docs](https://learn.microsoft.com/en-us/defender-cloud-apps/protect-github)
+- [GitHub Workflow Guide](https://docs.github.com/en/get-started/using-github/github-flow)
 - [Removing sensitive data from a repository - GitHub Docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)

docs/01-enterprise-hierarchy.md

@@ -1,5 +1,28 @@
 # GitHub Enterprise Cloud Hierarchy
 
+> **Document status**
+>
+> - **Last reviewed:** 2026-05-19
+> - **Authorship:** Drafted with AI assistance (GitHub Copilot, multi-model review) and reviewed by a human maintainer before publication.
+> - **Sources:** Based on public documentation — primarily [docs.github.com](https://docs.github.com), [learn.microsoft.com](https://learn.microsoft.com), and official vendor blogs cited inline.
+> - **Verify before acting:** GitHub and Microsoft update product documentation continuously. Re-confirm against the live source pages before relying on this content for production decisions.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Enterprise Account Capabilities](#enterprise-account-capabilities)
+- [Hierarchy Levels](#hierarchy-levels)
+- [Enterprise Roles](#enterprise-roles)
+- [Enterprise Settings and Dashboard Navigation](#enterprise-settings-and-dashboard-navigation)
+- [Multi-Organization Management Patterns](#multi-organization-management-patterns)
+- [Enterprise Admin Responsibilities Flow](#enterprise-admin-responsibilities-flow)
+- [Enterprise Audit Log and Compliance Features](#enterprise-audit-log-and-compliance-features)
+- [Best Practices for Enterprise Administration](#best-practices-for-enterprise-administration)
+- [Advanced Topics](#advanced-topics)
+- [Migration and Onboarding Strategies](#migration-and-onboarding-strategies)
+- [Troubleshooting Common Issues](#troubleshooting-common-issues)
+- [References](#references)
+
 ## Overview
 
 GitHub Enterprise Cloud (GHEC) provides a multi-tiered organizational structure that enables large organizations to manage multiple teams, projects, and repositories under a unified enterprise account. This hierarchical model facilitates centralized governance, billing, and policy enforcement while maintaining organizational autonomy and flexibility.
@@ -15,7 +38,7 @@ An enterprise account on GitHub Enterprise Cloud delivers advanced administrativ
 **Centralized Management**
 - Unified dashboard providing real-time visibility across all organizations
 - Consolidated user management with enterprise-level identity provisioning
-- Single sign-on (SSO) enforcement via SAML 2.0 or OIDC
+- Single sign-on (SSO) enforcement via SAML 2.0 (all enterprises); OIDC available for Enterprise Managed Users (EMU) enterprises only
 - Centralized billing with cost allocation and usage analytics
 
 **Security and Compliance**
@@ -27,7 +50,7 @@ An enterprise account on GitHub Enterprise Cloud delivers advanced administrativ
 
 **Policy Enforcement**
 - Repository policy management across organizations
-- Branch protection rules inheritance
+- Repository Rulesets (applicable at enterprise → organization → repository scope)
 - Required workflows for GitHub Actions
 - Custom repository roles and permissions
 - Dependency management and security advisories
@@ -302,7 +325,7 @@ The Settings area provides access to critical configuration options:
 - Runner group management and registration
 
 **Audit Log**
-- Searchable event log with 180+ day retention
+- Searchable event log with 180-day retention (extendable via log streaming to external SIEM)
 - Export capabilities (JSON, CSV)
 - Real-time event streaming to SIEM platforms
 - Compliance reporting and anomaly detection
@@ -626,7 +649,7 @@ For long-term retention and advanced analytics, configure audit log streaming:
 EMU provides complete lifecycle management of user identities through your Identity Provider:
 
 **Key Characteristics**
-- GitHub manages user accounts on your behalf
+- User accounts are provisioned and managed by your identity provider (IdP) via SCIM
 - Users can only authenticate via enterprise SSO
 - No personal GitHub account interactions
 - Usernames follow configurable pattern (e.g., `octocat_corp`)

docs/02-organization-strategies.md

@@ -1,5 +1,24 @@
 # Organization Design Patterns and Strategies
 
+> **Document status**
+>
+> - **Last reviewed:** 2026-05-19
+> - **Authorship:** Drafted with AI assistance (GitHub Copilot, multi-model review) and reviewed by a human maintainer before publication.
+> - **Sources:** Based on public documentation — primarily [docs.github.com](https://docs.github.com), [learn.microsoft.com](https://learn.microsoft.com), and official vendor blogs cited inline.
+> - **Verify before acting:** GitHub and Microsoft update product documentation continuously. Re-confirm against the live source pages before relying on this content for production decisions.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Single Organization Pattern](#single-organization-pattern)
+- [Multi-Organization Patterns](#multi-organization-patterns)
+- [Organization Naming Conventions](#organization-naming-conventions)
+- [Migration Strategies Between Patterns](#migration-strategies-between-patterns)
+- [Organization Strategy Decision Matrix](#organization-strategy-decision-matrix)
+- [Organization Lifecycle Management](#organization-lifecycle-management)
+- [Cross-References](#cross-references)
+- [References](#references)
+
 ## Overview
 
 Organization architecture represents one of the most critical design decisions in GitHub Enterprise Cloud (GHEC) deployment. The organizational structure directly impacts security boundaries, policy enforcement, cost allocation, compliance posture, and operational efficiency. This document provides expert-level guidance on selecting, implementing, and evolving organization design patterns for enterprise-scale GitHub deployments.
@@ -159,7 +178,7 @@ graph TD
 
 ### Red-Green-Sandbox-Archive Pattern
 
-The Red-Green-Sandbox-Archive pattern is GitHub's **recommended multi-organization model** for enterprises that need more than a single organization. This pattern is based on **visibility and access control levels**, not deployment environments.
+The Red-Green-Sandbox-Archive pattern is a well-established multi-organization model widely used in GitHub Enterprise Cloud deployments. This pattern is based on **visibility and access control levels**, not deployment environments.
 
 > **Reference:** This pattern is officially documented in [Strategies for using organizations in GitHub Enterprise Cloud](https://resources.github.com/learn/pathways/administration-governance/essentials/strategies-for-using-organizations-github-enterprise-cloud/).
 
@@ -269,7 +288,7 @@ The Sandbox organization provides a **shared space where any user can create and
 - Abandoned experiments are periodically cleaned up or archived
 - No expectation of long-term maintenance
 
-> **Note:** A Sandbox organization is especially important if you configure GHEC to prevent developers from creating personal repositories.
+> **Note:** A Sandbox organization is especially important if you use Enterprise Managed Users (EMU) and configure the enterprise policy to block user-namespace repository creation. Note: This policy is EMU-only; in personal-account enterprises, GitHub cannot prevent personal repository creation.
 
 #### Archive Organization (Optional)