diff --git a/workshop/side-quest-11-04-annotated-workflow.md b/workshop/side-quest-11-04-annotated-workflow.md index 50677f7a..39c56b53 100644 --- a/workshop/side-quest-11-04-annotated-workflow.md +++ b/workshop/side-quest-11-04-annotated-workflow.md @@ -74,7 +74,7 @@ safe-outputs: ## ✏️ Your Turn — Safe-Outputs -1. In your `daily-status.md`, comment out the entire `safe-outputs:` block. +1. In your `daily-status.md`, comment out the entire [safe-outputs](https://github.github.com/gh-aw/reference/safe-outputs/) block. 2. Run `gh aw compile --validate`. 3. Read the error message — what write capability does the agent lose? 4. Uncomment the block and recompile to confirm the error is gone. diff --git a/workshop/side-quest-11-05-event-triggers.md b/workshop/side-quest-11-05-event-triggers.md index 9ef8bc5e..b860da4f 100644 --- a/workshop/side-quest-11-05-event-triggers.md +++ b/workshop/side-quest-11-05-event-triggers.md @@ -89,7 +89,7 @@ Then: ## How trigger choice changes `safe-outputs` -The trigger decides **when** the workflow starts. The `safe-outputs` block decides **where it is allowed to write back**. +The trigger decides **when** the workflow starts. The [safe-outputs](https://github.github.com/gh-aw/reference/safe-outputs/) block decides **where it is allowed to write back**. | Trigger | Natural thing to reply to | Common `safe-outputs` choice | |---------|----------------------------|------------------------------| diff --git a/workshop/side-quest-11-06-anthropic-key.md b/workshop/side-quest-11-06-anthropic-key.md index 2c032e23..d9e6fce5 100644 --- a/workshop/side-quest-11-06-anthropic-key.md +++ b/workshop/side-quest-11-06-anthropic-key.md @@ -4,7 +4,7 @@ > _Optional: work through this guide when you want to use [Claude](side-quest-01-02-environment-reference.md#claude) (Anthropic's model family) as the AI engine for your agentic workflow, then return to your main path._ -By default, [agentic workflows](https://github.github.com/gh-aw/introduction/overview/) run on the GitHub Copilot engine. If you prefer to use **Claude**, you'll need an Anthropic API key stored as a repository secret and a one-line change to your workflow frontmatter. +By default, [agentic workflows](https://github.github.com/gh-aw/introduction/overview/) run on the [GitHub Copilot engine](https://github.github.com/gh-aw/reference/engines/). If you prefer to use **Claude**, you'll need an Anthropic API key stored as a repository secret and a one-line change to your [workflow frontmatter](https://github.github.com/gh-aw/reference/frontmatter/). ## 📋 Before You Start diff --git a/workshop/side-quest-11-07-openai-key.md b/workshop/side-quest-11-07-openai-key.md index a4dfc21e..e3e06ae8 100644 --- a/workshop/side-quest-11-07-openai-key.md +++ b/workshop/side-quest-11-07-openai-key.md @@ -4,12 +4,12 @@ > _Optional: work through this guide when you want to use the `codex` engine (OpenAI-powered) for your agentic workflow, then return to your main path._ -By default, [agentic workflows](https://github.github.com/gh-aw/introduction/overview/) use the GitHub Copilot engine. To use **OpenAI models**, store an OpenAI API key as a repository secret and add one frontmatter line. +By default, [agentic workflows](https://github.github.com/gh-aw/introduction/overview/) use the [GitHub Copilot engine](https://github.github.com/gh-aw/reference/engines/). To use **OpenAI models**, store an OpenAI API key as a repository secret and add one frontmatter line. ## 📋 Before You Start - You have completed [Install `gh-aw`](06-install-gh-aw.md) and have a working agentic workflow. -- You are familiar with YAML frontmatter `env:` blocks. If frontmatter is new, skim [Side Quest: Frontmatter Deep Dive — Part A](side-quest-11-01-frontmatter-deep-dive.md) before continuing. +- You are familiar with [YAML frontmatter](https://github.github.com/gh-aw/reference/frontmatter/) `env:` blocks. If frontmatter is new, skim [Side Quest: Frontmatter Deep Dive — Part A](side-quest-11-01-frontmatter-deep-dive.md) before continuing. - You have an OpenAI account or access to an OpenAI API key from your organization. > [!NOTE] diff --git a/workshop/side-quest-11-08-frontmatter-tools-outputs.md b/workshop/side-quest-11-08-frontmatter-tools-outputs.md index 53b08224..5769d8f0 100644 --- a/workshop/side-quest-11-08-frontmatter-tools-outputs.md +++ b/workshop/side-quest-11-08-frontmatter-tools-outputs.md @@ -67,7 +67,7 @@ safe-outputs: --- ``` -**What this section does:** Closes the YAML frontmatter block. Everything below this line is the Markdown body — the agent's plain-English task brief. +**What this section does:** Closes the [YAML frontmatter](https://github.github.com/gh-aw/reference/frontmatter/) block. Everything below this line is the Markdown body — the agent's plain-English task brief. **✏️ Try it:** Add the closing `---` to your draft. Confirm the file now has exactly two `---` fences. diff --git a/workshop/side-quest-11-09-agent-session-phases.md b/workshop/side-quest-11-09-agent-session-phases.md index 146a2434..a33964cb 100644 --- a/workshop/side-quest-11-09-agent-session-phases.md +++ b/workshop/side-quest-11-09-agent-session-phases.md @@ -22,7 +22,7 @@ After you submit the scenario prompt, the session shows a live activity feed. Th |---|---|---| | **Reading** | The agent fetches the `create.md` reference and reads existing files in your repository | Confirm the agent fetched the reference guide and found your repository files | | **Planning** | The agent decides what frontmatter keys, permissions, and task brief to use | The planning output should reflect your intended scenario | -| **Writing** | The agent creates the workflow `.md` file in `.github/workflows/` | The file should contain a YAML frontmatter block between `---` fences and a Markdown task brief | +| **Writing** | The agent creates the workflow `.md` file in `.github/workflows/` | The file should contain a [YAML frontmatter](https://github.github.com/gh-aw/reference/frontmatter/) block between `---` fences and a Markdown task brief | | **Compiling** | The agent runs `gh aw compile --validate` and fixes any errors it finds | A green success message indicates the `.lock.yml` was generated without errors | | **Opening PR** | The agent commits both files and opens a pull request | The pull request should list two changed files: the `.md` source and the `.lock.yml` | diff --git a/workshop/side-quest-12-01-iterate-agent-output.md b/workshop/side-quest-12-01-iterate-agent-output.md index 900c1c80..0626b892 100644 --- a/workshop/side-quest-12-01-iterate-agent-output.md +++ b/workshop/side-quest-12-01-iterate-agent-output.md @@ -101,7 +101,7 @@ Quick problem-to-fix guide: Quick run-log check: - **Compile error** — run `gh aw compile` locally, or ask your Copilot agent to run it and fix the reported line. -- **Missing permissions** — re-check the workflow frontmatter and confirm the safe output surface is declared correctly. +- **Missing permissions** — re-check the [workflow frontmatter](https://github.github.com/gh-aw/reference/frontmatter/) and confirm the safe output surface is declared correctly. - **Rate limits or transient failures** — wait a few minutes and re-run. diff --git a/workshop/side-quest-13-01-schedule-expressions.md b/workshop/side-quest-13-01-schedule-expressions.md index 63f953b0..acea5077 100644 --- a/workshop/side-quest-13-01-schedule-expressions.md +++ b/workshop/side-quest-13-01-schedule-expressions.md @@ -18,7 +18,7 @@ You'll learn how `gh-aw`'s plain-English schedule syntax maps to GitHub Actions GitHub Actions stores schedules as **[cron expressions](https://github.github.com/gh-aw/reference/schedule-syntax/)** — five fields: `minute hour day-of-month month day-of-week`. -You do **not** need to write cron by hand for common cases. In `gh-aw`, you can write a fuzzy expression like `daily on weekdays`, then let `gh aw compile` convert it for you. +You do **not** need to write cron by hand for common cases. In `gh-aw`, you can write a [fuzzy expression](https://github.github.com/gh-aw/reference/schedule-syntax/#fuzzy-schedules) like `daily on weekdays`, then let `gh aw compile` convert it for you. ## Fuzzy schedule reference diff --git a/workshop/side-quest-15-01-expressions-and-contexts.md b/workshop/side-quest-15-01-expressions-and-contexts.md index 86d6414f..b04fb73c 100644 --- a/workshop/side-quest-15-01-expressions-and-contexts.md +++ b/workshop/side-quest-15-01-expressions-and-contexts.md @@ -32,7 +32,7 @@ A **context** is a named object that GitHub Actions populates automatically. The |---------|--------------| | `github` | Event metadata — repo name, branch, commit SHA, actor | | `steps..outputs` | Outputs written by a previous step using `$GITHUB_OUTPUT` | -| `env` | Environment variables set in the workflow or step | +| `env` | [Environment variables](https://github.github.com/gh-aw/reference/environment-variables/) set in the workflow or step | | `secrets` | Repository or organisation secrets | | `runner` | Information about the runner OS and temp directory | | `job` | Current job status | diff --git a/workshop/side-quest-16-01-github-output.md b/workshop/side-quest-16-01-github-output.md index 90a77798..889c4ac6 100644 --- a/workshop/side-quest-16-01-github-output.md +++ b/workshop/side-quest-16-01-github-output.md @@ -19,7 +19,7 @@ run: echo "$RESULT" # prints nothing — RESULT is gone ``` -Each step is a separate child process. Environment variables set with `export` only survive for the duration of that step. +Each step is a separate child process. [Environment variables](https://github.github.com/gh-aw/reference/environment-variables/) set with `export` only survive for the duration of that step. ---