Adding diagnostic checks in codespace and local terminal setups

mnkiefer · mnkiefer · commit bb9a1a4da772 · 2026-07-17T05:28:36.000+02:00
diff --git a/workshop/06a-install-terminal.md b/workshop/06a-install-terminal.md
@@ -5,7 +5,7 @@
 
 ## 🎯 What You'll Do
 
-You'll verify the `gh` CLI is authenticated, install the `gh-aw` extension, and confirm it is working in your Codespace terminal.
+You'll verify the `gh` CLI is authenticated, install the `gh-aw` extension, and run one quick diagnostic to confirm your Codespace terminal is ready for agentic workflow setup.
 
 ## 📋 Before You Start
 
@@ -57,6 +57,18 @@ gh aw --version
 
 You should see output like `gh-aw version 0.81.6`.
 
+## Run a quick diagnostic
+
+Now run:
+
+```bash
+gh aw doctor
+```
+
+This verifies your GitHub CLI authentication using the same setup checks `gh-aw` expects before later authoring and compile steps.
+
+Expected result: a success message confirming GitHub CLI authentication. If it fails, use [Side Quest: Install gh-aw Troubleshooting](side-quest-06-01-install-troubleshooting.md), then rerun `gh aw doctor`.
+
 ## Initialize [agentic workflow](https://github.github.com/gh-aw/introduction/overview/) skills
 
 Before you author your first workflow, initialize and push the generated skill files:
@@ -84,6 +96,7 @@ Which one sub-command do you expect to use in Step 7 when you create and run you
 
 - [ ] `gh auth status` shows you are logged in to github.com
 - [ ] `gh aw --version` returns a version number
+- [ ] `gh aw doctor` completes successfully
 - [ ] `gh aw init` has been run in your practice repository
 - [ ] All files generated by `gh aw init` are committed and pushed
 - [ ] You can name one `gh aw` sub-command from `gh aw --help`
diff --git a/workshop/06b-install-local.md b/workshop/06b-install-local.md
@@ -5,7 +5,7 @@
 
 ## 🎯 What You'll Do
 
-You'll verify the `gh` CLI is authenticated, install the `gh-aw` extension, and confirm it is working in your local terminal.
+You'll verify the `gh` CLI is authenticated, install the `gh-aw` extension, and run one quick diagnostic to confirm your local terminal is ready for agentic workflow setup.
 
 ## 📋 Before You Start
 
@@ -57,6 +57,18 @@ gh aw --version
 
 You should see output like `gh-aw version 0.81.6`.
 
+## Run a quick diagnostic
+
+Now run:
+
+```bash
+gh aw doctor
+```
+
+This verifies your GitHub CLI authentication using the same setup checks `gh-aw` expects before later authoring and compile steps.
+
+Expected result: a success message confirming GitHub CLI authentication. If it fails, use [Side Quest: Install gh-aw Troubleshooting](side-quest-06-01-install-troubleshooting.md), then rerun `gh aw doctor`.
+
 ## Initialize [agentic workflow](https://github.github.com/gh-aw/introduction/overview/) skills
 
 Before you author your first workflow, initialize and push the generated skill files:
@@ -84,6 +96,7 @@ Which one sub-command do you expect to use in Step 7 when you create and run you
 
 - [ ] `gh auth status` shows you are logged in to github.com
 - [ ] `gh aw --version` returns a version number
+- [ ] `gh aw doctor` completes successfully
 - [ ] `gh aw init` has been run in your practice repository
 - [ ] All files generated by `gh aw init` are committed and pushed
 - [ ] You can name one `gh aw` sub-command from `gh aw --help`
