Add repo scaffolding for Colorado-Mesh publish

Adds the project metadata and CI/release workflow needed to publish this
repo under Colorado-Mesh/meshcore-bot-firmware.

- LICENSE: MIT with attribution to upstream MeshCore (also MIT)
- README: rewritten with badges, supported boards, install paths (web
  flasher / PlatformIO / esptool), bot command table, layout map,
  development quickstart
- CONTRIBUTING: submodule + patch-queue workflow, what-goes-where,
  patch hygiene rules, PR expectations
- RELEASE: cmesh-bot-vX.Y.Z tag scheme + procedure
- CHANGELOG: Keep-a-Changelog format, seeded with the hop-coordination
  fix and patch-5 utility commands
- Issue templates: bug_report (with bot stats prompt), feature_request,
  config.yml (no blank issues, link to upstream + community)
- Pull request template: layer checklist, verification gates,
  prefs-schema impact prompt
- .github/workflows/firmware-build.yml: keep PR check on representative
  envs (Heltec V3, RAK 4631 USB+BLE), add concurrency cancellation for
  PRs, scope cache key to PIO config hash
- .github/workflows/release.yml: NEW; triggers on cmesh-bot-v* tag or
  manual dispatch, enumerates all 133 *_companion_radio_(usb|ble) envs
  from vendor/MeshCore/variants/, shards across 8 parallel matrix jobs,
  aggregates artifacts into a single draft release
- scripts/verify.sh: respect MESHCORE_SKIP_APPLY_PATCHES like
  build-representative.sh does, so verify works when vendor already has
  patches applied as commits
- .gitignore: add .forge.bak.*/ for forge backup directories

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug report
+description: Something's broken in the firmware or tooling
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. The more concrete, the faster we can chase it down.
+  - type: input
+    id: firmware_version
+    attributes:
+      label: Firmware version
+      description: From `bot` (no args) CLI command, the `version` chat command, or the filename you flashed.
+      placeholder: cmesh-bot-v1.2.3-abc1234
+    validations:
+      required: true
+  - type: dropdown
+    id: board
+    attributes:
+      label: Board
+      description: Which PlatformIO env / hardware?
+      options:
+        - Heltec V3 (USB)
+        - Heltec V3 (BLE)
+        - RAK 4631 (USB)
+        - RAK 4631 (BLE)
+        - LilyGo T-Echo
+        - LilyGo T-Deck
+        - Xiao S3 WIO
+        - Other (specify below)
+    validations:
+      required: true
+  - type: textarea
+    id: symptom
+    attributes:
+      label: What happened?
+      description: What did you observe? What did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: The shortest sequence of actions that reproduces the bug.
+      placeholder: |
+        1. Flash cmesh-bot-vX.Y.Z to Heltec V3
+        2. From another node 3 hops away, send `ping` on #bot
+        3. Observe: no reply within 30s
+    validations:
+      required: true
+  - type: textarea
+    id: bot_stats
+    attributes:
+      label: bot stats output (if available)
+      description: Output of `bot` and `bot stats` from the USB CLI rescue console, before and after the trigger.
+      render: shell
+  - type: textarea
+    id: other
+    attributes:
+      label: Anything else?
+      description: Logs, screenshots, hop diagrams, peer node names, etc.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: MeshCore upstream
+    url: https://github.com/meshcore-dev/MeshCore/issues
+    about: Bugs that affect upstream MeshCore (not specific to the Colorado bot patches) should go upstream.
+  - name: Colorado Mesh community
+    url: https://github.com/Colorado-Mesh
+    about: General questions about Colorado Mesh — coverage, joining, hardware recommendations.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Suggest a new bot command, board, or capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: motivation
+    attributes:
+      label: What problem are you trying to solve?
+      description: Start with the use case, not the proposed solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What command, behavior, or board support would address the problem?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've considered
+      description: Other commands, workflow changes, off-device tools, etc.
+  - type: textarea
+    id: scope
+    attributes:
+      label: Anything specific about scope or implementation?
+      description: e.g. should this be guarded by a CLI toggle? Does it need new bot prefs? Cross-bot coordination?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--
+Thanks for the PR. A few quick prompts to make review fast.
+Delete sections that don't apply.
+-->
+
+## Summary
+
+<!-- What changed and why. Lead with the why. -->
+
+## Affected layer
+
+- [ ] MeshCore submodule (`vendor/MeshCore/`) — patches re-exported
+- [ ] Wrapper tooling (`scripts/`, `tests/`, `.github/`)
+- [ ] Colorado overlay (`colorado/`)
+- [ ] Docs only
+
+## Verification
+
+- [ ] `MESHCORE_SKIP_APPLY_PATCHES=1 bash scripts/verify.sh --no-build` passes locally
+- [ ] (if firmware changed) Built a representative env and confirmed size impact in `out/size/summary.json`
+- [ ] (if behavior changed on the radio) Flashed and tested on real hardware — note the board and what you tried:
+  > _e.g. Heltec V3, sent `ping`/`trace`/`path` at 0, 2, 4, 6 hops from another node on #bot_
+
+## Bot-prefs schema impact
+
+- [ ] No change to `BotPrefs` shape or default values
+- [ ] Schema changed → `BOT_PREFS_VERSION` bumped accordingly
+- [ ] N/A

