Comprehensively update docs & reorganize monorepo

.github/ISSUE_TEMPLATE/design-review-request.yml

@@ -0,0 +1,118 @@
+name: Design Review Request
+description: >-
+  Request review of a design BEFORE starting layout/routing or writing/refactoring
+  code. The goal is to catch requirement
+  gaps before time is spent on implementation.
+title: "[Design Review]: "
+labels:
+  - design-review
+  - needs-review
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Fill this out **before** starting the work, not after it's done. "Not yet" is a
+        fine answer on the checklist below, just meaning a reviewer will help close
+        the gap before implementation starts.
+
+  - type: input
+    id: subsystem
+    attributes:
+      label: Subsystem
+      placeholder: e.g. EPS, ADCS, COMMS
+    validations:
+      required: true
+
+  - type: dropdown
+    id: work-type
+    attributes:
+      label: Type of work
+      options:
+        - Schematic
+        - Layout
+        - New firmware service
+        - Firmware refactor
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: target-start-date
+    attributes:
+      label: Target start date
+      placeholder: e.g. 2026-07-15
+    validations:
+      required: false
+
+  - type: input
+    id: reviewers
+    attributes:
+      label: Reviewer(s) requested
+      placeholder: "@username, @username"
+    validations:
+      required: false
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What you're about to build
+      description: One paragraph description of the change.
+    validations:
+      required: true
+
+  - type: textarea
+    id: requirements
+    attributes:
+      label: Which requirement(s) does this satisfy?
+      description: >-
+        Reference the subsystem information document. If no requirement exists yet for this
+        work, write it first.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: prework-checklist
+    attributes:
+      label: Pre-work checklist
+      description: Evaluate what's true right now.
+      options:
+        - label: >-
+            Relevant subsystem information doc section (mission context, electrical requirements,
+            part tradeoffs) exists and covers this work
+        - label: >-
+            (Hardware) Relevant part(s) selected with a documented tradeoff, or
+            reusing an already-approved part
+        - label: >-
+            (Hardware) Derating requirements for any new part identified before
+            layout begins
+        - label: >-
+            (Hardware) If this touches envelope, mass, power architecture, RBF,
+            deployment switches, or RF: CDS-compliance checklist reviewed
+        - label: >-
+            (Firmware) Interface sketched out and classified into Question/Command/Loop
+            per the event-driven refactor guideline
+        - label: >-
+            (Firmware) Proposed event UID(s) checked against the existing UID
+            registry for collisions
+        - label: Known open questions or risks are listed below
+
+  - type: textarea
+    id: open-questions
+    attributes:
+      label: Open questions / risks
+      description: >-
+        This is the most useful field for a you and the reviewer. List any questions here
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        ---
+        ### For reviewers
+        Leave the review decision as a comment on this issue, not in the form above:
+        - **Gaps identified:**
+        - **Action items before work starts:**
+        - **Cleared to proceed?** Yes / Yes with action items / No — revisit after action items resolved
+
+        Apply the `cleared-to-proceed` label and close the issue once resolved.

.github/pull_request_template.md

