diff --git a/COMING_SOON.md b/COMING_SOON.md deleted file mode 100644 index 28e7dd95..00000000 --- a/COMING_SOON.md +++ /dev/null @@ -1,31 +0,0 @@ -# Coming Soon - -## GIT Going with GitHub - Workshop Materials - -### A Two-Day Workshop by [Community Access](https://community-access.org) - -The full workshop curriculum, lesson materials, and reference guides are currently being finalized. They will be published here before the workshop begins. - -### In the Meantime - -- [**Join the Discussion Forum**](https://github.com/community-access/git-going-with-github/discussions) - ask questions, connect with fellow participants -- [**Return to the home page**](https://community-access.org/git-going-with-github/) - -### Questions? - -Need help? [File an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository. - -*A [Community Access](https://community-access.org) initiative.* - -## Authoritative Sources - -Use these official references when you need the current source of truth for facts in this chapter. - -- [GitHub Docs, home](https://docs.github.com/en) -- [GitHub Changelog](https://github.blog/changelog/) - -### Section-Level Source Map - -Use this map to verify facts for each major section in this file. - -- **GIT Going with GitHub - Workshop Materials:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [About Git](https://docs.github.com/en/get-started/using-git/about-git), [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow), [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) diff --git a/GitHub Learning Room.docx b/GitHub Learning Room.docx deleted file mode 100644 index 2febfd03..00000000 Binary files a/GitHub Learning Room.docx and /dev/null differ diff --git a/DEPLOYMENT_ASSESSMENT.md b/admin/planning/DEPLOYMENT_ASSESSMENT.md similarity index 100% rename from DEPLOYMENT_ASSESSMENT.md rename to admin/planning/DEPLOYMENT_ASSESSMENT.md diff --git a/admin/planning/README.md b/admin/planning/README.md new file mode 100644 index 00000000..798156dd --- /dev/null +++ b/admin/planning/README.md @@ -0,0 +1,59 @@ +# Planning Archive and Initiative Status + +One consolidated index of the project's planning documents. Each initiative below has a status, a summary of what shipped, and a pointer to the full original document (preserved unedited in this folder). New planning documents belong here, not in the repository root. + +## How to read this folder + +- **Shipped** means the feature is live and the planning document is retained only as a historical record and decision log. +- **In flight** means the plan still has open work; the document remains the working checklist. +- Durable, current documentation always lives in the operational docs (SPEC.md, admin/ guides, .github/README.md), never in this archive. + +## Initiative status + +| Initiative | Status | Document | +| --- | --- | --- | +| Hybrid provisioning deployment | Shipped (July 2026) | [DEPLOYMENT_ASSESSMENT.md](DEPLOYMENT_ASSESSMENT.md) | +| Provisioning failure review and hardening | Shipped (July 2026) | [REVIEW-2026-07-02.md](REVIEW-2026-07-02.md) | +| Podcast site reorganization (content repo to lp.csedesigns.com) | In flight | [REORG-PLAN.md](REORG-PLAN.md) | +| Stage 3 cutover checklist for the reorganization | In flight (gated on REORG-PLAN) | [SHIP-CHECKLIST.md](SHIP-CHECKLIST.md) | +| Site information architecture (Stage 1.3) | Approved input to REORG-PLAN | [SITE-IA.md](SITE-IA.md) | +| Tooling inventory (Stage 1.4) | Complete input to REORG-PLAN | [TOOLING-INVENTORY.md](TOOLING-INVENTORY.md) | + +## Shipped initiative summaries + +### Hybrid provisioning (replaces GitHub Classroom) + +Planned in DEPLOYMENT_ASSESSMENT.md (June 2, 2026), hardened after the July 2 incident review. Live since July 2026: the `provision-learning-rooms.yml` workflow runs `.github/scripts/provisioning/` (pure-orchestration core, injected GitHub client, serial with backoff, idempotent), creates each learner's private room from `learning-room-template`, invites the learner, and seeds Challenge 1. The algorithm is specified in SPEC.md section 7.2b. Key lesson encoded from the review: no READY claim without a green run ID; the smoke test is the gate. + +### Provisioning failure review (July 2, 2026) + +Root-caused the provisioning credential failures, added the health-check workflow and alerting, closed the registration-to-roster gap, and tolerated pending collaborator invitations. All action items in its sections 3, 4.1-4.4, and 6 were implemented; see the document for the incident narrative and lessons. + +### Peer simulation seeding (July 4, 2026, no standalone plan document) + +The Classroom removal deleted `Seed-PeerSimulation.ps1` without a replacement, leaving every learning room without the peer-simulation issue and PR that Challenges 1-13 reference (support issue 58). The Student Progression Bot now seeds and self-repairs those artifacts automatically (PR 238), Challenges 10-11 were repointed at the learner's own room (PR 239), and all active rooms were remediated in place. + +## Removed in the July 2026 cleanup + +- `datetime` (empty stray file at the root) +- `GitHub Learning Room.docx` (February draft, superseded by docs/) +- `COMING_SOON.md` (pre-launch teaser, workshop is live) +- `github/index.html` (redirect stub never served; GitHub Pages deploys only the `html/` artifact) + +## Authoritative Sources + +Use these official references when you need the current source of truth for facts in this file. + +- [GitHub Actions documentation](https://docs.github.com/en/actions) - workflow behavior referenced by the shipped initiatives +- [GitHub Pages documentation](https://docs.github.com/en/pages) - deployment model that made the root redirect stub dead weight +- [GitHub REST API documentation](https://docs.github.com/en/rest) - provisioning and seeding API calls + +### Section-Level Source Map + +Use this map to verify facts for each major section in this file. + +- **Initiative status:** the linked planning documents in this folder +- **Hybrid provisioning:** [SPEC.md](../../SPEC.md) section 7.2b, [DEPLOYMENT_ASSESSMENT.md](DEPLOYMENT_ASSESSMENT.md) +- **Provisioning failure review:** [REVIEW-2026-07-02.md](REVIEW-2026-07-02.md) +- **Peer simulation seeding:** [.github/scripts/challenge-progression.js in learning-room/](../../learning-room/.github/scripts/challenge-progression.js), PRs 238 and 239 +- **Removed in cleanup:** git history (commit for this change) diff --git a/REORG-PLAN.md b/admin/planning/REORG-PLAN.md similarity index 97% rename from REORG-PLAN.md rename to admin/planning/REORG-PLAN.md index c84cb1f8..52214e82 100644 --- a/REORG-PLAN.md +++ b/admin/planning/REORG-PLAN.md @@ -521,16 +521,16 @@ Execute in a single working session. Plan a 2-3 hour window. Branch: `cutover-20 Use these official references when you need the current source of truth for this plan. -- [Episode map](docs/EPISODE_MAP.json) -- [Episode map schema](docs/EPISODE-MAP-SCHEMA.json) -- [Tooling inventory](docs/TOOLING-INVENTORY.md) -- [Site information architecture](docs/SITE-IA.md) +- [Episode map](../../docs/EPISODE_MAP.json) +- [Episode map schema](../../docs/EPISODE-MAP-SCHEMA.json) +- [Tooling inventory](TOOLING-INVENTORY.md) +- [Site information architecture](SITE-IA.md) ### Section-Level Source Map Use this map to verify facts for each major section in this file. -- **Launch posture:** [Site Information Architecture (Stage 1.3)](docs/SITE-IA.md), [Tooling Inventory (Stage 1.4)](docs/TOOLING-INVENTORY.md) -- **Identity model:** [Episode map](docs/EPISODE_MAP.json), [Episode map schema](docs/EPISODE-MAP-SCHEMA.json) -- **Guiding principles:** [Tooling Inventory (Stage 1.4)](docs/TOOLING-INVENTORY.md), [Site Information Architecture (Stage 1.3)](docs/SITE-IA.md) -- **Stage plans and gates:** [Site Information Architecture (Stage 1.3)](docs/SITE-IA.md), [Tooling Inventory (Stage 1.4)](docs/TOOLING-INVENTORY.md), [Stage 3 Cutover - Ship Checklist](SHIP-CHECKLIST.md) +- **Launch posture:** [Site Information Architecture (Stage 1.3)](SITE-IA.md), [Tooling Inventory (Stage 1.4)](TOOLING-INVENTORY.md) +- **Identity model:** [Episode map](../../docs/EPISODE_MAP.json), [Episode map schema](../../docs/EPISODE-MAP-SCHEMA.json) +- **Guiding principles:** [Tooling Inventory (Stage 1.4)](TOOLING-INVENTORY.md), [Site Information Architecture (Stage 1.3)](SITE-IA.md) +- **Stage plans and gates:** [Site Information Architecture (Stage 1.3)](SITE-IA.md), [Tooling Inventory (Stage 1.4)](TOOLING-INVENTORY.md), [Stage 3 Cutover - Ship Checklist](SHIP-CHECKLIST.md) diff --git a/REVIEW-2026-07-02.md b/admin/planning/REVIEW-2026-07-02.md similarity index 100% rename from REVIEW-2026-07-02.md rename to admin/planning/REVIEW-2026-07-02.md diff --git a/SHIP-CHECKLIST.md b/admin/planning/SHIP-CHECKLIST.md similarity index 94% rename from SHIP-CHECKLIST.md rename to admin/planning/SHIP-CHECKLIST.md index 2be40ee9..ceaaf30e 100644 --- a/SHIP-CHECKLIST.md +++ b/admin/planning/SHIP-CHECKLIST.md @@ -177,16 +177,16 @@ old -> new pair so a reverse rename script can be reconstructed. Use these official references when you need the current source of truth for this checklist. - [Reorganization master plan](REORG-PLAN.md) -- [Episode map](docs/EPISODE_MAP.json) -- [Site information architecture](docs/SITE-IA.md) -- [Tooling inventory](docs/TOOLING-INVENTORY.md) +- [Episode map](../../docs/EPISODE_MAP.json) +- [Site information architecture](SITE-IA.md) +- [Tooling inventory](TOOLING-INVENTORY.md) ### Section-Level Source Map Use this map to verify facts for each major section in this file. -- **Pre-cutover state (verified):** [Reorganization master plan](REORG-PLAN.md), [Episode map](docs/EPISODE_MAP.json) -- **Built tools (this session):** [Tooling Inventory (Stage 1.4)](docs/TOOLING-INVENTORY.md), [Reorganization master plan](REORG-PLAN.md) +- **Pre-cutover state (verified):** [Reorganization master plan](REORG-PLAN.md), [Episode map](../../docs/EPISODE_MAP.json) +- **Built tools (this session):** [Tooling Inventory (Stage 1.4)](TOOLING-INVENTORY.md), [Reorganization master plan](REORG-PLAN.md) - **Dry-run summary:** [Reorganization master plan](REORG-PLAN.md), [Stage 3 Cutover - Ship Checklist](SHIP-CHECKLIST.md) -- **Fire sequence (locally reversible up through step 5):** [Reorganization master plan](REORG-PLAN.md), [Site Information Architecture (Stage 1.3)](docs/SITE-IA.md) -- **Rollback / exclusions / notes:** [Reorganization master plan](REORG-PLAN.md), [Tooling Inventory (Stage 1.4)](docs/TOOLING-INVENTORY.md) +- **Fire sequence (locally reversible up through step 5):** [Reorganization master plan](REORG-PLAN.md), [Site Information Architecture (Stage 1.3)](SITE-IA.md) +- **Rollback / exclusions / notes:** [Reorganization master plan](REORG-PLAN.md), [Tooling Inventory (Stage 1.4)](TOOLING-INVENTORY.md) diff --git a/docs/SITE-IA.md b/admin/planning/SITE-IA.md similarity index 95% rename from docs/SITE-IA.md rename to admin/planning/SITE-IA.md index f1f36586..83b337ff 100644 --- a/docs/SITE-IA.md +++ b/admin/planning/SITE-IA.md @@ -1,7 +1,7 @@ # Site Information Architecture (Stage 1.3) Status: draft for Stage 1.5 gate approval. -Authority: this doc, together with [EPISODE_MAP.json](EPISODE_MAP.json), governs every URL emitted by the site generator in `c:\code\ggg\generator\`. +Authority: this doc, together with [EPISODE_MAP.json](../../docs/EPISODE_MAP.json), governs every URL emitted by the site generator in `c:\code\ggg\generator\`. ## Principles @@ -270,18 +270,18 @@ Total static URLs generated by the build: roughly 12 + 9 + 79 + 79 = 179 HTML pa Use these official references when you need the current source of truth for this IA. -- [Episode map](EPISODE_MAP.json) +- [Episode map](../../docs/EPISODE_MAP.json) - [Episode map schema](EPISODE-MAP-SCHEMA.json) -- [Reorganization master plan](../REORG-PLAN.md) +- [Reorganization master plan](REORG-PLAN.md) - [Tooling inventory](TOOLING-INVENTORY.md) ### Section-Level Source Map Use this map to verify facts for each major section in this file. -- **Principles:** [Episode map](EPISODE_MAP.json), [Reorganization master plan](../REORG-PLAN.md) -- **URL map:** [Episode map](EPISODE_MAP.json), [Tooling inventory](TOOLING-INVENTORY.md) -- **Page-level layout:** [Reorganization master plan](../REORG-PLAN.md), [Episode map](EPISODE_MAP.json) -- **Facilitator banners / components / cross-link rendering:** [Episode map](EPISODE_MAP.json), [Reorganization master plan](../REORG-PLAN.md) -- **Accessibility checklist / URL stability contract:** [Site Information Architecture (Stage 1.3)](SITE-IA.md), [Reorganization master plan](../REORG-PLAN.md) -- **Mapping to existing tooling / routing summary:** [Tooling inventory](TOOLING-INVENTORY.md), [Reorganization master plan](../REORG-PLAN.md) +- **Principles:** [Episode map](../../docs/EPISODE_MAP.json), [Reorganization master plan](REORG-PLAN.md) +- **URL map:** [Episode map](../../docs/EPISODE_MAP.json), [Tooling inventory](TOOLING-INVENTORY.md) +- **Page-level layout:** [Reorganization master plan](REORG-PLAN.md), [Episode map](../../docs/EPISODE_MAP.json) +- **Facilitator banners / components / cross-link rendering:** [Episode map](../../docs/EPISODE_MAP.json), [Reorganization master plan](REORG-PLAN.md) +- **Accessibility checklist / URL stability contract:** [Site Information Architecture (Stage 1.3)](SITE-IA.md), [Reorganization master plan](REORG-PLAN.md) +- **Mapping to existing tooling / routing summary:** [Tooling inventory](TOOLING-INVENTORY.md), [Reorganization master plan](REORG-PLAN.md) diff --git a/docs/TOOLING-INVENTORY.md b/admin/planning/TOOLING-INVENTORY.md similarity index 96% rename from docs/TOOLING-INVENTORY.md rename to admin/planning/TOOLING-INVENTORY.md index b337de61..3e72fc9f 100644 --- a/docs/TOOLING-INVENTORY.md +++ b/admin/planning/TOOLING-INVENTORY.md @@ -2,7 +2,7 @@ Purpose: identify every source file in the content repo and the deploy/site repo that hardcodes an episode identifier, an appendix letter, or an audio slug, so Stage 1.3 (Site IA) and Stage 2+ (refactor) can be scoped accurately. -The canonical identity source is now [docs/EPISODE_MAP.json](EPISODE_MAP.json). Every locked field below should ultimately resolve through that map by `narration_id`, `filename`, or `topic_prefix` + `topic_number`. +The canonical identity source is now [docs/EPISODE_MAP.json](../../docs/EPISODE_MAP.json). Every locked field below should ultimately resolve through that map by `narration_id`, `filename`, or `topic_prefix` + `topic_number`. Scope of this inventory: @@ -156,17 +156,17 @@ The deploy repo `c:\code\ggg` contains a parallel `generator/` pipeline with its Use these official references when you need the current source of truth for this inventory. -- [Episode map](EPISODE_MAP.json) +- [Episode map](../../docs/EPISODE_MAP.json) - [Episode map schema](EPISODE-MAP-SCHEMA.json) - [Site information architecture](SITE-IA.md) -- [Reorganization master plan](../REORG-PLAN.md) +- [Reorganization master plan](REORG-PLAN.md) ### Section-Level Source Map Use this map to verify facts for each major section in this file. -- **Purpose / scope / exclusions:** [Reorganization master plan](../REORG-PLAN.md), [Site Information Architecture (Stage 1.3)](SITE-IA.md) -- **Group A - live tooling that drives audio identity:** [Episode map](EPISODE_MAP.json), [Episode map schema](EPISODE-MAP-SCHEMA.json) -- **Group B-D - docs tooling, legacy tools, wrappers:** [Reorganization master plan](../REORG-PLAN.md), [Site Information Architecture (Stage 1.3)](SITE-IA.md) -- **Group E-G - generation pipeline, artifacts, authoring docs:** [Reorganization master plan](../REORG-PLAN.md), [Episode map](EPISODE_MAP.json) -- **Group H / recommendations:** [Site Information Architecture (Stage 1.3)](SITE-IA.md), [Reorganization master plan](../REORG-PLAN.md), [Episode map](EPISODE_MAP.json) +- **Purpose / scope / exclusions:** [Reorganization master plan](REORG-PLAN.md), [Site Information Architecture (Stage 1.3)](SITE-IA.md) +- **Group A - live tooling that drives audio identity:** [Episode map](../../docs/EPISODE_MAP.json), [Episode map schema](EPISODE-MAP-SCHEMA.json) +- **Group B-D - docs tooling, legacy tools, wrappers:** [Reorganization master plan](REORG-PLAN.md), [Site Information Architecture (Stage 1.3)](SITE-IA.md) +- **Group E-G - generation pipeline, artifacts, authoring docs:** [Reorganization master plan](REORG-PLAN.md), [Episode map](../../docs/EPISODE_MAP.json) +- **Group H / recommendations:** [Site Information Architecture (Stage 1.3)](SITE-IA.md), [Reorganization master plan](REORG-PLAN.md), [Episode map](../../docs/EPISODE_MAP.json) diff --git a/datetime b/datetime deleted file mode 100644 index e69de29b..00000000 diff --git a/github/index.html b/github/index.html deleted file mode 100644 index 4845c98d..00000000 --- a/github/index.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - - Redirecting... - - - -

