refactor: move firmware workspace under firmware

.github/workflows/sitl-smoke.yml

@@ -18,6 +18,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Check host-SITL contracts
+        working-directory: firmware
         run: |
           python3 -m unittest tools/sitl/test_kaptan_sim.py
           python3 tools/sitl/world-structure-test.py
@@ -37,4 +38,4 @@ jobs:
           cargo test --locked -p kaptan-sitl
 
       - name: Run Docker closed-loop smoke
-        run: tools/sitl/e2e-smoke.sh
+        run: firmware/tools/sitl/e2e-smoke.sh

docs/src/boards/geprc-f722-v2.md

@@ -9,9 +9,10 @@ schedule, and an `INFO` optional-log threshold. The platform verifies these
 values against the checked SPI3/USART2 typestate route before it enables
 peripherals. They are compiled image policy, not ground-station parameters.
 
-Build and package from the workspace root:
+Build and package from the firmware workspace:
 
 ```sh
+cd firmware
 cargo build --release -p kaptan-geprc-f722-v2 --target thumbv7em-none-eabihf
 ./scripts/create-dfu-image.sh target/thumbv7em-none-eabihf/release/kaptan-geprc-f722-v2
 ```

docs/src/boards/kakute-f7-mini-v3.md

@@ -3,7 +3,7 @@
 The Holybro Kakute F7 Mini V3 board declaration uses the MPU-6000 on SPI1,
 MAVLink telemetry on USART1, and the MTF01 range/optical-flow route on UART4.
 The checked-in manufacturer datasheet is
-`boards/kakute-f7-mini-v3/datasheet.pdf`.
+`firmware/boards/kakute-f7-mini-v3/datasheet.pdf`.
 
 Its immutable board policy selects the MPU-6000 body-aligned mount, logical
 MAVLink `Serial1`, endpoint `1/1`, 115200 baud, the documented telemetry
@@ -13,9 +13,10 @@ peripherals. They are compiled image policy, not ground-station parameters.
 
 ## Build and package
 
-From the workspace root:
+From the firmware workspace:
 
 ```sh
+cd firmware
 cargo build --release -p kaptan-kakute-f7-mini-v3 --target thumbv7em-none-eabihf
 ./scripts/create-dfu-image.sh target/thumbv7em-none-eabihf/release/kaptan-kakute-f7-mini-v3
 ```

docs/src/development.md

@@ -3,6 +3,7 @@
 ## Fast host checks
 
 ```sh
+cd firmware
 cargo test --workspace --offline
 cargo clippy --workspace --all-targets --offline --exclude kaptan-geprc-f722-v2 --exclude kaptan-kakute-f7-mini-v3 -- -D warnings
 cargo clippy -p platform-stm32f7 --all-targets --offline -- -D warnings
@@ -13,6 +14,7 @@ git diff --check
 ## Target checks
 
 ```sh
+cd firmware
 cargo check -p kaptan-geprc-f722-v2 --release --target thumbv7em-none-eabihf --offline
 cargo check -p kaptan-kakute-f7-mini-v3 --release --target thumbv7em-none-eabihf --offline
 ```
@@ -20,6 +22,7 @@ cargo check -p kaptan-kakute-f7-mini-v3 --release --target thumbv7em-none-eabihf
 ## Strict core coverage
 
 ```sh
+cd firmware
 scripts/report-test-coverage.sh
 ```
 
@@ -32,6 +35,7 @@ the gate.
 ## Simulation acceptance
 
 ```sh
+cd firmware
 python3 tools/sitl/world-structure-test.py
 python3 -m unittest tools/sitl/test_kaptan_sim.py
 tools/sitl/e2e-smoke.sh

docs/src/getting-started.md

@@ -2,12 +2,13 @@
 
 ## Prerequisites
 
-Use the repository toolchain, Rust 1.90. The workspace declares the embedded
+Use the firmware toolchain, Rust 1.90. The firmware workspace declares the
-F7 targets and `llvm-tools-preview` in `rust-toolchain.toml`.
+embedded F7 targets and `llvm-tools-preview` in `firmware/rust-toolchain.toml`.
 
 For host development, run:
 
 ```sh
+cd firmware
 cargo test --workspace --offline
 cargo clippy --workspace --all-targets --offline --exclude kaptan-geprc-f722-v2 --exclude kaptan-kakute-f7-mini-v3 -- -D warnings
 ```