.github/workflows/firmware-build.yml

@@ -7,9 +7,15 @@ on:
       - main
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   representative-build:
+    name: Representative build (Heltec V3, RAK 4631)
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
@@ -22,7 +28,9 @@ jobs:
           path: |
             ~/.cache/pip
             ~/.platformio/.cache
-          key: ${{ runner.os }}-pio
+          key: ${{ runner.os }}-pio-${{ hashFiles('vendor/MeshCore/platformio.ini', 'vendor/MeshCore/variants/**/platformio.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-pio-
 
       - name: Install Python
         uses: actions/setup-python@v5
@@ -32,7 +40,7 @@ jobs:
       - name: Install PlatformIO
         run: python3 -m pip install --upgrade platformio
 
-      - name: Run host and safety checks
+      - name: Run host tests and safety checks
         run: bash scripts/verify.sh --no-build
 
       - name: Build representative firmware

.github/workflows/release.yml

@@ -0,0 +1,205 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'cmesh-bot-v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label to embed (e.g. v1.2.3 or v1.2.3-rc.1). Required for manual runs.'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  enumerate:
+    name: Enumerate companion targets
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      shards: ${{ steps.shards.outputs.shards }}
+      env_count: ${{ steps.shards.outputs.env_count }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Resolve release version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            version="${{ inputs.version }}"
+          else
+            tag="${GITHUB_REF#refs/tags/}"
+            # cmesh-bot-vX.Y.Z[-...]  ->  vX.Y.Z[-...]
+            version="${tag#cmesh-bot-}"
+          fi
+          if [ -z "$version" ]; then
+            echo "Could not derive a version label." >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Release version: $version"
+
+      - name: Enumerate companion USB+BLE environments and shard
+        id: shards
+        run: |
+          envs=$(grep -rhE '^\[env:' vendor/MeshCore/variants/ \
+                 | sort -u \
+                 | grep -E '_companion_radio_(usb|ble)\]$' \
+                 | sed -e 's/\[env://' -e 's/\]//')
+          count=$(printf '%s\n' "$envs" | wc -l | tr -d ' ')
+          echo "env_count=$count" >> "$GITHUB_OUTPUT"
+          echo "Found $count companion USB+BLE environments."
+          shards=$(jq -nc '[range(0;8)]')
+          echo "shards=$shards" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build shard ${{ matrix.shard }}/8
+    needs: enumerate
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: ${{ fromJSON(needs.enumerate.outputs.shards) }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Cache PlatformIO
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+            ~/.platformio/packages
+          key: ${{ runner.os }}-pio-release-${{ hashFiles('vendor/MeshCore/platformio.ini', 'vendor/MeshCore/variants/**/platformio.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-pio-release-
+            ${{ runner.os }}-pio-
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PlatformIO
+        run: python3 -m pip install --upgrade platformio
+
+      - name: Apply patches
+        run: bash scripts/apply-patches.sh
+
+      - name: Select envs for this shard
+        id: select
+        run: |
+          envs=$(grep -rhE '^\[env:' vendor/MeshCore/variants/ \
+                 | sort -u \
+                 | grep -E '_companion_radio_(usb|ble)\]$' \
+                 | sed -e 's/\[env://' -e 's/\]//')
+          shard_envs=$(printf '%s\n' "$envs" \
+                       | awk -v shard=${{ matrix.shard }} -v total=8 'NR%total==shard')
+          printf 'envs<<EOF\n%s\nEOF\n' "$shard_envs" >> "$GITHUB_OUTPUT"
+          shard_count=$(printf '%s\n' "$shard_envs" | grep -c . || true)
+          echo "Shard ${{ matrix.shard }}: building $shard_count envs"
+          printf '%s\n' "$shard_envs"
+
+      - name: Build firmware
+        env:
+          FIRMWARE_VERSION: ${{ needs.enumerate.outputs.version }}
+        run: |
+          set -e
+          mkdir -p out/firmware out/logs
+          cd vendor/MeshCore
+          while IFS= read -r env; do
+            [ -z "$env" ] && continue
+            log="../../out/logs/$env.log"
+            echo "::group::Building $env"
+            if /usr/bin/env bash build.sh build-firmware "$env" 2>&1 | tee "$log"; then
+              echo "::endgroup::"
+              if compgen -G "out/$env-*" >/dev/null; then
+                cp out/"$env"-* ../../out/firmware/
+              fi
+            else
+              echo "::endgroup::"
+              echo "::error::Build failed for $env (see logs artifact)"
+              exit 1
+            fi
+          done <<< "${{ steps.select.outputs.envs }}"
+
+      - name: Upload firmware shard
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: firmware-shard-${{ matrix.shard }}
+          path: out/firmware
+          if-no-files-found: warn
+          retention-days: 14
+
+      - name: Upload build logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-logs-shard-${{ matrix.shard }}
+          path: out/logs
+          if-no-files-found: warn
+          retention-days: 14
+
+  release:
+    name: Publish draft release
+    needs: [enumerate, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Download all firmware shards
+        uses: actions/download-artifact@v4
+        with:
+          pattern: firmware-shard-*
+          merge-multiple: true
+          path: release-firmware
+
+      - name: List release artifacts
+        run: |
+          count=$(find release-firmware -maxdepth 1 -type f | wc -l | tr -d ' ')
+          echo "Aggregated $count release artifacts:"
+          ls -la release-firmware/
+
+      - name: Create draft release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          name: Colorado Mesh Bot Firmware ${{ needs.enumerate.outputs.version }}
+          tag_name: ${{ github.ref_name }}
+          draft: true
+          prerelease: ${{ contains(needs.enumerate.outputs.version, '-') }}
+          generate_release_notes: true
+          body: |
+            Companion-radio firmware for the Colorado Mesh.
+
+            **Built environments:** ${{ needs.enumerate.outputs.env_count }} companion USB+BLE targets across ESP32, NRF52, RP2040, and STM32 platforms.
+
+            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for changes in this version.
+
+            ### Install
+
+            Easiest: flash via [flasher.meshcore.io](https://flasher.meshcore.io) and drag in the right artifact for your board.
+
+            - ESP32 boards: `<board>-merged.bin`
+            - NRF52 boards: `<board>.uf2`
+
+            See the [README](https://github.com/${{ github.repository }}#install) for other install methods.
+          files: release-firmware/*