From a8d44f3cb4d06464339cecbd7c6b3e8684874f8e Mon Sep 17 00:00:00 2001 From: Pj Metz Date: Fri, 23 Oct 2026 13:29:18 -0700 Subject: [PATCH 1/3] Split Build instructions into combined tool guides Refs #50 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 16600baa-96ad-4836-8e96-6b34a1c9fbd9 --- README.md | 8 + src/components/build-guide-connect.astro | 24 +++ src/components/build-guide-continue.astro | 25 ++++ src/components/build-guide-idea.astro | 32 ++++ src/components/build-guide-panel.astro | 21 --- src/components/build-guide-test.astro | 44 ++++++ src/components/navigation-card.astro | 3 - src/components/navigation.tsx | 6 +- src/content/build-guides/01-copilot-app.mdx | 83 ++--------- src/content/build-guides/02-vscode.mdx | 82 ++--------- src/content/build-guides/03-copilot-cli.mdx | 94 ++++-------- .../build-guides/mac/01-copilot-app.mdx | 86 ----------- src/content/build-guides/mac/02-vscode.mdx | 87 ----------- .../build-guides/mac/03-copilot-cli.mdx | 95 ------------ src/layouts/BuildGuideLayout.astro | 36 +++++ src/lib/build-guide-navigation.ts | 14 ++ src/pages/build.astro | 138 ++---------------- src/pages/build/app.astro | 11 ++ src/pages/build/cli.astro | 11 ++ src/pages/build/vscode.astro | 11 ++ tests/build-guide-navigation.test.mjs | 26 ++++ 21 files changed, 316 insertions(+), 621 deletions(-) create mode 100644 src/components/build-guide-connect.astro create mode 100644 src/components/build-guide-continue.astro create mode 100644 src/components/build-guide-idea.astro delete mode 100644 src/components/build-guide-panel.astro create mode 100644 src/components/build-guide-test.astro delete mode 100644 src/content/build-guides/mac/01-copilot-app.mdx delete mode 100644 src/content/build-guides/mac/02-vscode.mdx delete mode 100644 src/content/build-guides/mac/03-copilot-cli.mdx create mode 100644 src/layouts/BuildGuideLayout.astro create mode 100644 src/lib/build-guide-navigation.ts create mode 100644 src/pages/build/app.astro create mode 100644 src/pages/build/cli.astro create mode 100644 src/pages/build/vscode.astro create mode 100644 tests/build-guide-navigation.test.mjs diff --git a/README.md b/README.md index 56456a0..c5b524c 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,14 @@ The **Apps** tab opens `/apps`, which contains the app store and USB/disk tools. Old `/edit` links redirect to `/apps`. The optional app-browsing catalog lives at `/browse-apps`. The Bluetooth editor is disabled by default. +## Build routes + +`/build` lists the build paths. The Copilot guides are at `/build/app`, +`/build/vscode`, and `/build/cli`, with Windows and macOS instructions together. +Shared steps live in `src/components/build-guide-*.astro`; tool-specific content +lives in `src/content/build-guides/`. Old tool and platform fragment links redirect +to the matching guide. + ## 🛠️ Tech Stack - **Framework**: [Astro](https://astro.build/) diff --git a/src/components/build-guide-connect.astro b/src/components/build-guide-connect.astro new file mode 100644 index 0000000..5a24c49 --- /dev/null +++ b/src/components/build-guide-connect.astro @@ -0,0 +1,24 @@ +

1. Connect the badge

+ +

+ Connect the badge to your computer with a USB cable that transfers data. + Leave it connected while Copilot works. You do not need to enter Disk Mode + before you start. +

+ +

+ When Copilot is ready to copy your app, hyb26-skill switches + the badge into USB Disk Mode. The badge restarts and + appears as a BADGER drive on your computer. This is expected. +

+ +

+ If automatic Disk Mode fails: quickly press + RESET twice, then ask Copilot to try again. + If it still cannot find BADGER, check the USB data cable and ask staff for help. +

+ +

+ If you see RP2350, stop: that drive is for firmware updates, + not apps. Do not copy files to it, erase the drive, or change the firmware. +

diff --git a/src/components/build-guide-continue.astro b/src/components/build-guide-continue.astro new file mode 100644 index 0000000..37c544f --- /dev/null +++ b/src/components/build-guide-continue.astro @@ -0,0 +1,25 @@ +

5. Continue building

+ +

+ Tell Copilot what you want to change. If the badge shows an error, give Copilot + the error message as best as you can and ask it to try to fix it. + If anything is unclear, ask a volunteer for help. +

+ +

+ Reconnect the badge if needed. The skill handles Disk Mode for the next copy; + follow Copilot's steps to copy and test the updated app. +

+ +

+ When updating your own app, tell Copilot it is an update so it uses the skill's + replacement option and keeps a backup. Do not replace someone else's app or + change shared badge files. +

+ +

+ If Copilot cannot copy your app, ask it for the full path to your checked app + folder and the correct BADGER destination. With Copilot's guidance, you can + copy that one folder in File Explorer on Windows or Finder on macOS, then + eject and test as above. Do not disable broad safety settings to give access. +

diff --git a/src/components/build-guide-idea.astro b/src/components/build-guide-idea.astro new file mode 100644 index 0000000..c065b1f --- /dev/null +++ b/src/components/build-guide-idea.astro @@ -0,0 +1,32 @@ +--- +import CopyPrompt from '@/components/copy-prompt.astro' +--- + +

3. Describe your app

+ +

+ Tell Copilot what you want to make in your local session and ask it to use + hyb26-skill. The prompt below is only an example. You do not need + to copy it or use it as written; describe your own idea in your own words. +

+ + + +

+ Answer Copilot's questions. If a permission request appears, check that it is + for your local project, the installed skill tools, or BADGER before allowing + it. You may still need to approve a tool action; the prompt does not bypass + those controls. Do not use an allow-everything option. +

+ +

