Merge branch 'master' into 129-hardware-support-agent

.claude/commands/README.md

@@ -0,0 +1,49 @@
+# Claude Code slash commands for the mcp-server test suite
+
+Three AI-assisted workflows wrapping `mcp-server/run-tests.sh` and the meshtastic MCP tools. Each one has a twin in `.github/prompts/` for Copilot users.
+
+| Slash command         | What it does                                                              | Copilot equivalent                       |
+| --------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
+| `/test [args]`        | Runs the test suite (auto-detects hardware) and interprets failures       | `.github/prompts/mcp-test.prompt.md`     |
+| `/diagnose [role]`    | Read-only device health report via the meshtastic MCP tools               | `.github/prompts/mcp-diagnose.prompt.md` |
+| `/repro <test> [n=5]` | Re-runs one test N times, diffs firmware logs between passes and failures | `.github/prompts/mcp-repro.prompt.md`    |
+
+## Why two surfaces
+
+The Claude Code commands and Copilot prompts cover the same three workflows but each speaks its host's idiom:
+
+- **Claude Code** (`/test`) uses `$ARGUMENTS` for pass-through, has direct access to Bash + all MCP tools registered in the user's settings, and runs in the terminal context.
+- **Copilot** (`/mcp-test`) runs in VS Code's agent mode; it has terminal + MCP access too but typically asks the operator to confirm inputs interactively.
+
+A contributor using either IDE gets equivalent assistance. Keep the two in sync when behavior changes — the diff of intent should be minimal.
+
+## House rules
+
+- **No destructive writes without explicit operator approval.** Skills that could reflash, factory-reset, or reboot a device must describe the action and stop — the operator authorizes.
+- **Interpret failures, don't just echo them.** The skill body should pull firmware log lines from `mcp-server/tests/report.html` (the `Meshtastic debug` section, attached by `tests/conftest.py::pytest_runtest_makereport`) and classify the failure.
+- **Keep MCP tool calls sequential per port.** SerialInterface holds an exclusive port lock; two parallel tool calls on the same port deadlock.
+- **Never speculate about root cause.** If the evidence doesn't support a classification, say "unknown" and list what you'd need to disambiguate.
+
+## Adding a new command
+
+1. Write the Claude Code version at `.claude/commands/<name>.md` with YAML frontmatter:
+
+   ```yaml
+   ---
+   description: one-line purpose (used for auto-invocation by the model)
+   argument-hint: [optional-hint]
+   ---
+   ```
+
+2. Write the Copilot equivalent at `.github/prompts/mcp-<name>.prompt.md` with:
+
+   ```yaml
+   ---
+   mode: agent
+   description: ...
+   ---
+   ```
+
+3. Add the row to the table above. Cross-link in both bodies.
+
+4. Smoke-test on Claude Code first (`/<name>` should appear in autocomplete), then in VS Code Copilot (`/mcp-<name>` in Chat).

.claude/commands/diagnose.md

@@ -0,0 +1,62 @@
+---
+description: Produce a device health report using the meshtastic MCP tools (device_info, list_nodes, get_config, short serial log capture)
+argument-hint: [role=all|nrf52|esp32s3|<port>]
+---
+
+# `/diagnose` — device health report
+
+Call the meshtastic MCP tool bundle and format a structured health report for one or all detected devices. Zero guesswork for the operator.
+
+## What to do
+
+1. **Enumerate hardware.** Call `mcp__meshtastic__list_devices(include_unknown=True)`. For each entry where `likely_meshtastic=True`, capture `port`, `vid`, `pid`, `description`.
+
+2. **Filter by `$ARGUMENTS`**:
+   - No args, `all` → every likely-meshtastic device.
+   - `nrf52` → only devices with `vid == 0x239a`.
+   - `esp32s3` → only devices with `vid == 0x303a` or `vid == 0x10c4`.
+   - A `/dev/cu.*` path → only that one port.
+   - Anything else → treat as a substring match against the `port` string.
+
+3. **For each selected device, in sequence (NOT parallel — SerialInterface holds an exclusive port lock):**
+   - `mcp__meshtastic__device_info(port=<p>)` — captures `my_node_num`, `long_name`, `short_name`, `firmware_version`, `hw_model`, `region`, `num_nodes`, `primary_channel`.
+   - `mcp__meshtastic__list_nodes(port=<p>)` — count of peers, which ones have `publicKey` set, SNR/RSSI distribution.
+   - `mcp__meshtastic__get_config(section="lora", port=<p>)` — region, preset, channel_num, tx_power, hop_limit.
+   - Optionally, if the device seems unhappy (fails to connect, `num_nodes==1` when ≥2 are plugged in, missing firmware*version), open a short firmware log window: `mcp__meshtastic__serial_open(port=<p>, env=<inferred-env>)`, wait 3s, `serial_read(session_id=<s>, max_lines=100)`, `serial_close(session_id=<s>)`. The env should be inferred from the VID map in `mcp-server/run-tests.sh` (nrf52 → rak4631, esp32s3 → heltec-v3) unless `MESHTASTIC_MCP_ENV*<ROLE>` is set.
+
+4. **Hub health** (call once, not per-device): `mcp__meshtastic__uhubctl_list()` — enumerates every USB hub the host can see. Note which hubs advertise `ppps=true` and which hub hosts each Meshtastic device (cross-reference by VID). Flag it in the report if:
+   - No hub advertises PPPS → `tests/recovery/` can't run on this setup; hard-recovery via `uhubctl_cycle` isn't available.
+   - A Meshtastic device is on a non-PPPS hub → note it; operator may want to move the device to a PPPS hub to unlock auto-recovery.
+   - `uhubctl_list` raises `ConfigError: uhubctl not found` → just say `uhubctl not installed` in the report; don't treat as a fault.
+
+5. **Render per-device report** as:
+
+   ```text
+   [nrf52 @ /dev/cu.usbmodem1101]      fw=2.7.23.bce2825, hw=RAK4631
+     owner       : Meshtastic 40eb / 40eb
+     region/band : US, channel 88, LONG_FAST
+     tx_power    : 30 dBm, hop_limit=3
+     peers       : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm)
+     primary ch  : McpTest
+     hub         : 1-1.3 port 2 (PPPS, uhubctl-controllable)
+     firmware    : no panics in last 3s; NodeInfoModule emitted 2 broadcasts
+   ```
+
+   Keep it scannable. If a field is missing or abnormal (no pubkey for a known peer, region=UNSET, num_nodes inconsistent with the hub, device on non-PPPS hub), flag it inline with a short `⚠︎ <one-line reason>`.
+
+6. **Cross-device correlation** (only when >1 device is inspected):
+   - Do both sides see each other in `nodesByNum`? If one does and the other doesn't, that's asymmetric NodeInfo — flag it.
+   - Do the LoRa configs match? (region, channel_num, modem_preset should all agree; mismatch = no mesh)
+   - Do the primary channel NAMES match? Mismatch = different PSK = no decode.
+
+7. **Suggest next actions only for specific, recognisable failure modes**:
+   - Stale PKI pubkey one-way → "run `/test tests/mesh/test_direct_with_ack.py` — the retry + nodeinfo-ping heals this in the test path."
+   - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`."
+   - Device unreachable, reachable via DFU → `touch_1200bps(port=...)` + `pio_flash`. If not even DFU responds AND the device is on a PPPS hub, escalate to `uhubctl_cycle(role=..., confirm=True)`.
+   - CP2102-wedged-driver on macOS → see the note in `run-tests.sh`.
+
+## What NOT to do
+
+- No writes. No `set_config`, no `reboot`, no `factory_reset`. This is a read-only diagnostic skill — if the operator wants to change state, they'll ask explicitly.
+- No `flash` / `erase_and_flash`. Those are separate escalations.
+- No holding SerialInterface across tool calls — open, query, close; next device. The port lock is exclusive.

.claude/commands/repro.md

@@ -0,0 +1,66 @@
+---
+description: Re-run a specific test N times in isolation to triage flakes, diff firmware logs between passes and failures
+argument-hint: <test-node-id> [count=5]
+---
+
+# `/repro` — flakiness triage for one test
+
+Re-run a single pytest node ID N times in isolation, track pass rate, and surface what's _different_ in the firmware logs between the passing attempts and the failing ones. Turns "it's flaky, I guess" into "it fails when X, passes when Y."
+
+## What to do
+
+1. **Parse `$ARGUMENTS`**: first token is the pytest node id (e.g. `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[nrf52->esp32s3]`); second token is an integer count (default `5`, cap at `20`). If the first token doesn't look like a test path (no `::` and no `tests/` prefix), treat the whole `$ARGUMENTS` as a `-k` filter instead.
+
+2. **Sanity-check the hub first** (so we're not measuring "nothing plugged in" N times): call `mcp__meshtastic__list_devices`. If the test name contains `nrf52` or `esp32s3` and the matching VID isn't present, stop and report — re-running won't help.
+
+3. **Loop N times**. For each iteration:
+
+   ```bash
+   ./mcp-server/run-tests.sh <test-id> --tb=short -p no:cacheprovider
+   ```
+
+   Capture: exit code, duration, and (on failure) the `Meshtastic debug` firmware log section from `mcp-server/tests/report.html`. `-p no:cacheprovider` suppresses pytest's `.pytest_cache` writes so iterations don't influence each other.
+
+4. **Track a small structured tally**:
+
+   ```text
+   attempt 1: PASS (42s)
+   attempt 2: FAIL (128s)  ← firmware log 200-line tail captured
+   attempt 3: PASS (39s)
+   attempt 4: FAIL (121s)
+   attempt 5: PASS (41s)
+   --------------------------------------
+   pass rate: 3/5 (60%)   |   mean duration: 74s
+   ```
+
+5. **On mixed outcomes**: diff the firmware log tails between a representative passing attempt and a representative failing attempt. Focus on:
+   - Error-level lines only present in failures (`PKI_UNKNOWN_PUBKEY`, `Alloc an err=`, `Skip send`, `No suitable channel`)
+   - Timing around the assertion event — did a broadcast go out, was there an ACK, did NAK fire?
+   - Device state fields that changed (nodesByNum entries, region/preset, channel_num)
+
+   Surface the top 3 differences as a "passes when / fails when" table. Don't dump full logs — pull specific lines with uptime timestamps.
+
+6. **Classify the flake** into one of:
+   - **LoRa airtime collision** → pass rate improves with fewer concurrent transmitters; propose a `time.sleep` gap or retry bump in the test body.
+   - **PKI key staleness** → fails on first attempt, passes after self-heal; existing retry loop in `test_direct_with_ack.py` handles this.
+   - **NodeInfo cooldown** → `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs `broadcast_nodeinfo_ping()` warmup.
+   - **Hardware-specific** (one direction fails, other passes; one device's firmware is older; driver wedged) → specific recovery pointer. For a device that's wedged past `touch_1200bps`, the next escalation is `uhubctl_cycle(role=..., confirm=True)` to hard-power-cycle its hub port (requires `uhubctl` installed).
+   - **Device went dark mid-run** → fails from some attempt onward, never recovers, firmware log stops arriving. Almost always hardware: a Guru crash + frozen CDC. Hard-power-cycle via `uhubctl_cycle(role=..., confirm=True)` before the next iteration; if that also fails, escalate to replug.
+   - **Genuinely unknown** → say so; don't invent a root cause.
+
+7. **Report back** with:
+   - Pass rate and mean duration.
+   - Classification + evidence (the specific log lines that support it).
+   - A suggested next step (re-run with specific args, open `/diagnose`, edit a specific test file, nothing).
+
+## Examples
+
+- `/repro tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[esp32s3->nrf52] 10` — runs 10 times, diffs firmware logs.
+- `/repro broadcast_delivers` — no `::`, no `tests/`, so interpreted as `-k broadcast_delivers`; runs every matching test the default 5 times.
+- `/repro tests/telemetry/test_device_telemetry_broadcast.py 3` — shorter run for a slow test.
+
+## Constraints
+
+- Don't exceed `count=20` per invocation — airtime and USB wear add up. If the user asks for 50, negotiate down.
+- Don't rebuild firmware as part of triage; flakes that only reproduce under different firmware belong in a separate session.
+- If the FIRST attempt fails AND the rest all pass, that's a classic "state leak from a prior test" → say so and suggest running with `--force-bake` or starting from a clean state rather than chasing the first failure.

.claude/commands/test.md

@@ -0,0 +1,47 @@
+---
+description: Run the mcp-server test suite (auto-detects devices) and interpret the results
+argument-hint: [pytest-args]
+---
+
+# `/test` — mcp-server test runner with interpretation
+
+Run `mcp-server/run-tests.sh` and make sense of the output so the operator doesn't have to.
+
+## What to do
+
+1. **Invoke the wrapper.** From the firmware repo root, run:
+
+   ```bash
+   ./mcp-server/run-tests.sh $ARGUMENTS
+   ```
+
+   The wrapper auto-detects connected Meshtastic devices, maps each to its PlatformIO env, exports the required `MESHTASTIC_MCP_ENV_*` env vars, and invokes pytest. If the user passed no arguments, the wrapper supplies a sensible default set (`tests/ --html=tests/report.html --self-contained-html --junitxml=tests/junit.xml -v --tb=short`). A `--report-log=tests/reportlog.jsonl` arg is always appended (unless the operator passed their own). `--assume-baked` is deliberately NOT in the defaults — `test_00_bake.py` has its own skip-if-already-baked check and runs the ~8 s verification by default. Operators can opt into the fast path with `--assume-baked`, or force a reflash with `--force-bake`.
+
+2. **Read the pre-flight header.** First ~6 lines print the detected hub (role → port → env). If that line reads `detected hub : (none)`, the wrapper will narrow to `tests/unit` only — say so explicitly in your summary so the operator knows hardware tiers were skipped.
+
+3. **On pass**: one-line summary of the form `N passed, M skipped in <duration>`. Don't enumerate the test names — the user can read those. Do mention any SKIPPED tests and name the cause:
+   - `"role not present on hub"` → device unplugged; operator knows to reconnect.
+   - `"firmware not baked with USERPREFS_UI_TEST_LOG"` → tests/ui skipped because the macro isn't in firmware yet; suggest `--force-bake`.
+   - `"uhubctl not installed"` → tests/recovery + peer-offline skipped; suggest `brew install uhubctl` / `apt install uhubctl`.
+   - `"no PPPS-capable hubs detected"` → tests/recovery skipped because the hub doesn't support per-port power; the tier will never run on that setup.
+   - `"opencv-python-headless is not installed"` → tests/ui auto-deselected by run-tests.sh; suggest `pip install -e 'mcp-server/.[ui]'`.
+
+4. **On failure**: for every FAILED test, open `mcp-server/tests/report.html` and extract the `Meshtastic debug` section for that test. pytest-html embeds the firmware log stream + device state dump there; the 200-line firmware log tail is usually enough to explain the failure. Summarise: which test, one-line assertion message, the firmware log lines that matter (things like `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`). For UI-tier failures also glance at `mcp-server/tests/ui_captures/<session>/<test>/transcript.md` — it records each step's frame + OCR.
+
+5. **Classify the failure** as one of:
+   - **Transient/flake**: LoRa collision, timing-sensitive assertion, first-attempt NAK + successful retry pattern. Propose `/repro <test_node_id>` to confirm.
+   - **Environmental**: device unreachable, port busy, CP2102 driver wedged. Suggest the specific recovery in escalation order: (a) replug USB, (b) `touch_1200bps(port=...)` + `pio_flash` for nRF52 DFU, (c) `uhubctl_cycle(role="nrf52", confirm=True)` when a device is fully wedged past DFU (needs `uhubctl` installed — `baked_single`'s auto-recovery hook does this once automatically). Also check `git status userPrefs.jsonc`.
+   - **Regression**: same assertion fails repeatedly, firmware log shows a new/unusual error. Surface the diff between expected and observed, identify the module likely responsible.
+
+6. **Never run destructive recovery automatically.** If a failure looks like it needs a reflash, factory*reset, `uhubctl_cycle`, or USB replug, \_describe what to do* — don't execute. The operator decides.
+
+## Arguments handling
+
+- No args → wrapper's defaults (full suite).
+- `$ARGUMENTS` passed verbatim to the wrapper, which passes them to pytest.
+- Common operator invocations: `/test tests/mesh`, `/test tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip`, `/test --force-bake`, `/test -k telemetry`.
+
+## Side-effects to mention in summary
+
+- The session fixture snapshots `userPrefs.jsonc` at session start and restores at teardown (plus on `atexit`). After a clean run, `git status userPrefs.jsonc` should be empty. If the wrapper's pre-flight printed a warning about a stale sidecar, call that out — means a prior session crashed.
+- `mcp-server/tests/report.html` and `junit.xml` are regenerated on every run; the HTML is self-contained (shareable).

.claude/settings.json

@@ -1,17 +0,0 @@
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "f=$(tr -d '\\n' | grep -o '\"file_path\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | head -1 | sed 's/.*:[[:space:]]*\"//; s/\"$//'); [ -n \"$f\" ] && [ -f \"$f\" ] || exit 0; t=$(command -v trunk || echo \"$HOME/.cache/trunk/launcher/trunk\"); [ -x \"$t\" ] || { echo \"trunk-fmt hook: trunk not found; its launcher needs curl or wget to bootstrap the CLI (see 'Formatting & the trunk toolchain' in .github/copilot-instructions.md)\" >&2; exit 1; }; out=$(\"$t\" fmt --force \"$f\" 2>&1) || { echo \"trunk-fmt hook: trunk fmt failed on $f: $out\" >&2; exit 1; }",
-            "timeout": 120,
-            "statusMessage": "Formatting (trunk)..."
-          }
-        ]
-      }
-    ]
-  }
-}

.clusterfuzzlite/Dockerfile

@@ -4,18 +4,21 @@
 # As this is not a long running service, health-checks are not required. ClusterFuzzLite
 # also only works if the user remains unchanged from the base image (it expects to run
 # as root).
-# trunk-ignore-all(trivy/DS-0026): No healthcheck is needed for this builder container
+# trunk-ignore-all(trivy/DS026): No healthcheck is needed for this builder container
 # trunk-ignore-all(checkov/CKV_DOCKER_2): No healthcheck is needed for this builder container
 # trunk-ignore-all(checkov/CKV_DOCKER_3): We must run as root for this container
-# trunk-ignore-all(trivy/DS-0002): We must run as root for this container
+# trunk-ignore-all(trivy/DS002): We must run as root for this container
+# trunk-ignore-all(checkov/CKV_DOCKER_8): We must run as root for this container
+# trunk-ignore-all(hadolint/DL3002): We must run as root for this container
 
 FROM gcr.io/oss-fuzz-base/base-builder:v1
 
 ENV PIP_ROOT_USER_ACTION=ignore
 
 # trunk-ignore(hadolint/DL3008): apt packages are not pinned.
+# trunk-ignore(terrascan/AC_DOCKER_0002): apt packages are not pinned.
 RUN apt-get update && apt-get install --no-install-recommends -y \
-        cmake git zip libgpiod-dev libjsoncpp-dev libbluetooth-dev libi2c-dev \
+        cmake git zip libgpiod-dev libbluetooth-dev libi2c-dev \
         libunistring-dev libmicrohttpd-dev libgnutls28-dev libgcrypt20-dev \
         libusb-1.0-0-dev libssl-dev pkg-config libsqlite3-dev libsdl2-dev && \
     apt-get clean && rm -rf /var/lib/apt/lists/* && \

.clusterfuzzlite/build.sh

@@ -31,7 +31,7 @@ cmake --install "$WORK/ulfius/$SANITIZER" --prefix /usr
 cd "$SRC/firmware"
 
 PLATFORMIO_EXTRA_SCRIPTS=$(echo -e "pre:.clusterfuzzlite/platformio-clusterfuzzlite-pre.py\npost:.clusterfuzzlite/platformio-clusterfuzzlite-post.py")
-STATIC_LIBS=$(pkg-config --libs --static libulfius openssl libgpiod yaml-cpp jsoncpp bluez --silence-errors)
+STATIC_LIBS=$(pkg-config --libs --static libulfius openssl libgpiod yaml-cpp bluez --silence-errors)
 export PLATFORMIO_EXTRA_SCRIPTS
 export STATIC_LIBS
 export PLATFORMIO_WORKSPACE_DIR="$WORK/pio/$SANITIZER"

.coderabbit.yaml

@@ -1,46 +0,0 @@
-# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
-# CodeRabbit config - see https://docs.coderabbit.ai/getting-started/yaml-configuration
-language: en-US
-
-reviews:
-  # chill = fewer nitpicks.
-  profile: chill
-  high_level_summary: true
-  poem: false
-  auto_review:
-    enabled: true
-    # Don't burn reviews on WIP. This repo opens lots of draft PRs; review on "ready".
-    drafts: false
-    # Review PRs regardless of target branch.
-    base_branches:
-      - .*
-    # Skip Renovate dependency updates - CI gates dependencies; we review for substance, not every bump.
-    ignore_usernames:
-      - renovate
-      - renovate[bot]
-  # Stop reviewing once a PR is closed.
-  abort_on_close: true
-
-  path_filters:
-    # Generated - don't review, just noise + token burn.
-    - "!src/mesh/generated/**"
-    - "!protobufs/**"
-
-  path_instructions:
-    - path: bin/config.d/**
-      instructions: >
-        meshtasticd configuration files. Bundled with meshtasticd Linux/MacOS packaging.
-        Ensure configurations include metadata found in other configs.
-    - path: "**/*.md"
-      instructions: >
-        Documentation does not live in this repo; it lives in
-        https://github.com/meshtastic/meshtastic. Flag any NEW .md file that documents a
-        feature, configuration surface, API, wire format, or design, and ask for it to be
-        opened against the docs repo instead. Flag any attempt to recreate a docs/
-        directory: it was deleted in #11488 and must not come back. Flag write-ups left in
-        the tree - investigation notes, mitigation plans, migration checklists, "how we got
-        here" narrative, summaries of what a change did - that content belongs in the PR
-        description and commit message. Documentation that does belong upstream must read
-        as a technical manual, not a novel: what it does, the settings in user terms, the
-        API or protocol a client speaks. No debugging journey, no rationale essays, no
-        changelog prose.

.devcontainer/Dockerfile

@@ -1,3 +1,4 @@
+# trunk-ignore-all(terrascan/AC_DOCKER_0002): Known terrascan issue
 # trunk-ignore-all(hadolint/DL3008): Do not pin apt package versions
 # trunk-ignore-all(hadolint/DL3013): Do not pin pip package versions
 FROM mcr.microsoft.com/devcontainers/cpp:2-debian-13
@@ -15,7 +16,6 @@ RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
     libssl-dev \
     libulfius-dev \
     libyaml-cpp-dev \
-    libjsoncpp-dev \
     pipx \
     pkg-config \
     python3 \

.devcontainer/devcontainer.json

@@ -15,14 +15,10 @@
     "vscode": {
       "extensions": [
         "ms-vscode.cpptools",
-        "Jason2866.esp-decoder",
-        "pioarduino.pioarduino-ide",
+        "platformio.platformio-ide",
         "Trunk.io"
       ],
-      "unwantedRecommendations": [
-        "ms-azuretools.vscode-docker",
-        "platformio.platformio-ide"
-      ],
+      "unwantedRecommendations": ["ms-azuretools.vscode-docker"],
       "settings": {
         "extensions.ignoreRecommendations": true
       }

.github/actions/build-variant/action.yml

@@ -76,7 +76,7 @@ runs:
         done
 
     - name: PlatformIO ${{ inputs.arch }} download cache
-      uses: actions/cache@v6
+      uses: actions/cache@v5
       with:
         path: ~/.platformio/.cache
         key: pio-cache-${{ inputs.arch }}-${{ hashFiles('.github/actions/**', '**.ini') }}

.github/actions/setup-base/action.yml

@@ -5,7 +5,7 @@ runs:
   using: composite
   steps:
     - name: Checkout code
-      uses: actions/checkout@v7
+      uses: actions/checkout@v6
       with:
         submodules: recursive
 
@@ -13,7 +13,7 @@ runs:
       shell: bash
       run: |
         sudo apt-get -y update --fix-missing
-        sudo apt-get install -y cppcheck libbluetooth-dev libgpiod-dev libyaml-cpp-dev libjsoncpp-dev lsb-release
+        sudo apt-get install -y cppcheck libbluetooth-dev libgpiod-dev libyaml-cpp-dev lsb-release
 
     - name: Setup Python
       uses: actions/setup-python@v6

.github/actions/setup-native/action.yml

@@ -11,4 +11,4 @@ runs:
     - name: Install libs needed for native build
       shell: bash
       run: |
-        sudo apt-get install -y libbluetooth-dev libgpiod-dev libyaml-cpp-dev libjsoncpp-dev openssl libssl-dev libulfius-dev liborcania-dev libusb-1.0-0-dev libi2c-dev libuv1-dev libcurl4-gnutls-dev
+        sudo apt-get install -y libbluetooth-dev libgpiod-dev libyaml-cpp-dev openssl libssl-dev libulfius-dev liborcania-dev libusb-1.0-0-dev libi2c-dev libuv1-dev

.github/agents/copilot-instructions.md

@@ -0,0 +1,29 @@
+# firmware Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-03-25
+
+## Active Technologies
+
+- Python 3.x for workflow tooling, Markdown for generated artifacts, existing C/C++/PlatformIO repository conventions for downstream scaffold targets + Python standard library for inventory/intake tooling, existing Spec Kit artifacts, repository-local Copilot prompt/agent files, PlatformIO environment metadata conventions already in `variants/**/platformio.ini` (129-hardware-support-agent)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
+
+## Code Style
+
+Python 3.x for workflow tooling, Markdown for generated artifacts, existing C/C++/PlatformIO repository conventions for downstream scaffold targets: Follow standard conventions
+
+## Recent Changes
+
+- 129-hardware-support-agent: Added Python 3.x for workflow tooling, Markdown for generated artifacts, existing C/C++/PlatformIO repository conventions for downstream scaffold targets + Python standard library for inventory/intake tooling, existing Spec Kit artifacts, repository-local Copilot prompt/agent files, PlatformIO environment metadata conventions already in `variants/**/platformio.ini`
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.github/agents/hardware-support.agent.md

@@ -0,0 +1,124 @@
+---
+description: Guide maintainers through Meshtastic hardware support context generation, board intake assessment, and optional scaffold generation.
+---
+
+# Hardware Support Workflow
+
+Use this workflow when a maintainer wants to add support for a new board variant in the Meshtastic firmware repository.
+
+## Goals
+
+- Reuse repository-backed hardware patterns before drafting new board files.
+- Keep all generated output scoped to the requested architecture and board.
+- Stop and surface evidence gaps instead of inventing pin mappings or metadata.
+
+## Required Inputs
+
+Collect or confirm these fields before scaffold generation:
+
+- PlatformIO environment name
+- hardware model identifier
+- display name
+- architecture
+
+Recommended additional inputs:
+
+- hardware model slug
+- actively supported flag
+- support level
+- source materials such as schematic, pinout, or datasheet links
+- board notes covering revision scope and known uncertainty
+
+## Workflow
+
+### 1. Refresh Repository Context
+
+Run from the repository root:
+
+```bash
+python3 bin/generate_hardware_support_context.py
+```
+
+Review [docs/hardware-support-context.md](../../docs/hardware-support-context.md) for architecture-specific examples, metadata keys, and inherited-default notes.
+
+### 2. Capture The Intake Request
+
+Create or update a JSON file matching the contract in [specs/129-hardware-support-agent/contracts/board-intake-contract.md](../../specs/129-hardware-support-agent/contracts/board-intake-contract.md).
+
+### 3. Assess Intake Readiness
+
+Run:
+
+```bash
+python3 bin/board_intake.py path/to/intake.json
+```
+
+What to look for:
+
+- expected artifacts
+- required metadata
+- matched repository patterns
+- evidence gaps
+- risk flags
+- next actions
+- scaffold readiness decision
+
+For CI-style gating, use:
+
+```bash
+python3 bin/board_intake.py path/to/intake.json --validate
+```
+
+If the assessment is not scaffold-ready, stop and resolve the blocking gaps before continuing.
+
+### 4. Generate Scaffold Output When Ready
+
+Only run this when the intake assessment reports `Scaffold ready: Yes`.
+
+```bash
+python3 bin/board_scaffold.py path/to/intake.json --output-dir generated/hardware-support
+```
+
+Expected outputs:
+
+- draft `variant.h`
+- draft `platformio.ini`
+- optional `variant.cpp` for ESP32-family targets
+
+Review all `// TODO: verify — ...` annotations before treating the scaffold as merge-ready.
+
+### 5. Compile-Gate The Target Environment (Required)
+
+The end stage must always validate that the target environment is at least compilable.
+
+Run:
+
+```bash
+pio run -e <environment_name>
+```
+
+Expected behavior:
+
+- If compile succeeds, include a "compile check passed" note in the review summary.
+- If compile fails, treat it as a blocking issue and report the exact failing error.
+- Do not mark the workflow complete while compile is failing.
+
+Common first-pass blocker for new scaffolds:
+
+- Missing or placeholder `board = ...` in `platformio.ini` causes `BoardConfig: Board is not defined`.
+
+## Guardrails
+
+- Do not change live firmware runtime code under `src/` as part of this workflow.
+- Do not modify existing board definitions under `variants/` automatically.
+- Do not guess unresolved radio, display, GPS, power, or input pin mappings.
+- Treat multi-revision or multi-option board notes as blocking until the revision scope is explicit.
+- Check inherited BSP defaults for `nrf52840`, `rp2040`, `stm32`, and `native` targets before declaring a missing define.
+
+## Validation Expectations
+
+- Run `trunk fmt --force` on touched Python workflow files.
+- Re-run `python3 bin/generate_hardware_support_context.py` after changes affecting context output.
+- Use fixture-driven smoke tests in `bin/fixtures/` for intake and scaffold workflows.
+- Run `pio run -e <environment_name>` as a required final compile gate for the generated board environment.
+- Report any skipped validation or remaining TODO annotations in the review notes.

.github/agents/speckit.analyze.agent.md

@@ -0,0 +1,184 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID  | Category    | Severity | Location(s)      | Summary                      | Recommendation                       |
+| --- | ----------- | -------- | ---------------- | ---------------------------- | ------------------------------------ |
+| A1  | Duplication | HIGH     | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+| --------------- | --------- | -------- | ----- |
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS

.github/agents/speckit.checklist.agent.md

@@ -0,0 +1,295 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+   - File handling behavior:
+     - If file does NOT exist: Create new file and number items starting from CHK001
+     - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016)
+   - Never delete or replace existing checklist content - always preserve and append
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"

.github/agents/speckit.clarify.agent.md

@@ -0,0 +1,181 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs:
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+   - Maximum of 5 total questions across the whole session.
+   - Each question must be answerable with EITHER:
+     - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+     - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+   - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+   - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+   - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+   - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+   - If more than 5 categories remain unresolved, select the top 5 by (Impact \* Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+   - Present EXACTLY ONE question at a time.
+   - For multiple‑choice questions:
+     - **Analyze all options** and determine the **most suitable option** based on:
+       - Best practices for the project type
+       - Common patterns in similar implementations
+       - Risk reduction (security, performance, maintainability)
+       - Alignment with any explicit project goals or constraints visible in the spec
+     - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+     - Format as: `**Recommended:** Option [X] - <reasoning>`
+     - Then render all options as a Markdown table:
+
+     | Option | Description                                                                                         |
+     | ------ | --------------------------------------------------------------------------------------------------- |
+     | A      | <Option A description>                                                                              |
+     | B      | <Option B description>                                                                              |
+     | C      | <Option C description> (add D/E as needed up to 5)                                                  |
+     | Short  | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+     - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+
+   - For short‑answer style (no meaningful discrete options):
+     - Provide your **suggested answer** based on best practices and context.
+     - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+     - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+   - After the user answers:
+     - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+     - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+     - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+     - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+   - Stop asking further questions when:
+     - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+     - User signals completion ("done", "good", "no more"), OR
+     - You reach 5 asked questions.
+   - Never reveal future queued questions in advance.
+   - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+   - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+   - For the first integrated answer in this session:
+     - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+     - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+   - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+   - Then immediately apply the clarification to the most appropriate section(s):
+     - Functional ambiguity → Update or add a bullet in Functional Requirements.
+     - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+     - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+     - Non-functional constraint → Add/modify measurable criteria in Success Criteria > Measurable Outcomes (convert vague adjective to metric or explicit target).
+     - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+     - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+   - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+   - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+   - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+   - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS

.github/agents/speckit.constitution.agent.md

@@ -0,0 +1,84 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs:
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
+
+Follow this execution flow:
+
+1. Load the existing constitution at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+     **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.

.github/agents/speckit.implement.agent.md

@@ -0,0 +1,207 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before implementation)**:
+
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_implement` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+  - **Mandatory hook** (`optional: false`):
+
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile\* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc\* exists → create/verify .eslintignore
+   - Check if eslint.config.\* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc\* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (\*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
+
+10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
+    - If it exists, read it and look for entries under the `hooks.after_implement` key
+    - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+    - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+    - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+      - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+      - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+    - For each executable hook, output the following based on its `optional` flag:
+      - **Optional hook** (`optional: true`):
+
+        ```
+        ## Extension Hooks
+
+        **Optional Hook**: {extension}
+        Command: `/{command}`
+        Description: {description}
+
+        Prompt: {prompt}
+        To execute: `/{command}`
+        ```
+
+      - **Mandatory hook** (`optional: false`):
+
+        ```
+        ## Extension Hooks
+
+        **Automatic Hook**: {extension}
+        Executing: `/{command}`
+        EXECUTE_COMMAND: {command}
+        ```
+
+    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.github/agents/speckit.plan.agent.md

@@ -0,0 +1,162 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs:
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before planning)**:
+
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_plan` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+  - **Mandatory hook** (`optional: false`):
+
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_plan` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+
+     - **Mandatory hook** (`optional: false`):
+
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
+   - Identify what interfaces the project exposes to users or other systems
+   - Document the contract format appropriate for the project type
+   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
+   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh copilot`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/\*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications

.github/agents/speckit.specify.agent.md

@@ -0,0 +1,313 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs:
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: speckit.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before specification)**:
+
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+  - **Mandatory hook** (`optional: false`):
+
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Create the feature branch** by running the script with `--short-name` (and `--json`). In sequential mode, do NOT pass `--number` — the script auto-detects the next available number. In timestamp mode, the script generates a `YYYYMMDD-HHMMSS` prefix automatically:
+
+   **Branch numbering mode**: Before running the script, check if `.specify/init-options.json` exists and read the `branch_numbering` value.
+   - If `"timestamp"`, add `--timestamp` (Bash) or `-Timestamp` (PowerShell) to the script invocation
+   - If `"sequential"` or absent, do not add any extra flag (default behavior)
+
+   - Bash example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --short-name "user-auth" "Add user authentication"`
+   - Bash (timestamp): `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --timestamp --short-name "user-auth" "Add user authentication"`
+   - PowerShell example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -ShortName "user-auth" "Add user authentication"`
+   - PowerShell (timestamp): `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -Timestamp -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Do NOT pass `--number` — the script determines the correct next number automatically
+   - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+   1. Parse user description from Input
+      If empty: ERROR "No feature description provided"
+   2. Extract key concepts from description
+      Identify: actors, actions, data, constraints
+   3. For unclear aspects:
+      - Make informed guesses based on context and industry standards
+      - Only mark with [NEEDS CLARIFICATION: specific question] if:
+        - The choice significantly impacts feature scope or user experience
+        - Multiple reasonable interpretations exist with different implications
+        - No reasonable default exists
+      - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+      - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+   4. Fill User Scenarios & Testing section
+      If no clear user flow: ERROR "Cannot determine user scenarios"
+   5. Generate Functional Requirements
+      Each requirement must be testable
+      Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+   6. Define Success Criteria
+      Create measurable, technology-agnostic outcomes
+      Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+      Each criterion must be verifiable without implementation details
+   7. Identify Key Entities (if data involved)
+   8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+   ```markdown
+   # Specification Quality Checklist: [FEATURE NAME]
+
+   **Purpose**: Validate specification completeness and quality before proceeding to planning
+   **Created**: [DATE]
+   **Feature**: [Link to spec.md]
+
+   ## Content Quality
+
+   - [ ] No implementation details (languages, frameworks, APIs)
+   - [ ] Focused on user value and business needs
+   - [ ] Written for non-technical stakeholders
+   - [ ] All mandatory sections completed
+
+   ## Requirement Completeness
+
+   - [ ] No [NEEDS CLARIFICATION] markers remain
+   - [ ] Requirements are testable and unambiguous
+   - [ ] Success criteria are measurable
+   - [ ] Success criteria are technology-agnostic (no implementation details)
+   - [ ] All acceptance scenarios are defined
+   - [ ] Edge cases are identified
+   - [ ] Scope is clearly bounded
+   - [ ] Dependencies and assumptions identified
+
+   ## Feature Readiness
+
+   - [ ] All functional requirements have clear acceptance criteria
+   - [ ] User scenarios cover primary flows
+   - [ ] Feature meets measurable outcomes defined in Success Criteria
+   - [ ] No implementation details leak into specification
+
+   ## Notes
+
+   - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+   ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+   - For each item, determine if it passes or fails
+   - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+   - **If all items pass**: Mark checklist complete and proceed to step 7
+
+   - **If items fail (excluding [NEEDS CLARIFICATION])**:
+     1. List the failing items and specific issues
+     2. Update the spec to address each issue
+     3. Re-run validation until all items pass (max 3 iterations)
+     4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+   - **If [NEEDS CLARIFICATION] markers remain**:
+     1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+     2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+     3. For each clarification needed (max 3), present options to user in this format:
+
+        ```markdown
+        ## Question [N]: [Topic]
+
+        **Context**: [Quote relevant spec section]
+
+        **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+
+        **Suggested Answers**:
+
+        | Option | Answer                    | Implications                          |
+        | ------ | ------------------------- | ------------------------------------- |
+        | A      | [First suggested answer]  | [What this means for the feature]     |
+        | B      | [Second suggested answer] | [What this means for the feature]     |
+        | C      | [Third suggested answer]  | [What this means for the feature]     |
+        | Custom | Provide your own answer   | [Explain how to provide custom input] |
+
+        **Your choice**: _[Wait for user response]_
+        ```
+
+     4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+        - Use consistent spacing with pipes aligned
+        - Each cell should have spaces around content: `| Content |` not `|Content|`
+        - Header separator must have at least 3 dashes: `|--------|`
+        - Test that the table renders correctly in markdown preview
+     5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+     6. Present all questions together before waiting for responses
+     7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+     8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+     9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+8. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_specify` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+
+     - **Mandatory hook** (`optional: false`):
+
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)

.github/agents/speckit.tasks.agent.md

@@ -0,0 +1,209 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs:
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before tasks generation)**:
+
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_tasks` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+  - **Mandatory hook** (`optional: false`):
+
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_tasks` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+
+     - **Mandatory hook** (`optional: false`):
+
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

.github/agents/speckit.taskstoissues.agent.md

@@ -0,0 +1,30 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ["github/github-mcp-server/issue_write"]
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL

.github/copilot-instructions.md

@@ -1,23 +1,5 @@
 # Meshtastic Firmware - Copilot Instructions
 
-> **TL;DR**
->
-> |                |                                                                                                                        |
-> | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
-> | Local tests    | `./bin/run-tests.sh` (exit 0 GREEN · 1 RED · 2 AMBER · 3 FILTERED)                                                     |
-> | Hardware tests | [meshtastic/meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) (`MESHTASTIC_FIRMWARE_ROOT` → this checkout) |
-> | Format         | `trunk fmt`                                                                                                            |
-> | Mirror docs    | `AGENTS.md` (short pointer for agents that don't read this file) · `CLAUDE.md` (Claude Code)                           |
->
-> **Need this? It's here.**
->
-> |                                             |                                                            |
-> | ------------------------------------------- | ---------------------------------------------------------- |
-> | General helpers (clamp, UTF-8, string fmt…) | `src/meshUtils.h`                                          |
-> | Logging macros (LOG_DEBUG / INFO / WARN…)   | `src/DebugConfiguration.h`                                 |
-> | New module skeleton                         | inherit `ProtobufModule<T>` in `src/mesh/ProtobufModule.h` |
-> | Observer / event wiring                     | `src/Observer.h`                                           |
-
 This document provides context and guidelines for AI assistants working with the Meshtastic firmware codebase.
 
 ## Project Overview
@@ -55,7 +37,7 @@ MQTT provides a bridge between Meshtastic mesh networks and the internet, enabli
 
 Messages are published/subscribed using a hierarchical topic format:
 
-```text
+```
 {root}/{channel_id}/{gateway_id}
 ```
 
@@ -91,15 +73,15 @@ PKI (Public Key Infrastructure) messages have special handling:
 
 ## Encryption & Key Management
 
-Meshtastic packets on the air are typically encrypted one of two ways: the **per-channel symmetric** layer (AES-CTR with a shared PSK) for broadcasts and channel traffic, and the **per-peer PKI** layer (X25519 ECDH → AES-256-CCM) for direct messages and remote admin. A channel with a 0-byte PSK (or Ham mode, which wipes PSKs) transmits cleartext - see the size table below. Both are implemented in `src/mesh/CryptoEngine.cpp`; the send/receive dispatch lives in `src/mesh/Router.cpp`; admin authorization lives in `src/modules/AdminModule.cpp`.
+Meshtastic packets on the air are typically encrypted one of two ways: the **per-channel symmetric** layer (AES-CTR with a shared PSK) for broadcasts and channel traffic, and the **per-peer PKI** layer (X25519 ECDH → AES-256-CCM) for direct messages and remote admin. A channel with a 0-byte PSK (or Ham mode, which wipes PSKs) transmits cleartext — see the size table below. Both are implemented in `src/mesh/CryptoEngine.cpp`; the send/receive dispatch lives in `src/mesh/Router.cpp`; admin authorization lives in `src/modules/AdminModule.cpp`.
 
 ### High-level model
 
-- **Channels** are symmetric rooms: anyone with the PSK can read any message on the channel. Channel 0 is the "primary" channel and ships with the short-form default PSK on factory devices, forming the public mesh most users join. (The LoRa modem preset `LONG_FAST` lives on `config.lora.modem_preset` and is an independent field - don't conflate "channel 0 default PSK" with the modem preset name.)
+- **Channels** are symmetric rooms: anyone with the PSK can read any message on the channel. Channel 0 is the "primary" channel and ships with the short-form default PSK on factory devices, forming the public mesh most users join. (The LoRa modem preset `LONG_FAST` lives on `config.lora.modem_preset` and is an independent field — don't conflate "channel 0 default PSK" with the modem preset name.)
 - **DMs** addressed to a single node require PKI so that other holders of the channel PSK can't read them. Outside Ham mode, Meshtastic does not fall back to channel-symmetric encryption when the destination public key is unknown.
 - **Remote admin** is a DM carrying an `AdminMessage`. The receiver only acts on it if the sender's public key is on its allowlist (`config.security.admin_key[0..2]`).
-- **Ham mode** (`owner.is_licensed=true`, where `owner` is the local `meshtastic_User` record) disables PKI entirely and sends cleartext - FCC Part 97 prohibits encryption on amateur bands.
-- **No ratchet, no session.** Every packet is encrypted from scratch - a stateless design that matches the high-loss, store-and-forward nature of LoRa.
+- **Ham mode** (`owner.is_licensed=true`, where `owner` is the local `meshtastic_User` record) disables PKI entirely and sends cleartext — FCC Part 97 prohibits encryption on amateur bands.
+- **No ratchet, no session.** Every packet is encrypted from scratch — a stateless design that matches the high-loss, store-and-forward nature of LoRa.
 
 ### Symmetric channel encryption (AES-CTR)
 
@@ -122,151 +104,40 @@ Meshtastic packets on the air are typically encrypted one of two ways: the **per
 
 - **Keypair**: Curve25519 (aka X25519), 32-byte public + 32-byte private. Stored in `config.security.public_key` / `private_key`; the public half is mirrored into `owner.public_key` so it rides along in NodeInfo broadcasts and propagates through the mesh like any other identity field.
 - **Key generation** (`generateKeyPair`): stirs `HardwareRNG::fill()` (64 B from platform TRNG when available), the 16-byte `myNodeInfo.device_id`, and a call to `random()` into the rweather/Crypto library's software RNG, then `Curve25519::dh1`. `regeneratePublicKey` recomputes the public half from a known private (used when restoring from backup).
-- **Keygen entry points**: at boot, `NodeDB` calls `generateKeyPair` (or `regeneratePublicKey` when a stored private key is present and passes a low-entropy check) **directly** when `!owner.is_licensed` and `config.lora.region != UNSET`. `ensurePkiKeys` wraps the same logic for runtime/admin flows - it's the path `AdminModule::handleSetConfig` runs when first assigning a valid region or when security config is written; **do not assume it's the universal boot-time gate**, because the NodeDB path bypasses it.
+- **Keygen entry points**: at boot, `NodeDB` calls `generateKeyPair` (or `regeneratePublicKey` when a stored private key is present and passes a low-entropy check) **directly** when `!owner.is_licensed` and `config.lora.region != UNSET`. `ensurePkiKeys` wraps the same logic for runtime/admin flows — it's the path `AdminModule::handleSetConfig` runs when first assigning a valid region or when security config is written; **do not assume it's the universal boot-time gate**, because the NodeDB path bypasses it.
 - **Handshake**: `Curve25519::dh2(local_private, remote_public) → 32-byte shared secret → SHA-256 → 32-byte AES-256 key`. Recomputed per packet. The SHA-256 step is effectively a KDF over the raw ECDH output.
-- **Cipher**: AES-256-CCM via `aes_ccm_ae` / `aes_ccm_ad` (`src/mesh/aes-ccm.cpp`). MAC length (the `M` parameter) is **8 bytes**. No AAD - the MAC covers ciphertext only.
+- **Cipher**: AES-256-CCM via `aes_ccm_ae` / `aes_ccm_ad` (`src/mesh/aes-ccm.cpp`). MAC length (the `M` parameter) is **8 bytes**. No AAD — the MAC covers ciphertext only.
 - **Nonce (13 bytes / 104 bit)**: `aes_ccm_ae`/`aes_ccm_ad` use a 13-byte CCM nonce (`L = 2` is hardcoded in `src/mesh/aes-ccm.cpp`), not a 16-byte nonce. For PKI packets, `CryptoEngine::initNonce(fromNode, packetNum, extraNonce)` starts from the usual packet-derived nonce material, then overwrites nonce bytes `4..7` with a fresh 32-bit `extraNonce = random()`. The effective nonce bytes are therefore: bytes `0..3` = `packet_id`, bytes `4..7` = transmitted `extraNonce`, bytes `8..11` = `from_node`, byte `12` = `0x00`. The receiver reconstructs the same 13-byte nonce from the packet metadata plus the appended `extraNonce`.
 - **Wire overhead**: 12 bytes appended to the ciphertext = 8-byte MAC ‖ 4-byte extraNonce. Defined as `MESHTASTIC_PKC_OVERHEAD = 12` in `src/mesh/RadioInterface.h`. Only the 4-byte `extraNonce` is sent; the rest of the 13-byte CCM nonce is reconstructed from packet fields as described above. The Router's send path checks this overhead against `MAX_LORA_PAYLOAD_LEN` before committing to PKI.
-- **Send selection** (`Router::send`): the sender enters the PKI path when **all** hold - we're the originator AND not Ham mode AND not Portduino simradio AND not on the `serial`/`gpio` channels (unless the packet is already marked `pki_encrypted`) AND `config.security.private_key.size == 32` AND destination is a single node (not broadcast) AND the portnum isn't infrastructure. `TRACEROUTE_APP`, `NODEINFO_APP`, `ROUTING_APP`, and `POSITION_APP` are routed through channel encryption even when DMed (these need to be readable by relaying peers). Once on the PKI path, if the destination's public key isn't in our NodeDB the send **fails** with `PKI_SEND_FAIL_PUBLIC_KEY` - it does not silently fall back to channel encryption. If the client explicitly set `pki_encrypted=true` and any condition blocks PKI, the send fails with `PKI_FAILED`.
+- **Send selection** (`Router::send`): the sender enters the PKI path when **all** hold — we're the originator AND not Ham mode AND not Portduino simradio AND not on the `serial`/`gpio` channels (unless the packet is already marked `pki_encrypted`) AND `config.security.private_key.size == 32` AND destination is a single node (not broadcast) AND the portnum isn't infrastructure. `TRACEROUTE_APP`, `NODEINFO_APP`, `ROUTING_APP`, and `POSITION_APP` are routed through channel encryption even when DMed (these need to be readable by relaying peers). Once on the PKI path, if the destination's public key isn't in our NodeDB the send **fails** with `PKI_SEND_FAIL_PUBLIC_KEY` — it does not silently fall back to channel encryption. If the client explicitly set `pki_encrypted=true` and any condition blocks PKI, the send fails with `PKI_FAILED`.
 - **Receive selection** (`Router::perhapsDecode`): try PKI decrypt first when `channel == 0` AND `isToUs(p)` AND not broadcast AND both peers have public keys in NodeDB AND `rawSize > MESHTASTIC_PKC_OVERHEAD`. On success the packet gets `pki_encrypted=true` stamped and the sender's public key copied into `p->public_key` for downstream authorization.
 
 ### Remote admin authorization
 
 Implemented in `src/modules/AdminModule.cpp` → `handleReceivedProtobuf`. The authorization check runs in this order:
 
-1. **Response messages** - if `messageIsResponse(r)` is true (the payload is a response to one of our earlier admin requests), it's accepted without any further check. The in-file comment flags this as a known-untightened gap: a stricter implementation would remember which `public_key` we last queried and reject responses that don't match.
-2. **Local admin** - `mp.from == 0` (phone app over BLE, serial CLI, internal module); never travels over the air. **Rejected** if `config.security.is_managed` is true, because managed devices expect admin to arrive over the air through an authorized remote path.
-3. **Legacy admin channel (deprecated)** - the packet arrived on a channel named literally `"admin"`. Gated by `config.security.admin_channel_enabled`; returns `NOT_AUTHORIZED` if the flag is false. Kept for backward compatibility; new deployments should use PKI admin.
-4. **PKI admin (preferred for remote)** - `mp.pki_encrypted == true` AND `mp.public_key` matches one of `config.security.admin_key[0..2]` (up to three authorized 32-byte Curve25519 public keys, typically copied from the admin node's own `user.public_key`).
+1. **Response messages** — if `messageIsResponse(r)` is true (the payload is a response to one of our earlier admin requests), it's accepted without any further check. The in-file comment flags this as a known-untightened gap: a stricter implementation would remember which `public_key` we last queried and reject responses that don't match.
+2. **Local admin** — `mp.from == 0` (phone app over BLE, serial CLI, internal module); never travels over the air. **Rejected** if `config.security.is_managed` is true, because managed devices expect admin to arrive over the air through an authorized remote path.
+3. **Legacy admin channel (deprecated)** — the packet arrived on a channel named literally `"admin"`. Gated by `config.security.admin_channel_enabled`; returns `NOT_AUTHORIZED` if the flag is false. Kept for backward compatibility; new deployments should use PKI admin.
+4. **PKI admin (preferred for remote)** — `mp.pki_encrypted == true` AND `mp.public_key` matches one of `config.security.admin_key[0..2]` (up to three authorized 32-byte Curve25519 public keys, typically copied from the admin node's own `user.public_key`).
 5. **Fallthrough** → `NOT_AUTHORIZED`.
 
-On top of authorization, any remote admin message that **mutates** state (not a request, not a response) also has to pass a session-key check (`checkPassKey`): the client must first pull a fresh 8-byte `session_passkey` via `get_admin_session_key_request`, then echo that passkey back in the mutating message. The device rotates the passkey after 150 s and rejects values older than 300 s - a narrow anti-replay window on top of the PKI layer.
+On top of authorization, any remote admin message that **mutates** state (not a request, not a response) also has to pass a session-key check (`checkPassKey`): the client must first pull a fresh 8-byte `session_passkey` via `get_admin_session_key_request`, then echo that passkey back in the mutating message. The device rotates the passkey after 150 s and rejects values older than 300 s — a narrow anti-replay window on top of the PKI layer.
 
-`config.security.is_managed = true` disables **local** admin writes (`mp.from == 0` is rejected). It does not by itself force every admin action through PKI - the legacy `"admin"` channel still authorizes remote admin when `config.security.admin_channel_enabled == true`. The AdminModule refuses to persist `is_managed=true` unless at least one `admin_key` is populated - a deliberate guard against operators locking themselves out.
+`config.security.is_managed = true` disables **local** admin writes (`mp.from == 0` is rejected). It does not by itself force every admin action through PKI — the legacy `"admin"` channel still authorizes remote admin when `config.security.admin_channel_enabled == true`. The AdminModule refuses to persist `is_managed=true` unless at least one `admin_key` is populated — a deliberate guard against operators locking themselves out.
 
 ### Key-rotation hazards (actions that invalidate peers)
 
 - **`factory_reset_device`** (the "full" variant, calls `NodeDB::factoryReset(eraseBleBonds=true)`) → **wipes** the X25519 private key; a fresh keypair is generated on the next region-set. Every existing peer holds the old public key, so DMs to this node silently fail PKI decrypt until every peer re-exchanges NodeInfo.
 - **`factory_reset_config`** (the "partial" variant, calls `NodeDB::factoryReset()` with `eraseBleBonds=false`) → **preserves** the X25519 private key in `installDefaultConfig(preserveKey=true)`; the public key is zeroed and gets rebuilt from the preserved private key on the next boot via the NodeDB path's `regeneratePublicKey` call. Identity is preserved and the mesh does not need to re-exchange keys.
 - **`region=UNSET → valid region`** → `ensurePkiKeys` runs inside the same `handleSetConfig` path; missing keys get generated at that moment.
-- **Ham mode transitions** - entering Ham mode (`user.is_licensed=true`) runs `Channels::ensureLicensedOperation`, which **wipes every channel PSK** (all traffic becomes cleartext) and disables the legacy admin channel. The X25519 private key is preserved on the device but not used because `Router::send` skips PKI when `owner.is_licensed` is true. Leaving Ham mode re-enables PKI with the preserved keypair but does not restore the wiped channel PSKs - the operator has to re-set them.
+- **Ham mode transitions** — entering Ham mode (`user.is_licensed=true`) runs `Channels::ensureLicensedOperation`, which **wipes every channel PSK** (all traffic becomes cleartext) and disables the legacy admin channel. The X25519 private key is preserved on the device but not used because `Router::send` skips PKI when `owner.is_licensed` is true. Leaving Ham mode re-enables PKI with the preserved keypair but does not restore the wiped channel PSKs — the operator has to re-set them.
 - **Channel 0 PSK change** → every peer must re-learn the channel hash; cached NodeInfo becomes temporarily unreachable until the next broadcast.
 - **`security.private_key` blanked via admin** → regenerates both halves (unless in Ham mode) and propagates the new public key via NodeInfo.
 
-## NodeDB Layout (v25)
-
-`DEVICESTATE_CUR_VER = 25`, `DEVICESTATE_MIN_VER = 24`. The on-device NodeDB was split in v25 into a slim header table plus four optional satellite stores. Older v24 saves auto-migrate at boot. Old training-data instincts (`node->user.long_name`, `node->position.latitude_i`, `node->is_favorite`, `node->device_metrics.battery_level`) are wrong now - the fields aren't there. Read this section before touching anything that walks `nodeDB->meshNodes`.
-
-### Slim `NodeInfoLite`
-
-`UserLite` is flattened onto `NodeInfoLite` (no nested sub-message); `position` and `device_metrics` are removed entirely (tags reserved). MAC address is dropped. Long names are capped at 25 chars (`max_size:25` in `deviceonly.options`); `hw_model` and `role` are `int_size:8`. Encoded size dropped from ~166 B → ~105 B per node.
-
-Booleans are bit-packed into `NodeInfoLite.bitfield`. **Do not read or write the bits directly** - use the inline helpers in `src/mesh/NodeDB.h`:
-
-```cpp
-nodeInfoLiteHasUser(n)                  // bit 5 - user fields populated
-nodeInfoLiteIsFavorite(n)               // bit 3
-nodeInfoLiteIsIgnored(n)                // bit 4
-nodeInfoLiteIsMuted(n)                  // bit 1
-nodeInfoLiteIsLicensed(n)               // bit 6 - Ham mode peer
-nodeInfoLiteIsKeyManuallyVerified(n)    // bit 0
-nodeInfoLiteHasIsUnmessagable(n)        // bit 8 - "is_unmessagable was sent"
-nodeInfoLiteIsUnmessagable(n)           // bit 7
-// via_mqtt is bit 2 (mask exposed; predicate uses the mask directly)
-
-nodeInfoLiteSetBit(n, NODEINFO_BITFIELD_IS_FAVORITE_MASK, true);  // setter
-```
-
-### Satellite stores
-
-Four `std::unordered_map<NodeNum, …>` members on `NodeDB`, each gated by its own build flag:
-
-| Map               | Value type                      | Build flag                         |
-| ----------------- | ------------------------------- | ---------------------------------- |
-| `nodePositions`   | `meshtastic_PositionLite`       | `MESHTASTIC_EXCLUDE_POSITIONDB`    |
-| `nodeTelemetry`   | `meshtastic_DeviceMetrics`      | `MESHTASTIC_EXCLUDE_TELEMETRYDB`   |
-| `nodeEnvironment` | `meshtastic_EnvironmentMetrics` | `MESHTASTIC_EXCLUDE_ENVIRONMENTDB` |
-| `nodeStatus`      | `meshtastic_StatusMessage`      | `MESHTASTIC_EXCLUDE_STATUSDB`      |
-
-Defaults are ON (i.e., maps **excluded**) for STM32WL only - see `src/mesh/mesh-pb-constants.h`. On every other arch all four maps are present. When excluded, the map member is absent and the corresponding accessors return `false`.
-
-All four maps are guarded by **`mutable concurrency::Lock satelliteMutex`** - concurrent access from receive threads, the phone API state machine, and the renderer is the rule, not the exception.
-
-### Accessor convention
-
-**Never hand out pointers into the maps.** Use the copy-out accessors on `NodeDB`:
-
-```cpp
-bool copyNodePosition(NodeNum, meshtastic_PositionLite &out)       const;
-bool copyNodeTelemetry(NodeNum, meshtastic_DeviceMetrics &out)     const;
-bool copyNodeEnvironment(NodeNum, meshtastic_EnvironmentMetrics &out) const;
-bool copyNodeStatus(NodeNum, meshtastic_StatusMessage &out)        const;
-```
-
-Each takes the lock, copies the value if present, returns `false` if the entry is absent or the DB is excluded. Pass-by-out-param is deliberate - pointer-style accessors would invite UAF and lock-leak bugs across the renderer. The "has any X" convenience predicates (`hasValidPosition` etc.) are implemented in terms of these.
-
-Writers go through `setNodeStatus`, `updatePosition`, `updateTelemetry` (which dispatches on `which_variant` for device vs environment metrics) - these own the lock and the eviction hooks.
-
-### Eviction
-
-Every code path that drops a node from the header table must also evict the satellites. The single chokepoint is `eraseNodeSatellites(NodeNum)`; it's already called from `getOrCreateMeshNode`'s oldest-boring eviction, `demoteOldestHotNodesToWarm` (the over-cap warm-tier migration), `removeNodeByNum`, both branches of `resetNodes`, `cleanupMeshDB`, `addFromContact`'s ignored-branch, and `AdminModule`'s `set_ignored_node`. Add new eviction sites here, not by calling `.erase()` directly. (Note: `enforceSatelliteCaps`/`evictSatelliteOverCap` call `.erase()` directly on purpose - that's a satellite-only cap trim where the node _stays_ in the header, a different operation from this chokepoint.)
-
-### Warm tier (long-tail identity)
-
-On every arch except STM32WL and bare nRF52832 (`WARM_NODE_COUNT > 0`), a node evicted from the header table is not forgotten outright: `WarmNodeStore` (`src/mesh/WarmNodeStore.{h,cpp}`) keeps a 40 B `{num, last_heard, public_key}` record per evicted node - primarily so PKI DMs to/from a long-tail node keep decrypting without re-running a NodeInfo exchange (the rest of `NodeInfoLite` rebuilds from traffic in seconds).
-
-- **Write:** `getOrCreateMeshNode`'s eviction and `demoteOldestHotNodesToWarm` (the over-cap boot migration) call `warmStore.absorb(num, last_heard, key)` _before_ the node leaves the header.
-- **Read-back:** `getOrCreateMeshNode` calls `warmStore.take()` to rehydrate `last_heard` + key when a warm node is re-admitted; `copyPublicKey()` falls back to the warm tier so the PKI send path finds keys for evicted peers.
-- **Persistence:** nRF52840 uses a 12 KB raw-flash record-ring at `0xEA000` (below LittleFS; append + replay + compact-on-rotate, link-guarded by `nrf52840_s140_v7.ld` and `extra_scripts/nrf52_warm_region.py`). Everywhere else: a `/prefs/warm.dat` snapshot flushed by `saveIfDirty()` on the node-DB save cadence.
-- **Tunables** (`mesh-pb-constants.h`): `WARM_NODE_COUNT` (per-arch; `0` disables the tier) and `MAX_NUM_NODES` (hot cap - 120 on nRF52840/generic ESP32 to fit the 28 KB LittleFS; ESP32-S3 picks 100/200/250 at boot from its flash size). Verbose migration/self-care tracing routes through `LOG_MIGRATION`, gated by `MESHTASTIC_NODEDB_MIGRATION_VERBOSE`.
-- **`MAX_NUM_NODES` on native is not in that header and is not a constant.** `variants/native/portduino{,-buildroot}/variant.h` define it as `portduino_config.MaxNodes` - resolved at **runtime**, default **200**, overridable per-host with `General: MaxNodes` in the portduino YAML. `variant.h` is reached first, so the `ARCH_PORTDUINO` branch in `mesh-pb-constants.h` never fires; it is now `#error`-guarded rather than holding a plausible-looking `250`. Reading 250 there yields a protected-node cap of 248 when the real one is 198 (`numProtectedNodes() < MAX_NUM_NODES - 2`), which has already produced one wrong diagnosis. The separate 250 in `NodeDB::getMaxNodesAllocatedSize()` is `NODEDB_MIGRATION_LOAD_CEILING`, a decode allowance for files from larger-cap firmware - not a cap.
-
-### Satellite caps
-
-Only the freshest `MAX_SATELLITE_NODES` nodes keep satellite payloads; the rest of the header table carries just the `NodeInfoLite`. The cap is **per-platform**: 40 on RAM-constrained parts (nRF52840, generic ESP32) since the four maps live in internal SRAM (not PSRAM, ~408 B/node across the four), and 250 on flash-rich hosts (ESP32-S3, portduino) so every hot node can carry rich data as before the cap existed. `enforceSatelliteCaps()` trims each map to the cap on load (returns whether it trimmed); `evictSatelliteOverCap()` trims before each insert. Eviction is by the owning node's hot `last_heard` (stalest first, demoted/absent nodes rank as `last_heard==0`); self is never trimmed.
-
-### On-boot self-care
-
-`NodeDB::nodeDBSelfCare()` runs once identity is established (the constructor after key (re)gen, and `reloadFromDisk()` - _not_ inside `loadFromDisk`, where `getNodeNum()` is still 0). It confirms self is present (warns if a non-empty DB is missing us - a foreign/over-cap file), pins self to index 0, demotes/trims only **non-self** overflow into the warm tier, then rewrites `nodes.proto` **once** and only if it healed something - and never while encrypted storage is locked (it would persist placeholder defaults). `loadFromDisk` deliberately leaves the loaded store untrimmed for this pass.
-
-### Sync flow: thin NodeInfo + post-COMPLETE_ID replay (no opt-in)
-
-There is no capability flag and no special "gradient" nonce. The **default** sync flow is:
-
-1. Config / module-config / channel / metadata segments (same as before).
-2. `STATE_SEND_OWN_NODEINFO` - **our own** NodeInfo, still bundled with our position and device_metrics (because the replay snapshot excludes our own NodeNum). Emitted via `ConvertToNodeInfo(lite)`.
-3. `STATE_SEND_OTHER_NODEINFOS` - every other peer's NodeInfo, **always thin** (no `position`, no `device_metrics`). Emitted via `ConvertToNodeInfoThin(lite)`.
-4. `STATE_SEND_FILEMANIFEST` → `STATE_SEND_COMPLETE_ID` - the phone sees `config_complete_id` and treats sync as done.
-5. `STATE_SEND_PACKETS` - live mesh packets, with a trailing replay drain interleaved. The replay drain walks four cached satellite stores in order (positions → telemetry → environment → status) and emits each cached entry as an ordinary `MeshPacket` on the matching portnum (`POSITION_APP`, `TELEMETRY_APP` device + environment variants, `NODE_STATUS_APP`). These are indistinguishable on the wire from live mesh traffic, so clients need no special handling - any code that already updates UI on `POSITION_APP` etc. works.
-
-`PhoneAPI::sendConfigComplete()` arms `replayPhase = REPLAY_PHASE_POSITIONS` for default/full sync and `SPECIAL_NONCE_ONLY_NODES`, while `SPECIAL_NONCE_ONLY_CONFIG` skips replay. The drain runs inside `STATE_SEND_PACKETS` via `popReplayPacket()`, lower priority than live traffic. When all four phases drain, `replayPhase` flips back to `REPLAY_PHASE_IDLE` and the snapshot vectors get `shrink_to_fit`ed.
-
-STM32WL and any other build with all four `MESHTASTIC_EXCLUDE_*DB` flags set produces zero replay packets - `popReplayPacket` advances through each phase in microseconds without emitting anything.
-
-Special nonces that still mean something:
-
-- `SPECIAL_NONCE_ONLY_CONFIG` (69420) - skip node sync entirely, just config.
-- `SPECIAL_NONCE_ONLY_NODES` (69421) - skip config segments, jump straight to `STATE_SEND_OWN_NODEINFO`. Still gets the post-COMPLETE_ID replay drain.
-
-There are no other reserved nonces; everything else is a fresh random `want_config_id` from the client.
-
-### v24 → v25 migration
-
-The legacy migration code lives in **`src/mesh/NodeDBLegacyMigration.cpp`**, not in `NodeDB.cpp`. It owns the `meshtastic_NodeDatabase_Legacy` callback and `NodeDB::migrateLegacyNodeDatabase()`. The legacy proto descriptor is `protobufs/meshtastic/deviceonly_legacy.proto` (only included by the migration TU). The boot path peeks the file's leading version tag, runs the migration if `version < 25`, then re-saves in v25 layout. The legacy descriptor is scheduled for removal once `DEVICESTATE_MIN_VER` is bumped.
-
-### Read-site rules of thumb
-
-- Never `node->position.X` / `node->device_metrics.X` - those fields no longer exist. Pull from the satellite map via `copyNodePosition` / `copyNodeTelemetry`.
-- Never `node->user.long_name` - `long_name`, `short_name`, `public_key`, `hw_model`, `role`, `macaddr` (gone), `is_licensed`, `is_unmessagable` are flat on `NodeInfoLite`.
-- Never `node->is_favorite` / `node->is_ignored` / `node->via_mqtt` / `node->is_key_manually_verified` - use the bitfield helpers.
-- Never assume `nodeDB->getMeshNode(num)->position.time` - call `copyNodePosition` and check the return.
-- Don't lock `satelliteMutex` yourself in renderer code; the copy-out accessors already do.
-
-Unit tests for the conversion layer live in `test/test_type_conversions/test_main.cpp` (Unity) - bitfield round-trips, `long_name` truncation, thin-vs-full conversions. Add cases there when extending the schema.
-
 ## Project Structure
 
-```text
+```
 firmware/
 ├── src/                    # Main source code
 │   ├── main.cpp           # Application entry point
@@ -313,44 +184,18 @@ firmware/
 │   └── native/           # Linux/Portduino variants
 ├── protobufs/            # Protocol buffer definitions
 ├── boards/               # Custom PlatformIO board definitions
-├── test/                 # Native unit-test suites (count = the test_* dirs, detected on the fly)
+├── test/                 # Unit tests (12 test suites)
 └── bin/                  # Build and utility scripts
 ```
 
 ## Coding Conventions
 
-### Formatting & the trunk toolchain
-
-`trunk fmt` is the project formatter (`trunk_check` CI rejects unformatted code). For Claude Code users, `.claude/settings.json` ships a PostToolUse hook that runs `trunk fmt --force` on every file the agent writes or edits. The hook is pure sh/grep/sed - no python or jq required - but trunk itself must be able to run:
-
-- Trunk's launcher (`~/.cache/trunk/launcher/trunk`, or `trunk` on PATH) downloads the CLI version pinned in `.trunk/trunk.yaml` on first use and again whenever that pin is bumped. **The launcher needs `curl` or `wget`**; without one it fails with "Cannot download… please install curl or wget", and the hook surfaces that as a warning on every write.
-- No curl/wget available (e.g. a minimal WSL image)? Bootstrap by hand with any Python (PlatformIO bundles one at `~/.platformio/penv/bin/python`): download `https://trunk.io/releases/<ver>/trunk-<ver>-linux-x86_64.tar.gz` and place the `trunk` binary at `~/.cache/trunk/cli/<ver>-linux-x86_64/trunk` (chmod +x), where `<ver>` is the `cli.version` from `.trunk/trunk.yaml`.
-- The hook fails loudly by design (visible warning, non-blocking). Silent no-op formatting hooks hide real breakage - don't re-add `2>/dev/null || true` around the whole thing.
-- More generally: don't assume a stock Linux userland in hooks or helper scripts - minimal WSL/container images may lack `python3`, `curl`, `wget`, and `jq`. Prefer plain sh + coreutils, or PlatformIO's bundled Python for anything heavier.
-
 ### General Style
 
 - Follow existing code style - run `trunk fmt` before commits
 - Prefer `LOG_DEBUG`, `LOG_INFO`, `LOG_WARN`, `LOG_ERROR` for logging
-- **Three logging tiers for diagnostics.** `LOG_TRACE` is the per-packet/per-poll firehose - compiled out by default (`MESHTASTIC_TRACE_LOGGING=1` enables; always on for portduino). Subsystem bring-up detail routes through a per-subsystem gate macro instead, e.g. `LOG_DEBUG_GPS(...)` in `src/gps/GPSLog.h` (`GPS_DEBUG=1` enables; costs no flash when off) - model new subsystem gates on it or on `LOG_MIGRATION` (`src/mesh/WarmNodeStore.h`): `#ifndef` value-default, `#if SYM` value test, `((void)0)` off-branch. Genuine anomalies stay unconditional `LOG_WARN`/`LOG_ERROR`.
-- **Format node IDs and packet IDs as `0x%08x` in logs.** This covers `NodeNum`/`PacketId` and the `uint32_t` packet fields `from`, `to`, `id`, `dest`, `source`, `request_id`, and `node_id`. They are 32-bit, so 8 hex digits is exact - `%08x` never truncates or leaves a value ragged. Do **not** use `%x` (variable width) or `%0x` (a no-op typo for `%08x` - the `0` flag does nothing without a width). User-facing display uses `!%08x` (the `!xxxxxxxx` convention), e.g. `Applet::hexifyNodeNum`.
-- **Do not zero-pad one-byte values to 8.** `next_hop`, `relay_node`, and the next-hop hint are `uint8_t` last-byte route hints, and `channel` is a one-byte hash/index - log these as `0x%x` (or `%d`). Padding a byte to `0x000000ab` falsely implies a full node number. The same goes for I2C addresses, register values, flags/bitmasks, and error/reason codes: they are not IDs, so leave them `0x%x`.
 - Use `assert()` for invariants that should never fail
 - C++17 features are available (`std::optional`, structured bindings, `if constexpr`, etc.)
-- **Keep code comments minimal - one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior.
-- **Documentation does not live in this repo. Do not add it here.** This repository holds firmware code. There is no `docs/` directory - the design documents that used to sit there were published to [meshtastic/meshtastic](https://github.com/meshtastic/meshtastic) in #11488 and the directory was deleted - and it must not come back. Do not create a `.md` file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow.
-- **Never compare against `millis()` directly. Use `Throttle`.** `src/mesh/Throttle.h` is the sanctioned way to ask about time, and CI enforces this (`millis-deadline-check` in `.github/workflows/test_native.yml` fails the PR on a new `millis() >` / `< millis()` comparison).
-  - `Throttle::isWithinTimespanMs(lastMs, intervalMs)` - true while still inside the cooldown.
-  - `Throttle::hasElapsed(lastMs, intervalMs)` - its complement, true once the interval has passed (inclusive `>=`). Prefer this to spelling `!isWithinTimespanMs(...)`.
-  - `Throttle::execute(&lastMs, intervalMs, func)` - function-pointer form that updates the timestamp on fire.
-  - `Throttle::deadlinePassed(deadlineMs)` - for a stored absolute deadline that cannot be re-expressed as "interval since an event". Uses an unsigned half-range compare; reads deadlines more than ~24.8 days out as already passed, which no interval in this firmware approaches (the longest is 24 h).
-  - `Throttle::deadlinePassedAt(nowMs, deadlineMs)` - the same test against a caller-supplied `now`, for a loop that snapshots the clock once and then tests many deadlines (`NextHopRouter::doRetransmissions()`). Take the snapshot from `Time::getMillis()`, not `millis()`.
-
-  Raw `millis() > deadline` or `deadline < millis()` is rollover-unsafe: the comparison inverts while the deadline sits on the far side of the 32-bit wrap, so the action fires immediately (losing its whole wait) or blocks for roughly the interval it should have waited - days, for the nRF52 flash-corruption backoff. All five helpers subtract first, so unsigned wraparound cancels out. `Throttle` reads the clock through `Time::getMillis()` (`src/UptimeClock.h`), which means every one of its ~94 call sites is time-injectable - a native test can drive `Time::setTestMillis(0xFFFFFF00)` across the wrap. For _timestamps_ (not deadlines) there is `Time::getMillisMonotonic()` / `Time::getUptimeSecs()` - a 64-bit monotonic uptime read. Readers are pure: they add their own wrap-immune elapsed time to a snapshot published by `Time::serviceMonotonic()`, which the main loop calls every iteration and which is **the only writer**. Never call `serviceMonotonic()` from anywhere else - two writers can count one wrap twice, putting every uptime and wall-clock reading ~49.7 days into the future for the rest of the boot. Not ISR-safe (the snapshot is read under a seqlock); see the contract in `UptimeClock.h`. Deadline and interval checks should still use `Throttle`, which needs no carry state at all.
-
-  **Sentinel hazard.** If a deadline variable also encodes "inactive" - `0` for `rebootAtMsec`, `shutdownAtMsec`, `alertBannerUntil`, `fixHoldEnds`; `UINT32_MAX` for `nagCycleCutoff` - test that sentinel _before_ the elapsed comparison, and match the test to the sentinel actually in use. `if (deadline && Throttle::deadlinePassed(deadline))` covers the `0` family only; `nagCycleCutoff` needs `deadline != UINT32_MAX`, or a separate armed flag as `ExternalNotificationModule` does with `isNagging`. Every sentinel value is arithmetically far in the past, so a correct comparison reads it as "expired" and fires immediately: `rebootAtMsec = -1` meaning "never" is what would have become a reboot loop. Never fold the sentinel into the helper.
-
-  **And decide which way the sentinel should fall.** "Inactive" does not always mean "suppress". At the GPS fix-hold site `fixHoldEnds == 0` means _no hold is in force_, which is exactly when a new hold must be armed - the naive comparison it replaced was `(fixHoldEnds + GPS_THREAD_INTERVAL) < millis()`, always true when nothing was armed. Guarding it with `fixHoldEnds != 0 &&` looks like this rule and inverts the site: nothing re-arms, nothing publishes, and the receiver stays powered until the search timeout. Read the surrounding logic before adding the guard. `fixHoldInForce()` in `src/gps/GPS.cpp` is the worked example - state the predicate positively, so the sentinel has an honest answer, and derive both decisions from it - with `test/test_gps_fix_hold/` pinning both directions.
 
 ### Naming Conventions
 
@@ -440,7 +285,7 @@ Multiple display driver families in `src/graphics/`:
 
 **InkHUD** (`src/graphics/niche/InkHUD/`) is an event-driven e-ink UI framework:
 
-- Applet-based architecture - modular display tiles
+- Applet-based architecture — modular display tiles
 - Read-only, static display optimized for minimal refreshes and low power
 - Configured per-variant via `nicheGraphics.h`
 - Separate PlatformIO config: `src/graphics/niche/InkHUD/PlatformioConfig.ini`
@@ -497,7 +342,6 @@ Key defines in variant.h:
 - Regenerate with `bin/regen-protos.sh`
 - Message types prefixed with `meshtastic_`
 - Nanopb `.options` files control field sizes and encoding
-- **Never edit or commit files under `src/mesh/generated/`.** They are regenerated from the [`meshtastic/protobufs`](https://github.com/meshtastic/protobufs) submodule by the `update_protobufs.yml` GitHub Action and any hand edits will be overwritten - guaranteed merge conflict on the next sync. To change a wire format, open a PR against the protobufs repo first; the workflow then re-runs `bin/regen-protos.sh` and opens a PR here with the regenerated sources.
 
 ### Conditional Compilation
 
@@ -517,7 +361,7 @@ Key defines in variant.h:
 
 ## Build System
 
-### Agent Tooling Baseline
+## Agent Tooling Baseline
 
 Mirror counterpart: `AGENTS.md` under **Agent Tooling Baseline**.
 
@@ -570,10 +414,9 @@ pio run -e native-macos       # Build headless macOS meshtasticd (Homebrew prere
 
 1. Create directory under `variants/<arch>/<name>/`
 2. Add `variant.h` with pin definitions and hardware capability defines
-3. Add `platformio.ini` with build config - use `extends` to reference common base (e.g., `esp32s3_base`)
-4. Set `board_level` (required - `release` for a normal variant; see "Build Matrix Generation")
-5. Set `custom_meshtastic_support_level` (1-3) and the other `custom_meshtastic_*` metadata
-6. For e-ink displays, add `nicheGraphics.h` for InkHUD configuration
+3. Add `platformio.ini` with build config — use `extends` to reference common base (e.g., `esp32s3_base`)
+4. Set `custom_meshtastic_support_level = 1` (PR builds) or `2` (merge builds)
+5. For e-ink displays, add `nicheGraphics.h` for InkHUD configuration
 
 ### Adding a New Telemetry Sensor
 
@@ -657,16 +500,11 @@ The CI uses `bin/generate_ci_matrix.py` to dynamically select which targets to b
 ./bin/generate_ci_matrix.py all --level pr
 ```
 
-Every variant env **must** declare a `board_level` in its `platformio.ini`; the matrix
-generator exits non-zero if any env is missing it or uses an unrecognized value:
+Variants can specify their support level in `platformio.ini`:
 
-- `board_level = pr` - Smallest subset, built on every PR (and in every larger matrix)
-- `board_level = release` - The full release matrix, built on push / schedule / `workflow_dispatch`
-- `board_level = extra` - Opt-in only, built when explicitly requested via `--level extra`
-
-`custom_meshtastic_support_level` (1-3) is **not** part of this filtering. It is variant
-metadata that `bin/platformio-custom.py` emits as `supportLevel` in the generated
-hardware list; changing it does not change which targets CI builds.
+- `custom_meshtastic_support_level = 1` - Actively supported, built on every PR
+- `custom_meshtastic_support_level = 2` - Supported, built on merge to main branches
+- `board_level = extra` - Extra builds, only on full releases
 
 ### Running Workflows Locally
 
@@ -676,130 +514,34 @@ Most workflows can be triggered manually via `workflow_dispatch` for testing.
 
 ### Native unit tests (C++)
 
-Unit tests in `test/` directory. The canonical suite count is detected on the fly: the `test_*` directories under `test/` are the register, and `bin/run-tests.sh` cross-checks the suites that actually ran against them on every full run. **Never state the count as a literal anywhere** - it is whatever `test/test_*` contains right now. In CI, the `suite-shrinkage-check` job (`test_native.yml`) fails a PR that loses a `test_*` directory relative to its merge base unless the suite is named in the PR title, body, or a commit message - deleting a suite therefore requires saying so. The list below is a partial description of what suites cover, not an inventory:
+Unit tests in `test/` directory with 12 test suites:
 
-- `test_admin_radio/` - LoRa region/config validation, AdminModule dispatch, node-DB metadata saves
-- `test_fscommon_getfiles/` - bounded file-manifest walk (cap, depth, truncation reporting)
-- `test_atak/` - ATAK integration
 - `test_crypto/` - Cryptography
-- `test_default/` - Default configuration
-- `test_hop_scaling/` - Hop scaling histogram and required-hop logic
-- `test_http_content_handler/` - HTTP handling
-- `test_mac_from_string/` - MAC address parsing
+- `test_mqtt/` - MQTT integration
+- `test_radio/` - Radio interface
 - `test_mesh_module/` - Module framework
 - `test_meshpacket_serializer/` - Packet serialization
-- `test_mqtt/` - MQTT integration
-- `test_nexthop_routing/` - Next-hop routing logic
-- `test_nodedb_blocked/` - NodeDB blocked-node handling
-- `test_packet_history/` - Packet history tracking
-- `test_packet_signing/` - Packet signing
-- `test_position_module/` - Position module behaviour
-- `test_position_precision/` - Position precision helpers
-- `test_radio/` - Radio interface
-- `test_rtc/` - RTC / time handling
-- `test_serial/` - Serial communication
-- `test_tak_config/` - TAK (ATAK) team/role value fidelity through set/save/load/get
-- `test_module_config/` - every ModuleConfig submessage survives admin set -> save -> load -> get
-- `test_traffic_management/` - Traffic management (dedup, rate-limit, hop-trim, role exceptions)
 - `test_transmit_history/` - Retransmission tracking
-- `test_type_conversions/` - NodeDB v25 type conversion (bitfield round-trips, NodeInfoLite)
-- `test_utf8/` - UTF-8 utilities
-- `test_warm_store/` - Warm-tier node store
+- `test_atak/` - ATAK integration
+- `test_default/` - Default configuration
+- `test_http_content_handler/` - HTTP handling
+- `test_serial/` - Serial communication
 
-**Preferred run command - `bin/run-tests.sh`** (defaults to the `coverage` env; emits a machine-readable verdict on the final line; new `test_*` directories are picked up automatically):
-
-```bash
-./bin/run-tests.sh                             # all suites
-./bin/run-tests.sh -f test_traffic_management  # single suite (yields FILTERED, not GREEN)
-```
-
-**The harness is Linux-only, and rejects anything else.** `bin/run-tests.sh` needs bash 4+ and GNU coreutils/find (`find -printf`, `md5sum`, `-executable`), so it exits 2 on a non-Linux `uname` rather than degrade quietly - a state check that silently mis-hashes a sandbox still prints a verdict, and that verdict would be worthless. The `native-macos` PlatformIO env is a **build** target for `meshtasticd`, not a test host. On macOS or Windows use `./bin/test-native-docker.sh`.
-
-**Sanitizer coverage is per env, and only one env has any.** `coverage` (the default) adds gcov + ASan/LSan on top of `native`. **`native` itself has none** - verified, zero ASan symbols in the built binary. A `-e native` run is _not_ sanitized, so do not reason from "run-tests.sh uses ASan" when you passed `-e native`.
-
-**A signal name from the runner is not a crash.** `exit(UNITY_END())` returns the failure count, and PlatformIO's native runner renders a non-zero exit code as a POSIX signal - 4 failures prints `Program received signal SIGILL`, 5 prints `SIGTRAP`, and the suite is reported `[ERRORED]` instead of `[FAILED]`. Check the exit code against the failure count before theorising about memory bugs; confirm any real crash under a debugger.
-
-**Suite order is randomisable.** `./bin/run-tests.sh --shuffle` runs suites in a seeded random order; `--seed <n>` replays one. The seed defaults to the commit SHA (deterministic per commit, varied across commits), is printed at the start and on the `RESULT:` line, and the full order is printed on failure. CI shuffles its area order the same way, seeded from `GITHUB_SHA`. A single green seed is not evidence of order independence.
-
-**`-f` is not a gate.** A filtered run can pass while a full run fails, because filtering removes the suites that _create_ the state a later suite trips over. Iterate with `-f`; gate on a full run.
-
-Exit codes and verdicts (exact counts will vary; examples below are illustrative):
-
-| Exit | Verdict    | Meaning                                                                                                                                                                                                              |
-| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0    | `GREEN`    | All canonical suites ran, all passed, no ignored test cases                                                                                                                                                          |
-| 1    | `RED`      | At least one failure, build error, or sanitizer fault                                                                                                                                                                |
-| 2    | `AMBER`    | All that ran passed, but something was lost or unexplained: a suite silently went missing on a full run, individual test cases were skipped (`TEST_IGNORE`), or a suite left behind shared state it does not declare |
-| 3    | `FILTERED` | A `-f` run completed cleanly; suites outside the filter were intentionally not run                                                                                                                                   |
-
-Examples - exact counts will vary by suite count and env:
-
-```text
-# GREEN: all suites ran and passed
-RESULT: GREEN N/N suites passed, all CLEAN
-
-# RED: real test failure
-RESULT: RED 1 failed
-
-# RED: sanitizer exit-time abort (all tests passed but process aborted at exit)
-RESULT: RED exit-time abort (tests passed; likely sanitizer - see hint above)
-
-# AMBER: a suite silently went missing on a full run
-RESULT: AMBER 23/24 suites ran (missing: test_radio) - all that ran passed
-
-# FILTERED: single suite run completed cleanly
-RESULT: FILTERED 1/24 suites ran (not run: test_admin_radio test_atak …) - filtered: test_serial
-```
-
-> **Copilot interface note:** When running tests via the Copilot chat interface, edits made through the chat may not be reflected in the on-disk files that the test binary reads. If tests pass in chat but fail locally (or vice versa), verify the files on disk match what you expect before trusting the result. Always confirm with a local terminal run.
-
-Raw `pio test` (no sanitizers, no verdict logic) - use only when you need to override the env:
-
-```bash
-~/.platformio/penv/bin/python -m platformio test -e native -f test_your_suite > /tmp/test_out.txt 2>&1
-grep -E 'error:|PASS|FAIL|succeeded|failed' /tmp/test_out.txt
-tail -15 /tmp/test_out.txt
-```
-
-Do **not** pipe `pio test` - line-buffering makes the terminal appear hung and hides build errors.
+Run with: `pio test -e native`
 
 Simulation testing: `bin/test-simulator.sh`
 
 Quick entry point for new test modules: `test/README.md` (native unit-test authoring guide, skeleton, pitfalls, and setup checklist).
 
-### Shared state: every suite gets a clean sandbox
+### Hardware-in-the-loop tests (`mcp-server/tests/`)
 
-Each suite runs inside its own scratch `$HOME` (`bin/pio-test-isolate.sh`, wired in per env as `test_testing_command`, so a bare `pio test` and CI get it too). **State never crosses a suite boundary.** Mutation _inside_ a suite is free; carrying state _out_ of one is impossible by construction, not by policy.
-
-The state in question lives in `~/.portduino/default/prefs/` - `nodes.proto`, `config.proto`, `channels.proto`, `module.proto`, `device.proto`, `warm.dat`, `transmit_history.dat`. `NodeDB`'s constructor calls `loadFromDisk()`, so any suite that constructs one reads it, and several `NodeDB` paths (`removeNodeByNum()`, `resetNodes()`, `nodeDBSelfCare()`, and the constructor when the file is absent) write it without being asked.
-
-Two orthogonal axes: **PASS/FAIL x CLEAN/DIRTY**.
-
-- **CLEAN** - nothing changed, or everything that changed is declared.
-- **DIRTY** - an undeclared path changed. Graded **AMBER**: with isolation in place it means "undeclared", not "dangerous".
-- **MISSING** - a declared write did not happen. A warning only; it catches persistence that silently stopped working.
-
-Declare deliberate writes in **`test/state-manifest.tsv`** - one central file, `<suite>` / `<flags>` / `<reason>`, with the reason mandatory and reviewed on change. Central so every opt-out is visible in one diffable list; per-suite files hide growth. `run-tests.sh` prints how many suites declare non-default handling on every run.
-
-| Flag              | Meaning                                                                                                                                                                                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| _(no entry)_      | the default: fresh state in, contents discarded out                                                                                                                                                         |
-| `writes=<a,b>`    | files this suite mutates on purpose; matched on the path relative to the sandbox `$HOME` or just the basename                                                                                               |
-| `state=per-suite` | state persists across this suite's own test cases (persistence round-trips, migration ladders). Only the suite boundary is checked; the default is per-test, which names the exact test that dirtied things |
-
-No flag grants cross-suite carry. A suite that needs another suite's output needs an explicit fixture, not inheritance.
-
-`./bin/run-tests.sh --write-manifest` prints the entries a run would need, for a human to paste and justify - it never applies them, and neither does CI. `bin/test-state-check.sh` is the checker's own self-test: fixtures asserting CLEAN / CLEAN / DIRTY / MISSING, plus the before-empty assertion.
-
-### Hardware-in-the-loop tests ([meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp))
-
-Separate pytest suite that exercises real USB-connected Meshtastic devices. It now lives in the standalone [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) repo, run against a firmware checkout via `MESHTASTIC_FIRMWARE_ROOT`. See the **MCP Server & Hardware Test Harness** section below for invocation, tier layout, and agent usage rules.
+Separate pytest suite that exercises real USB-connected Meshtastic devices. See the **MCP Server & Hardware Test Harness** section below for invocation, tier layout, and agent usage rules.
 
 ## MCP Server & Hardware Test Harness
 
-The firmware-aware [MCP](https://modelcontextprotocol.io/) server plus its pytest-based integration suite now live in the standalone [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) repo. AI agents that speak MCP get a well-defined tool surface for flashing, configuring, and inspecting physical Meshtastic devices - use it instead of hand-rolling `pio` or `meshtastic --port` calls where possible. The meshtastic-mcp repo's README is the operator-facing setup doc; this section is the agent-facing usage contract.
+The `mcp-server/` directory houses a firmware-aware [MCP](https://modelcontextprotocol.io/) server plus a pytest-based integration suite. AI agents that speak MCP get a well-defined tool surface for flashing, configuring, and inspecting physical Meshtastic devices — use it instead of hand-rolling `pio` or `meshtastic --port` calls where possible. `mcp-server/README.md` is the operator-facing setup doc; this section is the agent-facing usage contract.
 
-The repo registers the server via `.mcp.json` at the repo root - Claude Code / Copilot pick it up automatically and run it through `uvx --from git+https://github.com/meshtastic/meshtastic-mcp meshtastic-mcp`, so the MCP tools work with no local build. To run the pytest hardware harness instead, clone [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) and point `MESHTASTIC_FIRMWARE_ROOT` at this firmware checkout.
+The repo registers the server via `.mcp.json` at the repo root — Claude Code picks it up automatically once `mcp-server/.venv/` is built (`cd mcp-server && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'`).
 
 ### When to use which surface
 
@@ -807,80 +549,70 @@ The repo registers the server via `.mcp.json` at the repo root - Claude Code / C
 | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | Find a connected device                           | `mcp__meshtastic__list_devices`                                                                                  |
 | Read a live node's config/state                   | `mcp__meshtastic__device_info`, `list_nodes`, `get_config`                                                       |
-| Mutate a device (owner, region, channels, reboot) | `set_owner`, `set_config`, `set_channel_url`, `reboot`, `shutdown`, `factory_reset` - all require `confirm=True` |
+| Mutate a device (owner, region, channels, reboot) | `set_owner`, `set_config`, `set_channel_url`, `reboot`, `shutdown`, `factory_reset` — all require `confirm=True` |
 | Flash firmware to a variant                       | `pio_flash` (any arch) or `erase_and_flash` (ESP32 factory install)                                              |
 | Stream serial logs while debugging                | `serial_open` → `serial_read` loop → `serial_close`                                                              |
 | Administer `userPrefs.jsonc` build-time constants | `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`                                        |
-| Run the regression suite                          | `./run-tests.sh` from a meshtastic-mcp checkout (or `/test` slash command)                                       |
+| Run the regression suite                          | `./mcp-server/run-tests.sh` (or `/test` slash command)                                                           |
 | Diagnose a specific device                        | `/diagnose [role]` slash command (read-only)                                                                     |
 | Triage a flaky test                               | `/repro <node-id> [count]` slash command                                                                         |
 
 **One MCP call per port at a time.** `SerialInterface` holds an exclusive OS-level lock on the serial port for its lifetime. If a `serial_*` session is open on `/dev/cu.usbmodem101`, calling `device_info` on the same port will fail fast pointing at the active session. Sequence calls: open → read/mutate → close, then next device. Never parallelize tool calls on the same port.
 
-### MCP tool surface (44 tools)
+### MCP tool surface (43 tools)
 
-Grouped by purpose. Full argument shapes in the meshtastic-mcp repo's README; a few high-value signatures are called out here.
+Grouped by purpose. Full argument shapes in `mcp-server/README.md`; a few high-value signatures are called out here.
 
 - **Discovery & metadata**: `list_devices`, `list_boards`, `get_board`
 - **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 only), `update_flash` (ESP32 OTA), `touch_1200bps`
 - **Serial sessions** (long-running, 10k-line ring buffer): `serial_open`, `serial_read`, `serial_list`, `serial_close`
 - **Device reads**: `device_info`, `list_nodes`
-- **Device writes**: `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `send_input_event` (inject a button/key press via the firmware's InputBroker), `inject_frame` (inject an over-the-air-style frame into the RX pipeline - see below), `set_debug_log_api`; destructive/power-state writes require `confirm=True`: `reboot`, `shutdown`, `factory_reset`
+- **Device writes**: `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `send_input_event` (inject a button/key press via the firmware's InputBroker), `set_debug_log_api`; destructive/power-state writes require `confirm=True`: `reboot`, `shutdown`, `factory_reset`
 - **userPrefs admin** (build-time constants, not runtime config): `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile`
 - **Vendor escape hatches**: `esptool_chip_info`, `esptool_erase_flash`, `esptool_raw`, `nrfutil_dfu`, `nrfutil_raw`, `picotool_info`, `picotool_load`, `picotool_raw`
 - **USB power control** (via `uhubctl`, per-port PPPS toggle): `uhubctl_list` (read-only), `uhubctl_power(action='on'|'off', confirm=True)`, `uhubctl_cycle(delay_s, confirm=True)`. Target by raw `(location, port)` or by `role` (`"nrf52"`, `"esp32s3"`); role lookup checks `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` + `_PORT_<ROLE>` env vars first, falls back to VID auto-detection.
-- **Observability** (UI tier + operator ad-hoc): `capture_screen(role, ocr=True)` - grabs a USB-webcam frame of the device OLED and optionally OCRs it. Requires `meshtastic-mcp[ui]` extras (`opencv-python-headless`, `easyocr`) and `MESHTASTIC_UI_CAMERA_DEVICE_<ROLE>` env var; falls through to a 1×1 black PNG `NullBackend` when unconfigured.
+- **Observability** (UI tier + operator ad-hoc): `capture_screen(role, ocr=True)` — grabs a USB-webcam frame of the device OLED and optionally OCRs it. Requires `mcp-server[ui]` extras (`opencv-python-headless`, `easyocr`) and `MESHTASTIC_UI_CAMERA_DEVICE_<ROLE>` env var; falls through to a 1×1 black PNG `NullBackend` when unconfigured.
 
-`confirm=True` is a tool-level gate on top of whatever permission prompt your MCP host shows. **Don't bypass it** by asking the host to auto-approve - it exists specifically because MCP hosts sometimes remember "always allow this tool" and that's dangerous for `factory_reset`, `erase_and_flash`, `uhubctl_power(action='off')`, and `uhubctl_cycle`.
+`confirm=True` is a tool-level gate on top of whatever permission prompt your MCP host shows. **Don't bypass it** by asking the host to auto-approve — it exists specifically because MCP hosts sometimes remember "always allow this tool" and that's dangerous for `factory_reset`, `erase_and_flash`, `uhubctl_power(action='off')`, and `uhubctl_cycle`.
 
-**TCP / native-host nodes.** Setting `MESHTASTIC_MCP_TCP_HOST=<host[:port]>` makes `list_devices` surface a `meshtasticd` daemon (e.g. the `native-macos` build) as a synthetic `tcp://host:port` entry, and `connect()` routes through `meshtastic.tcp_interface.TCPInterface` instead of `SerialInterface`. Every read/write/admin tool that flows through `connect()` works against the daemon transparently. USB-only tools (`pio_flash`, `erase_and_flash`, `update_flash`, `touch_1200bps`, `serial_open`, `esptool_*`, `nrfutil_*`, `picotool_*`) raise a clear `ConnectionError` when handed a `tcp://` port; `pio_flash` against a `native*` env raises a `FlashError` (no upload step - use `build` and run the binary directly). The pytest harness still assumes USB-attached devices per role; TCP-aware fixtures are deferred. See the meshtastic-mcp repo's README § "TCP / native-host nodes".
+**TCP / native-host nodes.** Setting `MESHTASTIC_MCP_TCP_HOST=<host[:port]>` makes `list_devices` surface a `meshtasticd` daemon (e.g. the `native-macos` build) as a synthetic `tcp://host:port` entry, and `connect()` routes through `meshtastic.tcp_interface.TCPInterface` instead of `SerialInterface`. Every read/write/admin tool that flows through `connect()` works against the daemon transparently. USB-only tools (`pio_flash`, `erase_and_flash`, `update_flash`, `touch_1200bps`, `serial_open`, `esptool_*`, `nrfutil_*`, `picotool_*`) raise a clear `ConnectionError` when handed a `tcp://` port; `pio_flash` against a `native*` env raises a `FlashError` (no upload step — use `build` and run the binary directly). The pytest harness still assumes USB-attached devices per role; TCP-aware fixtures are deferred. See `mcp-server/README.md` § "TCP / native-host nodes".
 
-### Frame injection: testing the off-air receive path
-
-The `toRadio` API can only inject **locally-originated** traffic - the firmware forces `p.from = 0` in `MeshService::handleToRadio`, which bypasses the `from != 0` receive path and everything gated on it (remote admin authorization, the admin session-passkey check, hop handling, promiscuous sniffing). To exercise those paths you either need a second transmitting radio, or **frame injection**: a build-flagged seam that delivers a client-supplied frame into the real RX pipeline as if it arrived off the LoRa chip.
-
-- **Firmware:** build with `-D MESHTASTIC_ENABLE_FRAME_INJECTION=1` (`src/configuration.h`, off by default - it forges over-the-air traffic and must never ship enabled). `MeshService::injectAsReceived` extends the existing portduino `SimRadio` `SIMULATOR_APP` path to real hardware: it unwraps a `Compressed` envelope (`portnum == UNKNOWN_APP` → verbatim ciphertext the router decrypts; else → decoded payload for that portnum), then calls `router->enqueueReceivedMessage()` - the exact entry point `RadioLibInterface::handleReceiveInterrupt` uses. Injection is reached before the `p.from = 0` line, so a forged sender survives; `from == 0` is dropped to match real RX.
-- **Host:** drive it with the meshtastic-mcp `inject_frame` tool (or `cli/meshinject.py`). The crafter replicates channel crypto (default-PSK expansion, `xorHash` channel hash, AES-CTR with the `packetId|from|0` nonce), so an encrypted frame decrypts on-device as if received. Modes: `text`, `raw`, `admin` (+ `pki`/`public_key` for the PKC-admin path), `ciphertext`, `fuzz` (malformed-frame decode-path/crash testing).
-- **Example - remote-admin session-key repro:** set the target's `admin_key[0]` to a key you hold, then inject an `admin` set_owner with `pki=true`, that key, and a stale `session_hex`. The node logs `PKC admin payload with authorized sender key` → `Expected session key: 00…` → `Admin message without session_key!` - the exact ndoo scenario, on real silicon. Capture logs via `set_debug_log_api` on the same connection.
-- **nRF52 gotcha:** the USB CDC wedges under rapid `SerialInterface` open/close churn (unrelated to injection) - keep setup + inject + log-capture on one connection; recover a hung board via a 1200 bps-touch DFU reflash.
-
-### Hardware test suite (`run-tests.sh`, from a meshtastic-mcp checkout)
+### Hardware test suite (`mcp-server/run-tests.sh`)
 
 The wrapper auto-detects connected devices (VID → role map: `0x239A` → `nrf52`, `0x303A`/`0x10C4` → `esp32s3`), maps each role to a PlatformIO env (`nrf52` → `rak4631`, `esp32s3` → `heltec-v3`, overridable via `MESHTASTIC_MCP_ENV_<ROLE>`), then invokes pytest. Zero pre-flight config needed from the operator.
 
 Suite tiers (collected + run in this order via `pytest_collection_modifyitems`):
 
-1. `tests/unit/` - pure Python (boards parse, pio wrapper, userPrefs parse, testing profile, uhubctl parser). No hardware.
-2. `tests/test_00_bake.py` - flashes each detected device with current `userPrefs.jsonc` merged with the session's test profile. Has its own skip-if-already-baked check comparing region + primary channel to the session profile; skips cheaply on warm devices.
-3. `tests/mesh/` - multi-device mesh: bidirectional send, broadcast delivery, direct-with-ACK, mesh formation within 60s. Parametrized `[nrf52->esp32s3]` and `[esp32s3->nrf52]`. Includes `test_peer_offline_recovery` which uses uhubctl to physically power off one peer mid-conversation (requires uhubctl; skips without).
-4. `tests/telemetry/` - `DEVICE_METRICS_APP` broadcast timing.
-5. `tests/monitor/` - boot-log panic check.
-6. `tests/recovery/` - `uhubctl` power-cycle round-trip + NVS persistence across hard reset. Requires `uhubctl` installed and a PPPS-capable hub; entire tier auto-skips otherwise.
-7. `tests/ui/` - input-broker-driven screen navigation with camera + OCR evidence.
-8. `tests/fleet/` - PSK seed session isolation.
-9. `tests/admin/` - channel URL roundtrip, owner persistence across reboot.
-10. `tests/provisioning/` - region + modem + slot bake, admin key presence, `UNSET` region blocks TX, userPrefs survive factory reset.
+1. `tests/unit/` — pure Python (boards parse, pio wrapper, userPrefs parse, testing profile, uhubctl parser). No hardware.
+2. `tests/test_00_bake.py` — flashes each detected device with current `userPrefs.jsonc` merged with the session's test profile. Has its own skip-if-already-baked check comparing region + primary channel to the session profile; skips cheaply on warm devices.
+3. `tests/mesh/` — multi-device mesh: bidirectional send, broadcast delivery, direct-with-ACK, mesh formation within 60s. Parametrized `[nrf52->esp32s3]` and `[esp32s3->nrf52]`. Includes `test_peer_offline_recovery` which uses uhubctl to physically power off one peer mid-conversation (requires uhubctl; skips without).
+4. `tests/telemetry/` — `DEVICE_METRICS_APP` broadcast timing.
+5. `tests/monitor/` — boot-log panic check.
+6. `tests/recovery/` — `uhubctl` power-cycle round-trip + NVS persistence across hard reset. Requires `uhubctl` installed and a PPPS-capable hub; entire tier auto-skips otherwise.
+7. `tests/ui/` — input-broker-driven screen navigation with camera + OCR evidence.
+8. `tests/fleet/` — PSK seed session isolation.
+9. `tests/admin/` — channel URL roundtrip, owner persistence across reboot.
+10. `tests/provisioning/` — region + modem + slot bake, admin key presence, `UNSET` region blocks TX, userPrefs survive factory reset.
 
 Invocation patterns:
 
 ```bash
-# run from a meshtastic-mcp checkout, with MESHTASTIC_FIRMWARE_ROOT=/path/to/firmware
-./run-tests.sh                                        # full suite (auto-bake-if-needed)
-./run-tests.sh --force-bake                           # reflash before testing
-./run-tests.sh --assume-baked                         # skip bake (caller vouches for device state)
-./run-tests.sh tests/mesh                             # one tier
-./run-tests.sh tests/mesh/test_direct_with_ack.py     # one file
-./run-tests.sh -k telemetry                           # name filter
+./mcp-server/run-tests.sh                                        # full suite (auto-bake-if-needed)
+./mcp-server/run-tests.sh --force-bake                           # reflash before testing
+./mcp-server/run-tests.sh --assume-baked                         # skip bake (caller vouches for device state)
+./mcp-server/run-tests.sh tests/mesh                             # one tier
+./mcp-server/run-tests.sh tests/mesh/test_direct_with_ack.py     # one file
+./mcp-server/run-tests.sh -k telemetry                           # name filter
 ```
 
-**No hardware detected?** The wrapper auto-narrows to `tests/unit/` only and prints `detected hub : (none)` in the pre-flight header. Agents interpreting the output should call this out explicitly - a 52-test green run without hardware is qualitatively different from a 12-unit-test green run.
+**No hardware detected?** The wrapper auto-narrows to `tests/unit/` only and prints `detected hub : (none)` in the pre-flight header. Agents interpreting the output should call this out explicitly — a 52-test green run without hardware is qualitatively different from a 12-unit-test green run.
 
 **Artifacts every run produces:**
 
-- `tests/report.html` - self-contained pytest-html. Each test gets a `Meshtastic debug` section with the tail of firmware log + device state dump. **Open this first** on failures; it's the canonical evidence source.
-- `tests/junit.xml` - CI-parseable.
-- `tests/reportlog.jsonl` - pytest-reportlog stream (`$report_type` keyed JSONL). Consumed by the live TUI.
-- `tests/fwlog.jsonl` - firmware log mirror from the `meshtastic.log.line` pubsub topic. Populated by the `_firmware_log_stream` autouse session fixture.
+- `mcp-server/tests/report.html` — self-contained pytest-html. Each test gets a `Meshtastic debug` section with the tail of firmware log + device state dump. **Open this first** on failures; it's the canonical evidence source.
+- `mcp-server/tests/junit.xml` — CI-parseable.
+- `mcp-server/tests/reportlog.jsonl` — pytest-reportlog stream (`$report_type` keyed JSONL). Consumed by the live TUI.
+- `mcp-server/tests/fwlog.jsonl` — firmware log mirror from the `meshtastic.log.line` pubsub topic. Populated by the `_firmware_log_stream` autouse session fixture.
 
 ### Live TUI (`meshtastic-mcp-test-tui`)
 
@@ -900,7 +632,7 @@ A Textual-based live view that wraps `run-tests.sh`. Tails reportlog for per-tes
 Launch:
 
 ```bash
-# from a meshtastic-mcp checkout (MESHTASTIC_FIRMWARE_ROOT set)
+cd mcp-server
 .venv/bin/meshtastic-mcp-test-tui                 # full suite
 .venv/bin/meshtastic-mcp-test-tui tests/mesh      # args pass through to pytest
 ```
@@ -925,29 +657,29 @@ House rules for agents running these prompts:
 
 ### Key fixtures (test authors + agents debugging)
 
-`tests/conftest.py` (in the meshtastic-mcp checkout) provides:
+`mcp-server/tests/conftest.py` provides:
 
-- **`_session_userprefs`** (autouse session) - snapshots `userPrefs.jsonc` at session start, merges the session test profile via `userprefs.merge_active(test_profile)`, restores at teardown. Four layers of safety: pytest teardown + `atexit` + sidecar file (`userPrefs.jsonc.mcp-session-bak`) + startup self-heal in `run-tests.sh`. **Do not edit `userPrefs.jsonc` from inside a test.**
-- **`_firmware_log_stream`** (autouse session) - subscribes to `meshtastic.log.line` pubsub on every connected `SerialInterface` and mirrors lines to `tests/fwlog.jsonl`. Drives the TUI firmware-log pane.
-- **`_debug_log_buffer`** (autouse per-test) - captures last 200 firmware log lines + device state for attachment to the pytest-html `Meshtastic debug` section on failure.
-- **`hub_devices`** (session) - `dict[role, SerialInterface]` with session-long exclusive port locks. Reason the TUI's device poller is gated to startup + post-run only.
-- **`baked_mesh`** - parametrized mesh-pair fixture; depends on `test_00_bake`. `pytest_generate_tests` in `conftest.py` auto-generates `[nrf52->esp32s3]` and `[esp32s3->nrf52]` variants.
-- **`test_profile`** - session-scoped dict: region, primary channel, admin key, PSK seed. Derived from `MESHTASTIC_MCP_SEED` (defaults to `mcp-<user>-<host>`).
+- **`_session_userprefs`** (autouse session) — snapshots `userPrefs.jsonc` at session start, merges the session test profile via `userprefs.merge_active(test_profile)`, restores at teardown. Four layers of safety: pytest teardown + `atexit` + sidecar file (`userPrefs.jsonc.mcp-session-bak`) + startup self-heal in `run-tests.sh`. **Do not edit `userPrefs.jsonc` from inside a test.**
+- **`_firmware_log_stream`** (autouse session) — subscribes to `meshtastic.log.line` pubsub on every connected `SerialInterface` and mirrors lines to `tests/fwlog.jsonl`. Drives the TUI firmware-log pane.
+- **`_debug_log_buffer`** (autouse per-test) — captures last 200 firmware log lines + device state for attachment to the pytest-html `Meshtastic debug` section on failure.
+- **`hub_devices`** (session) — `dict[role, SerialInterface]` with session-long exclusive port locks. Reason the TUI's device poller is gated to startup + post-run only.
+- **`baked_mesh`** — parametrized mesh-pair fixture; depends on `test_00_bake`. `pytest_generate_tests` in `conftest.py` auto-generates `[nrf52->esp32s3]` and `[esp32s3->nrf52]` variants.
+- **`test_profile`** — session-scoped dict: region, primary channel, admin key, PSK seed. Derived from `MESHTASTIC_MCP_SEED` (defaults to `mcp-<user>-<host>`).
 
 ### Firmware integration points tied to the test harness
 
 Two firmware changes exist specifically so the test harness works reliably. **Keep these in mind when touching related code.**
 
-- **`src/mesh/StreamAPI.cpp` + `StreamAPI.h`** - `emitLogRecord` uses a dedicated `fromRadioScratchLog` + `txBufLog` pair and a `concurrency::Lock streamLock`. Before this fix, `debug_log_api_enabled=true` would tear `FromRadio` protobufs on the serial transport because `emitTxBuffer` and `emitLogRecord` shared a single scratch buffer. The conftest enables the log stream session-wide; without this fix the device would corrupt its own FromRadio replies mid-session.
-- **`src/mesh/PhoneAPI.cpp`** - `ToRadio` `Heartbeat(nonce=1)` triggers `nodeInfoModule->sendOurNodeInfo(NODENUM_BROADCAST, true, 0, true)` for serial clients, mirroring the pre-existing behavior for TCP/UDP clients in `PacketAPI.cpp`. The mesh tests rely on this to force a NodeInfo broadcast right after connect so the peer discovers them before the test's first assertion.
+- **`src/mesh/StreamAPI.cpp` + `StreamAPI.h`** — `emitLogRecord` uses a dedicated `fromRadioScratchLog` + `txBufLog` pair and a `concurrency::Lock streamLock`. Before this fix, `debug_log_api_enabled=true` would tear `FromRadio` protobufs on the serial transport because `emitTxBuffer` and `emitLogRecord` shared a single scratch buffer. The conftest enables the log stream session-wide; without this fix the device would corrupt its own FromRadio replies mid-session.
+- **`src/mesh/PhoneAPI.cpp`** — `ToRadio` `Heartbeat(nonce=1)` triggers `nodeInfoModule->sendOurNodeInfo(NODENUM_BROADCAST, true, 0, true)` for serial clients, mirroring the pre-existing behavior for TCP/UDP clients in `PacketAPI.cpp`. The mesh tests rely on this to force a NodeInfo broadcast right after connect so the peer discovers them before the test's first assertion.
 
-If you're modifying `StreamAPI`, `PhoneAPI`, `NodeInfoModule`, or `userPrefs` flow, run `./run-tests.sh` (from a meshtastic-mcp checkout, with `MESHTASTIC_FIRMWARE_ROOT` pointed here) at minimum before asking for review.
+If you're modifying `StreamAPI`, `PhoneAPI`, `NodeInfoModule`, or `userPrefs` flow, run `./mcp-server/run-tests.sh` at minimum before asking for review.
 
 ### Recovery playbooks
 
 | Symptom                                                                           | First check                                                   | Fix                                                                                                                                                                                                                              |
 | --------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `userPrefs.jsonc` dirty after test run                                            | `git status --porcelain userPrefs.jsonc`                      | If non-empty, re-run `./run-tests.sh` (from a meshtastic-mcp checkout) once - the pre-flight self-heal restores from sidecar. If still dirty, `git checkout userPrefs.jsonc`.                                                    |
+| `userPrefs.jsonc` dirty after test run                                            | `git status --porcelain userPrefs.jsonc`                      | If non-empty, re-run `./mcp-server/run-tests.sh` once — the pre-flight self-heal restores from sidecar. If still dirty, `git checkout userPrefs.jsonc`.                                                                          |
 | Port busy / wedged CP2102 on macOS                                                | `lsof /dev/cu.usbserial-0001`                                 | Kill the holder. USB replug if the kernel still reports busy. Often a stale `pio device monitor` or zombie `meshtastic_mcp` process.                                                                                             |
 | nRF52 appears unresponsive                                                        | `list_devices` shows VID `0x239A` but `device_info` times out | `touch_1200bps(port=...)` drops it into the DFU bootloader → `pio_flash` re-installs.                                                                                                                                            |
 | Device fully wedged (Guru Meditation, frozen CDC, no DFU)                         | `list_devices` shows the VID but every admin call times out   | `uhubctl_cycle(role="nrf52", confirm=True)` hard-power-cycles the port via USB hub PPPS. `baked_single`'s auto-recovery hook does this once automatically if uhubctl is installed. Falls back to physical replug if no PPPS hub. |
@@ -957,17 +689,17 @@ If you're modifying `StreamAPI`, `PhoneAPI`, `NodeInfoModule`, or `userPrefs` fl
 | Entire `tests/recovery/` tier skipped                                             | `command -v uhubctl`                                          | Expected if `uhubctl` isn't on PATH. Install via `brew install uhubctl` (macOS) or `apt install uhubctl` (Debian/Ubuntu). Also skips if no hub advertises PPPS.                                                                  |
 | Entire `tests/ui/` tier skipped ("firmware not baked with USERPREFS_UI_TEST_LOG") | reportlog.jsonl for the skip reason                           | Re-run with `--force-bake` so the UI-log macro gets compiled into the fresh firmware. First run after the Round-3 landing always re-bakes.                                                                                       |
 | `tests/ui/` runs but captures are all 1×1 black PNGs                              | `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3`                         | Env var not set → `NullBackend`. Point a USB webcam at the heltec-v3 OLED and set the device index; `.venv/bin/python -c "import cv2; [print(i, cv2.VideoCapture(i).read()[0]) for i in range(5)]"` discovers it.                |
-| Tests fail only on first attempt then pass on rerun                               | -                                                             | State leak from a prior session. Run with `--force-bake` to reset to a known state.                                                                                                                                              |
+| Tests fail only on first attempt then pass on rerun                               | —                                                             | State leak from a prior session. Run with `--force-bake` to reset to a known state.                                                                                                                                              |
 
 ### Never do these without asking
 
-- `factory_reset` - wipes node identity; regenerates PKI keypair. Mesh peers will reject old DMs until re-exchange. Legitimate only when the operator explicitly wants it.
-- `erase_and_flash` - full chip erase; destroys all on-device state.
-- `esptool_erase_flash` / `esptool_raw` write/erase - bypasses pio's safety chain.
-- `set_config` on `lora.region` - changes regulatory domain; requires physical-location context the operator has and the agent doesn't.
-- `reboot` / `shutdown` mid-test - breaks fixture invariants.
+- `factory_reset` — wipes node identity; regenerates PKI keypair. Mesh peers will reject old DMs until re-exchange. Legitimate only when the operator explicitly wants it.
+- `erase_and_flash` — full chip erase; destroys all on-device state.
+- `esptool_erase_flash` / `esptool_raw` write/erase — bypasses pio's safety chain.
+- `set_config` on `lora.region` — changes regulatory domain; requires physical-location context the operator has and the agent doesn't.
+- `reboot` / `shutdown` mid-test — breaks fixture invariants.
 - `push -f`, `rebase -i`, `reset --hard`, or any history-rewriting git operation.
-- Clicking computer-use tools on web links in Mail/Messages/PDFs - open URLs via the claude-in-chrome MCP so the extension's link-safety checks apply.
+- Clicking computer-use tools on web links in Mail/Messages/PDFs — open URLs via the claude-in-chrome MCP so the extension's link-safety checks apply.
 
 ## Resources
 

.github/millis-deadline-allowlist.txt

@@ -1,22 +0,0 @@
-# Allowlist for the millis-deadline-check guard in .github/workflows/test_native.yml.
-#
-# That guard rejects comparisons made directly against millis(), because they invert while the
-# deadline sits on the far side of the 32-bit wrap. Use Throttle::deadlinePassed(deadline) or
-# Throttle::hasElapsed(lastEvent, intervalMs) instead - see .github/copilot-instructions.md.
-#
-# Only add a line here when the comparison genuinely is not a deadline test. The usual valid case is
-# an *uptime threshold*: "has the device been up for at least N ms", where there is no stored
-# deadline and no event to measure from. Those still misbehave briefly after a wrap - the threshold
-# is simply re-crossed - which is harmless for boot-holdoff logic and not worth new state.
-#
-# Format: <path><TAB><exact trimmed source line, comments stripped>
-# Line numbers are deliberately absent so edits above an entry do not invalidate it. A `#` comment
-# on the code line is stripped before matching, so do not include one here.
-
-# Boot holdoff, not a deadline: suppresses a phantom shutdown from floating pins during the first
-# 30s of uptime. Pairs with the buttonPressStartTime > 30000 test on the same line.
-src/input/ButtonThread.cpp	if (millis() > 30000 && buttonPressStartTime > 30000 && _longLongPress != INPUT_BROKER_NONE &&
-
-# Boot-window check, not a deadline: draws the custom OEM logo only during the first 10s of uptime,
-# so the ordinary Meshtastic logo is used at shutdown.
-src/graphics/niche/InkHUD/Applets/System/Logo/LogoApplet.cpp	if (millis() < 10 * 1000UL) {

.github/node-id-format-allowlist.txt

@@ -1,15 +0,0 @@
-# Exception list for bin/lint-node-id-format.sh (trunk linter: node-id-format).
-#
-# Format:  <path>[:<line>]   <reason>
-#   - "<path>"          exempts the whole file
-#   - "<path>:<line>"   exempts one call site
-#   - blank lines and # comments are ignored; the reason column is mandatory
-#
-# Intentionally empty. The known pre-existing sites - PacketHistory.cpp, NodeInfoModule.cpp
-# and PositionModule.cpp - are deliberately NOT listed, so trunk surfaces them the next time
-# someone edits those files and they get cleaned up in the change that was already touching
-# them. The rule emits "note", trunk's only non-blocking level, so this costs a notice rather
-# than a red PR.
-#
-# Add an entry only for a value the linter has misread as an ID - a CRC, a register, a hash -
-# and say which, so the next reader can tell a real exemption from a deferred cleanup.

.github/prompts/hardware-support.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: hardware-support
+---

.github/prompts/mcp-diagnose.prompt.md

@@ -0,0 +1,64 @@
+---
+mode: agent
+description: Device health report via the meshtastic MCP tools (Copilot equivalent of the Claude Code /diagnose slash command)
+---
+
+# `/mcp-diagnose` — device health report
+
+Equivalent of `.claude/commands/diagnose.md`. Use when the operator asks to "check the devices", "what's the mesh looking like", "is nrf52 alive", etc.
+
+This prompt assumes the meshtastic MCP server is registered with your VS Code Copilot agent. If it isn't, fall back to running `./mcp-server/run-tests.sh tests/unit` plus a short `device_info` script via the terminal.
+
+## What to do
+
+1. **Enumerate hardware** via the `list_devices` MCP tool (with `include_unknown=True`). For each entry where `likely_meshtastic=True`, capture `port`, `vid`, `pid`, `description`.
+
+2. **Apply the operator's filter** (if any):
+   - No filter → every likely-meshtastic device.
+   - `nrf52` → `vid == 0x239a`
+   - `esp32s3` → `vid == 0x303a` or `vid == 0x10c4`
+   - A `/dev/cu.*` path → only that port.
+   - Anything else → substring match on port.
+
+3. **For each selected device, in sequence (don't parallelize — SerialInterface holds an exclusive port lock):**
+   - `device_info(port=<p>)` → `my_node_num`, `long_name`, `short_name`, `firmware_version`, `hw_model`, `region`, `num_nodes`, `primary_channel`
+   - `list_nodes(port=<p>)` → peer count, which peers have `publicKey`, SNR/RSSI distribution
+   - `get_config(section="lora", port=<p>)` → region, preset, channel_num, tx_power, hop_limit
+   - If anything looks off (can't connect, `num_nodes` wrong, missing `firmware_version`), open a short firmware-log window: `serial_open(port=<p>, env=<inferred>)`, wait 3 seconds, `serial_read(session_id, max_lines=100)`, `serial_close(session_id)`. Infer env from VID (0x239a → `rak4631`, 0x303a/0x10c4 → `heltec-v3`) unless an `MESHTASTIC_MCP_ENV_<ROLE>` env var overrides it.
+
+4. **Hub health** (call once, not per-device): `uhubctl_list()` — enumerates every USB hub the host sees. Cross-reference each Meshtastic device's VID to find which hub + port it's on. Flag in the report if:
+   - No hub advertises `ppps=true` → `tests/recovery/` can't run; hard-recovery via `uhubctl_cycle` isn't available.
+   - A Meshtastic device is on a non-PPPS hub → note it; moving to a PPPS hub unlocks auto-recovery.
+   - `uhubctl_list` raises `ConfigError: uhubctl not found` → report as "uhubctl not installed"; don't treat as a device fault.
+
+5. **Render per-device report** as a compact block:
+
+   ```text
+   [nrf52 @ /dev/cu.usbmodem1101]      fw=2.7.23.bce2825, hw=RAK4631
+     owner       : Meshtastic 40eb / 40eb
+     region/band : US, channel 88, LONG_FAST
+     tx_power    : 30 dBm, hop_limit=3
+     peers       : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm)
+     primary ch  : McpTest
+     hub         : 1-1.3 port 2 (PPPS, uhubctl-controllable)
+     firmware    : no panics in last 3s
+   ```
+
+   Flag abnormalities inline with `⚠︎ <short reason>` — missing pubkey on a known peer, region UNSET, mismatched channel name, device on non-PPPS hub, etc.
+
+6. **Cross-device correlation** (when >1 device selected):
+   - Do both see each other in `nodesByNum`?
+   - Do `region`, `channel_num`, `modem_preset` match across devices?
+   - Do the primary channel names match? (Different name → different PSK → no decode.)
+
+7. **Suggest next steps only for recognizable failure modes**, never speculatively:
+   - Stale PKI one-way → "`/mcp-test tests/mesh/test_direct_with_ack.py` — the test's retry+nodeinfo-ping heals this."
+   - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`."
+   - Device unreachable, DFU reachable → `touch_1200bps(port=...)` + `pio_flash`. If not even DFU responds and the device is on a PPPS hub, escalate to `uhubctl_cycle(role=..., confirm=True)`.
+   - CP2102-wedged-driver on macOS → see `run-tests.sh` notes.
+
+## Hard constraints
+
+- **Read-only.** No `set_config`, no `reboot`, no `factory_reset`, no `flash`. If the operator wants mutation, they'll escalate explicitly.
+- **Open/query/close per device.** Never hold multiple SerialInterfaces to the same port. The port lock is exclusive.
+- **Don't infer env beyond the VID map** — if the operator has an unusual board, ask them which env to use rather than guessing.

.github/prompts/mcp-repro.prompt.md

@@ -0,0 +1,68 @@
+---
+mode: agent
+description: Re-run a specific test N times to triage flakes; diff firmware logs between passes and failures (Copilot equivalent of the Claude Code /repro slash command)
+---
+
+# `/mcp-repro` — flakiness triage for one test
+
+Equivalent of `.claude/commands/repro.md`. Use when the operator says "that one test is flaky — dig in", "repro the direct_with_ack failure", "why does X sometimes fail?".
+
+## What to do
+
+1. **Parse the operator's input** into two pieces:
+   - **Test identifier** — either a pytest node id (has `::` or starts with `tests/`) or a `-k`-style filter (plain substring like `direct_with_ack`).
+   - **Count** — integer, default `5`, cap at `20`. If the operator asks for 50, negotiate down and explain (airtime + USB wear).
+
+2. **Sanity-check the hub** via the `list_devices` MCP tool. If the test name references `nrf52` or `esp32s3` and the matching VID isn't present, stop and report — re-running won't help.
+
+3. **Loop** N times. Each iteration:
+
+   ```bash
+   ./mcp-server/run-tests.sh <test-id> --tb=short -p no:cacheprovider
+   ```
+
+   `-p no:cacheprovider` keeps pytest from caching anything between iterations. Capture: exit code, duration, and (on failure) the `Meshtastic debug` firmware-log section from `mcp-server/tests/report.html`.
+
+4. **Tally** results as you go:
+
+   ```text
+   attempt 1: PASS (42s)
+   attempt 2: FAIL (128s)    ← fw log captured
+   attempt 3: PASS (39s)
+   attempt 4: FAIL (121s)
+   attempt 5: PASS (41s)
+   --------------------------------------------------
+   pass rate: 3/5 (60%)  |  mean duration: 74s
+   ```
+
+5. **On mixed outcomes, diff the firmware logs** between one representative pass and one representative fail. Focus on:
+   - Error-level lines present only in failures (`PKI_UNKNOWN_PUBKEY`, `Alloc an err=`, `Skip send`, `No suitable channel`, `NAK`)
+   - Timing around the assertion point (broadcast sent? ACK received? retry fired?)
+   - Device-state fields that changed between attempts
+
+   Surface the top 3 differences as a compact "passes when / fails when" table with uptime timestamps. Don't dump full logs.
+
+6. **Classify** the flake into one of:
+   - **LoRa airtime collision** — pass rate improves with fewer concurrent transmitters. Suggest a `time.sleep` gap or retry bump in the test body.
+   - **PKI key staleness** — first attempt fails, subsequent ones pass; existing retry-loop pattern in `test_direct_with_ack.py` is the fix.
+   - **NodeInfo cooldown** — `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs a `broadcast_nodeinfo_ping()` warmup.
+   - **Hardware-specific** — one direction consistently fails, firmware versions differ, CP2102 driver wedged, etc. For a device wedged past `touch_1200bps`, recommend `uhubctl_cycle(role=..., confirm=True)` to hard-power-cycle its hub port (requires `uhubctl` installed).
+   - **Device went dark mid-run** — fails from some iteration onward and never recovers; firmware log stops arriving. Almost always a Guru crash with frozen CDC. Recommend `uhubctl_cycle` before the next iteration; escalate to replug if that also fails.
+   - **Unknown** — say so. Don't invent a root cause.
+
+7. **Report back** with:
+   - Pass rate + mean duration.
+   - Classification + the specific log evidence for it.
+   - A concrete next step (tighter assertion, more retries, open `/mcp-diagnose`, file a bug, nothing).
+
+## Examples
+
+- `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[esp32s3->nrf52] 10` — 10 runs of that parametrized case.
+- `broadcast_delivers` — no `::`, no `tests/`; treat as `-k broadcast_delivers`; runs every match 5 times.
+- `tests/telemetry/test_device_telemetry_broadcast.py 3` — shorter count for a slow test.
+
+## Notes
+
+- If the FIRST attempt fails and the rest pass, that's a state-leak signature — suggest starting from `--force-bake` or a clean device state rather than chasing the first-failure firmware logs.
+- If ALL N fail, this isn't a flake — it's a regression. Say so, stop iterating, escalate to `/mcp-test` for full-suite context.
+- Don't rebuild firmware during triage. Flakes that only reproduce under different firmware belong in a separate session with a plan.

.github/prompts/mcp-test.prompt.md

@@ -0,0 +1,57 @@
+---
+mode: agent
+description: Run the mcp-server test suite and interpret results (Copilot equivalent of the Claude Code /test slash command)
+---
+
+# `/mcp-test` — mcp-server test runner with interpretation
+
+Equivalent of the Claude Code `/test` slash command in `.claude/commands/test.md`. Use this when the operator asks you to "run the tests", "check the mcp test suite", "run the mesh tests", etc.
+
+## What to do
+
+1. **Invoke the wrapper** from the firmware repo root:
+
+   ```bash
+   ./mcp-server/run-tests.sh [pytest-args]
+   ```
+
+   If the operator specified a subset (e.g. "just the mesh tests"), pass it through as `tests/mesh` or a pytest `-k filter`. If they said nothing, use the wrapper's defaults (full suite with pytest-html report).
+
+   The wrapper auto-detects connected Meshtastic devices, maps each to its PlatformIO env, exports the required env vars, and invokes pytest. Zero pre-flight config needed from the operator.
+
+2. **Read the pre-flight header** (first few lines of wrapper output). The `detected hub :` line lists role → port → env mappings. If it reads `(none)`, the wrapper narrowed to `tests/unit` only — call that out explicitly so the operator knows hardware tiers were skipped.
+
+3. **On pass**: one-line summary like `N passed, M skipped in <duration>`. Don't enumerate test names. DO mention any non-placeholder SKIPs and name the cause:
+   - `"role not present on hub"` → device unplugged; operator should reconnect.
+   - `"firmware not baked with USERPREFS_UI_TEST_LOG"` → tests/ui skipped; the UI-log compile macro isn't in the baked firmware. Suggest `--force-bake`.
+   - `"uhubctl not installed"` → tests/recovery + `test_peer_offline_recovery` skipped. Suggest `brew install uhubctl` / `apt install uhubctl`.
+   - `"no PPPS-capable hubs detected"` → tests/recovery skipped because the attached hub doesn't support per-port power switching; won't run on that setup.
+   - `"opencv-python-headless is not installed"` → tests/ui auto-deselected by `run-tests.sh`. Suggest `pip install -e 'mcp-server/.[ui]'`.
+
+4. **On failure**: open `mcp-server/tests/report.html` (pytest-html output, self-contained) and extract the `Meshtastic debug` section for each failed test. That section includes a firmware log stream (last 200 lines) and device state dump. For each failure, summarise:
+   - test name
+   - one-line assertion message
+   - the specific firmware log lines that explain why (look for `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`, `No suitable channel`)
+   - for UI-tier failures also check `mcp-server/tests/ui_captures/<session>/<test>/transcript.md` (per-step frame + OCR)
+
+5. **Classify each failure** as one of:
+   - **Transient flake** — LoRa collision, first-attempt NAK with self-heal pattern, timing-sensitive assertion. Suggest `/mcp-repro <test-id>` to confirm.
+   - **Environmental** — device unreachable, port busy, CP2102 driver wedged on macOS. Suggest recovery in escalation order: (a) replug USB, (b) `touch_1200bps` + `pio_flash` for nRF52 DFU, (c) `uhubctl_cycle(role=..., confirm=True)` for a device wedged past DFU (needs `uhubctl` installed; `baked_single` does this once automatically when available). Also check `git status userPrefs.jsonc`.
+   - **Regression** — same assertion fails repeatedly on re-runs, firmware log shows novel errors. Identify the firmware module likely responsible.
+
+6. **Do NOT run destructive recovery automatically**. If a failure looks like it needs a reflash, factory*reset, `uhubctl_cycle`, or replug — \_describe the steps* and let the operator decide. Never burn airtime or flash cycles without approval.
+
+## Arguments convention
+
+Operators generally invoke this prompt either with no arguments (full suite) or with a specific subset. Examples:
+
+- `tests/mesh` — one tier
+- `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip` — one test
+- `--force-bake` — reflash devices first
+- `-k telemetry` — name-filter
+
+## Side-effects to confirm in your summary
+
+- `userPrefs.jsonc` should be clean after a successful run. The session fixture in `mcp-server/tests/conftest.py` (`_session_userprefs`) snapshots and restores. Check `git status --porcelain userPrefs.jsonc` and report if it's non-empty.
+- `mcp-server/tests/report.html` and `junit.xml` regenerate on every run.
+- The wrapper prints a warning if a `.mcp-session-bak` sidecar was left over from a crashed prior session and auto-restores from it — mention that if it happened.

.github/prompts/new-module.prompt.md

@@ -6,9 +6,9 @@ Guide for developing a new Meshtastic firmware module.
 
 Choose the appropriate base class:
 
-1. **`MeshModule`** - Raw base class. Override `wantPacket()` and `handleReceived()`. Returns `ProcessMessage::STOP` or `ProcessMessage::CONTINUE`.
-2. **`SinglePortModule`** - Handles a single `meshtastic_PortNum`. Constructor takes `(name, portNum)`. Simplified `wantPacket()` checking `decoded.portnum`. Use `allocDataPacket()` to create outgoing packets.
-3. **`ProtobufModule<T>`** - Template for protobuf-encoded modules. Constructor takes `(name, portNum, fields)`. Override `handleReceivedProtobuf()`. Use `allocDataProtobuf(payload)` to create outgoing packets.
+1. **`MeshModule`** — Raw base class. Override `wantPacket()` and `handleReceived()`. Returns `ProcessMessage::STOP` or `ProcessMessage::CONTINUE`.
+2. **`SinglePortModule`** — Handles a single `meshtastic_PortNum`. Constructor takes `(name, portNum)`. Simplified `wantPacket()` checking `decoded.portnum`. Use `allocDataPacket()` to create outgoing packets.
+3. **`ProtobufModule<T>`** — Template for protobuf-encoded modules. Constructor takes `(name, portNum, fields)`. Override `handleReceivedProtobuf()`. Use `allocDataProtobuf(payload)` to create outgoing packets.
 
 Most modules also mix in `concurrency::OSThread` for periodic background tasks.
 
@@ -32,7 +32,7 @@ class MyModule : public ProtobufModule<meshtastic_MyMessage>, private concurrenc
     // Generate response packet (optional)
     virtual meshtastic_MeshPacket *allocReply() override;
 
-    // Periodic task - return next run interval in ms, or disable()
+    // Periodic task — return next run interval in ms, or disable()
     virtual int32_t runOnce() override;
 
     // Modify packet in-flight before delivery (optional)

.github/prompts/new-sensor.prompt.md

@@ -6,10 +6,10 @@ Guide for adding a new I2C telemetry sensor driver to Meshtastic firmware.
 
 Telemetry sensors live in `src/modules/Telemetry/Sensor/`. There are 50+ existing drivers organized by measurement type. Each sensor integrates with one of the telemetry modules:
 
-- **EnvironmentTelemetryModule** - Temperature, humidity, pressure, gas, light
-- **AirQualityTelemetryModule** - Particulate matter, VOCs
-- **PowerTelemetryModule** - Voltage, current, power monitoring
-- **HealthTelemetryModule** - Heart rate, SpO2, body temperature
+- **EnvironmentTelemetryModule** — Temperature, humidity, pressure, gas, light
+- **AirQualityTelemetryModule** — Particulate matter, VOCs
+- **PowerTelemetryModule** — Voltage, current, power monitoring
+- **HealthTelemetryModule** — Heart rate, SpO2, body temperature
 
 ## Sensor Driver Pattern
 
@@ -75,10 +75,10 @@ The scan runs at boot and populates a device map that telemetry modules use to d
 If the sensor provides data not covered by existing telemetry fields:
 
 1. Add fields to the appropriate message in `protobufs/meshtastic/telemetry.proto`:
-   - `EnvironmentMetrics` - Environmental measurements
-   - `AirQualityMetrics` - Air quality data
-   - `PowerMetrics` - Power/energy data
-   - `HealthMetrics` - Health/biometric data
+   - `EnvironmentMetrics` — Environmental measurements
+   - `AirQualityMetrics` — Air quality data
+   - `PowerMetrics` — Power/energy data
+   - `HealthMetrics` — Health/biometric data
 2. Add a `.options` constraint if needed (field sizes for nanopb)
 3. Regenerate: `bin/regen-protos.sh`
 

.github/prompts/new-variant.prompt.md

@@ -20,14 +20,14 @@ variants/
 
 Each variant needs at minimum:
 
-- `variant.h` - Pin definitions and hardware capabilities
-- `platformio.ini` - Build configuration
+- `variant.h` — Pin definitions and hardware capabilities
+- `platformio.ini` — Build configuration
 
 Optional files:
 
-- `pins_arduino.h` - Arduino pin mapping overrides
-- `rfswitch.h` - RF switch control for multi-band radios
-- `nicheGraphics.h` - InkHUD e-ink configuration
+- `pins_arduino.h` — Arduino pin mapping overrides
+- `rfswitch.h` — RF switch control for multi-band radios
+- `nicheGraphics.h` — InkHUD e-ink configuration
 
 ## variant.h Template
 
@@ -101,25 +101,25 @@ upload_speed = 921600
 
 ### Common Base Configs
 
-- `esp32_base` / `esp32-common.ini` - ESP32
-- `esp32s3_base` - ESP32-S3
-- `esp32c3_base` - ESP32-C3
-- `esp32c6_base` - ESP32-C6
-- `nrf52840_base` / `nrf52.ini` - nRF52840
-- `rp2040_base` - RP2040/RP2350
+- `esp32_base` / `esp32-common.ini` — ESP32
+- `esp32s3_base` — ESP32-S3
+- `esp32c3_base` — ESP32-C3
+- `esp32c6_base` — ESP32-C6
+- `nrf52840_base` / `nrf52.ini` — nRF52840
+- `rp2040_base` — RP2040/RP2350
 
 ### Support Levels
 
-- `custom_meshtastic_support_level = 1` - Built on every PR (actively supported)
-- `custom_meshtastic_support_level = 2` - Built only on merge to main branches
-- `board_level = extra` - Only built on full releases
+- `custom_meshtastic_support_level = 1` — Built on every PR (actively supported)
+- `custom_meshtastic_support_level = 2` — Built only on merge to main branches
+- `board_level = extra` — Only built on full releases
 
 ## Build Manifest Metadata
 
 `bin/platformio-custom.py` emits UI capability flags in the build manifest:
 
-- `custom_meshtastic_has_mui = true/false` - Override MUI detection
-- `custom_meshtastic_has_ink_hud = true/false` - Override InkHUD detection
+- `custom_meshtastic_has_mui = true/false` — Override MUI detection
+- `custom_meshtastic_has_ink_hud = true/false` — Override InkHUD detection
 - Architecture names are normalized (e.g., `esp32s3` → `esp32-s3`)
 
 ## InkHUD E-Ink Variants
@@ -127,7 +127,7 @@ upload_speed = 921600
 For e-ink display variants using the InkHUD framework, add `nicheGraphics.h`:
 
 ```cpp
-// nicheGraphics.h - InkHUD configuration for this variant
+// nicheGraphics.h — InkHUD configuration for this variant
 #define INKHUD                     // Enable InkHUD
 // Configure display, applets, and refresh behavior per device
 ```

.github/prompts/speckit.analyze.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.analyze
+---

.github/prompts/speckit.checklist.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.checklist
+---

.github/prompts/speckit.clarify.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.clarify
+---

.github/prompts/speckit.constitution.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.constitution
+---

.github/prompts/speckit.implement.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.implement
+---

.github/prompts/speckit.plan.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.plan
+---

.github/prompts/speckit.specify.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.specify
+---

.github/prompts/speckit.tasks.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.tasks
+---

.github/prompts/speckit.taskstoissues.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.taskstoissues
+---

.github/workflows/build_debian_src.yml

@@ -21,13 +21,9 @@ permissions:
 jobs:
   build-debian-src:
     runs-on: ubuntu-24.04
-    # Only pushes to the default branch (develop) populate the cache; PR / merge_group runs
-    # restore it but never save, so they stop filling up the repo's Actions cache storage.
-    env:
-      SAVE_CACHE: ${{ github.event_name == 'push' && github.ref_name == github.event.repository.default_branch }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
           path: meshtasticd
@@ -62,14 +58,6 @@ jobs:
           BUILD_LOCATION: ${{ inputs.build_location }}
         id: version
 
-      - name: Restore PlatformIO cache
-        id: pio-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: meshtasticd/pio/core/.cache
-          key: |
-            pio-deb-src-${{ hashFiles('meshtasticd/platformio.ini', 'meshtasticd/variants/native/portduino.ini', 'meshtasticd/variants/native/portduino/platformio.ini') }}
-
       - name: Fetch libdeps, package debian source
         working-directory: meshtasticd
         run: debian/ci_pack_sdeb.sh
@@ -78,18 +66,6 @@ jobs:
           GPG_KEY_ID: ${{ steps.gpg.outputs.keyid || '' }}
           PKG_VERSION: ${{ steps.version.outputs.deb }}
 
-      - name: Extract cache from pio.tar
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        run: tar -C meshtasticd -xf meshtasticd/pio.tar pio/core/.cache
-
-      - name: Save PlatformIO cache
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: meshtasticd/pio/core/.cache
-          key: |
-            pio-deb-src-${{ hashFiles('meshtasticd/platformio.ini', 'meshtasticd/variants/native/portduino.ini', 'meshtasticd/variants/native/portduino/platformio.ini') }}
-
       - name: Store binaries as an artifact
         uses: actions/upload-artifact@v7
         with:

.github/workflows/build_firmware.yml

@@ -23,7 +23,7 @@ jobs:
     outputs:
       artifact-id: ${{ steps.upload-firmware.outputs.artifact-id }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
         with:
           submodules: recursive
 

.github/workflows/build_macos_bin.yml

@@ -14,71 +14,30 @@ permissions:
 jobs:
   build-MacOS:
     runs-on: macos-${{ inputs.macos_ver }}
-    # Only pushes to the default branch (develop) populate the cache; PR / merge_group runs
-    # restore it but never save, so they stop filling up the repo's Actions cache storage.
-    env:
-      SAVE_CACHE: ${{ github.event_name == 'push' && github.ref_name == github.event.repository.default_branch }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 
-      - name: Capture runner image version (for caching)
-        id: r_image
-        run: echo "ver=$ImageVersion" >> "$GITHUB_OUTPUT"
-
-      - name: Restore Homebrew cache
-        id: brew-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: ~/Library/Caches/Homebrew
-          key: brew-macos-${{ inputs.macos_ver }}-${{ steps.r_image.outputs.ver }}
-
-      - name: Install deps (Homebrew)
+      - name: Install deps
         shell: bash
-        env:
-          # GitHub-Hosted MacOS runner images are updated frequently
-          # so skip running `brew update` to avoid unnecessary failures and delays.
-          HOMEBREW_NO_AUTO_UPDATE: "1"
-          HOMEBREW_NO_INSTALL_CLEANUP: "1"
-        run: >
-          brew install
-          platformio yaml-cpp libuv openssl@3 libusb argp-standalone pkg-config ulfius jsoncpp
-
-      - name: Save Homebrew cache
-        if: env.SAVE_CACHE == 'true' && steps.brew-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: ~/Library/Caches/Homebrew
-          key: brew-macos-${{ inputs.macos_ver }}-${{ steps.r_image.outputs.ver }}
+        run: |
+          brew update
+          brew install platformio yaml-cpp libuv openssl@3 libusb argp-standalone pkg-config ulfius
 
       - name: Get release version string
         run: |
           echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
         id: version
 
-      - name: Restore PlatformIO cache
-        id: pio-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-macos-${{ inputs.macos_ver }}-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-          restore-keys: |
-            pio-macos-${{ inputs.macos_ver }}-
-
       - name: Build for MacOS
         run: |
           platformio run -e native-macos
         env:
           PKG_VERSION: ${{ steps.version.outputs.long }}
-
-      - name: Save PlatformIO cache
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-macos-${{ inputs.macos_ver }}-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
+        # Errors in this step should not fail the entire workflow while MacOS support is in development.
+        continue-on-error: true
 
       - name: List output files
         run: ls -lah .pio/build/native-macos/

.github/workflows/build_one_target.yml

@@ -4,14 +4,9 @@ on:
   workflow_dispatch:
     inputs:
       # trunk-ignore(checkov/CKV_GHA_7)
-      target:
-        type: string
-        required: false
-        description: Choose the target board, e.g. nrf52_promicro_diy_tcxo. If blank, will find available targets.
       arch:
         type: choice
         options:
-          - all
           - esp32
           - esp32s3
           - esp32c3
@@ -20,21 +15,35 @@ on:
           - rp2040
           - rp2350
           - stm32
-        description: Choose an arch to limit the search, or 'all' to search all architectures.
-        default: all
+      target:
+        type: string
+        required: false
+        description: Choose the target board, e.g. nrf52_promicro_diy_tcxo. If blank, will find available targets.
+      # find-target:
+      #   type: boolean
+      #   default: true
+      #   description: 'Find the available targets'
 
 permissions: read-all
 
 jobs:
   find-targets:
+    if: ${{ inputs.target == '' }}
     strategy:
       fail-fast: false
       matrix:
         arch:
-          - all
+          - esp32
+          - esp32s3
+          - esp32c3
+          - esp32c6
+          - nrf52840
+          - rp2040
+          - rp2350
+          - stm32
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
           python-version: 3.x
@@ -42,43 +51,20 @@ jobs:
       - run: pip install -U platformio
       - name: Generate matrix
         id: jsonStep
-        env:
-          BUILDTARGET: ${{ inputs.target }}
-          MATRIXARCH: ${{ inputs.arch }}
         run: |
           TARGETS=$(./bin/generate_ci_matrix.py ${{matrix.arch}} --level extra)
-          if [ "$BUILDTARGET" = "" ]; then
-            echo "Name: $GITHUB_REF_NAME" >> $GITHUB_STEP_SUMMARY
-            echo "Base: $GITHUB_BASE_REF" >> $GITHUB_STEP_SUMMARY
-            echo "Arch: $MATRIXARCH" >> $GITHUB_STEP_SUMMARY
-            echo "Ref: $GITHUB_REF" >> $GITHUB_STEP_SUMMARY
-            echo "## 🎯 The following target boards are available to build:" >> $GITHUB_STEP_SUMMARY
-            echo "| Platform | Board |" >> $GITHUB_STEP_SUMMARY
-            echo "| -------- | ----- |" >> $GITHUB_STEP_SUMMARY
-            echo $TARGETS | jq -r 'sort_by(.board) | sort_by(.platform) |.[] | "| " + .platform + " | " + .board + " |" ' >> $GITHUB_STEP_SUMMARY
-          else
-            echo "We build this one:" >> $GITHUB_STEP_SUMMARY
-            ARCH=$(echo "$TARGETS" | jq --arg BUILDTARGET "$BUILDTARGET" -r '.[] | select(.board==$BUILDTARGET) | .platform')
-            echo "| Platform | Board |" >> $GITHUB_STEP_SUMMARY
-            echo "| -------- | ----- |" >> $GITHUB_STEP_SUMMARY
-            echo "| $ARCH | "$BUILDTARGET" |" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
-            if [[ "$ARCH" == "" ]]; then
-              echo "## ❌ Error: Target "$BUILDTARGET" not found!" >> $GITHUB_STEP_SUMMARY
-            else
-              echo "## ✅ Target "$BUILDTARGET" found, proceeding to build." >> $GITHUB_STEP_SUMMARY
-            fi
-            echo "You may need to refresh this page to make the built firmware appear below." >> $GITHUB_STEP_SUMMARY
-            echo "arch=$ARCH" >> $GITHUB_OUTPUT
-          fi
-    outputs:
-      arch: ${{ steps.jsonStep.outputs.arch }}
+          echo "Name: $GITHUB_REF_NAME" >> $GITHUB_STEP_SUMMARY
+          echo "Base: $GITHUB_BASE_REF" >> $GITHUB_STEP_SUMMARY
+          echo "Arch: ${{matrix.arch}}" >> $GITHUB_STEP_SUMMARY
+          echo "Ref: $GITHUB_REF" >> $GITHUB_STEP_SUMMARY
+          echo "Targets:" >> $GITHUB_STEP_SUMMARY
+          echo $TARGETS | jq -r 'sort_by(.board) |.[] | "- " + .board' >> $GITHUB_STEP_SUMMARY
 
   version:
     if: ${{ inputs.target != '' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
       - name: Get release version string
         run: |
           echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
@@ -92,12 +78,12 @@ jobs:
 
   build:
     if: ${{ inputs.target != '' && inputs.arch != 'native' }}
-    needs: [version, find-targets]
+    needs: [version]
     uses: ./.github/workflows/build_firmware.yml
     with:
       version: ${{ needs.version.outputs.long }}
       pio_env: ${{ inputs.target }}
-      platform: ${{ needs.find-targets.outputs.arch }}
+      platform: ${{ inputs.arch }}
 
   gather-artifacts:
     permissions:
@@ -107,7 +93,7 @@ jobs:
     needs: [version, build]
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           ref: ${{github.event.pull_request.head.ref}}
           repository: ${{github.event.pull_request.head.repo.full_name}}

.github/workflows/build_portduino_wasm.yml

@@ -1,81 +0,0 @@
-name: Build PortDuino WASM
-
-# Reusable workflow - called as the `build-wasm` job of the main CI workflow
-# (main_matrix.yml), so the WebAssembly portduino node is built like every other
-# platform. Builds the [env:native-wasm] target (src/platform/portduino/wasm/) with
-# `pio run -e native-wasm` so it can't silently bit-rot. Software/CI only - asserts the
-# full mesh stack + RadioLib + Crypto compile and link to meshnode.{mjs,wasm}
-# via the meshtastic/platform-wasm PlatformIO platform (emcc/Asyncify). It does
-# NOT exercise the radio (that's CH341/WebUSB, hardware).
-
-on:
-  workflow_call:
-  workflow_dispatch:
-
-permissions: {}
-
-jobs:
-  build-wasm:
-    name: Build PortDuino WASM
-    runs-on: ubuntu-latest
-    # Only pushes to the default branch (develop) populate the cache; PR / merge_group runs
-    # restore it but never save, so they stop filling up the repo's Actions cache storage.
-    env:
-      SAVE_CACHE: ${{ github.event_name == 'push' && github.ref_name == github.event.repository.default_branch }}
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          submodules: recursive
-
-      # Python + PlatformIO. (`pio run -e native-wasm` installs its own libdeps and the
-      # platform-wasm/framework-portduino packages; it needs no native apt libs.)
-      - name: Setup native build
-        uses: ./.github/actions/setup-native
-
-      - name: Setup Emscripten SDK
-        uses: emscripten-core/setup-emsdk@0822153d7a5488b70a269cfa0a631b2a86ab4da2 # 'v17' main
-        with:
-          version: 6.0.1
-          actions-cache-folder: emsdk-cache
-
-      - name: Restore PlatformIO cache
-        id: pio-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-wasm-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-          restore-keys: |
-            pio-wasm-
-
-      - name: Build PortDuino WASM
-        run: platformio run -e native-wasm
-
-      - name: Save PlatformIO cache
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-wasm-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-
-      - name: Assert WASM artifacts
-        run: |
-          OUT=.pio/build/native-wasm
-          if [ ! -s "$OUT/meshnode.mjs" ] || [ ! -s "$OUT/meshnode.wasm" ]; then
-            echo "::error::wasm artifacts missing"; exit 1
-          fi
-          # The emcc link succeeds even if embedded EM_ASM JS is malformed, so
-          # parse the generated ES-module loader to catch runtime-JS breakage
-          # (e.g. a formatter splitting !== inside EM_ASM).
-          node --check "$OUT/meshnode.mjs" || { echo "::error::meshnode.mjs failed JS parse"; exit 1; }
-          ls -lah "$OUT"/meshnode.*
-
-      - name: Upload WASM artifacts
-        if: success()
-        uses: actions/upload-artifact@v7
-        with:
-          name: portduino-wasm
-          overwrite: true
-          path: |
-            .pio/build/native-wasm/meshnode.mjs
-            .pio/build/native-wasm/meshnode.wasm
-          retention-days: 14

.github/workflows/build_windows_bin.yml

@@ -1,165 +0,0 @@
-name: Build Windows Binary
-
-on:
-  workflow_call:
-    inputs:
-      windows_ver:
-        required: false
-        default: "2025"
-        type: string
-
-permissions:
-  contents: read
-
-jobs:
-  build-Windows:
-    runs-on: windows-${{ inputs.windows_ver }}
-    # Only pushes to the default branch (develop) populate the cache; PR / merge_group runs
-    # restore it but never save, so they stop filling up the repo's Actions cache storage.
-    env:
-      SAVE_CACHE: ${{ github.event_name == 'push' && github.ref_name == github.event.repository.default_branch }}
-    defaults:
-      run:
-        # UCRT64 is the MinGW-w64 environment native-windows targets; the `msys`
-        # environment would link msys-2.0.dll and produce a Cygwin-style binary.
-        shell: msys2 {0}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-        with:
-          submodules: recursive
-          # Keep the token out of .git/config so later steps and artifacts can't leak it.
-          persist-credentials: false
-
-      - name: Setup MSYS2 / UCRT64
-        id: msys2
-        uses: msys2/setup-msys2@v2
-        with:
-          msystem: UCRT64
-          update: true
-          cache: true
-          # argp is not packaged for the mingw environments and is built below.
-          # Python is omitted too: MSYS2's reports a `mingw` platform tag no wheel matches.
-          install: >-
-            mingw-w64-ucrt-x86_64-gcc
-            mingw-w64-ucrt-x86_64-pkgconf
-            mingw-w64-ucrt-x86_64-yaml-cpp
-            mingw-w64-ucrt-x86_64-libuv
-            mingw-w64-ucrt-x86_64-jsoncpp
-            mingw-w64-ucrt-x86_64-openssl
-            mingw-w64-ucrt-x86_64-curl
-            mingw-w64-ucrt-x86_64-libusb
-            mingw-w64-ucrt-x86_64-cmake
-            mingw-w64-ucrt-x86_64-ninja
-            git
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.14"
-          cache: pip
-
-      # framework-portduino calls argp_parse(); MSYS2 packages argp only for the
-      # msys runtime, which cannot link into a native binary. No install() rules.
-      - name: Build and install argp-standalone
-        run: |
-          git clone --depth 1 https://github.com/tom42/argp-standalone /tmp/argp
-          cd /tmp/argp
-          cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release .
-          cmake --build build
-          cp include/argp-standalone/argp.h /ucrt64/include/argp.h
-          cp build/src/libargp-standalone.a /ucrt64/lib/libargp.a
-
-      - name: Install PlatformIO
-        shell: pwsh
-        run: |
-          python -m pip install --upgrade pip
-          pip install platformio
-
-      - name: Restore PlatformIO cache
-        id: pio-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-windows-${{ inputs.windows_ver }}-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-          restore-keys: |
-            pio-windows-${{ inputs.windows_ver }}-
-
-      - name: Get release version string
-        shell: pwsh
-        id: version
-        run: echo "long=$(python ./bin/buildinfo.py long)" >> $env:GITHUB_OUTPUT
-
-      # Runs outside the MSYS2 shell so PlatformIO stays on the runner's
-      # CPython; the UCRT64 toolchain is reached through PATH instead.
-      - name: Build for Windows
-        shell: pwsh
-        run: |
-          $env:PATH = "${{ steps.msys2.outputs.msys2-location }}\ucrt64\bin;$env:PATH"
-          platformio run -e native-windows
-        env:
-          PKG_VERSION: ${{ steps.version.outputs.long }}
-
-      - name: Save PlatformIO cache
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-windows-${{ inputs.windows_ver }}-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-
-      - name: List output files
-        run: ls -lah .pio/build/native-windows/
-
-      # The env links statically, so only Windows system DLLs should appear here.
-      # A third-party DLL means the static link regressed.
-      - name: Verify the binary is self-contained
-        run: |
-          set -euo pipefail
-          bin=.pio/build/native-windows/meshtasticd.exe
-          test -f "$bin"
-          # `|| true` keeps grep's no-match exit out of `set -e`; an empty import
-          # table is caught by the test below instead of passing as "no deps".
-          deps=$(objdump -p "$bin" | grep -i 'DLL Name' || true)
-          test -n "$deps"
-          extra=$(printf '%s\n' "$deps" \
-            | grep -viE 'api-ms-win|KERNEL32|WS2_32|ADVAPI32|USER32|msvcrt|ucrtbase|bcrypt|IPHLPAPI|SHELL32|ole32|CRYPT32|SETUPAPI|CFGMGR32|WINMM|dbghelp' || true)
-          if [ -n "$extra" ]; then
-            printf '%s\n' "$extra"
-            echo "::error::meshtasticd.exe has non-system DLL dependencies (static link regressed)"
-            exit 1
-          fi
-          echo "OK: no third-party DLL dependencies"
-
-      - name: Smoke test the binary
-        run: |
-          .pio/build/native-windows/meshtasticd.exe --version
-
-      - name: Store binaries as an artifact
-        uses: actions/upload-artifact@v7
-        with:
-          name: firmware-windows-${{ inputs.windows_ver }}-${{ steps.version.outputs.long }}
-          overwrite: true
-          path: |
-            .pio/build/native-windows/meshtasticd.exe
-
-      - name: Install WiX
-        shell: pwsh
-        run: |
-          dotnet tool install --global wix --version 5.0.2
-          "$env:USERPROFILE\.dotnet\tools" | Out-File -FilePath $env:GITHUB_PATH -Append -Encoding utf8
-          & "$env:USERPROFILE\.dotnet\tools\wix.exe" extension add -g WixToolset.Util.wixext/5.0.2
-
-      - name: Build the MSI and winget manifests
-        shell: pwsh
-        run: ./bin/build-winget-package.ps1 -ReleaseTag "v$env:LONG_VERSION" -Validate
-        env:
-          LONG_VERSION: ${{ steps.version.outputs.long }}
-
-      - name: Store the MSI and winget manifests as an artifact
-        uses: actions/upload-artifact@v7
-        with:
-          name: meshtasticd-msi-${{ inputs.windows_ver }}-${{ steps.version.outputs.long }}
-          overwrite: true
-          path: |
-            release/winget/*.msi
-            release/winget/manifests/

.github/workflows/daily_packaging.yml

@@ -35,8 +35,8 @@ jobs:
         series:
           - jammy # 22.04 LTS
           - noble # 24.04 LTS
+          - questing # 25.10
           - resolute # 26.04 LTS
-          - stonking # 26.10
     uses: ./.github/workflows/package_ppa.yml
     with:
       ppa_repo: ppa:meshtastic/daily

.github/workflows/docker_build.yml

@@ -45,13 +45,9 @@ jobs:
     outputs:
       digest: ${{ steps.docker_variant.outputs.digest }}
     runs-on: ${{ inputs.runs-on }}
-    env:
-      # Only cache on default branch (develop).
-      # 'docker/' actions don't support separate Restore/Save actions, so we have to disable caching entirely on PRs/merge_queue.
-      USE_CACHE: ${{ github.ref_name == github.event.repository.default_branch }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 
@@ -63,12 +59,11 @@ jobs:
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v4
         with:
-          cache-image: ${{ env.USE_CACHE }}
+          cache-image: true
 
       - name: Docker setup
         uses: docker/setup-buildx-action@v4
         with:
-          cache-binary: ${{ env.USE_CACHE }}
           # Add Google/Amazon DockerHub mirrors to buildkit config
           # https://docs.docker.com/build/ci/github-actions/configure-builder/#registry-mirror
           buildkitd-config-inline: |
@@ -82,20 +77,13 @@ jobs:
           plat: ${{ inputs.platform }}
         run: echo "cleaned_platform=${plat}" | sed 's/\//_/g' >> $GITHUB_OUTPUT
 
-      - name: DockerHub login
+      - name: Docker login
         if: ${{ inputs.push }}
         uses: docker/login-action@v4
         with:
           username: meshtastic
           password: ${{ secrets.DOCKER_FIRMWARE_TOKEN }}
 
-      - name: GHCR login
-        uses: docker/login-action@v4
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Docker tag
         id: meta
         uses: docker/metadata-action@v6
@@ -105,19 +93,6 @@ jobs:
             GHA-${{ steps.version.outputs.long }}-${{ inputs.distro }}-${{ steps.sanitize_platform.outputs.cleaned_platform }}
           flavor: latest=false
 
-      - name: Docker setup caching
-        id: docker-cache
-        env:
-          BASE_REF: ${{ github.event.merge_group.base_ref || github.event.pull_request.base.ref || github.ref_name }}
-        run: |
-          base=$(echo "${BASE_REF#refs/heads/}" | sed 's/\//_/g')
-          ref=ghcr.io/${{ github.repository }}-cache:${base}-${{ inputs.distro }}-${{ steps.sanitize_platform.outputs.cleaned_platform }}
-          echo "cache_from=type=registry,ref=${ref}" >> $GITHUB_OUTPUT
-          case "${GITHUB_EVENT_NAME}" in
-            merge_group|pull_request) ;;
-            *) echo "cache_to=type=registry,ref=${ref},mode=max,ignore-error=true" >> $GITHUB_OUTPUT ;;
-          esac
-
       - name: Docker build and push
         uses: docker/build-push-action@v7
         id: docker_variant
@@ -130,6 +105,6 @@ jobs:
           platforms: ${{ inputs.platform }}
           build-args: |
             PIO_ENV=${{ inputs.pio_env }}
-          # Cache image layers in GitHub Container Registry to speed up subsequent builds.
-          cache-from: ${{ steps.docker-cache.outputs.cache_from }}
-          cache-to: ${{ steps.docker-cache.outputs.cache_to || '' }}
+          # Cache image layers in GitHub Actions cache to speed up subsequent builds.
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker_manifest.yml

@@ -103,7 +103,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 

.github/workflows/firmware-size-comment.yml

@@ -1,62 +0,0 @@
-name: Post Firmware Size Comment
-
-on:
-  workflow_run:
-    workflows: [CI]
-    types: [completed]
-
-permissions:
-  pull-requests: write
-  actions: read
-
-jobs:
-  post-size-comment:
-    if: >
-      github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.conclusion != 'cancelled' &&
-      github.repository == 'meshtastic/firmware'
-    continue-on-error: true
-    runs-on: ubuntu-latest
-    steps:
-      - name: Download size report
-        id: download
-        uses: actions/download-artifact@v8
-        continue-on-error: true
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          run-id: ${{ github.event.workflow_run.id }}
-          name: size-report
-          path: ./
-
-      - name: Post or update PR comment
-        if: steps.download.outcome == 'success'
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const fs = require('fs');
-            const marker = '<!-- firmware-size-report -->';
-            const body = fs.readFileSync('./size-report.md', 'utf8');
-            const prNumber = parseInt(fs.readFileSync('./pr-number.txt', 'utf8').trim(), 10);
-
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: prNumber,
-            });
-
-            const existing = comments.find(c => c.body.includes(marker));
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-                body,
-              });
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body,
-              });
-            }

.github/workflows/flasher-link-comment.yml

@@ -1,187 +0,0 @@
-name: Post Web Flasher Link Comment
-
-on:
-  workflow_run:
-    workflows: [CI]
-    types: [completed]
-
-permissions:
-  pull-requests: write
-  actions: read
-
-jobs:
-  post-flasher-link:
-    if: >
-      github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.conclusion != 'cancelled' &&
-      github.repository == 'meshtastic/firmware'
-    continue-on-error: true
-    runs-on: ubuntu-latest
-    steps:
-      # Per-board manifests carry the firmware's own metadata (activelySupported,
-      # displayName, ...) generated from each target's custom_meshtastic_* config.
-      - name: Download board manifests
-        uses: actions/download-artifact@v8
-        continue-on-error: true
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          run-id: ${{ github.event.workflow_run.id }}
-          pattern: manifest-*
-          path: ./manifests
-          merge-multiple: true
-
-      - name: Post or update web flasher link comment
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const marker = '<!-- web-flasher-link -->';
-            const run = context.payload.workflow_run;
-            const { owner, repo } = context.repo;
-
-            // Resolve the PR by matching the run's head SHA against the repo's open
-            // PRs. workflow_run.pull_requests is empty for fork PRs, and
-            // listPullRequestsAssociatedWithCommit won't return an open fork PR by
-            // its head commit - but pulls.list includes fork PRs. Matching on head
-            // SHA also enforces that the run is for the PR's current commit, so stale
-            // re-runs of an outdated commit won't match.
-            const openPrs = await github.paginate(github.rest.pulls.list, {
-              owner, repo, state: 'open', per_page: 100,
-            });
-            const pr = openPrs.find((p) => p.head.sha === run.head_sha);
-            if (!pr) {
-              core.info(`No open pull request matches commit ${run.head_sha}; skipping.`);
-              return;
-            }
-            const prNumber = pr.number;
-
-            // Restrict to trusted authors. NOTE: author_association is computed for
-            // the GITHUB_TOKEN, which cannot see *private/concealed* org memberships -
-            // those members come back as CONTRIBUTOR, not MEMBER. So gating on MEMBER
-            // alone silently excludes most maintainers. We allow the trusted set the
-            // token can actually identify (members, collaborators, and anyone with a
-            // previously merged PR). For strict members-only you'd need an org-read
-            // App/PAT token to call orgs.checkMembershipForUser.
-            const allowedAssociations = ['OWNER', 'MEMBER', 'COLLABORATOR', 'CONTRIBUTOR'];
-            if (!allowedAssociations.includes(pr.author_association)) {
-              core.info(`Author association ${pr.author_association} is not trusted; skipping.`);
-              return;
-            }
-
-            // Require at least one per-arch firmware artifact from gather-artifacts
-            const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
-              owner, repo, run_id: run.id, per_page: 100,
-            });
-            const archRe = /^firmware-(esp32|esp32s3|esp32c3|esp32c6|nrf52840|rp2040|rp2350|stm32)-(\d+\.\d+\.\d+\.[0-9a-f]+)$/;
-            const archArtifacts = artifacts.filter((a) => archRe.test(a.name) && !a.expired);
-            if (archArtifacts.length === 0) {
-              core.info('No per-arch firmware artifacts found; skipping.');
-              return;
-            }
-
-            const version = archRe.exec(archArtifacts[0].name)[2];
-            const expiresAt = archArtifacts[0].expires_at
-              ? new Date(archArtifacts[0].expires_at).toISOString().slice(0, 10)
-              : null;
-
-            // Read each built board's manifest (.mt.json). activelySupported,
-            // displayName and architecture come straight from the board's
-            // custom_meshtastic_* platformio config, so the list is in sync with
-            // the firmware itself - no external device database needed.
-            const fs = require('fs');
-            let boards = [];
-            try {
-              boards = fs.readdirSync('./manifests')
-                .filter((f) => f.endsWith('.mt.json'))
-                .map((f) => {
-                  try { return JSON.parse(fs.readFileSync(`./manifests/${f}`, 'utf8')); }
-                  catch { return null; }
-                })
-                .filter((m) => m && m.activelySupported === true && m.platformioTarget)
-                .map((m) => ({
-                  board: m.platformioTarget,
-                  platform: m.architecture || '',
-                  // displayName is maintainer-authored text; escape table-breaking pipes
-                  displayName: String(m.displayName || m.platformioTarget).replace(/\|/g, '\\|'),
-                  image: Array.isArray(m.images) && m.images[0] ? String(m.images[0]) : '',
-                }))
-                .sort((a, b) => a.board.localeCompare(b.board));
-            } catch (e) {
-              core.warning(`Could not read board manifests: ${e.message}`);
-            }
-
-            const flasherUrl = `https://flasher.meshtastic.org/?pr=${prNumber}`;
-            // Device illustrations are served by the flasher from the same image
-            // names the manifest declares (custom_meshtastic_images). The flasher
-            // serves its SPA shell (HTML, 200) for unknown paths, so confirm each
-            // image really resolves to an image before linking it.
-            const imageBase = 'https://flasher.meshtastic.org/img/devices/';
-            await Promise.all(boards.map(async (b) => {
-              if (!b.image) return;
-              try {
-                const res = await fetch(`${imageBase}${encodeURIComponent(b.image)}`);
-                const type = res.headers.get('content-type') || '';
-                if (!res.ok || !type.startsWith('image/')) b.image = '';
-              } catch { b.image = ''; }
-            }));
-
-            const boardLines = boards
-              .map((b) => {
-                const img = b.image ? `<img src="${imageBase}${encodeURIComponent(b.image)}" alt="" height="34">` : '';
-                return `| ${img} | ${b.displayName} | [\`${b.board}\`](${flasherUrl}&device=${encodeURIComponent(b.board)}) | ${b.platform} |`;
-              })
-              .join('\n');
-
-            // Shields.io badges. Only non-user-controlled, charset-constrained values
-            // (version, commit sha, counts, dates) go into badge URLs - never board
-            // names or the PR title - so the rendered comment cannot be spoofed.
-            const shieldText = (s) =>
-              encodeURIComponent(String(s).replace(/-/g, '--').replace(/_/g, '__').replace(/ /g, '_'));
-            const shield = (label, message, color) =>
-              `https://img.shields.io/badge/${shieldText(label)}-${shieldText(message)}-${color}`;
-            const buttonUrl =
-              `https://img.shields.io/badge/${shieldText('Flash this PR in the Web Flasher')}-2C2D3C?style=for-the-badge`;
-            const badges = [
-              `![firmware](${shield('firmware', version, '67EA94')})`,
-              `![commit](${shield('commit', run.head_sha.slice(0, 7), '2C2D3C')})`,
-              `![boards](${shield('boards', boards.length, '5C6BC0')})`,
-            ];
-            if (expiresAt) badges.push(`![expires](${shield('expires', expiresAt, '9A4E00')})`);
-
-            // Only render the board table when there are supported boards to list
-            const boardTable = boards.length > 0 ? [
-              `<details><summary>Supported boards built by this PR (${boards.length})</summary>`,
-              '',
-              '| | Device | Board | Platform |',
-              '| --- | --- | --- | --- |',
-              boardLines,
-              '',
-              '</details>',
-              '',
-            ] : [];
-
-            const body = [
-              marker,
-              '## ⚡ Try this PR in the Web Flasher',
-              '',
-              `[![Flash this PR in the Web Flasher](${buttonUrl})](${flasherUrl})`,
-              '',
-              badges.join(' '),
-              '',
-              '> [!WARNING]',
-              '> This is an automated, unreviewed CI test build. Back up your device configuration',
-              '> before flashing, and only flash devices you are able to recover.',
-              '',
-              ...boardTable,
-              `*Build artifacts expire${expiresAt ? ` on ${expiresAt}` : ' after 30 days'}. Updated for \`${run.head_sha.slice(0, 7)}\`.*`,
-            ].join('\n');
-
-            // Sticky comment: update in place when the marker is found
-            const comments = await github.paginate(github.rest.issues.listComments, {
-              owner, repo, issue_number: prNumber, per_page: 100,
-            });
-            const existing = comments.find((c) => c.body?.includes(marker));
-            if (existing) {
-              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
-            } else {
-              await github.rest.issues.createComment({ owner, repo, issue_number: prNumber, body });
-            }

.github/workflows/flasher-link-placeholder.yml

@@ -1,62 +0,0 @@
-name: Post Web Flasher Build Placeholder
-
-# Drops an immediate "build in progress" comment when a PR opens, so the web
-# flasher entry shows up right away. The real CI-driven workflow
-# (flasher-link-comment.yml) later replaces it in place via the shared marker.
-#
-# SECURITY: this uses pull_request_target (write token, runs for fork PRs) but is
-# safe because it never checks out or runs PR code and posts a fully static body
-# - no PR title, branch name, or other untrusted input is used anywhere.
-
-on:
-  pull_request_target:
-    types: [opened, reopened]
-
-permissions:
-  pull-requests: write
-
-jobs:
-  post-placeholder:
-    if: github.repository == 'meshtastic/firmware'
-    continue-on-error: true
-    runs-on: ubuntu-latest
-    steps:
-      - name: Post web flasher build-in-progress placeholder
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const marker = '<!-- web-flasher-link -->';
-            const { owner, repo } = context.repo;
-            const pr = context.payload.pull_request;
-
-            // Trusted authors only (matches the real workflow). author_association
-            // can't reflect private org membership for the token, so concealed
-            // members appear as CONTRIBUTOR - include it, or maintainers are excluded.
-            const allowedAssociations = ['OWNER', 'MEMBER', 'COLLABORATOR', 'CONTRIBUTOR'];
-            if (!allowedAssociations.includes(pr.author_association)) {
-              core.info(`Author association ${pr.author_association} is not trusted; skipping.`);
-              return;
-            }
-
-            // Only seed a placeholder when no flasher comment exists yet - never
-            // overwrite a real (or existing placeholder) comment.
-            const comments = await github.paginate(github.rest.issues.listComments, {
-              owner, repo, issue_number: pr.number, per_page: 100,
-            });
-            if (comments.some((c) => c.body?.includes(marker))) {
-              core.info('Flasher comment already exists; nothing to do.');
-              return;
-            }
-
-            const body = [
-              marker,
-              '## ⚡ Try this PR in the Web Flasher',
-              '',
-              '> [!NOTE]',
-              '> Building this pull request… the flash button, badges and supported-board',
-              '> list will appear here automatically once CI finishes.',
-            ].join('\n');
-
-            await github.rest.issues.createComment({
-              owner, repo, issue_number: pr.number, body,
-            });

.github/workflows/hook_copr.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 

.github/workflows/main_matrix.yml

@@ -3,21 +3,12 @@ concurrency:
   group: ci-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 on:
-  # The merge queue is the pre-merge gate for the protected branches (master,
-  # develop): a merge_group run validates the merged result before code lands. For
-  # now PRs and merge_group runs build the same narrowed board subset (--level pr);
-  # see the setup job. push still runs the full matrix on master/develop (post-merge)
-  # as well as on the event/* and feature/* branches, which have no merge queue.
-  merge_group:
-    types: [checks_requested]
-    branches:
-      - master
-      - develop
-
+  # # Triggers the workflow on push but only for the main branches
   push:
     branches:
       - master
       - develop
+      - pioarduino # Remove when merged // use `feature/` in the future.
       - event/*
       - feature/*
     paths-ignore:
@@ -28,36 +19,28 @@ on:
     branches:
       - master
       - develop
+      - pioarduino # Remove when merged // use `feature/` in the future.
       - event/*
       - feature/*
     paths-ignore:
       - "**.md"
       #- "**.yml"
 
-  schedule:
-    # Nightly develop build, published to meshtastic.github.io firmware-nightly/ (no GitHub release).
-    # Scheduled runs execute on the default branch (develop). 07:00 UTC avoids the 00:00 tests
-    # and 02:00 daily_packaging crons.
-    - cron: 0 7 * * * # Nightly develop build/publish (default branch is develop)
-
   workflow_dispatch:
-    inputs:
-      # trunk-ignore(checkov/CKV_GHA_7): intentional manual-test switch for the nightly publish path
-      nightly:
-        description: "Nightly mode: build + publish develop to github.io firmware-nightly/ (skips creating a GitHub release)"
-        type: boolean
-        default: false
 
 permissions: read-all
 
 jobs:
   setup:
+    strategy:
+      fail-fast: true
+      matrix:
+        arch:
+          - all
+          - check
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v7
-        with:
-          # Needed to diff against the base branch for newly added variants.
-          fetch-depth: 0
+      - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
           python-version: 3.x
@@ -65,46 +48,23 @@ jobs:
       - run: pip install -U platformio
       - name: Generate matrix
         id: jsonStep
-        env:
-          BASE_REF: ${{ github.base_ref }}
-          MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
         run: |
-          # A new board is 'release' and gets no CI until after merge, so force-build the
-          # first env of each ADDED variant config. A new env in an existing one does not count.
-          DIFF_BASE=""
-          if [[ "$GITHUB_EVENT_NAME" == "pull_request" ]]; then
-            git fetch --no-tags --depth=1 origin "$BASE_REF"
-            DIFF_BASE=$(git merge-base FETCH_HEAD HEAD)
-          elif [[ "$GITHUB_EVENT_NAME" == "merge_group" ]]; then
-            DIFF_BASE="$MERGE_GROUP_BASE_SHA"
-          fi
-          ADDED_ARGS=()
-          if [[ -n "$DIFF_BASE" ]]; then
-            # Assign rather than pipe: a failing diff must abort the step under 'set -e',
-            # not silently yield an empty list and drop the new board from the matrix.
-            ADDED_CONFIGS=$(git diff --name-only --diff-filter=A \
-              "$DIFF_BASE" HEAD -- 'variants/**/platformio.ini')
-            while IFS= read -r cfg; do
-              [[ -n "$cfg" ]] && ADDED_ARGS+=(--added-config "$cfg")
-            done <<<"$ADDED_CONFIGS"
-          fi
-          # PRs and (for now) merge_group builds use the narrowed --level pr board
-          # subset. Full-matrix builds run on push / schedule / workflow_dispatch.
-          if [[ "$GITHUB_EVENT_NAME" == "pull_request" || "$GITHUB_EVENT_NAME" == "merge_group" ]]; then
-            TARGETS=$(./bin/generate_ci_matrix.py all --level pr "${ADDED_ARGS[@]}")
-          else
-            TARGETS=$(./bin/generate_ci_matrix.py all)
+          if [[ "$GITHUB_HEAD_REF" == "" ]]; then
+            TARGETS=$(./bin/generate_ci_matrix.py ${{matrix.arch}})
+          else  
+            TARGETS=$(./bin/generate_ci_matrix.py ${{matrix.arch}} --level pr)
           fi
           echo "Name: $GITHUB_REF_NAME Base: $GITHUB_BASE_REF Ref: $GITHUB_REF"
-          echo "all=$TARGETS" >> $GITHUB_OUTPUT
+          echo "${{matrix.arch}}=$TARGETS" >> $GITHUB_OUTPUT
           echo "$TARGETS" >> $GITHUB_STEP_SUMMARY
     outputs:
       all: ${{ steps.jsonStep.outputs.all }}
+      check: ${{ steps.jsonStep.outputs.check }}
 
   version:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
       - name: Get release version string
         run: |
           echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
@@ -121,14 +81,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        check: ${{ fromJson(needs.setup.outputs.all) }}
-    # Runs on GitHub-hosted runners so checks don't compete with builds for the
-    # self-hosted 'arctastic' pool (which builds use).
-    runs-on: ubuntu-latest
-    # Only run checks for PRs and Merge Queue runs.
-    if: contains(fromJSON('["pull_request", "merge_group"]'), github.event_name)
+        check: ${{ fromJson(needs.setup.outputs.check) }}
+    # Use 'arctastic' self-hosted runner pool when checking in the main repo
+    runs-on: ${{ github.repository_owner == 'meshtastic' && 'arctastic' || 'ubuntu-latest' }}
+    if: ${{ github.event_name != 'workflow_dispatch' && github.repository == 'meshtastic/firmware' }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
         with:
           submodules: recursive
       - name: Check ${{ matrix.check.board }}
@@ -151,7 +109,7 @@ jobs:
       platform: ${{ matrix.build.platform }}
 
   build-debian-src:
-    if: github.repository_owner == 'meshtastic' && github.event_name != 'schedule' && github.event.inputs.nightly != 'true'
+    if: github.repository == 'meshtastic/firmware'
     uses: ./.github/workflows/build_debian_src.yml
     with:
       series: UNRELEASED
@@ -159,7 +117,6 @@ jobs:
     secrets: inherit
 
   MacOS:
-    if: github.event_name != 'schedule' && github.event.inputs.nightly != 'true' && !contains(github.ref_name, 'event/')
     strategy:
       fail-fast: false
       matrix:
@@ -173,44 +130,22 @@ jobs:
       macos_ver: ${{ matrix.macos_ver }}
     # secrets: inherit
 
-  Windows:
-    if: github.event_name != 'schedule' && github.event.inputs.nightly != 'true' && !contains(github.ref_name, 'event/')
-    strategy:
-      fail-fast: false
-      matrix:
-        windows_ver:
-          - "2025" # x86_64
-    uses: ./.github/workflows/build_windows_bin.yml
-    with:
-      windows_ver: ${{ matrix.windows_ver }}
-    # secrets: inherit
-
   package-pio-deps-native-tft:
-    if: github.repository_owner == 'meshtastic' && github.event_name == 'workflow_dispatch'
+    if: ${{ github.repository == 'meshtastic/firmware' && github.event_name == 'workflow_dispatch' }}
     uses: ./.github/workflows/package_pio_deps.yml
     with:
       pio_env: native-tft
     secrets: inherit
 
   test-native:
-    if: github.repository_owner == 'meshtastic' && github.event_name != 'schedule' && github.event.inputs.nightly != 'true' && !contains(github.ref_name, 'event/')
+    if: ${{ !contains(github.ref_name, 'event/') && github.repository == 'meshtastic/firmware' }}
     permissions: # Needed for dorny/test-reporter.
       contents: read
       actions: read
       checks: write
     uses: ./.github/workflows/test_native.yml
 
-  build-wasm:
-    if: github.event_name != 'schedule' && github.event.inputs.nightly != 'true' && !contains(github.ref_name, 'event/')
-    # Build the WebAssembly portduino node ([env:native-wasm]) as part of normal CI,
-    # like the other platforms. It's a dedicated job (not a row in the `build`
-    # matrix) because its artifact is meshnode.{mjs,wasm} - not a flashable
-    # .bin/.uf2/.hex - and it needs the Emscripten SDK; board_level=extra keeps
-    # it out of generate_ci_matrix.py.
-    uses: ./.github/workflows/build_portduino_wasm.yml
-
   docker:
-    if: github.event_name != 'schedule' && github.event.inputs.nightly != 'true' && !contains(github.ref_name, 'event/')
     permissions: # Needed for pushing to GHCR.
       contents: read
       packages: write
@@ -218,8 +153,15 @@ jobs:
       fail-fast: false
       matrix:
         distro: [debian, alpine]
-        platform: [linux/arm64]
-        pio_env: [native-tft]
+        platform: [linux/amd64, linux/arm64, linux/arm/v7]
+        pio_env: [native, native-tft]
+        exclude:
+          - distro: alpine
+            platform: linux/arm/v7
+          - pio_env: native-tft
+            platform: linux/arm64
+          - pio_env: native-tft
+            platform: linux/arm/v7
     uses: ./.github/workflows/docker_build.yml
     with:
       distro: ${{ matrix.distro }}
@@ -228,32 +170,9 @@ jobs:
       pio_env: ${{ matrix.pio_env }}
       push: false
 
-  # Single, stable status check for branch protection.
-  # Always runs and passes only if every build and check that ran succeeded.
-  ci-gate:
-    # Consumed in PRs and Merge Queue
-    if: contains(fromJSON('["pull_request", "merge_group"]'), github.event_name) && !cancelled()
-    needs: [build, check]
-    runs-on: ubuntu-slim
-    steps:
-      - name: Verify build and check results
-        run: |
-          echo "build=${{ needs.build.result }} check=${{ needs.check.result }}"
-          if [[ "${{ needs.build.result }}" != "success" ]]; then
-            echo "::error::One or more firmware builds failed, were cancelled, or did not run."
-            exit 1
-          fi
-          case "${{ needs.check.result }}" in
-            success | skipped) ;;
-            *)
-              echo "::error::One or more checks failed or were cancelled (${{ needs.check.result }})."
-              exit 1
-              ;;
-          esac
-
   gather-artifacts:
-    # Only run on Release (workflow_dispatch) and Nightly (schedule) runs, not on PRs or merge_group runs.
-    if: github.repository_owner == 'meshtastic' && contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name)
+    # trunk-ignore(checkov/CKV2_GHA_1)
+    if: github.repository == 'meshtastic/firmware'
     strategy:
       fail-fast: false
       matrix:
@@ -270,7 +189,7 @@ jobs:
     needs: [version, build]
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - uses: actions/download-artifact@v8
         with:
@@ -326,161 +245,53 @@ jobs:
           path: ./*.elf
           retention-days: 30
 
-  firmware-size-report:
-    if: github.repository_owner == 'meshtastic' && github.event_name != 'schedule' && github.event.inputs.nightly != 'true'
+  shame:
+    if: github.repository == 'meshtastic/firmware'
     continue-on-error: true
-    permissions:
-      contents: read
-      actions: read
     runs-on: ubuntu-latest
     needs: [build]
     steps:
-      - uses: actions/checkout@v7
-
-      - name: Download current manifests
+      - uses: actions/checkout@v6
+        if: github.event_name == 'pull_request'
+        with:
+          filter: blob:none # means we download all the git history but none of the commit (except ones with checkout like the head)
+          fetch-depth: 0
+      - name: Download the current manifests
         uses: actions/download-artifact@v8
         with:
-          path: ./manifests/
+          path: ./manifests-new/
           pattern: manifest-*
           merge-multiple: true
-
-      - name: Collect current firmware sizes
-        run: python3 bin/collect_sizes.py ./manifests/ ./current-sizes.json
-
-      - name: Upload size report artifact
+      - name: Upload combined manifests for later commit and global stats crunching.
         uses: actions/upload-artifact@v7
+        id: upload-manifest
         with:
-          name: firmware-sizes-${{ github.sha }}
+          name: manifests-${{ github.sha }}
           overwrite: true
-          path: ./current-sizes.json
-          retention-days: 90
-
-      - name: Download baseline sizes from develop
+          path: manifests-new/*.mt.json
+      - name: Find the merge base
         if: github.event_name == 'pull_request'
-        continue-on-error: true
-        id: baseline-develop
+        run: echo "MERGE_BASE=$(git merge-base "origin/$base" "$head")" >> $GITHUB_ENV
         env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          RUN_ID=$(gh run list -R "${{ github.repository }}" \
-            --workflow CI --branch develop --status success \
-            --limit 1 --json databaseId --jq '.[0].databaseId // empty')
-          if [ -n "$RUN_ID" ]; then
-            ARTIFACT_NAME=$(gh api "repos/${{ github.repository }}/actions/runs/${RUN_ID}/artifacts" \
-              --jq '.artifacts[] | select(.name | startswith("firmware-sizes-")) | select(.expired == false) | .name' | head -1)
-            if [ -n "$ARTIFACT_NAME" ]; then
-              gh run download "$RUN_ID" -R "${{ github.repository }}" \
-                --name "$ARTIFACT_NAME" --dir ./baseline-develop/
-              cp "./baseline-develop/current-sizes.json" ./develop-sizes.json
-              echo "found=true" >> "$GITHUB_OUTPUT"
-            else
-              echo "found=false" >> "$GITHUB_OUTPUT"
-            fi
-          else
-            echo "found=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Download baseline sizes from master
-        if: github.event_name == 'pull_request'
-        continue-on-error: true
-        id: baseline-master
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          RUN_ID=$(gh run list -R "${{ github.repository }}" \
-            --workflow CI --branch master --status success \
-            --limit 1 --json databaseId --jq '.[0].databaseId // empty')
-          if [ -n "$RUN_ID" ]; then
-            ARTIFACT_NAME=$(gh api "repos/${{ github.repository }}/actions/runs/${RUN_ID}/artifacts" \
-              --jq '.artifacts[] | select(.name | startswith("firmware-sizes-")) | select(.expired == false) | .name' | head -1)
-            if [ -n "$ARTIFACT_NAME" ]; then
-              gh run download "$RUN_ID" -R "${{ github.repository }}" \
-                --name "$ARTIFACT_NAME" --dir ./baseline-master/
-              cp "./baseline-master/current-sizes.json" ./master-sizes.json
-              echo "found=true" >> "$GITHUB_OUTPUT"
-            else
-              echo "found=false" >> "$GITHUB_OUTPUT"
-            fi
-          else
-            echo "found=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Generate size comparison report
-        if: github.event_name == 'pull_request'
-        id: report
-        run: |
-          ARGS="./current-sizes.json --budgets bin/ram_budgets.json"
-          if [ -f ./develop-sizes.json ]; then
-            ARGS="$ARGS --baseline develop:./develop-sizes.json"
-          fi
-          if [ -f ./master-sizes.json ]; then
-            ARGS="$ARGS --baseline master:./master-sizes.json"
-          fi
-          REPORT=$(python3 bin/size_report.py $ARGS)
-          if [ -z "$REPORT" ]; then
-            echo "has_report=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "has_report=true" >> "$GITHUB_OUTPUT"
-            {
-              echo '<!-- firmware-size-report -->'
-              echo '# Firmware Size Report'
-              echo ''
-              echo "$REPORT"
-              echo ''
-              echo '---'
-              echo "*Updated for ${{ github.sha }}*"
-            } > ./size-report.md
-            cat ./size-report.md >> "$GITHUB_STEP_SUMMARY"
-          fi
-
-      - name: Save PR number
-        if: github.event_name == 'pull_request' && steps.report.outputs.has_report == 'true'
-        run: echo "${{ github.event.pull_request.number }}" > ./pr-number.txt
-
-      - name: Upload size report
-        if: github.event_name == 'pull_request' && steps.report.outputs.has_report == 'true'
-        uses: actions/upload-artifact@v7
-        with:
-          name: size-report
-          path: |
-            ./size-report.md
-            ./pr-number.txt
-          retention-days: 5
-
-  # RAM/flash guardrails: fails CI when an env listed in bin/ram_budgets.json
-  # exceeds its static RAM (.data+.bss) or flash budget. Kept separate from
-  # firmware-size-report, which is informational and continue-on-error.
-  size-budget-gate:
-    if: github.event_name != 'schedule' && github.event.inputs.nightly != 'true'
-    permissions:
-      contents: read
-      actions: read
-    runs-on: ubuntu-latest
-    needs: [build]
-    steps:
-      - uses: actions/checkout@v7
-
-      # No continue-on-error / empty-dir fallback: the gate must fail closed when
-      # the data it enforces on cannot be fetched (size_report.py additionally
-      # fails on missing budgeted envs under --enforce-budgets).
-      - name: Download current manifests
-        uses: actions/download-artifact@v8
-        with:
-          path: ./manifests/
-          pattern: manifest-*
-          merge-multiple: true
-
-      - name: Collect current firmware sizes
-        run: python3 bin/collect_sizes.py ./manifests/ ./current-sizes.json
-
-      - name: Enforce RAM/flash budgets
-        run: python3 bin/size_report.py ./current-sizes.json --budgets bin/ram_budgets.json --enforce-budgets
+          base: ${{ github.base_ref }}
+          head: ${{ github.sha }}
+      # Currently broken (for-loop through EVERY artifact -- rate limiting)
+      # - name: Download the old manifests
+      #   if: github.event_name == 'pull_request'
+      #   run: gh run download -R "$repo" --name "manifests-$merge_base" --dir manifest-old/
+      #   env:
+      #     GH_TOKEN: ${{ github.token }}
+      #     merge_base: ${{ env.MERGE_BASE }}
+      #     repo: ${{ github.repository }}
+      # - name: Do scan and post comment
+      #   if: github.event_name == 'pull_request'
+      #   run: python3 bin/shame.py ${{ github.event.pull_request.number }} manifests-old/ manifests-new/
 
   release-artifacts:
     permissions: # Needed for 'gh release upload'.
       contents: write
     runs-on: ubuntu-latest
-    if: github.repository_owner == 'meshtastic' && github.event_name == 'workflow_dispatch' && github.event.inputs.nightly != 'true'
+    if: ${{ github.event_name == 'workflow_dispatch' && github.repository == 'meshtastic/firmware' }}
     outputs:
       upload_url: ${{ steps.create_release.outputs.upload_url }}
     needs:
@@ -492,7 +303,7 @@ jobs:
       # - MacOS
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -522,7 +333,6 @@ jobs:
           prerelease: true
           name: Meshtastic Firmware ${{ needs.version.outputs.long }} Alpha
           tag_name: v${{ needs.version.outputs.long }}
-          target_commitish: ${{ github.sha }}
           body: ${{ steps.release_notes.outputs.notes }}
 
       - name: Download source deb
@@ -565,7 +375,7 @@ jobs:
 
       - name: Add sources to GitHub Release
         # Only run when targeting master branch with workflow_dispatch
-        if: github.ref_name == 'master'
+        if: ${{ github.ref_name == 'master' }}
         run: |
           gh release upload v${{ needs.version.outputs.long }} ./firmware-${{ needs.version.outputs.long }}.json
           gh release upload v${{ needs.version.outputs.long }} ./output/meshtasticd-${{ needs.version.outputs.deb }}-src.zip
@@ -589,11 +399,11 @@ jobs:
           - rp2350
           - stm32
     runs-on: ubuntu-latest
-    if: github.repository_owner == 'meshtastic' && github.event_name == 'workflow_dispatch' && github.event.inputs.nightly != 'true'
+    if: ${{ github.event_name == 'workflow_dispatch' && github.repository == 'meshtastic/firmware'}}
     needs: [release-artifacts, version]
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - name: Setup Python
         uses: actions/setup-python@v6
@@ -632,7 +442,7 @@ jobs:
 
       - name: Add bins and debug elfs to GitHub Release
         # Only run when targeting master branch with workflow_dispatch
-        if: github.ref_name == 'master'
+        if: ${{ github.ref_name == 'master' }}
         run: |
           gh release upload v${{ needs.version.outputs.long }} ./firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip
           gh release upload v${{ needs.version.outputs.long }} ./debug-elfs-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip
@@ -641,14 +451,14 @@ jobs:
 
   publish-firmware:
     runs-on: ubuntu-24.04
-    if: github.repository_owner == 'meshtastic' && github.event_name == 'workflow_dispatch' && github.event.inputs.nightly != 'true'
+    if: ${{ github.event_name == 'workflow_dispatch' }}
     needs: [release-firmware, version]
     env:
       targets: |-
         esp32,esp32s3,esp32c3,esp32c6,nrf52840,rp2040,rp2350,stm32
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -693,78 +503,3 @@ jobs:
           user_email: github-actions[bot]@users.noreply.github.com
           commit_message: ${{ needs.version.outputs.long }}
           enable_jekyll: true
-
-  # Nightly publish: refresh the single, stable firmware-nightly/ folder on
-  # meshtastic.github.io with the current develop build. Runs on the cron schedule
-  # (or a manual nightly=true dispatch) and never creates a GitHub release. The
-  # folder's release_notes.md is maintained by hand and deliberately left untouched.
-  publish-nightly:
-    runs-on: ubuntu-24.04
-    if: github.repository_owner == 'meshtastic' && (github.event_name == 'schedule' || github.event.inputs.nightly == 'true')
-    needs: [setup, version, gather-artifacts]
-    env:
-      targets: |-
-        esp32,esp32s3,esp32c3,esp32c6,nrf52840,rp2040,rp2350,stm32
-    steps:
-      - name: Get firmware artifacts
-        uses: actions/download-artifact@v8
-        with:
-          pattern: firmware-{${{ env.targets }}}-${{ needs.version.outputs.long }}
-          merge-multiple: true
-          path: ./stage
-
-      - name: Generate Release manifest
-        run: |
-          jq -n --arg ver "${{ needs.version.outputs.long }}" --argjson targets ${{ toJson(needs.setup.outputs.all) }} '{
-            "version": $ver,
-            "targets": $targets
-          }' > ./stage/firmware-${{ needs.version.outputs.long }}.json
-
-      - name: Generate nightly pointer
-        run: |
-          jq -n \
-            --arg ver "${{ needs.version.outputs.long }}" \
-            --arg sha "${{ github.sha }}" \
-            '{version: $ver, id: ("v" + $ver), title: ("Meshtastic Firmware " + $ver + " Nightly"), commit: $sha}' \
-            > ./stage/index.json
-
-      - name: Preserve manually-maintained release notes
-        # firmware-nightly/release_notes.md is edited by hand. Carry the current
-        # copy into ./stage so the keep_files:false publish (which refreshes the
-        # folder and clears stale nightly binaries) does not drop it. Seed a
-        # placeholder on the first run (404); fail closed on any other error so a
-        # transient fetch failure never clobbers the notes.
-        run: |
-          set -euo pipefail
-          url=https://raw.githubusercontent.com/meshtastic/meshtastic.github.io/master/firmware-nightly/release_notes.md
-          code=$(curl -sSL -o ./stage/release_notes.md -w '%{http_code}' --retry 5 --retry-all-errors "$url" || echo 000)
-          if [ "$code" = "200" ]; then
-            echo "Preserved existing release_notes.md"
-          elif [ "$code" = "404" ]; then
-            echo "No existing release_notes.md; seeding placeholder"
-            printf '# Nightly (develop)\n\nAutomated nightly build from the `develop` branch. Edit these notes by hand.\n' > ./stage/release_notes.md
-          else
-            echo "Unexpected HTTP $code fetching release_notes.md; refusing to publish to avoid clobbering manual notes"
-            exit 1
-          fi
-
-      # For diagnostics
-      - name: Display structure of files to publish
-        run: ls -lR ./stage
-
-      - name: Publish nightly to meshtastic.github.io
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          deploy_key: ${{ secrets.DIST_PAGES_DEPLOY_KEY }}
-          external_repository: meshtastic/meshtastic.github.io
-          publish_branch: master
-          publish_dir: ./stage
-          # keep_files:false is scoped to destination_dir, so this refreshes only
-          # firmware-nightly/ (clearing stale nightly binaries) while sibling
-          # release folders stay untouched; release_notes.md is carried in above.
-          destination_dir: firmware-nightly
-          keep_files: false
-          user_name: github-actions[bot]
-          user_email: github-actions[bot]@users.noreply.github.com
-          commit_message: Nightly ${{ needs.version.outputs.long }}
-          enable_jekyll: true

.github/workflows/models_issue_triage.yml

@@ -0,0 +1,213 @@
+name: Issue Triage (Models)
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+  models: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  triage:
+    if: ${{ github.repository == 'meshtastic/firmware' && github.event.issue.user.type != 'Bot' }}
+    runs-on: ubuntu-latest
+    steps:
+      # ─────────────────────────────────────────────────────────────────────────
+      # Step 1: Quality check (spam/AI-slop detection) - runs first, exits early if spam
+      # ─────────────────────────────────────────────────────────────────────────
+      - name: Detect spam or low-quality content
+        uses: actions/ai-inference@v2
+        id: quality
+        continue-on-error: true
+        with:
+          max-tokens: 20
+          prompt: |
+            Is this GitHub issue spam, AI-generated slop, or low quality?
+
+            Title: ${{ github.event.issue.title }}
+            Body: ${{ github.event.issue.body }}
+
+            Respond with exactly one of: spam, ai-generated, needs-review, ok
+          system-prompt: You detect spam and low-quality contributions. Be conservative - only flag obvious spam or AI slop.
+          model: openai/gpt-4o-mini
+
+      - name: Apply quality label if needed
+        if: steps.quality.outputs.response != '' && steps.quality.outputs.response != 'ok'
+        uses: actions/github-script@v9
+        env:
+          QUALITY_LABEL: ${{ steps.quality.outputs.response }}
+        with:
+          script: |
+            const label = (process.env.QUALITY_LABEL || '').trim().toLowerCase();
+            const labelMeta = {
+              'spam': { color: 'd73a4a', description: 'Possible spam' },
+              'ai-generated': { color: 'fbca04', description: 'Possible AI-generated low-quality content' },
+              'needs-review': { color: 'f9d0c4', description: 'Needs human review' },
+            };
+            const meta = labelMeta[label];
+            if (!meta) return;
+
+            // Ensure label exists
+            try {
+              await github.rest.issues.getLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label });
+            } catch (e) {
+              if (e.status !== 404) throw e;
+              await github.rest.issues.createLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label, color: meta.color, description: meta.description });
+            }
+
+            // Apply label
+            await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.payload.issue.number, labels: [label] });
+
+            // Set output to skip remaining steps
+            core.setOutput('is_spam', 'true');
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Step 2: Duplicate detection - only if not spam
+      # ─────────────────────────────────────────────────────────────────────────
+      - name: Detect duplicate issues
+        if: steps.quality.outputs.response == 'ok' || steps.quality.outputs.response == ''
+        uses: pelikhan/action-genai-issue-dedup@bdb3b5d9451c1090ffcdf123d7447a5e7c7a2528 # v0.0.19
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Step 3: Completeness check + auto-labeling (combined into one AI call)
+      # ─────────────────────────────────────────────────────────────────────────
+      - name: Determine if completeness check should be skipped
+        if: steps.quality.outputs.response == 'ok' || steps.quality.outputs.response == ''
+        uses: actions/github-script@v9
+        id: check-skip
+        with:
+          script: |
+            const title = (context.payload.issue.title || '').toLowerCase();
+            const labels = (context.payload.issue.labels || []).map(label => label.name);
+            const hasFeatureRequest = title.includes('feature request');
+            const hasEnhancement = labels.includes('enhancement');
+            const shouldSkip = hasFeatureRequest && hasEnhancement;
+            core.setOutput('should_skip', shouldSkip ? 'true' : 'false');
+
+      - name: Analyze issue completeness and determine labels
+        if: (steps.quality.outputs.response == 'ok' || steps.quality.outputs.response == '') && steps.check-skip.outputs.should_skip != 'true'
+        uses: actions/ai-inference@v2
+        id: analysis
+        continue-on-error: true
+        with:
+          prompt: |
+            Analyze this GitHub issue for completeness and determine if it needs labels.
+
+            IMPORTANT: Distinguish between:
+            - Device/firmware bugs (crashes, reboots, lockups, radio/GPS/display/power issues) - these need device logs
+            - Build/release/packaging issues (missing files, CI failures, download problems) - these do NOT need device logs
+            - Documentation or website issues - these do NOT need device logs
+
+            If this is a device/firmware bug, request device logs and explain how to get them:
+
+            Web Flasher logs:
+            - Go to https://flasher.meshtastic.org
+            - Connect the device via USB and click Connect
+            - Open the device console/log output, reproduce the problem, then copy/download and attach/paste the logs
+
+            Meshtastic CLI logs:
+            - Run: meshtastic --port <serial-port> --noproto
+            - Reproduce the problem, then copy/paste the terminal output
+
+            Also request key context if missing: device model/variant, firmware version, region, steps to reproduce, expected vs actual.
+
+            Respond ONLY with valid JSON (no markdown, no code fences):
+            {"complete": true, "comment": "", "label": "none"}
+            OR
+            {"complete": false, "comment": "Your helpful comment", "label": "needs-logs"}
+
+            Use "needs-logs" ONLY if this is a device/firmware bug AND no logs are attached.
+            Use "needs-info" if basic info like firmware version or steps to reproduce are missing.
+            Use "none" if the issue is complete, is a feature request, or is a build/CI/packaging issue.
+
+            Title: ${{ github.event.issue.title }}
+            Body: ${{ github.event.issue.body }}
+          system-prompt: You are a helpful assistant that triages GitHub issues. Be conservative with labels. Only request device logs for actual device/firmware bugs, not for build/release/CI issues.
+          model: openai/gpt-4o-mini
+
+      - name: Process analysis result
+        if: (steps.quality.outputs.response == 'ok' || steps.quality.outputs.response == '') && steps.check-skip.outputs.should_skip != 'true' && steps.analysis.outputs.response != ''
+        uses: actions/github-script@v9
+        id: process
+        env:
+          AI_RESPONSE: ${{ steps.analysis.outputs.response }}
+        with:
+          script: |
+            let raw = (process.env.AI_RESPONSE || '').trim();
+
+            // Strip markdown code fences if present
+            raw = raw.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '').trim();
+
+            let complete = true;
+            let comment = '';
+            let label = 'none';
+
+            try {
+              const parsed = JSON.parse(raw);
+              complete = !!parsed.complete;
+              comment = (parsed.comment ?? '').toString().trim();
+              label = (parsed.label ?? 'none').toString().trim().toLowerCase();
+            } catch {
+              // If JSON parse fails, log warning and don't comment (avoid posting raw JSON)
+              console.log('Failed to parse AI response as JSON:', raw);
+              complete = true;
+              comment = '';
+              label = 'none';
+            }
+
+            // Validate label
+            const allowedLabels = new Set(['needs-logs', 'needs-info', 'none']);
+            if (!allowedLabels.has(label)) label = 'none';
+
+            // Only comment if we have a valid parsed comment (not raw JSON)
+            const shouldComment = !complete && comment.length > 0 && !comment.startsWith('{');
+            core.setOutput('should_comment', shouldComment ? 'true' : 'false');
+            core.setOutput('comment_body', comment);
+            core.setOutput('label', label);
+
+      - name: Apply triage label
+        if: steps.process.outputs.label != '' && steps.process.outputs.label != 'none'
+        uses: actions/github-script@v9
+        env:
+          LABEL_NAME: ${{ steps.process.outputs.label }}
+        with:
+          script: |
+            const label = process.env.LABEL_NAME;
+            const labelMeta = {
+              'needs-logs': { color: 'cfd3d7', description: 'Device logs requested for triage' },
+              'needs-info': { color: 'f9d0c4', description: 'More information requested for triage' },
+            };
+            const meta = labelMeta[label];
+            if (!meta) return;
+
+            // Ensure label exists
+            try {
+              await github.rest.issues.getLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label });
+            } catch (e) {
+              if (e.status !== 404) throw e;
+              await github.rest.issues.createLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label, color: meta.color, description: meta.description });
+            }
+
+            // Apply label
+            await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.payload.issue.number, labels: [label] });
+
+      - name: Comment on issue
+        if: steps.process.outputs.should_comment == 'true'
+        uses: actions/github-script@v9
+        env:
+          COMMENT_BODY: ${{ steps.process.outputs.comment_body }}
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.issue.number,
+              body: process.env.COMMENT_BODY
+            });

.github/workflows/models_pr_triage.yml

@@ -0,0 +1,139 @@
+name: PR Triage (Models)
+
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  pull-requests: write
+  issues: write
+  models: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  triage:
+    if: ${{ github.repository == 'meshtastic/firmware' && github.event.pull_request.user.type != 'Bot' }}
+    runs-on: ubuntu-latest
+    steps:
+      # ─────────────────────────────────────────────────────────────────────────
+      # Step 1: Check if PR already has automation/type labels (skip if so)
+      # ─────────────────────────────────────────────────────────────────────────
+      - name: Check existing labels
+        uses: actions/github-script@v9
+        id: check-labels
+        with:
+          script: |
+            const skipLabels = new Set(['automation']);
+            const typeLabels = new Set(['bugfix', 'hardware-support', 'enhancement', 'dependencies', 'submodules', 'github_actions', 'trunk', 'cleanup']);
+            const prLabels = context.payload.pull_request.labels.map(l => l.name);
+
+            const shouldSkipAll = prLabels.some(l => skipLabels.has(l));
+            const hasTypeLabel = prLabels.some(l => typeLabels.has(l));
+
+            core.setOutput('skip_all', shouldSkipAll ? 'true' : 'false');
+            core.setOutput('has_type_label', hasTypeLabel ? 'true' : 'false');
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Step 2: Quality check (spam/AI-slop detection)
+      # ─────────────────────────────────────────────────────────────────────────
+      - name: Detect spam or low-quality content
+        if: steps.check-labels.outputs.skip_all != 'true'
+        uses: actions/ai-inference@v2
+        id: quality
+        continue-on-error: true
+        with:
+          max-tokens: 20
+          prompt: |
+            Is this GitHub pull request spam, AI-generated slop, or low quality?
+
+            Title: ${{ github.event.pull_request.title }}
+            Body: ${{ github.event.pull_request.body }}
+
+            Respond with exactly one of: spam, ai-generated, needs-review, ok
+          system-prompt: You detect spam and low-quality contributions. Be conservative - only flag obvious spam or AI slop.
+          model: openai/gpt-4o-mini
+
+      - name: Apply quality label if needed
+        if: steps.check-labels.outputs.skip_all != 'true' && steps.quality.outputs.response != '' && steps.quality.outputs.response != 'ok'
+        uses: actions/github-script@v9
+        id: quality-label
+        env:
+          QUALITY_LABEL: ${{ steps.quality.outputs.response }}
+        with:
+          script: |
+            const label = (process.env.QUALITY_LABEL || '').trim().toLowerCase();
+            const labelMeta = {
+              'spam': { color: 'd73a4a', description: 'Possible spam' },
+              'ai-generated': { color: 'fbca04', description: 'Possible AI-generated low-quality content' },
+              'needs-review': { color: 'f9d0c4', description: 'Needs human review' },
+            };
+            const meta = labelMeta[label];
+            if (!meta) return;
+
+            // Ensure label exists
+            try {
+              await github.rest.issues.getLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label });
+            } catch (e) {
+              if (e.status !== 404) throw e;
+              await github.rest.issues.createLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label, color: meta.color, description: meta.description });
+            }
+
+            // Apply label
+            await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.payload.pull_request.number, labels: [label] });
+
+            core.setOutput('is_spam', 'true');
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Step 3: Auto-label PR type (bugfix/hardware-support/enhancement)
+      # Only skip for spam/ai-generated; still classify needs-review PRs
+      # ─────────────────────────────────────────────────────────────────────────
+      - name: Classify PR for labeling
+        if: steps.check-labels.outputs.skip_all != 'true' && steps.check-labels.outputs.has_type_label != 'true' && steps.quality.outputs.response != 'spam' && steps.quality.outputs.response != 'ai-generated'
+        uses: actions/ai-inference@v2
+        id: classify
+        continue-on-error: true
+        with:
+          max-tokens: 30
+          prompt: |
+            Classify this pull request into exactly one category.
+
+            Return exactly one of: bugfix, hardware-support, enhancement
+
+            Use bugfix if it fixes a bug, crash, or incorrect behavior.
+            Use hardware-support if it adds or improves support for a specific hardware device/variant.
+            Use enhancement if it adds a new feature, improves performance, or refactors code.
+
+            Title: ${{ github.event.pull_request.title }}
+            Body: ${{ github.event.pull_request.body }}
+          system-prompt: You classify pull requests into categories. Be conservative and pick the most appropriate single label.
+          model: openai/gpt-4o-mini
+
+      - name: Apply type label
+        if: steps.check-labels.outputs.skip_all != 'true' && steps.check-labels.outputs.has_type_label != 'true' && steps.classify.outputs.response != ''
+        uses: actions/github-script@v9
+        env:
+          TYPE_LABEL: ${{ steps.classify.outputs.response }}
+        with:
+          script: |
+            const label = (process.env.TYPE_LABEL || '').trim().toLowerCase();
+            const labelMeta = {
+              'bugfix': { color: 'd73a4a', description: 'Bug fix' },
+              'hardware-support': { color: '0e8a16', description: 'Hardware support addition or improvement' },
+              'enhancement': { color: 'a2eeef', description: 'New feature or enhancement' },
+            };
+            const meta = labelMeta[label];
+            if (!meta) return;
+
+            // Ensure label exists
+            try {
+              await github.rest.issues.getLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label });
+            } catch (e) {
+              if (e.status !== 404) throw e;
+              await github.rest.issues.createLabel({ owner: context.repo.owner, repo: context.repo.repo, name: label, color: meta.color, description: meta.description });
+            }
+
+            // Apply label
+            await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.payload.pull_request.number, labels: [label] });

.github/workflows/nightly.yml

@@ -14,10 +14,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - name: Trunk Check
-        uses: trunk-io/trunk-action@v2.0.0
+        uses: trunk-io/trunk-action@v1
         with:
           trunk-token: ${{ secrets.TRUNK_TOKEN }}
 
@@ -31,9 +31,9 @@ jobs:
       pull-requests: write # For trunk to create PRs
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - name: Trunk Upgrade
-        uses: trunk-io/trunk-action/upgrade@v2.0.0
+        uses: trunk-io/trunk-action/upgrade@v1
         with:
-          base: develop
+          base: master

.github/workflows/package_obs.yml

@@ -33,7 +33,7 @@ jobs:
     needs: build-debian-src
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
           path: meshtasticd

.github/workflows/package_pio_deps.yml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 

.github/workflows/package_ppa.yml

@@ -34,7 +34,7 @@ jobs:
     needs: build-debian-src
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: recursive
           path: meshtasticd

.github/workflows/package_winget.yml

@@ -1,62 +0,0 @@
-name: Validate winget manifest
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  validate-winget:
-    runs-on: windows-2025
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-        with:
-          persist-credentials: false
-
-      - name: Resolve the newest release and download its MSI
-        id: release
-        shell: pwsh
-        run: |
-          $tag = gh release list --limit 1 --json tagName --jq '.[0].tagName'
-          if (-not $tag) { throw 'No releases found.' }
-          New-Item -ItemType Directory -Force -Path release/download | Out-Null
-          gh release download $tag --pattern '*.msi' --dir release/download
-          $msis = @(Get-ChildItem release/download/*.msi)
-          if ($msis.Count -eq 0) { throw "Release $tag carries no MSI asset." }
-          if ($msis.Count -gt 1) { throw "Release $tag carries $($msis.Count) MSIs; this validates one architecture." }
-          $parsed = [regex]::Match($msis[0].Name, '^meshtasticd-([0-9][0-9A-Za-z.\-]*)-(x64|arm64)\.msi$')
-          if (-not $parsed.Success) { throw "Cannot parse version and architecture out of $($msis[0].Name)." }
-          "tag=$tag", "version=$($parsed.Groups[1].Value)", "arch=$($parsed.Groups[2].Value)", "msi=$($msis[0].FullName)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Generate manifests for the published MSI
-        shell: pwsh
-        run: ./bin/build-winget-package.ps1 -MsiPath $env:MSI_PATH -Version $env:PKG_VERSION -Architecture $env:PKG_ARCH -ReleaseTag $env:RELEASE_TAG -Validate
-        env:
-          MSI_PATH: ${{ steps.release.outputs.msi }}
-          PKG_VERSION: ${{ steps.release.outputs.version }}
-          PKG_ARCH: ${{ steps.release.outputs.arch }}
-          RELEASE_TAG: ${{ steps.release.outputs.tag }}
-
-      - name: Verify the manifest URL resolves to the published asset
-        shell: pwsh
-        run: |
-          $installer = Get-ChildItem release/winget/manifests -Recurse -Filter '*.installer.yaml' | Select-Object -First 1
-          $url = (Select-String -Path $installer.FullName -Pattern 'InstallerUrl:\s*(\S+)').Matches[0].Groups[1].Value
-          $expected = (Select-String -Path $installer.FullName -Pattern 'InstallerSha256:\s*(\S+)').Matches[0].Groups[1].Value
-          Invoke-WebRequest -Uri $url -OutFile fetched.msi
-          $actual = (Get-FileHash fetched.msi -Algorithm SHA256).Hash
-          if ($actual -ne $expected) {
-            throw "InstallerUrl $url hashes to $actual, manifest claims $expected"
-          }
-          "URL and hash agree: $url"
-
-      - name: Upload the manifests as an artifact
-        uses: actions/upload-artifact@v7
-        with:
-          name: winget-manifests-${{ steps.release.outputs.version }}
-          overwrite: true
-          path: release/winget/manifests/

.github/workflows/pr_tests.yml

@@ -4,11 +4,10 @@ name: Tests
 on:
   workflow_dispatch:
     inputs:
-      # trunk-ignore(checkov/CKV_GHA_7): the reason input is a free-text run label, never fed into the build
       reason:
-        description: Reason for manual test run
+        description: "Reason for manual test run"
         required: false
-        default: Manual test execution
+        default: "Manual test execution"
 
 concurrency:
   group: tests-${{ github.head_ref || github.run_id }}
@@ -22,7 +21,7 @@ permissions:
 
 jobs:
   native-tests:
-    name: 🧪 Native Tests
+    name: "🧪 Native Tests"
     if: github.repository == 'meshtastic/firmware'
     uses: ./.github/workflows/test_native.yml
     permissions:
@@ -31,7 +30,7 @@ jobs:
       checks: write
 
   test-summary:
-    name: 📊 Test Results
+    name: "📊 Test Results"
     runs-on: ubuntu-latest
     needs: [native-tests]
     if: always()
@@ -41,7 +40,7 @@ jobs:
       checks: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
         with:
           submodules: recursive
 

.github/workflows/release_channels.yml

@@ -23,8 +23,8 @@ jobs:
         series:
           - jammy # 22.04 LTS
           - noble # 24.04 LTS
+          - questing # 25.10
           - resolute # 26.04 LTS
-          - stonking # 26.10
     uses: ./.github/workflows/package_ppa.yml
     with:
       ppa_repo: |-
@@ -91,7 +91,7 @@ jobs:
         shell: bash
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           # Always use master branch for version bumps
           ref: master

.github/workflows/sec_sast_semgrep_cron.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       # step 1
       - name: clone application source code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       # step 2
       - name: full scan

.github/workflows/sec_sast_semgrep_pull.yml

@@ -13,7 +13,7 @@ jobs:
     steps:
       # step 1
       - name: clone application source code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/stale_bot.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Stale PR+Issues
-        uses: actions/stale@v11
+        uses: actions/stale@v10.2.0
         with:
           days-before-stale: 45
           stale-issue-message: This issue has not had any comment or update in the last month. If it is still relevant, please post update comments. If no comments are made, this issue will be closed automagically in 7 days.

.github/workflows/test_native.yml

@@ -2,154 +2,19 @@ name: Run Tests on Native platform
 
 on:
   workflow_call:
-    inputs:
-      suite_order_seed:
-        description: >-
-          Seed for shuffling the test-area order. Empty (the default) means: fixed declared order on
-          pull_request, so a contributor's PR never turns red because of an order they did not
-          choose; commit-SHA-derived elsewhere. Set a number to force that exact order anywhere -
-          that is how you replay a shuffled failure.
-        type: string
-        required: false
-        default: ""
   workflow_dispatch:
 
 permissions: {}
 
 env:
-  # Only pushes to the default branch (develop) populate the cache; PR / merge_group runs
-  # restore it but never save, so they stop filling up the repo's Actions cache storage.
-  SAVE_CACHE: ${{ github.event_name == 'push' && github.ref_name == github.event.repository.default_branch }}
   LCOV_CAPTURE_FLAGS: --quiet --capture --include "${PWD}/src/*" --exclude '*/src/mesh/generated/*' --directory .pio/build/coverage/src --base-directory "${PWD}"
 
 jobs:
-  # Tripwire against the native suite set shrinking by accident. `platformio test` discovers and
-  # runs whatever test_* directories exist, and bin/run-tests.sh derives its expected count from
-  # the same walk - so a suite directory lost in a bad rebase or an overzealous cleanup just means
-  # fewer suites run, and every remaining check stays green. Compare the test_* directory list
-  # against the PR's merge base and fail when a suite vanished without the PR saying so: a removed
-  # suite's name must appear in the PR title, the PR body, or a commit message in the PR's range.
-  # A deliberate removal satisfies that by stating what it removes; an accidental loss cannot.
-  # Only pull_request runs have a base to compare against (and PRs are where accidents arrive);
-  # every other event skips. No job depends on this one: a skipped job would skip its dependents,
-  # and the expensive jobs should not wait on a full-history clone.
-  suite-shrinkage-check:
-    name: Native Suite Shrinkage
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-slim
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-          # Full history: the merge base must be computed, not guessed from a possibly stale
-          # event payload, and the acknowledgment scan reads every commit message in the range.
-          fetch-depth: 0
-
-      - name: Fail if a test_* suite vanished unacknowledged
-        shell: bash
-        # PR title/body are attacker-controlled text; they reach the script through env: only,
-        # never spliced into the shell source (same rule as the suite-order seed below).
-        env:
-          BASE_REF: ${{ github.base_ref }}
-          PR_TITLE: ${{ github.event.pull_request.title }}
-          PR_BODY: ${{ github.event.pull_request.body }}
-        run: |
-          set -euo pipefail
-          git fetch --quiet origin "$BASE_REF"
-          base=$(git merge-base FETCH_HEAD HEAD)
-          # Same canonical set every other consumer derives: directories named test_* directly
-          # under test/, read from the git trees so the comparison is exact at both endpoints.
-          list_suites() { git ls-tree -d --name-only "$1" test/ | sed 's#^test/##' | grep '^test_' | sort; }
-          removed=$(comm -23 <(list_suites "$base") <(list_suites HEAD))
-          if [[ -z $removed ]]; then
-            echo "No suite removed: $(list_suites HEAD | wc -l) test_* directories, none lost since merge base ${base:0:8}."
-            exit 0
-          fi
-          messages=$(git log --format=%B "$base..HEAD")
-          fail=0
-          while IFS= read -r suite; do
-            if printf '%s\n%s\n%s\n' "$PR_TITLE" "$PR_BODY" "$messages" | grep -qF "$suite"; then
-              echo "Removed suite $suite is named in the PR title/body or a commit message - acknowledged."
-            else
-              echo "::error title=Native suite vanished::test/$suite exists on the merge base but is gone from this PR, and nothing in the PR title, body, or commit messages mentions it. If the removal is deliberate, name $suite in the PR description or a commit message; if not, restore the directory - platformio test would silently run without it."
-              fail=1
-            fi
-          done <<<"$removed"
-          exit $fail
-
-  # Reject naive deadline comparisons against the 32-bit uptime clocks. `millis() > deadline` and
-  # `deadline < millis()` invert while the deadline sits on the far side of the 32-bit wrap: the
-  # action fires immediately, or blocks for about the interval it should have waited. The correct
-  # forms are
-  # Throttle::isWithinTimespanMs / hasElapsed (elapsed since a stored event) and
-  # Throttle::deadlinePassed (an absolute deadline). See .github/copilot-instructions.md.
-  millis-deadline-check:
-    # Name is load-bearing: upstream branch protection matches the check by name. Widen the guard,
-    # not this string.
-    name: Naive millis() Deadline Compare
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: Reject 32-bit uptime clocks used directly in a deadline comparison
-        shell: bash
-        run: |
-          set -euo pipefail
-          allowlist=".github/millis-deadline-allowlist.txt"
-
-          # Flag millis() or its Time::getMillis() wrapper directly adjacent to a comparison
-          # operator, in either order. The correct idioms subtract first, so they are not matched.
-          #
-          # Line comments are stripped before matching, so prose may name the broken idiom (this
-          # guard's own documentation does). Block comments are not stripped; keep `millis() >` out
-          # of /* */ blocks. mawk-compatible - ubuntu-latest has no gawk.
-          find src -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.hpp' -o -name '*.ino' \) \
-               ! -path 'src/mesh/generated/*' -print0 |
-            xargs -0 awk '
-              {
-                line = $0
-                sub(/\/\/.*/, "", line)
-                if (line ~ /((millis|getMillis)\(\)[ \t]*[<>]=?)|([<>]=?[ \t]*(millis|getMillis)\(\))/) {
-                  code = line
-                  sub(/^[ \t]+/, "", code); sub(/[ \t]+$/, "", code)
-                  printf "%s\t%s\t%s\n", FILENAME, FNR, code
-                }
-              }' > /tmp/millis-hits.tsv
-
-          # Allowlisted entries are keyed on file + exact source text, deliberately without a line
-          # number, so unrelated edits above them do not invalidate the entry.
-          : > /tmp/millis-allowed.tsv
-          if [[ -f $allowlist ]]; then
-            grep -vE '^[[:space:]]*(#|$)' "$allowlist" > /tmp/millis-allowed.tsv || true
-          fi
-
-          violations=0
-          while IFS=$'\t' read -r file line code; do
-            [[ -n ${file:-} ]] || continue
-            if grep -qxF "$(printf '%s\t%s' "$file" "$code")" /tmp/millis-allowed.tsv; then
-              continue
-            fi
-            echo "$file:$line: $code"
-            violations=$((violations + 1))
-          done < /tmp/millis-hits.tsv
-
-          if [[ $violations -gt 0 ]]; then
-            echo "::error title=Naive uptime deadline compare::$violations line(s) compare a 32-bit uptime clock directly, which inverts while the deadline is on the far side of the 32-bit wrap - the action fires immediately, or blocks for about the interval it should have waited. Use Throttle::deadlinePassed(deadline) for a stored absolute deadline, or Throttle::hasElapsed(lastEvent, intervalMs) for an interval. If a match genuinely is not a deadline test (an uptime threshold, say), add it to $allowlist with a reason."
-            exit 1
-          fi
-          echo "No naive 32-bit uptime deadline comparisons in src/ (allowlist: $(wc -l < /tmp/millis-allowed.tsv) entr(y/ies))."
-
   simulator-tests:
     name: Native Simulator Tests
-    runs-on: ubuntu-24.04-arm
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@v6
         with:
           submodules: recursive
 
@@ -160,26 +25,10 @@ jobs:
       - name: Install simulator dependencies
         run: pip install -U dotmap
 
-      - name: Restore PlatformIO cache
-        id: pio-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-simulator-tests-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-          restore-keys: |
-            pio-simulator-tests-
-
       # We now run integration test before other build steps (to quickly see runtime failures)
       - name: Build for native/coverage
         run: platformio run -e coverage
 
-      - name: Save PlatformIO cache
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-simulator-tests-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-
       - name: Capture initial coverage information
         shell: bash
         run: |
@@ -187,49 +36,14 @@ jobs:
           lcov ${{ env.LCOV_CAPTURE_FLAGS }} --initial --output-file coverage_base.info
           sed -i -e "s#${PWD}#.#" coverage_base.info # Make paths relative.
 
-      - name: Config check tests
-        # Drives the same binary against test/fixtures/portduino-config: asserts that
-        # `--check` reports each planted fault, and that a normal run still refuses the
-        # configs it should. Runs before the simulator test because it is seconds long
-        # and a failure here explains a lot of downstream weirdness.
-        timeout-minutes: 5
-        run: ./bin/test-config-check.sh .pio/build/coverage/meshtasticd
-
-      - name: Shared-state checker self-test
-        # Fixtures that write nothing / exactly what they declare / something undeclared /
-        # a declared write they never make, asserting CLEAN / CLEAN / DIRTY / MISSING. A
-        # checker that has silently stopped matching looks identical to a clean codebase.
-        timeout-minutes: 5
-        run: ./bin/test-state-check.sh
-
       - name: Integration test
-        # Cap the whole step: if the simulator ever fails to exit (e.g. the
-        # exit_simulator admin path regresses again) the job must fail fast,
-        # not run to GitHub's 6-hour limit.
-        timeout-minutes: 5
         run: |
           .pio/build/coverage/meshtasticd -s &
           PID=$!
-          trap 'kill "$PID" 2>/dev/null || true' EXIT
           timeout 20 bash -c "until ls -al /proc/$PID/fd | grep socket; do sleep 1; done"
           echo "Simulator started, launching python test..."
           python3 -c 'from meshtastic.test import testSimulator; testSimulator()'
-          # The Python harness sends exit_simulator and exits; the simulator is
-          # expected to terminate on its own. Give it a moment, then verify.
-          # If it is still alive the exit handshake is broken - fail loudly and
-          # do NOT fall through to `wait`, which would otherwise block until the
-          # job's hard timeout.
-          for i in $(seq 1 10); do
-            kill -0 "$PID" 2>/dev/null || break
-            sleep 1
-          done
-          if kill -0 "$PID" 2>/dev/null; then
-            echo "::error title=Simulator did not exit::meshtasticd ignored exit_simulator and is still running after the integration test. The exit_simulator admin path is broken (see AdminModule::handleReceivedProtobuf, ARCH_PORTDUINO bypass). Killing it to avoid a 6-hour CI overrun."
-            kill -9 "$PID" 2>/dev/null || true
-            wait "$PID" 2>/dev/null || true
-            exit 1
-          fi
-          wait "$PID" 2>/dev/null || true
+          wait
 
       - name: Capture coverage information
         if: always() # run this step even if previous step failed
@@ -252,9 +66,9 @@ jobs:
 
   platformio-tests:
     name: Native PlatformIO Tests
-    runs-on: ubuntu-24.04-arm
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@v6
         with:
           submodules: recursive
 
@@ -271,195 +85,8 @@ jobs:
       - name: Disable BUILD_EPOCH
         run: sed -i 's/-DBUILD_EPOCH=$UNIX_TIME/#-DBUILD_EPOCH=$UNIX_TIME/' platformio.ini
 
-      - name: Restore PlatformIO cache
-        id: pio-cache
-        uses: actions/cache/restore@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-coverage-tests-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-          restore-keys: |
-            pio-coverage-tests-
-
-      - name: Warm the shared test build
-        # Compiles src + every test program once so no single area absorbs the whole src build in
-        # its reported duration; gcov then accumulates counts into this shared
-        # .pio/build/coverage/src as the areas run. NOT a substitute for building in the run step:
-        # PlatformIO links every test program to the one .pio/build/coverage/meshtasticd path, so a
-        # --without-building run executes whichever suite was linked last under every suite's name.
-        run: platformio test -e coverage --without-testing
-
-      - name: Save PlatformIO cache
-        if: env.SAVE_CACHE == 'true' && steps.pio-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v6
-        with:
-          path: ~/.platformio/.cache
-          key: pio-coverage-tests-${{ hashFiles('platformio.ini', 'variants/native/portduino.ini', 'variants/native/portduino/platformio.ini') }}
-
-      - name: Run tests one area at a time
-        shell: bash
-        # Both values reach the script through env: rather than ${{ }} inside run:, so nothing from
-        # the event payload is ever spliced into the shell text.
-        env:
-          SUITE_ORDER_SEED: ${{ inputs.suite_order_seed }}
-          EVENT_NAME: ${{ github.event_name }}
-        run: |
-          set -uo pipefail
-          # One runner, no matrix, no concurrency. Group the test_* suites by area and run each
-          # area sequentially, reusing the single build above (--without-building). Each area gets
-          # its own JUnit report and its own collapsible log, so a failure lands in a small named
-          # section instead of being buried past the log limit. Sequential runs share one build
-          # dir, so gcov coverage accumulates and the single capture in the next step has the union.
-
-          # Ordered area rules "name:ERE"; first match wins. Anything unmatched falls to "misc", so
-          # a newly added suite always runs even before it is placed. Add a suite to an area by
-          # extending that area's regex; add a new area by inserting a rule line.
-          area_rules=(
-            "admin:^test_(admin|pki)_"
-            "crypto:^test_(crypto|packet_signing)$"
-            "routing:^test_(mesh|nexthop|traceroute|hop|traffic|nodedb|warm)_"
-            "position:^test_position_"
-            "fuzz:^test_fuzz_"
-            "packets:^test_(packet|transmit|meshpacket)_"
-            "io:^test_(serial|stream|xmodem|http|mqtt)"
-          )
-
-          mapfile -t suites < <(find test -maxdepth 1 -type d -name 'test_*' -printf '%f\n' | sort)
-          declare -A group
-          for s in "${suites[@]}"; do
-            a="misc"
-            for rule in "${area_rules[@]}"; do
-              if [[ "$s" =~ ${rule#*:} ]]; then a="${rule%%:*}"; break; fi
-            done
-            group[$a]="${group[$a]:-} -f $s"
-          done
-
-          run_order=()
-          for rule in "${area_rules[@]}"; do run_order+=("${rule%%:*}"); done
-          run_order+=("misc")
-
-          # Area order. The rule order above is an accident of how the areas were written, and
-          # running it fixed forever means order dependence between areas is never observed - but
-          # randomising it on a contributor's PR would turn their run red for an order they did not
-          # choose, which is how a randomisation gets reverted instead of the coupling fixed.
-          #
-          # So: pull_request keeps the fixed declared order. Everywhere else (push, schedule) the
-          # order is shuffled, seeded from the commit SHA - deterministic per commit, replayable,
-          # attributable, and it never blocks someone else's PR. An explicit seed input overrides
-          # both, which is how you replay a specific failing order anywhere.
-          #
-          # Intra-area order stays PlatformIO's: filters select suites, they do not order them
-          # (list_test_names() walks test/ with os.walk()), so controlling it needs one invocation
-          # per suite. bin/run-tests.sh --shuffle does exactly that locally.
-          seed_input="${SUITE_ORDER_SEED:-}"
-          if [ -n "$seed_input" ]; then
-            seed="$seed_input"
-            echo "area order: shuffled with explicitly supplied seed $seed"
-          elif [ "${EVENT_NAME:-}" = "pull_request" ]; then
-            seed=""
-            echo "area order: fixed declared order (pull_request) - ${run_order[*]}"
-            echo "  to exercise a different order, re-run this workflow with a suite_order_seed input"
-          else
-            seed=$((16#${GITHUB_SHA:0:8}))
-            echo "area order: shuffled with seed $seed (from ${GITHUB_SHA:0:8})"
-          fi
-
-          if [ -n "$seed" ]; then
-            # Same shuffle_suites() bin/run-tests.sh uses, so the replay hint below is true by
-            # construction rather than by two copies happening to agree.
-            source bin/lib/shuffle.sh
-            mapfile -t run_order < <(shuffle_suites "$seed" "${run_order[@]}")
-            echo "area order: ${run_order[*]}"
-            echo "  replay locally: ./bin/run-tests.sh --shuffle --seed $seed"
-          fi
-
-          fail=0
-          for a in "${run_order[@]}"; do
-            [ -n "${group[$a]:-}" ] || continue
-            echo "::group::area $a (${group[$a]# })"
-            # Capture platformio's real exit status (not grep's) via a log file, then show the log
-            # with the noisy per-variant SKIPPED rows filtered out.
-            if ! platformio test -e coverage -v ${group[$a]# } \
-                 --junit-output-path "testreport-$a.xml" > "area-$a.log" 2>&1; then
-              fail=1
-              echo "::error::area $a had test failures"
-            fi
-            # Suites outside this area are reported SKIPPED by design (PlatformIO lists every suite
-            # in the env and marks the unselected ones finished), so those rows are noise here. The
-            # attribution check below is what catches a suite that was selected and did not run.
-            grep -v "[[:space:]]SKIPPED$" "area-$a.log" || true
-            # Per area, so a mismatch names the area it happened in rather than the whole run.
-            if ! ./bin/check-test-attribution.py --label "area $a" \
-                 --expect "${group[$a]# }" "testreport-$a.xml"; then
-              fail=1
-              echo "::error::area $a ran suites that did not match their own test binaries"
-            fi
-            echo "::endgroup::"
-          done
-          exit $fail
-
-      - name: Merge per-area reports into testreport.xml
-        # Preserve the single-file JUnit contract that downstream consumers rely on
-        # (pr_tests.yml's summary and generate-reports' Test Report both read testreport.xml).
-        # The per-area split is only for readable logs; the report stays consolidated.
-        if: always() # run even when a chunk failed, so the report captures the failures
-        shell: bash
-        run: |
-          python3 - <<'PY'
-          import glob, xml.etree.ElementTree as ET
-          out = ET.Element('testsuites')
-          for f in sorted(glob.glob('testreport-*.xml')):
-              try:
-                  root = ET.parse(f).getroot()
-              except ET.ParseError:
-                  continue
-              # PlatformIO writes a <testsuites> root; fold in a bare <testsuite> too, just in case.
-              out.extend(root.findall('testsuite') if root.tag == 'testsuites' else [root])
-          ET.ElementTree(out).write('testreport.xml', encoding='utf-8', xml_declaration=True)
-          PY
-
-      - name: Verify every suite ran its own tests
-        # Whole-run gate over the merged report: every test_* directory must appear with at least
-        # one test case, and every case must come from the suite that reported it. The per-area
-        # check above cannot see an area that never executed - this can.
-        if: always() # a suite going missing is the finding; do not hide it behind an earlier failure
-        shell: bash
-        run: |
-          set -euo pipefail
-          mapfile -t suites < <(find test -maxdepth 1 -type d -name 'test_*' -printf '%f\n' | sort)
-          ./bin/check-test-attribution.py --label "coverage (all areas)" \
-            --expect "${suites[*]}" testreport.xml
-
-      - name: Capture coverage information
-        if: always() # run this step even if previous step failed
-        run: |
-          sudo apt-get install -y lcov
-          lcov ${{ env.LCOV_CAPTURE_FLAGS }} --test-name tests --output-file coverage_tests.info
-          sed -i -e "s#${PWD}#.#" coverage_tests.info # Make paths relative.
-
-      - name: Attribution canary
-        # Guards the guard above: runs two suites the broken way (--without-building, so PlatformIO
-        # does not relink and both execute the same leftover binary) and requires the checker to
-        # catch it. Fails if the checker regressed, or if the reproduction stops reproducing - in
-        # which case the reason both harnesses stopped passing that flag no longer holds.
-        #
-        # Lives in this job, not simulator-tests: it relinks $BUILD_DIR/$PROGNAME, and there that
-        # replaced the daemon binary with a test suite, so the integration test waited for a socket
-        # a test binary never opens. Here the binary is already per-suite and nothing later needs it.
-        timeout-minutes: 15
-        run: ./bin/test-attribution-canary.sh -e coverage
-
-      - name: Event channel policy tests
-        run: platformio test -e coverage-event-policy -v --junit-output-path event-policy-testreport.xml
-
-      - name: Verify the event-policy suites ran their own tests
-        # Expected set read through PlatformIO's own config parser, so it cannot drift from the
-        # env's test_filter the way a second hand-maintained list would.
-        run: |
-          set -euo pipefail
-          expect=$(python3 -c "from platformio.project.config import ProjectConfig; \
-            print(' '.join(ProjectConfig().get('env:coverage-event-policy', 'test_filter', [])))")
-          ./bin/check-test-attribution.py --label coverage-event-policy \
-            --expect "$expect" event-policy-testreport.xml
+      - name: PlatformIO Tests
+        run: platformio test -e coverage -v --junit-output-path testreport.xml
 
       - name: Save test results
         if: always() # run this step even if previous step failed
@@ -467,7 +94,14 @@ jobs:
         with:
           name: platformio-test-report-${{ steps.version.outputs.long }}
           overwrite: true
-          path: ./*testreport.xml
+          path: ./testreport.xml
+
+      - name: Capture coverage information
+        if: always() # run this step even if previous step failed
+        run: |
+          sudo apt-get install -y lcov
+          lcov ${{ env.LCOV_CAPTURE_FLAGS }} --test-name tests --output-file coverage_tests.info
+          sed -i -e "s#${PWD}#.#" coverage_tests.info # Make paths relative.
 
       - name: Save coverage information
         uses: actions/upload-artifact@v7
@@ -487,10 +121,9 @@ jobs:
     needs:
       - simulator-tests
       - platformio-tests
-    # Run this job even if the previous jobs failed, but skip if the workflow was cancelled.
-    if: ${{ !cancelled() }}
+    if: always()
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@v6
 
       - name: Get release version string
         run: echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
@@ -502,14 +135,6 @@ jobs:
           name: platformio-test-report-${{ steps.version.outputs.long }}
           merge-multiple: true
 
-      - name: Drop no-status testsuites from the report
-        # PlatformIO emits a self-closing <testsuite tests="0"/> row for every test_* dir
-        # crossed with every hardware variant it cannot run on the native host (~4900 rows).
-        # They carry no pass/fail/skip status and bury the suites that actually ran. Strip
-        # them so the Test Report lists only suites with a real status. Only the copy the
-        # reporter renders is trimmed; the uploaded artifact keeps the full XML.
-        run: sed -i -E 's#<testsuite [^>]*tests="0"[^>]*/>##g' testreport.xml
-
       - name: Test Report
         uses: dorny/test-reporter@v3.0.0
         with:
@@ -525,17 +150,9 @@ jobs:
           merge-multiple: true
 
       - name: Generate Code Coverage Report
-        # Merge every tracefile the jobs produced: coverage_base.info (zeroed baseline),
-        # coverage_integration.info, and one coverage_tests_<chunk>.info per chunk. lcov
-        # sums hit counts across them, so the merged report is the union of all chunks -
-        # identical to running the whole suite in one job.
         run: |
           sudo apt-get install -y lcov
-          args=()
-          for f in code-coverage-report/coverage_*.info; do
-            args+=(--add-tracefile "$f")
-          done
-          lcov --quiet "${args[@]}" --output-file code-coverage-report/coverage_src.info
+          lcov --quiet --add-tracefile code-coverage-report/coverage_base.info --add-tracefile code-coverage-report/coverage_integration.info --add-tracefile code-coverage-report/coverage_tests.info --output-file code-coverage-report/coverage_src.info
           genhtml --quiet --legend --prefix "${PWD}" code-coverage-report/coverage_src.info --output-directory code-coverage-report
 
       - name: Save Code Coverage Report

.github/workflows/tests.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: test-runner
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       # - uses: actions/setup-python@v6
       #   with:
@@ -47,7 +47,7 @@ jobs:
           pio upgrade
 
       - name: Setup Node
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@v6
         with:
           node-version: 24
 

.github/workflows/trunk_annotate_pr.yml

@@ -0,0 +1,26 @@
+name: Annotate PR with trunk issues
+# See: https://github.com/trunk-io/trunk-action/blob/v1/readme.md#getting-inline-annotations-for-fork-prs
+
+on:
+  workflow_run:
+    workflows: [Pull Request] # Name from `trunk_check.yml`
+    types: [completed]
+
+permissions: read-all
+
+jobs:
+  trunk_check:
+    name: Trunk Code Quality Annotate
+    runs-on: ubuntu-24.04
+    permissions:
+      checks: write # For trunk to post annotations
+      contents: read # For repo checkout
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Trunk Check
+        uses: trunk-io/trunk-action@v1
+        with:
+          post-annotations: true

.github/workflows/trunk_check.yml

@@ -11,13 +11,14 @@ jobs:
     name: Trunk Check Runner
     runs-on: ubuntu-24.04
     permissions:
+      checks: write # For trunk to post annotations
       contents: read # For repo checkout
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - name: Trunk Check
-        uses: trunk-io/trunk-action@v2.0.0
+        uses: trunk-io/trunk-action@v1
         with:
-          cache: false
+          save-annotations: true

.github/workflows/update_protobufs.yml

@@ -1,74 +1,30 @@
 name: Update protobufs and regenerate classes
-on:
-  workflow_dispatch:
-    inputs:
-      protobufs_branch:
-        description: Branch of meshtastic/protobufs to generate from
-        required: true
-        type: choice
-        default: same-as-this-branch
-        options:
-          - same-as-this-branch
-          - master
-          - develop
+on: workflow_dispatch
 
 permissions: read-all
 
 jobs:
   update-protobufs:
     runs-on: ubuntu-latest
-    permissions:
+    permissions: # Needed for peter-evans/create-pull-request.
       contents: write
       pull-requests: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
         with:
           submodules: true
-          persist-credentials: false
-
-      - name: Resolve protobufs branch
-        id: resolve
-        env:
-          INPUT_BRANCH: ${{ inputs.protobufs_branch }}
-          TRIGGER_BRANCH: ${{ github.ref_name }}
-        run: |
-          set -euo pipefail
-          if [ "$INPUT_BRANCH" = "same-as-this-branch" ]; then
-            BRANCH="$TRIGGER_BRANCH"
-          else
-            BRANCH="$INPUT_BRANCH"
-          fi
-          case "$BRANCH" in
-            master | develop) ;;
-            *)
-              echo "::error::Refusing to generate from branch '$BRANCH'"
-              exit 1
-              ;;
-          esac
-          echo "branch=$BRANCH" >>"$GITHUB_OUTPUT"
 
       - name: Update submodule
-        working-directory: protobufs
-        env:
-          GIT_BRANCH: ${{ steps.resolve.outputs.branch }}
+        if: ${{ github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop' }}
         run: |
-          set -euo pipefail
-          git fetch --prune origin "+refs/heads/${GIT_BRANCH}:refs/remotes/origin/${GIT_BRANCH}"
-          git checkout --detach "refs/remotes/origin/${GIT_BRANCH}"
-          git rev-parse HEAD
+          git submodule update --remote protobufs
 
       - name: Download nanopb
-        env:
-          NANOPB_VERSION: 0.4.9.1
-          NANOPB_SHA256: 951a9ab2385424a4cdf245d0c84f4c88c6ccbc65a0dade4b246d50c068f24128
         run: |
-          set -euo pipefail
-          TARBALL="nanopb-${NANOPB_VERSION}-linux-x86.tar.gz"
-          wget -q "https://github.com/nanopb/nanopb/releases/download/nanopb-${NANOPB_VERSION}/${TARBALL}"
-          echo "${NANOPB_SHA256}  ${TARBALL}" | sha256sum -c -
-          tar xzf "${TARBALL}"
-          mv "nanopb-${NANOPB_VERSION}-linux-x86" nanopb-0.4.9
+          wget https://jpa.kapsi.fi/nanopb/download/nanopb-0.4.9.1-linux-x86.tar.gz
+          tar xvzf nanopb-0.4.9.1-linux-x86.tar.gz
+          mv nanopb-0.4.9.1-linux-x86 nanopb-0.4.9
 
       - name: Re-generate protocol buffers
         run: |
@@ -77,12 +33,10 @@ jobs:
       - name: Create pull request
         uses: peter-evans/create-pull-request@v8
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          branch: create-pull-request/update-protobufs-${{ github.ref_name }}-from-${{ steps.resolve.outputs.branch }}
+          branch: create-pull-request/update-protobufs
           labels: submodules
           title: Update protobufs and classes
           commit-message: Update protobufs
           add-paths: |
             protobufs
             src/mesh
-

.gitignore

@@ -1,6 +1,5 @@
 .pio
 pio
-.pio-docker
 pio.tar
 web
 web.tar
@@ -48,10 +47,6 @@ data/boot/logo.*
 managed_components/*
 arduino-lib-builder*
 dependencies.lock
-
-# JLink / RTT debug artifacts (nRF SoCs)
-flash.jlink
-rtt_*.txt
 idf_component.yml
 CMakeLists.txt
 /sdkconfig.*
@@ -61,17 +56,3 @@ CMakeLists.txt
 .python3
 .claude/scheduled_tasks.lock
 userPrefs.jsonc.mcp-session-bak
-
-# Fake-NodeDB fixture pipeline (bin/regen-fake-nodedbs.sh)
-# JSONL seeds are committed (test/fixtures/nodedb/seed_v25_*.jsonl);
-# compiled .proto outputs are ephemeral build artifacts.
-build/fixtures/
-bin/_generated/
-
-# portduino WASM build (pio run -e native-wasm) + Emscripten SDK. The artifacts land in
-# .pio/build/native-wasm/ (already ignored via .pio/); these cover the retired
-# standalone emcc build's output dirs and any in-repo emsdk checkout.
-build/wasm/
-build/wasm-obj/
-build/wasm-*.log
-.emsdk/

.gitpod.yml

@@ -0,0 +1,2 @@
+tasks:
+  - init: pip install platformio && pip install --upgrade pip

.mcp.json

@@ -1,12 +1,8 @@
 {
   "mcpServers": {
     "meshtastic": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/meshtastic/meshtastic-mcp",
-        "meshtastic-mcp"
-      ],
+      "command": "./mcp-server/.venv/bin/python",
+      "args": ["-m", "meshtastic_mcp"],
       "env": {
         "MESHTASTIC_FIRMWARE_ROOT": "."
       }

.semgrepignore

@@ -1,8 +1,2 @@
 .github/workflows/main_matrix.yml
-.github/workflows/build_windows_bin.yml
-.github/workflows/package_winget.yml
 src/mesh/compression/unishox2.cpp
-# Emscripten/WebUSB browser glue for the wasm node — not part of the firmware
-# binary or its security surface. The format-string rule false-positives on its
-# benign retry/diagnostic console logs.
-src/platform/portduino/wasm/js/

.specify/init-options.json

@@ -0,0 +1,11 @@
+{
+  "ai": "copilot",
+  "ai_commands_dir": null,
+  "ai_skills": false,
+  "branch_numbering": "sequential",
+  "here": true,
+  "offline": false,
+  "preset": null,
+  "script": "sh",
+  "speckit_version": "0.4.2"
+}

.specify/memory/constitution.md

@@ -0,0 +1,136 @@
+<!--
+Sync Impact Report
+Version change: template -> 1.0.0
+Modified principles:
+- [PRINCIPLE_1_NAME] -> I. Safety-Critical Mesh Behavior
+- [PRINCIPLE_2_NAME] -> II. Variant-Scoped Hardware Truth
+- [PRINCIPLE_3_NAME] -> III. Verification by Targeted Evidence
+- [PRINCIPLE_4_NAME] -> IV. Resource and Power Discipline
+- [PRINCIPLE_5_NAME] -> V. Minimal, Reviewable Change Sets
+Added sections:
+- Engineering Constraints
+- Delivery Workflow
+Removed sections:
+- None
+Templates requiring updates:
+- ✅ .specify/templates/plan-template.md
+- ✅ .specify/templates/spec-template.md
+- ✅ .specify/templates/tasks-template.md
+- ⚠ pending .specify/templates/checklist-template.md (not required for current constitution alignment)
+- ⚠ pending .specify/templates/agent-file-template.md (generic scaffold, no constitution-specific drift found)
+Follow-up TODOs:
+- None
+-->
+
+# Meshtastic Firmware Constitution
+
+## Core Principles
+
+### I. Safety-Critical Mesh Behavior
+
+All feature and bug-fix work MUST preserve safe, predictable behavior on live mesh networks.
+Changes that affect routing, airtime, broadcast intervals, MQTT bridging, channel handling,
+or packet processing MUST document the operational impact on shared bandwidth, public-channel
+abuse protections, and interoperability. Any relaxation of rate limits, encryption behavior,
+or default-channel safeguards MUST be treated as a breaking governance change unless explicitly
+approved and justified.
+
+Rationale: Meshtastic devices operate in constrained radio environments where seemingly small
+behavior changes can degrade network reliability, privacy, and fairness for other nodes.
+
+### II. Variant-Scoped Hardware Truth
+
+Board definitions, platform conditionals, and peripheral flags MUST reflect verified hardware
+truth and MUST remain scoped to the exact supported target. New capabilities in `variant.h`,
+`platformio.ini`, `pins_arduino.h`, or related board files MUST be backed by pin mappings,
+chip selection, and power assumptions that are consistent with the board design. Cross-board
+copying is prohibited unless every reused define is revalidated for the destination variant.
+
+Rationale: This firmware spans many architectures and board revisions; incorrect hardware
+declarations create silent regressions that are hard to detect until devices are flashed.
+
+### III. Verification by Targeted Evidence
+
+Every change MUST be validated by the smallest credible evidence that matches its risk.
+At minimum, contributors MUST run formatting or static validation for touched files and MUST
+run a targeted build, test, or simulation path for the affected platform when feasible.
+Changes to shared core logic, protobufs, routing, or configuration defaults SHOULD include a
+native test, simulator run, or equivalent cross-target evidence. If validation cannot be run,
+the gap MUST be stated explicitly in the plan, tasks, and final review.
+
+Rationale: The repository supports many targets, so quality depends on explicit validation
+rather than assumptions that one successful build implies system-wide safety.
+
+### IV. Resource and Power Discipline
+
+Implementations MUST respect embedded constraints for memory, flash, CPU, battery, and radio
+duty cycle. New dependencies, background tasks, logging, polling, display work, and peripheral
+power use MUST be justified against the target hardware footprint. Defaults MUST prefer safe
+operation on constrained devices, and network-facing behavior MUST account for scaling with
+node count where existing project patterns provide that mechanism.
+
+Rationale: Meshtastic firmware runs on low-power devices where unnecessary work directly harms
+battery life, responsiveness, thermal behavior, and mesh capacity.
+
+### V. Minimal, Reviewable Change Sets
+
+Changes MUST solve the root problem with the smallest coherent diff that fits the existing
+architecture and coding patterns. Unrelated refactors, opportunistic renames, and speculative
+abstractions are prohibited in the same change unless they are required to make the fix safe.
+Public behavior, configuration semantics, and generated artifacts MUST remain stable unless the
+specification and plan explicitly call out the intended change.
+
+Rationale: Small, scoped changes are easier to review across board variants and reduce the
+risk of hidden regressions in a large multi-platform firmware repository.
+
+## Engineering Constraints
+
+The authoritative implementation context for this repository is `.github/copilot-instructions.md`.
+Plans and tasks MUST align with the existing PlatformIO-based build system, generated protobuf
+workflow, architecture-specific source layout, and hardware-variant structure already used in
+the repository.
+
+Feature work MUST honor these constraints:
+
+- Code MUST follow existing logging, naming, threading, and configuration patterns.
+- Default values and user-facing configuration changes MUST use existing `Default` helpers and
+  public-channel safeguards where applicable.
+- Protobuf changes MUST include regeneration steps and identify downstream effects in generated
+  code and dependent modules.
+- Build and validation steps MUST prefer repository-standard commands such as targeted `pio run`,
+  `pio test -e native`, simulator tooling, and `trunk fmt` where applicable.
+- Platform-specific logic MUST be isolated to the narrowest valid architecture or variant scope.
+
+## Delivery Workflow
+
+Spec-driven work in this repository MUST produce artifacts that make operational risk visible
+before code is written.
+
+- Specifications MUST describe affected user or device behavior, impacted platforms, and edge
+  cases for unavailable peripherals, misconfigured variants, and constrained-network scenarios.
+- Plans MUST include a Constitution Check that names the exact validation evidence, target
+  environments, and any justified deviations from the constitution.
+- Tasks MUST be organized so that foundational hardware, protocol, or configuration work is
+  completed before feature-specific behavior that depends on it.
+- Review and implementation notes MUST call out any skipped validation, generated-file updates,
+  migration considerations, or behavior changes requiring maintainer scrutiny.
+
+## Governance
+
+This constitution supersedes ad hoc workflow preferences for spec-driven work in this repository.
+All plans, tasks, reviews, and implementation summaries MUST verify compliance with these
+principles.
+
+- Amendments MUST be documented in this file and reflected in dependent templates before new
+  work proceeds under the changed rule set.
+- Versioning policy for this constitution follows semantic versioning.
+  MAJOR versions indicate removed or materially redefined principles.
+  MINOR versions indicate new principles, sections, or materially expanded guidance.
+  PATCH versions indicate clarifications, wording improvements, or non-semantic refinements.
+- Compliance review is mandatory for every feature plan and code review. Any constitutional
+  violation MUST be listed in the plan's Complexity Tracking section or equivalent justification.
+- Repository guidance files remain authoritative for implementation detail. Where conflict is
+  discovered, this constitution governs process and quality gates, while `.github/copilot-instructions.md`
+  governs repository-specific coding practice until the conflict is resolved by amendment.
+
+**Version**: 1.0.0 | **Ratified**: 2026-03-25 | **Last Amended**: 2026-03-25

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+	case "$arg" in
+	--json)
+		JSON_MODE=true
+		;;
+	--require-tasks)
+		REQUIRE_TASKS=true
+		;;
+	--include-tasks)
+		INCLUDE_TASKS=true
+		;;
+	--paths-only)
+		PATHS_ONLY=true
+		;;
+	--help | -h)
+		cat <<'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+		exit 0
+		;;
+	*)
+		echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+		exit 1
+		;;
+	esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+_paths_output=$(get_feature_paths) || {
+	echo "ERROR: Failed to resolve feature paths" >&2
+	exit 1
+}
+eval "$_paths_output"
+unset _paths_output
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+	if $JSON_MODE; then
+		# Minimal JSON paths payload (no validation performed)
+		if has_jq; then
+			jq -cn \
+				--arg repo_root "$REPO_ROOT" \
+				--arg branch "$CURRENT_BRANCH" \
+				--arg feature_dir "$FEATURE_DIR" \
+				--arg feature_spec "$FEATURE_SPEC" \
+				--arg impl_plan "$IMPL_PLAN" \
+				--arg tasks "$TASKS" \
+				'{REPO_ROOT:$repo_root,BRANCH:$branch,FEATURE_DIR:$feature_dir,FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,TASKS:$tasks}'
+		else
+			printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+				"$(json_escape "$REPO_ROOT")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$TASKS")"
+		fi
+	else
+		echo "REPO_ROOT: $REPO_ROOT"
+		echo "BRANCH: $CURRENT_BRANCH"
+		echo "FEATURE_DIR: $FEATURE_DIR"
+		echo "FEATURE_SPEC: $FEATURE_SPEC"
+		echo "IMPL_PLAN: $IMPL_PLAN"
+		echo "TASKS: $TASKS"
+	fi
+	exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d $FEATURE_DIR ]]; then
+	echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+	echo "Run /speckit.specify first to create the feature structure." >&2
+	exit 1
+fi
+
+if [[ ! -f $IMPL_PLAN ]]; then
+	echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+	echo "Run /speckit.plan first to create the implementation plan." >&2
+	exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f $TASKS ]]; then
+	echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+	echo "Run /speckit.tasks first to create the task list." >&2
+	exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f $RESEARCH ]] && docs+=("research.md")
+[[ -f $DATA_MODEL ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d $CONTRACTS_DIR ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+	docs+=("contracts/")
+fi
+
+[[ -f $QUICKSTART ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f $TASKS ]]; then
+	docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+	# Build JSON array of documents
+	if has_jq; then
+		if [[ ${#docs[@]} -eq 0 ]]; then
+			json_docs="[]"
+		else
+			json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
+		fi
+		jq -cn \
+			--arg feature_dir "$FEATURE_DIR" \
+			--argjson docs "$json_docs" \
+			'{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+	else
+		if [[ ${#docs[@]} -eq 0 ]]; then
+			json_docs="[]"
+		else
+			json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
+			json_docs="[${json_docs%,}]"
+		fi
+		printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+	fi
+else
+	# Text output
+	echo "FEATURE_DIR:$FEATURE_DIR"
+	echo "AVAILABLE_DOCS:"
+
+	# Show status of each potential document
+	check_file "$RESEARCH" "research.md"
+	check_file "$DATA_MODEL" "data-model.md"
+	check_dir "$CONTRACTS_DIR" "contracts/"
+	check_file "$QUICKSTART" "quickstart.md"
+
+	if $INCLUDE_TASKS; then
+		check_file "$TASKS" "tasks.md"
+	fi
+fi

.specify/scripts/bash/common.sh

@@ -0,0 +1,329 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Find repository root by searching upward for .specify directory
+# This is the primary marker for spec-kit projects
+find_specify_root() {
+	local dir="${1:-$(pwd)}"
+	# Normalize to absolute path to prevent infinite loop with relative paths
+	# Use -- to handle paths starting with - (e.g., -P, -L)
+	dir="$(cd -- "$dir" 2>/dev/null && pwd)" || return 1
+	local prev_dir=""
+	while true; do
+		if [ -d "$dir/.specify" ]; then
+			echo "$dir"
+			return 0
+		fi
+		# Stop if we've reached filesystem root or dirname stops changing
+		if [ "$dir" = "/" ] || [ "$dir" = "$prev_dir" ]; then
+			break
+		fi
+		prev_dir="$dir"
+		dir="$(dirname "$dir")"
+	done
+	return 1
+}
+
+# Get repository root, prioritizing .specify directory over git
+# This prevents using a parent git repo when spec-kit is initialized in a subdirectory
+get_repo_root() {
+	# First, look for .specify directory (spec-kit's own marker)
+	local specify_root
+	if specify_root=$(find_specify_root); then
+		echo "$specify_root"
+		return
+	fi
+
+	# Fallback to git if no .specify found
+	if git rev-parse --show-toplevel >/dev/null 2>&1; then
+		git rev-parse --show-toplevel
+		return
+	fi
+
+	# Final fallback to script location for non-git repos
+	local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	(cd "$script_dir/../../.." && pwd)
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+	# First check if SPECIFY_FEATURE environment variable is set
+	if [[ -n ${SPECIFY_FEATURE-} ]]; then
+		echo "$SPECIFY_FEATURE"
+		return
+	fi
+
+	# Then check git if available at the spec-kit root (not parent)
+	local repo_root=$(get_repo_root)
+	if has_git; then
+		git -C "$repo_root" rev-parse --abbrev-ref HEAD
+		return
+	fi
+
+	# For non-git repos, try to find the latest feature directory
+	local specs_dir="$repo_root/specs"
+
+	if [[ -d $specs_dir ]]; then
+		local latest_feature=""
+		local highest=0
+		local latest_timestamp=""
+
+		for dir in "$specs_dir"/*; do
+			if [[ -d $dir ]]; then
+				local dirname=$(basename "$dir")
+				if [[ $dirname =~ ^([0-9]{8}-[0-9]{6})- ]]; then
+					# Timestamp-based branch: compare lexicographically
+					local ts="${BASH_REMATCH[1]}"
+					if [[ $ts > $latest_timestamp ]]; then
+						latest_timestamp="$ts"
+						latest_feature=$dirname
+					fi
+				elif [[ $dirname =~ ^([0-9]{3})- ]]; then
+					local number=${BASH_REMATCH[1]}
+					number=$((10#$number))
+					if [[ $number -gt $highest ]]; then
+						highest=$number
+						# Only update if no timestamp branch found yet
+						if [[ -z $latest_timestamp ]]; then
+							latest_feature=$dirname
+						fi
+					fi
+				fi
+			fi
+		done
+
+		if [[ -n $latest_feature ]]; then
+			echo "$latest_feature"
+			return
+		fi
+	fi
+
+	echo "main" # Final fallback
+}
+
+# Check if we have git available at the spec-kit root level
+# Returns true only if git is installed and the repo root is inside a git work tree
+# Handles both regular repos (.git directory) and worktrees/submodules (.git file)
+has_git() {
+	# First check if git command is available (before calling get_repo_root which may use git)
+	command -v git >/dev/null 2>&1 || return 1
+	local repo_root=$(get_repo_root)
+	# Check if .git exists (directory or file for worktrees/submodules)
+	[ -e "$repo_root/.git" ] || return 1
+	# Verify it's actually a valid git work tree
+	git -C "$repo_root" rev-parse --is-inside-work-tree >/dev/null 2>&1
+}
+
+check_feature_branch() {
+	local branch="$1"
+	local has_git_repo="$2"
+
+	# For non-git repos, we can't enforce branch naming but still provide output
+	if [[ $has_git_repo != "true" ]]; then
+		echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+		return 0
+	fi
+
+	if [[ ! $branch =~ ^[0-9]{3}- ]] && [[ ! $branch =~ ^[0-9]{8}-[0-9]{6}- ]]; then
+		echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+		echo "Feature branches should be named like: 001-feature-name or 20260319-143022-feature-name" >&2
+		return 1
+	fi
+
+	return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+	local repo_root="$1"
+	local branch_name="$2"
+	local specs_dir="$repo_root/specs"
+
+	# Extract prefix from branch (e.g., "004" from "004-whatever" or "20260319-143022" from timestamp branches)
+	local prefix=""
+	if [[ $branch_name =~ ^([0-9]{8}-[0-9]{6})- ]]; then
+		prefix="${BASH_REMATCH[1]}"
+	elif [[ $branch_name =~ ^([0-9]{3})- ]]; then
+		prefix="${BASH_REMATCH[1]}"
+	else
+		# If branch doesn't have a recognized prefix, fall back to exact match
+		echo "$specs_dir/$branch_name"
+		return
+	fi
+
+	# Search for directories in specs/ that start with this prefix
+	local matches=()
+	if [[ -d $specs_dir ]]; then
+		for dir in "$specs_dir"/"$prefix"-*; do
+			if [[ -d $dir ]]; then
+				matches+=("$(basename "$dir")")
+			fi
+		done
+	fi
+
+	# Handle results
+	if [[ ${#matches[@]} -eq 0 ]]; then
+		# No match found - return the branch name path (will fail later with clear error)
+		echo "$specs_dir/$branch_name"
+	elif [[ ${#matches[@]} -eq 1 ]]; then
+		# Exactly one match - perfect!
+		echo "$specs_dir/${matches[0]}"
+	else
+		# Multiple matches - this shouldn't happen with proper naming convention
+		echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+		echo "Please ensure only one spec directory exists per prefix." >&2
+		return 1
+	fi
+}
+
+get_feature_paths() {
+	local repo_root=$(get_repo_root)
+	local current_branch=$(get_current_branch)
+	local has_git_repo="false"
+
+	if has_git; then
+		has_git_repo="true"
+	fi
+
+	# Use prefix-based lookup to support multiple branches per spec
+	local feature_dir
+	if ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
+		echo "ERROR: Failed to resolve feature directory" >&2
+		return 1
+	fi
+
+	# Use printf '%q' to safely quote values, preventing shell injection
+	# via crafted branch names or paths containing special characters
+	printf 'REPO_ROOT=%q\n' "$repo_root"
+	printf 'CURRENT_BRANCH=%q\n' "$current_branch"
+	printf 'HAS_GIT=%q\n' "$has_git_repo"
+	printf 'FEATURE_DIR=%q\n' "$feature_dir"
+	printf 'FEATURE_SPEC=%q\n' "$feature_dir/spec.md"
+	printf 'IMPL_PLAN=%q\n' "$feature_dir/plan.md"
+	printf 'TASKS=%q\n' "$feature_dir/tasks.md"
+	printf 'RESEARCH=%q\n' "$feature_dir/research.md"
+	printf 'DATA_MODEL=%q\n' "$feature_dir/data-model.md"
+	printf 'QUICKSTART=%q\n' "$feature_dir/quickstart.md"
+	printf 'CONTRACTS_DIR=%q\n' "$feature_dir/contracts"
+}
+
+# Check if jq is available for safe JSON construction
+has_jq() {
+	command -v jq >/dev/null 2>&1
+}
+
+# Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
+# Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
+json_escape() {
+	local s="$1"
+	s="${s//\\/\\\\}"
+	s="${s//\"/\\\"}"
+	s="${s//$'\n'/\\n}"
+	s="${s//$'\t'/\\t}"
+	s="${s//$'\r'/\\r}"
+	s="${s//$'\b'/\\b}"
+	s="${s//$'\f'/\\f}"
+	# Escape any remaining U+0001-U+001F control characters as \uXXXX.
+	# (U+0000/NUL cannot appear in bash strings and is excluded.)
+	# LC_ALL=C ensures ${#s} counts bytes and ${s:$i:1} yields single bytes,
+	# so multi-byte UTF-8 sequences (first byte >= 0xC0) pass through intact.
+	local LC_ALL=C
+	local i char code
+	for ((i = 0; i < ${#s}; i++)); do
+		char="${s:i:1}"
+		printf -v code '%d' "'$char" 2>/dev/null || code=256
+		if ((code >= 1 && code <= 31)); then
+			printf '\\u%04x' "$code"
+		else
+			printf '%s' "$char"
+		fi
+	done
+}
+
+check_file() { [[ -f $1 ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d $1 && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+
+# Resolve a template name to a file path using the priority stack:
+#   1. .specify/templates/overrides/
+#   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+#   3. .specify/extensions/<ext-id>/templates/
+#   4. .specify/templates/ (core)
+resolve_template() {
+	local template_name="$1"
+	local repo_root="$2"
+	local base="$repo_root/.specify/templates"
+
+	# Priority 1: Project overrides
+	local override="$base/overrides/${template_name}.md"
+	[ -f "$override" ] && echo "$override" && return 0
+
+	# Priority 2: Installed presets (sorted by priority from .registry)
+	local presets_dir="$repo_root/.specify/presets"
+	if [ -d "$presets_dir" ]; then
+		local registry_file="$presets_dir/.registry"
+		if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
+			# Read preset IDs sorted by priority (lower number = higher precedence).
+			# The python3 call is wrapped in an if-condition so that set -e does not
+			# abort the function when python3 exits non-zero (e.g. invalid JSON).
+			local sorted_presets=""
+			if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
+import json, sys, os
+try:
+    with open(os.environ['SPECKIT_REGISTRY']) as f:
+        data = json.load(f)
+    presets = data.get('presets', {})
+    for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10)):
+        print(pid)
+except Exception:
+    sys.exit(1)
+" 2>/dev/null); then
+				if [ -n "$sorted_presets" ]; then
+					# python3 succeeded and returned preset IDs — search in priority order
+					while IFS= read -r preset_id; do
+						local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
+						[ -f "$candidate" ] && echo "$candidate" && return 0
+					done <<<"$sorted_presets"
+				fi
+				# python3 succeeded but registry has no presets — nothing to search
+			else
+				# python3 failed (missing, or registry parse error) — fall back to unordered directory scan
+				for preset in "$presets_dir"/*/; do
+					[ -d "$preset" ] || continue
+					local candidate="$preset/templates/${template_name}.md"
+					[ -f "$candidate" ] && echo "$candidate" && return 0
+				done
+			fi
+		else
+			# Fallback: alphabetical directory order (no python3 available)
+			for preset in "$presets_dir"/*/; do
+				[ -d "$preset" ] || continue
+				local candidate="$preset/templates/${template_name}.md"
+				[ -f "$candidate" ] && echo "$candidate" && return 0
+			done
+		fi
+	fi
+
+	# Priority 3: Extension-provided templates
+	local ext_dir="$repo_root/.specify/extensions"
+	if [ -d "$ext_dir" ]; then
+		for ext in "$ext_dir"/*/; do
+			[ -d "$ext" ] || continue
+			# Skip hidden directories (e.g. .backup, .cache)
+			case "$(basename "$ext")" in .*) continue ;; esac
+			local candidate="$ext/templates/${template_name}.md"
+			[ -f "$candidate" ] && echo "$candidate" && return 0
+		done
+	fi
+
+	# Priority 4: Core templates
+	local core="$base/${template_name}.md"
+	[ -f "$core" ] && echo "$core" && return 0
+
+	# Template not found in any location.
+	# Return 1 so callers can distinguish "not found" from "found".
+	# Callers running under set -e should use: TEMPLATE=$(resolve_template ...) || true
+	return 1
+}

.specify/scripts/bash/create-new-feature.sh

@@ -0,0 +1,335 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+USE_TIMESTAMP=false
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+	arg="${!i}"
+	case "$arg" in
+	--json)
+		JSON_MODE=true
+		;;
+	--short-name)
+		if [ $((i + 1)) -gt $# ]; then
+			echo 'Error: --short-name requires a value' >&2
+			exit 1
+		fi
+		i=$((i + 1))
+		next_arg="${!i}"
+		# Check if the next argument is another option (starts with --)
+		if [[ $next_arg == --* ]]; then
+			echo 'Error: --short-name requires a value' >&2
+			exit 1
+		fi
+		SHORT_NAME="$next_arg"
+		;;
+	--number)
+		if [ $((i + 1)) -gt $# ]; then
+			echo 'Error: --number requires a value' >&2
+			exit 1
+		fi
+		i=$((i + 1))
+		next_arg="${!i}"
+		if [[ $next_arg == --* ]]; then
+			echo 'Error: --number requires a value' >&2
+			exit 1
+		fi
+		BRANCH_NUMBER="$next_arg"
+		;;
+	--timestamp)
+		USE_TIMESTAMP=true
+		;;
+	--help | -h)
+		echo "Usage: $0 [--json] [--short-name <name>] [--number N] [--timestamp] <feature_description>"
+		echo ""
+		echo "Options:"
+		echo "  --json              Output in JSON format"
+		echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+		echo "  --number N          Specify branch number manually (overrides auto-detection)"
+		echo "  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
+		echo "  --help, -h          Show this help message"
+		echo ""
+		echo "Examples:"
+		echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+		echo "  $0 'Implement OAuth2 integration for API' --number 5"
+		echo "  $0 --timestamp --short-name 'user-auth' 'Add user authentication'"
+		exit 0
+		;;
+	*)
+		ARGS+=("$arg")
+		;;
+	esac
+	i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+	echo "Usage: $0 [--json] [--short-name <name>] [--number N] [--timestamp] <feature_description>" >&2
+	exit 1
+fi
+
+# Trim whitespace and validate description is not empty (e.g., user passed only whitespace)
+FEATURE_DESCRIPTION=$(echo "$FEATURE_DESCRIPTION" | xargs)
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+	echo "Error: Feature description cannot be empty or contain only whitespace" >&2
+	exit 1
+fi
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+	local specs_dir="$1"
+	local highest=0
+
+	if [ -d "$specs_dir" ]; then
+		for dir in "$specs_dir"/*; do
+			[ -d "$dir" ] || continue
+			dirname=$(basename "$dir")
+			# Only match sequential prefixes (###-*), skip timestamp dirs
+			if echo "$dirname" | grep -q '^[0-9]\{3\}-'; then
+				number=$(echo "$dirname" | grep -o '^[0-9]\{3\}')
+				number=$((10#$number))
+				if [ "$number" -gt "$highest" ]; then
+					highest=$number
+				fi
+			fi
+		done
+	fi
+
+	echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+	local highest=0
+
+	# Get all branches (local and remote)
+	branches=$(git branch -a 2>/dev/null || echo "")
+
+	if [ -n "$branches" ]; then
+		while IFS= read -r branch; do
+			# Clean branch name: remove leading markers and remote prefixes
+			clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+
+			# Extract feature number if branch matches pattern ###-*
+			if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+				number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+				number=$((10#$number))
+				if [ "$number" -gt "$highest" ]; then
+					highest=$number
+				fi
+			fi
+		done <<<"$branches"
+	fi
+
+	echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+	local specs_dir="$1"
+
+	# Fetch all remotes to get latest branch info (suppress errors if no remotes)
+	git fetch --all --prune >/dev/null 2>&1 || true
+
+	# Get highest number from ALL branches (not just matching short name)
+	local highest_branch=$(get_highest_from_branches)
+
+	# Get highest number from ALL specs (not just matching short name)
+	local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+	# Take the maximum of both
+	local max_num=$highest_branch
+	if [ "$highest_spec" -gt "$max_num" ]; then
+		max_num=$highest_spec
+	fi
+
+	# Return next number
+	echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+	local name="$1"
+	echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root using common.sh functions which prioritize .specify over git
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+REPO_ROOT=$(get_repo_root)
+
+# Check if git is available at this repo root (not a parent)
+if has_git; then
+	HAS_GIT=true
+else
+	HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+	local description="$1"
+
+	# Common stop words to filter out
+	local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+
+	# Convert to lowercase and split into words
+	local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+
+	# Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+	local meaningful_words=()
+	for word in $clean_name; do
+		# Skip empty words
+		[ -z "$word" ] && continue
+
+		# Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+		if ! echo "$word" | grep -qiE "$stop_words"; then
+			if [ ${#word} -ge 3 ]; then
+				meaningful_words+=("$word")
+			elif echo "$description" | grep -q "\b${word^^}\b"; then
+				# Keep short words if they appear as uppercase in original (likely acronyms)
+				meaningful_words+=("$word")
+			fi
+		fi
+	done
+
+	# If we have meaningful words, use first 3-4 of them
+	if [ ${#meaningful_words[@]} -gt 0 ]; then
+		local max_words=3
+		if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+
+		local result=""
+		local count=0
+		for word in "${meaningful_words[@]}"; do
+			if [ $count -ge $max_words ]; then break; fi
+			if [ -n "$result" ]; then result="$result-"; fi
+			result="$result$word"
+			count=$((count + 1))
+		done
+		echo "$result"
+	else
+		# Fallback to original logic if no meaningful words found
+		local cleaned=$(clean_branch_name "$description")
+		echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+	fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+	# Use provided short name, just clean it up
+	BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+	# Generate from description with smart filtering
+	BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Warn if --number and --timestamp are both specified
+if [ "$USE_TIMESTAMP" = true ] && [ -n "$BRANCH_NUMBER" ]; then
+	echo >&2 "[specify] Warning: --number is ignored when --timestamp is used"
+	BRANCH_NUMBER=""
+fi
+
+# Determine branch prefix
+if [ "$USE_TIMESTAMP" = true ]; then
+	FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
+	BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+else
+	# Determine branch number
+	if [ -z "$BRANCH_NUMBER" ]; then
+		if [ "$HAS_GIT" = true ]; then
+			# Check existing branches on remotes
+			BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+		else
+			# Fall back to local directory check
+			HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+			BRANCH_NUMBER=$((HIGHEST + 1))
+		fi
+	fi
+
+	# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+	FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+	BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+fi
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+	# Calculate how much we need to trim from suffix
+	# Account for prefix length: timestamp (15) + hyphen (1) = 16, or sequential (3) + hyphen (1) = 4
+	PREFIX_LENGTH=$((${#FEATURE_NUM} + 1))
+	MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - PREFIX_LENGTH))
+
+	# Truncate suffix at word boundary if possible
+	TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+	# Remove trailing hyphen if truncation created one
+	TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+
+	ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+	BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+
+	echo >&2 "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+	echo >&2 "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+	echo >&2 "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+	if ! git checkout -b "$BRANCH_NAME" 2>/dev/null; then
+		# Check if branch already exists
+		if git branch --list "$BRANCH_NAME" | grep -q .; then
+			if [ "$USE_TIMESTAMP" = true ]; then
+				echo >&2 "Error: Branch '$BRANCH_NAME' already exists. Rerun to get a new timestamp or use a different --short-name."
+			else
+				echo >&2 "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
+			fi
+			exit 1
+		else
+			echo >&2 "Error: Failed to create git branch '$BRANCH_NAME'. Please check your git configuration and try again."
+			exit 1
+		fi
+	fi
+else
+	echo >&2 "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
+	cp "$TEMPLATE" "$SPEC_FILE"
+else
+	echo "Warning: Spec template not found; created empty spec file" >&2
+	touch "$SPEC_FILE"
+fi
+
+# Inform the user how to persist the feature variable in their own shell
+printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
+
+if $JSON_MODE; then
+	if command -v jq >/dev/null 2>&1; then
+		jq -cn \
+			--arg branch_name "$BRANCH_NAME" \
+			--arg spec_file "$SPEC_FILE" \
+			--arg feature_num "$FEATURE_NUM" \
+			'{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num}'
+	else
+		printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+	fi
+else
+	echo "BRANCH_NAME: $BRANCH_NAME"
+	echo "SPEC_FILE: $SPEC_FILE"
+	echo "FEATURE_NUM: $FEATURE_NUM"
+	printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"
+fi

.specify/scripts/bash/setup-plan.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+	case "$arg" in
+	--json)
+		JSON_MODE=true
+		;;
+	--help | -h)
+		echo "Usage: $0 [--json]"
+		echo "  --json    Output results in JSON format"
+		echo "  --help    Show this help message"
+		exit 0
+		;;
+	*)
+		ARGS+=("$arg")
+		;;
+	esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || {
+	echo "ERROR: Failed to resolve feature paths" >&2
+	exit 1
+}
+eval "$_paths_output"
+unset _paths_output
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
+if [[ -n $TEMPLATE ]] && [[ -f $TEMPLATE ]]; then
+	cp "$TEMPLATE" "$IMPL_PLAN"
+	echo "Copied plan template to $IMPL_PLAN"
+else
+	echo "Warning: Plan template not found"
+	# Create a basic plan file if template doesn't exist
+	touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+	if has_jq; then
+		jq -cn \
+			--arg feature_spec "$FEATURE_SPEC" \
+			--arg impl_plan "$IMPL_PLAN" \
+			--arg specs_dir "$FEATURE_DIR" \
+			--arg branch "$CURRENT_BRANCH" \
+			--arg has_git "$HAS_GIT" \
+			'{FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,SPECS_DIR:$specs_dir,BRANCH:$branch,HAS_GIT:$has_git}'
+	else
+		printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+			"$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$HAS_GIT")"
+	fi
+else
+	echo "FEATURE_SPEC: $FEATURE_SPEC"
+	echo "IMPL_PLAN: $IMPL_PLAN"
+	echo "SPECS_DIR: $FEATURE_DIR"
+	echo "BRANCH: $CURRENT_BRANCH"
+	echo "HAS_GIT: $HAS_GIT"
+fi

.specify/scripts/bash/update-agent-context.sh

@@ -0,0 +1,840 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Junie, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, Pi Coding Agent, iFlow CLI, Antigravity or Generic
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || {
+	echo "ERROR: Failed to resolve feature paths" >&2
+	exit 1
+}
+eval "$_paths_output"
+unset _paths_output
+
+NEW_PLAN="$IMPL_PLAN" # Alias for compatibility with existing code
+AGENT_TYPE="${1-}"
+
+# Agent-specific file paths
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+JUNIE_FILE="$REPO_ROOT/.junie/AGENTS.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+# Amp, Kiro CLI, IBM Bob, and Pi all share AGENTS.md — use AGENTS_FILE to avoid
+# updating the same file multiple times.
+AMP_FILE="$AGENTS_FILE"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+TABNINE_FILE="$REPO_ROOT/TABNINE.md"
+KIRO_FILE="$AGENTS_FILE"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
+BOB_FILE="$AGENTS_FILE"
+VIBE_FILE="$REPO_ROOT/.vibe/agents/specify-agents.md"
+KIMI_FILE="$REPO_ROOT/KIMI.md"
+TRAE_FILE="$REPO_ROOT/.trae/rules/AGENTS.md"
+IFLOW_FILE="$REPO_ROOT/IFLOW.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+	echo "INFO: $1"
+}
+
+log_success() {
+	echo "✓ $1"
+}
+
+log_error() {
+	echo "ERROR: $1" >&2
+}
+
+log_warning() {
+	echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+	local exit_code=$?
+	# Disarm traps to prevent re-entrant loop
+	trap - EXIT INT TERM
+	rm -f /tmp/agent_update_*_$$
+	rm -f /tmp/manual_additions_$$
+	exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+	# Check if we have a current branch/feature (git or non-git)
+	if [[ -z $CURRENT_BRANCH ]]; then
+		log_error "Unable to determine current feature"
+		if [[ $HAS_GIT == "true" ]]; then
+			log_info "Make sure you're on a feature branch"
+		else
+			log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+		fi
+		exit 1
+	fi
+
+	# Check if plan.md exists
+	if [[ ! -f $NEW_PLAN ]]; then
+		log_error "No plan.md found at $NEW_PLAN"
+		log_info "Make sure you're working on a feature with a corresponding spec directory"
+		if [[ $HAS_GIT != "true" ]]; then
+			log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+		fi
+		exit 1
+	fi
+
+	# Check if template exists (needed for new files)
+	if [[ ! -f $TEMPLATE_FILE ]]; then
+		log_warning "Template file not found at $TEMPLATE_FILE"
+		log_warning "Creating new agent files will fail"
+	fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+	local field_pattern="$1"
+	local plan_file="$2"
+
+	grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null |
+		head -1 |
+		sed "s|^\*\*${field_pattern}\*\*: ||" |
+		sed 's/^[ \t]*//;s/[ \t]*$//' |
+		grep -v "NEEDS CLARIFICATION" |
+		grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+	local plan_file="$1"
+
+	if [[ ! -f $plan_file ]]; then
+		log_error "Plan file not found: $plan_file"
+		return 1
+	fi
+
+	if [[ ! -r $plan_file ]]; then
+		log_error "Plan file is not readable: $plan_file"
+		return 1
+	fi
+
+	log_info "Parsing plan data from $plan_file"
+
+	NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+	NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+	NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+	NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+
+	# Log what we found
+	if [[ -n $NEW_LANG ]]; then
+		log_info "Found language: $NEW_LANG"
+	else
+		log_warning "No language information found in plan"
+	fi
+
+	if [[ -n $NEW_FRAMEWORK ]]; then
+		log_info "Found framework: $NEW_FRAMEWORK"
+	fi
+
+	if [[ -n $NEW_DB ]] && [[ $NEW_DB != "N/A" ]]; then
+		log_info "Found database: $NEW_DB"
+	fi
+
+	if [[ -n $NEW_PROJECT_TYPE ]]; then
+		log_info "Found project type: $NEW_PROJECT_TYPE"
+	fi
+}
+
+format_technology_stack() {
+	local lang="$1"
+	local framework="$2"
+	local parts=()
+
+	# Add non-empty parts
+	[[ -n $lang && $lang != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+	[[ -n $framework && $framework != "NEEDS CLARIFICATION" && $framework != "N/A" ]] && parts+=("$framework")
+
+	# Join with proper formatting
+	if [[ ${#parts[@]} -eq 0 ]]; then
+		echo ""
+	elif [[ ${#parts[@]} -eq 1 ]]; then
+		echo "${parts[0]}"
+	else
+		# Join multiple parts with " + "
+		local result="${parts[0]}"
+		for ((i = 1; i < ${#parts[@]}; i++)); do
+			result="$result + ${parts[i]}"
+		done
+		echo "$result"
+	fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+	local project_type="$1"
+
+	if [[ $project_type == *"web"* ]]; then
+		echo 'backend/\nfrontend/\ntests/'
+	else
+		echo 'src/\ntests/'
+	fi
+}
+
+get_commands_for_language() {
+	local lang="$1"
+
+	case "$lang" in
+	*"Python"*)
+		echo "cd src && pytest && ruff check ."
+		;;
+	*"Rust"*)
+		echo "cargo test && cargo clippy"
+		;;
+	*"JavaScript"* | *"TypeScript"*)
+		echo 'npm test \&\& npm run lint'
+		;;
+	*)
+		echo "# Add commands for $lang"
+		;;
+	esac
+}
+
+get_language_conventions() {
+	local lang="$1"
+	echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+	local target_file="$1"
+	local temp_file="$2"
+	local project_name="$3"
+	local current_date="$4"
+
+	if [[ ! -f $TEMPLATE_FILE ]]; then
+		log_error "Template not found at $TEMPLATE_FILE"
+		return 1
+	fi
+
+	if [[ ! -r $TEMPLATE_FILE ]]; then
+		log_error "Template file is not readable: $TEMPLATE_FILE"
+		return 1
+	fi
+
+	log_info "Creating new agent context file from template..."
+
+	if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+		log_error "Failed to copy template file"
+		return 1
+	fi
+
+	# Replace template placeholders
+	local project_structure
+	project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+
+	local commands
+	commands=$(get_commands_for_language "$NEW_LANG")
+
+	local language_conventions
+	language_conventions=$(get_language_conventions "$NEW_LANG")
+
+	# Perform substitutions with error checking using safer approach
+	# Escape special characters for sed by using a different delimiter or escaping
+	local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+	local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+	local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+
+	# Build technology stack and recent change strings conditionally
+	local tech_stack
+	if [[ -n $escaped_lang && -n $escaped_framework ]]; then
+		tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+	elif [[ -n $escaped_lang ]]; then
+		tech_stack="- $escaped_lang ($escaped_branch)"
+	elif [[ -n $escaped_framework ]]; then
+		tech_stack="- $escaped_framework ($escaped_branch)"
+	else
+		tech_stack="- ($escaped_branch)"
+	fi
+
+	local recent_change
+	if [[ -n $escaped_lang && -n $escaped_framework ]]; then
+		recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+	elif [[ -n $escaped_lang ]]; then
+		recent_change="- $escaped_branch: Added $escaped_lang"
+	elif [[ -n $escaped_framework ]]; then
+		recent_change="- $escaped_branch: Added $escaped_framework"
+	else
+		recent_change="- $escaped_branch: Added"
+	fi
+
+	local substitutions=(
+		"s|\[PROJECT NAME\]|$project_name|"
+		"s|\[DATE\]|$current_date|"
+		"s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+		"s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+		"s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+		"s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+		"s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+	)
+
+	for substitution in "${substitutions[@]}"; do
+		if ! sed -i.bak -e "$substitution" "$temp_file"; then
+			log_error "Failed to perform substitution: $substitution"
+			rm -f "$temp_file" "$temp_file.bak"
+			return 1
+		fi
+	done
+
+	# Convert \n sequences to actual newlines
+	newline=$(printf '\n')
+	sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+
+	# Clean up backup files
+	rm -f "$temp_file.bak" "$temp_file.bak2"
+
+	# Prepend Cursor frontmatter for .mdc files so rules are auto-included
+	if [[ $target_file == *.mdc ]]; then
+		local frontmatter_file
+		frontmatter_file=$(mktemp) || return 1
+		printf '%s\n' "---" "description: Project Development Guidelines" 'globs: ["**/*"]' "alwaysApply: true" "---" "" >"$frontmatter_file"
+		cat "$temp_file" >>"$frontmatter_file"
+		mv "$frontmatter_file" "$temp_file"
+	fi
+
+	return 0
+}
+
+update_existing_agent_file() {
+	local target_file="$1"
+	local current_date="$2"
+
+	log_info "Updating existing agent context file..."
+
+	# Use a single temporary file for atomic update
+	local temp_file
+	temp_file=$(mktemp) || {
+		log_error "Failed to create temporary file"
+		return 1
+	}
+
+	# Process the file in one pass
+	local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+	local new_tech_entries=()
+	local new_change_entry=""
+
+	# Prepare new technology entries
+	if [[ -n $tech_stack ]] && ! grep -q "$tech_stack" "$target_file"; then
+		new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+	fi
+
+	if [[ -n $NEW_DB ]] && [[ $NEW_DB != "N/A" ]] && [[ $NEW_DB != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+		new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+	fi
+
+	# Prepare new change entry
+	if [[ -n $tech_stack ]]; then
+		new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+	elif [[ -n $NEW_DB ]] && [[ $NEW_DB != "N/A" ]] && [[ $NEW_DB != "NEEDS CLARIFICATION" ]]; then
+		new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+	fi
+
+	# Check if sections exist in the file
+	local has_active_technologies=0
+	local has_recent_changes=0
+
+	if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+		has_active_technologies=1
+	fi
+
+	if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+		has_recent_changes=1
+	fi
+
+	# Process file line by line
+	local in_tech_section=false
+	local in_changes_section=false
+	local tech_entries_added=false
+	local changes_entries_added=false
+	local existing_changes_count=0
+	local file_ended=false
+
+	while IFS= read -r line || [[ -n $line ]]; do
+		# Handle Active Technologies section
+		if [[ $line == "## Active Technologies" ]]; then
+			echo "$line" >>"$temp_file"
+			in_tech_section=true
+			continue
+		elif [[ $in_tech_section == true ]] && [[ $line =~ ^##[[:space:]] ]]; then
+			# Add new tech entries before closing the section
+			if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+				printf '%s\n' "${new_tech_entries[@]}" >>"$temp_file"
+				tech_entries_added=true
+			fi
+			echo "$line" >>"$temp_file"
+			in_tech_section=false
+			continue
+		elif [[ $in_tech_section == true ]] && [[ -z $line ]]; then
+			# Add new tech entries before empty line in tech section
+			if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+				printf '%s\n' "${new_tech_entries[@]}" >>"$temp_file"
+				tech_entries_added=true
+			fi
+			echo "$line" >>"$temp_file"
+			continue
+		fi
+
+		# Handle Recent Changes section
+		if [[ $line == "## Recent Changes" ]]; then
+			echo "$line" >>"$temp_file"
+			# Add new change entry right after the heading
+			if [[ -n $new_change_entry ]]; then
+				echo "$new_change_entry" >>"$temp_file"
+			fi
+			in_changes_section=true
+			changes_entries_added=true
+			continue
+		elif [[ $in_changes_section == true ]] && [[ $line =~ ^##[[:space:]] ]]; then
+			echo "$line" >>"$temp_file"
+			in_changes_section=false
+			continue
+		elif [[ $in_changes_section == true ]] && [[ $line == "- "* ]]; then
+			# Keep only first 2 existing changes
+			if [[ $existing_changes_count -lt 2 ]]; then
+				echo "$line" >>"$temp_file"
+				((existing_changes_count++))
+			fi
+			continue
+		fi
+
+		# Update timestamp
+		if [[ $line =~ (\*\*)?Last\ updated(\*\*)?:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+			echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >>"$temp_file"
+		else
+			echo "$line" >>"$temp_file"
+		fi
+	done <"$target_file"
+
+	# Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+	if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+		printf '%s\n' "${new_tech_entries[@]}" >>"$temp_file"
+		tech_entries_added=true
+	fi
+
+	# If sections don't exist, add them at the end of the file
+	if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+		echo "" >>"$temp_file"
+		echo "## Active Technologies" >>"$temp_file"
+		printf '%s\n' "${new_tech_entries[@]}" >>"$temp_file"
+		tech_entries_added=true
+	fi
+
+	if [[ $has_recent_changes -eq 0 ]] && [[ -n $new_change_entry ]]; then
+		echo "" >>"$temp_file"
+		echo "## Recent Changes" >>"$temp_file"
+		echo "$new_change_entry" >>"$temp_file"
+		changes_entries_added=true
+	fi
+
+	# Ensure Cursor .mdc files have YAML frontmatter for auto-inclusion
+	if [[ $target_file == *.mdc ]]; then
+		if ! head -1 "$temp_file" | grep -q '^---'; then
+			local frontmatter_file
+			frontmatter_file=$(mktemp) || {
+				rm -f "$temp_file"
+				return 1
+			}
+			printf '%s\n' "---" "description: Project Development Guidelines" 'globs: ["**/*"]' "alwaysApply: true" "---" "" >"$frontmatter_file"
+			cat "$temp_file" >>"$frontmatter_file"
+			mv "$frontmatter_file" "$temp_file"
+		fi
+	fi
+
+	# Move temp file to target atomically
+	if ! mv "$temp_file" "$target_file"; then
+		log_error "Failed to update target file"
+		rm -f "$temp_file"
+		return 1
+	fi
+
+	return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+	local target_file="$1"
+	local agent_name="$2"
+
+	if [[ -z $target_file ]] || [[ -z $agent_name ]]; then
+		log_error "update_agent_file requires target_file and agent_name parameters"
+		return 1
+	fi
+
+	log_info "Updating $agent_name context file: $target_file"
+
+	local project_name
+	project_name=$(basename "$REPO_ROOT")
+	local current_date
+	current_date=$(date +%Y-%m-%d)
+
+	# Create directory if it doesn't exist
+	local target_dir
+	target_dir=$(dirname "$target_file")
+	if [[ ! -d $target_dir ]]; then
+		if ! mkdir -p "$target_dir"; then
+			log_error "Failed to create directory: $target_dir"
+			return 1
+		fi
+	fi
+
+	if [[ ! -f $target_file ]]; then
+		# Create new file from template
+		local temp_file
+		temp_file=$(mktemp) || {
+			log_error "Failed to create temporary file"
+			return 1
+		}
+
+		if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+			if mv "$temp_file" "$target_file"; then
+				log_success "Created new $agent_name context file"
+			else
+				log_error "Failed to move temporary file to $target_file"
+				rm -f "$temp_file"
+				return 1
+			fi
+		else
+			log_error "Failed to create new agent file"
+			rm -f "$temp_file"
+			return 1
+		fi
+	else
+		# Update existing file
+		if [[ ! -r $target_file ]]; then
+			log_error "Cannot read existing file: $target_file"
+			return 1
+		fi
+
+		if [[ ! -w $target_file ]]; then
+			log_error "Cannot write to existing file: $target_file"
+			return 1
+		fi
+
+		if update_existing_agent_file "$target_file" "$current_date"; then
+			log_success "Updated existing $agent_name context file"
+		else
+			log_error "Failed to update existing agent file"
+			return 1
+		fi
+	fi
+
+	return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+	local agent_type="$1"
+
+	case "$agent_type" in
+	claude)
+		update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+		;;
+	gemini)
+		update_agent_file "$GEMINI_FILE" "Gemini CLI" || return 1
+		;;
+	copilot)
+		update_agent_file "$COPILOT_FILE" "GitHub Copilot" || return 1
+		;;
+	cursor-agent)
+		update_agent_file "$CURSOR_FILE" "Cursor IDE" || return 1
+		;;
+	qwen)
+		update_agent_file "$QWEN_FILE" "Qwen Code" || return 1
+		;;
+	opencode)
+		update_agent_file "$AGENTS_FILE" "opencode" || return 1
+		;;
+	codex)
+		update_agent_file "$AGENTS_FILE" "Codex CLI" || return 1
+		;;
+	windsurf)
+		update_agent_file "$WINDSURF_FILE" "Windsurf" || return 1
+		;;
+	junie)
+		update_agent_file "$JUNIE_FILE" "Junie" || return 1
+		;;
+	kilocode)
+		update_agent_file "$KILOCODE_FILE" "Kilo Code" || return 1
+		;;
+	auggie)
+		update_agent_file "$AUGGIE_FILE" "Auggie CLI" || return 1
+		;;
+	roo)
+		update_agent_file "$ROO_FILE" "Roo Code" || return 1
+		;;
+	codebuddy)
+		update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI" || return 1
+		;;
+	qodercli)
+		update_agent_file "$QODER_FILE" "Qoder CLI" || return 1
+		;;
+	amp)
+		update_agent_file "$AMP_FILE" "Amp" || return 1
+		;;
+	shai)
+		update_agent_file "$SHAI_FILE" "SHAI" || return 1
+		;;
+	tabnine)
+		update_agent_file "$TABNINE_FILE" "Tabnine CLI" || return 1
+		;;
+	kiro-cli)
+		update_agent_file "$KIRO_FILE" "Kiro CLI" || return 1
+		;;
+	agy)
+		update_agent_file "$AGY_FILE" "Antigravity" || return 1
+		;;
+	bob)
+		update_agent_file "$BOB_FILE" "IBM Bob" || return 1
+		;;
+	vibe)
+		update_agent_file "$VIBE_FILE" "Mistral Vibe" || return 1
+		;;
+	kimi)
+		update_agent_file "$KIMI_FILE" "Kimi Code" || return 1
+		;;
+	trae)
+		update_agent_file "$TRAE_FILE" "Trae" || return 1
+		;;
+	pi)
+		update_agent_file "$AGENTS_FILE" "Pi Coding Agent" || return 1
+		;;
+	iflow)
+		update_agent_file "$IFLOW_FILE" "iFlow CLI" || return 1
+		;;
+	generic)
+		log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+		;;
+	*)
+		log_error "Unknown agent type '$agent_type'"
+		log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic"
+		exit 1
+		;;
+	esac
+}
+
+# Helper: skip non-existent files and files already updated (dedup by
+# realpath so that variables pointing to the same file — e.g. AMP_FILE,
+# KIRO_FILE, BOB_FILE all resolving to AGENTS_FILE — are only written once).
+# Uses a linear array instead of associative array for bash 3.2 compatibility.
+# Note: defined at top level because bash 3.2 does not support true
+# nested/local functions. _updated_paths, _found_agent, and _all_ok are
+# initialised exclusively inside update_all_existing_agents so that
+# sourcing this script has no side effects on the caller's environment.
+
+_update_if_new() {
+	local file="$1" name="$2"
+	[[ -f $file ]] || return 0
+	local real_path
+	real_path=$(realpath "$file" 2>/dev/null || echo "$file")
+	local p
+	if [[ ${#_updated_paths[@]} -gt 0 ]]; then
+		for p in "${_updated_paths[@]}"; do
+			[[ $p == "$real_path" ]] && return 0
+		done
+	fi
+	# Record the file as seen before attempting the update so that:
+	# (a) aliases pointing to the same path are not retried on failure
+	# (b) _found_agent reflects file existence, not update success
+	_updated_paths+=("$real_path")
+	_found_agent=true
+	update_agent_file "$file" "$name"
+}
+
+update_all_existing_agents() {
+	_found_agent=false
+	_updated_paths=()
+	local _all_ok=true
+
+	_update_if_new "$CLAUDE_FILE" "Claude Code" || _all_ok=false
+	_update_if_new "$GEMINI_FILE" "Gemini CLI" || _all_ok=false
+	_update_if_new "$COPILOT_FILE" "GitHub Copilot" || _all_ok=false
+	_update_if_new "$CURSOR_FILE" "Cursor IDE" || _all_ok=false
+	_update_if_new "$QWEN_FILE" "Qwen Code" || _all_ok=false
+	_update_if_new "$AGENTS_FILE" "Codex/opencode" || _all_ok=false
+	_update_if_new "$AMP_FILE" "Amp" || _all_ok=false
+	_update_if_new "$KIRO_FILE" "Kiro CLI" || _all_ok=false
+	_update_if_new "$BOB_FILE" "IBM Bob" || _all_ok=false
+	_update_if_new "$WINDSURF_FILE" "Windsurf" || _all_ok=false
+	_update_if_new "$JUNIE_FILE" "Junie" || _all_ok=false
+	_update_if_new "$KILOCODE_FILE" "Kilo Code" || _all_ok=false
+	_update_if_new "$AUGGIE_FILE" "Auggie CLI" || _all_ok=false
+	_update_if_new "$ROO_FILE" "Roo Code" || _all_ok=false
+	_update_if_new "$CODEBUDDY_FILE" "CodeBuddy CLI" || _all_ok=false
+	_update_if_new "$SHAI_FILE" "SHAI" || _all_ok=false
+	_update_if_new "$TABNINE_FILE" "Tabnine CLI" || _all_ok=false
+	_update_if_new "$QODER_FILE" "Qoder CLI" || _all_ok=false
+	_update_if_new "$AGY_FILE" "Antigravity" || _all_ok=false
+	_update_if_new "$VIBE_FILE" "Mistral Vibe" || _all_ok=false
+	_update_if_new "$KIMI_FILE" "Kimi Code" || _all_ok=false
+	_update_if_new "$TRAE_FILE" "Trae" || _all_ok=false
+	_update_if_new "$IFLOW_FILE" "iFlow CLI" || _all_ok=false
+
+	# If no agent files exist, create a default Claude file
+	if [[ $_found_agent == false ]]; then
+		log_info "No existing agent files found, creating default Claude file..."
+		update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+	fi
+
+	[[ $_all_ok == true ]]
+}
+print_summary() {
+	echo
+	log_info "Summary of changes:"
+
+	if [[ -n $NEW_LANG ]]; then
+		echo "  - Added language: $NEW_LANG"
+	fi
+
+	if [[ -n $NEW_FRAMEWORK ]]; then
+		echo "  - Added framework: $NEW_FRAMEWORK"
+	fi
+
+	if [[ -n $NEW_DB ]] && [[ $NEW_DB != "N/A" ]]; then
+		echo "  - Added database: $NEW_DB"
+	fi
+
+	echo
+	log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+	# Validate environment before proceeding
+	validate_environment
+
+	log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+
+	# Parse the plan file to extract project information
+	if ! parse_plan_data "$NEW_PLAN"; then
+		log_error "Failed to parse plan data"
+		exit 1
+	fi
+
+	# Process based on agent type argument
+	local success=true
+
+	if [[ -z $AGENT_TYPE ]]; then
+		# No specific agent provided - update all existing agent files
+		log_info "No agent specified, updating all existing agent files..."
+		if ! update_all_existing_agents; then
+			success=false
+		fi
+	else
+		# Specific agent provided - update only that agent
+		log_info "Updating specific agent: $AGENT_TYPE"
+		if ! update_specific_agent "$AGENT_TYPE"; then
+			success=false
+		fi
+	fi
+
+	# Print summary
+	print_summary
+
+	if [[ $success == true ]]; then
+		log_success "Agent context update completed successfully"
+		exit 0
+	else
+		log_error "Agent context update completed with errors"
+		exit 1
+	fi
+}
+
+# Execute main function if script is run directly
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+	main "$@"
+fi

.specify/templates/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!--
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

.specify/templates/constitution-template.md

@@ -0,0 +1,73 @@
+# [PROJECT_NAME] Constitution
+
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+
+<!-- Example: I. Library-First -->
+
+[PRINCIPLE_1_DESCRIPTION]
+
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+
+<!-- Example: II. CLI Interface -->
+
+[PRINCIPLE_2_DESCRIPTION]
+
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+
+[PRINCIPLE_3_DESCRIPTION]
+
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+
+<!-- Example: IV. Integration Testing -->
+
+[PRINCIPLE_4_DESCRIPTION]
+
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+
+[PRINCIPLE_5_DESCRIPTION]
+
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/templates/plan-template.md

@@ -0,0 +1,109 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+- Safety-critical mesh impact is identified for any routing, airtime, MQTT, channel, or packet-path change.
+- Variant and platform scope are explicit, and all hardware flags or pin mappings are verified against the target board.
+- Validation evidence is defined, including the exact `pio`, native test, simulator, formatting, or static checks to run.
+- Resource, power, memory, and dependency impact are assessed for the affected targets.
+- Any constitutional violation or validation gap is documented with justification in Complexity Tracking.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation                  | Why Needed         | Simpler Alternative Rejected Because |
+| -------------------------- | ------------------ | ------------------------------------ |
+| [e.g., 4th project]        | [current need]     | [why 3 projects insufficient]        |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient]  |

.specify/templates/spec-template.md

@@ -0,0 +1,140 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing _(mandatory)_
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+For firmware and hardware-facing work, each story MUST identify affected platforms or variants
+and describe how the behavior is validated on its own.
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+- What happens when the target hardware capability is absent, misdeclared, or only present on some variants?
+- How does the system behave when radio, power, timing, or memory constraints are tighter than expected?
+
+## Requirements _(mandatory)_
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+_Example of marking unclear requirements:_
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+Where relevant, requirements MUST also state:
+
+- affected architectures, boards, or modules
+- whether behavior changes public defaults, protocol compatibility, or generated artifacts
+- any required validation evidence for high-risk mesh, hardware, or power behavior
+
+### Key Entities _(include if feature involves data)_
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria _(mandatory)_
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Assumptions
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right assumptions based on reasonable defaults
+  chosen when the feature description did not specify certain details.
+-->
+
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
+- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
+- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]
+- [Assumption about available hardware capabilities, board revisions, or build targets]

.specify/templates/tasks-template.md

@@ -0,0 +1,259 @@
+---
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: Validation tasks are REQUIRED whenever the constitution or feature risk profile demands evidence. Include targeted builds, native tests, simulator runs, protobuf regeneration checks, formatting, or other repository-standard validation appropriate to the change.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!--
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+- [ ] T00X Identify affected targets, variants, and validation commands
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+- [ ] T00X Verify board-specific flags, pins, generated assets, or protocol prerequisites needed by all stories
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Validation for User Story 1 ⚠️
+
+> **NOTE: Add the smallest credible validation for the story's risk level before declaring it complete**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test\_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test\_[name].py
+- [ ] T01X [P] [US1] Run targeted build or simulation for affected platform(s)
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+- [ ] T01Y [US1] Confirm variant-scoped behavior and configuration defaults remain correct
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Validation for User Story 2 ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test\_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test\_[name].py
+- [ ] T02X [P] [US2] Run targeted build or simulation for affected platform(s)
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+- [ ] T02Y [US2] Confirm resource, power, and compatibility impacts stay within plan constraints
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Validation for User Story 3 ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test\_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test\_[name].py
+- [ ] T03X [P] [US3] Run targeted build or simulation for affected platform(s)
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T03Y [US3] Confirm backward compatibility or explicitly document intentional behavior changes
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+- [ ] TXXX Summarize skipped validations, migration notes, and generated-file updates for review
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

.trunk/configs/.bandit

@@ -12,10 +12,10 @@
 #   defensive loops over flaky sources (pubsub handlers, device
 #   re-enumeration polls). One failed iteration shouldn't abort the loop.
 # B404 import_subprocess
-#   the bin/ proto + fixture tooling (regen-py-protos, gen-fake-nodedb-seed,
-#   seed-json-to-proto) shells out to protoc and helper scripts — subprocess
-#   is a load-bearing import here, not a smell. The "consider possible security
-#   implications" advisory is redundant given the file-level review already applied.
+#   mcp-server wraps PlatformIO, esptool, nrfutil, picotool, and the
+#   pytest test-runner — subprocess is a load-bearing import here, not
+#   a smell. The "consider possible security implications" advisory is
+#   redundant given the file-level review already applied.
 # B603 subprocess_without_shell_equals_true
 #   all subprocess calls use a static argv list; `shell=False` is the
 #   default and we never string-interpolate user input into the command.

.trunk/trunk.yaml

@@ -4,118 +4,29 @@ cli:
 plugins:
   sources:
     - id: trunk
-      ref: v1.10.2
+      ref: v1.8.0
       uri: https://github.com/trunk-io/plugins
 lint:
-  # Custom file set + formatter that rewrites Unicode em-dash (U+2014, UTF-8
-  # bytes e2 80 94) and en-dash (U+2013, UTF-8 bytes e2 80 93) to an ASCII
-  # hyphen. The sed pattern matches the byte sequences under LC_ALL=C rather
-  # than literal characters on purpose, so the rule survives editors/hooks
-  # that themselves strip Unicode dashes. These dashes only ever appear in
-  # comments and log/error strings (LLM-authored prose), never in code, so
-  # the rewrite is purely cosmetic. Runs under `trunk fmt`; enforced by
-  # `trunk check` and the trunk-fmt-pre-commit action.
-  files:
-    - name: ascii-dash-targets
-      extensions:
-        - c
-        - cc
-        - cpp
-        - h
-        - hpp
-        - ino
-        - md
-        - py
-        - sh
-        - yaml
-        - yml
-        - json
-        - toml
-        - ini
-    - name: cpp-sources
-      extensions:
-        - c
-        - cc
-        - cpp
-        - cxx
-        - h
-        - hh
-        - hpp
-        - hxx
-        - ino
-  definitions:
-    - name: ascii-dash
-      files: [ascii-dash-targets]
-      commands:
-        - name: format
-          output: rewrite
-          formatter: true
-          run: env LC_ALL=C sed -e 's/\xe2\x80\x94/-/g' -e 's/\xe2\x80\x93/-/g' ${target}
-          success_codes: [0]
-    # Flags preprocessor conditionals that contain too many defined() terms
-    # (e.g. the 13-driver display chains in main.cpp). The compiler has no
-    # warning for this; the fix is an umbrella feature macro (HAS_TFT /
-    # HAS_SCREEN, already in src/configuration.h). Tune the limit via
-    # MAX_DEFINED in bin/lint-ifdef-complexity.sh (default 5 -> warns at 6+).
-    - name: too-many-defined
-      files: [cpp-sources]
-      commands:
-        - name: lint
-          output: regex
-          parse_regex: (?P<path>.+):(?P<line>\d+):(?P<col>\d+):(?P<severity>\w+):(?P<message>.+):(?P<code>[a-z-]+)
-          run: ${workspace}/bin/lint-ifdef-complexity.sh ${target}
-          success_codes: [0]
-          read_output_from: stdout
-    # Flags node/packet IDs logged as bare %08x instead of the 0x%08x convention in
-    # src/mesh/RadioInterface.cpp. Emits "note", trunk's only non-blocking level, so it
-    # advises without gating - including on the known pre-existing sites, which are left
-    # unlisted so they get cleaned up by whoever next edits those files.
-    - name: node-id-format
-      files: [cpp-sources]
-      commands:
-        - name: lint
-          output: regex
-          parse_regex: (?P<path>.+):(?P<line>\d+):(?P<col>\d+):(?P<severity>\w+):(?P<message>.+):(?P<code>[a-z-]+)
-          run: ${workspace}/bin/lint-node-id-format.sh ${target}
-          success_codes: [0]
-          read_output_from: stdout
-    # Flags a UNITY_END() not wrapped in exit(). A bare one ends the reporting, not the suite:
-    # the runtime keeps calling loop(), so the process never exits, its sandbox is deleted
-    # underneath it, and its .gcda and LeakSanitizer report never flush. Emits "note" because the
-    # enforcing half is bin/pio-test-isolate.sh, which catches an actual survivor at run time.
-    - name: unity-exit
-      files: [cpp-sources]
-      commands:
-        - name: lint
-          output: regex
-          parse_regex: (?P<path>.+):(?P<line>\d+):(?P<col>\d+):(?P<severity>\w+):(?P<message>.+):(?P<code>[a-z-]+)
-          run: ${workspace}/bin/lint-unity-exit.sh ${target}
-          success_codes: [0]
-          read_output_from: stdout
   enabled:
-    - ascii-dash@SYSTEM
-    - too-many-defined@SYSTEM
-    - node-id-format@SYSTEM
-    - unity-exit@SYSTEM
-    - checkov@3.3.8
-    - renovate@44.2.3
-    - prettier@3.9.6
-    - trufflehog@3.96.0
+    - checkov@3.2.526
+    - renovate@43.150.0
+    - prettier@3.8.3
+    - trufflehog@3.95.2
     - yamllint@1.38.0
     - bandit@1.9.4
-    - trivy@0.72.0
+    - trivy@0.70.0
     - taplo@0.10.0
-    - ruff@0.16.0
+    - ruff@0.15.12
     - isort@8.0.1
-    - markdownlint@0.49.1
+    - markdownlint@0.48.0
     - oxipng@10.1.1
-    - svgo@4.0.2
+    - svgo@4.0.1
     - actionlint@1.7.12
     - flake8@7.3.0
     - hadolint@2.14.0
     - shfmt@3.6.0
     - shellcheck@0.11.0
-    - black@26.5.1
+    - black@26.3.1
     - git-diff-check
     - gitleaks@8.30.1
     - clang-format@16.0.3
@@ -123,44 +34,6 @@ lint:
     - linters: [ALL]
       paths:
         - bin/**
-    # Fake-NodeDB fixture JSONL files contain deterministic synthetic
-    # public_key_hex (64-char hex) values that gitleaks misidentifies as
-    # generic-api-key. These are not secrets - they're test fixtures
-    # produced by bin/gen-fake-nodedb-seed.py with a fixed RNG seed.
-    - linters: [gitleaks]
-      paths:
-        - test/fixtures/nodedb/seed_v25_*.jsonl
-    # Deliberately broken YAML: these are the inputs to bin/test-config-check.sh,
-    # which asserts that `meshtasticd --check` reports each planted fault. Prettier
-    # rejects the duplicate keys and bad indentation that are the whole point of
-    # them, so the directory is exempt. The README there is normal prose and stays
-    # linted.
-    - linters: [ALL]
-      paths:
-        - test/fixtures/portduino-config/**/*.yaml
-    # checkov/CKV_SECRET_6 flags the commented-out "large4cats" example,
-    # which is the public default credential for the meshtastic.org MQTT
-    # broker rather than a real secret. Ignore the whole file so the
-    # example config stays free of lint-suppression comments.
-    - linters: [ALL]
-      paths:
-        - userPrefs.jsonc
-    # The UA font's em/en dashes live only in trailing comments documenting
-    # each glyph's codepoint (e.g. "8212=:2549"); rewriting them would make
-    # those docs inaccurate. Glyph byte data is unaffected either way.
-    - linters: [ascii-dash]
-      paths:
-        - src/graphics/fonts/**
-    # millis()-wraparound tests pin dense clusters of hex boundary constants
-    # (0xFFFFFF00u and neighbors). trufflehog's Lob detector stitches nearby
-    # hex literals into one candidate string and the result happens to match
-    # a Lob API key shape. Not secrets - deterministic test fixtures for the
-    # 32-bit rollover.
-    - linters: [trufflehog]
-      paths:
-        - test/test_airtime/test_main.cpp
-        - test/test_throttle/test_main.cpp
-        - test/test_uptime_clock/test_main.cpp
 runtimes:
   enabled:
     - python@3.14.4

.vscode/extensions.json

@@ -1,10 +1,10 @@
 {
+    // See http://go.microsoft.com/fwlink/?LinkId=827846
+    // for the documentation about the extensions.json format
     "recommendations": [
-        "Jason2866.esp-decoder",
-        "pioarduino.pioarduino-ide"
+        "platformio.platformio-ide"
     ],
     "unwantedRecommendations": [
-        "ms-vscode.cpptools-extension-pack",
-        "platformio.platformio-ide"
+        "ms-vscode.cpptools-extension-pack"
     ]
 }

.vscode/settings.json

@@ -10,5 +10,16 @@
   },
   "[powershell]": {
     "editor.defaultFormatter": "ms-vscode.powershell"
+  },
+  "chat.promptFilesRecommendations": {
+    "speckit.constitution": true,
+    "speckit.specify": true,
+    "speckit.plan": true,
+    "speckit.tasks": true,
+    "speckit.implement": true
+  },
+  "chat.tools.terminal.autoApprove": {
+    ".specify/scripts/bash/": true,
+    ".specify/scripts/powershell/": true
   }
 }

AGENTS.md

@@ -1,99 +1,71 @@
 # Agent instructions
 
-> **TL;DR**
->
-> |                |                                                                                                                        |
-> | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
-> | Local tests    | `./bin/run-tests.sh` (exit 0 GREEN · 1 RED · 2 AMBER · 3 FILTERED)                                                     |
-> | Hardware tests | [meshtastic/meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) (`MESHTASTIC_FIRMWARE_ROOT` → this checkout) |
-> | Format         | `trunk fmt`                                                                                                            |
-> | Mirror docs    | `.github/copilot-instructions.md` (canonical) · `CLAUDE.md` (Claude Code)                                              |
->
-> **Need this? It's here.**
->
-> |                                             |                                                            |
-> | ------------------------------------------- | ---------------------------------------------------------- |
-> | General helpers (clamp, UTF-8, string fmt…) | `src/meshUtils.h`                                          |
-> | Logging macros (LOG_DEBUG / INFO / WARN…)   | `src/DebugConfiguration.h`                                 |
-> | New module skeleton                         | inherit `ProtobufModule<T>` in `src/mesh/ProtobufModule.h` |
-> | Observer / event wiring                     | `src/Observer.h`                                           |
-
-This repository is the [Meshtastic](https://meshtastic.org) firmware - a C++17 embedded codebase targeting ESP32 / nRF52 / RP2040 / STM32WL / Linux-Portduino LoRa mesh radios. The Python MCP server that AI agents use to flash, configure, and test connected devices now lives in its own repo, [meshtastic/meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp); this repo registers it via `.mcp.json` (run through `uvx`) so its tools are available automatically.
+This repository is the [Meshtastic](https://meshtastic.org) firmware — a C++17 embedded codebase targeting ESP32 / nRF52 / RP2040 / STM32WL / Linux-Portduino LoRa mesh radios — plus a Python MCP server in `mcp-server/` that AI agents use to flash, configure, and test connected devices.
 
 ## Primary instruction file
 
-**Read `.github/copilot-instructions.md` first.** That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions (naming, module framework, Observer pattern, thread safety), the build system, CI/CD, the native C++ test suite, and - most importantly for automation work - the **MCP Server & Hardware Test Harness** section. Read it top-to-bottom before starting any non-trivial change.
+**Read `.github/copilot-instructions.md` first.** That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions (naming, module framework, Observer pattern, thread safety), the build system, CI/CD, the native C++ test suite, and — most importantly for automation work — the **MCP Server & Hardware Test Harness** section. Read it top-to-bottom before starting any non-trivial change.
 
 This file (`AGENTS.md`) is a short pointer + quick reference for agents that don't read `.github/copilot-instructions.md` by default.
 
 ## Quick command reference
 
-| Action                           | Command                                                                                                                                                               |
-| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Build a firmware variant         | `pio run -e <env>` (e.g. `pio run -e rak4631`, `pio run -e heltec-v3`)                                                                                                |
-| Build native macOS host binary   | `pio run -e native-macos` (Homebrew prereqs + CH341 LoRa setup in `variants/native/portduino/platformio.ini`)                                                         |
-| Clean + rebuild                  | `pio run -e <env> -t clean && pio run -e <env>`                                                                                                                       |
-| Flash a device                   | `pio run -e <env> -t upload --upload-port <port>` (or use the `pio_flash` MCP tool)                                                                                   |
-| Run firmware unit tests (native) | `./bin/run-tests.sh` (preferred - ASan/LSan + RED/AMBER/GREEN verdict); or raw: `~/.platformio/penv/bin/python -m platformio test -e native > /tmp/test_out.txt 2>&1` |
-| Run MCP hardware tests           | From a [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) checkout: `MESHTASTIC_FIRMWARE_ROOT=/path/to/firmware ./run-tests.sh`                           |
-| Live TUI test runner             | `uvx --from git+https://github.com/meshtastic/meshtastic-mcp meshtastic-mcp-test-tui`                                                                                 |
-| Format before commit             | `trunk fmt`                                                                                                                                                           |
-| Regenerate protobuf bindings     | `bin/regen-protos.sh`                                                                                                                                                 |
-| Generate CI matrix               | `./bin/generate_ci_matrix.py all [--level pr]`                                                                                                                        |
+| Action                           | Command                                                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Build a firmware variant         | `pio run -e <env>` (e.g. `pio run -e rak4631`, `pio run -e heltec-v3`)                                        |
+| Build native macOS host binary   | `pio run -e native-macos` (Homebrew prereqs + CH341 LoRa setup in `variants/native/portduino/platformio.ini`) |
+| Clean + rebuild                  | `pio run -e <env> -t clean && pio run -e <env>`                                                               |
+| Flash a device                   | `pio run -e <env> -t upload --upload-port <port>` (or use the `pio_flash` MCP tool)                           |
+| Run firmware unit tests (native) | `pio test -e native`                                                                                          |
+| Run MCP hardware tests           | `./mcp-server/run-tests.sh`                                                                                   |
+| Live TUI test runner             | `mcp-server/.venv/bin/meshtastic-mcp-test-tui`                                                                |
+| Format before commit             | `trunk fmt`                                                                                                   |
+| Regenerate protobuf bindings     | `bin/regen-protos.sh`                                                                                         |
+| Generate CI matrix               | `./bin/generate_ci_matrix.py all [--level pr]`                                                                |
 
 ## MCP server (device + test automation)
 
-The [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) server exposes ~32 MCP tools for device discovery, building, flashing, serial monitoring, and live-node administration. Tools are grouped as:
+The `mcp-server/` package exposes ~32 MCP tools for device discovery, building, flashing, serial monitoring, and live-node administration. Tools are grouped as:
 
 - **Discovery**: `list_devices`, `list_boards`, `get_board`
 - **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 factory), `update_flash` (ESP32 OTA), `touch_1200bps`
 - **Serial sessions**: `serial_open`, `serial_read`, `serial_list`, `serial_close`
 - **Device reads**: `device_info`, `list_nodes`
 - **Device writes** (require `confirm=True`): `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `reboot`, `shutdown`, `factory_reset`, `set_debug_log_api`
-- **Frame injection**: `inject_frame` - deliver a crafted frame into a board's real RX pipeline as if received off LoRa (reaches `from != 0` / decrypt / remote-admin paths the `toRadio` API can't). Needs firmware built with `-D MESHTASTIC_ENABLE_FRAME_INJECTION=1` (`MeshService::injectAsReceived`); sim nodes always. See the copilot-instructions **Frame injection** section.
 - **userPrefs admin**: `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile`
 - **Vendor escape hatches**: `esptool_*`, `nrfutil_*`, `picotool_*`
 
-Setup: nothing to build - `.mcp.json` runs the server via `uvx --from git+https://github.com/meshtastic/meshtastic-mcp meshtastic-mcp`, so Claude Code picks it up automatically. To run the pytest hardware harness, clone [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) and set `MESHTASTIC_FIRMWARE_ROOT` to this firmware checkout.
+Setup: `cd mcp-server && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'`. The repo registers the server via `.mcp.json` — Claude Code picks it up automatically.
 
-See the meshtastic-mcp repo's README for argument shapes and the **MCP Server & Hardware Test Harness** section of `.github/copilot-instructions.md` for agent usage rules (tool surface, fixture contract, firmware integration points, recovery playbooks).
+See `mcp-server/README.md` for argument shapes and the **MCP Server & Hardware Test Harness** section of `.github/copilot-instructions.md` for agent usage rules (tool surface, fixture contract, firmware integration points, recovery playbooks).
 
 ## Slash commands (AI-assisted workflows)
 
-The test-and-diagnose workflows (`/test`, `/diagnose`, `/repro`, `/leakhunt`) now ship with the [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) repo as skills - run them from a checkout of that repo (with `MESHTASTIC_FIRMWARE_ROOT` pointed here). The MCP tools they build on are still available in this repo via `.mcp.json`.
+Three test-and-diagnose workflows exist as slash commands:
+
+- **`/test` (Claude Code) / `/mcp-test` (Copilot)** — run the hardware test suite and interpret failures
+- **`/diagnose` / `/mcp-diagnose`** — read-only device health report
+- **`/repro` / `/mcp-repro`** — flakiness triage: re-run one test N times, diff firmware logs between passes and failures
+
+Bodies live in `.claude/commands/` and `.github/prompts/` respectively. `.claude/commands/README.md` is the index.
 
 ## Encryption at a glance
 
 Two layers, both in `src/mesh/CryptoEngine.cpp`:
 
-- **Channel (symmetric)** - **AES-CTR** with a channel-wide PSK (AES-128 or AES-256). Nonce = packet_id ‖ from_node ‖ block_counter. No AEAD; integrity is soft (channel-hash filter). The well-known default PSK lives in `src/mesh/Channels.h`; a 1-byte PSK is a short-form index into it.
-- **Per-peer PKI** - **X25519 ECDH** (Curve25519, 32-byte keys) → SHA-256 → **AES-256-CCM** with an 8-byte MAC. Fresh 32-bit `extraNonce` per packet, sent in the clear alongside the MAC. 12-byte wire overhead (`MESHTASTIC_PKC_OVERHEAD`). Used for DMs. Also used for remote admin (`src/modules/AdminModule.cpp`), where AdminMessage authorization is gated by `config.security.admin_key[0..2]`. Disabled entirely in Ham mode (`user.is_licensed=true`).
+- **Channel (symmetric)** — **AES-CTR** with a channel-wide PSK (AES-128 or AES-256). Nonce = packet_id ‖ from_node ‖ block_counter. No AEAD; integrity is soft (channel-hash filter). The well-known default PSK lives in `src/mesh/Channels.h`; a 1-byte PSK is a short-form index into it.
+- **Per-peer PKI** — **X25519 ECDH** (Curve25519, 32-byte keys) → SHA-256 → **AES-256-CCM** with an 8-byte MAC. Fresh 32-bit `extraNonce` per packet, sent in the clear alongside the MAC. 12-byte wire overhead (`MESHTASTIC_PKC_OVERHEAD`). Used for DMs. Also used for remote admin (`src/modules/AdminModule.cpp`), where AdminMessage authorization is gated by `config.security.admin_key[0..2]`. Disabled entirely in Ham mode (`user.is_licensed=true`).
 
-Key rotation to never trigger casually: only the **full** factory reset (`factory_reset_device`, `eraseBleBonds=true`) wipes `security.private_key` and regenerates the keypair - every peer holds the old public key, so DMs silently fail PKI decrypt until NodeInfo re-exchanges. The **partial** config reset (`factory_reset_config`) preserves the private key and doesn't invalidate peer relationships. Explicitly blanking `security.private_key` via admin also triggers regen. See the **Encryption & Key Management** section of `.github/copilot-instructions.md` for the full spec (nonce layout, send/receive selection logic including infrastructure-portnum exceptions, admin-key + session-passkey authorization, `is_managed` scope, key-rotation hazards).
+Key rotation to never trigger casually: only the **full** factory reset (`factory_reset_device`, `eraseBleBonds=true`) wipes `security.private_key` and regenerates the keypair — every peer holds the old public key, so DMs silently fail PKI decrypt until NodeInfo re-exchanges. The **partial** config reset (`factory_reset_config`) preserves the private key and doesn't invalidate peer relationships. Explicitly blanking `security.private_key` via admin also triggers regen. See the **Encryption & Key Management** section of `.github/copilot-instructions.md` for the full spec (nonce layout, send/receive selection logic including infrastructure-portnum exceptions, admin-key + session-passkey authorization, `is_managed` scope, key-rotation hazards).
 
 ## House rules
 
-- **No destructive device operations without operator approval.** `factory_reset`, `erase_and_flash`, `reboot`, `shutdown`, history-rewriting git ops - describe the action and stop. Operator authorizes.
+- **No destructive device operations without operator approval.** `factory_reset`, `erase_and_flash`, `reboot`, `shutdown`, history-rewriting git ops — describe the action and stop. Operator authorizes.
 - **One MCP call per serial port at a time.** The port lock is exclusive; concurrent calls deadlock. Sequence: open → read/mutate → close, then next device.
 - **`userPrefs.jsonc` is session state during tests.** The `_session_userprefs` fixture snapshots + restores it; never edit it from inside a test.
 - **Don't speculate about firmware root causes.** When evidence doesn't support a classification, say "unknown" and list what would disambiguate.
-- **Run `trunk fmt` before proposing a commit.** The `trunk_check` CI gate will reject unformatted code. Claude Code runs it automatically via the PostToolUse hook in `.claude/settings.json`; trunk's launcher needs `curl` or `wget` to bootstrap its pinned CLI - see **Formatting & the trunk toolchain** in `.github/copilot-instructions.md` for the no-curl bootstrap procedure.
-- **Never edit or commit files under `src/mesh/generated/`.** They are regenerated from the [`meshtastic/protobufs`](https://github.com/meshtastic/protobufs) repo by the `update_protobufs.yml` workflow (entry point: `bin/regen-protos.sh`). Local edits will be overwritten and create merge conflicts. If a `.proto` change is needed, open a PR against the protobufs repo first, then let the workflow re-sync this repo.
+- **Run `trunk fmt` before proposing a commit.** The `trunk_check` CI gate will reject unformatted code.
 - **`confirm=True` on destructive MCP tools is a real gate, not a formality.** Don't bypass it via auto-approve settings.
-- **Keep code comments minimal - one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior.
-- **Documentation does not live in this repo. Do not add it here.** This repository holds firmware code. There is no `docs/` directory - the design documents that used to sit there were published to [meshtastic/meshtastic](https://github.com/meshtastic/meshtastic) in #11488 and the directory was deleted - and it must not come back. Do not create a `.md` file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow.
-- **Never compare against `millis()` directly. Use `Throttle`.** `src/mesh/Throttle.h` is the sanctioned way to ask about time, and CI enforces this (`millis-deadline-check` in `.github/workflows/test_native.yml` fails the PR on a new `millis() >` / `< millis()` comparison).
-  - `Throttle::isWithinTimespanMs(lastMs, intervalMs)` - true while still inside the cooldown.
-  - `Throttle::hasElapsed(lastMs, intervalMs)` - its complement, true once the interval has passed (inclusive `>=`). Prefer this to spelling `!isWithinTimespanMs(...)`.
-  - `Throttle::execute(&lastMs, intervalMs, func)` - function-pointer form that updates the timestamp on fire.
-  - `Throttle::deadlinePassed(deadlineMs)` - for a stored absolute deadline that cannot be re-expressed as "interval since an event".
-  - `Throttle::deadlinePassedAt(nowMs, deadlineMs)` - the same test against a caller-supplied `now`, for a loop that snapshots the clock once and tests many deadlines. Snapshot from `Time::getMillis()`.
-
-  Raw `millis() > deadline` or `deadline < millis()` is rollover-unsafe: the comparison inverts while the deadline sits on the far side of the 32-bit wrap, so the action fires immediately or blocks for roughly the interval it should have waited. All five helpers subtract first, so unsigned wraparound cancels out. `Throttle` reads the clock through `Time::getMillis()` (`src/UptimeClock.h`), so all ~94 of its call sites are time-injectable and a native test can drive the wrap with `Time::setTestMillis()`.
-
-  **Sentinel hazard.** If a deadline variable also encodes "inactive" (`0` for `rebootAtMsec`, `shutdownAtMsec`, `alertBannerUntil`, `fixHoldEnds`; `UINT32_MAX` for `nagCycleCutoff`), test that sentinel _before_ the elapsed comparison - every such value is arithmetically far in the past, so a correct comparison fires on it immediately. Match the test to the sentinel in use: `if (deadline && Throttle::deadlinePassed(deadline))` covers the `0` family, `nagCycleCutoff` needs `deadline != UINT32_MAX` or a separate armed flag (`isNagging`).
-
-  Then decide which way the sentinel should fall - "inactive" does not always mean "suppress". At the GPS fix-hold site `fixHoldEnds == 0` means _no hold is in force_, which is exactly when one must be armed; guarding it with `fixHoldEnds != 0 &&` looks like this rule and inverts the site. See `fixHoldInForce()` in `src/gps/GPS.cpp` and `test/test_gps_fix_hold/`.
 
 ## Typical agent workflows
 
@@ -105,9 +77,9 @@ Key rotation to never trigger casually: only the **full** factory reset (`factor
 
 ### Inspecting live node state
 
-1. `device_info(port=...)` - short summary (node num, firmware version, region, peer count)
-2. `list_nodes(port=...)` - full peer table (SNR, RSSI, pubkey presence, last_heard)
-3. `get_config(section="lora", port=...)` - LoRa settings for cross-device comparison
+1. `device_info(port=...)` — short summary (node num, firmware version, region, peer count)
+2. `list_nodes(port=...)` — full peer table (SNR, RSSI, pubkey presence, last_heard)
+3. `get_config(section="lora", port=...)` — LoRa settings for cross-device comparison
 
 Sequence these; don't parallelize on the same port.
 
@@ -115,49 +87,42 @@ Sequence these; don't parallelize on the same port.
 
 1. Build locally: `pio run -e <env>`
 2. Flash the test device: `pio_flash(env=..., port=..., confirm=True)`
-3. Run the suite from a meshtastic-mcp checkout: `MESHTASTIC_FIRMWARE_ROOT=/path/to/firmware ./run-tests.sh tests/<tier>` (or the `/test` skill)
-4. On failure, open the run's `tests/report.html` → `Meshtastic debug` section for the firmware log tail + device state dump
+3. Run the suite: `./mcp-server/run-tests.sh tests/<tier>` or `/test tests/<tier>`
+4. On failure, open `mcp-server/tests/report.html` → `Meshtastic debug` section for the firmware log tail + device state dump
 5. Iterate
 
-### Debugging a native unit-test failure
+### Debugging a flaky test
 
-1. **Run the full suite before believing a filtered one.** `-f` is not a gate: it removes the suites that _create_ the shared state a later suite trips over.
-2. **A signal name is not a crash.** `exit(UNITY_END())` returns the failure count and PlatformIO renders it as a signal (4 -> `SIGILL`, 5 -> `SIGTRAP`), reporting `[ERRORED]`. Match it against the failure count first.
-3. **Check the CLEAN/DIRTY axis.** Each suite runs in its own scratch `$HOME`; deliberate writes are declared in `test/state-manifest.tsv`. A DIRTY verdict names the suite and the undeclared path, and the kept sandbox under `.pio/test-state/<suite>/` is a replayable reproduction.
-4. **Sanitizers are per env** - `coverage` has ASan/LSan, `native` has none. Don't reason from ASan on a `-e native` run.
-5. **Reproduce a shuffled order.** `--shuffle` prints its seed and puts it on the `RESULT:` line; `--seed <n>` replays that exact order. One green seed proves nothing about order independence.
-6. **Exit 2 with "Linux-only" is the host, not the tests.** The harness needs bash 4+ and GNU coreutils/find and rejects any other `uname` rather than degrade quietly. `native-macos` is a build target, not a test host; elsewhere use `./bin/test-native-docker.sh`.
-
-### Debugging a flaky hardware test
-
-1. `/repro <test-node-id> [count]` - re-runs the test N times, diffs firmware logs between passes and failures
+1. `/repro <test-node-id> [count]` — re-runs the test N times, diffs firmware logs between passes and failures
 2. If the first attempt always fails and the rest pass, that's a state-leak pattern → suggest `--force-bake` or a clean device state, don't chase the first failure
-3. If all N fail, this isn't a flake - it's a regression. Stop iterating and escalate to `/test` for full-suite context.
+3. If all N fail, this isn't a flake — it's a regression. Stop iterating and escalate to `/test` for full-suite context.
 
 ## Where to look
 
-| Path                                                           | What's there                                                                                                                                                                                   |
-| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/`                                                         | Firmware C++ source (`mesh/`, `modules/`, `platform/`, `graphics/`, `gps/`, `motion/`, `mqtt/`, …)                                                                                             |
-| `src/mesh/`                                                    | Core: NodeDB, Router, Channels, CryptoEngine, radio interfaces, StreamAPI, PhoneAPI                                                                                                            |
-| `src/modules/`                                                 | Feature modules; `Telemetry/Sensor/` has 50+ I2C sensor drivers                                                                                                                                |
-| `variants/`                                                    | 200+ hardware variant definitions (`variant.h` + `platformio.ini` per board)                                                                                                                   |
-| `protobufs/`                                                   | `.proto` definitions; regenerate with `bin/regen-protos.sh`                                                                                                                                    |
-| `test/`                                                        | Firmware unit tests (count = the `test_*` dirs, detected on the fly; `./bin/run-tests.sh` preferred, falls back to `pio test -e native`)                                                       |
-| [meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) | Standalone MCP server + tiered pytest hardware harness (`unit/`, `mesh/`, `telemetry/`, `monitor/`, `recovery/`, `ui/`, `fleet/`, `admin/`, `provisioning/`) - registered here via `.mcp.json` |
-| `.github/prompts/`                                             | Copilot prompt bodies (firmware scaffolding: new module / sensor / variant)                                                                                                                    |
-| `.github/copilot-instructions.md`                              | **Primary agent instructions - read this**                                                                                                                                                     |
-| `.github/workflows/`                                           | CI pipelines                                                                                                                                                                                   |
-| `.mcp.json`                                                    | MCP server registration for Claude Code                                                                                                                                                        |
+| Path                              | What's there                                                                                                             |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `src/`                            | Firmware C++ source (`mesh/`, `modules/`, `platform/`, `graphics/`, `gps/`, `motion/`, `mqtt/`, …)                       |
+| `src/mesh/`                       | Core: NodeDB, Router, Channels, CryptoEngine, radio interfaces, StreamAPI, PhoneAPI                                      |
+| `src/modules/`                    | Feature modules; `Telemetry/Sensor/` has 50+ I2C sensor drivers                                                          |
+| `variants/`                       | 200+ hardware variant definitions (`variant.h` + `platformio.ini` per board)                                             |
+| `protobufs/`                      | `.proto` definitions; regenerate with `bin/regen-protos.sh`                                                              |
+| `test/`                           | Firmware unit tests (12 suites; `pio test -e native`)                                                                    |
+| `mcp-server/`                     | Python MCP server + pytest hardware integration tests                                                                    |
+| `mcp-server/tests/`               | Tiered pytest suite: `unit/`, `mesh/`, `telemetry/`, `monitor/`, `recovery/`, `ui/`, `fleet/`, `admin/`, `provisioning/` |
+| `.claude/commands/`               | Claude Code slash command bodies                                                                                         |
+| `.github/prompts/`                | Copilot prompt bodies (mirrors of the Claude Code ones)                                                                  |
+| `.github/copilot-instructions.md` | **Primary agent instructions — read this**                                                                               |
+| `.github/workflows/`              | CI pipelines                                                                                                             |
+| `.mcp.json`                       | MCP server registration for Claude Code                                                                                  |
 
 ## Recovery one-liners
 
-- **`userPrefs.jsonc` dirty after a test run?** Re-run the meshtastic-mcp harness once (pre-flight self-heals from the sidecar). If still dirty: `git checkout userPrefs.jsonc`.
+- **`userPrefs.jsonc` dirty after a test run?** Re-run `./mcp-server/run-tests.sh` once (pre-flight self-heals from the sidecar). If still dirty: `git checkout userPrefs.jsonc`.
 - **nRF52 not responding?** `mcp__meshtastic__touch_1200bps(port=...)` drops it into the DFU bootloader, then `pio_flash` re-installs.
 - **Device fully wedged (no DFU)?** `mcp__meshtastic__uhubctl_cycle(role="nrf52", confirm=True)` hard-power-cycles it via USB hub PPPS. Needs `uhubctl` installed (`brew install uhubctl` / `apt install uhubctl`); on Linux without udev rules, permission errors fail fast, so use `sudo uhubctl` yourself or configure udev access.
 - **Port busy?** `lsof <port>` to find the holder. Usually a stale `pio device monitor` or zombie `meshtastic_mcp` process. Kill it.
-- **Multiple MCP servers running?** `ps aux | grep meshtastic_mcp` - zombies hold ports. Kill all but the one your host spawned.
-- **macOS: `LIBUSB_ERROR_BUSY` on a CH341 LoRa adapter?** A third-party WCH `CH34xVCPDriver` is claiming interface 0. Find the bundle ID with `ioreg -p IOUSB -l -w 0 | grep -B2 -A30 0x5512`, then `sudo kmutil unload -b <bundleID>`. Apple's bundled CH34x kext targets the CH340 UART (PID 0x7523), not the SPI bridge - it's never the culprit.
+- **Multiple MCP servers running?** `ps aux | grep meshtastic_mcp` — zombies hold ports. Kill all but the one your host spawned.
+- **macOS: `LIBUSB_ERROR_BUSY` on a CH341 LoRa adapter?** A third-party WCH `CH34xVCPDriver` is claiming interface 0. Find the bundle ID with `ioreg -p IOUSB -l -w 0 | grep -B2 -A30 0x5512`, then `sudo kmutil unload -b <bundleID>`. Apple's bundled CH34x kext targets the CH340 UART (PID 0x7523), not the SPI bridge — it's never the culprit.
 
 ## Environment variables (test harness)
 
@@ -168,7 +133,7 @@ Sequence these; don't parallelize on the same port.
 | `MESHTASTIC_MCP_FLASH_LOG`           | File path to tee pio/esptool/nrfutil/picotool output. `run-tests.sh` sets this to `tests/flash.log` so the TUI can stream live flash progress.                                                             |
 | `MESHTASTIC_MCP_TCP_HOST`            | `host` or `host:port` of a `meshtasticd` daemon (e.g. the `native-macos` build). Surfaces it in `list_devices` as `tcp://host:port` so `connect()`-based tools target it transparently. Default port 4403. |
 | `MESHTASTIC_UHUBCTL_BIN`             | Absolute path to `uhubctl` binary. Default: PATH lookup.                                                                                                                                                   |
-| `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` | Pin a role to a specific uhubctl hub location (e.g. `1-1.3`). Wins over VID auto-detection - use when multiple devices share a VID.                                                                        |
+| `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` | Pin a role to a specific uhubctl hub location (e.g. `1-1.3`). Wins over VID auto-detection — use when multiple devices share a VID.                                                                        |
 | `MESHTASTIC_UHUBCTL_PORT_<ROLE>`     | Pin a role to a specific hub port number. Required alongside `LOCATION_<ROLE>`.                                                                                                                            |
 | `MESHTASTIC_UI_CAMERA_BACKEND`       | Camera backend for UI tier + `capture_screen` tool: `opencv` / `ffmpeg` / `null` / `auto` (default).                                                                                                       |
 | `MESHTASTIC_UI_CAMERA_DEVICE`        | Generic camera device (index or path). Used by the UI tier when no per-role var is set.                                                                                                                    |

CLAUDE.md

@@ -1,28 +0,0 @@
-# Claude Code instructions
-
-> **TL;DR**
->
-> |                |                                                                                                                        |
-> | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
-> | Local tests    | `./bin/run-tests.sh` (exit 0 GREEN · 1 RED · 2 AMBER · 3 FILTERED)                                                     |
-> | Hardware tests | [meshtastic/meshtastic-mcp](https://github.com/meshtastic/meshtastic-mcp) (`MESHTASTIC_FIRMWARE_ROOT` → this checkout) |
-> | Format         | `trunk fmt`                                                                                                            |
-> | Mirror docs    | `.github/copilot-instructions.md` (canonical) · `AGENTS.md`                                                            |
->
-> **Need this? It's here.**
->
-> |                                                           |                                                            |
-> | --------------------------------------------------------- | ---------------------------------------------------------- |
-> | General helpers (clamp, UTF-8, string fmt…)               | `src/meshUtils.h`                                          |
-> | Logging macros (LOG_DEBUG / INFO / WARN…)                 | `src/DebugConfiguration.h`                                 |
-> | Elapsed time / deadlines (never bare `millis()` compares) | `src/mesh/Throttle.h`                                      |
-> | New module skeleton                                       | inherit `ProtobufModule<T>` in `src/mesh/ProtobufModule.h` |
-> | Observer / event wiring                                   | `src/Observer.h`                                           |
-
-**Read `.github/copilot-instructions.md` first.** That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions, the build system, CI/CD, the native C++ test suite, and the MCP Server & Hardware Test Harness. Read it top-to-bottom before starting any non-trivial change.
-
-This file (`CLAUDE.md`) is a short pointer for Claude Code sessions. Slash commands live in `.claude/commands/`.
-
-## House rule: documentation does not live in this repo
-
-This repository holds firmware code. There is no `docs/` directory - the design documents that used to sit there were published to [meshtastic/meshtastic](https://github.com/meshtastic/meshtastic) in #11488 and the directory was deleted - and it must not come back. Do not create a `.md` file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow.

Dockerfile

@@ -1,5 +1,4 @@
-# trunk-ignore-all(trivy/DS-0002): We must run as root for this container
-# trunk-ignore-all(checkov/CKV_DOCKER_8): We must run as root for this container
+# trunk-ignore-all(trivy/DS002): We must run as root for this container
 # trunk-ignore-all(hadolint/DL3002): We must run as root for this container
 # trunk-ignore-all(hadolint/DL3008): Do not pin apt package versions
 # trunk-ignore-all(hadolint/DL3013): Do not pin pip package versions
@@ -15,8 +14,8 @@ ENV PIP_BREAK_SYSTEM_PACKAGES=1
 RUN apt-get update && apt-get install --no-install-recommends -y \
         curl wget g++ zip git ca-certificates pkg-config \
         python3-pip python3-grpc-tools \
-        libgpiod-dev libyaml-cpp-dev libjsoncpp-dev libbluetooth-dev libi2c-dev libuv1-dev \
-        libcurl4-gnutls-dev libusb-1.0-0-dev libulfius-dev liborcania-dev libssl-dev \
+        libgpiod-dev libyaml-cpp-dev libbluetooth-dev libi2c-dev libuv1-dev \
+        libusb-1.0-0-dev libulfius-dev liborcania-dev libssl-dev \
         libx11-dev libinput-dev libxkbcommon-x11-dev libsqlite3-dev libsdl2-dev \
     && apt-get clean && rm -rf /var/lib/apt/lists/* \
     && pip install --no-cache-dir -U platformio \
@@ -54,8 +53,8 @@ ENV TZ=Etc/UTC
 USER root
 
 RUN apt-get update && apt-get --no-install-recommends -y install \
-        libc-bin libc6 libgpiod3 libyaml-cpp0.8 libjsoncpp26 libi2c0 libuv1t64 libusb-1.0-0-dev \
-        libcurl4t64 liborcania2.3 libulfius2.7t64 libssl3t64 \
+        libc-bin libc6 libgpiod3 libyaml-cpp0.8 libi2c0 libuv1t64 libusb-1.0-0-dev \
+        liborcania2.3 libulfius2.7t64 libssl3t64 \
         libx11-6 libinput10 libxkbcommon-x11-0 libsdl2-2.0-0 \
     && apt-get clean && rm -rf /var/lib/apt/lists/* \
     && mkdir -p /var/lib/meshtasticd \

Dockerfile.test

@@ -7,7 +7,7 @@ ENV PIP_ROOT_USER_ACTION=ignore
 # hadolint ignore=DL3008
 RUN apt-get update && apt-get install --no-install-recommends -y \
         g++ git ca-certificates pkg-config \
-        libgpiod-dev libyaml-cpp-dev libjsoncpp-dev libbluetooth-dev libi2c-dev libuv1-dev \
+        libgpiod-dev libyaml-cpp-dev libbluetooth-dev libi2c-dev libuv1-dev \
         libusb-1.0-0-dev libulfius-dev liborcania-dev libssl-dev \
         libx11-dev libinput-dev libxkbcommon-x11-dev libsqlite3-dev libsdl2-dev \
     && apt-get clean && rm -rf /var/lib/apt/lists/* \

README.md

@@ -29,8 +29,8 @@ Meshtastic enables text messaging, location sharing, and telemetry over a decent
 
 ### Get Started
 
-- 🔧 **[Building Instructions](https://meshtastic.org/docs/development/firmware/build)** - Learn how to compile the firmware from source.
-- ⚡ **[Flashing Instructions](https://meshtastic.org/docs/getting-started/flashing-firmware/)** - Install or update the firmware on your device.
+- 🔧 **[Building Instructions](https://meshtastic.org/docs/development/firmware/build)** – Learn how to compile the firmware from source.
+- ⚡ **[Flashing Instructions](https://meshtastic.org/docs/getting-started/flashing-firmware/)** – Install or update the firmware on your device.
 
 Join our community and help improve Meshtastic! 🚀