If you are not redirected, click here to go to the registration page.

- - diff --git a/html/COMING_SOON.html b/html/COMING_SOON.html deleted file mode 100644 index a5402561..00000000 --- a/html/COMING_SOON.html +++ /dev/null @@ -1,271 +0,0 @@ - - - - - - - Coming Soon - GIT Going with GitHub - - - - - - - - -
- -
- - - -

Coming Soon

-

GIT Going with GitHub - Workshop Materials

-

A Two-Day Workshop by Community Access

-

The full workshop curriculum, lesson materials, and reference guides are currently being finalized. They will be published here before the workshop begins.

-

In the Meantime

- -

Questions?

-

Need help? File an issue in the workshop repository.

-

A Community Access initiative.

-

Authoritative Sources

-

Use these official references when you need the current source of truth for facts in this chapter.

- -

Section-Level Source Map

-

Use this map to verify facts for each major section in this file.

- -
- -
-
- - - - - diff --git a/html/DEPLOYMENT_ASSESSMENT.html b/html/admin/planning/DEPLOYMENT_ASSESSMENT.html similarity index 76% rename from html/DEPLOYMENT_ASSESSMENT.html rename to html/admin/planning/DEPLOYMENT_ASSESSMENT.html index 8b3f1789..7a1e85b6 100644 --- a/html/DEPLOYMENT_ASSESSMENT.html +++ b/html/admin/planning/DEPLOYMENT_ASSESSMENT.html @@ -5,9 +5,9 @@ Deployment Assessment: Hybrid Provisioning System - GIT Going with GitHub - - - + + + + + + + +
+ +
+ + + +

Planning Archive and Initiative Status

+

One consolidated index of the project's planning documents. Each initiative below has a status, a summary of what shipped, and a pointer to the full original document (preserved unedited in this folder). New planning documents belong here, not in the repository root.

+

How to read this folder

+
    +
  • Shipped means the feature is live and the planning document is retained only as a historical record and decision log.
    • +
  • In flight means the plan still has open work; the document remains the working checklist.
    • +
  • Durable, current documentation always lives in the operational docs (SPEC.md, admin/ guides, .github/README.md), never in this archive.
    • +
+

Initiative status

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
InitiativeStatusDocument
Hybrid provisioning deploymentShipped (July 2026)DEPLOYMENT_ASSESSMENT.md
Provisioning failure review and hardeningShipped (July 2026)REVIEW-2026-07-02.md
Podcast site reorganization (content repo to lp.csedesigns.com)In flightREORG-PLAN.md
Stage 3 cutover checklist for the reorganizationIn flight (gated on REORG-PLAN)SHIP-CHECKLIST.md
Site information architecture (Stage 1.3)Approved input to REORG-PLANSITE-IA.md
Tooling inventory (Stage 1.4)Complete input to REORG-PLANTOOLING-INVENTORY.md
+

Shipped initiative summaries

+

Hybrid provisioning (replaces GitHub Classroom)

+

Planned in DEPLOYMENT_ASSESSMENT.md (June 2, 2026), hardened after the July 2 incident review. Live since July 2026: the provision-learning-rooms.yml workflow runs .github/scripts/provisioning/ (pure-orchestration core, injected GitHub client, serial with backoff, idempotent), creates each learner's private room from learning-room-template, invites the learner, and seeds Challenge 1. The algorithm is specified in SPEC.md section 7.2b. Key lesson encoded from the review: no READY claim without a green run ID; the smoke test is the gate.

+

Provisioning failure review (July 2, 2026)

+

Root-caused the provisioning credential failures, added the health-check workflow and alerting, closed the registration-to-roster gap, and tolerated pending collaborator invitations. All action items in its sections 3, 4.1-4.4, and 6 were implemented; see the document for the incident narrative and lessons.

+

Peer simulation seeding (July 4, 2026, no standalone plan document)

+

The Classroom removal deleted Seed-PeerSimulation.ps1 without a replacement, leaving every learning room without the peer-simulation issue and PR that Challenges 1-13 reference (support issue 58). The Student Progression Bot now seeds and self-repairs those artifacts automatically (PR 238), Challenges 10-11 were repointed at the learner's own room (PR 239), and all active rooms were remediated in place.

+

Removed in the July 2026 cleanup

+
    +
  • datetime (empty stray file at the root)
    • +
  • GitHub Learning Room.docx (February draft, superseded by docs/)
    • +
  • COMING_SOON.md (pre-launch teaser, workshop is live)
    • +
  • github/index.html (redirect stub never served; GitHub Pages deploys only the html/ artifact)
    • +
+

Authoritative Sources

+

Use these official references when you need the current source of truth for facts in this file.

+ +

Section-Level Source Map

+

Use this map to verify facts for each major section in this file.

+ +
+ +
+
+ + + + + diff --git a/html/REORG-PLAN.html b/html/admin/planning/REORG-PLAN.html similarity index 89% rename from html/REORG-PLAN.html rename to html/admin/planning/REORG-PLAN.html index 8ff756f0..eecb81d7 100644 --- a/html/REORG-PLAN.html +++ b/html/admin/planning/REORG-PLAN.html @@ -5,9 +5,9 @@ Git Going with GitHub - Reorganization Master Plan - GIT Going with GitHub - - - + + + + + + + +
+ +
+ + + +

Planning Archive and Initiative Status

+

One consolidated index of the project's planning documents. Each initiative below has a status, a summary of what shipped, and a pointer to the full original document (preserved unedited in this folder). New planning documents belong here, not in the repository root.

+

How to read this folder

+
    +
  • Shipped means the feature is live and the planning document is retained only as a historical record and decision log.
    • +
  • In flight means the plan still has open work; the document remains the working checklist.
    • +
  • Durable, current documentation always lives in the operational docs (SPEC.md, admin/ guides, .github/README.md), never in this archive.
    • +
+

Initiative status

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
InitiativeStatusDocument
Hybrid provisioning deploymentShipped (July 2026)DEPLOYMENT_ASSESSMENT.md
Provisioning failure review and hardeningShipped (July 2026)REVIEW-2026-07-02.md
Podcast site reorganization (content repo to lp.csedesigns.com)In flightREORG-PLAN.md
Stage 3 cutover checklist for the reorganizationIn flight (gated on REORG-PLAN)SHIP-CHECKLIST.md
Site information architecture (Stage 1.3)Approved input to REORG-PLANSITE-IA.md
Tooling inventory (Stage 1.4)Complete input to REORG-PLANTOOLING-INVENTORY.md
+

Shipped initiative summaries

+

Hybrid provisioning (replaces GitHub Classroom)

+

Planned in DEPLOYMENT_ASSESSMENT.md (June 2, 2026), hardened after the July 2 incident review. Live since July 2026: the provision-learning-rooms.yml workflow runs .github/scripts/provisioning/ (pure-orchestration core, injected GitHub client, serial with backoff, idempotent), creates each learner's private room from learning-room-template, invites the learner, and seeds Challenge 1. The algorithm is specified in SPEC.md section 7.2b. Key lesson encoded from the review: no READY claim without a green run ID; the smoke test is the gate.

+

Provisioning failure review (July 2, 2026)

+

Root-caused the provisioning credential failures, added the health-check workflow and alerting, closed the registration-to-roster gap, and tolerated pending collaborator invitations. All action items in its sections 3, 4.1-4.4, and 6 were implemented; see the document for the incident narrative and lessons.

+

Peer simulation seeding (July 4, 2026, no standalone plan document)

+

The Classroom removal deleted Seed-PeerSimulation.ps1 without a replacement, leaving every learning room without the peer-simulation issue and PR that Challenges 1-13 reference (support issue 58). The Student Progression Bot now seeds and self-repairs those artifacts automatically (PR 238), Challenges 10-11 were repointed at the learner's own room (PR 239), and all active rooms were remediated in place.

+

Removed in the July 2026 cleanup

+
    +
  • datetime (empty stray file at the root)
    • +
  • GitHub Learning Room.docx (February draft, superseded by docs/)
    • +
  • COMING_SOON.md (pre-launch teaser, workshop is live)
    • +
  • github/index.html (redirect stub never served; GitHub Pages deploys only the html/ artifact)
    • +
+

Authoritative Sources

+

Use these official references when you need the current source of truth for facts in this file.

+ +

Section-Level Source Map

+

Use this map to verify facts for each major section in this file.