+ On macOS, your tool may also ask for access to Documents or removable volumes. + Allow only access needed for this work; do not grant broad disk access or + disable safety settings. +

+ +

+ Copilot should check the app before copying it. If the skill, Python, or badge + tools are missing, or Copilot cannot identify the badge, ask staff for help + rather than skip the checks. +

diff --git a/src/components/build-guide-panel.astro b/src/components/build-guide-panel.astro deleted file mode 100644 index 97aef6e..0000000 --- a/src/components/build-guide-panel.astro +++ /dev/null @@ -1,21 +0,0 @@ ---- -interface Props { - title: string - id: string - tool: string -} - -const { title, id, tool } = Astro.props ---- - -
- - - {title} - - - -
- -
-
diff --git a/src/components/build-guide-test.astro b/src/components/build-guide-test.astro new file mode 100644 index 0000000..803bb52 --- /dev/null +++ b/src/components/build-guide-test.astro @@ -0,0 +1,44 @@ +

4. Test on your badge

+ +

+ Wait until Copilot says copying has finished. The skill can eject BADGER and + wait for the badge to restart into its menu. Follow Copilot's test steps: +

+ +
    +
  1. Open your app from the badge menu. If the menu has not returned after ejecting, press RESET once.
    2. +
  2. Try its screens and buttons, then press HOME to return to the menu.
    3. +
  3. If the app saves data, reopen it and check the data after a reset too.
    4. +
+ +

+ Copilot can check files and copy them, but it needs you to report what the + badge displays and how the controls work. Sensors and wireless features need + tests on the real badge; passing file checks does not prove they work. +

+ +

+ If you need to eject by hand, wait until copying has finished, + then use the steps for your computer: +

+ +

+ Windows: press Windows key + E + to open File Explorer. Under This PC, right-click + BADGER and choose Eject. Its drive letter may + differ between computers. +

+ +

+ macOS: open Finder and click the + Eject button beside BADGER under + Locations. If external disks are hidden, enable them in + Finder > Settings > Sidebar. +

+ +

+ Wait for BADGER to disappear. If it is still present and your computer says it + is in use, close files or terminals using the badge and try again; do not + force eject. The badge normally returns to its menu by itself. Press + RESET once if it does not. +

