avni · Oct 26, 2026 · Oct 23, 2026 · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026
diff --git 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
@@ -0,0 +1,24 @@
+<h2 id="connect-the-badge">1. Connect the badge</h2>
+
+<p>
+  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.
+</p>
+
+<p>
+  When Copilot is ready to copy your app, <code>hyb26-skill</code> switches
+  the badge into <strong>USB Disk Mode</strong>. The badge restarts and
+  appears as a <strong>BADGER</strong> drive on your computer. This is expected.
+</p>
+
+<p>
+  <strong>If automatic Disk Mode fails:</strong> quickly press
+  <strong>RESET</strong> twice, then ask Copilot to try again.
+  If it still cannot find BADGER, check the USB data cable and ask staff for help.
+</p>
+
+<p>
+  If you see <strong>RP2350</strong>, stop: that drive is for firmware updates,
+  not apps. Do not copy files to it, erase the drive, or change the firmware.
+</p>
diff --git a/src/components/build-guide-continue.astro b/src/components/build-guide-continue.astro
@@ -0,0 +1,25 @@
+<h2 id="continue-building">5. Continue building</h2>
+
+<p>
+  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.
+</p>
+
+<p>
+  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.
+</p>
+
+<p>
+  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.
+</p>
+
+<p>
+  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.
+</p>
diff --git a/src/components/build-guide-idea.astro b/src/components/build-guide-idea.astro
@@ -0,0 +1,32 @@
+---
+import CopyPrompt from '@/components/copy-prompt.astro'
+---
+
+<h2 id="describe-your-app">3. Describe your app</h2>
+
+<p>
+  Tell Copilot what you want to make in your local session and ask it to use
+  <code>hyb26-skill</code>. 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.
+</p>
+
+<CopyPrompt prompt="Use hyb26-skill to make a badge app with a counter that increases when I press SELECT. Walk me through anything I need to do with the badge using plain English." />
+
+<p>
+  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.
+</p>
+
+<p>
+  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.
+</p>
+
+<p>
+  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.
+</p>
diff --git a/src/components/build-guide-panel.astro b/src/components/build-guide-panel.astro
diff --git a/src/components/build-guide-test.astro b/src/components/build-guide-test.astro
@@ -0,0 +1,44 @@
+<h2 id="test-on-your-badge">4. Test on your badge</h2>
+
+<p>
+  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:
+</p>
+
+<ol>
+  <li>Open your app from the badge menu. If the menu has not returned after ejecting, press <strong>RESET</strong> once.</li>
+  <li>Try its screens and buttons, then press <strong>HOME</strong> to return to the menu.</li>
+  <li>If the app saves data, reopen it and check the data after a reset too.</li>
+</ol>
+
+<p>
+  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.
+</p>
+
+<p>
+  <strong>If you need to eject by hand,</strong> wait until copying has finished,
+  then use the steps for your computer:
+</p>
+
+<p>
+  <strong class="font-mono">Windows:</strong> press <strong>Windows key + E</strong>
+  to open File Explorer. Under <strong>This PC</strong>, right-click
+  <strong>BADGER</strong> and choose <strong>Eject</strong>. Its drive letter may
+  differ between computers.
+</p>
+
+<p>
+  <strong class="font-mono">macOS:</strong> open Finder and click the
+  <strong>Eject</strong> button beside <strong>BADGER</strong> under
+  <strong>Locations</strong>. If external disks are hidden, enable them in
+  <strong>Finder &gt; Settings &gt; Sidebar</strong>.
+</p>
+
+<p>
+  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
+  <strong>RESET</strong> once if it does not.
+</p>
diff --git a/src/components/navigation-card.astro b/src/components/navigation-card.astro
@@ -8,7 +8,6 @@ interface Props {
   icon: any
   id?: string
   compact?: boolean
-  dataBuildPath?: string
 }
 
 const {
@@ -18,14 +17,12 @@ const {
   icon: Icon,
   id,
   compact = false,
-  dataBuildPath,
 } = Astro.props as Props
 ---
 
 <a
   id={id}
   href={sitePath(href)}
-  data-build-path={dataBuildPath}
   class:list={[
     'surface surface-hover group flex min-w-0 items-start gap-3 scroll-mt-28 no-underline',
     compact ? 'p-4' : 'p-5',

diff --git a/src/components/navigation.tsx b/src/components/navigation.tsx
@@ -78,9 +78,9 @@ const navigationGroups: NavigationGroup[] = [
     icon: Hammer,
     matches: ['/build', '/simulator', '/editor', '/hacks', '/hack'],
     items: [
-      { href: '/build#copilot-app', label: 'Copilot App', description: 'Build in the desktop app' },
-      { href: '/build#vscode', label: 'VS Code', description: 'Build with Copilot Chat' },
-      { href: '/build#copilot-cli', label: 'Copilot CLI', description: 'Build from a terminal' },
+      { href: '/build/app', label: 'Copilot App', description: 'Build in the desktop app' },
+      { href: '/build/vscode', label: 'VS Code', description: 'Build with Copilot Chat' },
+      { href: '/build/cli', label: 'Copilot CLI', description: 'Build from a terminal' },
       { href: '/simulator', label: 'Developer Simulator', description: 'Edit MonaOS live in the browser' },
       { href: '/hacks', label: 'Start From a Hack', description: 'Follow a prepared project' },
     ],

diff --git a/src/content/build-guides/01-copilot-app.mdx b/src/content/build-guides/01-copilot-app.mdx
@@ -1,84 +1,33 @@
-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 the GitHub Copilot App
 
 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.
 
-The Windows PC already has `hyb26-skill`, a set of instructions and tools
-that helps Copilot build apps for this badge. Use the **GitHub Copilot**
-app, not Microsoft Copilot. You do not need to install the skill or write
-code yourself.
+These steps work on Windows and macOS. They assume the GitHub Copilot App,
+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. Use the **GitHub Copilot** app, not
+Microsoft Copilot. You do not need to write code yourself.
 
-## 1. Connect the badge for the Copilot App
-
-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.
+<ConnectBadge />
 
 ## 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.
-
-<CopyPrompt prompt="Use hyb26-skill to make a badge app with a counter that increases when I press SELECT. Walk me through anything I need to do with the badge using plain English." />
-
-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.
+<DescribeApp />
 
-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.
+<TestBadge />
 
-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.
+<ContinueBuilding />