@@ -19,10 +20,11 @@ target-specific commands in [Development and verification](development.md).
 
 | Path | Responsibility |
 | --- | --- |
-| `boards/` | Immutable board declarations and linker layouts. |
+| `firmware/boards/` | Immutable board declarations and linker layouts. |
-| `platforms/stm32f7/` | Reviewed F722 RTIC platform and peripheral ownership. |
+| `firmware/platforms/stm32f7/` | Reviewed F722 RTIC platform and peripheral ownership. |
-| `libs/` | Typed math, estimation, control, safety, protocol, and driver crates. |
+| `firmware/libs/` | Typed math, estimation, control, safety, protocol, and driver crates. |
-| `tools/sitl/` | Host-only closed-loop Gazebo simulation. |
+| `firmware/tools/sitl/` | Host-only closed-loop Gazebo simulation. |
+| `ground-suite/` | Desktop ground-control application. |
 | `docs/` | This Markdown documentation site. |
 
 Do not add board-local READMEs. Add a page here instead, then link it from

docs/src/index.md

@@ -12,6 +12,8 @@ Markdown.
 ## Index
 
 - New contributors should read [Getting started](getting-started.md).
+- Firmware source and its Rust workspace begin in `firmware/`; the desktop
+  application is a sibling project in `ground-suite/`.
 - Board work belongs under [Boards](boards/index.md).
 - The currently supported closed-loop simulation is [Host SITL](sitl.md).
 - [Configuration](configuration.md) distinguishes the current SITL profile
@@ -22,9 +24,11 @@ Markdown.
 
 ## Documentation conventions
 
-Documentation is centralized in `docs/src/`; source directories do not carry
+Documentation is centralized in `docs/src/`; individual crates and board
-README files. Keep pages in Markdown, add each page to `SUMMARY.md`, and place
+directories do not carry README files. The top-level `firmware/README.md`
-commands beside the assumptions and safety boundary they depend on.
+only defines the firmware workspace boundary. Keep pages in Markdown, add each
+page to `SUMMARY.md`, and place commands beside the assumptions and safety
+boundary they depend on.
 
 The current configuration contract is intentionally deployment-specific. A
 SITL Quad-X profile is a bounded restart-only CBOR snapshot; F722 hardware

docs/src/reference.md

@@ -20,6 +20,7 @@ upload sequence, [Logs](logs.md) for receiver decoding and filtering, and
 Before review, run:
 
 ```sh
+cd firmware
 cargo fmt --all --check
 cargo test --workspace --locked --offline
 cargo clippy --workspace --all-targets --locked -- -D warnings

docs/src/safety-boundary.md

@@ -17,6 +17,7 @@ arming-sequence reference. It does not grant hardware access or authority.
 Run the structural guard after any platform or board change:
 
 ```sh
+cd firmware
 cargo test -p platform-stm32f7 --test platform_safety_boundary --offline
 ```
 

docs/src/sitl.md

@@ -11,6 +11,7 @@ It is a pre-bench software gate, not a physical-flight validation.
 ## Run the closed loop
 
 ```sh
+cd firmware
 docker compose -f tools/sitl/compose.yaml up -d --build
 tools/sitl/kaptan-sim ready
 tools/sitl/kaptan-sim move 5 3 1 --wait
@@ -21,6 +22,7 @@ docker compose -f tools/sitl/compose.yaml down
 For the reproducible command-path gate, use:
 
 ```sh
+cd firmware
 tools/sitl/e2e-smoke.sh
 ```
 

firmware/README.md

@@ -0,0 +1,26 @@
+# Firmware
+
+This directory is the Kaptan flight-controller firmware workspace. It owns the
+Rust workspace manifest, board declarations, platform implementation, reusable
+firmware crates, simulator, firmware scripts, and firmware test fixtures.
+
+```text
+firmware/
+├── boards/     immutable board declarations and linker layouts
+├── libs/       reusable no_std firmware crates
+├── platforms/  hardware platform composition
+├── tools/      SITL and firmware development tooling
+├── scripts/    packaging, analysis, and coverage helpers
+└── tests/      firmware integration-test fixtures
+```
+
+Run Cargo commands from this directory:
+
+```sh
+cd firmware
+cargo test --workspace --locked --offline
+```
+
+The sibling `ground-suite/` directory is the desktop ground-control
+application. It is intentionally a separate project and does not participate
+in the firmware Cargo workspace.