+ +
+ +
+
+ + + + + diff --git a/html/search-index.json b/html/search-index.json index da03fa68..8a0c201a 100644 --- a/html/search-index.json +++ b/html/search-index.json @@ -275,18 +275,6 @@ "url": "docs/index.html", "body": "Workshop Documentation This directory contains the full workshop curriculum: chapters, appendices, and supporting reference material. Start here Course Guide -- map of every chapter and recommended reading order Get Going -- short on-ramp if you only have a few minutes Challenges -- the hands-on practice that goes with each chapter Student Onboarding -- first-time setup checklist Core chapters The numbered chapters ( 00 through 22 ) are the workshop curriculum, in order: 00 -- Pre-workshop setup 01 -- Choose your tools 02 -- Understanding GitHub 03 -- Navigating repositories 04 -- The Learning Room 05 -- Working with issues 06 -- Working with pull requests 07 -- Merge conflicts 08 -- Open source culture 09 -- Labels, milestones, projects 10 -- Notifications and Day 1 close 11 -- VS Code interface 12 -- VS Code accessibility 13 -- How Git works 14 -- Git in practice 15 -- Code review 16 -- GitHub Copilot 17 -- Issue templates 18 -- Fork and contribute 19 -- Accessibility agents 20 -- Build your agent 21 -- GitHub accessibility and open source 22 -- What comes next Appendices Reference material that supports the chapters. See appendix-a-glossary.md for the full glossary and appendix-x-resources.md for external links and further reading. Reference solutions The solutions/ directory has reference answers for every challenge, intended for facilitator use and for learners who get stuck. Authoritative Sources Use these official references when you need the current source of truth for facts in this index. GitHub Docs, home GitHub Changelog Section-Level Source Map Use this map to verify facts for each major section in this file. Chapters: GitHub Docs, home , GitHub Changelog Appendices: GitHub Docs, home , GitHub Changelog Reference solutions: GitHub Docs, home , GitHub Changelog" }, - { - "id": "docs/SITE-IA.html", - "title": "Site Information Architecture (Stage 1.3)", - "url": "docs/SITE-IA.html", - "body": "Site Information Architecture (Stage 1.3) Status: draft for Stage 1.5 gate approval. Authority: this doc, together with EPISODE_MAP.json , governs every URL emitted by the site generator in c:\\code\\ggg\\generator\\ . Principles Identity-first URLs. Every per-episode URL is keyed on the immutable map filename (without the .mp3 extension). When filename is locked, the URL is locked. track_number is never in a URL. One landing page per learning band. Nine top-level navigation routes, one per band. No "appendices" umbrella. Audio and learning views. Listeners can browse by feed order (chronological / track) or by curriculum (paired view). Both views resolve to the same per-episode pages. No legacy redirects. Greenfield launch. Old paths ( ep##-slug.html , appendix-x-*.html , anything with cc-NN- only) simply do not exist on the new site. All pages are static. No client-side routing. Every URL serves a real file from c:\\code\\ggg\\site\\ . Accessibility is non-negotiable. Semantic HTML, single H1 per page, named landmarks, keyboard-reachable controls, captions/transcripts linked from every episode page. URL map All URLs are rooted at https://lp.csedesigns.com/ggg/ . Local site build mirrors this layout under c:\\code\\ggg\\site\\ . URL Source Description / generator/templates/home.html + map Homepage. Curriculum view by default. Toggle for feed view. Hero, what-this-is, "Start here" CTA pointing at /chapters/ch-00-welcome/ . /learn/ generator/templates/learn.html + map Full curriculum-ordered view: chapters 00..22 interleaved with their paired challenges, bonus block, then appendix bands in order ref / git / tools / agents / sec / a11y. Same ordering as track_number . /feed-order/ generator/templates/feed-order.html + map Strict track_number list 1..79 with no grouping. Direct mirror of the RSS feed. /feed.xml generator/generate-feed.js + map Public RSS 2.0 + iTunes podcast feed. /chapters/ generator/templates/band-landing.html + map filter learning_band=chapter Lists 23 chapters in topic_number order. /challenges/ same template, filter learning_band=challenge Lists 16 code challenges in topic_number order. /bonus/ same template, filter learning_band=bonus Lists 5 bonus challenges in topic_number order. /ref/ same template, filter learning_band=reference Lists 6 reference appendices. /git/ same template, filter learning_band=git Lists 5 git appendices. /tools/ same template, filter learning_band=tools Lists 12 tools appendices. /agents/ same template, filter learning_band=agents Lists 6 agents appendices. /sec/ same template, filter learning_band=sec Lists 2 security appendices. /a11y/ same template, filter learning_band=a11y Lists 4 accessibility appendices. /episodes/<filename-without-ext>/ generator/templates/episode.html + map entry Per-episode page. One per map entry. 79 pages total. /media/<filename>.mp3 c:\\code\\ggg\\site\\media\\ Raw enclosure URL. Used by <enclosure> and <audio src> . Direct download supported. /about/ , /contributors/ , /contact/ , /license/ static templates Standard site furniture. No map dependency. /search/ generator/templates/search.html + site/search-index.json Client-side search across episode titles, summaries, and chapter marker titles. Built from map. /sitemap.xml generator/generate-sitemap.js + map XML sitemap including all 79 episode pages and all band landings. /robots.txt static Standard. /opml.xml generator/generate-opml.js + map OPML export of the feed. Stage 5 polish; can ship empty in Stage 3. Per-episode URL examples Map entry URL ch-00-welcome.mp3 /episodes/ch-00-welcome/ ch-05-collaboration.mp3 /episodes/ch-05-collaboration/ cc-05-make-your-mark.mp3 /episodes/cc-05-make-your-mark/ cc-bonus-d-notifications.mp3 /episodes/cc-bonus-d-notifications/ ref-01-glossary.mp3 /episodes/ref-01-glossary/ a11y-04-document-developer-tools.mp3 /episodes/a11y-04-document-developer-tools/ Page-level layout Homepage / Sections, top to bottom: Skip link to main content (visually hidden until focus). Site header with primary nav (chapters, challenges, appendices dropdown opening to the six appendix-band routes, search). Hero: show title, tagline, single CTA "Start with Chapter 00: Welcome" linking to /episodes/ch-00-welcome/ . "How to use this site" three-card row: Learn (curriculum view), Listen (feed view), Reference (band landings). Latest two map entries by track_number (NOT by date) as a "Continue where the curriculum begins" strip. Newsletter / register CTA. No-op for now. Site footer with license, repo links, accessibility statement. No date carousel. No "recent episodes" widget. Order is curriculum-driven, not chronological. Curriculum view /learn/ Linear ordered list of all 79 entries by track_number . Visual grouping: chapter+challenge pairs share a card (the chapter on top, the challenge nested below in a details / summary block), bonuses get their own card-band, each appendix band gets a heading. Each card" - }, - { - "id": "docs/TOOLING-INVENTORY.html", - "title": "Tooling Inventory (Stage 1.4)", - "url": "docs/TOOLING-INVENTORY.html", - "body": "Tooling Inventory (Stage 1.4) Purpose: identify every source file in the content repo and the deploy/site repo that hardcodes an episode identifier, an appendix letter, or an audio slug, so Stage 1.3 (Site IA) and Stage 2+ (refactor) can be scoped accurately. The canonical identity source is now docs/EPISODE_MAP.json . Every locked field below should ultimately resolve through that map by narration_id , filename , or topic_prefix + topic_number . Scope of this inventory: Source-controlled tooling and authoring files in c:\\code\\git-going-with-github . Top-level scripts ( generate-*.bat , build-rss-feed.bat , validate-rss-feed.bat , generate-podcast-scripts.py ). podcasts/ tooling and configuration (excluding audio/ , chapters/ , transcripts/ , bundles/ , challenge-bundles/ , logs/ , _backups/ , _snapshot-*/ , llm-podcast-generator-review/generated/ , __pycache__/ ). scripts/ directory. docs/ (excluding EPISODE_MAP.json and EPISODE-MAP-SCHEMA.json ). admin/ markdown. Site repo c:\\code\\ggg . Out of scope (excluded as noise): html/ (generated site output). podcasts/audio/ (binary tagged mp3s, already updated). podcasts/_snapshot-pre-tagging-20260518/ , podcasts/_snapshot-pre-gpt55-20260518-164221/ , podcasts/_backups/ (snapshots). podcasts/logs/ , tmp-* files. podcasts/chapters/ , podcasts/transcripts/ , podcasts/bundles/ , podcasts/challenge-bundles/ (regenerable build outputs). podcasts/llm-podcast-generator-review/generated/ (regression run outputs). node_modules/ , .git/ , epub/ , learning-room/ (out of reorg scope). Counts shown below are raw hits from ripgrep against the patterns \\bep[0-9]{2}\\b , appendix-[a-z]+ , and cc-bonus-[a-e] . Group A: Live tooling that drives audio identity (MUST refactor) These files are part of the active audio/feed pipeline. Each one currently encodes the legacy ep##-slug / cc-NN-slug / cc-bonus-X-slug identity scheme and will need to switch to the canonical map. File Counts Role Refactor required podcasts/config/listening-order.json 58 ep, 5 bonus Defines the listener-facing order of all 79 items by slug, grouped by section headers ("Day 1: Issues...", "Day 2: ..."). Consumed by podcasts/lib/listening-plan.js , podcasts/generate-site.js , and the RSS feed builder via npm run build:podcast-site . Heavy. Replace with derivation from EPISODE_MAP.json track_number ordering. Section headers will need to be added as a new field on map entries (e.g. section_title ) or driven by learning_band groupings. Decision needed: keep section breaks, or flatten to single-stream feed. podcasts/build-bundles.js 77 appendix-, plus a large hardcoded const episodes = [...] array Generates NotebookLM source bundles for each episode. Carries the entire episode catalog inline ( slug , sources , concepts , crossRefs , prerequisites , duration ) and a SOURCE_ALIASES table that maps historical docs/*.md filenames to current ones. Consumed by npm run build:podcast-bundles and indirectly by generate-transcripts.bat . Heavy. The hardcoded episodes array is the parallel catalog of truth. Refactor to read from EPISODE_MAP.json and a separate bundle-config.json (concepts / crossRefs / prerequisites are bundle-only data not in the map; keep them, but key them by narration_id ). SOURCE_ALIASES is an orthogonal docs/* concern. podcasts/build-challenge-bundles.js 3 appendix- Companion to build-bundles.js for the 16 challenges and 5 bonus challenges. Same shape: inline catalog of slugs. Heavy. Same treatment as build-bundles.js . Key challenge bundles by challenge narration_id / topic_prefix=cc / topic_prefix=cc-bonus . podcasts/generate-draft-transcripts.js 1 ep## ref Generates the draft podcasts/scripts/**/*.txt files. Slug-aware: emits to podcasts/scripts/{chapters,challenges,appendices}/<slug>.txt . The three-bucket directory structure ( chapters/ , challenges/ , appendices/ ) is hardcoded. Medium. The three-bucket layout no longer matches the locked nine-band model (chapter, challenge, bonus, ref, git, tools, agents, sec, a11y). Decision needed: rename appendices/ to nine band-named subdirs, or keep flat. podcasts/tts/generate_episode.py 4 ep## TTS dispatcher invoked by generate-audio*.bat via python -m podcasts.tts.generate_audio --slug <slug> . Resolves slug to a script path under podcasts/scripts/{chapters,challenges,appendices}/<slug>.txt . Medium. Update path resolution if podcasts/scripts/ layout changes. Otherwise the script name (still ep##-... ) is the lookup key for the existing 79 mp3s, so this can stay slug-keyed until filenames are rotated in Stage 2. podcasts/tts/generate_all_kokoro.py 2 ep## Higher-level batch driver around generate_episode.py . Low. Same pattern as generate_episode.py . podcasts/listening_plan.py 1 ep## Reads podcasts/config/listening-order.json and emits a structured plan. Medium. Refactor once listening-order.json is replaced with map-derived ordering. podcasts/generate-site.js 1 ep## Builds podcasts/feed.xml and admin/PODCASTS.md . Consu" - }, { "id": "docs/_Sidebar.html", "title": "_Sidebar", @@ -479,18 +467,18 @@ "url": "docs/CHALLENGES.html", "body": "Challenge Hub Welcome to the Challenge Hub - your guide to all 16 core challenges and 5 bonus challenges. The challenges are the practice path for the course. Each one asks you to do a small piece of real GitHub work, leave evidence of what you did, and then close the issue so the next challenge can open. The goal is not speed. The goal is to build a contributor rhythm you can trust: orient yourself, make the move, verify the result, and ask for help with clear facts when something feels off. Prefer the exact issue-style flow? Open the consolidated issue walkthrough: Issue-Style Challenge Walkthrough . How Challenges Work Start in your private Learning Room repository, not in the public curriculum repository. Open the Issues tab, find the challenge issue assigned to you, and read the issue body before acting. Each issue explains the task, the evidence prompt, and any buddy check or automated check that applies. When a challenge asks for evidence, post it as a comment on that challenge issue. Evidence can be a link, a short reflection, the name of a branch, a pull request number, or a note about what you tried and what happened. After you post the evidence, close the challenge issue. The Student Progression Bot uses that closed issue as the signal to open the next challenge. Every challenge below includes a reference solution. Treat those files as worked examples, not answer keys. Your exact branch name, issue number, wording, or file count may differ. What matters is whether you practiced the skill and can explain the result. Day 1: You Belong Here (Challenges 1-9) Challenge 1: Find Your Way Around Chapters: Ch02-04 | Evidence: Comment This first challenge is about orientation. Before you edit anything, you learn how a repository is organized: where the Code tab lives, where Issues live, how the file tree behaves, and how the README gives a project its front door. What to do: Find the Code tab and count the files or folders in the repository root Open the Issues tab and identify at least one issue or confirm the tab exists Navigate to docs/welcome.md and read the opening paragraph Find the repository description and the rendered README Evidence to post: Describe what you found and name one navigation shortcut or screen reader technique that helped. Compare your result with the Challenge 1 solution reference when you want a second view of the same exploration path. Challenge 2: File Your First Issue Chapter: Ch05 | Evidence: Comment Issues are how maintainers turn observations into trackable work. In this challenge, you find a small TODO in the Learning Room and write an issue that another person could understand without being in the room with you. What to do: Open docs/welcome.md and search for TODO Create a new issue with a specific title Explain what needs to change, where it is, and why the change would help Evidence to post: Link to the issue you created and include one sentence about why your title is clear. If you want to compare tone and structure, read the Challenge 2 solution reference . Challenge 3: Join the Conversation Chapter: Ch05 | Evidence: Comment Open source is conversation as much as code. This challenge teaches you how to participate in an issue thread with an @mention, a reaction, and a comment that moves the work forward. What to do: Find your buddy's Challenge 2 issue or a facilitator-provided peer simulation issue Leave a meaningful comment with an @mention Add a reaction to the original issue or a helpful comment Evidence to post: Link to your comment and describe what made it useful, kind, or specific. The Challenge 3 solution reference shows one way to make a short comment feel genuinely collaborative. Challenge 4: Branch Out Chapter: Ch06 | Evidence: Comment A branch is a safe workspace. It lets you try a change without rewriting the main version of the project. In this challenge, you create your own branch and confirm that you know where your work will happen. What to do: Find the branch selector on the Code tab Create a branch named learn/YOUR-USERNAME from main Confirm the branch selector now names your branch Evidence to post: Write the branch name you created and how you confirmed you were on it. Use the Challenge 4 solution reference if you want to check your branch mental model. Challenge 5: Make Your Mark Chapter: Ch06 | Evidence: Comment This is your first small content change. You edit a file, replace a TODO with real text, and commit the change with a message that explains what happened. What to do: Switch to your learn/YOUR-USERNAME branch Edit docs/welcome.md to replace the TODO with useful content Write a commit message that explains the change in plain language Evidence to post: Share your commit message and the file you edited. For a worked example of a focused commit, compare with the Challenge 5 solution reference . Challenge 6: Open Your First Pull Request Chapter: Ch06 | Evidence: Comment A pull request is the conversation around a proposed change. It lets" }, - { - "id": "docs/11-vscode-interface.html", - "title": "VS Code: Interface and Setup", - "url": "docs/11-vscode-interface.html", - "body": "VS Code: Interface and Setup Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both this chapter and Chapter 12 . Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: VS Code Docs: User Interface | VS Code Docs: Accessibility Your Accessible Development Environment - The Foundation Day 2, Block 1 Material This chapter covers the VS Code interface: launching VS Code, signing in to GitHub, verifying Copilot is active, configuring screen reader mode, and navigating the Activity Bar, Status Bar, menus, settings, and keyboard shortcuts. For accessibility deep-dive topics (keyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech), see Chapter 12: VS Code Accessibility Deep Dive . Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material. Workshop Recommendation (Chapter 11) For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. Challenge count: 1 guided walkthrough Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue Pattern: open, configure, navigate, verify Chapter 11 Practice Set VS Code accessibility baseline - open VS Code (github.dev or desktop), enable screen reader mode, sign in to GitHub, verify Copilot status, and navigate core surfaces. Practice 11.1 Step-by-Step: VS Code Accessibility Baseline Goal: Confirm you can access VS Code (github.dev or desktop), enable screen reader support, sign in to GitHub, check Copilot status, and perform core navigation. Where you are working: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0. Estimated time: 10-15 minutes. Open your Learning Room repository on GitHub.com. Press . (the period key) on your keyboard. This launches github.dev - a full VS Code editor running in your browser. Wait a few seconds for it to load. Enable screen reader mode: Windows (NVDA/JAWS): Press Shift+Alt+F1 . You should hear an announcement confirming screen reader mode is on. Mac (VoiceOver): Screen reader mode is usually already optimized. If navigation feels wrong, open Command Palette ( Cmd+Shift+P ) and run Toggle Screen Reader Accessibility Mode . Open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E ). Your screen reader should announce the file tree. Navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Open the outline/symbols view with Ctrl+Shift+O (Mac: Cmd+Shift+O ). This shows all headings and sections in the current file - a key navigation tool for screen reader users. Open the Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type any command name (for example, Toggle Word Wrap ) and press Enter to run it. Press Escape to close without running. Check the Accounts button in the Activity Bar (bottom-left of the sidebar). If you are signed in, your screen reader announces your GitHub username. If not, activate it and sign in with GitHub. Check the Status Bar at the bottom of the window. Tab or arrow through it to find GitHub Copilot status. If Copilot is active, you hear an indicator showing it is ready. You are done when: You have successfully opened github.dev, enabled screen reader mode, signed in to GitHub, confirmed Copilot status, opened a file, viewed its outline, and run a command from the Command Palette. Completing Chapter 11: Submit Your Evidence Return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment: Chapter 11 completed: - Opened github.dev: yes / no - Screen reader mode enabled: yes / no - Signed in to GitHub: yes / no - Copilot status checked: yes / no - Opened file in Explorer: yes / no - Opened outline/symbols: yes / no - Opened Command Palette: yes / no If any step was "no," add a note explaining where you got stuck so the facilitator can help. Close the assigned setup or readiness issue when done. Expected Outcomes Student can launch and navigate github.dev or desktop VS Code. Student can enable screen reader mode and hear navigation announcements. Student has signed in to GitHub and can see their account status. Student has verified GitHub Copilot is active (or knows it requires desktop VS Code). Student can open core navigation surfaces (Explorer, Outline, Command Palette). Student is ready for VS Code-based contribution chapters (6-16). If You Get Stuck Nothing happens when you press . ? Make sure you are on the repository's main page (not inside an issue or PR). The . shortcut only works on repository code pages. Screen reader mode toggle did not announce anything? Open Command Palette ( Ctrl+Shift+P ) and type Screen Reader to find the toggle manually. Explorer panel is empty? VS Code may stil" - }, { "id": "docs/06-working-with-pull-requests.html", "title": "Working with Pull Requests", "url": "docs/06-working-with-pull-requests.html", "body": "Working with Pull Requests Listen to Episode 6: Working with Pull Requests - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix C: Markdown Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About pull requests | GitHub Accessibility Guide: Pull Requests | GitHub Accessibility Lab: CLI Guide Creating, Reviewing, and Merging Pull Requests with a Screen Reader See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader. Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at Using GitHub Pull Requests with a Screen Reader . This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. Screen reader note - New Files Changed Experience: This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Files Changed Experience" : If listed and the toggle announces "Pressed" (or "Disable" ) - already enabled, no action needed If listed but not Pressed (or "Enable" ) - activate the toggle to enable it If not listed at all - the feature has graduated to the standard interface; it is active automatically Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4 . Browse vs Focus Mode (NVDA): Use Browse Mode (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to Focus Mode ( NVDA+Space ) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout. Workshop Recommendation (Chapter 6) Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. Challenge count: 3 Time per challenge: under 10 minutes each Evidence: PR metadata, bot checks, and merged issue linkage Pattern: small change -> linked PR -> green checks Chapter 6 Challenge Set Create one small branch change - edit a practice file on a new branch. Open a linked PR - use the PR template and include Closes #XX . Pass required checks - respond to bot feedback until all required checks pass. CLI getting-started principles for pull request work For reliable PR workflows in the terminal: Check current branch before pushing ( git branch --show-current ). Keep PR scope small (one focused change per branch). Confirm issue linkage in plain text ( Closes #<number> ). Validate check status after each push ( gh pr checks ). Prefer documented command options only ( gh pr --help ). Branch guidance for Chapter 6: This is the first chapter where you edit files and create branches. Use one of these two paths: Web editor (recommended for beginners): When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it fix/yourname-issueXX (for example, fix/maria-issue42 ). Local Git (if you cloned in Block 0): Create a feature branch with git checkout -b fix/yourname-issueXX from main . See the "Local Git Alternative" section below for the full command sequence. Do not reuse your learn/<username> branch for this short exercise unless your facilitator tells you to. Chapter 6 works best with a short-lived feature branch such as fix/yourname-issueXX , because it teaches the pull request loop without mixing multiple challenges on one branch. Challenge 6.1 Step-by-Step: Create One Small Branch Change Goal: Edit one of the practice files and save your change on a new branch. Where you are working: your Learning Room repository on GitHub.com, using the web editor. Before you start: Open your assigned Chapter 6.1 challenge issue (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix. The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for. File What it contains" }, + { + "id": "docs/11-vscode-interface.html", + "title": "VS Code: Interface and Setup", + "url": "docs/11-vscode-interface.html", + "body": "VS Code: Interface and Setup Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both this chapter and Chapter 12 . Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: VS Code Docs: User Interface | VS Code Docs: Accessibility Your Accessible Development Environment - The Foundation Day 2, Block 1 Material This chapter covers the VS Code interface: launching VS Code, signing in to GitHub, verifying Copilot is active, configuring screen reader mode, and navigating the Activity Bar, Status Bar, menus, settings, and keyboard shortcuts. For accessibility deep-dive topics (keyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech), see Chapter 12: VS Code Accessibility Deep Dive . Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material. Workshop Recommendation (Chapter 11) For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. Challenge count: 1 guided walkthrough Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue Pattern: open, configure, navigate, verify Chapter 11 Practice Set VS Code accessibility baseline - open VS Code (github.dev or desktop), enable screen reader mode, sign in to GitHub, verify Copilot status, and navigate core surfaces. Practice 11.1 Step-by-Step: VS Code Accessibility Baseline Goal: Confirm you can access VS Code (github.dev or desktop), enable screen reader support, sign in to GitHub, check Copilot status, and perform core navigation. Where you are working: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0. Estimated time: 10-15 minutes. Open your Learning Room repository on GitHub.com. Press . (the period key) on your keyboard. This launches github.dev - a full VS Code editor running in your browser. Wait a few seconds for it to load. Enable screen reader mode: Windows (NVDA/JAWS): Press Shift+Alt+F1 . You should hear an announcement confirming screen reader mode is on. Mac (VoiceOver): Screen reader mode is usually already optimized. If navigation feels wrong, open Command Palette ( Cmd+Shift+P ) and run Toggle Screen Reader Accessibility Mode . Open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E ). Your screen reader should announce the file tree. Navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Open the outline/symbols view with Ctrl+Shift+O (Mac: Cmd+Shift+O ). This shows all headings and sections in the current file - a key navigation tool for screen reader users. Open the Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type any command name (for example, Toggle Word Wrap ) and press Enter to run it. Press Escape to close without running. Check the Accounts button in the Activity Bar (bottom-left of the sidebar). If you are signed in, your screen reader announces your GitHub username. If not, activate it and sign in with GitHub. Check the Status Bar at the bottom of the window. Tab or arrow through it to find GitHub Copilot status. If Copilot is active, you hear an indicator showing it is ready. You are done when: You have successfully opened github.dev, enabled screen reader mode, signed in to GitHub, confirmed Copilot status, opened a file, viewed its outline, and run a command from the Command Palette. Completing Chapter 11: Submit Your Evidence Return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment: Chapter 11 completed: - Opened github.dev: yes / no - Screen reader mode enabled: yes / no - Signed in to GitHub: yes / no - Copilot status checked: yes / no - Opened file in Explorer: yes / no - Opened outline/symbols: yes / no - Opened Command Palette: yes / no If any step was "no," add a note explaining where you got stuck so the facilitator can help. Close the assigned setup or readiness issue when done. Expected Outcomes Student can launch and navigate github.dev or desktop VS Code. Student can enable screen reader mode and hear navigation announcements. Student has signed in to GitHub and can see their account status. Student has verified GitHub Copilot is active (or knows it requires desktop VS Code). Student can open core navigation surfaces (Explorer, Outline, Command Palette). Student is ready for VS Code-based contribution chapters (6-16). If You Get Stuck Nothing happens when you press . ? Make sure you are on the repository's main page (not inside an issue or PR). The . shortcut only works on repository code pages. Screen reader mode toggle did not announce anything? Open Command Palette ( Ctrl+Shift+P ) and type Screen Reader to find the toggle manually. Explorer panel is empty? VS Code may stil" + }, { "id": "docs/appendix-z-github-skills.html", "title": "Appendix Z: GitHub Skills - Complete Course Catalog", @@ -2195,6 +2183,48 @@ "url": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", "body": "Learning Room End-to-End QA Runbook (Registration to Student Completion) Status note (2026-07): GitHub Classroom and the scripts/classroom/ PowerShell tooling were removed. Provisioning is the hybrid pipeline in .github/scripts/provisioning/ (workflow provision-learning-rooms.yml ), and peer simulation artifacts are seeded automatically by the Student Progression Bot in each learning room. Interpret scripts/classroom/*.ps1 steps below as the Student Progression Bot workflow dispatch (inputs start_challenge , assignee ); Seed-PeerSimulation.ps1 steps need no action because the bot seeds and self-repairs those artifacts. Use this runbook when you want one operational checklist that covers the full workflow: Registration intake and validation. GitHub Classroom deployment and assignment setup. Test account acceptance and repository seeding. Full student walkthrough of every challenge path. Release sign-off evidence for go-live. This runbook intentionally excludes podcast validation work. Everything else is in scope: registration flow, classroom deployment, assignment configuration, template readiness, student progression, PR validation, content validation, skills progression, autograder behavior, challenge completion tracking, and chapter-by-chapter curriculum review. Scope and Audience This runbook is for facilitators, QA leads, and admins who need to verify the complete workshop flow from administrator setup to student completion. Scope Boundaries In scope: Registration workflow behavior and classroom invitation handoff. Classroom assignment creation and autograding configuration. Learning Room automation workflows and facilitator scripts. Full curriculum walkthrough (chapters and appendices). Student challenge journey (1-16) and bonus challenge tracking (A-E). QA evidence capture, defect logging, and release sign-off. Out of scope: Podcast generation, podcast validation, and RSS audio feed checks. Canonical Source Files Used by This Runbook Table: Source files consolidated by this runbook Area Source file Registration entry page REGISTER.md Registration automation admin REGISTRATION-ADMIN.md Registration automation quickstart REGISTRATION-QUICKSTART.md Registration workflow logic .github/workflows/registration.yml Classroom deployment classroom/README.md Assignment copy and autograding setup admin/classroom/README.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Challenge definitions docs/CHALLENGES.md Student starting path docs/get-going.md Grading criteria classroom/grading-guide.md Release gate baseline GO-LIVE-QA-GUIDE.md Support hub operations SUPPORT_HUB_OPERATIONS.md Table: QA validation checkpoints for registration and classroom automation Table: Student journey checkpoints and expected artifacts Table: Label color and purpose for registration automation Table: Screen reader options for workshop setup Table: Accessibility improvements for screen reader users Required Accounts, Access, and Tools Complete this section before Phase 1. Facilitator admin account ( accesswatch ) with Owner access to both Community-Access and Community-Access-Classroom . Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization. Access to classroom.github.com while signed in as accesswatch . Access to repository settings for Community-Access/git-going-with-github (secrets and variables). Local clone of this repository with PowerShell available. GitHub CLI ( gh ) installed and authenticated as accesswatch for optional verification commands. Critical Precondition Gates (No-Go if any fail) Complete all items below before any cohort launch actions. Facilitator account accesswatch can access both organizations: Community-Access (the workshop and code repository organization) Community-Access-Classroom (the GitHub Classroom organization where student repos are created) accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com . Dedicated non-admin test student account exists and can accept invites. gh auth status succeeds for accesswatch in local terminal. Template repository exists and is set as template repo: Community-Access/learning-room-template Template repository Actions settings allow required automation behavior: Actions enabled GITHUB_TOKEN default workflow permissions include write where required Allow GitHub Actions to create and approve pull requests enabled Registration automation settings are correct when using registration-to-classroom handoff: Variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github Registration entry configuration exists and is valid: Issue form template workshop-registration.yml exists Required labels exist: registration , duplicate , waitlist While signed in as accesswatch , opening classroom.github.com shows the Communi" }, + { + "id": "admin/planning/DEPLOYMENT_ASSESSMENT.html", + "title": "Deployment Assessment: Hybrid Provisioning System", + "url": "admin/planning/DEPLOYMENT_ASSESSMENT.html", + "body": "Deployment Assessment: Hybrid Provisioning System Date: June 2, 2026 Status: READY FOR PRODUCTION (with caveat below) Summary The Hybrid provisioning system is architecturally sound, hardened, and production-ready . However, the end-to-end workflow has not yet been tested with real student enrollment . Recommendation: Run Phase 4 smoke test before admitting first cohort. Hardening Assessment by Component OK: GitHub App Configuration Status: HARDENED Why: Fine-grained permissions (least privilege), secrets stored in GitHub Actions only, PEM key never in code Risk: None identified Action: READY OK: Secrets & Variables Management Status: HARDENED Why: All three secrets (App ID, Installation ID, PEM) stored securely in GitHub repository Actions secrets; variables configured correctly Risk: None identified Action: READY OK: Infrastructure Code (Provisioning Scripts) Status: HARDENED Why: Idempotent: Re-running is safe (already-exists vs. created state) Self-healing: Missing students auto-provisioned on next run Deterministic: Uses GitHub API signals, not external state Auditable: All history in provisioning-log.json and git Risk: None identified Action: READY OK: Documentation Updates Status: COMPLETE What: 15+ files updated, 37+ files deleted, HTML regenerated on both sites Coverage: Student-facing, facilitator, operator all covered Risk: None identified Action: READY OK: Public Site Deployments Status: COMPLETE Coverage: community-access.org/git-going-with-github (auto via GitHub Pages) lp.csedesigns.com/ggg (manual via rsync + Caddy reload) Verification: Both sites live and tested (404s work, navigation intact) Risk: None identified Action: READY Warning: End-to-End Student Workflow (NOT YET TESTED) Status: UNTESTED What's missing: Admin roster repo creation Smoke test with test student account Verification that provision workflow runs end-to-end Verification that invitation email sent to test account Verification that student can accept invite and access repo Risk: Medium-logical gaps possible, though architecture is solid Action: REQUIRED-Run Phase 4 before admitting real students What Has Been Tested OK: Automation tests: 78/78 passing (was 98, reduced after removing Classroom tests) OK: Provisioning tests: 55/55 passing OK: HTML regeneration: 393 markdown files -> HTML OK: Site deployments: Both production sites live OK: GitHub App creation: Properly configured with correct permissions OK: Secrets storage: All three values stored securely What Has NOT Been Tested Missing: End-to-end provisioning flow with a real test student Enrollment form submission Issue creation in test account Automation comment with learning room link Provisioning workflow execution Private repo creation and invitation Student repo readiness for challenges Failsafe Mechanisms Mechanism How It Works When It Helps Idempotence Re-running workflow is safe; state tracked in roster.json If automation fails, re-run fixes it Self-healing Missing students auto-provisioned on next run If student missed by error, they're caught on retry Audit Trail provisioning-log.json records every action Troubleshooting, rollback, verification Source of Truth roster.json is canonical; all state derives from it Repo can be recreated, roster is immutable Least Privilege GitHub App has minimal permissions Limits blast radius if credentials compromised Secrets in Actions PEM never stored in code or logs Prevents accidental exposure Deterministic Signals Progress tracked via GitHub events No hidden external dependencies Recommendations Before Go-Live MUST DO (Blocking) Run Phase 4 Smoke Test Create test admin roster repo Add one test learner (e.g., a throwaway GitHub account you control) Trigger provisioning workflow with dry-run first Trigger provisioning workflow without dry-run Verify: Private repo created Invitation sent to test account Roster entry updated to "provisioned" provisioning-log.json records "created" Run again; verify log records "already-exists" Test account accepts invite; repo is ready for challenges Verify End-to-End Student Flow Submit enrollment form as test student Verify issue created in your account Reply ack to issue Verify automation comment posts learning room link Verify you receive GitHub invitation Accept invitation; verify repo has challenges SHOULD DO (Recommended, not blocking) Verify Flask Companion (Optional) If deploying companion for web enrollment, test locally first See Phase 5 of deployment guide Document Rollback Plan If provisioning fails, how to revert? If student repo corrupted, how to re-provision? Document in runbook Test with Multiple Students Once Phase 4 passes, add 3-5 test students to roster Verify all get provisioned correctly Verify no duplicates or conflicts NICE TO HAVE (After launch) Monitor first week of production: Track provisioning success rate Log any failures to support channel Verify no duplicate repos Verify all students receive invitations Set up alert" + }, + { + "id": "admin/planning/REORG-PLAN.html", + "title": "Git Going with GitHub - Reorganization Master Plan", + "url": "admin/planning/REORG-PLAN.html", + "body": "Git Going with GitHub - Reorganization Master Plan Living document. Update checkboxes as work completes. Two repos in scope: Content repo: c:\\code\\git-going-with-github (Community-Access/git-going-with-github) - book, scripts, audio source of truth. Site repo: c:\\code\\ggg - lp.csedesigns.com static site, episode HTML, RSS feed, media folder. Last updated: 2026-05-18. Launch posture Greenfield. No published audience yet, no subscribers, no external inbound links worth preserving. Treat the entire reorg as preparation for a clean first launch. Consequences: No 301 redirects, no moved.html , no Caddyfile redirect rules. Old paths simply disappear at cutover. RSS <guid> values can change freely until we publicly announce the feed. We still mint stable UUIDs now so we never have to break GUIDs once we do announce. No SEO carryover. New URLs are the only URLs. No subscriber re-download risk. Identity model The architecture rests on a two-axis identity model in docs/EPISODE_MAP.json : Identity axis (immutable after launch). uuid and filename are stable forever. They appear in mp3 ID3 frames, RSS <guid> , and enclosure URLs. Ordering axis (freely reassignable). track_number and pairs_with_uuid drive the podcast feed and the website learning view. Rewriting them is a map edit plus a regenerate; no audio is touched, no filename is renamed. This separation is why insertion, interleaving, and topic expansion all become map edits rather than cascade renames. Filename scheme Filename pattern: <topic-prefix>-<NN>[-<letter>]-<slug>.mp3 Group Topic prefix learning_band Example Chapter ch chapter ch-05-collaboration.mp3 Code challenge cc challenge cc-05-fork-and-clone.mp3 Bonus challenge cc-bonus bonus cc-bonus-a-improve-agent.mp3 Reference appendix ref reference ref-01-glossary.mp3 Git appendix git git git-03-security.mp3 Tools appendix tools tools tools-01-vscode-reference.mp3 Agents appendix agents agents agents-01-copilot-reference.mp3 Security appendix sec sec sec-01-branch-protection.mp3 Ops appendix ops ops ops-01-actions-and-workflows.mp3 Reach appendix reach reach reach-01-community-and-social.mp3 Rules: NN is zero-padded two-digit within-topic. ch-05 is the 6th chapter (00-indexed) regardless of feed position. Optional letter suffix ( ch-05a- , ch-05b- ) is reserved for mid-sequence insertion where the new content is logically part of the adjacent chapter. Slugs are lowercase ASCII kebab-case. No double dashes. No trailing dash. Max 60 chars. Within-topic numbers are append-only. Deleted entries leave the number reserved (entry stays in map with archived: true ). Two digits is the cap. If a single topic exceeds 99 entries, that is a curriculum signal to split the topic, not to extend numbering. Track number track_number is a 1-based integer. Unique across the entire map. Contiguous after every regenerate-all run (no gaps). The feed is sorted strictly by track_number . ID3 TRCK frame is written from track_number . Listeners see "Episode N of M" by track number; titles still carry the within-topic identity ("Chapter 5: Collaboration"). pairs_with_uuid Optional. Points from child (challenge, bonus, appendix) to parent (usually a chapter). Used by regenerate-all to compute interleaved track numbers automatically: parent track N, then all children of N in their pair_order , then parent track N+1. Must point to an existing UUID. Cannot cycle. Lint-enforced. A parent can have many children. A child has at most one parent. Narration-vs-display contract Within-topic number ( ch-05 ) is the curriculum truth spoken in narration. It never changes after launch. Show notes, ID3 titles, site headings all use it. Track number is the feed truth for podcast apps. It can shift freely; nothing in the recorded audio refers to it. This is why interleaving challenges with chapters is safe: the narration in cc-05 calling itself "Challenge 5" remains correct regardless of whether it plays at track 6 (paired with chapter 5) or track 30 (challenges grouped at end). Guiding principles Audio is sacred. Once an mp3 is rendered, tagged, and chaptered, we do not re-render it to change a number or a name. One canonical map, many surfaces. docs/EPISODE_MAP.json is the single source of truth. Every rename, feed regen, ID3 retag, site build, and deploy reads from it. No tool hardcodes a slug or number. All tooling conforms to the map. Tools that currently hardcode slugs get refactored in Stage 2 before they touch anything in Stage 3. Stable UUIDs from day one. Each episode gets a permanent UUID stored in the map, in its ID3 TXXX:UUID frame, and in its RSS <guid isPermaLink="false"> . Decoupled identity and ordering. Filename is identity. track_number is display. Never confuse the two. Clean cutover on the server. Replace scp -r with rsync --delete plus pre-deploy tarball backup. Validate at every gate. Schema check, link check, RSS validate, mp3 tag verify, server-side " + }, + { + "id": "admin/planning/REVIEW-2026-07-02.html", + "title": "Operations Review: Provisioning Failures and Workshop Model Robustness", + "url": "admin/planning/REVIEW-2026-07-02.html", + "body": "Operations Review: Provisioning Failures and Workshop Model Robustness Date: July 2, 2026 Scope: GitHub Actions failure analysis, provisioning subsystem, registration pipeline, repo hygiene. Implementation status (July 2, 2026): everything in sections 3, 4.1-4.4, and 6 that is code has been implemented (installation-ID auto-discovery, watchdog alert issue, work-free early exit, event-driven provisioning dispatch, weekly credentials health check, preflight assertions, intake-to-roster sync, Classroom link removal, [REGISTER] private intake plus redaction, authoritative-sources gate fixes, scratch cleanup). The remaining manual step is section 2: install the GitHub App on the Community-Access organization. Template drift (4.5) is still open. 1. Headline Finding: The Provisioning GitHub App Is Not Installed on the Org The "Provision Learning Rooms" workflow has failed on every real run since it was deployed. Verified numbers from the GitHub API: 280 total runs of provision-learning-rooms.yml . Exactly 1 success ever (June 2, 2026, 20:16 UTC) - and that run was a dry run, which skips authentication entirely. Every non-dry run, including roughly 12 scheduled runs per day for the past 30 days, fails with: Failed to mint installation token (HTTP 404) Root cause, confirmed directly: GET /orgs/Community-Access/installations shows exactly one GitHub App installed on the org - digitalocean (app id 64711). The provisioning App was created (App ID and PEM are stored as secrets) but was never installed on the Community-Access organization. There is no installation to mint a token against, so the token mint returns 404 no matter what PROVISIONING_APP_INSTALLATION_ID contains. Consequences, also confirmed: The private roster ( git-going-with-github-administration/roster.json ) has 2 learners in provision_state: pending - unchanged since June 2. Two registered people have been waiting a month for learning rooms that were never created. The admin repo has had no roster commits since June 2 because the workflow dies before the commit step. This is precisely the failure class SPEC.md's golden principle warns about ("never let a single point of failure hold a cohort hostage") and violates the section 7.2b invariant "any failure visible to a human before a learner notices." The watchdog the spec calls for does not exist. Note on the local working-tree changes: the uncommitted edits to github-app-auth.js (normalize URL-form installation IDs, better 404 hint) are good hardening and all 58 provisioning tests pass, but they will not fix production. No installation ID is valid until the App is installed. 2. Immediate Fix (Operator Steps, ~15 Minutes) Install the App: GitHub -> Organization settings -> Developer settings -> GitHub Apps -> your provisioning App -> Install App -> Community-Access. Because the App must create new repositories, install it org-wide (repository creation cannot be granted through a selected-repositories installation). Capture the installation ID from the post-install URL ( .../settings/installations/<id> ) or from GET /app/installations using an App JWT. Update the PROVISIONING_APP_INSTALLATION_ID secret (it lives in the provisioning environment, not repo-level secrets). Run the workflow manually with dry_run: true (expect: "2 learner(s) would be provisioned"), then run it for real. Verify: two new learning-room-* repos, invitations sent, roster entries flipped to provisioned , provisioning-log.json committed to the admin repo. 3. Make the Failure Class Impossible: Code Changes These are ordered by payoff. 3.1 Auto-discover the installation ID Stop storing the installation ID as a secret at all. With an App JWT you can call GET /app/installations and select the installation whose account matches PROVISIONING_STUDENT_OWNER . Add this as the fallback (or the default) in github-app-auth.js / provision-cli.js . This removes an entire class of copy-paste misconfiguration and survives App re-installation (installation IDs change when an App is uninstalled and reinstalled). Alternative for the workflow path: the official actions/create-github-app-token action needs only app-id and private-key and resolves the installation from the repo owner automatically. It keeps the zero-npm-dependency property of the repo since it runs as an action, and the CLI keeps the hand-rolled path for local use. 3.2 Alert on failure - implement the spec's watchdog Thirty days of silent failure proves the need. Add a final if: failure() step to provision-learning-rooms.yml that creates or updates a pinned, labeled issue (for example provisioning-broken ) in this repo, including the error line from the log. Close it automatically on the next success. Requires issues: write on this workflow only. 3.3 Skip work-free runs Most of the 280 failed runs had zero learners to provision. Read the roster first; if there are no pending / failed entries, exit success before minting" + }, + { + "id": "admin/planning/SHIP-CHECKLIST.html", + "title": "Stage 3 Cutover - Ship Checklist", + "url": "admin/planning/SHIP-CHECKLIST.html", + "body": "Stage 3 Cutover - Ship Checklist Generated by the Stage 3 pre-flight on the current main branch. Everything below has been dry-run verified . The actual cutover is one explicit go away. Pre-cutover state (verified) Stage 2 gate: 5/5 PASS ( scripts/run-stage2-gate.ps1 ). Map: docs/EPISODE_MAP.json validates against schema 1.0.0; 79 episodes (58 ep + 16 cc + 5 cc-bonus); UUIDs stable; track_number drives ordering. Audio inventory: 79 mp3 files present in podcasts/audio/kokoro-am_liam-af_jessica/ ; 58 need rename, 21 already in new scheme. Working tree dirty: 522 uncommitted files from prior Stage 1-2 work. Recommend committing or stashing these before Stage 3. Built tools (this session) Step Tool Status 3.1 podcasts/tools/dry_run_rename.py Dry-run PASS 3.2 podcasts/tools/rename_audio.py (--apply, --finalize-map, --chapters-dir) Preview PASS, preflight clean 3.5 scripts/rewrite-cross-links.ps1 (-Apply) Dry-run PASS, 8 files / 509 reps Dry-run summary Stage 3 . 1 - rename plan 58 mp3 renames (e.g. ch- 00 -welcome.mp3 -> ch- 00 -welcome.mp3) 21 no-op (current_filename == filename) CSV : tmp-proposed-rename.csv Stage 3 . 5 - cross-link rewrite (with .history, snapshots, transcripts excluded) 8 files, 509 replacements Largest : admin\\PODCASTS.md ( 174 ), quality_triage_report.csv/.md ( 224 total), listening -order.json ( 58 ), validate-report.json ( 44 ) Report : tmp-crosslink-rewrite-report.txt Fire sequence (locally reversible up through step 5) Run these commands in order. Each step is a separate commit so any single step can be reverted in isolation. 0. Clean slate cd c:\\code\\git -going-with-github git checkout -b cutover -20260518 git add -A git commit -m "Pre-cutover state: Stage 1-2 work product + Stage 3 tooling" 1. Rename audio + parallel chapter JSON (Stage 3.2) python podcasts\\tools\\rename_audio.py --apply --finalize-map git add -A git commit -m "Stage 3.2: rename audio to topic-prefixed filenames + finalize map" Effect: 58 mp3 files renamed, 58 chapter JSON files renamed, map's current_filename / current_slug updated to match filename . 2. Retag ID3 (Stage 3.3) python podcasts\\tools\\tag_id3.py python podcasts\\tools\\verify_id3.py git add -A git commit -m "Stage 3.3: retag ID3 frames on renamed audio" Effect: TIT2, TRCK, TXXX:TOPIC updated; CHAP/CTOC untouched. Idempotent. 3. Cross-link rewrite (Stage 3.5) powershell -NoProfile -ExecutionPolicy Bypass -File scripts\\re write-cross -links .ps1 -Repo c:\\code\\git -going-with-github -Apply git add -A git commit -m "Stage 3.5: rewrite cross-links to new filename scheme" Effect: 509 replacements across 8 files (listening-order.json, PODCASTS.md, quality_triage_report.*, validate-report.json, etc.). 4. Re-run Stage 2 gate powershell -NoProfile -ExecutionPolicy Bypass -File scripts\\run -stage2-gate .ps1 Must return 5/5 PASS. If not, halt and investigate. 5. Mirror to deploy repo (Stage 3.6) robocopy podcasts\\audio\\kokoro -am_liam-af_jessica c:\\code\\ggg\\site\\media *.mp3 /MIR Confirm file counts match: (Get-ChildItem c:\\code\\ggg\\site\\media\\*.mp3).Count . 6. Regenerate feed + site (Stages 3.7 - 3.8) cd c:\\code\\ggg node generator\\generate -site .js node generator\\validate -feed .js Spot-check c:\\code\\ggg\\site\\feed.xml . Confirm <enclosure url> points to the new filenames. (Cover art piece intentionally omitted per project constraint.) --- IRREVERSIBLE LINE --- Steps below affect remote systems. Confirm step 6 looks correct before proceeding. 7. Deploy (Stage 3.9) c:\\code\\ggg\\ deploy-ggg .ps1 -Backup c:\\code\\ggg\\ deploy-ggg .ps1 -DryRun # review the rsync delta c:\\code\\ggg\\ deploy-ggg .ps1 # live 8. Smoke-test remote curl -I https://lp.csedesigns.com/ggg/feed.xml -> 200 Three sample enclosure URLs -> 200 Three episode pages -> 200 9. Tag (Stage 3.10) cd c:\\code\\git -going-with-github git checkout main git merge --no-ff cutover -20260518 git tag v2 -renumbered-20260518 git push origin main --tags cd c:\\code\\ggg git tag v2 -renumbered-20260518 git push origin main --tags Rollback (steps 1-5) Any of steps 1-5 can be reverted with: git reset --hard HEAD~ 1 For audio rename specifically, tmp-rename-audit.log records every old -> new pair so a reverse rename script can be reconstructed. What's intentionally excluded Cover art ( <itunes:image> in feed) - skipped per project constraint. .history/ files - VS Code Local History snapshots, not rewritten. podcasts/_snapshot-pre-*/ - intentional historical reference. podcasts/transcripts/ - workflow artifacts that key off old slug names in their own filename scheme; do not need rewrite for cutover. Notes All 522 currently-uncommitted files come from prior Stage 1-2 sessions. They have been validated by the Stage 2.8 gate. Committing them in step 0 is the cleanest restore point. The cutover branch should be cutover-20260518 per the REORG-PLAN.md specification. Authoritative Sources Use these official references when you need the current source of truth for t" + }, + { + "id": "admin/planning/SITE-IA.html", + "title": "Site Information Architecture (Stage 1.3)", + "url": "admin/planning/SITE-IA.html", + "body": "Site Information Architecture (Stage 1.3) Status: draft for Stage 1.5 gate approval. Authority: this doc, together with EPISODE_MAP.json , governs every URL emitted by the site generator in c:\\code\\ggg\\generator\\ . Principles Identity-first URLs. Every per-episode URL is keyed on the immutable map filename (without the .mp3 extension). When filename is locked, the URL is locked. track_number is never in a URL. One landing page per learning band. Nine top-level navigation routes, one per band. No "appendices" umbrella. Audio and learning views. Listeners can browse by feed order (chronological / track) or by curriculum (paired view). Both views resolve to the same per-episode pages. No legacy redirects. Greenfield launch. Old paths ( ep##-slug.html , appendix-x-*.html , anything with cc-NN- only) simply do not exist on the new site. All pages are static. No client-side routing. Every URL serves a real file from c:\\code\\ggg\\site\\ . Accessibility is non-negotiable. Semantic HTML, single H1 per page, named landmarks, keyboard-reachable controls, captions/transcripts linked from every episode page. URL map All URLs are rooted at https://lp.csedesigns.com/ggg/ . Local site build mirrors this layout under c:\\code\\ggg\\site\\ . URL Source Description / generator/templates/home.html + map Homepage. Curriculum view by default. Toggle for feed view. Hero, what-this-is, "Start here" CTA pointing at /chapters/ch-00-welcome/ . /learn/ generator/templates/learn.html + map Full curriculum-ordered view: chapters 00..22 interleaved with their paired challenges, bonus block, then appendix bands in order ref / git / tools / agents / sec / a11y. Same ordering as track_number . /feed-order/ generator/templates/feed-order.html + map Strict track_number list 1..79 with no grouping. Direct mirror of the RSS feed. /feed.xml generator/generate-feed.js + map Public RSS 2.0 + iTunes podcast feed. /chapters/ generator/templates/band-landing.html + map filter learning_band=chapter Lists 23 chapters in topic_number order. /challenges/ same template, filter learning_band=challenge Lists 16 code challenges in topic_number order. /bonus/ same template, filter learning_band=bonus Lists 5 bonus challenges in topic_number order. /ref/ same template, filter learning_band=reference Lists 6 reference appendices. /git/ same template, filter learning_band=git Lists 5 git appendices. /tools/ same template, filter learning_band=tools Lists 12 tools appendices. /agents/ same template, filter learning_band=agents Lists 6 agents appendices. /sec/ same template, filter learning_band=sec Lists 2 security appendices. /a11y/ same template, filter learning_band=a11y Lists 4 accessibility appendices. /episodes/<filename-without-ext>/ generator/templates/episode.html + map entry Per-episode page. One per map entry. 79 pages total. /media/<filename>.mp3 c:\\code\\ggg\\site\\media\\ Raw enclosure URL. Used by <enclosure> and <audio src> . Direct download supported. /about/ , /contributors/ , /contact/ , /license/ static templates Standard site furniture. No map dependency. /search/ generator/templates/search.html + site/search-index.json Client-side search across episode titles, summaries, and chapter marker titles. Built from map. /sitemap.xml generator/generate-sitemap.js + map XML sitemap including all 79 episode pages and all band landings. /robots.txt static Standard. /opml.xml generator/generate-opml.js + map OPML export of the feed. Stage 5 polish; can ship empty in Stage 3. Per-episode URL examples Map entry URL ch-00-welcome.mp3 /episodes/ch-00-welcome/ ch-05-collaboration.mp3 /episodes/ch-05-collaboration/ cc-05-make-your-mark.mp3 /episodes/cc-05-make-your-mark/ cc-bonus-d-notifications.mp3 /episodes/cc-bonus-d-notifications/ ref-01-glossary.mp3 /episodes/ref-01-glossary/ a11y-04-document-developer-tools.mp3 /episodes/a11y-04-document-developer-tools/ Page-level layout Homepage / Sections, top to bottom: Skip link to main content (visually hidden until focus). Site header with primary nav (chapters, challenges, appendices dropdown opening to the six appendix-band routes, search). Hero: show title, tagline, single CTA "Start with Chapter 00: Welcome" linking to /episodes/ch-00-welcome/ . "How to use this site" three-card row: Learn (curriculum view), Listen (feed view), Reference (band landings). Latest two map entries by track_number (NOT by date) as a "Continue where the curriculum begins" strip. Newsletter / register CTA. No-op for now. Site footer with license, repo links, accessibility statement. No date carousel. No "recent episodes" widget. Order is curriculum-driven, not chronological. Curriculum view /learn/ Linear ordered list of all 79 entries by track_number . Visual grouping: chapter+challenge pairs share a card (the chapter on top, the challenge nested below in a details / summary block), bonuses get their own card-band, each appendix band gets a heading. Each card" + }, + { + "id": "admin/planning/TOOLING-INVENTORY.html", + "title": "Tooling Inventory (Stage 1.4)", + "url": "admin/planning/TOOLING-INVENTORY.html", + "body": "Tooling Inventory (Stage 1.4) Purpose: identify every source file in the content repo and the deploy/site repo that hardcodes an episode identifier, an appendix letter, or an audio slug, so Stage 1.3 (Site IA) and Stage 2+ (refactor) can be scoped accurately. The canonical identity source is now docs/EPISODE_MAP.json . Every locked field below should ultimately resolve through that map by narration_id , filename , or topic_prefix + topic_number . Scope of this inventory: Source-controlled tooling and authoring files in c:\\code\\git-going-with-github . Top-level scripts ( generate-*.bat , build-rss-feed.bat , validate-rss-feed.bat , generate-podcast-scripts.py ). podcasts/ tooling and configuration (excluding audio/ , chapters/ , transcripts/ , bundles/ , challenge-bundles/ , logs/ , _backups/ , _snapshot-*/ , llm-podcast-generator-review/generated/ , __pycache__/ ). scripts/ directory. docs/ (excluding EPISODE_MAP.json and EPISODE-MAP-SCHEMA.json ). admin/ markdown. Site repo c:\\code\\ggg . Out of scope (excluded as noise): html/ (generated site output). podcasts/audio/ (binary tagged mp3s, already updated). podcasts/_snapshot-pre-tagging-20260518/ , podcasts/_snapshot-pre-gpt55-20260518-164221/ , podcasts/_backups/ (snapshots). podcasts/logs/ , tmp-* files. podcasts/chapters/ , podcasts/transcripts/ , podcasts/bundles/ , podcasts/challenge-bundles/ (regenerable build outputs). podcasts/llm-podcast-generator-review/generated/ (regression run outputs). node_modules/ , .git/ , epub/ , learning-room/ (out of reorg scope). Counts shown below are raw hits from ripgrep against the patterns \\bep[0-9]{2}\\b , appendix-[a-z]+ , and cc-bonus-[a-e] . Group A: Live tooling that drives audio identity (MUST refactor) These files are part of the active audio/feed pipeline. Each one currently encodes the legacy ep##-slug / cc-NN-slug / cc-bonus-X-slug identity scheme and will need to switch to the canonical map. File Counts Role Refactor required podcasts/config/listening-order.json 58 ep, 5 bonus Defines the listener-facing order of all 79 items by slug, grouped by section headers ("Day 1: Issues...", "Day 2: ..."). Consumed by podcasts/lib/listening-plan.js , podcasts/generate-site.js , and the RSS feed builder via npm run build:podcast-site . Heavy. Replace with derivation from EPISODE_MAP.json track_number ordering. Section headers will need to be added as a new field on map entries (e.g. section_title ) or driven by learning_band groupings. Decision needed: keep section breaks, or flatten to single-stream feed. podcasts/build-bundles.js 77 appendix-, plus a large hardcoded const episodes = [...] array Generates NotebookLM source bundles for each episode. Carries the entire episode catalog inline ( slug , sources , concepts , crossRefs , prerequisites , duration ) and a SOURCE_ALIASES table that maps historical docs/*.md filenames to current ones. Consumed by npm run build:podcast-bundles and indirectly by generate-transcripts.bat . Heavy. The hardcoded episodes array is the parallel catalog of truth. Refactor to read from EPISODE_MAP.json and a separate bundle-config.json (concepts / crossRefs / prerequisites are bundle-only data not in the map; keep them, but key them by narration_id ). SOURCE_ALIASES is an orthogonal docs/* concern. podcasts/build-challenge-bundles.js 3 appendix- Companion to build-bundles.js for the 16 challenges and 5 bonus challenges. Same shape: inline catalog of slugs. Heavy. Same treatment as build-bundles.js . Key challenge bundles by challenge narration_id / topic_prefix=cc / topic_prefix=cc-bonus . podcasts/generate-draft-transcripts.js 1 ep## ref Generates the draft podcasts/scripts/**/*.txt files. Slug-aware: emits to podcasts/scripts/{chapters,challenges,appendices}/<slug>.txt . The three-bucket directory structure ( chapters/ , challenges/ , appendices/ ) is hardcoded. Medium. The three-bucket layout no longer matches the locked nine-band model (chapter, challenge, bonus, ref, git, tools, agents, sec, a11y). Decision needed: rename appendices/ to nine band-named subdirs, or keep flat. podcasts/tts/generate_episode.py 4 ep## TTS dispatcher invoked by generate-audio*.bat via python -m podcasts.tts.generate_audio --slug <slug> . Resolves slug to a script path under podcasts/scripts/{chapters,challenges,appendices}/<slug>.txt . Medium. Update path resolution if podcasts/scripts/ layout changes. Otherwise the script name (still ep##-... ) is the lookup key for the existing 79 mp3s, so this can stay slug-keyed until filenames are rotated in Stage 2. podcasts/tts/generate_all_kokoro.py 2 ep## Higher-level batch driver around generate_episode.py . Low. Same pattern as generate_episode.py . podcasts/listening_plan.py 1 ep## Reads podcasts/config/listening-order.json and emits a structured plan. Medium. Refactor once listening-order.json is replaced with map-derived ordering. podcasts/generate-site.js 1 ep## Builds podcasts/feed.xml and admin/PODCASTS.md . Consu" + }, + { + "id": "admin/planning/index.html", + "title": "Planning Archive and Initiative Status", + "url": "admin/planning/index.html", + "body": "Planning Archive and Initiative Status One consolidated index of the project's planning documents. Each initiative below has a status, a summary of what shipped, and a pointer to the full original document (preserved unedited in this folder). New planning documents belong here, not in the repository root. How to read this folder Shipped means the feature is live and the planning document is retained only as a historical record and decision log. In flight means the plan still has open work; the document remains the working checklist. Durable, current documentation always lives in the operational docs (SPEC.md, admin/ guides, .github/README.md), never in this archive. Initiative status Initiative Status Document Hybrid provisioning deployment Shipped (July 2026) DEPLOYMENT_ASSESSMENT.md Provisioning failure review and hardening Shipped (July 2026) REVIEW-2026-07-02.md Podcast site reorganization (content repo to lp.csedesigns.com) In flight REORG-PLAN.md Stage 3 cutover checklist for the reorganization In flight (gated on REORG-PLAN) SHIP-CHECKLIST.md Site information architecture (Stage 1.3) Approved input to REORG-PLAN SITE-IA.md Tooling inventory (Stage 1.4) Complete input to REORG-PLAN TOOLING-INVENTORY.md Shipped initiative summaries Hybrid provisioning (replaces GitHub Classroom) Planned in DEPLOYMENT_ASSESSMENT.md (June 2, 2026), hardened after the July 2 incident review. Live since July 2026: the provision-learning-rooms.yml workflow runs .github/scripts/provisioning/ (pure-orchestration core, injected GitHub client, serial with backoff, idempotent), creates each learner's private room from learning-room-template , invites the learner, and seeds Challenge 1. The algorithm is specified in SPEC.md section 7.2b. Key lesson encoded from the review: no READY claim without a green run ID; the smoke test is the gate. Provisioning failure review (July 2, 2026) Root-caused the provisioning credential failures, added the health-check workflow and alerting, closed the registration-to-roster gap, and tolerated pending collaborator invitations. All action items in its sections 3, 4.1-4.4, and 6 were implemented; see the document for the incident narrative and lessons. Peer simulation seeding (July 4, 2026, no standalone plan document) The Classroom removal deleted Seed-PeerSimulation.ps1 without a replacement, leaving every learning room without the peer-simulation issue and PR that Challenges 1-13 reference (support issue 58). The Student Progression Bot now seeds and self-repairs those artifacts automatically (PR 238), Challenges 10-11 were repointed at the learner's own room (PR 239), and all active rooms were remediated in place. Removed in the July 2026 cleanup datetime (empty stray file at the root) GitHub Learning Room.docx (February draft, superseded by docs/) COMING_SOON.md (pre-launch teaser, workshop is live) github/index.html (redirect stub never served; GitHub Pages deploys only the html/ artifact) Authoritative Sources Use these official references when you need the current source of truth for facts in this file. GitHub Actions documentation - workflow behavior referenced by the shipped initiatives GitHub Pages documentation - deployment model that made the root redirect stub dead weight GitHub REST API documentation - provisioning and seeding API calls Section-Level Source Map Use this map to verify facts for each major section in this file. Initiative status: the linked planning documents in this folder Hybrid provisioning: SPEC.md section 7.2b, DEPLOYMENT_ASSESSMENT.md Provisioning failure review: REVIEW-2026-07-02.md Peer simulation seeding: .github/scripts/challenge-progression.js in learning-room/ , PRs 238 and 239 Removed in cleanup: git history (commit for this change)" + }, { "id": "classroom/assignment-issue-template.html", "title": "Assignment Issue Template Reference", @@ -2249,12 +2279,6 @@ "url": "BATCH.html", "body": "Batch Command Reference This file documents the cmd.exe batch files in the repo root for podcast operations. All batch files change directory to the repo root automatically, so they work correctly from any location. Workflow order Run operations in this sequence for a full podcast build from scratch: generate-transcripts.bat - write episode scripts from the catalog generate-audio.bat - synthesise MP3 audio from those scripts build-rss-feed.bat - generate the RSS feed and podcast listing validate-rss-feed.bat - verify the feed is valid before publishing generate-transcripts.bat Validates the podcast catalog, builds episode and challenge bundles, then writes all episode and challenge coach scripts to podcasts\\scripts\\ . generate -transcripts .bat Output files: podcasts\\scripts\\ep*.txt and podcasts\\scripts\\cc-*.txt Note: transcript generation always rebuilds all episodes from the catalog. Range selection is not supported at this stage. Run this step whenever the catalog or source docs change. generate-audio.bat Synthesises MP3 audio for all episodes or a specific numbered range. Audio format, voice model, pitch, and speed settings are read from podcasts\\tts\\voice-config.ini . The script echoes each episode name and index as it is processed. ffmpeg is required for MP3 output and is located automatically from the machine PATH, including after a fresh winget install. generate -audio .bat generate all 75 episodes generate -audio .bat 5 generate episodes 5 and above generate -audio .bat 5 10 generate episodes 5 through 10 Output files: podcasts\\audio\\*.mp3 To change audio format, voice pitch, or speed, edit podcasts\\tts\\voice-config.ini before running this command. build-rss-feed.bat Generates the RSS 2.0 / iTunes-compatible podcast feed and the admin podcast listing. Reads MP3 file sizes from podcasts\\audio\\ and episode metadata from the catalog. build -rss-feed.bat Output files: podcasts\\feed.xml - the RSS feed for podcast directories admin\\PODCASTS.md - human-readable episode listing Run this command after generate-audio.bat completes so that enclosure lengths reflect the final MP3 file sizes. validate-rss-feed.bat Runs local RSS 2.0 and iTunes compliance checks on podcasts\\feed.xml . validate -rss-feed.bat Checks performed: Required channel elements: title, link, description, language Required per-item elements: title, enclosure, guid Enclosure URL, byte length, and MIME type Duplicate GUID detection Run build-rss-feed.bat first. The validator exits with a non-zero code on any failure so it can be used in CI scripts. Configuration file podcasts\\tts\\voice-config.ini controls all audio generation settings. The following table lists the available settings. Key Description Example male_model Piper ONNX model file for the male voice (Alex) en_US-ryan-high.onnx female_model Piper ONNX model file for the female voice (Jamie) en_US-lessac-high.onnx male_pitch_semitones Pitch shift in semitones for the male voice -2 female_pitch_semitones Pitch shift in semitones for the female voice 2 speech_rate Words per minute (passed to Piper) 180 episode_audio_format Output format: wav , mp3 , or both mp3 npm scripts The batch files wrap these npm scripts. They can also be run directly from a PowerShell or bash session at the repo root. npm script Description npm run validate:podcasts Validate the podcast catalog npm run generate:podcast-transcripts Generate transcript scripts npm run build:podcast-audio Generate audio (all episodes) npm run build:podcast-site Build RSS feed and podcast listing npm run validate:podcast-feed Validate the RSS feed To pass a range to the audio build from npm: npm run build:podcast - audio -- -- start 5 -- end 10 Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog Section-Level Source Map Use this map to verify facts for each major section in this file. Workflow order: GitHub Docs, home , GitHub Changelog , Workflow syntax for GitHub Actions , Secure use reference for GitHub Actions , GitHub Actions changelog generate-transcripts.bat: GitHub Docs, home , GitHub Changelog generate-audio.bat: GitHub Docs, home , GitHub Changelog build-rss-feed.bat: GitHub Docs, home , GitHub Changelog validate-rss-feed.bat: GitHub Docs, home , GitHub Changelog Configuration file: GitHub Docs, home , GitHub Changelog npm scripts: GitHub Docs, home , GitHub Changelog" }, - { - "id": "COMING_SOON.html", - "title": "Coming Soon", - "url": "COMING_SOON.html", - "body": "Coming Soon GIT Going with GitHub - Workshop Materials A Two-Day Workshop by Community Access The full workshop curriculum, lesson materials, and reference guides are currently being finalized. They will be published here before the workshop begins. In the Meantime Join the Discussion Forum - ask questions, connect with fellow participants Return to the home page Questions? Need help? File an issue in the workshop repository. A Community Access initiative. Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog Section-Level Source Map Use this map to verify facts for each major section in this file. GIT Going with GitHub - Workshop Materials: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests" - }, { "id": "SECURITY.html", "title": "Security Policy", @@ -2309,24 +2333,12 @@ "url": "README.html", "body": "GIT Going with GitHub License: CC BY 4.0 | Site | Discussions A Workshop by Community Access Welcome. This repository is your complete guide and companion for the two-day GIT Going with GitHub workshop. Every document here is written to be read with or without a screen reader. All steps are keyboard-accessible. You belong here. About Community Access: Community Access is a community of blind and low vision technology professionals. Visit community-access.org to learn more. Register Now -- May 21 & 22, 2026 Registration is open and free for the May 2026 cohort. The workshop runs Thursday, May 21 and Friday, May 22, 2026 . Register for GIT Going with GitHub -- single enrollment form, automated confirmation, guided next steps. You will need a GitHub account to register. New to GitHub? Creating an account is free and takes about two minutes; the registration page walks you through every step. Learn Online From Anywhere GIT Going with GitHub is available to remote learners as a fully online, self-paced experience . Wherever you are, you can work through the full curriculum on your own schedule. All materials -- challenges, episodes, podcasts, and reference docs -- are published on this site and available to read or listen to at any time. Hands-on practice happens inside your own GitHub learning room repository; mentors and automation agents support you through GitHub issues and discussions. No travel, no special software -- a browser, a keyboard, and your screen reader or assistive tech of choice are all you need. Open a discussion if you get stuck and a mentor will meet you there. This is open-source learning: free to read, free to share, free to join. Tools change. Exploration is part of the skill. GitHub.com, VS Code, GitHub Copilot, github.dev, browser extensions, and agent experiences change continuously. We do our best to keep this documentation current, source-backed, and tested, but a label may move, a feature may graduate from preview, or an account policy may change what you hear. When something differs, pause and use the exploration skills taught here: check the page title and URL, move by headings and landmarks, find the named tab or button, use the Command Palette or keyboard shortcut help, and compare with the official docs linked in each chapter. If the documented path is wrong, file a curriculum issue so we can update it for everyone. Detail Information Workshop site community-access.org/git-going-with-github Registration Student opt-in and waitlist workflow Discussions Join the conversation Support hub Community-Access/support Curriculum issues File an issue in this repository Dates May 21, 2026 & May 22, 2026 Facilitators Jeff Bishop and Michael Babcock The Central Project: Accessibility Agents This workshop is built around a real, live open source project: Accessibility Agents - 55 AI agents across 3 teams and 5 platforms for accessible, agentic repository management. It was built by your facilitator Jeff Bishop and is MIT-licensed. You will fork it, understand it, contribute to it, and personalize it. The live workshop prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. Accessibility Agents does not replace what you learn on Day 1. It amplifies it. The agents only make sense when you already understand the skills they automate. That is why Day 1 comes first - and why every guide in this repository shows you the manual path before it shows you the agent path. By the Numbers This curriculum represents hundreds of hours of work by the Community Access team. Metric Count Written chapters 23 Reference appendices 29 Total reference pages 78 Total words across all documentation ~355,000 Podcast companion episodes 58 Total podcast audio ~12 hours Hands-on challenges 16 core + 5 bonus = 21 total Worked reference solutions 21 Every chapter has a companion podcast episode. Every challenge has a worked solution. All 78 pages are written for screen reader users first. What Is This Event? During this two-day workshop, you will learn how to confidently navigate and contribute to open source projects on GitHub using: A screen reader (NVDA on Windows, JAWS on Windows, or VoiceOver on macOS) Keyboard-only navigation - no mouse required GitHub Copilot (Day 2) - AI-assisted writing and coding in the browser and in VS Code By the end of this event, you will have practiced real contribution workflows in a real repository. Some participants will ship during the live event; others will leave with a branch, a pull request path, and clear next steps to finish asynchronously. Who Is This For? This event is designed for: People new to GitHub who use assistive technology Developers who use screen readers and want to contribute to open source Anyone who is curious about accessible development workflows Sighted participants are welcome - all content is keyboard-navigable for everyone You do not need to know how to code to participate and contribute " }, - { - "id": "REORG-PLAN.html", - "title": "Git Going with GitHub - Reorganization Master Plan", - "url": "REORG-PLAN.html", - "body": "Git Going with GitHub - Reorganization Master Plan Living document. Update checkboxes as work completes. Two repos in scope: Content repo: c:\\code\\git-going-with-github (Community-Access/git-going-with-github) - book, scripts, audio source of truth. Site repo: c:\\code\\ggg - lp.csedesigns.com static site, episode HTML, RSS feed, media folder. Last updated: 2026-05-18. Launch posture Greenfield. No published audience yet, no subscribers, no external inbound links worth preserving. Treat the entire reorg as preparation for a clean first launch. Consequences: No 301 redirects, no moved.html , no Caddyfile redirect rules. Old paths simply disappear at cutover. RSS <guid> values can change freely until we publicly announce the feed. We still mint stable UUIDs now so we never have to break GUIDs once we do announce. No SEO carryover. New URLs are the only URLs. No subscriber re-download risk. Identity model The architecture rests on a two-axis identity model in docs/EPISODE_MAP.json : Identity axis (immutable after launch). uuid and filename are stable forever. They appear in mp3 ID3 frames, RSS <guid> , and enclosure URLs. Ordering axis (freely reassignable). track_number and pairs_with_uuid drive the podcast feed and the website learning view. Rewriting them is a map edit plus a regenerate; no audio is touched, no filename is renamed. This separation is why insertion, interleaving, and topic expansion all become map edits rather than cascade renames. Filename scheme Filename pattern: <topic-prefix>-<NN>[-<letter>]-<slug>.mp3 Group Topic prefix learning_band Example Chapter ch chapter ch-05-collaboration.mp3 Code challenge cc challenge cc-05-fork-and-clone.mp3 Bonus challenge cc-bonus bonus cc-bonus-a-improve-agent.mp3 Reference appendix ref reference ref-01-glossary.mp3 Git appendix git git git-03-security.mp3 Tools appendix tools tools tools-01-vscode-reference.mp3 Agents appendix agents agents agents-01-copilot-reference.mp3 Security appendix sec sec sec-01-branch-protection.mp3 Ops appendix ops ops ops-01-actions-and-workflows.mp3 Reach appendix reach reach reach-01-community-and-social.mp3 Rules: NN is zero-padded two-digit within-topic. ch-05 is the 6th chapter (00-indexed) regardless of feed position. Optional letter suffix ( ch-05a- , ch-05b- ) is reserved for mid-sequence insertion where the new content is logically part of the adjacent chapter. Slugs are lowercase ASCII kebab-case. No double dashes. No trailing dash. Max 60 chars. Within-topic numbers are append-only. Deleted entries leave the number reserved (entry stays in map with archived: true ). Two digits is the cap. If a single topic exceeds 99 entries, that is a curriculum signal to split the topic, not to extend numbering. Track number track_number is a 1-based integer. Unique across the entire map. Contiguous after every regenerate-all run (no gaps). The feed is sorted strictly by track_number . ID3 TRCK frame is written from track_number . Listeners see "Episode N of M" by track number; titles still carry the within-topic identity ("Chapter 5: Collaboration"). pairs_with_uuid Optional. Points from child (challenge, bonus, appendix) to parent (usually a chapter). Used by regenerate-all to compute interleaved track numbers automatically: parent track N, then all children of N in their pair_order , then parent track N+1. Must point to an existing UUID. Cannot cycle. Lint-enforced. A parent can have many children. A child has at most one parent. Narration-vs-display contract Within-topic number ( ch-05 ) is the curriculum truth spoken in narration. It never changes after launch. Show notes, ID3 titles, site headings all use it. Track number is the feed truth for podcast apps. It can shift freely; nothing in the recorded audio refers to it. This is why interleaving challenges with chapters is safe: the narration in cc-05 calling itself "Challenge 5" remains correct regardless of whether it plays at track 6 (paired with chapter 5) or track 30 (challenges grouped at end). Guiding principles Audio is sacred. Once an mp3 is rendered, tagged, and chaptered, we do not re-render it to change a number or a name. One canonical map, many surfaces. docs/EPISODE_MAP.json is the single source of truth. Every rename, feed regen, ID3 retag, site build, and deploy reads from it. No tool hardcodes a slug or number. All tooling conforms to the map. Tools that currently hardcode slugs get refactored in Stage 2 before they touch anything in Stage 3. Stable UUIDs from day one. Each episode gets a permanent UUID stored in the map, in its ID3 TXXX:UUID frame, and in its RSS <guid isPermaLink="false"> . Decoupled identity and ordering. Filename is identity. track_number is display. Never confuse the two. Clean cutover on the server. Replace scp -r with rsync --delete plus pre-deploy tarball backup. Validate at every gate. Schema check, link check, RSS validate, mp3 tag verify, server-side " - }, { "id": "REPOSITORY_SECURITY.html", "title": "Repository Security & Access Guidelines", "url": "REPOSITORY_SECURITY.html", "body": "Repository Security & Access Guidelines Overview This repository hosts the curriculum and facilitator materials for the Git Going with GitHub workshop. Student work happens in individual private repositories created by GitHub Classroom, not in this repository. This document covers the security model for both the curriculum repository and the student repositories. Access Control Curriculum Repository (git-going-with-github) Role Repository Issues PRs Settings Facilitators Full access Full access Review and merge Admin Contributors Read Create and comment Create None Public Read View View None This repository is public. It contains no secrets, student data, or sensitive configuration. All curriculum content is openly licensed. Student Repositories (created by GitHub Classroom) Role Repository Issues PRs Settings Student (owner) Read/Write Full access Create and merge Limited (no Actions config) Facilitators Full access via Classroom Full access Review and comment Admin Other students No access No access No access No access Student repositories are private by default . Each student can only see their own repo. Facilitators see all student repos through the GitHub Classroom dashboard. Organization Membership Students do not need to be members of the Community-Access organization. GitHub Classroom handles all access automatically when a student accepts an assignment invite link. The student is granted access to their individual repo without any org-level permissions. Facilitators do need organization-level access to manage the classroom. See the Facilitator Access section below. Branch Protection Curriculum Repository (main branch) Protection Rules: Require pull request reviews: Yes (1 approval minimum) Require status checks to pass: Yes (GitHub Actions validation) Require branches to be up to date: No (to avoid unnecessary merge conflicts) Allow auto-merge: No (manual merge only for safety) Allow force pushes: No (protect history) Allow deletions: No (protect branch) Student Repositories Student repos are created from the learning-room-template . Branch protection in student repos is intentionally minimal: Students can create branches freely (required for challenges) Students can merge their own PRs (required for the learning flow) No force push protection (students are learning; mistakes are part of the process) GitHub Actions workflows run with read/write permissions (required for Gandalf and the Progression Bot) What Students Cannot Do Even within their own repo, students cannot: Access GitHub Actions secrets at the organization level Modify workflow files that run with elevated permissions Access other students' repositories View the classroom admin settings Permission Model Least Privilege The GitHub Classroom model enforces least privilege by design: Students are not organization members Students have no access to the curriculum repository's settings Students have no access to other students' repos Students have no access to CI/CD secrets or org-level configuration Students can create branches, issues, and PRs in their own repo Students can push to any branch in their own repo Students can merge PRs in their own repo (with autograder checks reporting status) Facilitator Access Required Access Level Facilitators must be Owners or Admins of the Community-Access organization to: Create and manage GitHub Classroom assignments View all student repositories through the classroom dashboard Comment on student PRs via the feedback pull request Monitor autograding results Troubleshoot workflow failures in student repos Adding a Facilitator # Add a facilitator as an org admin gh api /orgs/Community-Access/memberships/USERNAME -X PUT -f role=admin # Verify the role gh api /orgs/Community-Access/memberships/USERNAME --jq .role # Expected output: "admin" Removing a Facilitator After the Workshop # Downgrade to member (retains read access) or remove entirely gh api /orgs/Community-Access/memberships/USERNAME -X DELETE GitHub Actions Security Workflows in Student Repositories The template repository includes these workflows, which are copied into every student repo: Workflow Trigger Permissions What It Does pr-validation-bot.yml PR opened/updated Read/Write Gandalf validates PR structure and posts feedback student-progression.yml Issue closed Read/Write Creates the next challenge issue autograder-conflicts.yml Push Read Checks for conflict markers autograder-local-commit.yml Push Read Verifies local commit evidence autograder-template.yml Push Read Validates YAML template autograder-capstone.yml Push Read Validates agent file structure Safety guarantees: Workflows use only GITHUB_TOKEN (scoped to the individual student repo) No external API keys or webhook secrets are stored Workflows cannot access other repositories or organization-level resources Workflow code is visible to the student (transparency) Curriculum Repository Workflows The curriculum repo uses standard CI workflows for building HT" }, - { - "id": "SHIP-CHECKLIST.html", - "title": "Stage 3 Cutover - Ship Checklist", - "url": "SHIP-CHECKLIST.html", - "body": "Stage 3 Cutover - Ship Checklist Generated by the Stage 3 pre-flight on the current main branch. Everything below has been dry-run verified . The actual cutover is one explicit go away. Pre-cutover state (verified) Stage 2 gate: 5/5 PASS ( scripts/run-stage2-gate.ps1 ). Map: docs/EPISODE_MAP.json validates against schema 1.0.0; 79 episodes (58 ep + 16 cc + 5 cc-bonus); UUIDs stable; track_number drives ordering. Audio inventory: 79 mp3 files present in podcasts/audio/kokoro-am_liam-af_jessica/ ; 58 need rename, 21 already in new scheme. Working tree dirty: 522 uncommitted files from prior Stage 1-2 work. Recommend committing or stashing these before Stage 3. Built tools (this session) Step Tool Status 3.1 podcasts/tools/dry_run_rename.py Dry-run PASS 3.2 podcasts/tools/rename_audio.py (--apply, --finalize-map, --chapters-dir) Preview PASS, preflight clean 3.5 scripts/rewrite-cross-links.ps1 (-Apply) Dry-run PASS, 8 files / 509 reps Dry-run summary Stage 3 . 1 - rename plan 58 mp3 renames (e.g. ch- 00 -welcome.mp3 -> ch- 00 -welcome.mp3) 21 no-op (current_filename == filename) CSV : tmp-proposed-rename.csv Stage 3 . 5 - cross-link rewrite (with .history, snapshots, transcripts excluded) 8 files, 509 replacements Largest : admin\\PODCASTS.md ( 174 ), quality_triage_report.csv/.md ( 224 total), listening -order.json ( 58 ), validate-report.json ( 44 ) Report : tmp-crosslink-rewrite-report.txt Fire sequence (locally reversible up through step 5) Run these commands in order. Each step is a separate commit so any single step can be reverted in isolation. 0. Clean slate cd c:\\code\\git -going-with-github git checkout -b cutover -20260518 git add -A git commit -m "Pre-cutover state: Stage 1-2 work product + Stage 3 tooling" 1. Rename audio + parallel chapter JSON (Stage 3.2) python podcasts\\tools\\rename_audio.py --apply --finalize-map git add -A git commit -m "Stage 3.2: rename audio to topic-prefixed filenames + finalize map" Effect: 58 mp3 files renamed, 58 chapter JSON files renamed, map's current_filename / current_slug updated to match filename . 2. Retag ID3 (Stage 3.3) python podcasts\\tools\\tag_id3.py python podcasts\\tools\\verify_id3.py git add -A git commit -m "Stage 3.3: retag ID3 frames on renamed audio" Effect: TIT2, TRCK, TXXX:TOPIC updated; CHAP/CTOC untouched. Idempotent. 3. Cross-link rewrite (Stage 3.5) powershell -NoProfile -ExecutionPolicy Bypass -File scripts\\re write-cross -links .ps1 -Repo c:\\code\\git -going-with-github -Apply git add -A git commit -m "Stage 3.5: rewrite cross-links to new filename scheme" Effect: 509 replacements across 8 files (listening-order.json, PODCASTS.md, quality_triage_report.*, validate-report.json, etc.). 4. Re-run Stage 2 gate powershell -NoProfile -ExecutionPolicy Bypass -File scripts\\run -stage2-gate .ps1 Must return 5/5 PASS. If not, halt and investigate. 5. Mirror to deploy repo (Stage 3.6) robocopy podcasts\\audio\\kokoro -am_liam-af_jessica c:\\code\\ggg\\site\\media *.mp3 /MIR Confirm file counts match: (Get-ChildItem c:\\code\\ggg\\site\\media\\*.mp3).Count . 6. Regenerate feed + site (Stages 3.7 - 3.8) cd c:\\code\\ggg node generator\\generate -site .js node generator\\validate -feed .js Spot-check c:\\code\\ggg\\site\\feed.xml . Confirm <enclosure url> points to the new filenames. (Cover art piece intentionally omitted per project constraint.) --- IRREVERSIBLE LINE --- Steps below affect remote systems. Confirm step 6 looks correct before proceeding. 7. Deploy (Stage 3.9) c:\\code\\ggg\\ deploy-ggg .ps1 -Backup c:\\code\\ggg\\ deploy-ggg .ps1 -DryRun # review the rsync delta c:\\code\\ggg\\ deploy-ggg .ps1 # live 8. Smoke-test remote curl -I https://lp.csedesigns.com/ggg/feed.xml -> 200 Three sample enclosure URLs -> 200 Three episode pages -> 200 9. Tag (Stage 3.10) cd c:\\code\\git -going-with-github git checkout main git merge --no-ff cutover -20260518 git tag v2 -renumbered-20260518 git push origin main --tags cd c:\\code\\ggg git tag v2 -renumbered-20260518 git push origin main --tags Rollback (steps 1-5) Any of steps 1-5 can be reverted with: git reset --hard HEAD~ 1 For audio rename specifically, tmp-rename-audit.log records every old -> new pair so a reverse rename script can be reconstructed. What's intentionally excluded Cover art ( <itunes:image> in feed) - skipped per project constraint. .history/ files - VS Code Local History snapshots, not rewritten. podcasts/_snapshot-pre-*/ - intentional historical reference. podcasts/transcripts/ - workflow artifacts that key off old slug names in their own filename scheme; do not need rewrite for cutover. Notes All 522 currently-uncommitted files come from prior Stage 1-2 sessions. They have been validated by the Stage 2.8 gate. Committing them in step 0 is the cleanest restore point. The cutover branch should be cutover-20260518 per the REORG-PLAN.md specification. Authoritative Sources Use these official references when you need the current source of truth for t" - }, { "id": "golden.html", "title": "golden.md", @@ -2339,18 +2351,6 @@ "url": "CLAUDE.html", "body": "CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. What This Repository Is "GIT Going with GitHub" - an accessible, screen-reader-first workshop teaching blind and low-vision users to contribute to open source on GitHub. This is primarily a documentation project (Markdown in docs/ ) with three supporting systems: an HTML build pipeline, a podcast audio pipeline, and GitHub Actions automation that provisions and grades per-student "Learning Room" repositories. Commands npm run build:html # Regenerate html/ from Markdown (also regenerates work.md) npm run watch:html # Auto-rebuild HTML on Markdown changes npm run clean # Delete html/ npm run test :automation # node --test .github/scripts/__tests__/*.test.js npm run test :provisioning # node --test .github/scripts/provisioning/__tests__/*.test.js npm run test :llm-execution # Podcast LLM job execution tests # Single test file: node -- test .github/scripts/provisioning/__tests__/roster.test.js npm run validate:podcasts # Podcast catalog + listening-order validation npm run validate:authoritative-sources # Checks "Authoritative Sources" sections in docs Tests use the built-in Node test runner (Node >= 20), no test framework dependency. The podcast audio/TTS steps ( build:podcast-audio , metadata, inventory) require Python and ffmpeg and run locally; treat them as out of scope unless asked. Critical Workflow: HTML Is Committed, Not CI-Built There is no CI build for the docs. After editing any .md file, run npm run build:html and commit both the Markdown source and the regenerated html/ output in the same commit. docs/*.md -> html/docs/*.html , README.md -> html/index.html , plus learning-room/ and root-level docs. The build template and CSS live in scripts/build-html.js . Architecture docs/ - The curriculum: chapters 00 - 22 plus appendix-*.md , CHALLENGES.md (challenge hub), and solutions/ (reference solutions). Note: appendix display letters (A-Z in README tables) do NOT match appendix filenames - they were renumbered; go by the README tables, not the filename letter. learning-room/ - Template repository copied into each student's private repo during provisioning. Its own .github/ holds the student-facing automation (challenge issue templates, validation bot, progression workflows). scripts/generate-work-md.js derives work.md from these challenge templates. .github/scripts/provisioning/ - "Hybrid provisioning": the GitHub-native replacement for GitHub Classroom (which was removed entirely). provision-core.js is pure orchestration - it takes an injected client ( github-client.js ), never touches the network or secrets directly, and returns an updated roster plus a log. Tests run it against a fake client. github-app-auth.js handles GitHub App authentication; roster.js and roster.schema.json define the student roster; provision-cli.js is the entry point; the workflow is provision-learning-rooms.yml . The algorithm (serial, backoff, idempotent) is specified in SPEC.md section 7.2b - keep code and spec in sync. .github/scripts/ (top level) - PR validation and challenge-progression bots. Some are legacy from the old shared-repository model; see .github/README.md for which workflows are active vs. legacy. podcasts/ - Audio companion pipeline: build-bundles.js -> per-episode source bundles -> scripts -> local ONNX TTS (Kokoro default, Piper fallback) -> generate-site.js builds the player page and RSS feed. config/listening-order.json is the canonical episode order shared by JS ( lib/listening-plan.js ) and Python ( listening_plan.py ) resolvers. Audio files are gitignored and hosted on GitHub Releases. scripts/ - Repo-level build tooling (HTML, ePub, BRF, diagram SVGs, source validation). Root-level tmp-* files, work.md / work.html , and golden.md / golden.html are generated or scratch artifacts - do not hand-edit them. Conventions Never use emojis anywhere: docs, code, comments, commit messages (from .github/copilot-instructions.md ). All documentation is written screen-reader-first: semantic headings, descriptive link text, keyboard-only instructions, no meaning conveyed by visuals alone. Docs end with an "Authoritative Sources" section plus a "Section-Level Source Map"; npm run validate:authoritative-sources checks these. Preserve them when editing docs. Commit messages in this repo follow conventional-commit style ( docs: , build: , refactor: , ...). License is CC BY 4.0." }, - { - "id": "DEPLOYMENT_ASSESSMENT.html", - "title": "Deployment Assessment: Hybrid Provisioning System", - "url": "DEPLOYMENT_ASSESSMENT.html", - "body": "Deployment Assessment: Hybrid Provisioning System Date: June 2, 2026 Status: READY FOR PRODUCTION (with caveat below) Summary The Hybrid provisioning system is architecturally sound, hardened, and production-ready . However, the end-to-end workflow has not yet been tested with real student enrollment . Recommendation: Run Phase 4 smoke test before admitting first cohort. Hardening Assessment by Component OK: GitHub App Configuration Status: HARDENED Why: Fine-grained permissions (least privilege), secrets stored in GitHub Actions only, PEM key never in code Risk: None identified Action: READY OK: Secrets & Variables Management Status: HARDENED Why: All three secrets (App ID, Installation ID, PEM) stored securely in GitHub repository Actions secrets; variables configured correctly Risk: None identified Action: READY OK: Infrastructure Code (Provisioning Scripts) Status: HARDENED Why: Idempotent: Re-running is safe (already-exists vs. created state) Self-healing: Missing students auto-provisioned on next run Deterministic: Uses GitHub API signals, not external state Auditable: All history in provisioning-log.json and git Risk: None identified Action: READY OK: Documentation Updates Status: COMPLETE What: 15+ files updated, 37+ files deleted, HTML regenerated on both sites Coverage: Student-facing, facilitator, operator all covered Risk: None identified Action: READY OK: Public Site Deployments Status: COMPLETE Coverage: community-access.org/git-going-with-github (auto via GitHub Pages) lp.csedesigns.com/ggg (manual via rsync + Caddy reload) Verification: Both sites live and tested (404s work, navigation intact) Risk: None identified Action: READY Warning: End-to-End Student Workflow (NOT YET TESTED) Status: UNTESTED What's missing: Admin roster repo creation Smoke test with test student account Verification that provision workflow runs end-to-end Verification that invitation email sent to test account Verification that student can accept invite and access repo Risk: Medium-logical gaps possible, though architecture is solid Action: REQUIRED-Run Phase 4 before admitting real students What Has Been Tested OK: Automation tests: 78/78 passing (was 98, reduced after removing Classroom tests) OK: Provisioning tests: 55/55 passing OK: HTML regeneration: 393 markdown files -> HTML OK: Site deployments: Both production sites live OK: GitHub App creation: Properly configured with correct permissions OK: Secrets storage: All three values stored securely What Has NOT Been Tested Missing: End-to-end provisioning flow with a real test student Enrollment form submission Issue creation in test account Automation comment with learning room link Provisioning workflow execution Private repo creation and invitation Student repo readiness for challenges Failsafe Mechanisms Mechanism How It Works When It Helps Idempotence Re-running workflow is safe; state tracked in roster.json If automation fails, re-run fixes it Self-healing Missing students auto-provisioned on next run If student missed by error, they're caught on retry Audit Trail provisioning-log.json records every action Troubleshooting, rollback, verification Source of Truth roster.json is canonical; all state derives from it Repo can be recreated, roster is immutable Least Privilege GitHub App has minimal permissions Limits blast radius if credentials compromised Secrets in Actions PEM never stored in code or logs Prevents accidental exposure Deterministic Signals Progress tracked via GitHub events No hidden external dependencies Recommendations Before Go-Live MUST DO (Blocking) Run Phase 4 Smoke Test Create test admin roster repo Add one test learner (e.g., a throwaway GitHub account you control) Trigger provisioning workflow with dry-run first Trigger provisioning workflow without dry-run Verify: Private repo created Invitation sent to test account Roster entry updated to "provisioned" provisioning-log.json records "created" Run again; verify log records "already-exists" Test account accepts invite; repo is ready for challenges Verify End-to-End Student Flow Submit enrollment form as test student Verify issue created in your account Reply ack to issue Verify automation comment posts learning room link Verify you receive GitHub invitation Accept invitation; verify repo has challenges SHOULD DO (Recommended, not blocking) Verify Flask Companion (Optional) If deploying companion for web enrollment, test locally first See Phase 5 of deployment guide Document Rollback Plan If provisioning fails, how to revert? If student repo corrupted, how to re-provision? Document in runbook Test with Multiple Students Once Phase 4 passes, add 3-5 test students to roster Verify all get provisioned correctly Verify no duplicates or conflicts NICE TO HAVE (After launch) Monitor first week of production: Track provisioning success rate Log any failures to support channel Verify no duplicate repos Verify all students receive invitations Set up alert" - }, - { - "id": "REVIEW-2026-07-02.html", - "title": "Operations Review: Provisioning Failures and Workshop Model Robustness", - "url": "REVIEW-2026-07-02.html", - "body": "Operations Review: Provisioning Failures and Workshop Model Robustness Date: July 2, 2026 Scope: GitHub Actions failure analysis, provisioning subsystem, registration pipeline, repo hygiene. Implementation status (July 2, 2026): everything in sections 3, 4.1-4.4, and 6 that is code has been implemented (installation-ID auto-discovery, watchdog alert issue, work-free early exit, event-driven provisioning dispatch, weekly credentials health check, preflight assertions, intake-to-roster sync, Classroom link removal, [REGISTER] private intake plus redaction, authoritative-sources gate fixes, scratch cleanup). The remaining manual step is section 2: install the GitHub App on the Community-Access organization. Template drift (4.5) is still open. 1. Headline Finding: The Provisioning GitHub App Is Not Installed on the Org The "Provision Learning Rooms" workflow has failed on every real run since it was deployed. Verified numbers from the GitHub API: 280 total runs of provision-learning-rooms.yml . Exactly 1 success ever (June 2, 2026, 20:16 UTC) - and that run was a dry run, which skips authentication entirely. Every non-dry run, including roughly 12 scheduled runs per day for the past 30 days, fails with: Failed to mint installation token (HTTP 404) Root cause, confirmed directly: GET /orgs/Community-Access/installations shows exactly one GitHub App installed on the org - digitalocean (app id 64711). The provisioning App was created (App ID and PEM are stored as secrets) but was never installed on the Community-Access organization. There is no installation to mint a token against, so the token mint returns 404 no matter what PROVISIONING_APP_INSTALLATION_ID contains. Consequences, also confirmed: The private roster ( git-going-with-github-administration/roster.json ) has 2 learners in provision_state: pending - unchanged since June 2. Two registered people have been waiting a month for learning rooms that were never created. The admin repo has had no roster commits since June 2 because the workflow dies before the commit step. This is precisely the failure class SPEC.md's golden principle warns about ("never let a single point of failure hold a cohort hostage") and violates the section 7.2b invariant "any failure visible to a human before a learner notices." The watchdog the spec calls for does not exist. Note on the local working-tree changes: the uncommitted edits to github-app-auth.js (normalize URL-form installation IDs, better 404 hint) are good hardening and all 58 provisioning tests pass, but they will not fix production. No installation ID is valid until the App is installed. 2. Immediate Fix (Operator Steps, ~15 Minutes) Install the App: GitHub -> Organization settings -> Developer settings -> GitHub Apps -> your provisioning App -> Install App -> Community-Access. Because the App must create new repositories, install it org-wide (repository creation cannot be granted through a selected-repositories installation). Capture the installation ID from the post-install URL ( .../settings/installations/<id> ) or from GET /app/installations using an App JWT. Update the PROVISIONING_APP_INSTALLATION_ID secret (it lives in the provisioning environment, not repo-level secrets). Run the workflow manually with dry_run: true (expect: "2 learner(s) would be provisioned"), then run it for real. Verify: two new learning-room-* repos, invitations sent, roster entries flipped to provisioned , provisioning-log.json committed to the admin repo. 3. Make the Failure Class Impossible: Code Changes These are ordered by payoff. 3.1 Auto-discover the installation ID Stop storing the installation ID as a secret at all. With an App JWT you can call GET /app/installations and select the installation whose account matches PROVISIONING_STUDENT_OWNER . Add this as the fallback (or the default) in github-app-auth.js / provision-cli.js . This removes an entire class of copy-paste misconfiguration and survives App re-installation (installation IDs change when an App is uninstalled and reinstalled). Alternative for the workflow path: the official actions/create-github-app-token action needs only app-id and private-key and resolves the installation from the repo owner automatically. It keeps the zero-npm-dependency property of the repo since it runs as an action, and the CLI keeps the hand-rolled path for local use. 3.2 Alert on failure - implement the spec's watchdog Thirty days of silent failure proves the need. Add a final if: failure() step to provision-learning-rooms.yml that creates or updates a pinned, labeled issue (for example provisioning-broken ) in this repo, including the error line from the log. Close it automatically on the next success. Requires issues: write on this workflow only. 3.3 Skip work-free runs Most of the 280 failed runs had zero learners to provision. Read the roster first; if there are no pending / failed entries, exit success before minting" - }, { "id": "SPEC.html", "title": "SPEC.md",