diff --git a/workshop/07c-your-first-workflow-copilot.md b/workshop/07c-your-first-workflow-copilot.md
@@ -16,9 +16,9 @@ Open your practice repository in the GitHub Copilot app and start a session in *
 Paste this prompt:
 
 ```text
-Create `.github/workflows/daily-report-status.md` as a GitHub Agentic Workflow.
+Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md
 
-Before authoring, run `gh aw init` from the repository root, then commit and push the generated `.github/skills/agentic-workflows/` files.
+Then create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
 
 The workflow must:
 - Be named "Daily Report Status"
@@ -29,9 +29,7 @@ The workflow must:
   "This issue has the most community support! We'll prioritise it in our next planning session."
 - Create an issue titled "Community Voting Test" and post the same comment if no open issues exist
 
-Run `gh aw compile --validate` in the session
-workspace, fix any errors, commit the source and generated lock file (plus the initialized skill files), and open a
-pull request. Show me the diff before merging.
+Run `gh aw compile --validate` in the session workspace, fix any errors, commit the source and generated lock file (plus any initialized skill files), and open a pull request. Show me the diff before merging.
 ```
 
 The agent runs validation in its isolated session workspace. You do not need a terminal for this path.
diff --git a/workshop/07d-confirm-model-access.md b/workshop/07d-confirm-model-access.md
@@ -33,9 +33,19 @@ The workflow uses the organization subscription. You do not need a personal Copi
 
 Use this path for a personal repository, or when the owning organization does not provide centralized Copilot billing.
 
-1. Complete [Method 2: `COPILOT_GITHUB_TOKEN`](side-quest-06-03b-copilot-github-token.md), or use its [GitHub UI-only path](side-quest-06-03c-copilot-github-token-ui-only.md).
-2. Remove `copilot-requests: write` from `daily-report-status.md`.
-3. Recompile and commit `daily-report-status.lock.yml` as described in the method guide.
+1. Remove `copilot-requests: write` from `daily-report-status.md`.
+2. If you are using a terminal, run:
+
+
+   ```bash
+   gh aw secrets bootstrap --engine copilot
+   ```
+
+   This guided flow checks whether `COPILOT_GITHUB_TOKEN` is needed, prompts for it if missing, and stores it as a repository secret.
+3. If you are staying in the browser, use [Method 2 (UI-only)](side-quest-06-03c-copilot-github-token-ui-only.md).
+4. Recompile and commit `daily-report-status.lock.yml`.
+
+If you want the full manual PAT procedure, use [Method 2: `COPILOT_GITHUB_TOKEN`](side-quest-06-03b-copilot-github-token.md).
 
 > [!IMPORTANT]
 > When `copilot-requests: write` is present, the workflow ignores `COPILOT_GITHUB_TOKEN` for inference. Remove the permission and recompile when you choose personal billing.
diff --git a/workshop/10-choose-your-scenario.md b/workshop/10-choose-your-scenario.md
@@ -121,7 +121,11 @@ Use the **Agentic Workflows** agent in the GitHub Copilot app or Agents tab to c
 Describe your intent in plain language — the agent handles the workflow format, compilation, and pull request for you:
 
 ```
-Create a daily status workflow that posts a summary of open PRs and issues to an issue comment every day.
+Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md
+
+Then create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
+
+The purpose of the workflow is a daily status report on recent repository activity, delivered as an issue comment. Summarize open pull requests and open issues every day.
 ```
 
 The agent creates the workflow, compiles it, and opens a pull request. Review the diff and merge it into `main`.
diff --git a/workshop/11d-build-copilot-agents.md b/workshop/11d-build-copilot-agents.md
@@ -68,7 +68,10 @@ The prompt below tells the agent two things:
 Copy and paste the following prompt into the Agents session input:
 
 ```
-Read the agentic workflow creation guide at:
+Initialize this repository for GitHub Agentic Workflows using:
+https://raw.githubusercontent.com/github/gh-aw/main/install.md
+
+Then read the agentic workflow creation guide at:
 https://github.com/github/gh-aw/blob/main/create.md
 
 Then create a daily repository status report agentic workflow for this repository.
@@ -93,7 +96,10 @@ Commit the `.md` file and the generated `.lock.yml`, then open a pull request fo
 Copy and paste the following prompt into the Agents session input:
 
 ```