@@ -0,0 +1,103 @@
+<!--
+Pull Request Template
+Applies to both hardware (schematic/layout) and firmware changes.
+Fill out the Summary and Type of Change sections always.
+Only fill out the checklist section(s) that apply and delete the ones that don't.
+See the design guideline docs in /documentation for full context on any checklist item.
+-->
+
+## Summary
+
+**What changed and why:**
+
+
+**Related issue/ticket (if any):**
+
+
+## Type of Change
+
+- [ ] Hardware - schematic
+- [ ] Hardware - layout
+- [ ] Firmware - new service/module
+- [ ] Firmware - refactor of existing service/module
+- [ ] Documentation only
+- [ ] Other:
+
+**Affected subsystem(s):**
+
+## Requirements Traceability
+
+- [ ] This change is covered by an existing requirement in the subsystem's information doc
+- [ ] This change requires a **new or updated** requirement in the information doc (link/describe below)
+- [ ] This change requires an update to the CDS-compliance checklist (see [the Preliminary Hardware Design Guidelines](../documentation/design_guidelines/preliminary_hardware_design.md))
+
+---
+
+## Hardware Checklist
+*(delete this section if the PR is firmware/docs only)*
+
+Reference: [Preliminary Hardware Design Guidelines](../documentation/design_guidelines/preliminary_hardware_design.md), [Schematic & Layout Design Guidelines](../documentation/design_guidelines/schematic_layout_design.md)
+
+**Schematic**
+- [ ] All nets labeled, no floating/unlabeled nets
+- [ ] Decoupling capacitors placed per datasheet for every new/changed IC
+- [ ] Pull-up/pull-down resistors present on shared buses (I2C, reset, boot)
+- [ ] Test points/headers added for key signals (UART, RESET, SWD/JTAG, I2C, SPI) if newly introduced
+- [ ] Protection added where applicable (fuses, TVS, reverse-polarity, ESD) on any new external interface
+- [ ] Components derated per team policy (voltage/current/power margin applied, not just worst-case survival)
+- [ ] ERC is clean: no errors, no unresolved warnings
+- [ ] Peer schematic review completed by someone other than the author
+
+**Layout**
+- [ ] Stackup/impedance requirements unaffected, or explicitly re-verified if changed
+- [ ] Return paths remain short/continuous; ground plane not split
+- [ ] Decoupling caps placed close to their ICs
+- [ ] Trace widths verified against current requirements (via KiCad calculator or equivalent)
+- [ ] Silkscreen updated: polarity marks, orientation dots, version/revision number bumped
+- [ ] Assembly file exported and spot-checked for obvious placement errors
+- [ ] DFM check: in-stock parts used, no exotic footprints introduced without discussion
+
+**CDS / Mission Compliance** *(only if this change affects envelope, mass, power architecture, RBF, deployment switches, or RF)*
+- [ ] Reviewed against CDS-compliance checklist in [Preliminary Hardware Design Guidelines](../documentation/design_guidelines/preliminary_hardware_design.md)
+- [ ] No new CDS deviation introduced, or deviation documented and routed for approval
+
+---
+
+## Firmware Checklist
+*(delete this section if the PR is hardware/docs only)*
+
+Reference: [Refactoring Polling-Based Modules to be Event Driven](../documentation/design_guidelines/refactoring_polling_services.md), [Keeping the HAL Policy Free](../documentation/design_guidelines/keeping_the_hal_policy_free.md)
+
+- [ ] New/changed service interfaces classified into Question / Command / Loop per [Refactoring Polling-Based Modules to be Event Driven](../documentation/design_guidelines/refactoring_polling_services.md), with Questions removed in favor of events
+- [ ] Unique event UID chosen and confirmed non-colliding with existing services
+- [ ] Service does not poll for state and subscribes to events or system tick as appropriate
+- [ ] HAL layer changes do not publish to the event bus directly (callback-based reporting only, per [Keeping the HAL Policy Free](../documentation/design_guidelines/keeping_the_hal_policy_free.md))
+- [ ] No new blocking or long-running calls introduced inside ISR-context or tick-handler code paths
+- [ ] Watchdog/fault-handling behavior considered for this service (does a stall or fault get detected upstream?)
+- [ ] Unit tested and/or tested on hardware; results summarized below
+
+**Test summary:**
+
+
+---
+
+## ATP / Bring-Up Impact
+
+- [ ] This change affects a board/unit that already has a released ATP: ATP updated or flagged for update
+- [ ] This change was verified via bring-up/test procedure (attach results or link)
+- [ ] No impact to existing ATP
+
+## Deviations
+
+List any deviation from the design guideline docs introduced by this PR, with justification. Leave blank if none.
+
+| Guideline doc | Deviation | Justification | Approved by |
+|---|---|---|---|
+| | | | |
+
+
+## Reviewer Sign-off
+
+- [ ] I reviewed this PR against the relevant checklist section(s) above, not just the diff
+- [ ] Any checked-but-not-actually-verified items were flagged and discussed with the author
+- [ ] No open anomalies/deviations without an approver