diff --git a/src/components/navigation-card.astro b/src/components/navigation-card.astro index afca10e..234a6a9 100644 --- a/src/components/navigation-card.astro +++ b/src/components/navigation-card.astro @@ -6,7 +6,6 @@ interface Props { icon: any id?: string compact?: boolean - dataBuildPath?: string } const { @@ -16,14 +15,12 @@ const { icon: Icon, id, compact = false, - dataBuildPath, } = Astro.props as Props --- ## 2. Open a local project in the Copilot App 1. Open the **GitHub Copilot App**. -2. Under **Projects**, select the **Badge Projects** folder prepared by staff. +2. Under **Projects**, select the **Badge Projects** folder prepared for you. 3. Start an **Interactive** session for that local project. -Use a local session on this PC, not a cloud session. A cloud session cannot -access the badge plugged into this PC. Use the project session, not a +Use a local session on your computer, not a cloud session. A cloud session cannot +access the badge plugged into your computer. Use the project session, not a general chat, so Copilot has a place to save your app. -## 3. Give the Copilot App your idea - -Tell Copilot what you want to make in the **local project session** and ask -it to use `hyb26-skill`. The prompt below is only an example. You do not need -to copy it or use it as written; describe your own idea in your own words. - - - -Answer Copilot's questions. If a permission request appears, check that it -is for your local project, the installed skill tools, or BADGER before -allowing it. You may still need to approve a tool action; the prompt does -not bypass those controls. - -Copilot should check the app before copying it. If the skill or Python is -missing, or Copilot cannot identify the badge, ask staff for help rather -than skip the checks. - -## 4. Test the Copilot App's result on your badge - -Wait until Copilot says copying has finished. Follow its test steps: - -1. In File Explorer, right-click **BADGER** and choose **Eject**. Wait until - Windows confirms it is safe to remove or the drive disappears. -2. Press **RESET** once. Open your app from the badge menu. -3. Try its screens and buttons, then press **HOME** to return to the menu. - If the app saves data, reopen it and check the data after a reset too. - -Copilot can check files and copy them, but it needs you to report what the -badge displays and how the controls work. Sensors and wireless features -need tests on the real badge; passing file checks does not prove they work. - -## 5. Continue in the Copilot App - -Tell Copilot what you want to change. If the badge shows an error, provide -the error message to Copilot as best as you can and ask it to try to fix -it. If anything is unclear, ask a volunteer for help. - -Before copying a fix, reconnect the badge if needed and press **RESET** -twice to return to Disk Mode. Follow Copilot's steps to copy and test the -updated app. + -When updating your own app, tell Copilot it is an update so it uses the -skill's replacement option and keeps a backup. Do not replace someone -else's app or change shared badge files. + -If Copilot cannot access BADGER, ask it for the full path to your checked -app folder and the correct destination. You can copy that one folder in -File Explorer as a fallback, then eject and test as above. Do not disable -broad safety settings to give access. + diff --git a/src/content/build-guides/02-vscode.mdx b/src/content/build-guides/02-vscode.mdx index 6acb556..711cf12 100644 --- a/src/content/build-guides/02-vscode.mdx +++ b/src/content/build-guides/02-vscode.mdx @@ -1,85 +1,35 @@ -import CopyPrompt from '@/components/copy-prompt.astro' +import ConnectBadge from '@/components/build-guide-connect.astro' +import DescribeApp from '@/components/build-guide-idea.astro' +import TestBadge from '@/components/build-guide-test.astro' +import ContinueBuilding from '@/components/build-guide-continue.astro' # Build with VS Code Describe your idea in Copilot Chat. Copilot builds the app and copies it to your connected badge. You test it on the badge. -The Windows PC already has `hyb26-skill`, a set of instructions and tools -that helps Copilot build apps for this badge. You do not need to install -the skill or write code yourself. +These steps work on Windows and macOS. They assume VS Code, GitHub Copilot, +Python 3.10 or newer, and `hyb26-skill` are already installed. The skill is +a set of instructions and tools that helps Copilot build apps for this badge. +Installation is not covered here. You do not need to write code yourself. -## 1. Connect the badge for VS Code - -1. Connect the badge to the PC with a USB cable that transfers data. -2. Quickly press the badge's **RESET** button twice. Wait for **USB Disk Mode**. -3. Press **Windows key + E** to open File Explorer. Select **This PC** and - find the **BADGER** drive. Windows adds a drive letter; yours may differ - from someone else's. -4. Leave the badge connected in Disk Mode while Copilot works. - -If BADGER does not appear, ask event staff for help. If you see **RP2350**, -stop: that drive is for firmware updates, not apps. Do not copy files to it -or change the firmware. + ## 2. Open Copilot Chat in VS Code -1. Open **VS Code** and use the **Badge Projects** folder prepared by staff. -2. Open **Copilot Chat** with **Ctrl + Alt + I**. +1. Open **VS Code** and use the **Badge Projects** folder prepared for you. +2. Open **Copilot Chat**. On **Windows**, press **Ctrl + Alt + I**. + On **macOS**, press **Control + Command + I**. 3. Start a new chat and select **Agent** so Copilot can create files and run - the badge tools. Work locally on this PC, not in a cloud session. + the badge tools. Work locally on your computer, not in a cloud session. If no folder is open, choose **File > Open Folder** and select **Badge Projects** in Documents. If it is missing, ask a volunteer for help. This folder is just a place to save your work. Copilot creates the app files inside it. You do not need a repository. -## 3. Give VS Code your app idea - -Tell **Copilot Chat** what you want to make and ask it to use `hyb26-skill`. -The prompt below is only an example. You do not need to copy it or use it -as written; describe your own idea in your own words. - - - -Answer Copilot's questions. If a permission request appears, check that it -is for your local project, the installed skill tools, or BADGER before -allowing it. You may still need to approve a tool action; the prompt does -not bypass those controls. - -Copilot should check the app before copying it. If the skill or Python is -missing, or Copilot cannot identify the badge, ask staff for help rather -than skip the checks. - -## 4. Test the app from VS Code on your badge - -Wait until Copilot says copying has finished. Follow its test steps: - -1. In File Explorer, right-click **BADGER** and choose **Eject**. Wait until - Windows confirms it is safe to remove or the drive disappears. -2. Press **RESET** once. Open your app from the badge menu. -3. Try its screens and buttons, then press **HOME** to return to the menu. - If the app saves data, reopen it and check the data after a reset too. - -Copilot can check files and copy them, but it needs you to report what the -badge displays and how the controls work. Sensors and wireless features -need tests on the real badge; passing file checks does not prove they work. - -## 5. Continue in VS Code - -Tell Copilot what you want to change. If the badge shows an error, provide -the error message to Copilot as best as you can and ask it to try to fix -it. If anything is unclear, ask a volunteer for help. - -Before copying a fix, reconnect the badge if needed and press **RESET** -twice to return to Disk Mode. Follow Copilot's steps to copy and test the -updated app. + -When updating your own app, tell Copilot it is an update so it uses the -skill's replacement option and keeps a backup. Do not replace someone -else's app or change shared badge files. + -If Copilot cannot access BADGER, ask it for the full path to your checked -app folder and the correct destination. You can copy that one folder in -File Explorer as a fallback, then eject and test as above. Do not disable -broad safety settings to give access. + diff --git a/src/content/build-guides/03-copilot-cli.mdx b/src/content/build-guides/03-copilot-cli.mdx index 77ca2c8..3f319f1 100644 --- a/src/content/build-guides/03-copilot-cli.mdx +++ b/src/content/build-guides/03-copilot-cli.mdx @@ -1,4 +1,7 @@ -import CopyPrompt from '@/components/copy-prompt.astro' +import ConnectBadge from '@/components/build-guide-connect.astro' +import DescribeApp from '@/components/build-guide-idea.astro' +import TestBadge from '@/components/build-guide-test.astro' +import ContinueBuilding from '@/components/build-guide-continue.astro' # Build with GitHub Copilot CLI @@ -6,87 +9,40 @@ Copilot CLI is Copilot in a terminal: a window where you type messages and commands. Describe your idea in plain language. Copilot builds the app and copies it to your connected badge. You test it on the badge. -The Windows PC already has `hyb26-skill`, a set of instructions and tools -that helps Copilot build apps for this badge. You do not need to install -the skill or write code yourself. +These steps work on Windows and macOS. They assume GitHub Copilot CLI, +Python 3.10 or newer, and `hyb26-skill` are already installed. The skill is +a set of instructions and tools that helps Copilot build apps for this badge. +Installation is not covered here. You do not need to write code yourself. -## 1. Connect the badge for Copilot CLI - -1. Connect the badge to the PC with a USB cable that transfers data. -2. Quickly press the badge's **RESET** button twice. Wait for **USB Disk Mode**. -3. Press **Windows key + E** to open File Explorer. Select **This PC** and - find the **BADGER** drive. Windows adds a drive letter; yours may differ - from someone else's. -4. Leave the badge connected in Disk Mode while Copilot works. - -If BADGER does not appear, ask event staff for help. If you see **RP2350**, -stop: that drive is for firmware updates, not apps. Do not copy files to it -or change the firmware. + ## 2. Open the prepared Copilot CLI session -1. Open the **Copilot CLI** terminal prepared by staff in the local **Badge +1. Open the **Copilot CLI** terminal prepared for you in the local **Badge Projects** folder. 2. If Copilot asks you to trust the folder, confirm it is the local **Badge Projects** folder before accepting. -3. Use the local session on this PC. Do not send the task to a cloud agent, +3. Use the local session on your computer. Do not send the task to a cloud agent, which cannot access the connected badge. -If no session is ready, open File Explorer and find **Badge Projects** in -Documents. If it is missing, ask a volunteer for help. Open the existing -folder, right-click an empty space, and choose **Open in Terminal**. -In PowerShell, type `copilot` and press **Enter** to start Copilot CLI. -If the command is not found, ask a volunteer for help. - -You do not need a repository or any other setup commands. Once Copilot is -running, type your request as a chat message, not as a PowerShell command. - -## 3. Give Copilot CLI your app idea - -Tell **Copilot CLI** what you want to make and ask it to use `hyb26-skill`. -The prompt below is only an example. You do not need to copy it or use it -as written; describe your own idea in your own words. +If no session is ready, find **Badge Projects** in Documents. If it is missing, +ask a volunteer for help. - +**Windows:** open the folder in File Explorer, right-click an empty space, +and choose **Open in Terminal**. In PowerShell, type `copilot` and press +**Enter**. -Answer Copilot's questions. If a permission request appears, check that it -is for your local project, the installed skill tools, or BADGER before -allowing it. You may still need to approve a tool action; the prompt does -not bypass those controls. Do not use an allow-everything option. +**macOS:** open **Terminal** from **Applications > Utilities**. Type `cd` +followed by a space, then drag **Badge Projects** from Finder into Terminal. +Press **Return**, then type `copilot` and press **Return** again. -Copilot should check the app before copying it. If the skill or Python is -missing, or Copilot cannot identify the badge, ask staff for help rather -than skip the checks. - -## 4. Test Copilot CLI's result on your badge - -Wait until Copilot says copying has finished. Follow its test steps: - -1. In File Explorer, right-click **BADGER** and choose **Eject**. Wait until - Windows confirms it is safe to remove or the drive disappears. -2. Press **RESET** once. Open your app from the badge menu. -3. Try its screens and buttons, then press **HOME** to return to the menu. - If the app saves data, reopen it and check the data after a reset too. - -Copilot can check files and copy them, but it needs you to report what the -badge displays and how the controls work. Sensors and wireless features -need tests on the real badge; passing file checks does not prove they work. - -## 5. Continue in Copilot CLI +If the command is not found, ask a volunteer for help. -Tell Copilot what you want to change. If the badge shows an error, provide -the error message to Copilot as best as you can and ask it to try to fix -it. If anything is unclear, ask a volunteer for help. +You do not need a repository or any other setup commands. Once Copilot is +running, type your request as a chat message, not as a terminal command. -Before copying a fix, reconnect the badge if needed and press **RESET** -twice to return to Disk Mode. Follow Copilot's steps to copy and test the -updated app. + -When updating your own app, tell Copilot it is an update so it uses the -skill's replacement option and keeps a backup. Do not replace someone -else's app or change shared badge files. + -If Copilot cannot access BADGER, ask it for the full path to your checked -app folder and the correct destination. You can copy that one folder in -File Explorer as a fallback, then eject and test as above. Do not disable -broad safety settings to give access. + diff --git a/src/content/build-guides/mac/01-copilot-app.mdx b/src/content/build-guides/mac/01-copilot-app.mdx deleted file mode 100644 index 6318655..0000000 --- a/src/content/build-guides/mac/01-copilot-app.mdx +++ /dev/null @@ -1,86 +0,0 @@ -import CopyPrompt from '@/components/copy-prompt.astro' - -# Build with the GitHub Copilot App on Mac - -Describe your idea in the GitHub Copilot desktop app. Copilot builds the -app and copies it to your connected badge. You test it on the badge. - -These steps assume the GitHub Copilot App, Python 3.10 or newer, and the -Mac version of `hyb26-skill` are already installed. The skill is a set of -instructions and tools that helps Copilot build apps for this badge. -Skill installation is not covered here. Use the **GitHub Copilot** app, -not Microsoft Copilot. You do not need to write code yourself. - -## 1. Connect the badge for the Copilot App on Mac - -1. Connect the badge to your Mac with a USB cable that transfers data. -2. Quickly press the badge's **RESET** button twice. Wait for **USB Disk Mode**. -3. Open **Finder** and look for **BADGER** under **Locations** in the sidebar. - If external disks are hidden, turn them on in **Finder > Settings > Sidebar**. -4. Leave the badge connected in Disk Mode while Copilot works. - -If BADGER does not appear, check the cable and connection before continuing. -If you see **RP2350**, stop: that drive is for firmware updates, not apps. -Do not copy files to it, erase the drive, or change the firmware. - -## 2. Open a local Copilot App project on Mac - -1. Open the **GitHub Copilot App**. -2. Under **Projects**, select the **Badge Projects** folder prepared for you. -3. Start an **Interactive** session for that local project. - -Use a local session on this Mac, not a cloud session. A cloud session cannot -access the badge plugged into your Mac. Use the project session, not a -general chat, so Copilot has a place to save your app. - -## 3. Give the Copilot App your Mac idea - -Tell Copilot what you want to make in the **local project session** and ask -it to use `hyb26-skill`. The prompt below is only an example. You do not need -to copy it or use it as written; describe your own idea in your own words. - - - -Answer Copilot's questions. If a permission request appears, check that it -is for your local project, the installed skill tools, or BADGER before -allowing it. macOS may also ask to let the app access Documents or removable -volumes. Allow only access needed for this work; do not grant broad disk -access or disable safety settings. - -Copilot should check the app before copying it. If the skill or Python is -missing, or Copilot cannot identify the badge, ask staff for help rather -than skip the checks. - -## 4. Test the Copilot App's result on your Mac-connected badge - -Wait until Copilot says copying has finished. Follow its test steps: - -1. In Finder, click the **Eject** button next to **BADGER**. Wait until - BADGER disappears from the sidebar. If macOS says it is in use, close - files or terminals using the badge and try again; do not force eject. -2. Press **RESET** once. Open your app from the badge menu. -3. Try its screens and buttons, then press **HOME** to return to the menu. - If the app saves data, reopen it and check the data after a reset too. - -Copilot can check files and copy them, but it needs you to report what the -badge displays and how the controls work. Sensors and wireless features -need tests on the real badge; passing file checks does not prove they work. - -## 5. Continue in the Copilot App on Mac - -Tell Copilot what you want to change. If the badge shows an error, provide -the error message to Copilot as best as you can and ask it to try to fix -it. If anything is unclear, ask a volunteer for help. - -Before copying a fix, reconnect the badge if needed and press **RESET** -twice to return to Disk Mode. Follow Copilot's steps to copy and test the -updated app. - -When updating your own app, tell Copilot it is an update so it uses the -skill's replacement option and keeps a backup. Do not replace someone -else's app or change shared badge files. - -If Copilot cannot access BADGER, ask it for the full path to your checked -app folder and the correct destination. You can copy that one folder in -Finder as a fallback, then eject and test as above. Do not disable broad -safety settings to give access. diff --git a/src/content/build-guides/mac/02-vscode.mdx b/src/content/build-guides/mac/02-vscode.mdx deleted file mode 100644 index 1a85e83..0000000 --- a/src/content/build-guides/mac/02-vscode.mdx +++ /dev/null @@ -1,87 +0,0 @@ -import CopyPrompt from '@/components/copy-prompt.astro' - -# Build with VS Code on Mac - -Describe your idea in Copilot Chat. Copilot builds the app and copies it to -your connected badge. You test it on the badge. - -These steps assume VS Code, GitHub Copilot, Python 3.10 or newer, and the -Mac version of `hyb26-skill` are already installed. The skill is a set of -instructions and tools that helps Copilot build apps for this badge. -Skill installation is not covered here. You do not need to write code yourself. - -## 1. Connect the badge for VS Code on Mac - -1. Connect the badge to your Mac with a USB cable that transfers data. -2. Quickly press the badge's **RESET** button twice. Wait for **USB Disk Mode**. -3. Open **Finder** and look for **BADGER** under **Locations** in the sidebar. - If external disks are hidden, turn them on in **Finder > Settings > Sidebar**. -4. Leave the badge connected in Disk Mode while Copilot works. - -If BADGER does not appear, check the cable and connection before continuing. -If you see **RP2350**, stop: that drive is for firmware updates, not apps. -Do not copy files to it, erase the drive, or change the firmware. - -## 2. Open Copilot Chat on Mac - -1. Open **VS Code** and use the **Badge Projects** folder prepared for you. -2. Open **Copilot Chat** with **Control + Command + I**. -3. Start a new chat and select **Agent** so Copilot can create files and run - the badge tools. Work locally on this Mac, not in a cloud session. - -If no folder is open, choose **File > Open Folder** and select **Badge -Projects** in Documents. If it is missing, ask a volunteer for help. -This folder is just a place to save your work. Copilot creates the app -files inside it. You do not need a repository. - -## 3. Give VS Code your Mac app idea - -Tell **Copilot Chat** what you want to make and ask it to use `hyb26-skill`. -The prompt below is only an example. You do not need to copy it or use it -as written; describe your own idea in your own words. - - - -Answer Copilot's questions. If a permission request appears, check that it -is for your local project, the installed skill tools, or BADGER before -allowing it. macOS may also ask to let VS Code access Documents or removable -volumes. Allow only access needed for this work; do not grant broad disk -access or disable safety settings. - -Copilot should check the app before copying it. If the skill or Python is -missing, or Copilot cannot identify the badge, ask staff for help rather -than skip the checks. - -## 4. Test the VS Code app on your Mac-connected badge - -Wait until Copilot says copying has finished. Follow its test steps: - -1. In Finder, click the **Eject** button next to **BADGER**. Wait until - BADGER disappears from the sidebar. If macOS says it is in use, close - files or terminals using the badge and try again; do not force eject. -2. Press **RESET** once. Open your app from the badge menu. -3. Try its screens and buttons, then press **HOME** to return to the menu. - If the app saves data, reopen it and check the data after a reset too. - -Copilot can check files and copy them, but it needs you to report what the -badge displays and how the controls work. Sensors and wireless features -need tests on the real badge; passing file checks does not prove they work. - -## 5. Continue in VS Code on Mac - -Tell Copilot what you want to change. If the badge shows an error, provide -the error message to Copilot as best as you can and ask it to try to fix -it. If anything is unclear, ask a volunteer for help. - -Before copying a fix, reconnect the badge if needed and press **RESET** -twice to return to Disk Mode. Follow Copilot's steps to copy and test the -updated app. - -When updating your own app, tell Copilot it is an update so it uses the -skill's replacement option and keeps a backup. Do not replace someone -else's app or change shared badge files. - -If Copilot cannot access BADGER, ask it for the full path to your checked -app folder and the correct destination. You can copy that one folder in -Finder as a fallback, then eject and test as above. Do not disable broad -safety settings to give access. diff --git a/src/content/build-guides/mac/03-copilot-cli.mdx b/src/content/build-guides/mac/03-copilot-cli.mdx deleted file mode 100644 index e8df3fd..0000000 --- a/src/content/build-guides/mac/03-copilot-cli.mdx +++ /dev/null @@ -1,95 +0,0 @@ -import CopyPrompt from '@/components/copy-prompt.astro' - -# Build with GitHub Copilot CLI on Mac - -Copilot CLI is Copilot in a terminal: a window where you type messages and -commands. Describe your idea in plain language. Copilot builds the app and -copies it to your connected badge. You test it on the badge. - -These steps assume GitHub Copilot CLI, Python 3.10 or newer, and the Mac -version of `hyb26-skill` are already installed. The skill is a set of -instructions and tools that helps Copilot build apps for this badge. -Skill installation is not covered here. You do not need to write code yourself. - -## 1. Connect the badge for Copilot CLI on Mac - -1. Connect the badge to your Mac with a USB cable that transfers data. -2. Quickly press the badge's **RESET** button twice. Wait for **USB Disk Mode**. -3. Open **Finder** and look for **BADGER** under **Locations** in the sidebar. - If external disks are hidden, turn them on in **Finder > Settings > Sidebar**. -4. Leave the badge connected in Disk Mode while Copilot works. - -If BADGER does not appear, check the cable and connection before continuing. -If you see **RP2350**, stop: that drive is for firmware updates, not apps. -Do not copy files to it, erase the drive, or change the firmware. - -## 2. Start a local Copilot CLI session on Mac - -1. Open the **Copilot CLI** terminal prepared for you in the local **Badge - Projects** folder. -2. If Copilot asks you to trust the folder, confirm it is the local **Badge - Projects** folder before accepting. -3. Use the local session on this Mac. Do not send the task to a cloud agent, - which cannot access the connected badge. - -If no session is ready, open Finder and find **Badge Projects** in Documents. -If it is missing, ask a volunteer for help. Open **Terminal** from -Applications > Utilities. Type `cd` followed by a space, then drag your -**Badge Projects** folder from Finder into Terminal. Press **Return** to use -that folder. Type `copilot` and press **Return** to start Copilot CLI. If the -command is not found, ask a volunteer for help. - -You do not need a repository or any other setup commands. Once Copilot is -running, type your request as a chat message, not as a Terminal command. - -## 3. Give Copilot CLI your Mac app idea - -Tell **Copilot CLI** what you want to make and ask it to use `hyb26-skill`. -The prompt below is only an example. You do not need to copy it or use it -as written; describe your own idea in your own words. - - - -Answer Copilot's questions. If a permission request appears, check that it -is for your local project, the installed skill tools, or BADGER before -allowing it. macOS may also ask to let Terminal access Documents or removable -volumes. Allow only access needed for this work; do not grant broad disk -access or disable safety settings. Do not use an allow-everything option. - -Copilot should check the app before copying it. If the skill or Python is -missing, or Copilot cannot identify the badge, ask staff for help rather -than skip the checks. - -## 4. Test Copilot CLI's result on your Mac-connected badge - -Wait until Copilot says copying has finished. Follow its test steps: - -1. In Finder, click the **Eject** button next to **BADGER**. Wait until - BADGER disappears from the sidebar. If macOS says it is in use, close - files or terminals using the badge and try again; do not force eject. -2. Press **RESET** once. Open your app from the badge menu. -3. Try its screens and buttons, then press **HOME** to return to the menu. - If the app saves data, reopen it and check the data after a reset too. - -Copilot can check files and copy them, but it needs you to report what the -badge displays and how the controls work. Sensors and wireless features -need tests on the real badge; passing file checks does not prove they work. - -## 5. Continue in Copilot CLI on Mac - -Tell Copilot what you want to change. If the badge shows an error, provide -the error message to Copilot as best as you can and ask it to try to fix -it. If anything is unclear, ask a volunteer for help. - -Before copying a fix, reconnect the badge if needed and press **RESET** -twice to return to Disk Mode. Follow Copilot's steps to copy and test the -updated app. - -When updating your own app, tell Copilot it is an update so it uses the -skill's replacement option and keeps a backup. Do not replace someone -else's app or change shared badge files. - -If Copilot cannot access BADGER, ask it for the full path to your checked -app folder and the correct destination. You can copy that one folder in -Finder as a fallback, then eject and test as above. Do not disable broad -safety settings to give access. diff --git a/src/layouts/BuildGuideLayout.astro b/src/layouts/BuildGuideLayout.astro new file mode 100644 index 0000000..f02357c --- /dev/null +++ b/src/layouts/BuildGuideLayout.astro @@ -0,0 +1,36 @@ +--- +import Layout from '@/layouts/Layout.astro' +import { ArrowLeft } from 'lucide-react' + +interface Props { + title: string + description: string +} + +const { title, description } = Astro.props +--- + + +
+
+ + +
+ +
+
+
+ + + diff --git a/src/lib/build-guide-navigation.ts b/src/lib/build-guide-navigation.ts new file mode 100644 index 0000000..9d3a1b4 --- /dev/null +++ b/src/lib/build-guide-navigation.ts @@ -0,0 +1,14 @@ +const guidePaths = new Map([ + ['copilot-app', '/build/app'], + ['vscode', '/build/vscode'], + ['copilot-cli', '/build/cli'], +]) + +export function legacyBuildGuidePath(fragment: string) { + try { + const tool = decodeURIComponent(fragment.replace(/^#/, '')).replace(/^(windows|mac)-/, '') + return guidePaths.get(tool) + } catch { + return undefined + } +} diff --git a/src/pages/build.astro b/src/pages/build.astro index 9fb2194..aa10d4c 100644 --- a/src/pages/build.astro +++ b/src/pages/build.astro @@ -1,58 +1,30 @@ --- import Layout from '@/layouts/Layout.astro' import ListingHero from '@/components/listing-hero.astro' -import BuildGuidePanel from '@/components/build-guide-panel.astro' import NavigationCard from '@/components/navigation-card.astro' -import VSCodeGuide from '@/content/build-guides/02-vscode.mdx' -import CopilotAppGuide from '@/content/build-guides/01-copilot-app.mdx' -import CopilotCLIGuide from '@/content/build-guides/03-copilot-cli.mdx' -import MacVSCodeGuide from '@/content/build-guides/mac/02-vscode.mdx' -import MacCopilotAppGuide from '@/content/build-guides/mac/01-copilot-app.mdx' -import MacCopilotCLIGuide from '@/content/build-guides/mac/03-copilot-cli.mdx' import { BookOpen, Code2, Laptop, MonitorPlay, Terminal } from 'lucide-react' -const platforms = [ - { - id: 'windows', - label: 'Windows', - guides: [ - { id: 'copilot-app', title: 'Build with the GitHub Copilot App', Content: CopilotAppGuide }, - { id: 'vscode', title: 'Build with VS Code', Content: VSCodeGuide }, - { id: 'copilot-cli', title: 'Build with GitHub Copilot CLI', Content: CopilotCLIGuide }, - ], - }, - { - id: 'mac', - label: 'macOS', - guides: [ - { id: 'copilot-app', title: 'Build with the GitHub Copilot App', Content: MacCopilotAppGuide }, - { id: 'vscode', title: 'Build with VS Code', Content: MacVSCodeGuide }, - { id: 'copilot-cli', title: 'Build with GitHub Copilot CLI', Content: MacCopilotCLIGuide }, - ], - }, -] - const buildPaths = [ { - href: '#copilot-app', + id: 'copilot-app', + href: '/build/app', title: 'Copilot App', description: 'Describe an app in the desktop app and copy it to a connected badge.', icon: Laptop, - dataBuildPath: 'copilot-app', }, { - href: '#vscode', + id: 'vscode', + href: '/build/vscode', title: 'VS Code', description: 'Build locally with Copilot Chat and the prepared badge tools.', icon: Code2, - dataBuildPath: 'vscode', }, { - href: '#copilot-cli', + id: 'copilot-cli', + href: '/build/cli', title: 'Copilot CLI', description: 'Build from a local terminal using plain-language instructions.', icon: Terminal, - dataBuildPath: 'copilot-cli', }, { href: '/simulator', @@ -72,11 +44,11 @@ const buildPaths = [ -
+

Choose a build path

@@ -90,98 +62,16 @@ const buildPaths = [
-
-
- -
- - -
- {platforms.map(({ id, label, guides }) => ( - - ))} -
-
diff --git a/src/pages/build/app.astro b/src/pages/build/app.astro new file mode 100644 index 0000000..c1f90a5 --- /dev/null +++ b/src/pages/build/app.astro @@ -0,0 +1,11 @@ +--- +import BuildGuideLayout from '@/layouts/BuildGuideLayout.astro' +import CopilotAppGuide from '@/content/build-guides/01-copilot-app.mdx' +--- + + + + diff --git a/src/pages/build/cli.astro b/src/pages/build/cli.astro new file mode 100644 index 0000000..48c213b --- /dev/null +++ b/src/pages/build/cli.astro @@ -0,0 +1,11 @@ +--- +import BuildGuideLayout from '@/layouts/BuildGuideLayout.astro' +import CopilotCLIGuide from '@/content/build-guides/03-copilot-cli.mdx' +--- + + + + diff --git a/src/pages/build/vscode.astro b/src/pages/build/vscode.astro new file mode 100644 index 0000000..7d3e116 --- /dev/null +++ b/src/pages/build/vscode.astro @@ -0,0 +1,11 @@ +--- +import BuildGuideLayout from '@/layouts/BuildGuideLayout.astro' +import VSCodeGuide from '@/content/build-guides/02-vscode.mdx' +--- + + + + diff --git a/tests/build-guide-navigation.test.mjs b/tests/build-guide-navigation.test.mjs new file mode 100644 index 0000000..6966574 --- /dev/null +++ b/tests/build-guide-navigation.test.mjs @@ -0,0 +1,26 @@ +import { fileURLToPath } from 'node:url' +import { test } from 'node:test' +import assert from 'node:assert/strict' +import { build } from 'esbuild' + +const compiled = await build({ entryPoints: [fileURLToPath(new URL('../src/lib/build-guide-navigation.ts', import.meta.url))], bundle: true, format: 'esm', platform: 'node', write: false }) +const { legacyBuildGuidePath } = await import(`data:text/javascript;base64,${Buffer.from(compiled.outputFiles[0].text).toString('base64')}`) + +test('old tool and platform links open the matching combined guide', () => { + for (const prefix of ['', 'windows-', 'mac-']) { + assert.equal(legacyBuildGuidePath(`#${prefix}copilot-app`), '/build/app') + assert.equal(legacyBuildGuidePath(`#${prefix}vscode`), '/build/vscode') + assert.equal(legacyBuildGuidePath(`#${prefix}copilot-cli`), '/build/cli') + } +}) + +test('encoded old guide fragments are recognized', () => { + assert.equal(legacyBuildGuidePath('#mac%2Dvscode'), '/build/vscode') + assert.equal(legacyBuildGuidePath('#%63opilot-app'), '/build/app') +}) + +test('ordinary visits, unknown fragments, and malformed encodings stay on Build', () => { + for (const fragment of ['', '#', '#local-build-guides', '#other', '#constructor', '#__proto__', '#%E0%A4%A', '#/build/app']) { + assert.equal(legacyBuildGuidePath(fragment), undefined) + } +}) From 3db03f4168e8b926450a2e9f48938ef8e06822b8 Mon Sep 17 00:00:00 2001 From: Pj Metz Date: Sat, 24 Oct 2026 19:41:01 -0700 Subject: [PATCH 2/3] Keep guide URL cases in the existing guide tests Cover root and prefixed deployments, including encoded and invalid old links. Avoid overlapping the catalog PR's additions to the shared site-path tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 16600baa-96ad-4836-8e96-6b34a1c9fbd9 --- tests/build-guide-navigation.test.mjs | 45 ++++++++++++++++----------- tests/site-paths.test.mjs | 9 ------ 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/tests/build-guide-navigation.test.mjs b/tests/build-guide-navigation.test.mjs index 6966574..fa6841c 100644 --- a/tests/build-guide-navigation.test.mjs +++ b/tests/build-guide-navigation.test.mjs @@ -3,24 +3,33 @@ import { test } from 'node:test' import assert from 'node:assert/strict' import { build } from 'esbuild' -const compiled = await build({ entryPoints: [fileURLToPath(new URL('../src/lib/build-guide-navigation.ts', import.meta.url))], bundle: true, format: 'esm', platform: 'node', write: false }) -const { legacyBuildGuidePath } = await import(`data:text/javascript;base64,${Buffer.from(compiled.outputFiles[0].text).toString('base64')}`) +for (const base of ['/', '/badger.github.io/']) { + const compiled = await build({ + entryPoints: [fileURLToPath(new URL('../src/lib/build-guide-navigation.ts', import.meta.url))], + bundle: true, + format: 'esm', + platform: 'node', + write: false, + define: { 'import.meta.env.BASE_URL': JSON.stringify(base) }, + }) + const { legacyBuildGuidePath } = await import(`data:text/javascript;base64,${Buffer.from(compiled.outputFiles[0].text).toString('base64')}`) -test('old tool and platform links open the matching combined guide', () => { - for (const prefix of ['', 'windows-', 'mac-']) { - assert.equal(legacyBuildGuidePath(`#${prefix}copilot-app`), '/build/app') - assert.equal(legacyBuildGuidePath(`#${prefix}vscode`), '/build/vscode') - assert.equal(legacyBuildGuidePath(`#${prefix}copilot-cli`), '/build/cli') - } -}) + test(`old tool and platform links open the matching combined guide under ${base}`, () => { + for (const prefix of ['', 'windows-', 'mac-']) { + assert.equal(legacyBuildGuidePath(`#${prefix}copilot-app`), `${base}build/app`) + assert.equal(legacyBuildGuidePath(`#${prefix}vscode`), `${base}build/vscode`) + assert.equal(legacyBuildGuidePath(`#${prefix}copilot-cli`), `${base}build/cli`) + } + }) -test('encoded old guide fragments are recognized', () => { - assert.equal(legacyBuildGuidePath('#mac%2Dvscode'), '/build/vscode') - assert.equal(legacyBuildGuidePath('#%63opilot-app'), '/build/app') -}) + test(`encoded old guide fragments are recognized under ${base}`, () => { + assert.equal(legacyBuildGuidePath('#mac%2Dvscode'), `${base}build/vscode`) + assert.equal(legacyBuildGuidePath('#%63opilot-app'), `${base}build/app`) + }) -test('ordinary visits, unknown fragments, and malformed encodings stay on Build', () => { - for (const fragment of ['', '#', '#local-build-guides', '#other', '#constructor', '#__proto__', '#%E0%A4%A', '#/build/app']) { - assert.equal(legacyBuildGuidePath(fragment), undefined) - } -}) + test(`ordinary visits, unknown fragments, and malformed encodings stay on Build under ${base}`, () => { + for (const fragment of ['', '#', '#local-build-guides', '#other', '#constructor', '#__proto__', '#%E0%A4%A', '#/build/app']) { + assert.equal(legacyBuildGuidePath(fragment), undefined) + } + }) +} diff --git a/tests/site-paths.test.mjs b/tests/site-paths.test.mjs index d2f3457..439deca 100644 --- a/tests/site-paths.test.mjs +++ b/tests/site-paths.test.mjs @@ -29,15 +29,6 @@ for (const base of ['/', '/badger.github.io/']) { } }) - test(`old build guide links respect the deployment base ${base}`, async () => { - const { legacyBuildGuidePath } = await compileModule('../src/lib/build-guide-navigation.ts', base) - for (const prefix of ['', 'windows-', 'mac-']) { - for (const [tool, guide] of [['copilot-app', 'app'], ['vscode', 'vscode'], ['copilot-cli', 'cli']]) { - assert.equal(legacyBuildGuidePath(`#${prefix}${tool}`), `${base}build/${guide}`) - } - } - }) - test(`Doom fetches manifest, WAD, and manifest artifacts under ${base}`, async () => { const { loadDoomRuntime } = await compileModule('../src/lib/doom-runtime.ts', base) const manifest = JSON.parse(await readFile( From 4305efa4247f83de738da6ad83a0184ffb45638d Mon Sep 17 00:00:00 2001 From: Pj Metz Date: Sat, 24 Oct 2026 19:43:09 -0700 Subject: [PATCH 3/3] Check deployment commands instead of a renamed step label Retain main's build-and-URL-verification step name. Assert that required Doom verification runs before the actual build command, avoiding unnecessary workflow conflicts between the website PRs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 16600baa-96ad-4836-8e96-6b34a1c9fbd9 --- .github/workflows/deploy.yml | 2 +- tests/doom-provisioning.test.mjs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 1e9fe37..84632e0 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -32,7 +32,7 @@ jobs: uses: actions/configure-pages@v5 - name: Verify Doom runtime and shareware assets run: npm run verify:doom-assets -- --require - - name: Build site + - name: Build and verify site URLs run: | npm run build node scripts/verify-site-paths.mjs "$BASE_PATH" "$SITE_URL" diff --git a/tests/doom-provisioning.test.mjs b/tests/doom-provisioning.test.mjs index e7c3c6f..3bd197b 100644 --- a/tests/doom-provisioning.test.mjs +++ b/tests/doom-provisioning.test.mjs @@ -95,7 +95,7 @@ test('CI and deployment verify committed pinned assets before building', () => { assert.match(runtimeBuild, /postMainLoop\(\)/) assert.match(runtimeBuild, /preserveDrawingBuffer = true/) assert.doesNotMatch(runtimeBuild, /framePump/) - assert.match(deploy, /Verify Doom runtime and shareware assets[\s\S]*verify:doom-assets -- --require[\s\S]*Build site/) + assert.match(deploy, /Verify Doom runtime and shareware assets[\s\S]*verify:doom-assets -- --require[\s\S]*run:\s*(?:\|\s*)?npm run build\b/) assert.match(ci, /Verify Doom runtime and shareware assets[\s\S]*verify:doom-assets -- --require[\s\S]*name: Build/) assert.doesNotMatch(deploy, /DOOM_RUNTIME_ENABLED|DOOM_WAD_B64|releases\/latest|\/latest(?:\/|$)/) assert.match(readme, /committed/)