-Read the agentic workflow creation guide at:
+Initialize this repository for GitHub Agentic Workflows using:
+https://raw.githubusercontent.com/github/gh-aw/main/install.md
+
+Then read the agentic workflow creation guide at:
 https://github.com/github/gh-aw/blob/main/create.md
 
 Then create a daily documentation health report agentic workflow for this repository.
@@ -118,7 +124,10 @@ Commit the `.md` file and the generated `.lock.yml`, then open a pull request fo
 Copy and paste the following prompt into the Agents session input:
 
 ```
-Read the agentic workflow creation guide at:
+Initialize this repository for GitHub Agentic Workflows using:
+https://raw.githubusercontent.com/github/gh-aw/main/install.md
+
+Then read the agentic workflow creation guide at:
 https://github.com/github/gh-aw/blob/main/create.md
 
 Then create a pull request code reviewer agentic workflow for this repository.
diff --git a/workshop/side-quest-06-03-copilot-token.md b/workshop/side-quest-06-03-copilot-token.md
@@ -11,6 +11,13 @@
 
 Agentic workflows call the GitHub Copilot API at runtime to run AI reasoning steps. Without a valid credential, every call returns `401 Unauthorized` and the workflow fails immediately. Configuring authentication once, before you run a workflow, ensures your agent can reach Copilot reliably on every future run.
 
+If you are using a terminal, prefer the guided `gh-aw` setup flows where possible:
+
+- `gh aw secrets bootstrap --engine copilot` after you choose personal billing
+- `gh aw add-wizard ...` when you are installing a curated workflow and want setup prompts inline
+
+Use the manual guides below when you need or prefer the step-by-step browser procedure.
+
 ## Choose your method
 
 Choose the method that fits your situation:
diff --git a/workshop/side-quest-06-03b-copilot-github-token.md b/workshop/side-quest-06-03b-copilot-github-token.md
@@ -11,7 +11,21 @@ If you want an all-UI path with no terminal commands, use [Method 2 (UI-only)](s
 - You have a GitHub account with an active Copilot subscription.
 - You have read [Side Quest: Configure GitHub Copilot Authentication](side-quest-06-03-copilot-token.md) and chosen Method 2.
 
-## ✏️ Sub-exercise A: Generate the token
+## Shortest terminal path
+
+If your workflow currently includes `copilot-requests: write`, remove that line first. When it is present, the workflow ignores `COPILOT_GITHUB_TOKEN` for inference.
+
+Then run:
+
+```bash
+gh aw secrets bootstrap --engine copilot
+```
+
+This guided flow checks whether the secret is missing, walks you through creating or pasting a valid fine-grained PAT, and stores it as `COPILOT_GITHUB_TOKEN`.
+
+If you prefer to create and store the PAT manually, follow the full procedure below.
+
+## ✏️ Sub-exercise A: Generate the token manually
 
 1. Go to [github.com/settings/tokens](https://github.com/settings/tokens) and click **Generate new token (fine-grained)**.
 2. Name the token (for example, `gh-aw-copilot`) and set an expiry (90 days is a common default).
@@ -33,7 +47,7 @@ Replace `YYYY-MM-DD` with your token expiry date.
 - [ ] I copied the token value before leaving the page
 - [ ] I noted the token rotation date
 
-## ✏️ Sub-exercise B: Store the secret
+## ✏️ Sub-exercise B: Store the secret manually
 
 Store the token as a repository secret:
 
@@ -56,7 +70,7 @@ You should see `COPILOT_GITHUB_TOKEN` in the output. Once confirmed, you can saf
 
 ## Select the token in your workflow
 
-Remove `copilot-requests: write` from the source workflow. When that permission is present, the workflow ignores `COPILOT_GITHUB_TOKEN` for inference.
+If you have not already done so, remove `copilot-requests: write` from the source workflow. When that permission is present, the workflow ignores `COPILOT_GITHUB_TOKEN` for inference.
 
 ```bash
 gh aw compile