.github/workflows/build_and_docs.yml

@@ -1,4 +1,4 @@
-name: EPS Build and Generate Documentation
+name: Subsystem Build and Generate Documentation
 
 on:
   push:
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: recursive
         fetch-depth: 0
@@ -22,64 +22,48 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install -y gcc-arm-none-eabi doxygen python3-pip cmake make g++
-        pip3 install -r eps/documentation/sphinx/requirements.txt
 
-    - name: Configure CMake for ARM
-      run: cmake -B eps/firmware/build_arm -S eps/firmware -DCMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/eps/firmware/arm-none-eabi-toolchain.cmake
+    - name: Run builds, tests, and documentation generation
+      env:
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
+        GITHUB_BASE_REF: ${{ github.base_ref }}
+        GITHUB_EVENT_BEFORE: ${{ github.event.before }}
+        GITHUB_SHA: ${{ github.sha }}
+        GITHUB_EVENT_NUMBER: ${{ github.event.number }}
+      run: ./.github/workflows/build_and_test.sh
 
-    - name: Build firmware for ARM
-      run: cmake --build eps/firmware/build_arm
-
-    - name: Configure CMake for Host/HITL
-      run: cmake -B eps/firmware/build_hitl -S eps/firmware -DTARGET_ARCH=HOST -DBUILD_HITL=ON
-
-    - name: Build Host/HITL Tests
-      run: cmake --build eps/firmware/build_hitl
-
-    - name: Run CTest
-      run: |
-        cd eps/firmware/build_hitl
-        ctest --output-on-failure
-
-    - name: Generate documentation
-      # documentation is generated from the main firmware build (ARM in this case)
-      run: cmake --build eps/firmware/build_arm --target docs
-
-    - name: Upload Doxygen documentation
+    - name: Upload Generated Documentation
       uses: actions/upload-artifact@v4
       with:
-        name: doxygen-documentation
-        path: eps/documentation/doxygen_output/
-
-    - name: Upload Sphinx documentation
-      uses: actions/upload-artifact@v4
-      with:
-        name: sphinx-documentation
-        path: eps/firmware/build_arm/documentation/sphinx/
+        name: generated-documentation
+        path: docs_out/
+        if-no-files-found: ignore
 
     - name: Deploy to GitHub Pages
       uses: peaceiris/actions-gh-pages@v4
-      if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+      if: (github.ref == 'refs/heads/main' || github.event_name == 'pull_request')
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: eps/firmware/build_arm/documentation/sphinx/
+        publish_dir: docs_out/
         destination_dir: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || '.' }}
         keep_files: true
 
-    - name: Post Preview Link
+    - name: Post Preview Links
       if: github.event_name == 'pull_request'
       uses: actions/github-script@v7
       with:
         script: |
-          const prNumber = context.issue.number;
-          const repo = context.repo.repo;
-          const owner = context.repo.owner;
-
-          const pageUrl = `https://${owner}.github.io/${repo}/pr-${prNumber}/`;
-
-          github.rest.issues.createComment({
-            owner,
-            repo,
-            issue_number: prNumber,
-            body: `**Documentation Preview:** [View Here](${pageUrl})`
-          });
+          const fs = require('fs');
+          if (fs.existsSync('pr_comment.md')) {
+            const body = fs.readFileSync('pr_comment.md', 'utf8');
+            const prNumber = context.issue.number;
+            const repo = context.repo.repo;
+            const owner = context.repo.owner;
+
+            github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: prNumber,
+              body: body
+            });
+          }