docs: add GitHub Copilot app workshop content

copilot-app/0-prerequisites.md

@@ -0,0 +1,82 @@
+---
+title: "Lesson 0 - Prerequisites"
+description: "Set up for the GitHub Copilot app lessons: install Node.js for the Tailspin Toys project and create your own copy of the repository from the template."
+---
+
+The GitHub Copilot app is a desktop app, serving as your central hub for both Copilot and GitHub. It provides quick access to issues and pull requests, and of course allows you to build using GitHub Copilot. During this workshop you'll be working locally, using both the Tailspin Toys app, built on Astro, and of course the GitHub Copilot app. Before you get started, let's ensure Node.js is installed locally, then install the Copilot app.
+
+In this lesson, you will:
+
+- install Node.js so the project's tests can run on your machine.
+- create your own copy of the Tailspin Toys project from the template.
+
+## Install Node.js
+
+Several lessons ask an agent to build features and run the Tailspin Toys test suite locally, which needs **[Node.js][nodejs]** — the only runtime the project requires. Install version **22 or newer**; the current **LTS** release is a safe choice.
+
+The simplest option on every platform is the official installer:
+
+1. In your operating system, open a terminal window using Windows Terminal, macOS terminal, or whatever you typically use.
+2. Run the following command to confirm you have at least Node.js 22 or higher installed:
+
+    ```shell
+    node --version
+    ```
+
+3. If you see `v22` or a higher number, you can skip to the next section!
+
+> [!TIP]
+> You only need to complete these steps if you don't have Node installed, or you need to update.
+
+4. Open the [Node.js download page][node-download].
+5. Download the **LTS** build for your operating system.
+6. Run the installer and accept the defaults. On Windows, keep the **Add to PATH** option selected.
+7. Once installed, open a new terminal window.
+8. Confirm the install in the new terminal window by running the following:
+
+    ```bash
+    node --version
+    ```
+
+9. You should see `v22.x.x` or higher.
+
+> [!TIP]
+> Prefer containers? If you have **[Docker][docker]**, you can use the repository's [dev container][dev-containers] instead of installing Node.js locally — it bundles Node for you. You don't need both.
+
+## Set up the lab repository
+
+You'll work against your own copy of the Tailspin Toys project. Create it now from the [template repository][template-repository]. The new repository contains every file the lab needs, and you'll connect it to the app in the next lesson.
+
+1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`.
+2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**.
+
+    ![The Use this template button with Create a new repository selected from the dropdown](images/app-0-use-template.png)
+
+3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to GitHub Copilot.
+
+    ![The Create a new repository form with github-samples/tailspin-toys set as the template and the repository name filled in](images/app-0-create-repository.png)
+
+4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab.
+
+> [!NOTE]
+> When you create your repository from the template, a backlog of GitHub issues is created for you automatically. You'll work from these issues throughout the workshop — there's nothing to file yourself.
+
+## Summary and next steps
+
+You're set up! You installed Node.js so the project can build and test on your machine, and you created your own copy of the Tailspin Toys repository from the template.
+
+Next, you'll install the GitHub Copilot app, connect the repository you just created, and get oriented in the workspace. Continue to [Lesson 1 - Installing the GitHub Copilot app][next-lesson].
+
+## Resources
+
+- [Download Node.js][node-download]
+- [Creating a repository from a template][template-repository]
+- [About the GitHub Copilot app][about-copilot-app]
+
+[next-lesson]: 1-install-copilot-app.md
+[nodejs]: https://nodejs.org/
+[node-download]: https://nodejs.org/en/download
+[docker]: https://www.docker.com/products/docker-desktop/
+[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers
+[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository
+[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app

copilot-app/1-install-copilot-app.md

@@ -0,0 +1,97 @@
+---
+title: "Lesson 1 - Installing the GitHub Copilot app"
+description: "Install the GitHub Copilot app, connect the repository you created from the template, get oriented in the workspace, and try a quick chat."
+---
+
+The **[GitHub Copilot app][about-copilot-app]** is a desktop application for agent-driven development. It is built on GitHub Copilot CLI and integrates natively with GitHub, so your repositories, branches, and CI pipelines work out of the box. It's designed for workflows where you direct several agents in parallel — each in its own isolated workspace — rather than doing all of the work yourself. With Node.js installed and your copy of the project ready, the next step is to install the app and connect that repository.
+
+In this lesson, you will:
+
+- install the GitHub Copilot app and sign in.
+- add your project to the app from its GitHub repository.
+- get oriented in the workspace, including the backlog the template seeded for you.
+- try a quick chat to learn about the app itself.
+
+## Scenario
+
+Your team is adopting AI agents to work through a growing backlog. The Copilot app gives you one place to direct that work — picking up issues, running agents, reviewing changes, and merging pull requests. This lesson gets you installed, connected, and comfortable starting a conversation about your project.
+
+> [!NOTE]
+> An eligible Copilot plan is required — Copilot Student or any paid plan (Pro, Pro+, Business, or Enterprise). If you are on Copilot Business or Copilot Enterprise, your administrator must enable the **Copilot CLI** policy before the app will work.
+
+## Install and configure the GitHub Copilot app
+
+To use the GitHub Copilot app the first step, as you might imagine, is to install it. Versions are available for Windows, macOS and Linux. Let's install the app, authenticate, and add our Tailspin Toys repo to the app.
+
+1. In a browser, open the [landing page for the GitHub Copilot app][download-app].
+2. Download the app for your platform and install it following the instructions provided on the landing page.
+3. Open the app once it's installed.
+4. Select **Sign in to GitHub** and follow the prompts to authenticate. If you use GitHub Enterprise Server, choose **Use GitHub Enterprise** and enter your server address when prompted.
+5. After authenticating, you'll be asked about connecting your repositories. Select the Tailspin Toys repo you just created, which should be named `<YOUR_GITHUB_HANDLE>/tailspin-toys`.
+6. Select **Continue** to continue the onboarding.
+7. When prompted for a theme, select the one which brings you the most joy, then select **Finish**.
+
+> [!NOTE]
+> If your copy of Tailspin Toys didn't appear in the list automatically, you can add it after completing the onboarding process in the app. When completed, the Copilot app will bring you to the home screen. From there you can select **Choose from GitHub**, and search for your repo by name (\<YOUR_GITHUB_HANDLE\>/tailspin-toys), then select it. Your repo will now be added to the Copilot app!
+
+## Get oriented in the workspace
+
+With your project connected, take a moment to learn your way around. The app organizes everything into a few areas in the sidebar:
+
+- **Sessions** — where agents do their work. Each session runs in its own isolated workspace, so you can run several at once without their changes colliding. You'll start your first session in the next lesson.
+- **Quick chats** — lightweight conversations for questions and brainstorming that don't need a branch or workspace of their own. You'll try one at the end of this lesson.
+- **My work** — your issues and pull requests, surfaced through the app's **native GitHub integration**. From here you can browse and filter issues and pull requests, check CI status, start a session from an issue, and review pull requests — all without leaving the app.
+- **Automations** — saved agent tasks that run on a schedule or on demand. You'll create one near the end of the harness.
+
+### Find your seeded backlog
+
+Because the app integrates with GitHub natively, the work waiting in your repository shows up right inside the app. When you created your repository from the template, a backlog of issues was filed for you — let's confirm it's there.
+
+1. Select **My work** in the sidebar.
+2. Confirm you see the three issues the template seeded for your backlog:
+
+   - Allow users to filter games by category and publisher
+   - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments
+   - Stretch Goal: Implement pagination on the game list page
+
+3. Select an issue to read its details. Each issue is also a launch point for an agent session — you'll start work from these issues later in the harness.
+
+> [!NOTE]
+> The list of items in My work is automatically filtered to only display items from the repositories you've added to Copilot app. Want to see work items from other repos? Add them to the app!
+
+## Try a quick chat
+
+A great way to get comfortable with the app is to use it to learn about the *app itself* — and a **quick chat** is exactly the right tool for that. Quick chats let you ask a question or brainstorm without creating a branch or worktree, so they're perfect for a fast, throwaway question — no session required.
+
+1. In the sidebar, select **+** next to **Quick chats** to open a new chat.
+2. Ask the app how its own sessions work:
+
+   ```plaintext
+   How does the GitHub Copilot app use worktrees?
+   ```
+
+3. Read the response in the conversation view. You'll see that each session runs in its own isolated git worktree — the detail that lets you run several agents in parallel without their changes colliding. You can continue the conversation or start a new chat at any time.
+
+## Summary and next steps
+
+Congratulations! You've installed the GitHub Copilot app, connected your project, and explored your workspace. You learned how to:
+
+- install the app and sign in to GitHub.
+- add a project from its GitHub repository.
+- get oriented in the workspace and find your seeded backlog in **My work**.
+- use a quick chat to ask a fast, throwaway question.
+
+Next, you'll start your first agent session and make your first change to the project — showing a star rating on the game cards. Continue to [Lesson 2 - Running your first agent session][next-lesson].
+
+## Resources
+
+- [About the GitHub Copilot app][about-copilot-app]
+- [Getting started with the GitHub Copilot app][getting-started]
+- [Working with agent sessions in the GitHub Copilot app][agent-sessions]
+
+[ex0]: 0-prerequisites.md
+[next-lesson]: 2-add-star-rating.md
+[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app
+[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started
+[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions
+[download-app]: https://gh.io/app

copilot-app/2-add-star-rating.md

@@ -0,0 +1,131 @@
+---
+title: "Lesson 2 - Running your first agent session"
+description: "Start your first agent session in the GitHub Copilot app, make a small change to the game cards, and merge it as your first pull request."
+---
+
+In the previous lesson you toured the workspace and used a quick chat. Now it's time to start an **agent session** and make your first change to the project. You'll keep it small: the games already have a star rating in their data, but the game cards on the home page don't show it yet. You'll ask the agent to surface it, review the change, and merge it as your first pull request.
+
+In this lesson, you will:
+
+- start an agent session and learn how a session is structured.
+- ask the agent to make a small, focused change to the project.
+- review the change in the workspace diff view.
+- run the app locally to confirm the change in the browser.
+- open and merge your first pull request.
+
+## Scenario
+
+Each game in Tailspin Toys can have a star rating, and it already appears on the game details page. The game cards on the home page, though, only show the title, category, publisher, and description. As a warm-up, you'll have the agent display the existing rating on each card — a tiny, self-contained change that's perfect for your first session.
+
+## Anatomy of a session
+
+A **session** is a conversation with an agent that runs in its own isolated workspace. Every session gets a **dedicated git worktree and branch**, which is what lets you run several sessions at once — one adding a feature, another fixing a bug — without their changes colliding. Your sessions appear in the sidebar grouped by repository; select any one to switch to it.
+
+Inside a session you'll see three things: the **conversation** with the agent, the agent's **tool activity** as it explores and edits files, and the list of **changed files** with their diffs.
+
+## Start a session and request our change
+
+Let's start a new session to begin exploring the project and implementing our feature. In a [prior lesson][prior-lesson] you added your project from its GitHub repository. We'll create a new session for that repository and request our change.
+
+1. Return to (or open) the GitHub Copilot app.
+2. Select the **Home screen**.
+3. Ensure `tailspin-toys` is selected for the repo.
+
+   ![The GitHub Copilot app prompt box with the repository selector set to tailspin-toys and the model selector shown beneath the prompt](images/app-2-start-session.png)
+
+4. Use the following prompt to request the change:
+
+   ```plaintext
+   On the game cards, show each game's star rating. The Game type already includes a starRating field — it's a number out of 5, or null when a game hasn't been rated yet. Display it on each card in src/components/GameCard.astro, and when starRating is null show "No rating yet" instead. Keep the change small and don't restructure the card layout.
+   ```
+
+> [!NOTE]
+> Notice how the prompt contained the name of the file for Copilot to update. While it's not required at all to specify which files Copilot should include in its work, pointing it in the right direction both helps Copilot quickly generate code and reduce token usage.
+
+5. Select <kbd>Enter</kbd> to send the prompt to Copilot.
+
+Copilot app begins work by first creating a new worktree, an isolated copy of the project. It then explores the project, locating the necessary files to update to add the new feature. It will then create the necessary code. You've now added a new feature with Copilot app!
+
+## Review the diff
+
+All AI-generated changes deserve a review before they're merged, even small ones. Let's explore the changes, right here in Copilot app.
+
+1. In the upper right-hand corner of the app, select **Toggle review panel**. This will open the diff screen with all the outstanding changes made by Copilot.
+
+   ![The GitHub Copilot app top toolbar with an arrow pointing to the Toggle review panel button to the right of Create PR](images/app-2-review-panel.png)
+
+2. You should notice code added to `GameCard.astro`, the core file used to display game details. It should be similar to the following — a small block that renders the rating when present and falls back to "No rating yet" when `starRating` is `null`:
+
+   ```astro
+   {game.starRating !== null ? (
+       <span class="text-xs font-medium px-2.5 py-0.5 rounded bg-amber-900/60 text-amber-300" data-testid="game-rating">
+           ★ {game.starRating} / 5
+       </span>
+   ) : (
+       <span class="text-xs font-medium text-slate-500" data-testid="game-rating-empty">
+           No rating yet
+       </span>
+   )}
+   ```
+
+> [!NOTE]
+> Because Copilot, like all generative AI tools, is probabilistic rather than deterministic, the exact code may vary from the above. But it should be relatively similar.
+
+## Check the changes
+
+Of course we shouldn't just read the code and assume it works. We should visually test everything as well! To do so we'll need to start the app from the terminal, then confirm everything works. Fortunately there's a terminal button in the upper right that will allow us quick access to the worktree the Copilot app created!
+
+1. In the upper right hand corner of the Copilot app, select **Open** next to the terminal icon.
+
+   ![The GitHub Copilot app top toolbar with an arrow pointing to the Open button next to the terminal icon](images/app-open-terminal.png)
+
+2. Enter the following command in the terminal window to start the web app's dev server:
+
+   ```shell
+   npm run dev
+   ```
+
+3. Once the server starts (this will just take a moment), open a browser window.
+4. Navigate to http://localhost:4321.
+5. You should now see star ratings on all the games on the landing page!
+6. Return to the terminal window.
+7. Select <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop the dev server.
+
+## Open and merge your first pull request
+
+Your change looks good — now it's time to ship it! You'll ask the agent to open a pull request, then review and merge it yourself on github.com. For now we'll manage this manually. In an upcoming lesson we'll explore how Copilot can handle some of the work for you automatically.
+
+1. In the upper right hand corner, select **Create PR**.
+2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate.
+3. Copilot gets to work on creating the PR.
+
+Once the PR is created, Copilot will monitor any workflows on the repository that need to run. After a few moments, the button in the upper right will change to **Ready to merge**. This will be your indication your PR is ready to merge!
+
+4. Select **Ready to merge**.
+5. Select **Merge pull request** on the new dialog window to merge your pull request!
+
+You've now pushed a new feature to the website!
+
+## Summary and next steps
+
+You've started your first agent session and shipped your first change! Specifically, you:
+
+- started an agent session and learned how sessions are structured.
+- directed the agent to make a small, focused change to the game cards.
+- reviewed the change in the workspace diff view.
+- ran the app locally to confirm the star rating in the browser.
+- opened a pull request and merged it yourself on github.com.
+
+Next, you'll use the app to add a custom instructions standard to the repository — starting from one of the issues in your backlog. Continue to [Lesson 3 - Guiding Copilot with custom instructions][next-lesson].
+
+## Resources
+
+- [Working with agent sessions in the GitHub Copilot app][agent-sessions]
+- [About the GitHub Copilot app][about-copilot-app]
+- [Managing issues and pull requests with the GitHub Copilot app][managing-issues-prs]
+
+[prior-lesson]: 1-install-copilot-app.md#install-and-configure-the-github-copilot-app
+[next-lesson]: 3-custom-instructions.md
+[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions
+[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app
+[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests