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

.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/prompts/hardware-support.prompt.md

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

.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_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,18 +15,32 @@ 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@v6
@@ -42,37 +51,14 @@ 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 != '' }}
@@ -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:

.github/workflows/test_native.yml

@@ -86,13 +86,7 @@ jobs:
         run: sed -i 's/-DBUILD_EPOCH=$UNIX_TIME/#-DBUILD_EPOCH=$UNIX_TIME/' platformio.ini
 
       - name: PlatformIO Tests
-        run: |
-          set -o pipefail
-          # Filter out SKIPPED summary rows for hardware variants that can't run on the
-          # native host. They flood the log and make it harder to spot real failures.
-          # The JUnit XML is written directly to testreport.xml before the pipe, so
-          # the test artifact is unaffected.
-          platformio test -e coverage -v --junit-output-path testreport.xml 2>&1 | grep -v "[[:space:]]SKIPPED$"
+        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

.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

.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
   }
 }

bin/board_intake.py

@@ -0,0 +1,628 @@
+#!/usr/bin/env python3
+"""Board intake assessment for new Meshtastic hardware support.
+
+Validates a board intake request against the repository hardware context,
+identifies evidence gaps, and produces a structured readiness report.
+
+Usage:
+    python3 bin/board_intake.py <intake.json>
+    python3 bin/board_intake.py <intake.json> --output report.md
+    python3 bin/board_intake.py <intake.json> --validate   # gaps check only, exit 1 if not scaffold_ready
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_CONTEXT_PATH = ROOT / "docs" / "hardware-support-context.md"
+
+# Metadata keys every new PlatformIO environment should declare.
+REQUIRED_METADATA_KEYS = [
+    "custom_meshtastic_hw_model",
+    "custom_meshtastic_hw_model_slug",
+    "custom_meshtastic_architecture",
+    "custom_meshtastic_actively_supported",
+    "custom_meshtastic_support_level",
+    "custom_meshtastic_display_name",
+]
+
+RECOMMENDED_METADATA_KEYS = [
+    "custom_meshtastic_images",
+    "custom_meshtastic_tags",
+    "custom_meshtastic_requires_dfu",
+    "custom_meshtastic_partition_scheme",
+]
+
+# Pin groups that should be backed by evidence before scaffolding.
+EVIDENCE_CATEGORIES = ["radio", "display", "input", "GPS", "power"]
+
+# Architecture families that rely on BSP defaults for many pin defines.
+BSP_DEFAULT_FAMILIES = {"nrf52840", "rp2040", "stm32", "native"}
+
+# Known valid architectures from the repository.
+KNOWN_ARCHITECTURES = {
+    "esp32",
+    "esp32-s3",
+    "esp32-c3",
+    "esp32-c6",
+    "esp32s2",
+    "nrf52840",
+    "rp2040",
+    "rp2350",
+    "stm32",
+    "native",
+}
+
+
+# ---------------------------------------------------------------------------
+# T004 – BoardIntakeRequest dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BoardIntakeRequest:
+    """Maintainer-supplied description of a proposed new board."""
+
+    # Required
+    environment_name: str
+    hardware_model: str
+    display_name: str
+    architecture: str
+
+    # Recommended
+    hardware_model_slug: str = ""
+    actively_supported: bool | None = None
+    support_level: str = ""
+    source_materials: list[str] = field(default_factory=list)
+    board_notes: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BoardIntakeRequest":
+        return cls(
+            environment_name=data.get("environment_name", ""),
+            hardware_model=str(data.get("hardware_model", "")),
+            display_name=data.get("display_name", ""),
+            architecture=data.get("architecture", ""),
+            hardware_model_slug=data.get("hardware_model_slug", ""),
+            actively_supported=data.get("actively_supported"),
+            support_level=str(data.get("support_level", "")),
+            source_materials=list(data.get("source_materials", [])),
+            board_notes=data.get("board_notes", ""),
+        )
+
+    @classmethod
+    def from_json(cls, path: Path) -> "BoardIntakeRequest":
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return cls.from_dict(data)
+
+
+# ---------------------------------------------------------------------------
+# T005 – EvidenceGap dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EvidenceGap:
+    """A specific missing, conflicting, or ambiguous hardware fact."""
+
+    category: str  # metadata | radio | display | input | GPS | power | storage | connectivity | revision-scope
+    description: str
+    affected_artifact: str
+    required_evidence: str
+    blocking: bool
+
+
+# ---------------------------------------------------------------------------
+# T006 – IntakeAssessment dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class IntakeAssessment:
+    """Structured result of evaluating a BoardIntakeRequest."""
+
+    request: BoardIntakeRequest
+    expected_artifacts: list[str]
+    required_metadata: list[str]
+    matched_patterns: list[dict]
+    evidence_gaps: list[EvidenceGap]
+    risk_flags: list[str]
+    next_actions: list[str]
+    scaffold_ready: bool
+
+
+# ---------------------------------------------------------------------------
+# T007 – load_hardware_context
+# ---------------------------------------------------------------------------
+
+
+def load_hardware_context(path: Path = DEFAULT_CONTEXT_PATH) -> dict:
+    """Parse the generated hardware-support-context.md into a usable dict.
+
+    Returns:
+        {
+            "architecture_names": list[str],  # families present in the inventory
+            "metadata_keys": list[str],       # custom_meshtastic_* keys observed
+            "environments": dict[str, dict],  # env_name -> {display, hw_model, hw_slug, variant_dir, arch}
+        }
+    """
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Hardware context not found at {path}. "
+            "Run: python3 bin/generate_hardware_support_context.py"
+        )
+
+    text = path.read_text(encoding="utf-8")
+
+    # Extract metadata keys from the "## Repository Metadata Inputs" section.
+    metadata_keys: list[str] = re.findall(r"`(custom_meshtastic_[^`]+)`", text)
+    metadata_keys = list(dict.fromkeys(metadata_keys))  # deduplicate, preserve order
+
+    # Extract architecture families from the "## Architecture and Environment Inventory" section.
+    arch_names: list[str] = re.findall(r"^### ([a-z0-9\-]+)\s*$", text, re.MULTILINE)
+    # Filter out sub-headings that are architecture names (exclude e.g. "nrf52840" inside examples)
+    # The inventory section has short arch names; filter to known set plus any that look like archs.
+    arch_names = [a for a in dict.fromkeys(arch_names) if not a[0].isupper()]
+
+    # Extract environments from inventory table rows.
+    environments: dict[str, dict] = {}
+    current_arch = ""
+    for line in text.splitlines():
+        arch_match = re.match(r"^### ([a-z0-9\-]+)\s*$", line)
+        if arch_match:
+            current_arch = arch_match.group(1)
+            continue
+        # Table row: | env | display | hw_model | hw_slug | variant_dir | categories |
+        row = re.match(
+            r"^\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|",
+            line,
+        )
+        if (
+            row
+            and not row.group(1).startswith("Environment")
+            and not row.group(1).startswith("---")
+        ):
+            env_name = row.group(1).strip()
+            if env_name:
+                environments[env_name] = {
+                    "display_name": row.group(2).strip(),
+                    "hw_model": row.group(3).strip(),
+                    "hw_slug": row.group(4).strip(),
+                    "variant_dir": row.group(5).strip(),
+                    "architecture": current_arch,
+                }
+
+    return {
+        "architecture_names": arch_names,
+        "metadata_keys": metadata_keys,
+        "environments": environments,
+    }
+
+
+# ---------------------------------------------------------------------------
+# T018 – validate_intake
+# ---------------------------------------------------------------------------
+
+
+def validate_intake(request: BoardIntakeRequest, context: dict) -> list[str]:
+    """Check required fields and detect conflicts with existing environments/models.
+
+    Returns a list of validation error strings (empty = valid).
+    """
+    errors: list[str] = []
+
+    if not request.environment_name:
+        errors.append("environment_name is required.")
+    if not request.hardware_model:
+        errors.append("hardware_model is required.")
+    if not request.display_name:
+        errors.append("display_name is required.")
+    if not request.architecture:
+        errors.append("architecture is required.")
+
+    if request.architecture and request.architecture not in KNOWN_ARCHITECTURES:
+        errors.append(
+            f"architecture '{request.architecture}' is not a known repository architecture. "
+            f"Known: {', '.join(sorted(KNOWN_ARCHITECTURES))}"
+        )
+
+    # Conflict: environment name already exists
+    if request.environment_name and request.environment_name in context.get(
+        "environments", {}
+    ):
+        errors.append(
+            f"environment_name '{request.environment_name}' already exists in the repository. "
+            "Choose a unique name or confirm this is an intentional update."
+        )
+
+    # Conflict: hardware model already assigned to a different environment
+    if request.hardware_model:
+        for env_name, env_data in context.get("environments", {}).items():
+            if (
+                env_data.get("hw_model") == request.hardware_model
+                and env_name != request.environment_name
+            ):
+                errors.append(
+                    f"hardware_model '{request.hardware_model}' is already assigned to "
+                    f"environment '{env_name}' ({env_data.get('display_name', '')!r}). "
+                    "Verify this is a new model number or confirm the shared-model intent."
+                )
+                break  # report once
+
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# T019 – find_matched_patterns
+# ---------------------------------------------------------------------------
+
+
+def find_matched_patterns(request: BoardIntakeRequest, context: dict) -> list[dict]:
+    """Return up to 3 existing environments closest to the request by architecture."""
+    envs = context.get("environments", {})
+    arch = request.architecture
+
+    # Prefer exact architecture match, then partial (e.g., "esp32" matches "esp32-s3").
+    exact: list[dict] = []
+    partial: list[dict] = []
+    for env_name, env_data in envs.items():
+        entry = {**env_data, "environment": env_name}
+        env_arch = env_data.get("architecture", "")
+        if env_arch == arch:
+            exact.append(entry)
+        elif arch and (env_arch.startswith(arch) or arch.startswith(env_arch)):
+            partial.append(entry)
+
+    candidates = exact + partial
+    # Prefer boards that have a display_name and hw_model (more complete entries).
+    candidates.sort(key=lambda e: (not e.get("display_name"), not e.get("hw_model")))
+    return candidates[:3]
+
+
+# ---------------------------------------------------------------------------
+# T020 – build_evidence_gaps
+# ---------------------------------------------------------------------------
+
+
+def build_evidence_gaps(request: BoardIntakeRequest) -> list[EvidenceGap]:
+    """Identify missing pin-group evidence and metadata gaps."""
+    gaps: list[EvidenceGap] = []
+    has_sources = bool(request.source_materials)
+
+    if not has_sources:
+        # Every pin category is unresolvable without sources.
+        for cat in EVIDENCE_CATEGORIES:
+            gaps.append(
+                EvidenceGap(
+                    category=cat,
+                    description=(
+                        f"No source materials supplied. {cat.capitalize()} pin mappings cannot be "
+                        "verified without a schematic, pinout diagram, or vendor datasheet."
+                    ),
+                    affected_artifact="variant.h",
+                    required_evidence="Schematic, pinout image, or vendor board page",
+                    blocking=True,
+                )
+            )
+    else:
+        # Sources exist but may still be incomplete; flag as non-blocking advisory.
+        for cat in EVIDENCE_CATEGORIES:
+            gaps.append(
+                EvidenceGap(
+                    category=cat,
+                    description=(
+                        f"Source materials are present but {cat} pin assignments have not been "
+                        "extracted and cross-checked against repository macro conventions."
+                    ),
+                    affected_artifact="variant.h",
+                    required_evidence=f"Explicit {cat} pin listing matched to repository #define names",
+                    blocking=False,
+                )
+            )
+
+    # Metadata gaps
+    if not request.hardware_model_slug:
+        gaps.append(
+            EvidenceGap(
+                category="metadata",
+                description="hardware_model_slug is not set. The repository requires an UPPER_SNAKE_CASE slug for PlatformIO metadata.",
+                affected_artifact="platformio.ini (custom_meshtastic_hw_model_slug)",
+                required_evidence="Agreed slug from the project maintainers",
+                blocking=True,
+            )
+        )
+
+    if request.actively_supported is None:
+        gaps.append(
+            EvidenceGap(
+                category="metadata",
+                description="actively_supported is not specified. This controls CI matrix inclusion.",
+                affected_artifact="platformio.ini (custom_meshtastic_actively_supported)",
+                required_evidence="Maintainer decision on support status",
+                blocking=False,
+            )
+        )
+
+    if not request.support_level:
+        gaps.append(
+            EvidenceGap(
+                category="metadata",
+                description="support_level is not specified (expected: 1 = active, 2 = supported, 3 = extra).",
+                affected_artifact="platformio.ini (custom_meshtastic_support_level)",
+                required_evidence="Maintainer decision on support tier",
+                blocking=False,
+            )
+        )
+
+    # Revision-scope: multiple display/radio options without disambiguation.
+    # Match whole-word choice language rather than raw substrings so normal text
+    # like "radio" does not trigger the ambiguity gate.
+    note_text = request.board_notes.lower()
+    revision_scope_patterns = (
+        r"\brevision\b",
+        r"\bvariant\b",
+        r"\bvariants\b",
+        r"\boption\b",
+        r"\boptions\b",
+        r"\balternative\b",
+        r"\balternatives\b",
+        r"\bmulti\b",
+        r"\btwo\b",
+        r"\beither\b",
+        r"\bor\b",
+    )
+    if note_text and any(re.search(pattern, note_text) for pattern in revision_scope_patterns):
+        gaps.append(
+            EvidenceGap(
+                category="revision-scope",
+                description=(
+                    "Board notes mention multiple variants, revisions, or options. "
+                    "The intake must be scoped to a single hardware revision before scaffolding can proceed."
+                ),
+                affected_artifact="variant.h, platformio.ini",
+                required_evidence="Explicit decision on which revision this intake covers",
+                blocking=True,
+            )
+        )
+
+    return gaps
+
+
+# ---------------------------------------------------------------------------
+# T021 – assess_intake
+# ---------------------------------------------------------------------------
+
+
+def assess_intake(request: BoardIntakeRequest, context: dict) -> IntakeAssessment:
+    """Produce a full structured assessment from intake request and context."""
+    validation_errors = validate_intake(request, context)
+    matched = find_matched_patterns(request, context)
+    gaps = build_evidence_gaps(request)
+
+    expected_artifacts = [
+        f"variants/{request.architecture or '<architecture>'}/<variant-dir>/variant.h",
+        f"variants/{request.architecture or '<architecture>'}/<variant-dir>/platformio.ini (env:{request.environment_name or '<env>'})",
+    ]
+    if request.architecture in {"esp32", "esp32-s3", "esp32-c3", "esp32-c6"}:
+        expected_artifacts.append(
+            "(optional) variants/.../variant.cpp — only if board requires custom init hooks"
+        )
+    expected_artifacts += [
+        "PlatformIO metadata: all required custom_meshtastic_* keys (see required_metadata below)",
+        "(optional) board image under branding/ or images/ if custom_meshtastic_images is set",
+    ]
+
+    required_metadata = list(REQUIRED_METADATA_KEYS)
+    if request.architecture in BSP_DEFAULT_FAMILIES:
+        required_metadata.append(
+            f"(BSP note) {request.architecture} boards may inherit some pin defines from BSP headers — "
+            "check the Inherited Defaults section of docs/hardware-support-context.md before assuming a missing define is an error."
+        )
+
+    risk_flags: list[str] = []
+    for err in validation_errors:
+        risk_flags.append(f"Validation error: {err}")
+    if request.architecture in BSP_DEFAULT_FAMILIES:
+        risk_flags.append(
+            f"Architecture '{request.architecture}' uses BSP defaults for some pin defines. "
+            "Verify which macros are inherited before declaring them explicitly in variant.h."
+        )
+    if not matched:
+        risk_flags.append(
+            "No closely matched existing board found for this architecture. "
+            "Manual review of variant structure is required."
+        )
+
+    next_actions: list[str] = []
+    if validation_errors:
+        next_actions.append("Resolve validation errors before proceeding.")
+    blocking_gaps = [g for g in gaps if g.blocking]
+    non_blocking_gaps = [g for g in gaps if not g.blocking]
+    for gap in blocking_gaps:
+        next_actions.append(
+            f"Provide {gap.required_evidence} for {gap.category} ({gap.affected_artifact})."
+        )
+    if non_blocking_gaps:
+        next_actions.append(
+            f"Review {len(non_blocking_gaps)} non-blocking gap(s) before merging scaffold output."
+        )
+    if not next_actions:
+        next_actions.append(
+            "All required evidence is present. Proceed to scaffold generation."
+        )
+
+    scaffold_ready = len(validation_errors) == 0 and all(not g.blocking for g in gaps)
+
+    return IntakeAssessment(
+        request=request,
+        expected_artifacts=expected_artifacts,
+        required_metadata=required_metadata,
+        matched_patterns=matched,
+        evidence_gaps=gaps,
+        risk_flags=risk_flags,
+        next_actions=next_actions,
+        scaffold_ready=scaffold_ready,
+    )
+
+
+# ---------------------------------------------------------------------------
+# T022 – render_assessment_markdown
+# ---------------------------------------------------------------------------
+
+
+def render_assessment_markdown(assessment: IntakeAssessment) -> str:
+    req = assessment.request
+    lines: list[str] = []
+
+    lines.append(f"# Board Intake Assessment: `{req.environment_name or '(unnamed)'}`")
+    lines.append("")
+    lines.append(
+        f"**Scaffold ready**: {'✅ Yes' if assessment.scaffold_ready else '❌ No — see blocking gaps below'}"
+    )
+    lines.append("")
+
+    lines.append("## Request Summary")
+    lines.append("")
+    lines.append(f"- **Environment name**: `{req.environment_name}`")
+    lines.append(f"- **Hardware model**: `{req.hardware_model}`")
+    lines.append(
+        f"- **Hardware model slug**: `{req.hardware_model_slug or '(not set)'}`"
+    )
+    lines.append(f"- **Display name**: {req.display_name}")
+    lines.append(f"- **Architecture**: `{req.architecture}`")
+    if req.actively_supported is not None:
+        lines.append(f"- **Actively supported**: {req.actively_supported}")
+    if req.support_level:
+        lines.append(f"- **Support level**: {req.support_level}")
+    if req.source_materials:
+        lines.append("- **Source materials**:")
+        for src in req.source_materials:
+            lines.append(f"  - {src}")
+    if req.board_notes:
+        lines.append(f"- **Board notes**: {req.board_notes}")
+    lines.append("")
+
+    lines.append("## Expected Artifacts")
+    lines.append("")
+    for artifact in assessment.expected_artifacts:
+        lines.append(f"- {artifact}")
+    lines.append("")
+
+    lines.append("## Required Metadata")
+    lines.append("")
+    for key in assessment.required_metadata:
+        lines.append(
+            f"- `{key}`" if key.startswith("custom_meshtastic") else f"- {key}"
+        )
+    lines.append("")
+
+    lines.append("## Matched Repository Patterns")
+    lines.append("")
+    if assessment.matched_patterns:
+        for pattern in assessment.matched_patterns:
+            name = pattern.get("display_name") or pattern.get("environment", "")
+            env = pattern.get("environment", "")
+            arch = pattern.get("architecture", "")
+            vdir = pattern.get("variant_dir", "")
+            lines.append(f"- **{name}** (`{env}`, {arch}) — `{vdir}`")
+    else:
+        lines.append("- No closely matched patterns found for this architecture.")
+    lines.append("")
+
+    blocking = [g for g in assessment.evidence_gaps if g.blocking]
+    non_blocking = [g for g in assessment.evidence_gaps if not g.blocking]
+
+    lines.append("## Evidence Gaps")
+    lines.append("")
+    if blocking:
+        lines.append("### Blocking")
+        lines.append("")
+        for gap in blocking:
+            lines.append(f"- **[{gap.category}]** {gap.description}")
+            lines.append(f"  - Affected: `{gap.affected_artifact}`")
+            lines.append(f"  - Required evidence: {gap.required_evidence}")
+    else:
+        lines.append("*No blocking evidence gaps.*")
+    lines.append("")
+    if non_blocking:
+        lines.append("### Non-blocking (review before merge)")
+        lines.append("")
+        for gap in non_blocking:
+            lines.append(f"- **[{gap.category}]** {gap.description}")
+            lines.append(f"  - Affected: `{gap.affected_artifact}`")
+            lines.append(f"  - Required evidence: {gap.required_evidence}")
+        lines.append("")
+
+    if assessment.risk_flags:
+        lines.append("## Risk Flags")
+        lines.append("")
+        for flag in assessment.risk_flags:
+            lines.append(f"- {flag}")
+        lines.append("")
+
+    lines.append("## Next Actions")
+    lines.append("")
+    for i, action in enumerate(assessment.next_actions, 1):
+        lines.append(f"{i}. {action}")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# T023 – CLI entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Evaluate a board intake request against the repository hardware context."
+    )
+    parser.add_argument("intake", help="Path to the intake JSON file")
+    parser.add_argument(
+        "--output",
+        default="-",
+        help="Output path for the assessment markdown (default: stdout)",
+    )
+    parser.add_argument(
+        "--validate",
+        action="store_true",
+        help="Exit with code 1 if scaffold_ready is false (useful for CI gate checks)",
+    )
+    parser.add_argument(
+        "--context",
+        default=str(DEFAULT_CONTEXT_PATH),
+        help="Path to docs/hardware-support-context.md (default: auto-detected)",
+    )
+    args = parser.parse_args()
+
+    intake_path = Path(args.intake)
+    if not intake_path.exists():
+        print(f"Error: intake file not found: {intake_path}", file=sys.stderr)
+        sys.exit(2)
+
+    request = BoardIntakeRequest.from_json(intake_path)
+    context = load_hardware_context(Path(args.context))
+    assessment = assess_intake(request, context)
+    report = render_assessment_markdown(assessment)
+
+    if args.output == "-":
+        print(report)
+    else:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(report, encoding="utf-8")
+        print(f"Assessment written to {output_path}")
+
+    if args.validate and not assessment.scaffold_ready:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

bin/board_scaffold.py

@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""Scaffold board-support files from a validated intake assessment."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from board_intake import (
+    BoardIntakeRequest,
+    EvidenceGap,
+    IntakeAssessment,
+    assess_intake,
+    load_hardware_context,
+    render_assessment_markdown,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_OUTPUT_ROOT = ROOT / "generated" / "hardware-support"
+
+ARCH_BASE_ENV = {
+    "esp32": "esp32_base",
+    "esp32-s3": "esp32s3_base",
+    "esp32-c3": "esp32c3_base",
+    "esp32-c6": "esp32c6_base",
+    "esp32s2": "esp32s2_base",
+    "nrf52840": "nrf52_base",
+    "rp2040": "rp2040_base",
+    "rp2350": "rp2350_base",
+    "stm32": "stm32_base",
+    "native": "native_base",
+}
+
+ARCH_VARIANT_ROOT = {
+    "esp32": "esp32",
+    "esp32-s3": "esp32s3",
+    "esp32-c3": "esp32c3",
+    "esp32-c6": "esp32c6",
+    "esp32s2": "esp32s2",
+    "nrf52840": "nrf52840",
+    "rp2040": "rp2040",
+    "rp2350": "rp2350",
+    "stm32": "stm32",
+    "native": "native",
+}
+
+PLACEHOLDER_DEFINES = {
+    "status": [
+        "#define LED_PIN  // TODO: verify status LED pin if present",
+    ],
+    "input": [
+        "#define BUTTON_PIN  // TODO: verify user button pin",
+    ],
+    "display": [
+        "#define HAS_SCREEN 1",
+        "#define USE_SSD1306 // TODO: verify display controller",
+        "#define I2C_SCL  // TODO: verify display I2C clock pin",
+        "#define I2C_SDA  // TODO: verify display I2C data pin",
+    ],
+    "GPS": [
+        "#define GPS_RX_PIN  // TODO: verify GPS RX pin or remove if GPS absent",
+        "#define GPS_TX_PIN  // TODO: verify GPS TX pin or remove if GPS absent",
+    ],
+    "power": [
+        "#define BATTERY_PIN  // TODO: verify battery sense pin",
+        "#define ADC_MULTIPLIER  // TODO: verify voltage divider ratio",
+    ],
+    "radio": [
+        "#define USE_SX1262 // TODO: verify radio chip selection from schematic",
+        "#define SX126X_CS  // TODO: verify radio chip-select pin",
+        "#define SX126X_BUSY  // TODO: verify radio busy pin",
+        "#define SX126X_DIO1  // TODO: verify radio IRQ pin",
+        "#define SX126X_RESET  // TODO: verify radio reset pin",
+        "#define LORA_SCK  // TODO: verify radio SPI clock pin",
+        "#define LORA_MISO  // TODO: verify radio SPI MISO pin",
+        "#define LORA_MOSI  // TODO: verify radio SPI MOSI pin",
+    ],
+}
+
+DEFINE_PATTERN = re.compile(r"^#define\s+([A-Za-z0-9_]+)(?:\s+(.*?))?\s*(?://.*)?$")
+
+CATEGORY_MACROS = {
+    "status": ["LED_POWER", "LED_PIN", "LED_STATE_ON", "VEXT_ENABLE"],
+    "input": ["BUTTON_PIN", "BUTTON_NEED_PULLUP", "ROTARY_A", "ROTARY_B"],
+    "display": [
+        "HAS_SCREEN",
+        "USE_SSD1306",
+        "USE_SH1106",
+        "USE_TFTDISPLAY",
+        "USE_ST7789",
+        "I2C_SCL",
+        "I2C_SDA",
+        "I2C_SCL1",
+        "I2C_SDA1",
+        "TFT_HEIGHT",
+        "TFT_WIDTH",
+        "TFT_OFFSET_X",
+        "TFT_OFFSET_Y",
+        "SCREEN_ROTATE",
+        "SCREEN_TRANSITION_FRAMERATE",
+    ],
+    "GPS": [
+        "HAS_GPS",
+        "GPS_RX_PIN",
+        "GPS_TX_PIN",
+        "GPS_BAUDRATE",
+        "PIN_GPS_PPS",
+        "GPS_THREAD_INTERVAL",
+    ],
+    "power": [
+        "ADC_CTRL",
+        "ADC_CTRL_ENABLED",
+        "BATTERY_PIN",
+        "ADC_CHANNEL",
+        "ADC_ATTENUATION",
+        "ADC_MULTIPLIER",
+        "USE_POWERSAVE",
+        "SLEEP_TIME",
+    ],
+    "radio": [
+        "USE_SX1262",
+        "USE_SX1268",
+        "USE_LR1121",
+        "USE_SX1280",
+        "LORA_DIO0",
+        "LORA_RESET",
+        "LORA_DIO1",
+        "LORA_DIO2",
+        "LORA_SCK",
+        "LORA_MISO",
+        "LORA_MOSI",
+        "LORA_CS",
+        "SX126X_CS",
+        "SX126X_DIO1",
+        "SX126X_BUSY",
+        "SX126X_RESET",
+        "SX126X_DIO2_AS_RF_SWITCH",
+        "SX126X_DIO3_TCXO_VOLTAGE",
+        "LR1121_IRQ_PIN",
+        "LR1121_NRESET_PIN",
+        "LR1121_BUSY_PIN",
+        "LR1121_SPI_NSS_PIN",
+        "LR1121_SPI_SCK_PIN",
+        "LR1121_SPI_MOSI_PIN",
+        "LR1121_SPI_MISO_PIN",
+        "LR11X0_DIO3_TCXO_VOLTAGE",
+        "LR11X0_DIO_AS_RF_SWITCH",
+    ],
+}
+
+
+def slugify_variant_dir(req: BoardIntakeRequest) -> str:
+    return req.environment_name.replace("_", "-").lower()
+
+
+def target_variant_dir(req: BoardIntakeRequest) -> Path:
+    arch_root = ARCH_VARIANT_ROOT.get(req.architecture, req.architecture)
+    return Path("variants") / arch_root / slugify_variant_dir(req)
+
+
+def pick_pattern(assessment: IntakeAssessment) -> dict | None:
+    return assessment.matched_patterns[0] if assessment.matched_patterns else None
+
+
+def source_basis_lines(assessment: IntakeAssessment, context: dict) -> list[str]:
+    lines = [
+        f"// Intake environment: {assessment.request.environment_name}",
+        f"// Intake architecture: {assessment.request.architecture}",
+    ]
+    pattern = pick_pattern(assessment)
+    if pattern:
+        lines.append(
+            "// Repository pattern basis: "
+            f"{pattern.get('environment', '')} -> {pattern.get('variant_dir', '')}"
+        )
+    lines.append(
+        f"// Context source: {context.get('context_path', 'docs/hardware-support-context.md')}"
+    )
+    return lines
+
+
+def parse_variant_defines(variant_path: Path) -> dict[str, str]:
+    defines: dict[str, str] = {}
+    if not variant_path.exists():
+        return defines
+
+    for raw_line in variant_path.read_text(encoding="utf-8").splitlines():
+        match = DEFINE_PATTERN.match(raw_line.strip())
+        if not match:
+            continue
+        name = match.group(1)
+        value = (match.group(2) or "1").strip()
+        defines[name] = value
+    return defines
+
+
+def infer_category_lines(pattern_variant_path: Path, category: str) -> list[str]:
+    defines = parse_variant_defines(pattern_variant_path)
+    lines: list[str] = []
+    for macro_name in CATEGORY_MACROS[category]:
+        value = defines.get(macro_name)
+        if value is None:
+            continue
+        if value == "1":
+            lines.append(f"#define {macro_name}")
+        else:
+            lines.append(f"#define {macro_name} {value}")
+
+    if lines:
+        return lines
+    return PLACEHOLDER_DEFINES[category]
+
+
+# T028
+
+
+def generate_variant_h(assessment: IntakeAssessment, context: dict) -> str:
+    req = assessment.request
+    lines: list[str] = []
+    lines.extend(source_basis_lines(assessment, context))
+    lines.append("")
+    lines.append("#pragma once")
+    lines.append("")
+
+    pattern = pick_pattern(assessment)
+    pattern_variant_path = None
+    if pattern and pattern.get("variant_dir"):
+        pattern_variant_path = (ROOT / str(pattern["variant_dir"]) / "variant.h").resolve()
+
+    for category in ("status", "input", "display", "GPS", "power", "radio"):
+        lines.append(f"// {category}")
+        if pattern_variant_path is not None:
+            lines.extend(infer_category_lines(pattern_variant_path, category))
+        else:
+            lines.extend(PLACEHOLDER_DEFINES[category])
+        lines.append("")
+
+    lines.append("// Board identity")
+    macro_name = req.hardware_model_slug or req.environment_name.upper().replace(
+        "-", "_"
+    )
+    lines.append(f"#define {macro_name} 1")
+    lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# T029
+
+
+def generate_platformio_env(assessment: IntakeAssessment) -> str:
+    req = assessment.request
+    extends = ARCH_BASE_ENV.get(req.architecture, f"{req.architecture}_base")
+    variant_dir = target_variant_dir(req)
+    build_define = (
+        req.hardware_model_slug or req.environment_name.upper().replace("-", "_")
+    ).replace(" ", "_")
+
+    lines = [
+        f"[env:{req.environment_name}]",
+        f"custom_meshtastic_hw_model = {req.hardware_model}",
+        f"custom_meshtastic_hw_model_slug = {req.hardware_model_slug or 'TODO_SET_HW_MODEL_SLUG'}",
+        f"custom_meshtastic_architecture = {req.architecture}",
+        f"custom_meshtastic_actively_supported = {str(req.actively_supported).lower() if req.actively_supported is not None else 'TODO_SET_ACTIVELY_SUPPORTED'}",
+        f"custom_meshtastic_support_level = {req.support_level or 'TODO_SET_SUPPORT_LEVEL'}",
+        f"custom_meshtastic_display_name = {req.display_name}",
+        "custom_meshtastic_images = TODO_SET_IMAGES",
+        "custom_meshtastic_tags = TODO_SET_TAGS",
+        "custom_meshtastic_requires_dfu = TODO_SET_REQUIRES_DFU",
+        "custom_meshtastic_partition_scheme = TODO_SET_PARTITION_SCHEME",
+        "",
+        "board = TODO_SET_PLATFORMIO_BOARD",
+        f"extends = {extends}",
+        "build_flags =",
+        f"  ${{{extends}.build_flags}}",
+        f"  -D {build_define}",
+        f"  -I {variant_dir.as_posix()}",
+    ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# T030
+
+
+def annotate_unresolved(content: str, gaps: list[EvidenceGap], is_ini: bool = False) -> str:
+    annotations = [
+        gap
+        for gap in gaps
+        if not gap.blocking
+        and gap.category in {"radio", "display", "input", "GPS", "power", "metadata"}
+    ]
+    if not annotations:
+        return content
+
+    lines = content.splitlines()
+    todo_lines = [f"; TODO: verify — {gap.description}" for gap in annotations]
+    
+    if is_ini:
+        # For INI files, insert TODOs after the first section header
+        if lines and lines[0].startswith("["):
+            return "\n".join(lines[:1] + todo_lines + [""] + lines[1:]) + "\n"
+    else:
+        # For .h files, prepend TODOs with C++ comment syntax
+        todo_lines = [f"// TODO: verify — {gap.description}" for gap in annotations]
+        return "\n".join(todo_lines + [""] + lines) + "\n"
+    
+    return content
+
+
+# T031
+
+
+def scaffold_board(
+    assessment: IntakeAssessment, context: dict, output_dir: Path
+) -> dict[str, Path]:
+    req = assessment.request
+    variant_dir = output_dir / target_variant_dir(req)
+    variant_dir.mkdir(parents=True, exist_ok=True)
+
+    variant_h_path = variant_dir / "variant.h"
+    platformio_path = variant_dir / "platformio.ini"
+
+    variant_h_content = annotate_unresolved(
+        generate_variant_h(assessment, context), assessment.evidence_gaps, is_ini=False
+    )
+    platformio_content = annotate_unresolved(
+        generate_platformio_env(assessment), assessment.evidence_gaps, is_ini=True
+    )
+
+    variant_h_path.write_text(variant_h_content, encoding="utf-8")
+    platformio_path.write_text(platformio_content, encoding="utf-8")
+
+    generated = {
+        "variant_h": variant_h_path,
+        "platformio": platformio_path,
+    }
+
+    if req.architecture in {"esp32", "esp32-s3", "esp32-c3", "esp32-c6"}:
+        variant_cpp_path = variant_dir / "variant.cpp"
+        variant_cpp_content = annotate_unresolved(
+            "\n".join(
+                [
+                    '#include "variant.h"',
+                    "",
+                    "// Optional board-specific initialization hooks go here.",
+                    "// Leave this file out if the board does not need custom startup behavior.",
+                ]
+            )
+            + "\n",
+            assessment.evidence_gaps,
+        )
+        variant_cpp_path.write_text(variant_cpp_content, encoding="utf-8")
+        generated["variant_cpp"] = variant_cpp_path
+
+    return generated
+
+
+# T032 + T033
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate board-support scaffold files from an intake JSON file."
+    )
+    parser.add_argument("intake", help="Path to intake JSON")
+    parser.add_argument(
+        "--output-dir",
+        default=str(DEFAULT_OUTPUT_ROOT),
+        help="Directory where scaffold files will be written",
+    )
+    args = parser.parse_args()
+
+    intake_path = Path(args.intake)
+    request = BoardIntakeRequest.from_json(intake_path)
+    context = load_hardware_context()
+    context["context_path"] = "docs/hardware-support-context.md"
+    assessment = assess_intake(request, context)
+
+    if not assessment.scaffold_ready:
+        print(render_assessment_markdown(assessment))
+        sys.exit(1)
+
+    generated = scaffold_board(assessment, context, Path(args.output_dir))
+    print("Generated scaffold files:")
+    for name, path in generated.items():
+        print(f"- {name}: {path}")
+
+
+if __name__ == "__main__":
+    main()

bin/config.d/femtofox/femtofox_E80-900M2213S.yaml

@@ -1,30 +0,0 @@
----
-Lora:
-## Ebyte E80-900M22S
-## This is a bit experimental
-## 
-##
-  Module: lr1121
-  gpiochip: 1 # subtract 32 from the gpio numbers
-  DIO3_TCXO_VOLTAGE: 1.8
-  CS: 16 #pin6 / GPIO48 1C0
-  IRQ: 23  #pin17 / GPIO55 1C7
-  Busy: 22 #pin16 / GPIO54 1C6
-  Reset: 25 #pin13 / GPIO57 1D1
-
-
-  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
-  spiSpeed: 2000000
-  
-rfswitch_table:
-  pins: [DIO5, DIO6, DIO7]
-  MODE_STBY: [LOW, LOW, LOW]
-  MODE_RX: [LOW, HIGH, LOW]
-  MODE_TX: [HIGH, HIGH, LOW]
-  MODE_TX_HP: [HIGH, LOW, LOW]
-  MODE_TX_HF: [LOW, LOW, LOW]
-  MODE_GNSS: [LOW, LOW, HIGH]
-  MODE_WIFI: [LOW, LOW, LOW]
-
-General:
-  MACAddressSource: eth0

bin/config.d/femtofox/femtofox_LR1121 generic.yaml

@@ -1,46 +0,0 @@
----
-Lora:
-## Ebyte E80-900M22S
-## This is a bit experimental
-## 
-##
-  Module: lr1121
-  gpiochip: 1 # subtract 32 from the gpio numbers
-  DIO3_TCXO_VOLTAGE: 1.8
-  CS: 16 #pin6 / GPIO48 1C0
-  IRQ: 23  #pin17 / GPIO55 1C7
-  Busy: 22 #pin16 / GPIO54 1C6
-  Reset: 25 #pin13 / GPIO57 1D1
-
-
-  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
-  spiSpeed: 2000000
-  
-rfswitch_table:
-  pins:
-    - DIO5
-    - DIO6
-  MODE_STBY:
-    - LOW
-    - LOW
-  MODE_RX:
-    - HIGH
-    - LOW
-  MODE_TX:
-    - HIGH
-    - HIGH
-  MODE_TX_HP:
-    - LOW
-    - HIGH
-  MODE_TX_HF:
-    - LOW
-    - LOW
-  MODE_GNSS:
-    - LOW
-    - LOW
-  MODE_WIFI:
-    - LOW
-    - LOW
-
-General:
-  MACAddressSource: eth0

bin/config.d/femtofox/femtofox_WIO-LR1121.yaml

@@ -1,30 +0,0 @@
----
-Lora:
-## Ebyte E80-900M22S
-## This is a bit experimental
-## 
-##
-  Module: lr1121
-  gpiochip: 1 # subtract 32 from the gpio numbers
-  DIO3_TCXO_VOLTAGE: 1.8
-  CS: 16 #pin6 / GPIO48 1C0
-  IRQ: 23  #pin17 / GPIO55 1C7
-  Busy: 22 #pin16 / GPIO54 1C6
-  Reset: 25 #pin13 / GPIO57 1D1
-
-
-  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
-  spiSpeed: 2000000
-  
-rfswitch_table:
-  pins: [DIO5, DIO6, DIO7]
-  MODE_STBY: [LOW, LOW, LOW]
-  MODE_RX: [LOW, LOW, LOW]
-  MODE_TX: [LOW, HIGH, LOW]
-  MODE_TX_HP: [HIGH, LOW, LOW]
-  # MODE_TX_HF: []
-  # MODE_GNSS: []
-  MODE_WIFI: [LOW, LOW, LOW]
-
-General:
-  MACAddressSource: eth0

bin/fixtures/intake_full.json

@@ -0,0 +1,14 @@
+{
+    "environment_name": "new_esp32s3_board",
+    "hardware_model": "999",
+    "hardware_model_slug": "NEW_ESP32S3_BOARD",
+    "display_name": "Acme ESP32-S3 Dev Board v1",
+    "architecture": "esp32-s3",
+    "actively_supported": true,
+    "support_level": "1",
+    "source_materials": [
+        "https://example.com/acme-esp32s3-schematic.pdf",
+        "https://example.com/acme-esp32s3-pinout.png"
+    ],
+    "board_notes": "Initial bring-up for v1 PCB only. SX1262 radio on SPI2, OLED on I2C bus."
+}

bin/fixtures/intake_minimal.json

@@ -0,0 +1,6 @@
+{
+    "environment_name": "hypothetical_esp32s3_board",
+    "hardware_model": "9981",
+    "display_name": "Hypothetical ESP32-S3 Board",
+    "architecture": "esp32-s3"
+}

bin/fixtures/intake_multi_env.json

@@ -0,0 +1,13 @@
+{
+    "environment_name": "new_nrf52_tracker",
+    "hardware_model": "998",
+    "hardware_model_slug": "NEW_NRF52_TRACKER",
+    "display_name": "Acme nRF52840 Tracker v2",
+    "architecture": "nrf52840",
+    "actively_supported": null,
+    "support_level": "2",
+    "source_materials": [
+        "https://example.com/acme-tracker-pinout.pdf"
+    ],
+    "board_notes": "Two revisions exist: v2 (SSD1306 OLED) and v2a (no display). This intake covers v2 only."
+}

bin/generate_hardware_support_context.py

@@ -0,0 +1,592 @@
+#!/usr/bin/env python3
+
+"""Generate a markdown inventory of board-support metadata and common target-definition macros."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from collections import Counter, defaultdict
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+VARIANTS_DIR = ROOT / "variants"
+OUTPUT_PATH = ROOT / "docs" / "hardware-support-context.md"
+
+PLATFORMIO_METADATA_KEYS = [
+    "custom_meshtastic_hw_model",
+    "custom_meshtastic_hw_model_slug",
+    "custom_meshtastic_architecture",
+    "custom_meshtastic_actively_supported",
+    "custom_meshtastic_support_level",
+    "custom_meshtastic_display_name",
+    "custom_meshtastic_images",
+    "custom_meshtastic_tags",
+    "custom_meshtastic_requires_dfu",
+    "custom_meshtastic_partition_scheme",
+]
+
+MACRO_PATTERNS = {
+    "Input": [
+        "BUTTON_PIN",
+        "BUTTON_PIN_TOUCH",
+        "ALT_BUTTON_PIN",
+        "CANCEL_BUTTON_PIN",
+        "ROTARY_",
+        "KB_",
+        "INPUTDRIVER_",
+    ],
+    "Radio": [
+        "USE_RF95",
+        "USE_SX126",
+        "USE_SX128",
+        "USE_LLCC68",
+        "USE_LR11",
+        "LORA_",
+        "SX126X_",
+        "SX128X_",
+        "LR1121_",
+        "RF95_",
+    ],
+    "GPS": [
+        "HAS_GPS",
+        "GPS_",
+        "PIN_GPS_",
+        "GPS_DEFAULT_NOT_PRESENT",
+    ],
+    "Display": [
+        "HAS_SCREEN",
+        "USE_TFTDISPLAY",
+        "USE_TFT",
+        "USE_SSD",
+        "USE_SH",
+        "USE_ST",
+        "TFT_",
+        "OLED_",
+        "SCREEN_",
+        "PIN_EINK_",
+        "EINK_",
+        "DISPLAY_",
+        "LGFX_",
+        "HAS_TFT",
+    ],
+    "I2C/SPI": [
+        "I2C_",
+        "SPI_",
+        "PIN_SPI",
+        "WIRE_",
+    ],
+    "Power": [
+        "BATTERY_",
+        "ADC_",
+        "PIN_POWER",
+        "USE_POWERSAVE",
+        "SLEEP_TIME",
+        "XPOWERS_",
+        "HAS_AXP",
+        "HAS_PPM",
+        "HAS_BQ",
+        "EXT_NOTIFY_OUT",
+        "FAN_CTRL_PIN",
+        "RF95_FAN_EN",
+    ],
+    "Connectivity/Other": [
+        "HAS_WIFI",
+        "HAS_BLUETOOTH",
+        "HAS_ETHERNET",
+        "HAS_NEOPIXEL",
+        "HAS_I2S",
+        "HAS_TOUCH",
+        "HAS_TOUCHSCREEN",
+        "HAS_NFC",
+        "NFC_",
+        "USE_XL9555",
+        "EXPANDS_",
+        "PCF",
+        "RTC",
+    ],
+}
+
+
+def classify_macro(name: str) -> str:
+    for category, prefixes in MACRO_PATTERNS.items():
+        for prefix in prefixes:
+            if name.startswith(prefix):
+                return category
+    return "Other"
+
+
+def parse_platformio_envs(path: Path) -> list[dict[str, object]]:
+    envs: list[dict[str, object]] = []
+    current: dict[str, object] | None = None
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith(";"):
+            continue
+        if line.startswith("[") and line.endswith("]"):
+            if current:
+                envs.append(current)
+            current = {"section": line[1:-1], "metadata": {}}
+            continue
+        if current is None or "=" not in line:
+            continue
+        key, value = [part.strip() for part in line.split("=", 1)]
+        if key in PLATFORMIO_METADATA_KEYS:
+            current["metadata"][key] = value
+    if current:
+        envs.append(current)
+    return envs
+
+
+def parse_variant_macros(path: Path) -> tuple[dict[str, str], Counter[str]]:
+    defines: dict[str, str] = {}
+    category_counts: Counter[str] = Counter()
+    pattern = re.compile(r"^#define\s+([A-Za-z0-9_]+)(?:\s+(.*?))?\s*(?://.*)?$")
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        match = pattern.match(raw_line.strip())
+        if not match:
+            continue
+        name = match.group(1)
+        value = (match.group(2) or "1").strip()
+        defines[name] = value
+        category_counts[classify_macro(name)] += 1
+    return defines, category_counts
+
+
+MACRO_DESCRIPTIONS: dict[str, str] = {
+    # ---------- Input ----------
+    "BUTTON_PIN":                    "Primary user button GPIO pin number.",
+    "ALT_BUTTON_PIN":                "Secondary / alternate button pin, used on boards with two buttons.",
+    "CANCEL_BUTTON_PIN":             "Button wired to cancel/back actions (e.g., T-Deck cancel key).",
+    "BUTTON_NEED_PULLUP":            "Set to 1 when the button GPIO requires the internal pull-up to be enabled.",
+    "BUTTON_PIN_ALT":                "Alternative spelling used by some older board families for a second button.",
+    "KB_BL_PIN":                     "Keyboard backlight control pin (e.g., T-LoRa Pager keyboard).",
+    "KB_INT":                        "Keyboard interrupt input pin; signals a keypress to the MCU.",
+    "KB_POWERON":                    "Pin used to power-on or enable the keyboard peripheral.",
+    "KB_SLAVE_ADDRESS":              "I2C address of the keyboard controller IC.",
+    "INPUTDRIVER_ENCODER_TYPE":      "Selects the rotary encoder driver variant (0 = none, 1+ = specific type).",
+    "INPUTDRIVER_TWO_WAY_ROCKER":    "Enables the two-way rocker input driver.",
+    "INPUTDRIVER_TWO_WAY_ROCKER_RIGHT": "GPIO pin for the rightward rocker direction.",
+    "INPUTDRIVER_TWO_WAY_ROCKER_LEFT":  "GPIO pin for the leftward rocker direction.",
+    "INPUTDRIVER_TWO_WAY_ROCKER_BTN":   "GPIO pin for the rocker click/press direction.",
+    "ROTARY_A":                      "First encoder channel pin (clock / A signal).",
+    "ROTARY_B":                      "Second encoder channel pin (data / B signal).",
+    # ---------- Radio ----------
+    "USE_SX1262":                    "Select the SX1262 sub-GHz LoRa chip driver.",
+    "USE_SX1268":                    "Select the SX1268 sub-GHz LoRa chip driver (higher power variant of SX1262).",
+    "USE_SX1280":                    "Select the SX1280 2.4 GHz LoRa chip driver.",
+    "USE_RF95":                      "Select the RFM95/SX1276 legacy LoRa chip driver.",
+    "USE_LLCC68":                    "Select the LLCC68 low-cost LoRa chip driver.",
+    "USE_LR1110":                    "Select the LR1110 wideband radio driver.",
+    "USE_LR1120":                    "Select the LR1120 wideband radio driver.",
+    "USE_LR1121":                    "Select the LR1121 wideband radio driver.",
+    "LORA_CS":                       "LoRa radio SPI chip-select GPIO pin.",
+    "LORA_RESET":                    "LoRa radio hardware-reset GPIO pin (active low).",
+    "LORA_DIO0":                     "LoRa radio DIO0 interrupt pin (RF95/SX1276 done/RxDone).",
+    "LORA_DIO1":                     "LoRa radio DIO1 interrupt pin; on SX126x this is the primary IRQ line.",
+    "LORA_DIO2":                     "LoRa radio DIO2 pin; on RF95 used for FSK interrupt; on SX126x tx/rx control.",
+    "LORA_SCK":                      "LoRa radio SPI clock pin.",
+    "LORA_MISO":                     "LoRa radio SPI MISO pin.",
+    "LORA_MOSI":                     "LoRa radio SPI MOSI pin.",
+    "SX126X_CS":                     "SX126x chip-select pin (often same as LORA_CS).",
+    "SX126X_RESET":                  "SX126x reset pin (often same as LORA_RESET).",
+    "SX126X_BUSY":                   "SX126x BUSY pin; must be polled low before issuing SPI commands.",
+    "SX126X_DIO1":                   "SX126x DIO1 interrupt output used for all IRQ events.",
+    "SX126X_DIO3_TCXO_VOLTAGE":      "Drives the TCXO regulator via DIO3; set to the supply voltage (e.g., 1.8).",
+    "SX126X_DIO2_AS_RF_SWITCH":      "Set to 1 so the driver controls the TX/RX RF switch via DIO2.",
+    "LR1121_IRQ_PIN":                "LR1121 interrupt request pin.",
+    "RF95_FAN_EN":                   "Enables a cooling fan for high-power RF95 installations.",
+    # ---------- GPS ----------
+    "HAS_GPS":                       "Set to 1 if the board has an on-board GPS receiver; 0 to disable GPS entirely.",
+    "GPS_RX_PIN":                    "UART RX pin connected to the GPS module TX output.",
+    "GPS_TX_PIN":                    "UART TX pin connected to the GPS module RX input.",
+    "PIN_GPS_EN":                    "GPIO to power-enable or power-gate the GPS module.",
+    "PIN_GPS_PPS":                   "GPS pulse-per-second input pin for timing synchronisation.",
+    "PIN_GPS_STANDBY":               "Places the GPS into standby/low-power mode when driven.",
+    "PIN_GPS_RESET":                 "Hardware-reset line to the GPS module.",
+    "PIN_GPS_REINIT":                "Pin used to trigger GPS re-initialisation sequences.",
+    "GPS_THREAD_INTERVAL":           "Millisecond poll interval for the GPS background thread.",
+    "GPS_BAUDRATE":                  "UART baud rate for GPS serial communication.",
+    "GPS_L76K":                      "Selects the Quectel L76K GPS driver and protocol.",
+    "GPS_UBLOX":                     "Selects the u-blox GPS driver and UBX protocol.",
+    "GPS_EN_ACTIVE":                 "Logic level (HIGH or LOW) that enables the GPS power pin.",
+    "GPS_RESET_MODE":                "Defines the reset signal polarity or protocol for the GPS chip.",
+    "GPS_DEFAULT_NOT_PRESENT":       "Compiled-in default assuming no GPS; overridden at runtime if detected.",
+    # ---------- Display ----------
+    "HAS_SCREEN":                    "Set to 1 if the board has any display hardware.",
+    "USE_TFTDISPLAY":                "Selects the TFT LCD driver path.",
+    "USE_SSD1306":                   "Selects the SSD1306 128×64 OLED driver over I2C.",
+    "USE_SH1106":                    "Selects the SH1106 128×64 OLED driver.",
+    "USE_ST7735":                    "Selects the ST7735 TFT SPI driver.",
+    "USE_ST7789":                    "Selects the ST7789 TFT SPI driver.",
+    "TFT_WIDTH":                     "Horizontal pixel resolution of the TFT display.",
+    "TFT_HEIGHT":                    "Vertical pixel resolution of the TFT display.",
+    "TFT_OFFSET_X":                  "Horizontal pixel offset for display alignment correction.",
+    "TFT_OFFSET_Y":                  "Vertical pixel offset for display alignment correction.",
+    "TFT_BL":                        "Backlight control PWM or GPIO pin for the TFT panel.",
+    "SCREEN_ROTATE":                 "Non-zero value rotates the display 180° for mounted-upside-down screens.",
+    "SCREEN_TRANSITION_FRAMERATE":   "Target framerate for UI animations and transitions.",
+    "PIN_EINK_CS":                   "E-ink display SPI chip-select pin.",
+    "PIN_EINK_BUSY":                 "E-ink display BUSY output; high when a page update is in progress.",
+    "PIN_EINK_DC":                   "E-ink display data/command select pin.",
+    "PIN_EINK_RES":                  "E-ink display hardware-reset pin.",
+    "PIN_EINK_SCLK":                 "E-ink display SPI clock pin.",
+    "PIN_EINK_MOSI":                 "E-ink display SPI MOSI pin.",
+    # ---------- I2C/SPI ----------
+    "I2C_SDA":                       "Primary I2C data line GPIO pin.",
+    "I2C_SCL":                       "Primary I2C clock line GPIO pin.",
+    "PIN_SPI_MISO":                  "Primary SPI MISO (data from peripheral) GPIO pin.",
+    "PIN_SPI_MOSI":                  "Primary SPI MOSI (data to peripheral) GPIO pin.",
+    "PIN_SPI_SCK":                   "Primary SPI clock GPIO pin.",
+    "SPI_INTERFACES_COUNT":          "Number of hardware SPI buses available on this board.",
+    "WIRE_INTERFACES_COUNT":         "Number of hardware I2C buses available on this board.",
+    "PIN_SPI1_MISO":                 "Secondary SPI bus MISO pin.",
+    "PIN_SPI1_MOSI":                 "Secondary SPI bus MOSI pin.",
+    "PIN_SPI1_SCK":                  "Secondary SPI bus clock pin.",
+    "SPI_FREQUENCY":                 "Default SPI clock frequency in Hz for this board.",
+    "SPI_READ_FREQUENCY":            "Reduced SPI clock rate used for read transactions.",
+    "SPI_SCK":                       "SPI clock pin alias used in older board files.",
+    "SPI_MOSI":                      "SPI MOSI pin alias used in older board files.",
+    "SPI_MISO":                      "SPI MISO pin alias used in older board files.",
+    # ---------- Power ----------
+    "BATTERY_PIN":                   "ADC input GPIO connected to the battery voltage divider.",
+    "ADC_MULTIPLIER":                "Floating-point scale factor to convert raw ADC reading to battery voltage.",
+    "ADC_CHANNEL":                   "ADC channel enum or number for the battery sense input.",
+    "BATTERY_SENSE_RESOLUTION_BITS": "ADC resolution in bits used for battery voltage sampling.",
+    "ADC_RESOLUTION":                "Board-level ADC resolution definition, referenced by other power macros.",
+    "BATTERY_SENSE_RESOLUTION":      "Alias for the effective ADC resolution for battery sense.",
+    "ADC_CTRL":                      "GPIO that enables or gates the ADC voltage-divider circuit.",
+    "ADC_CTRL_ENABLED":              "Logic level (HIGH or LOW) that turns on the ADC control switch.",
+    "ADC_ATTENUATION":               "ESP32 ADC input attenuation setting; controls measurable voltage range.",
+    "BATTERY_SENSE_SAMPLES":         "Number of ADC samples to average for a stable battery reading.",
+    "EXT_NOTIFY_OUT":                "GPIO output used to signal an external LED or buzzer for notifications.",
+    "USE_POWERSAVE":                 "Enables aggressive power-save mode (deep sleep, reduced poll intervals).",
+    "SLEEP_TIME":                    "Default light-sleep duration in milliseconds between wakeups.",
+    "PIN_POWER_EN":                  "GPIO to assert to enable a board power rail or load switch.",
+    "HAS_PPM":                       "Set to 1 if the board has an IP5306 or similar PPM power path IC.",
+    # ---------- Connectivity/Other ----------
+    "HAS_TOUCHSCREEN":               "Set to 1 for boards with a capacitive or resistive touch panel.",
+    "HAS_NEOPIXEL":                  "Set to 1 if the board has addressable RGB LEDs (WS2812 / NeoPixel).",
+    "PCF8563_RTC":                   "I2C address of the PCF8563 real-time clock IC.",
+    "PCF85063_RTC":                  "I2C address of the PCF85063 real-time clock IC.",
+    "HAS_ETHERNET":                  "Set to 1 for boards with a wired Ethernet interface.",
+    "HAS_I2S":                       "Set to 1 if I2S audio output is present.",
+    "NFC_INT":                       "Interrupt pin from the NFC controller IC.",
+    "NFC_CS":                        "SPI chip-select for the NFC controller.",
+    "USE_XL9555":                    "Enables the XL9555 16-bit I2C GPIO expander driver.",
+    "EXPANDS_DRV_EN":                "GPIO expander pin used to enable the haptic driver.",
+    "EXPANDS_AMP_EN":                "GPIO expander pin used to power-on the audio amplifier.",
+    "EXPANDS_KB_RST":                "GPIO expander pin used to reset the keyboard controller.",
+    "EXPANDS_LORA_EN":               "GPIO expander pin used to power-gate the LoRa radio.",
+    "EXPANDS_GPS_EN":                "GPIO expander pin used to power-gate the GPS module.",
+    "EXPANDS_NFC_EN":                "GPIO expander pin used to power-gate the NFC controller.",
+    # ---------- Other ----------
+    "LED_POWER":                     "GPIO for the status LED, defines the LED pin number.",
+    "LED_STATE_ON":                  "Logic level (HIGH or LOW) that turns the status LED on.",
+    "PIN_SERIAL1_RX":                "Secondary UART RX pin (used for accessories, GPS on some boards).",
+    "PIN_SERIAL1_TX":                "Secondary UART TX pin.",
+    "PIN_WIRE_SDA":                  "Arduino-framework I2C SDA pin alias (nRF52 / RP2040 style).",
+    "PIN_WIRE_SCL":                  "Arduino-framework I2C SCL pin alias.",
+    "PIN_LED1":                      "First LED GPIO pin in the nRF52 Arduino BSP pin table.",
+    "VARIANT_MCK":                   "Crystal oscillator frequency in Hz for nRF52 variant clock configuration.",
+    "PINS_COUNT":                    "Total number of GPIO pins defined in the Arduino BSP variant table.",
+    "NUM_DIGITAL_PINS":              "Count of digital-capable pins in the BSP variant table.",
+    "NUM_ANALOG_INPUTS":             "Count of analog-input pins in the BSP variant table.",
+    "NUM_ANALOG_OUTPUTS":            "Count of analog-output (DAC) pins in the BSP variant table.",
+    "LED_BLUE":                      "GPIO number of the blue status LED (typical on nRF52 and RP2040 boards).",
+    "USE_LFXO":                      "Instructs the nRF52 BSP to use the low-frequency crystal oscillator.",
+    "BUTTON_NEED_PULLUP":            "Enables internal pull-up on the button GPIO (duplicate entry for clarity).",
+}
+
+
+def shorten(value: str, limit: int = 60) -> str:
+    compact = " ".join(value.split())
+    return compact if len(compact) <= limit else compact[: limit - 3] + "..."
+
+
+# Architecture families known to rely heavily on BSP or base-environment defaults rather
+# than declaring every field locally. Used in the Inherited Defaults Note section.
+_BSP_DEFAULT_FAMILIES: dict[str, list[str]] = {
+    "nrf52840": [
+        "VARIANT_MCK — nRF52 BSP clock constant (e.g., 64000000ul); always inherited from BSP unless overridden.",
+        "USE_LFXO — low-frequency crystal oscillator selection; declared locally only when the board uses LFXO rather than the RC oscillator.",
+        "PIN_SPI_* / PIN_SPI1_* — SPI bus pin numbers come from the BSP variant table; boards override only when the LoRa radio or display uses non-default SPI routing.",
+        "WIRE_INTERFACES_COUNT / SPI_INTERFACES_COUNT — bus count comes from BSP; explicitly set only when the board deviates.",
+        "LED_BLUE / PIN_LED1 / PINS_COUNT / NUM_DIGITAL_PINS — standard BSP pin-table entries inherited from the nRF52 Arduino core.",
+    ],
+    "rp2040": [
+        "PIN_SPI_* — primary SPI pins come from the RP2040 Arduino BSP; most boards declare them explicitly, but the defaults align with the Pico pin assignments.",
+        "NUM_DIGITAL_PINS / NUM_ANALOG_INPUTS — Arduino BSP counts; rarely overridden locally.",
+    ],
+    "stm32": [
+        "Radio and pin assignments for STM32WL targets are largely internal to the WL SoC and declared via STM32 HAL/BSP headers; variant.h files are minimal.",
+        "USE_STM32WLx is typically the only explicit define; all other radio config comes from the BSP.",
+    ],
+    "native": [
+        "The native/Portduino target uses runtime configuration rather than compile-time pin defines; variant.h only sets display and GPS stubs.",
+    ],
+}
+
+
+def collect_inventory() -> dict[str, object]:
+    architectures: defaultdict[str, list[dict[str, object]]] = defaultdict(list)
+    category_frequency: defaultdict[str, Counter[str]] = defaultdict(Counter)
+    total_variant_dirs = 0
+    total_envs = 0
+    no_variant_h: defaultdict[str, int] = defaultdict(int)  # arch -> count of dirs with no variant.h
+    has_metadata: int = 0  # env count that has at least one custom_meshtastic_* key
+
+    for platformio_path in sorted(VARIANTS_DIR.glob("**/platformio.ini")):
+        variant_dir = platformio_path.parent
+        total_variant_dirs += 1
+        variant_path = variant_dir / "variant.h"
+        board_level_arch_raw = variant_dir.parts[-2] if len(variant_dir.parts) >= 2 else "unknown"
+        if not variant_path.exists():
+            no_variant_h[board_level_arch_raw] += 1
+            continue
+
+        envs = parse_platformio_envs(platformio_path)
+        defines, category_counts = parse_variant_macros(variant_path)
+        total_envs += len(envs)
+
+        board_level_arch = board_level_arch_raw
+        for env in envs:
+            section = str(env["section"])
+            if not section.startswith("env:"):
+                continue
+            metadata = dict(env["metadata"])
+            if metadata:
+                has_metadata += 1
+            architecture = str(metadata.get("custom_meshtastic_architecture") or board_level_arch)
+            if architecture == "esp32s3":
+                architecture = "esp32-s3"
+            if architecture == "esp32c3":
+                architecture = "esp32-c3"
+            if architecture == "esp32c6":
+                architecture = "esp32-c6"
+
+            entry = {
+                "environment": section.split(":", 1)[1],
+                "variant_dir": str(variant_dir.relative_to(ROOT)),
+                "metadata": metadata,
+                "defines": defines,
+                "category_counts": category_counts,
+            }
+            architectures[architecture].append(entry)
+
+            for name in defines:
+                category = classify_macro(name)
+                category_frequency[category][name] += 1
+
+    return {
+        "architectures": architectures,
+        "category_frequency": category_frequency,
+        "total_variant_dirs": total_variant_dirs,
+        "total_envs": total_envs,
+        "no_variant_h": dict(no_variant_h),
+        "has_metadata": has_metadata,
+    }
+
+
+def render_markdown(inventory: dict[str, object]) -> str:
+    architectures = inventory["architectures"]
+    category_frequency = inventory["category_frequency"]
+    lines: list[str] = []
+
+    lines.append("# Hardware Support Context")
+    lines.append("")
+    lines.append("This document inventories the board-support inputs and common target-definition fields")
+    lines.append("currently used in the Meshtastic firmware repository. It is intended as reusable context")
+    lines.append("for adding new hardware support without re-discovering naming patterns, metadata keys, and")
+    lines.append("frequently used pin or capability macros from scratch.")
+    lines.append("")
+    lines.append("## Scope")
+    lines.append("")
+    lines.append(f"- Variant directories scanned: {inventory['total_variant_dirs']}")
+    lines.append(f"- PlatformIO environments summarized: {inventory['total_envs']}")
+    lines.append("- Sources: `variants/**/platformio.ini` and `variants/**/variant.h`")
+    lines.append("- Notes: This inventory reflects explicit per-variant declarations. Some boards also inherit")
+    lines.append("  defaults from architecture headers or shared base environments, which must still be checked")
+    lines.append("  before creating new hardware support.")
+    lines.append("")
+    lines.append("## Repository Metadata Inputs")
+    lines.append("")
+    lines.append("The following `custom_meshtastic_*` metadata keys are already used across board environments:")
+    lines.append("")
+    for key in PLATFORMIO_METADATA_KEYS:
+        lines.append(f"- `{key}`")
+    lines.append("")
+    lines.append("## Common Target-Definition Categories")
+    lines.append("")
+    for category in ["Input", "Radio", "GPS", "Display", "I2C/SPI", "Power", "Connectivity/Other", "Other"]:
+        counter = category_frequency.get(category, Counter())
+        if not counter:
+            continue
+        lines.append(f"### {category}")
+        lines.append("")
+        lines.append("| Macro | Used in | Description |")
+        lines.append("| --- | --- | --- |")
+        for name, count in counter.most_common(15):
+            description = MACRO_DESCRIPTIONS.get(name, "")
+            lines.append(f"| `{name}` | {count} variants | {description} |")
+        lines.append("")
+
+    lines.append("## Architecture and Environment Inventory")
+    lines.append("")
+    for architecture in sorted(architectures):
+        entries = sorted(architectures[architecture], key=lambda item: item["environment"])
+        lines.append(f"### {architecture}")
+        lines.append("")
+        lines.append("| Environment | Display Name | HW Model | HW Slug | Variant Dir | Common Categories |")
+        lines.append("| --- | --- | --- | --- | --- | --- |")
+        for entry in entries:
+            metadata = entry["metadata"]
+            category_counts = entry["category_counts"]
+            categories = []
+            for category in ["Display", "Radio", "Input", "GPS", "Power", "Connectivity/Other"]:
+                count = category_counts.get(category, 0)
+                if count:
+                    categories.append(f"{category}:{count}")
+            category_summary = ", ".join(categories) if categories else "none"
+            lines.append(
+                "| {environment} | {display_name} | {hw_model} | {hw_slug} | {variant_dir} | {categories} |".format(
+                    environment=entry["environment"],
+                    display_name=metadata.get("custom_meshtastic_display_name", ""),
+                    hw_model=metadata.get("custom_meshtastic_hw_model", ""),
+                    hw_slug=metadata.get("custom_meshtastic_hw_model_slug", ""),
+                    variant_dir=entry["variant_dir"],
+                    categories=category_summary,
+                )
+            )
+        lines.append("")
+
+    lines.append("## Representative Board Examples")
+    lines.append("")
+    for architecture in sorted(architectures):
+        entries = sorted(architectures[architecture], key=lambda item: item["environment"])
+        if not entries:
+            continue
+        sample = entries[0]
+        lines.append(f"### {architecture}: `{sample['environment']}`")
+        lines.append("")
+        lines.append(f"- Variant directory: `{sample['variant_dir']}`")
+        metadata = sample["metadata"]
+        for key in PLATFORMIO_METADATA_KEYS:
+            value = metadata.get(key)
+            if value:
+                lines.append(f"- `{key}`: `{value}`")
+        defines = sample["defines"]
+        for category in ["Input", "Radio", "GPS", "Display", "I2C/SPI", "Power", "Connectivity/Other"]:
+            selected = [name for name in defines if classify_macro(name) == category][:8]
+            if not selected:
+                continue
+            lines.append(f"- {category} examples:")
+            for name in selected:
+                lines.append(f"  - `{name}` = `{shorten(defines[name])}`")
+        lines.append("")
+
+    lines.append("## Intake Guidance For New Hardware")
+    lines.append("")
+    lines.append("When using this context to add a new board, collect these inputs before generating files:")
+    lines.append("")
+    lines.append("- PlatformIO environment name")
+    lines.append("- `custom_meshtastic_hw_model` and `custom_meshtastic_hw_model_slug`")
+    lines.append("- Display name and architecture")
+    lines.append("- Whether the board is actively supported and its support level")
+    lines.append("- Partition scheme, DFU requirement, and image/tag metadata if applicable")
+    lines.append("- Radio chip family and complete radio pin group")
+    lines.append("- Input/button/rotary/keyboard pins")
+    lines.append("- Display interface pins and driver-related macros")
+    lines.append("- GPS, power-management, I2C, SPI, storage, and auxiliary peripheral definitions")
+    lines.append("- Any board-specific initialization that requires `variant.cpp` or extra variant hooks")
+    lines.append("")
+    lines.append("## Inherited Defaults Note")
+    lines.append("")
+    lines.append(
+        "Some architecture families rely on BSP (Board Support Package) or base-environment defaults "
+        "rather than declaring every pin or capability macro explicitly in `variant.h`. "
+        "When adding a new board for one of these families, check the relevant BSP headers before "
+        "assuming a missing define means a feature is absent."
+    )
+    lines.append("")
+    no_variant_h = inventory.get("no_variant_h", {})
+    if no_variant_h:
+        lines.append(
+            f"Directories scanned that had no `variant.h` "
+            f"(relying entirely on BSP/base-environment): "
+            + ", ".join(f"{arch}: {count}" for arch, count in sorted(no_variant_h.items()))
+        )
+        lines.append("")
+    for family, notes in _BSP_DEFAULT_FAMILIES.items():
+        lines.append(f"### {family}")
+        lines.append("")
+        for note in notes:
+            lines.append(f"- {note}")
+        lines.append("")
+    lines.append("## Cautions")
+    lines.append("")
+    lines.append("- Some boards rely on architecture defaults rather than declaring every field locally.")
+    lines.append("- Some board families expose multiple environments or display variants that share one hardware model.")
+    lines.append("- Source materials such as schematics still need human verification before new pin mappings are trusted.")
+    lines.append("- This document is a starting context artifact, not proof that a new board definition is safe to merge.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def print_validate_summary(inventory: dict[str, object]) -> None:
+    """Print a validation summary to stdout without writing the output file."""
+    total_dirs = inventory["total_variant_dirs"]
+    total_envs = inventory["total_envs"]
+    has_metadata = inventory["has_metadata"]
+    no_variant_h = inventory.get("no_variant_h", {})
+    no_variant_h_total = sum(no_variant_h.values())
+    architectures = inventory["architectures"]
+    arch_count = len(architectures)
+
+    print("Hardware Support Context — Validation Summary")
+    print("=" * 48)
+    print(f"Variant directories scanned : {total_dirs}")
+    print(f"Directories with no variant.h (BSP-only) : {no_variant_h_total}")
+    if no_variant_h:
+        for arch, count in sorted(no_variant_h.items()):
+            print(f"  {arch}: {count}")
+    print(f"PlatformIO environments found : {total_envs}")
+    print(f"Environments with custom_meshtastic_* metadata : {has_metadata}")
+    print(f"Architecture families represented : {arch_count}")
+    print("")
+    print("Architecture families:")
+    for arch in sorted(architectures):
+        entries = architectures[arch]
+        print(f"  {arch}: {len(entries)} environment(s)")
+    print("")
+    print("BSP-default families with special notes:")
+    for family in _BSP_DEFAULT_FAMILIES:
+        marker = "YES" if family in {a.split("-")[0] for a in architectures} else "not in scan"
+        print(f"  {family}: {marker}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate hardware support context markdown")
+    parser.add_argument("--output", default=str(OUTPUT_PATH), help="Output markdown path")
+    parser.add_argument(
+        "--validate",
+        action="store_true",
+        help="Print a validation summary (variant counts, BSP-only dirs, metadata coverage) without writing output",
+    )
+    args = parser.parse_args()
+
+    inventory = collect_inventory()
+
+    if args.validate:
+        print_validate_summary(inventory)
+        return
+
+    markdown = render_markdown(inventory)
+    output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(markdown + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

docs/hardware-support-context.md

@@ -0,0 +1,742 @@
+# Hardware Support Context
+
+This document inventories the board-support inputs and common target-definition fields
+currently used in the Meshtastic firmware repository. It is intended as reusable context
+for adding new hardware support without re-discovering naming patterns, metadata keys, and
+frequently used pin or capability macros from scratch.
+
+## Scope
+
+- Variant directories scanned: 166
+- PlatformIO environments summarized: 212
+- Sources: `variants/**/platformio.ini` and `variants/**/variant.h`
+- Notes: This inventory reflects explicit per-variant declarations. Some boards also inherit
+  defaults from architecture headers or shared base environments, which must still be checked
+  before creating new hardware support.
+
+## Repository Metadata Inputs
+
+The following `custom_meshtastic_*` metadata keys are already used across board environments:
+
+- `custom_meshtastic_hw_model`
+- `custom_meshtastic_hw_model_slug`
+- `custom_meshtastic_architecture`
+- `custom_meshtastic_actively_supported`
+- `custom_meshtastic_support_level`
+- `custom_meshtastic_display_name`
+- `custom_meshtastic_images`
+- `custom_meshtastic_tags`
+- `custom_meshtastic_requires_dfu`
+- `custom_meshtastic_partition_scheme`
+
+## Common Target-Definition Categories
+
+### Input
+
+| Macro                              | Used in      | Description                                                                 |
+| ---------------------------------- | ------------ | --------------------------------------------------------------------------- |
+| `BUTTON_PIN`                       | 127 variants | Primary user button GPIO pin number.                                        |
+| `ALT_BUTTON_PIN`                   | 12 variants  | Secondary / alternate button pin, used on boards with two buttons.          |
+| `CANCEL_BUTTON_PIN`                | 8 variants   | Button wired to cancel/back actions (e.g., T-Deck cancel key).              |
+| `KB_BL_PIN`                        | 5 variants   | Keyboard backlight control pin (e.g., T-LoRa Pager keyboard).               |
+| `KB_INT`                           | 4 variants   | Keyboard interrupt input pin; signals a keypress to the MCU.                |
+| `INPUTDRIVER_ENCODER_TYPE`         | 3 variants   | Selects the rotary encoder driver variant (0 = none, 1+ = specific type).   |
+| `BUTTON_PIN_ALT`                   | 2 variants   | Alternative spelling used by some older board families for a second button. |
+| `INPUTDRIVER_TWO_WAY_ROCKER`       | 2 variants   | Enables the two-way rocker input driver.                                    |
+| `INPUTDRIVER_TWO_WAY_ROCKER_RIGHT` | 2 variants   | GPIO pin for the rightward rocker direction.                                |
+| `INPUTDRIVER_TWO_WAY_ROCKER_LEFT`  | 2 variants   | GPIO pin for the leftward rocker direction.                                 |
+| `INPUTDRIVER_TWO_WAY_ROCKER_BTN`   | 2 variants   | GPIO pin for the rocker click/press direction.                              |
+| `KB_POWERON`                       | 2 variants   | Pin used to power-on or enable the keyboard peripheral.                     |
+| `KB_SLAVE_ADDRESS`                 | 2 variants   | I2C address of the keyboard controller IC.                                  |
+| `ROTARY_A`                         | 2 variants   | First encoder channel pin (clock / A signal).                               |
+| `ROTARY_B`                         | 2 variants   | Second encoder channel pin (data / B signal).                               |
+
+### Radio
+
+| Macro                      | Used in      | Description                                                                   |
+| -------------------------- | ------------ | ----------------------------------------------------------------------------- |
+| `SX126X_CS`                | 150 variants | SX126x chip-select pin (often same as LORA_CS).                               |
+| `SX126X_RESET`             | 150 variants | SX126x reset pin (often same as LORA_RESET).                                  |
+| `SX126X_BUSY`              | 150 variants | SX126x BUSY pin; must be polled low before issuing SPI commands.              |
+| `SX126X_DIO1`              | 150 variants | SX126x DIO1 interrupt output used for all IRQ events.                         |
+| `USE_SX1262`               | 145 variants | Select the SX1262 sub-GHz LoRa chip driver.                                   |
+| `SX126X_DIO3_TCXO_VOLTAGE` | 140 variants | Drives the TCXO regulator via DIO3; set to the supply voltage (e.g., 1.8).    |
+| `LORA_CS`                  | 137 variants | LoRa radio SPI chip-select GPIO pin.                                          |
+| `LORA_RESET`               | 135 variants | LoRa radio hardware-reset GPIO pin (active low).                              |
+| `SX126X_DIO2_AS_RF_SWITCH` | 135 variants | Set to 1 so the driver controls the TX/RX RF switch via DIO2.                 |
+| `LORA_DIO1`                | 130 variants | LoRa radio DIO1 interrupt pin; on SX126x this is the primary IRQ line.        |
+| `LORA_SCK`                 | 125 variants | LoRa radio SPI clock pin.                                                     |
+| `LORA_MISO`                | 125 variants | LoRa radio SPI MISO pin.                                                      |
+| `LORA_MOSI`                | 125 variants | LoRa radio SPI MOSI pin.                                                      |
+| `LORA_DIO2`                | 110 variants | LoRa radio DIO2 pin; on RF95 used for FSK interrupt; on SX126x tx/rx control. |
+| `LORA_DIO0`                | 98 variants  | LoRa radio DIO0 interrupt pin (RF95/SX1276 done/RxDone).                      |
+
+### GPS
+
+| Macro                     | Used in      | Description                                                                    |
+| ------------------------- | ------------ | ------------------------------------------------------------------------------ |
+| `GPS_RX_PIN`              | 114 variants | UART RX pin connected to the GPS module TX output.                             |
+| `GPS_TX_PIN`              | 111 variants | UART TX pin connected to the GPS module RX input.                              |
+| `HAS_GPS`                 | 69 variants  | Set to 1 if the board has an on-board GPS receiver; 0 to disable GPS entirely. |
+| `PIN_GPS_PPS`             | 43 variants  | GPS pulse-per-second input pin for timing synchronisation.                     |
+| `PIN_GPS_EN`              | 30 variants  | GPIO to power-enable or power-gate the GPS module.                             |
+| `PIN_GPS_STANDBY`         | 29 variants  | Places the GPS into standby/low-power mode when driven.                        |
+| `GPS_THREAD_INTERVAL`     | 28 variants  | Millisecond poll interval for the GPS background thread.                       |
+| `GPS_L76K`                | 27 variants  | Selects the Quectel L76K GPS driver and protocol.                              |
+| `GPS_BAUDRATE`            | 27 variants  | UART baud rate for GPS serial communication.                                   |
+| `GPS_EN_ACTIVE`           | 17 variants  | Logic level (HIGH or LOW) that enables the GPS power pin.                      |
+| `PIN_GPS_RESET`           | 16 variants  | Hardware-reset line to the GPS module.                                         |
+| `GPS_DEFAULT_NOT_PRESENT` | 16 variants  | Compiled-in default assuming no GPS; overridden at runtime if detected.        |
+| `GPS_RESET_MODE`          | 13 variants  | Defines the reset signal polarity or protocol for the GPS chip.                |
+| `GPS_UBLOX`               | 8 variants   | Selects the u-blox GPS driver and UBX protocol.                                |
+| `PIN_GPS_REINIT`          | 7 variants   | Pin used to trigger GPS re-initialisation sequences.                           |
+
+### Display
+
+| Macro                         | Used in     | Description                                                              |
+| ----------------------------- | ----------- | ------------------------------------------------------------------------ |
+| `PIN_EINK_CS`                 | 51 variants | E-ink display SPI chip-select pin.                                       |
+| `PIN_EINK_BUSY`               | 51 variants | E-ink display BUSY output; high when a page update is in progress.       |
+| `PIN_EINK_DC`                 | 51 variants | E-ink display data/command select pin.                                   |
+| `PIN_EINK_RES`                | 51 variants | E-ink display hardware-reset pin.                                        |
+| `PIN_EINK_SCLK`               | 49 variants | E-ink display SPI clock pin.                                             |
+| `PIN_EINK_MOSI`               | 49 variants | E-ink display SPI MOSI pin.                                              |
+| `HAS_SCREEN`                  | 34 variants | Set to 1 if the board has any display hardware.                          |
+| `USE_TFTDISPLAY`              | 27 variants | Selects the TFT LCD driver path.                                         |
+| `TFT_HEIGHT`                  | 25 variants | Vertical pixel resolution of the TFT display.                            |
+| `TFT_WIDTH`                   | 25 variants | Horizontal pixel resolution of the TFT display.                          |
+| `SCREEN_TRANSITION_FRAMERATE` | 23 variants | Target framerate for UI animations and transitions.                      |
+| `TFT_OFFSET_X`                | 22 variants | Horizontal pixel offset for display alignment correction.                |
+| `TFT_OFFSET_Y`                | 22 variants | Vertical pixel offset for display alignment correction.                  |
+| `SCREEN_ROTATE`               | 18 variants | Non-zero value rotates the display 180° for mounted-upside-down screens. |
+| `TFT_BL`                      | 15 variants | Backlight control PWM or GPIO pin for the TFT panel.                     |
+
+### I2C/SPI
+
+| Macro                   | Used in      | Description                                           |
+| ----------------------- | ------------ | ----------------------------------------------------- |
+| `I2C_SDA`               | 103 variants | Primary I2C data line GPIO pin.                       |
+| `I2C_SCL`               | 103 variants | Primary I2C clock line GPIO pin.                      |
+| `PIN_SPI_MISO`          | 72 variants  | Primary SPI MISO (data from peripheral) GPIO pin.     |
+| `PIN_SPI_MOSI`          | 72 variants  | Primary SPI MOSI (data to peripheral) GPIO pin.       |
+| `PIN_SPI_SCK`           | 72 variants  | Primary SPI clock GPIO pin.                           |
+| `SPI_INTERFACES_COUNT`  | 66 variants  | Number of hardware SPI buses available on this board. |
+| `WIRE_INTERFACES_COUNT` | 64 variants  | Number of hardware I2C buses available on this board. |
+| `PIN_SPI1_MISO`         | 35 variants  | Secondary SPI bus MISO pin.                           |
+| `PIN_SPI1_MOSI`         | 35 variants  | Secondary SPI bus MOSI pin.                           |
+| `PIN_SPI1_SCK`          | 35 variants  | Secondary SPI bus clock pin.                          |
+| `SPI_FREQUENCY`         | 24 variants  | Default SPI clock frequency in Hz for this board.     |
+| `SPI_READ_FREQUENCY`    | 21 variants  | Reduced SPI clock rate used for read transactions.    |
+| `SPI_SCK`               | 19 variants  | SPI clock pin alias used in older board files.        |
+| `SPI_MOSI`              | 19 variants  | SPI MOSI pin alias used in older board files.         |
+| `SPI_MISO`              | 19 variants  | SPI MISO pin alias used in older board files.         |
+
+### Power
+
+| Macro                           | Used in      | Description                                                                |
+| ------------------------------- | ------------ | -------------------------------------------------------------------------- |
+| `BATTERY_PIN`                   | 128 variants | ADC input GPIO connected to the battery voltage divider.                   |
+| `ADC_MULTIPLIER`                | 122 variants | Floating-point scale factor to convert raw ADC reading to battery voltage. |
+| `ADC_CHANNEL`                   | 71 variants  | ADC channel enum or number for the battery sense input.                    |
+| `BATTERY_SENSE_RESOLUTION_BITS` | 64 variants  | ADC resolution in bits used for battery voltage sampling.                  |
+| `ADC_RESOLUTION`                | 49 variants  | Board-level ADC resolution definition, referenced by other power macros.   |
+| `BATTERY_SENSE_RESOLUTION`      | 44 variants  | Alias for the effective ADC resolution for battery sense.                  |
+| `ADC_CTRL`                      | 29 variants  | GPIO that enables or gates the ADC voltage-divider circuit.                |
+| `ADC_CTRL_ENABLED`              | 27 variants  | Logic level (HIGH or LOW) that turns on the ADC control switch.            |
+| `EXT_NOTIFY_OUT`                | 23 variants  | GPIO output used to signal an external LED or buzzer for notifications.    |
+| `USE_POWERSAVE`                 | 21 variants  | Enables aggressive power-save mode (deep sleep, reduced poll intervals).   |
+| `SLEEP_TIME`                    | 21 variants  | Default light-sleep duration in milliseconds between wakeups.              |
+| `ADC_ATTENUATION`               | 20 variants  | ESP32 ADC input attenuation setting; controls measurable voltage range.    |
+| `PIN_POWER_EN`                  | 18 variants  | GPIO to assert to enable a board power rail or load switch.                |
+| `BATTERY_SENSE_SAMPLES`         | 11 variants  | Number of ADC samples to average for a stable battery reading.             |
+| `HAS_PPM`                       | 4 variants   | Set to 1 if the board has an IP5306 or similar PPM power path IC.          |
+
+### Connectivity/Other
+
+| Macro             | Used in     | Description                                                         |
+| ----------------- | ----------- | ------------------------------------------------------------------- |
+| `HAS_TOUCHSCREEN` | 19 variants | Set to 1 for boards with a capacitive or resistive touch panel.     |
+| `HAS_NEOPIXEL`    | 14 variants | Set to 1 if the board has addressable RGB LEDs (WS2812 / NeoPixel). |
+| `PCF8563_RTC`     | 11 variants | I2C address of the PCF8563 real-time clock IC.                      |
+| `HAS_ETHERNET`    | 9 variants  | Set to 1 for boards with a wired Ethernet interface.                |
+| `HAS_I2S`         | 7 variants  | Set to 1 if I2S audio output is present.                            |
+| `PCF85063_RTC`    | 3 variants  | I2C address of the PCF85063 real-time clock IC.                     |
+| `NFC_INT`         | 2 variants  | Interrupt pin from the NFC controller IC.                           |
+| `NFC_CS`          | 2 variants  | SPI chip-select for the NFC controller.                             |
+| `USE_XL9555`      | 2 variants  | Enables the XL9555 16-bit I2C GPIO expander driver.                 |
+| `EXPANDS_DRV_EN`  | 2 variants  | GPIO expander pin used to enable the haptic driver.                 |
+| `EXPANDS_AMP_EN`  | 2 variants  | GPIO expander pin used to power-on the audio amplifier.             |
+| `EXPANDS_KB_RST`  | 2 variants  | GPIO expander pin used to reset the keyboard controller.            |
+| `EXPANDS_LORA_EN` | 2 variants  | GPIO expander pin used to power-gate the LoRa radio.                |
+| `EXPANDS_GPS_EN`  | 2 variants  | GPIO expander pin used to power-gate the GPS module.                |
+| `EXPANDS_NFC_EN`  | 2 variants  | GPIO expander pin used to power-gate the NFC controller.            |
+
+### Other
+
+| Macro                | Used in     | Description                                                                |
+| -------------------- | ----------- | -------------------------------------------------------------------------- |
+| `LED_POWER`          | 94 variants | GPIO for the status LED, defines the LED pin number.                       |
+| `LED_STATE_ON`       | 88 variants | Logic level (HIGH or LOW) that turns the status LED on.                    |
+| `PIN_SERIAL1_RX`     | 67 variants | Secondary UART RX pin (used for accessories, GPS on some boards).          |
+| `PIN_SERIAL1_TX`     | 67 variants | Secondary UART TX pin.                                                     |
+| `PIN_WIRE_SDA`       | 64 variants | Arduino-framework I2C SDA pin alias (nRF52 / RP2040 style).                |
+| `PIN_WIRE_SCL`       | 64 variants | Arduino-framework I2C SCL pin alias.                                       |
+| `PIN_LED1`           | 63 variants | First LED GPIO pin in the nRF52 Arduino BSP pin table.                     |
+| `VARIANT_MCK`        | 63 variants | Crystal oscillator frequency in Hz for nRF52 variant clock configuration.  |
+| `PINS_COUNT`         | 63 variants | Total number of GPIO pins defined in the Arduino BSP variant table.        |
+| `NUM_DIGITAL_PINS`   | 63 variants | Count of digital-capable pins in the BSP variant table.                    |
+| `NUM_ANALOG_INPUTS`  | 63 variants | Count of analog-input pins in the BSP variant table.                       |
+| `NUM_ANALOG_OUTPUTS` | 63 variants | Count of analog-output (DAC) pins in the BSP variant table.                |
+| `LED_BLUE`           | 62 variants | GPIO number of the blue status LED (typical on nRF52 and RP2040 boards).   |
+| `USE_LFXO`           | 58 variants | Instructs the nRF52 BSP to use the low-frequency crystal oscillator.       |
+| `BUTTON_NEED_PULLUP` | 54 variants | Enables internal pull-up on the button GPIO (duplicate entry for clarity). |
+
+## Architecture and Environment Inventory
+
+### diy
+
+| Environment               | Display Name | HW Model | HW Slug | Variant Dir                                   | Common Categories                                         |
+| ------------------------- | ------------ | -------- | ------- | --------------------------------------------- | --------------------------------------------------------- |
+| 9m2ibr_aprs_lora_tracker  |              |          |         | variants/esp32/diy/9m2ibr_aprs_lora_tracker   | Display:1, Radio:24, Input:1, GPS:2, Power:4              |
+| esp32c3_super_mini        |              |          |         | variants/esp32c3/diy/esp32c3_super_mini       | Display:1, Radio:18, Input:1, GPS:2                       |
+| meshtastic-diy-v1_1       |              |          |         | variants/esp32/diy/v1_1                       | Radio:24, Input:1, GPS:1, Power:1                         |
+| my-esp32s3-diy-eink       |              |          |         | variants/esp32s3/diy/my_esp32s3_diy_eink      | Display:6, Radio:17, Input:1, GPS:1, Connectivity/Other:1 |
+| my-esp32s3-diy-oled       |              |          |         | variants/esp32s3/diy/my_esp32s3_diy_oled      | Display:1, Radio:17, Input:1, GPS:1, Connectivity/Other:1 |
+| nrf52_promicro_diy-inkhud |              |          |         | variants/nrf52840/diy/nrf52_promicro_diy_tcxo | Display:4, Radio:29, Input:1, GPS:4, Power:6              |
+| t-energy-s3_e22           |              |          |         | variants/esp32s3/diy/t-energy-s3_e22          | Display:1, Radio:18, Input:1, GPS:3, Power:3              |
+
+### esp32
+
+| Environment                 | Display Name                | HW Model | HW Slug                     | Variant Dir                                | Common Categories                                                  |
+| --------------------------- | --------------------------- | -------- | --------------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
+| betafpv_2400_tx_micro       |                             |          |                             | variants/esp32/betafpv_2400_tx_micro       | Radio:14, Input:1, Connectivity/Other:1                            |
+| betafpv_900_tx_nano         |                             |          |                             | variants/esp32/betafpv_900_tx_nano         | Display:1, Radio:10, Input:1                                       |
+| chatter2                    |                             |          |                             | variants/esp32/chatter2                    | Display:12, Radio:16, Input:3, GPS:3, Power:4                      |
+| hackerboxes-esp32-io        |                             |          |                             | variants/esp32/hackerboxes_esp32_io        | Display:1, Radio:16, Input:1, GPS:1                                |
+| heltec-v1                   | Heltec V1                   | 11       | HELTEC_V1                   | variants/esp32/heltec_v1                   | Radio:5, Input:1, GPS:2, Power:3                                   |
+| heltec-v2_0                 | Heltec V2.0                 | 5        | HELTEC_V2_0                 | variants/esp32/heltec_v2                   | Radio:5, Input:1, GPS:2, Power:3                                   |
+| heltec-v2_1                 | Heltec V2.1                 | 10       | HELTEC_V2_1                 | variants/esp32/heltec_v2.1                 | Radio:5, Input:1, GPS:3, Power:4                                   |
+| heltec-wireless-bridge      |                             |          |                             | variants/esp32/heltec_wireless_bridge      | Radio:9, GPS:1                                                     |
+| heltec-wsl-v2_1             |                             |          |                             | variants/esp32/heltec_wsl_v2.1             | Radio:9, Input:1, Power:5                                          |
+| hydra                       | Hydra                       | 39       | HYDRA                       | variants/esp32/diy/hydra                   | Radio:22, Input:1, GPS:3, Power:4                                  |
+| m5stack-core                | M5 Stack                    | 42       | M5STACK                     | variants/esp32/m5stack_core                | Display:7, Radio:9, Input:1, GPS:2                                 |
+| m5stack-coreink             |                             |          |                             | variants/esp32/m5stack_coreink             | Display:7, Radio:34, Input:1, GPS:2, Power:3, Connectivity/Other:1 |
+| meshtastic-diy-v1           | DIY V1                      | 39       | DIY_V1                      | variants/esp32/diy/v1                      | Radio:23, Input:1, GPS:3, Power:4                                  |
+| meshtastic-dr-dev           | DR-DEV                      | 41       | DR_DEV                      | variants/esp32/diy/dr-dev                  | Display:1, Radio:26, Input:1, GPS:2, Power:3                       |
+| nano-g1                     | Nano G1                     | 14       | NANO_G1                     | variants/esp32/nano-g1                     | Display:1, Radio:13, Input:1, GPS:2, Power:1                       |
+| nano-g1-explorer            | Nano G1 Explorer            | 17       | NANO_G1_EXPLORER            | variants/esp32/nano-g1-explorer            | Display:1, Radio:13, Input:1, GPS:2, Power:5                       |
+| radiomaster_900_bandit      |                             |          |                             | variants/esp32/radiomaster_900_bandit      | Radio:19, Input:1, GPS:1, Connectivity/Other:1                     |
+| radiomaster_900_bandit_nano | RadioMaster 900 Bandit Nano | 64       | RADIOMASTER_900_BANDIT_NANO | variants/esp32/radiomaster_900_bandit_nano | Display:1, Radio:19                                                |
+| rak11200                    | RAK WisBlock 11200          | 13       | RAK11200                    | variants/esp32/rak11200                    | Radio:18, GPS:2, Power:2                                           |
+| station-g1                  | Station G1                  | 25       | STATION_G1                  | variants/esp32/station-g1                  | Display:1, Radio:13, Input:1, GPS:2, Power:5                       |
+| sugarcube                   |                             |          |                             | variants/esp32/tlora_v2_1_16               | Radio:6, Power:4                                                   |
+| tbeam                       | LILYGO T-Beam               | 4        | TBEAM                       | variants/esp32/tbeam                       | Display:4, Radio:14, Input:1, GPS:3, Power:2, Connectivity/Other:1 |
+| tbeam-displayshield         |                             |          |                             | variants/esp32/tbeam                       | Display:4, Radio:14, Input:1, GPS:3, Power:2, Connectivity/Other:1 |
+| tbeam0_7                    | LILYGO T-Beam V0.7          | 6        | TBEAM_V0P7                  | variants/esp32/tbeam_v07                   | Radio:5, Input:1, GPS:3, Power:3                                   |
+| tlora-v1                    | LILYGO T-LoRa V1            | 2        | TLORA_V1                    | variants/esp32/tlora_v1                    | Radio:5, Input:1, Power:1                                          |
+| tlora-v2                    | LILYGO T-LoRa V2            | 1        | TLORA_V2                    | variants/esp32/tlora_v2                    | Radio:5, Input:1, Power:2                                          |
+| tlora-v2-1-1_6              | LILYGO T-LoRa V2.1-1.6      | 3        | TLORA_V2_1_1P6              | variants/esp32/tlora_v2_1_16               | Radio:6, Power:4                                                   |
+| tlora-v2-1-1_8              | LILYGO T-LoRa V2.1-1.8      | 15       | TLORA_V2_1_1P8              | variants/esp32/tlora_v2_1_18               | Radio:6, Input:1, Power:3                                          |
+| tlora_v1_3                  |                             |          |                             | variants/esp32/tlora_v1_3                  | Radio:5, Input:1, Power:2                                          |
+| trackerd                    |                             |          |                             | variants/esp32/trackerd                    | Display:1, Radio:5, Input:1, GPS:9, Power:4                        |
+| wiphone                     |                             |          |                             | variants/esp32/wiphone                     | Display:9, Radio:9, GPS:1                                          |
+
+### esp32-c3
+
+| Environment                | Display Name | HW Model | HW Slug     | Variant Dir                               | Common Categories                                                  |
+| -------------------------- | ------------ | -------- | ----------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| ai-c3                      |              |          |             | variants/esp32c3/ai-c3                    | Radio:15, Input:1, GPS:1                                           |
+| hackerboxes-esp32c3-oled   |              |          |             | variants/esp32c3/hackerboxes_esp32c3_oled | Display:1, Radio:16, Input:1, GPS:1                                |
+| heltec-hru-3601            |              |          |             | variants/esp32c3/heltec_hru_3601          | Display:1, Radio:16, Input:1, GPS:1, Power:1, Connectivity/Other:1 |
+| heltec-ht62-esp32c3-sx1262 | Heltec HT62  | 53       | HELTEC_HT62 | variants/esp32c3/heltec_esp32c3           | Display:1, Radio:16, Input:1, GPS:1                                |
+| m5stack-stamp-c3           |              |          |             | variants/esp32c3/m5stack-stamp-c3         | Radio:9, Input:1, GPS:1                                            |
+
+### esp32-c6
+
+| Environment     | Display Name     | HW Model | HW Slug     | Variant Dir                      | Common Categories                                |
+| --------------- | ---------------- | -------- | ----------- | -------------------------------- | ------------------------------------------------ |
+| m5stack-unitc6l | M5Stack Unit C6L | 111      | M5STACK_C6L | variants/esp32c6/m5stack_unitc6l | Display:1, Radio:14, GPS:3, Connectivity/Other:1 |
+| tlora-c6        |                  |          |             | variants/esp32c6/tlora_c6        | Radio:15                                         |
+
+### esp32-s3
+
+| Environment                      | Display Name                  | HW Model | HW Slug                      | Variant Dir                                   | Common Categories                                                    |
+| -------------------------------- | ----------------------------- | -------- | ---------------------------- | --------------------------------------------- | -------------------------------------------------------------------- |
+| CDEBYTE_EoRa-Hub                 |                               |          |                              | variants/esp32s3/CDEBYTE_EoRa-Hub             | Display:2, Radio:14, Input:1, Power:6                                |
+| CDEBYTE_EoRa-S3                  | EBYTE EoRa-S3                 | 61       | CDEBYTE_EORA_S3              | variants/esp32s3/CDEBYTE_EoRa-S3              | Display:2, Radio:13, Input:1, Power:3                                |
+| EBYTE_ESP32-S3                   |                               |          |                              | variants/esp32s3/EBYTE_ESP32-S3               | Display:1, Radio:26, Input:1, GPS:5, Power:1                         |
+| ESP32-S3-Pico                    |                               |          |                              | variants/esp32s3/esp32-s3-pico                | Display:6, Radio:18, Input:2, GPS:1, Power:4, Connectivity/Other:1   |
+| bpi_picow_esp32_s3               |                               |          |                              | variants/esp32s3/bpi_picow_esp32_s3           | Display:1, Radio:25, Input:1, GPS:1                                  |
+| crowpanel-esp32s3-2-epaper       |                               |          |                              | variants/esp32s3/crowpanel-esp32s3-5-epaper   | Display:6, Radio:21, Input:1, GPS:1, Power:1                         |
+| crowpanel-esp32s3-4-epaper       |                               |          |                              | variants/esp32s3/crowpanel-esp32s3-5-epaper   | Display:6, Radio:21, Input:1, GPS:1, Power:1                         |
+| crowpanel-esp32s3-5-epaper       |                               |          |                              | variants/esp32s3/crowpanel-esp32s3-5-epaper   | Display:6, Radio:21, Input:1, GPS:1, Power:1                         |
+| dreamcatcher-2206                |                               |          |                              | variants/esp32s3/dreamcatcher                 | Radio:16, Input:1, Power:1, Connectivity/Other:1                     |
+| elecrow-adv-24-28-tft            | Crowpanel Adv 2.4/2.8 TFT     | 97       | CROWPANEL                    | variants/esp32s3/elecrow_panel                | Display:1, Radio:21, GPS:6, Power:2                                  |
+| elecrow-adv-35-tft               | Crowpanel Adv 3.5 TFT         | 97       | CROWPANEL                    | variants/esp32s3/elecrow_panel                | Display:1, Radio:21, GPS:6, Power:2                                  |
+| elecrow-adv1-43-50-70-tft        | Crowpanel Adv 4.3/5.0/7.0 TFT | 97       | CROWPANEL                    | variants/esp32s3/elecrow_panel                | Display:1, Radio:21, GPS:6, Power:2                                  |
+| hackaday-communicator            |                               |          |                              | variants/esp32s3/hackaday-communicator        | Display:12, Radio:14, Input:1, GPS:1, Power:2                        |
+| heltec-v3                        | Heltec V3                     | 43       | HELTEC_V3                    | variants/esp32s3/heltec_v3                    | Display:1, Radio:16, Input:1, Power:6                                |
+| heltec-v4                        | Heltec V4                     | 110      | HELTEC_V4                    | variants/esp32s3/heltec_v4                    | Display:1, Radio:21, Input:1, GPS:10, Power:6                        |
+| heltec-v4-tft                    | Heltec V4 TFT                 | 110      | HELTEC_V4                    | variants/esp32s3/heltec_v4                    | Display:1, Radio:21, Input:1, GPS:10, Power:6                        |
+| heltec-vision-master-e213        | Heltec Vision Master E213     | 67       | HELTEC_VISION_MASTER_E213    | variants/esp32s3/heltec_vision_master_e213    | Display:6, Radio:15, Input:2, Power:6                                |
+| heltec-vision-master-e213-inkhud |                               |          |                              | variants/esp32s3/heltec_vision_master_e213    | Display:6, Radio:15, Input:2, Power:6                                |
+| heltec-vision-master-e290        | Heltec Vision Master E290     | 68       | HELTEC_VISION_MASTER_E290    | variants/esp32s3/heltec_vision_master_e290    | Display:6, Radio:15, Input:2, Power:6                                |
+| heltec-vision-master-e290-inkhud |                               |          |                              | variants/esp32s3/heltec_vision_master_e290    | Display:6, Radio:15, Input:2, Power:6                                |
+| heltec-vision-master-t190        | Heltec Vision Master T190     | 66       | HELTEC_VISION_MASTER_T190    | variants/esp32s3/heltec_vision_master_t190    | Display:6, Radio:16, Input:2, Power:6                                |
+| heltec-wireless-paper            | Heltec Wireless Paper         | 49       | HELTEC_WIRELESS_PAPER        | variants/esp32s3/heltec_wireless_paper        | Display:6, Radio:15, Input:1, Power:6                                |
+| heltec-wireless-paper-inkhud     |                               |          |                              | variants/esp32s3/heltec_wireless_paper        | Display:6, Radio:15, Input:1, Power:6                                |
+| heltec-wireless-paper-v1_0       | Heltec Wireless Paper V1.0    | 57       | HELTEC_WIRELESS_PAPER_V1_0   | variants/esp32s3/heltec_wireless_paper_v1     | Display:6, Radio:15, Input:1, Power:6                                |
+| heltec-wireless-tracker          | Heltec Wireless Tracker V1.1  | 48       | HELTEC_WIRELESS_TRACKER      | variants/esp32s3/heltec_wireless_tracker      | Display:9, Radio:16, Input:1, GPS:7, Power:6                         |
+| heltec-wireless-tracker-V1-0     | Heltec Wireless Tracker V1.0  | 58       | HELTEC_WIRELESS_TRACKER_V1_0 | variants/esp32s3/heltec_wireless_tracker_V1_0 | Display:9, Radio:16, Input:1, GPS:9, Power:4                         |
+| heltec-wireless-tracker-v2       | Heltec Wireless Tracker V2    | 113      | HELTEC_WIRELESS_TRACKER_V2   | variants/esp32s3/heltec_wireless_tracker_v2   | Display:10, Radio:19, Input:1, GPS:7, Power:6                        |
+| heltec-wsl-v3                    | Heltec Wireless Stick Lite V3 | 44       | HELTEC_WSL_V3                | variants/esp32s3/heltec_wsl_v3                | Radio:16, Input:1, Power:6                                           |
+| heltec_capsule_sensor_v3         |                               |          |                              | variants/esp32s3/heltec_capsule_sensor_v3     | Display:1, Radio:16, Input:1, GPS:7, Power:6                         |
+| heltec_sensor_hub                |                               |          |                              | variants/esp32s3/heltec_sensor_hub            | Display:1, Radio:15, Input:1, Power:6, Connectivity/Other:1          |
+| icarus                           |                               |          |                              | variants/esp32s3/icarus                       | Display:1, Radio:12, Input:1                                         |
+| link32-s3-v1                     |                               |          |                              | variants/esp32s3/link32_s3_v1                 | Display:1, Radio:16, Input:2, Power:4, Connectivity/Other:1          |
+| m5stack-cardputer-adv            |                               |          |                              | variants/esp32s3/m5stack_cardputer_adv        | Display:5, Radio:17, Input:2, GPS:4, Power:3, Connectivity/Other:2   |
+| m5stack-cores3                   |                               |          |                              | variants/esp32s3/m5stack_cores3               | Radio:11, Power:1                                                    |
+| mesh-tab-3-2-IPS-capacitive      |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mesh-tab-3-2-IPS-resistive       |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mesh-tab-3-2-TN-resistive        |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mesh-tab-3-5-IPS-capacitive      |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mesh-tab-3-5-IPS-resistive       |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mesh-tab-3-5-TN-resistive        |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mesh-tab-4-0-IPS-capacitive      |                               |          |                              | variants/esp32s3/mesh-tab                     | Radio:18, Input:1, GPS:2, Power:5, Connectivity/Other:1              |
+| mini-epaper-s3                   | LILYGO Mini ePaper S3 E-Ink   |          | MINI_EPAPER_S3               | variants/esp32s3/mini-epaper-s3               | Display:8, Radio:12, Input:5, GPS:1, Power:3, Connectivity/Other:1   |
+| mini-epaper-s3-inkhud            |                               |          |                              | variants/esp32s3/mini-epaper-s3               | Display:8, Radio:12, Input:5, GPS:1, Power:3, Connectivity/Other:1   |
+| nibble-esp32                     |                               |          |                              | variants/esp32s3/nibble_esp32                 | Radio:9, Input:1                                                     |
+| nugget-s3-lora                   |                               |          |                              | variants/esp32s3/nugget_s3_lora               | Display:2, Radio:9, Input:1, Connectivity/Other:1                    |
+| picomputer-s3                    | Pi Computer S3                | 52       | PICOMPUTER_S3                | variants/esp32s3/picomputer-s3                | Display:10, Radio:9, Input:1, Power:3                                |
+| picomputer-s3-tft                |                               |          |                              | variants/esp32s3/picomputer-s3                | Display:10, Radio:9, Input:1, Power:3                                |
+| rak3112                          |                               |          |                              | variants/esp32s3/rak3312                      | Radio:13, GPS:3, Power:5                                             |
+| rak3312                          | RAK3312                       | 106      | RAK3312                      | variants/esp32s3/rak3312                      | Radio:13, GPS:3, Power:5                                             |
+| rak_wismesh_tap_v2               | RAK WisMesh Tap V2            | 116      | WISMESH_TAP_V2               | variants/esp32s3/rak_wismesh_tap_v2           | Radio:13, Input:1, GPS:3, Power:4                                    |
+| rak_wismesh_tap_v2-tft           |                               |          |                              | variants/esp32s3/rak_wismesh_tap_v2           | Radio:13, Input:1, GPS:3, Power:4                                    |
+| seeed-sensecap-indicator         | Seeed SenseCAP Indicator      | 70       | SENSECAP_INDICATOR           | variants/esp32s3/seeed-sensecap-indicator     | Display:12, Radio:17, Input:1, GPS:4, Connectivity/Other:1           |
+| seeed-sensecap-indicator-tft     |                               |          |                              | variants/esp32s3/seeed-sensecap-indicator     | Display:12, Radio:17, Input:1, GPS:4, Connectivity/Other:1           |
+| seeed-xiao-s3                    | Seeed Xiao ESP32-S3           | 81       | SEEED_XIAO_S3                | variants/esp32s3/seeed_xiao_s3                | Radio:16, Input:1, GPS:6, Power:3                                    |
+| station-g2                       | Station G2                    | 31       | STATION_G2                   | variants/esp32s3/station-g2                   | Display:1, Radio:14, Input:1, GPS:2, Power:4                         |
+| t-beam-1w                        | LILYGO T-Beam 1W              | 122      | TBEAM_1_WATT                 | variants/esp32s3/t-beam-1w                    | Display:3, Radio:19, Input:2, GPS:6, Power:5                         |
+| t-deck                           | LILYGO T-Deck                 | 50       | T_DECK                       | variants/esp32s3/t-deck                       | Display:11, Radio:17, Input:3, GPS:3, Power:5, Connectivity/Other:2  |
+| t-deck-pro                       | LILYGO T-Deck Pro             | 102      | T_DECK_PRO                   | variants/esp32s3/t-deck-pro                   | Display:6, Radio:18, Input:2, GPS:7, Power:5, Connectivity/Other:1   |
+| t-deck-tft                       |                               |          |                              | variants/esp32s3/t-deck                       | Display:11, Radio:17, Input:3, GPS:3, Power:5, Connectivity/Other:2  |
+| t-eth-elite                      |                               |          |                              | variants/esp32s3/t-eth-elite                  | Display:1, Radio:34, Input:1, GPS:5, Connectivity/Other:1            |
+| t-watch-s3                       | LILYGO T-Watch S3             | 51       | T_WATCH_S3                   | variants/esp32s3/t-watch-s3                   | Display:12, Radio:17, Input:1, GPS:5, Power:3, Connectivity/Other:3  |
+| t5s3_epaper_inkhud               |                               |          |                              | variants/esp32s3/t5s3_epaper                  | Radio:21, Input:3, GPS:2, Power:5, Connectivity/Other:3              |
+| tbeam-s3-core                    | LILYGO T-Beam Supreme         | 12       | LILYGO_TBEAM_S3_CORE         | variants/esp32s3/tbeam-s3-core                | Display:1, Radio:25, Input:1, GPS:4, Power:1, Connectivity/Other:2   |
+| thinknode_m2                     | ThinkNode M2                  | 90       | THINKNODE_M2                 | variants/esp32s3/ELECROW-ThinkNode-M2         | Display:2, Radio:14, Input:2, GPS:1, Power:6                         |
+| thinknode_m5                     | ThinkNode M5                  | 107      | THINKNODE_M5                 | variants/esp32s3/ELECROW-ThinkNode-M5         | Display:6, Radio:14, Input:2, GPS:8, Power:4, Connectivity/Other:1   |
+| tlora-pager                      | LILYGO T-LoRa Pager           | 103      | T_LORA_PAGER                 | variants/esp32s3/tlora-pager                  | Display:10, Radio:30, Input:6, GPS:5, Power:5, Connectivity/Other:17 |
+| tlora-pager-tft                  |                               |          |                              | variants/esp32s3/tlora-pager                  | Display:10, Radio:30, Input:6, GPS:5, Power:5, Connectivity/Other:17 |
+| tlora-t3s3-epaper                | LILYGO T-LoRa T3-S3 E-Ink     | 16       | TLORA_T3_S3                  | variants/esp32s3/tlora_t3s3_epaper            | Display:6, Radio:28, Input:1, GPS:3, Power:3                         |
+| tlora-t3s3-epaper-inkhud         |                               |          |                              | variants/esp32s3/tlora_t3s3_epaper            | Display:6, Radio:28, Input:1, GPS:3, Power:3                         |
+| tlora-t3s3-v1                    | LILYGO T-LoRa T3-S3           | 16       | TLORA_T3_S3                  | variants/esp32s3/tlora_t3s3_v1                | Display:1, Radio:36, Input:1, Power:3                                |
+| unphone                          | unPhone                       | 59       | UNPHONE                      | variants/esp32s3/unphone                      | Display:9, Radio:9, Input:3, GPS:1, Power:2, Connectivity/Other:1    |
+| unphone-tft                      |                               |          |                              | variants/esp32s3/unphone                      | Display:9, Radio:9, Input:3, GPS:1, Power:2, Connectivity/Other:1    |
+
+### esp32s2
+
+| Environment    | Display Name | HW Model | HW Slug | Variant Dir                     | Common Categories                      |
+| -------------- | ------------ | -------- | ------- | ------------------------------- | -------------------------------------- |
+| nugget-s2-lora |              |          |         | variants/esp32s2/nugget_s2_lora | Radio:9, Input:1, Connectivity/Other:1 |
+
+### native
+
+| Environment      | Display Name | HW Model | HW Slug | Variant Dir                         | Common Categories |
+| ---------------- | ------------ | -------- | ------- | ----------------------------------- | ----------------- |
+| buildroot        |              |          |         | variants/native/portduino-buildroot | Display:2, GPS:1  |
+| coverage         |              |          |         | variants/native/portduino           | Display:2, GPS:1  |
+| native           |              |          |         | variants/native/portduino           | Display:2, GPS:1  |
+| native-fb        |              |          |         | variants/native/portduino           | Display:2, GPS:1  |
+| native-tft       |              |          |         | variants/native/portduino           | Display:2, GPS:1  |
+| native-tft-debug |              |          |         | variants/native/portduino           | Display:2, GPS:1  |
+
+### nrf52840
+
+| Environment                      | Display Name               | HW Model | HW Slug                   | Variant Dir                                    | Common Categories                                         |
+| -------------------------------- | -------------------------- | -------- | ------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
+| ME25LS01-4Y10TD                  |                            |          |                           | variants/nrf52840/ME25LS01-4Y10TD              | Radio:8, Input:1, GPS:8, Power:4                          |
+| ME25LS01-4Y10TD_e-ink            |                            |          |                           | variants/nrf52840/ME25LS01-4Y10TD_e-ink        | Display:6, Radio:8, Input:1, GPS:8, Power:4               |
+| TWC_mesh_v4                      |                            |          |                           | variants/nrf52840/TWC_mesh_v4                  | Display:1, Radio:7, GPS:4, Power:5                        |
+| canaryone                        | Canary One                 | 29       | CANARYONE                 | variants/nrf52840/canaryone                    | Radio:7, GPS:8, Power:5                                   |
+| feather_diy                      |                            |          |                           | variants/nrf52840/feather_diy                  | Radio:17, Input:1                                         |
+| gat562_mesh_trial_tracker        |                            |          |                           | variants/nrf52840/gat562_mesh_trial_tracker    | Display:2, Radio:8, GPS:4, Power:5                        |
+| heltec-mesh-node-t096            | Heltec Mesh Node 096       | 127      | HELTEC_MESH_NODE_T096     | variants/nrf52840/heltec_mesh_node_t096        | Display:8, Radio:11, GPS:10, Power:9                      |
+| heltec-mesh-node-t114            | Heltec Mesh Node T114      | 69       | HELTEC_MESH_NODE_T114     | variants/nrf52840/heltec_mesh_node_t114        | Display:7, Radio:8, GPS:7, Power:8, Connectivity/Other:1  |
+| heltec-mesh-node-t114-inkhud     |                            |          |                           | variants/nrf52840/heltec_mesh_node_t114-inkhud | Display:6, Radio:8, GPS:7, Power:7, Connectivity/Other:1  |
+| heltec-mesh-pocket-10000         | Heltec Mesh Pocket         | 94       | HELTEC_MESH_POCKET        | variants/nrf52840/heltec_mesh_pocket           | Display:6, Radio:8, GPS:1, Power:7                        |
+| heltec-mesh-pocket-10000-inkhud  | Heltec Mesh Pocket         | 94       | HELTEC_MESH_POCKET        | variants/nrf52840/heltec_mesh_pocket           | Display:6, Radio:8, GPS:1, Power:7                        |
+| heltec-mesh-pocket-5000          | Heltec Mesh Pocket         | 94       | HELTEC_MESH_POCKET        | variants/nrf52840/heltec_mesh_pocket           | Display:6, Radio:8, GPS:1, Power:7                        |
+| heltec-mesh-pocket-5000-inkhud   | Heltec Mesh Pocket         | 94       | HELTEC_MESH_POCKET        | variants/nrf52840/heltec_mesh_pocket           | Display:6, Radio:8, GPS:1, Power:7                        |
+| heltec-mesh-solar                | Heltec MeshSolar           | 108      | HELTEC_MESH_SOLAR         | variants/nrf52840/heltec_mesh_solar            | Radio:8, GPS:6                                            |
+| heltec-mesh-solar-eink           |                            |          |                           | variants/nrf52840/heltec_mesh_solar            | Radio:8, GPS:6                                            |
+| heltec-mesh-solar-inkhud         |                            |          |                           | variants/nrf52840/heltec_mesh_solar            | Radio:8, GPS:6                                            |
+| heltec-mesh-solar-oled           |                            |          |                           | variants/nrf52840/heltec_mesh_solar            | Radio:8, GPS:6                                            |
+| heltec-mesh-solar-tft            |                            |          |                           | variants/nrf52840/heltec_mesh_solar            | Radio:8, GPS:6                                            |
+| makerpython_nrf52840_sx1280_eink |                            |          |                           | variants/nrf52840/MakePython_nRF52840_eink     | Display:6, Radio:6, GPS:4, Power:5                        |
+| makerpython_nrf52840_sx1280_oled |                            |          |                           | variants/nrf52840/MakePython_nRF52840_oled     | Radio:6, GPS:4, Power:5                                   |
+| meshlink                         |                            |          |                           | variants/nrf52840/meshlink                     | Display:6, Radio:7, Input:1, GPS:5, Power:5               |
+| meshlink_eink                    |                            |          |                           | variants/nrf52840/meshlink                     | Display:6, Radio:7, Input:1, GPS:5, Power:5               |
+| meshtiny                         |                            |          |                           | variants/nrf52840/meshtiny                     | Display:2, Radio:8, Input:5, Power:5                      |
+| minimesh_lite                    |                            |          |                           | variants/nrf52840/dls_Minimesh_Lite            | Radio:15, Input:1, GPS:4, Power:6                         |
+| monteops_hw1                     |                            |          |                           | variants/nrf52840/monteops_hw1                 | Radio:8, GPS:3, Power:5, Connectivity/Other:1             |
+| ms24sf1                          |                            |          |                           | variants/nrf52840/MS24SF1                      | Radio:8, Input:1, GPS:8, Power:4                          |
+| muzi-base                        | muzi BASE                  | 93       | MUZI_BASE                 | variants/nrf52840/muzi_base                    | Display:3, Radio:19, Input:1, GPS:4, Power:5              |
+| nano-g2-ultra                    | Nano G2 Ultra              | 18       | NANO_G2_ULTRA             | variants/nrf52840/nano-g2-ultra                | Display:1, Radio:7, GPS:4, Power:6, Connectivity/Other:1  |
+| nrf52_promicro_diy_tcxo          | NRF52 Pro-micro DIY        | 63       | NRF52_PROMICRO_DIY        | variants/nrf52840/diy/nrf52_promicro_diy_tcxo  | Display:4, Radio:29, Input:1, GPS:4, Power:6              |
+| pca10059_diy_eink                |                            |          |                           | variants/nrf52840/Dongle_nRF52840-pca10059-v1  | Display:7, Radio:8, GPS:4, Power:5                        |
+| r1-neo                           | muzi R1 Neo                | 101      | MUZI_R1_NEO               | variants/nrf52840/r1-neo                       | Display:1, Radio:8, GPS:4, Power:5                        |
+| rak2560                          | RAK WisMesh Repeater       | 22       | WISMESH_HUB               | variants/nrf52840/rak2560                      | Display:6, Radio:8, GPS:2, Power:5                        |
+| rak3401-1watt                    | RAK3401 1W                 | 117      | RAK3401                   | variants/nrf52840/rak3401_1watt                | Display:6, Radio:12, GPS:3, Power:5                       |
+| rak4631                          | RAK WisBlock 4631          | 9        | RAK4631                   | variants/nrf52840/rak4631                      | Display:6, Radio:8, GPS:3, Power:7, Connectivity/Other:1  |
+| rak4631_dbg                      |                            |          |                           | variants/nrf52840/rak4631                      | Display:6, Radio:8, GPS:3, Power:7, Connectivity/Other:1  |
+| rak4631_eink                     |                            |          |                           | variants/nrf52840/rak4631_epaper               | Display:6, Radio:8, GPS:4, Power:5                        |
+| rak4631_eink_onrxtx              |                            |          |                           | variants/nrf52840/rak4631_epaper_onrxtx        | Display:6, Radio:8, Power:1                               |
+| rak4631_eth_gw                   |                            |          |                           | variants/nrf52840/rak4631_eth_gw               | Display:6, Radio:8, GPS:3, Power:5, Connectivity/Other:1  |
+| rak4631_eth_gw_dbg               |                            |          |                           | variants/nrf52840/rak4631_eth_gw               | Display:6, Radio:8, GPS:3, Power:5, Connectivity/Other:1  |
+| rak4631_nomadstar_meteor_pro     | NomadStar Meteor Pro       | 96       | NOMADSTAR_METEOR_PRO      | variants/nrf52840/rak4631_nomadstar_meteor_pro | Display:6, Radio:8, GPS:3, Power:5, Connectivity/Other:1  |
+| rak4631_nomadstar_meteor_pro_dbg |                            |          |                           | variants/nrf52840/rak4631_nomadstar_meteor_pro | Display:6, Radio:8, GPS:3, Power:5, Connectivity/Other:1  |
+| rak_wismeshtag                   | RAK WisMesh Tag            | 105      | WISMESH_TAG               | variants/nrf52840/rak_wismeshtag               | Display:7, Radio:8, GPS:4, Power:5                        |
+| rak_wismeshtap                   | RAK WisMesh Tap            | 84       | WISMESH_TAP               | variants/nrf52840/rak_wismeshtap               | Display:21, Radio:8, GPS:3, Power:7, Connectivity/Other:1 |
+| seeed_solar_node                 | Seeed SenseCAP Solar Node  | 95       | SEEED_SOLAR_NODE          | variants/nrf52840/seeed_solar_node             | Radio:9, Input:2, GPS:8, Power:3                          |
+| seeed_wio_tracker_L1             | Seeed Wio Tracker L1       | 99       | SEEED_WIO_TRACKER_L1      | variants/nrf52840/seeed_wio_tracker_L1         | Display:2, Radio:9, Input:1, GPS:7, Power:3               |
+| seeed_wio_tracker_L1_eink        | Seeed Wio Tracker L1 E-Ink | 100      | SEEED_WIO_TRACKER_L1_EINK | variants/nrf52840/seeed_wio_tracker_L1_eink    | Display:7, Radio:9, Input:1, GPS:7, Power:3               |
+| seeed_wio_tracker_L1_eink-inkhud |                            |          |                           | variants/nrf52840/seeed_wio_tracker_L1_eink    | Display:7, Radio:9, Input:1, GPS:7, Power:3               |
+| seeed_xiao_nrf52840_kit          | Seeed Xiao NRF52840 Kit    | 88       | XIAO_NRF52_KIT            | variants/nrf52840/seeed_xiao_nrf52840_kit      | Radio:19, Input:2, GPS:9, Power:6                         |
+| seeed_xiao_nrf52840_kit_i2c      |                            |          |                           | variants/nrf52840/seeed_xiao_nrf52840_kit      | Radio:19, Input:2, GPS:9, Power:6                         |
+| t-echo                           | LILYGO T-Echo              | 7        | T_ECHO                    | variants/nrf52840/t-echo                       | Display:7, Radio:8, GPS:7, Power:6, Connectivity/Other:1  |
+| t-echo-inkhud                    |                            |          |                           | variants/nrf52840/t-echo                       | Display:7, Radio:8, GPS:7, Power:6, Connectivity/Other:1  |
+| t-echo-lite                      | LILYGO T-Echo Lite         | 109      | T_ECHO_LITE               | variants/nrf52840/t-echo-lite                  | Display:6, Radio:9, GPS:10, Power:8                       |
+| t-echo-plus                      |                            |          |                           | variants/nrf52840/t-echo-plus                  | Display:8, Radio:8, GPS:7, Power:6                        |
+| thinknode_m1                     | ThinkNode M1               | 89       | THINKNODE_M1              | variants/nrf52840/ELECROW-ThinkNode-M1         | Display:7, Radio:8, Input:1, GPS:8, Power:8               |
+| thinknode_m1-inkhud              |                            |          |                           | variants/nrf52840/ELECROW-ThinkNode-M1         | Display:7, Radio:8, Input:1, GPS:8, Power:8               |
+| thinknode_m3                     | Elecrow ThinkNode M3       | 115      | THINKNODE_M3              | variants/nrf52840/ELECROW-ThinkNode-M3         | Radio:1, Input:2, GPS:8, Power:7, Connectivity/Other:1    |
+| thinknode_m4                     |                            |          |                           | variants/nrf52840/ELECROW-ThinkNode-M4         | Radio:8, GPS:12, Power:7                                  |
+| thinknode_m6                     | ThinkNode M6               | 120      | THINKNODE_M6              | variants/nrf52840/ELECROW-ThinkNode-M6         | Radio:7, GPS:9, Power:9, Connectivity/Other:1             |
+| tracker-t1000-e                  | Seeed SenseCAP T1000-E     | 71       | TRACKER_T1000_E           | variants/nrf52840/tracker-t1000-e              | Display:1, Radio:8, Input:1, GPS:13, Power:5              |
+| wio-sdk-wm1110                   |                            |          |                           | variants/nrf52840/wio-sdk-wm1110               | Radio:8, Input:1                                          |
+| wio-t1000-s                      |                            |          |                           | variants/nrf52840/wio-t1000-s                  | Radio:8, Input:1, GPS:12, Power:4                         |
+| wio-tracker-wm1110               | Seeed Wio WM1110 Tracker   | 21       | WIO_WM1110                | variants/nrf52840/wio-tracker-wm1110           | Radio:8, Input:1, GPS:3                                   |
+
+### rp2040
+
+| Environment          | Display Name        | HW Model | HW Slug     | Variant Dir                          | Common Categories                                |
+| -------------------- | ------------------- | -------- | ----------- | ------------------------------------ | ------------------------------------------------ |
+| catsniffer           |                     |          |             | variants/rp2040/ec_catsniffer        | Display:1, Radio:17, GPS:1                       |
+| challenger_2040_lora |                     |          |             | variants/rp2040/challenger_2040_lora | Radio:17, Input:1, Power:1                       |
+| feather_rp2040_rfm95 |                     |          |             | variants/rp2040/feather_rp2040_rfm95 | Radio:17, Input:1, Power:1                       |
+| nibble-rp2040        |                     |          |             | variants/rp2040/nibble_rp2040        | Radio:9, Input:1                                 |
+| pico                 | Raspberry Pi Pico   | 47       | RPI_PICO    | variants/rp2040/rpipico              | Radio:16, Input:1, Power:4                       |
+| pico_slowclock       |                     |          |             | variants/rp2040/rpipico-slowclock    | Display:2, Radio:16, Input:1, GPS:5, Power:4     |
+| picow                | Raspberry Pi Pico W | 47       | RPI_PICO    | variants/rp2040/rpipicow             | Radio:16, Input:1, Power:4, Connectivity/Other:1 |
+| rak11310             | RAK WisBlock 11310  | 26       | RAK11310    | variants/rp2040/rak11310             | Radio:17, Input:1, Power:3, Connectivity/Other:1 |
+| rp2040-lora          | RP2040 LoRa         | 30       | RP2040_LORA | variants/rp2040/rp2040-lora          | Radio:18, Input:1, Power:1                       |
+| senselora_rp2040     |                     |          |             | variants/rp2040/senselora_rp2040     | Display:1, Radio:9, Input:1, Power:1             |
+
+### rp2350
+
+| Environment | Display Name | HW Model | HW Slug | Variant Dir               | Common Categories                                |
+| ----------- | ------------ | -------- | ------- | ------------------------- | ------------------------------------------------ |
+| pico2       |              |          |         | variants/rp2350/rpipico2  | Radio:16, Input:1, Power:4                       |
+| pico2w      |              |          |         | variants/rp2350/rpipico2w | Radio:16, Input:1, Power:4, Connectivity/Other:1 |
+
+### stm32
+
+| Environment     | Display Name | HW Model | HW Slug | Variant Dir                    | Common Categories                  |
+| --------------- | ------------ | -------- | ------- | ------------------------------ | ---------------------------------- |
+| CDEBYTE_E77-MBL |              |          |         | variants/stm32/CDEBYTE_E77-MBL | Display:1                          |
+| milesight_gs301 |              |          |         | variants/stm32/milesight_gs301 | Display:1, Radio:1, Input:1        |
+| rak3172         |              |          |         | variants/stm32/rak3172         | Display:1                          |
+| russell         |              |          |         | variants/stm32/russell         | Display:1, Radio:1, Input:1, GPS:4 |
+| wio-e5          |              |          |         | variants/stm32/wio-e5          | Display:1                          |
+
+## Representative Board Examples
+
+### diy: `9m2ibr_aprs_lora_tracker`
+
+- Variant directory: `variants/esp32/diy/9m2ibr_aprs_lora_tracker`
+- Input examples:
+  - `BUTTON_PIN` = `15`
+- Radio examples:
+  - `LORA_SCK` = `18`
+  - `LORA_MISO` = `19`
+  - `LORA_MOSI` = `23`
+  - `LORA_CS` = `5`
+  - `LORA_DIO0` = `26`
+  - `LORA_RESET` = `27`
+  - `LORA_DIO1` = `12`
+  - `LORA_DIO2` = `RADIOLIB_NC`
+- GPS examples:
+  - `GPS_RX_PIN` = `16`
+  - `GPS_TX_PIN` = `17`
+- Display examples:
+  - `HAS_SCREEN` = `1`
+- I2C/SPI examples:
+  - `I2C_SDA` = `21`
+  - `I2C_SCL` = `22`
+- Power examples:
+  - `BATTERY_PIN` = `35`
+  - `ADC_MULTIPLIER` = `2.01`
+  - `ADC_CHANNEL` = `ADC1_GPIO35_CHANNEL`
+  - `BATTERY_SENSE_RESOLUTION_BITS` = `ADC_RESOLUTION`
+
+### esp32: `betafpv_2400_tx_micro`
+
+- Variant directory: `variants/esp32/betafpv_2400_tx_micro`
+- Input examples:
+  - `BUTTON_PIN` = `25`
+- Radio examples:
+  - `LORA_SCK` = `18`
+  - `LORA_MISO` = `19`
+  - `LORA_MOSI` = `23`
+  - `LORA_CS` = `5`
+  - `RF95_FAN_EN` = `17`
+  - `USE_SX1280` = `1`
+  - `LORA_RESET` = `14`
+  - `SX128X_CS` = `5`
+- I2C/SPI examples:
+  - `I2C_SDA` = `22`
+  - `I2C_SCL` = `32`
+- Connectivity/Other examples:
+  - `HAS_NEOPIXEL` = `1`
+
+### esp32-c3: `ai-c3`
+
+- Variant directory: `variants/esp32c3/ai-c3`
+- Input examples:
+  - `BUTTON_PIN` = `9`
+- Radio examples:
+  - `USE_RF95` = `1`
+  - `LORA_SCK` = `4`
+  - `LORA_MISO` = `5`
+  - `LORA_MOSI` = `6`
+  - `LORA_CS` = `7`
+  - `LORA_DIO0` = `10`
+  - `LORA_DIO1` = `3`
+  - `LORA_RESET` = `2`
+- GPS examples:
+  - `HAS_GPS` = `0`
+- I2C/SPI examples:
+  - `I2C_SDA` = `SDA`
+  - `I2C_SCL` = `SCL`
+
+### esp32-c6: `m5stack-unitc6l`
+
+- Variant directory: `variants/esp32c6/m5stack_unitc6l`
+- `custom_meshtastic_hw_model`: `111`
+- `custom_meshtastic_hw_model_slug`: `M5STACK_C6L`
+- `custom_meshtastic_architecture`: `esp32-c6`
+- `custom_meshtastic_actively_supported`: `true`
+- `custom_meshtastic_support_level`: `1`
+- `custom_meshtastic_display_name`: `M5Stack Unit C6L`
+- `custom_meshtastic_images`: `m5_c6l.svg`
+- `custom_meshtastic_tags`: `M5Stack`
+- Radio examples:
+  - `USE_SX1262` = `1`
+  - `LORA_MISO` = `22`
+  - `LORA_SCK` = `20`
+  - `LORA_MOSI` = `21`
+  - `LORA_CS` = `23`
+  - `LORA_RESET` = `RADIOLIB_NC`
+  - `LORA_DIO1` = `7`
+  - `LORA_BUSY` = `19`
+- GPS examples:
+  - `HAS_GPS` = `1`
+  - `GPS_RX_PIN` = `4`
+  - `GPS_TX_PIN` = `5`
+- Display examples:
+  - `SCREEN_TRANSITION_FRAMERATE` = `10`
+- I2C/SPI examples:
+  - `I2C_SDA` = `10`
+  - `I2C_SCL` = `8`
+- Connectivity/Other examples:
+  - `HAS_NEOPIXEL` = `1`
+
+### esp32-s3: `CDEBYTE_EoRa-Hub`
+
+- Variant directory: `variants/esp32s3/CDEBYTE_EoRa-Hub`
+- Input examples:
+  - `BUTTON_PIN` = `0`
+- Radio examples:
+  - `USE_LR1121` = `1`
+  - `LORA_SCK` = `9`
+  - `LORA_MOSI` = `10`
+  - `LORA_MISO` = `11`
+  - `LORA_RESET` = `12`
+  - `LORA_CS` = `8`
+  - `LORA_DIO9` = `13`
+  - `LR1121_IRQ_PIN` = `14`
+- Display examples:
+  - `HAS_SCREEN` = `1`
+  - `USE_SSD1306` = `1`
+- I2C/SPI examples:
+  - `I2C_SCL` = `17`
+  - `I2C_SDA` = `18`
+  - `I2C_SCL1` = `21`
+  - `I2C_SDA1` = `10`
+- Power examples:
+  - `BATTERY_PIN` = `1`
+  - `ADC_CHANNEL` = `ADC1_GPIO1_CHANNEL`
+  - `ADC_MULTIPLIER` = `103.0`
+  - `ADC_ATTENUATION` = `ADC_ATTEN_DB_0`
+  - `ADC_CTRL` = `37`
+  - `ADC_CTRL_ENABLED` = `LOW`
+
+### esp32s2: `nugget-s2-lora`
+
+- Variant directory: `variants/esp32s2/nugget_s2_lora`
+- Input examples:
+  - `BUTTON_PIN` = `0`
+- Radio examples:
+  - `USE_RF95` = `1`
+  - `LORA_SCK` = `6`
+  - `LORA_MISO` = `8`
+  - `LORA_MOSI` = `10`
+  - `LORA_CS` = `13`
+  - `LORA_DIO0` = `16`
+  - `LORA_RESET` = `5`
+  - `LORA_DIO1` = `RADIOLIB_NC`
+- I2C/SPI examples:
+  - `I2C_SDA` = `34`
+  - `I2C_SCL` = `36`
+- Connectivity/Other examples:
+  - `HAS_NEOPIXEL` = `1`
+
+### native: `buildroot`
+
+- Variant directory: `variants/native/portduino-buildroot`
+- GPS examples:
+  - `HAS_GPS` = `1`
+- Display examples:
+  - `HAS_SCREEN` = `1`
+  - `USE_TFTDISPLAY` = `1`
+
+### nrf52840: `ME25LS01-4Y10TD`
+
+- Variant directory: `variants/nrf52840/ME25LS01-4Y10TD`
+- Input examples:
+  - `BUTTON_PIN` = `(0 + 27)`
+- Radio examples:
+  - `LORA_RESET` = `(32 + 11)`
+  - `LORA_DIO1` = `(32 + 12)`
+  - `LORA_DIO2` = `(32 + 10)`
+  - `LORA_SCK` = `PIN_SPI_SCK`
+  - `LORA_MISO` = `PIN_SPI_MISO`
+  - `LORA_MOSI` = `PIN_SPI_MOSI`
+  - `LORA_CS` = `PIN_SPI_NSS`
+  - `USE_LR1110` = `1`
+- GPS examples:
+  - `HAS_GPS` = `0`
+  - `PIN_GPS_EN` = `-1`
+  - `GPS_EN_ACTIVE` = `HIGH`
+  - `PIN_GPS_RESET` = `-1`
+  - `GPS_VRTC_EN` = `-1`
+  - `GPS_SLEEP_INT` = `-1`
+  - `GPS_RTC_INT` = `-1`
+  - `GPS_RESETB_OUT` = `-1`
+- I2C/SPI examples:
+  - `WIRE_INTERFACES_COUNT` = `1`
+  - `SPI_INTERFACES_COUNT` = `1`
+  - `PIN_SPI_MISO` = `(0 + 29)`
+  - `PIN_SPI_MOSI` = `(0 + 2)`
+  - `PIN_SPI_SCK` = `(32 + 15)`
+  - `PIN_SPI_NSS` = `(32 + 13)`
+- Power examples:
+  - `BATTERY_PIN` = `-1`
+  - `ADC_MULTIPLIER` = `(2.0F)`
+  - `ADC_RESOLUTION` = `14`
+  - `BATTERY_SENSE_RESOLUTION_BITS` = `12`
+
+### rp2040: `catsniffer`
+
+- Variant directory: `variants/rp2040/ec_catsniffer`
+- Radio examples:
+  - `USE_SX1262` = `1`
+  - `LORA_SCK` = `18`
+  - `LORA_MISO` = `16`
+  - `LORA_MOSI` = `19`
+  - `LORA_CS` = `17`
+  - `LORA_DIO0` = `5`
+  - `LORA_RESET` = `24`
+  - `LORA_DIO1` = `4`
+- GPS examples:
+  - `HAS_GPS` = `0`
+- Display examples:
+  - `HAS_SCREEN` = `0`
+
+### rp2350: `pico2`
+
+- Variant directory: `variants/rp2350/rpipico2`
+- Input examples:
+  - `BUTTON_PIN` = `17`
+- Radio examples:
+  - `USE_SX1262` = `1`
+  - `LORA_SCK` = `10`
+  - `LORA_MISO` = `12`
+  - `LORA_MOSI` = `11`
+  - `LORA_CS` = `3`
+  - `LORA_DIO0` = `RADIOLIB_NC`
+  - `LORA_RESET` = `15`
+  - `LORA_DIO1` = `20`
+- Power examples:
+  - `EXT_NOTIFY_OUT` = `22`
+  - `BATTERY_PIN` = `26`
+  - `ADC_MULTIPLIER` = `3.1`
+  - `BATTERY_SENSE_RESOLUTION_BITS` = `ADC_RESOLUTION`
+
+### stm32: `CDEBYTE_E77-MBL`
+
+- Variant directory: `variants/stm32/CDEBYTE_E77-MBL`
+- Display examples:
+  - `USE_STM32WLx` = `1`
+
+## Intake Guidance For New Hardware
+
+When using this context to add a new board, collect these inputs before generating files:
+
+- PlatformIO environment name
+- `custom_meshtastic_hw_model` and `custom_meshtastic_hw_model_slug`
+- Display name and architecture
+- Whether the board is actively supported and its support level
+- Partition scheme, DFU requirement, and image/tag metadata if applicable
+- Radio chip family and complete radio pin group
+- Input/button/rotary/keyboard pins
+- Display interface pins and driver-related macros
+- GPS, power-management, I2C, SPI, storage, and auxiliary peripheral definitions
+- Any board-specific initialization that requires `variant.cpp` or extra variant hooks
+
+## Inherited Defaults Note
+
+Some architecture families rely on BSP (Board Support Package) or base-environment defaults rather than declaring every pin or capability macro explicitly in `variant.h`. When adding a new board for one of these families, check the relevant BSP headers before assuming a missing define means a feature is absent.
+
+Directories scanned that had no `variant.h` (relying entirely on BSP/base-environment): diy: 4, esp32: 3, esp32s3: 1
+
+### nrf52840
+
+- VARIANT_MCK — nRF52 BSP clock constant (e.g., 64000000ul); always inherited from BSP unless overridden.
+- USE_LFXO — low-frequency crystal oscillator selection; declared locally only when the board uses LFXO rather than the RC oscillator.
+- PIN*SPI*_ / PIN*SPI1*_ — SPI bus pin numbers come from the BSP variant table; boards override only when the LoRa radio or display uses non-default SPI routing.
+- WIRE_INTERFACES_COUNT / SPI_INTERFACES_COUNT — bus count comes from BSP; explicitly set only when the board deviates.
+- LED_BLUE / PIN_LED1 / PINS_COUNT / NUM_DIGITAL_PINS — standard BSP pin-table entries inherited from the nRF52 Arduino core.
+
+### rp2040
+
+- PIN*SPI*\* — primary SPI pins come from the RP2040 Arduino BSP; most boards declare them explicitly, but the defaults align with the Pico pin assignments.
+- NUM_DIGITAL_PINS / NUM_ANALOG_INPUTS — Arduino BSP counts; rarely overridden locally.
+
+### stm32
+
+- Radio and pin assignments for STM32WL targets are largely internal to the WL SoC and declared via STM32 HAL/BSP headers; variant.h files are minimal.
+- USE_STM32WLx is typically the only explicit define; all other radio config comes from the BSP.
+
+### native
+
+- The native/Portduino target uses runtime configuration rather than compile-time pin defines; variant.h only sets display and GPS stubs.
+
+## Cautions
+
+- Some boards rely on architecture defaults rather than declaring every field locally.
+- Some board families expose multiple environments or display variants that share one hardware model.
+- Source materials such as schematics still need human verification before new pin mappings are trusted.
+- This document is a starting context artifact, not proof that a new board definition is safe to merge.

platformio.ini

@@ -57,6 +57,7 @@ build_flags = -Wno-missing-field-initializers
 	-DMESHTASTIC_EXCLUDE_POWERSTRESS=1 ; exclude power stress test module from main firmware
 	-DMESHTASTIC_EXCLUDE_GENERIC_THREAD_MODULE=1
 	-DMESHTASTIC_EXCLUDE_POWERMON=1
+	-DMESHTASTIC_EXCLUDE_STATUS=1
 	-D MAX_THREADS=40 ; As we've split modules, we have more threads to manage
 	#-DBUILD_EPOCH=$UNIX_TIME ; set in platformio-custom.py now
 	#-D OLED_PL=1
@@ -120,7 +121,7 @@ lib_deps =
 [radiolib_base]
 lib_deps =
 	# renovate: datasource=github-tags depName=RadioLib packageName=jgromes/RadioLib
-	https://github.com/jgromes/RadioLib/archive/afe72ae46a343e15e3cac7f26ac585c7f98bffe5.zip
+	https://github.com/jgromes/RadioLib/archive/refs/tags/7.6.0.zip
 
 [device-ui_base]
 lib_deps =
@@ -226,8 +227,6 @@ lib_deps =
 	https://github.com/Sensirion/arduino-i2c-sfa3x/archive/refs/tags/1.0.0.zip
 	# renovate: datasource=github-tags depName=Sensirion I2C SCD30 packageName=sensirion/arduino-i2c-scd30
 	https://github.com/Sensirion/arduino-i2c-scd30/archive/refs/tags/1.0.0.zip
-	# renovate: datasource=github-tags depName=arduino-sht packageName=sensirion/arduino-sht
-	https://github.com/Sensirion/arduino-sht/archive/refs/tags/v1.2.6.zip
 
 ; Environmental sensors with BSEC2 (Bosch proprietary IAQ)
 [environmental_extra]

specs/129-hardware-support-agent/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Hardware Support Agent
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-25
+**Feature**: [spec.md](/Users/benmeadors/Documents/GitHub/firmware/specs/129-hardware-support-agent/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Specification validated against the repository constitution on 2026-03-25.
+- Initial scope is intentionally bounded to reusable hardware context plus safe board-intake and scaffolding workflow preparation.

specs/129-hardware-support-agent/contracts/board-intake-contract.md

@@ -0,0 +1,58 @@
+# Contract: Board Intake Request And Assessment
+
+## Purpose
+
+This contract defines the minimum maintainer input and the expected workflow output for the hardware-support-agent feature.
+
+## Input Contract
+
+### Required Fields
+
+- `environment_name`: Proposed PlatformIO environment name for the new board.
+- `hardware_model`: Meshtastic hardware model identifier to assign.
+- `display_name`: Human-readable board name.
+- `architecture`: Target architecture family such as `esp32`, `esp32-s3`, `nrf52840`, `rp2040`, or `stm32`.
+
+### Recommended Fields
+
+- `hardware_model_slug`: Repository-style uppercase slug if already known.
+- `actively_supported`: Whether the board is intended to be actively supported.
+- `support_level`: Intended `custom_meshtastic_support_level` value.
+- `source_materials`: Links, file paths, or notes for schematics, pinouts, datasheets, or vendor pages.
+- `board_notes`: Freeform notes about revisions, peripherals, or known uncertainty.
+
+## Validation Rules
+
+- The workflow must reject or pause on missing required fields.
+- The workflow must detect conflicts with existing environment names or existing hardware identifiers where discoverable.
+- The workflow must not invent radio, power, display, GPS, input, or auxiliary pin mappings.
+- The workflow must identify when architecture defaults may be relevant and flag them for human review.
+
+## Output Contract
+
+### Required Assessment Sections
+
+- `expected_artifacts`: What board-support artifacts are likely required.
+- `required_metadata`: What `custom_meshtastic_*` metadata and related fields must be decided.
+- `matched_patterns`: Existing repository examples that are closest to the request.
+- `evidence_gaps`: Missing or conflicting facts that block safe scaffolding.
+- `risk_flags`: Conditions that require special maintainer attention.
+- `next_actions`: Concrete steps to move the request toward scaffold readiness.
+- `scaffold_ready`: Boolean decision indicating whether draft file generation is safe.
+
+## Artifact Expectations
+
+Depending on the board and architecture, the assessment should consider whether the request will need:
+
+- a new or reused variant directory under `variants/<architecture>/...`
+- `variant.h`
+- optional `variant.cpp`
+- one or more PlatformIO environments with `custom_meshtastic_*` metadata
+- board images, tags, partition-scheme metadata, or DFU metadata
+- any architecture-specific board files or notes for inherited defaults
+
+## Non-Goals For Phase 1
+
+- Direct parsing of PDF schematics.
+- Automatic merging of new board files into the repository.
+- Any change to firmware runtime behavior, protocol behavior, or shared board defaults.

specs/129-hardware-support-agent/data-model.md

@@ -0,0 +1,124 @@
+# Data Model: Hardware Support Agent
+
+## Hardware Support Context
+
+Purpose: Repository-backed summary of current target-definition patterns across supported board variants.
+
+Fields:
+
+- source_paths: list of repository glob roots used to build the context
+- generated_at: timestamp or generation marker
+- variant_count: integer count of scanned variant directories
+- environment_count: integer count of summarized PlatformIO environments
+- metadata*keys: list of observed `custom_meshtastic*\*` keys
+- category_counts: mapping of capability category to common macros and frequencies
+- architecture_inventory: list of architecture groups and their environments
+- representative_examples: list of example boards with extracted metadata and macro samples
+- cautions: list of caveats about inherited defaults, multi-environment boards, and verification limits
+
+Validation rules:
+
+- Must be derived from repository state rather than hand-maintained guesses.
+- Must clearly separate explicit declarations from inherited/default behavior where known.
+- Must remain read-only context and not imply that any new board is validated for merge.
+
+Relationships:
+
+- Used by Board Intake Request as the canonical repository pattern source.
+
+## Board Intake Request
+
+Purpose: Maintainer-supplied description of a proposed new board or board revision.
+
+Fields:
+
+- environment_name: proposed PlatformIO environment name
+- hardware_model: numeric or repository-convention hardware model identifier
+- hardware_model_slug: uppercase slug when known
+- display_name: human-readable board name
+- architecture: target family such as `esp32-s3` or `nrf52840`
+- source_materials: optional list of schematic, pinout, datasheet, or board-page references
+- support_level: optional intended support metadata
+- actively_supported: optional boolean intent
+- board_notes: optional maintainer notes about revisions, optional peripherals, or known gaps
+
+Validation rules:
+
+- `environment_name`, `hardware_model`, and `display_name` are required for phase 1 intake.
+- Architecture is required before any artifact expectation can be considered complete.
+- Source materials are optional for submission but required for moving unresolved hardware fields toward scaffold generation.
+- Conflicts with existing environment names or hardware identifiers must be surfaced.
+
+Relationships:
+
+- Produces one Intake Assessment.
+- May eventually lead to one or more Board Support Scaffolds.
+
+## Intake Assessment
+
+Purpose: Structured result of evaluating a Board Intake Request against repository patterns and evidence sufficiency.
+
+Fields:
+
+- expected_artifacts: list of files or sections likely needed, such as `variant.h`, optional `variant.cpp`, PlatformIO environment entries, board metadata, images, or tags
+- required*metadata: list of mandatory `custom_meshtastic*\*` values and board-definition fields
+- matched_patterns: list of related repository examples by architecture or board family
+- evidence_gaps: list of unresolved or conflicting hardware facts
+- risk_flags: list of issues such as ambiguous board revisions, unsupported peripherals, or inherited-default uncertainty
+- next_actions: ordered maintainer actions needed before safe scaffold generation
+- scaffold_ready: boolean indicating whether evidence is sufficient for a later scaffold phase
+
+Validation rules:
+
+- Must never infer unsupported pin mappings silently.
+- Must describe missing information in maintainer-actionable language.
+- Must remain architecture- and variant-scoped.
+
+Relationships:
+
+- Derived from Board Intake Request and Hardware Support Context.
+- Blocks or permits creation of Board Support Scaffold.
+
+## Evidence Gap
+
+Purpose: Specific missing, conflicting, or ambiguous fact that prevents safe draft generation.
+
+Fields:
+
+- category: metadata, radio, display, input, GPS, power, storage, connectivity, or revision-scope
+- description: maintainer-readable explanation of what is missing or conflicting
+- affected_artifact: target file or configuration area impacted
+- required_evidence: type of source needed to resolve the gap
+- blocking: boolean indicating whether the gap prevents scaffold generation
+
+Validation rules:
+
+- Must be traceable to a missing repository pattern or missing board truth.
+- Must not be collapsed into generic “needs more info” language when the specific blocker is knowable.
+
+Relationships:
+
+- Belongs to an Intake Assessment.
+
+## Board Support Scaffold
+
+Purpose: Draft board-support content for a new target once evidence is sufficient.
+
+Fields:
+
+- target_variant_dir: proposed variant directory path
+- variant_h_content: draft content or structured sections for `variant.h`
+- variant_cpp_content: optional draft for `variant.cpp`
+- platformio_env_content: draft PlatformIO environment metadata and extends chain
+- unresolved_annotations: inline markers for any remaining non-blocking maintainer review items
+- source_basis: references to intake data and repository patterns used to draft content
+
+Validation rules:
+
+- Must only include fields backed by evidence and repository conventions.
+- Must preserve variant-scoped truth and never modify unrelated board definitions.
+- May only be produced when Intake Assessment marks `scaffold_ready` true.
+
+Relationships:
+
+- Produced from Intake Assessment after gaps are resolved.

specs/129-hardware-support-agent/plan.md

@@ -0,0 +1,97 @@
+# Implementation Plan: Hardware Support Agent
+
+**Branch**: `[129-hardware-support-agent]` | **Date**: 2026-03-25 | **Spec**: /Users/benmeadors/Documents/GitHub/firmware/specs/129-hardware-support-agent/spec.md
+**Input**: Feature specification from `/Users/benmeadors/Documents/GitHub/firmware/specs/129-hardware-support-agent/spec.md`
+
+**Note**: This plan covers Phase 0 and Phase 1 outputs for a constitution-safe first increment. The first delivery scope centers on repository-backed hardware context plus intake validation and report generation; scaffold generation remains designed but gated behind sufficient evidence.
+
+## Summary
+
+Build a Copilot-oriented hardware support workflow for Meshtastic that starts from repository-derived board-definition context, accepts a constrained board intake request, and produces a structured readiness report before any new board files are drafted. The technical approach uses lightweight Python tooling and repository-local markdown/JSON contract artifacts to inventory existing `variant.h` and `platformio.ini` patterns, normalize maintainer inputs, identify evidence gaps, and prepare a later scaffolding phase without changing live firmware behavior.
+
+## Technical Context
+
+**Language/Version**: Python 3.x for workflow tooling, Markdown for generated artifacts, existing C/C++/PlatformIO repository conventions for downstream scaffold targets  
+**Primary Dependencies**: 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`  
+**Storage**: Repository-local files under `docs/`, `specs/129-hardware-support-agent/`, optional future intake examples under repo docs or fixtures  
+**Testing**: Targeted script execution, generated artifact review, `python3 bin/generate_hardware_support_context.py`, `trunk fmt` where applicable for markdown/templates, and targeted follow-up validation against representative variant files  
+**Target Platform**: Maintainer workflow inside the Meshtastic firmware repository on macOS/Linux development environments; outputs describe supported firmware architectures including ESP32, ESP32-S3, ESP32-C3, ESP32-C6, nRF52, RP2040/RP2350, STM32, and native patterns  
+**Project Type**: Repository tooling and Copilot workflow support  
+**Performance Goals**: Generate context and intake reports quickly enough for interactive maintainer use on a local checkout; avoid repository-wide processing that would materially slow a normal Copilot session  
+**Constraints**: No changes to mesh protocol behavior or shared device defaults; no guessing of pin mappings; architecture-specific truth must stay variant-scoped; keep implementation dependency-light and reviewable  
+**Scale/Scope**: Inventory currently spans 166 variant directories and 212 PlatformIO environments; phase 1 scope covers context generation, intake contract, evidence-gap reporting, and custom-agent planning, not autonomous end-to-end board enablement
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+- Safety-critical mesh impact: Pass. This feature is workflow/documentation/tooling only and does not modify routing, airtime, MQTT, channel, packet-path, or public default behavior.
+- Variant and platform scope: Pass. The workflow is explicitly scoped to board-definition artifacts and requires variant-specific evidence before any scaffold output is permitted.
+- Validation evidence: Pass with explicit plan. Validation for this phase is `python3 bin/generate_hardware_support_context.py`, manual spot-check against representative variants, and review of generated documentation/contracts. Later implementation phases should add targeted intake fixture checks.
+- Resource, power, memory, dependency impact: Pass. The feature adds lightweight local tooling and markdown contracts only, with no runtime firmware impact and no new external runtime dependency requirement.
+- Constitutional violations or gaps: No active violations for Phase 0/1 planning. The only open product choice is whether future phase 2 includes scaffold generation immediately or remains report-only until more intake validation exists.
+
+### Post-Design Re-Check
+
+- Safety-critical mesh impact remains unchanged after design: no firmware runtime path is altered.
+- Variant-scoped hardware truth is reinforced by the intake contract and evidence-gap model.
+- Validation evidence remains sufficient for design artifacts, with implementation tasks needing targeted script-level checks.
+- Resource and dependency impact remains minimal and repository-local.
+- No justification entries are required in Complexity Tracking for this plan.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/129-hardware-support-agent/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── board-intake-contract.md
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+.github/
+├── agents/
+└── prompts/
+
+bin/
+├── generate_hardware_support_context.py
+├── board_intake.py
+└── board_scaffold.py
+
+docs/
+└── hardware-support-context.md
+
+variants/
+├── esp32/
+├── esp32c3/
+├── esp32c6/
+├── esp32s2/
+├── esp32s3/
+├── native/
+├── nrf52840/
+├── rp2040/
+├── rp2350/
+└── stm32/
+```
+
+**Structure Decision**: Use the existing single-repository tooling structure. Planning artifacts live under `specs/129-hardware-support-agent/`, reusable generated context stays in `docs/`, implementation scripts live in `bin/`, and any future custom Copilot workflow files belong in `.github/prompts/` and `.github/agents/`. No new top-level application structure is needed.
+
+## Complexity Tracking
+
+No constitutional violations or complexity exceptions are currently required.
+
+## Review Notes
+
+- **SC-004** is a post-launch business metric and is not a blocking acceptance gate before merge. A timed baseline comparison should be collected after the first real board intake using the completed workflow.
+- Validation completed so far: `python3 bin/generate_hardware_support_context.py --validate`, `python3 bin/board_intake.py bin/fixtures/intake_minimal.json --validate`, `python3 bin/board_intake.py bin/fixtures/intake_full.json`, `python3 bin/board_intake.py bin/fixtures/intake_multi_env.json`, `python3 bin/board_scaffold.py bin/fixtures/intake_full.json`, and `python3 bin/board_scaffold.py bin/fixtures/intake_multi_env.json`.
+- `bin/board_scaffold.py` intentionally emits placeholder pin and metadata values plus `// TODO: verify — ...` annotations. Generated scaffold output is draft-only and not suitable for direct merge without maintainer review against schematics and existing board patterns.
+- Scaffold generation currently writes to `generated/hardware-support/` rather than directly into `variants/` to keep the workflow reviewable and constitution-safe.
+- Skipped validations: no targeted `pio run`, native test, or simulator run was executed because this feature adds repository tooling and generated draft artifacts only; no firmware runtime files under `src/` were changed.

specs/129-hardware-support-agent/quickstart.md

@@ -0,0 +1,111 @@
+# Quickstart: Hardware Support Agent
+
+## Goal
+
+Use the repository-backed hardware support workflow to understand current board-definition patterns and evaluate whether a new board request is ready for safe scaffolding.
+
+## Prerequisites
+
+- Work from the repository root.
+- Ensure Python 3 is available.
+- Have the new board’s minimum intake information ready:
+  - proposed PlatformIO environment name
+  - hardware model identifier
+  - display name
+  - target architecture
+  - any available schematic, pinout, or datasheet references
+
+## Step 1: Regenerate the repository context artifact
+
+Run:
+
+```bash
+python3 bin/generate_hardware_support_context.py
+```
+
+Review:
+
+- `docs/hardware-support-context.md`
+
+Confirm that the architectures, representative examples, and metadata keys still reflect the current repository state.
+
+## Step 2: Prepare the board intake request
+
+Capture the request using the contract in:
+
+- `specs/129-hardware-support-agent/contracts/board-intake-contract.md`
+
+At minimum, fill:
+
+- environment name
+- hardware model
+- display name
+- architecture
+
+Add source materials for radio, display, power, GPS, input, and auxiliary peripherals when available.
+
+## Step 3: Evaluate readiness
+
+Run:
+
+```bash
+python3 bin/board_intake.py path/to/intake.json
+```
+
+The intake report now includes:
+
+- request summary
+- expected artifacts
+- required metadata
+- matched repository patterns
+- blocking and non-blocking evidence gaps
+- risk flags
+- next actions
+- a `scaffold_ready` decision
+
+For gate-style validation, run:
+
+```bash
+python3 bin/board_intake.py path/to/intake.json --validate
+```
+
+This exits non-zero when blocking gaps remain.
+
+## Step 4: Generate scaffold output when ready
+
+If Step 3 reports `scaffold_ready: true`, run:
+
+```bash
+python3 bin/board_scaffold.py path/to/intake.json --output-dir generated/hardware-support
+```
+
+Expected outputs:
+
+- `generated/hardware-support/variants/<arch>/<variant-dir>/variant.h`
+- `generated/hardware-support/variants/<arch>/<variant-dir>/platformio.ini`
+- optional `variant.cpp` for ESP32-family targets
+
+If the intake is not scaffold-ready, the scaffold command prints the assessment and exits non-zero instead of generating files.
+
+## Step 5: Validate the workflow artifacts
+
+Run:
+
+```bash
+python3 bin/generate_hardware_support_context.py
+python3 bin/board_intake.py bin/fixtures/intake_full.json
+python3 bin/board_scaffold.py bin/fixtures/intake_full.json --output-dir generated/hardware-support
+```
+
+Then manually spot-check representative targets such as:
+
+- `variants/esp32/tbeam`
+- `variants/esp32s3/tlora-pager`
+- `variants/nrf52840/t-echo`
+- `variants/rp2040/rak11310`
+
+Ensure the generated context, intake assessment, and scaffold output remain consistent with repository truth.
+
+## Next Step
+
+Use [hardware-support.prompt.md](.github/prompts/hardware-support.prompt.md) and [hardware-support.agent.md](.github/agents/hardware-support.agent.md) to invoke the workflow directly from Copilot.

specs/129-hardware-support-agent/research.md

@@ -0,0 +1,46 @@
+# Research: Hardware Support Agent
+
+## Decision: Use repository-local Python tooling and markdown artifacts as the first implementation slice
+
+Rationale: The repository already uses lightweight scripts under `bin/` and maintains board truth primarily in `variants/**/platformio.ini` and `variants/**/variant.h`. A Python script plus markdown outputs fits existing repo patterns, keeps dependencies minimal, and provides immediate value without touching firmware runtime code.
+
+Alternatives considered:
+
+- Implement the first increment directly as a full custom Copilot agent that generates new board files. Rejected because the workflow still needs a safer evidence-validation layer before scaffolding hardware definitions.
+- Build a standalone service or extension-backed parser. Rejected because it would add unnecessary complexity, operational overhead, and dependencies for a repo-local maintainer workflow.
+
+## Decision: Treat intake validation and readiness reporting as the first generation boundary
+
+Rationale: The constitution requires verified, variant-scoped hardware truth and forbids guessing pins or capabilities. A report-first boundary lets maintainers capture missing evidence, expected artifacts, and metadata requirements before draft files are produced.
+
+Alternatives considered:
+
+- Generate `variant.h` and `platformio.ini` scaffolding immediately from minimum inputs. Rejected because environment name, `hw_model`, and display name are not enough to guarantee correct radio, power, display, and peripheral mappings.
+- Block all workflow progress until every future scaffold field is known. Rejected because maintainers still need a useful way to understand what is missing and what repository patterns apply.
+
+## Decision: Reuse the existing hardware inventory document as the canonical context input for planning
+
+Rationale: `docs/hardware-support-context.md` already inventories metadata keys, common macro categories, and representative board examples across the repository. That artifact can serve as the phase 1 foundation for both maintainers and future agent prompts.
+
+Alternatives considered:
+
+- Generate a new per-architecture context file for each family. Rejected for now because a single canonical context artifact is easier to review and sufficient for the first intake/report workflow.
+- Depend on maintainers manually browsing variant files during intake. Rejected because it defeats the feature goal of reducing rediscovery work.
+
+## Decision: Represent the maintainer workflow as a small set of explicit entities and a human-readable contract
+
+Rationale: The feature is primarily a repository workflow, not a networked API. A markdown contract describing required fields, validations, and outputs is sufficient for Spec Kit design and future agent/prompt implementation.
+
+Alternatives considered:
+
+- Define a JSON Schema or OpenAPI contract immediately. Rejected for phase 1 because no external service boundary exists yet and the workflow is still evolving.
+- Keep the contract implicit in prompt text only. Rejected because it would be harder to review, test, and keep aligned with the constitution.
+
+## Decision: Keep scaffold generation as a designed later phase gated by evidence sufficiency
+
+Rationale: The user wants the end state to include new board-support scaffolding, but constitutional safety requires a stronger intake and validation model first. Planning the later phase now preserves momentum without collapsing safe and unsafe scopes together.
+
+Alternatives considered:
+
+- Remove scaffolding from the feature entirely. Rejected because it is core to the requested long-term outcome.
+- Merge report generation and scaffolding into a single undifferentiated phase. Rejected because it weakens reviewability and blurs the safety boundary.

specs/129-hardware-support-agent/spec.md

@@ -0,0 +1,170 @@
+# Feature Specification: Hardware Support Agent
+
+**Feature Branch**: `[129-hardware-support-agent]`  
+**Created**: 2026-03-25  
+**Status**: Draft  
+**Input**: User description: "Implement the feature specification based on the updated constitution. I want to build an agent inside copilot to add new hardware support, including variant.h/cpp, any platformio ini environments will all of our custom metadata, and all of the pinmappings. I would start this process by just giving the board environment name, hw_model, display name, and perhaps some source materials illustrating the pin mappings in a PDF schematic for instance. I think we should start by creating a context for you in the form of a markdown file documenting all of the current input, button, radio, gpio, and other common pins we use in the meshtastic firmware at a device target definition level, so that we reuse instead of re-invent."
+
+## 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 - Build Reusable Hardware Context (Priority: P1)
+
+As a firmware maintainer adding support for a new device, I want a single repository-backed reference
+that summarizes the common board-definition inputs already used across Meshtastic targets so I can
+start from verified patterns instead of re-deriving pins, feature flags, and board metadata from scratch.
+
+**Why this priority**: Without an authoritative context source, any later agent workflow will repeat the
+same manual discovery work and risks copying incorrect or incomplete target definitions.
+
+**Independent Test**: Can be fully tested by generating the hardware context artifact from the current
+repository and confirming it captures existing target-definition fields, common pins, and board-scoped
+capability patterns for a representative set of boards.
+
+**Acceptance Scenarios**:
+
+1. **Given** an existing firmware checkout with multiple board variants, **When** a maintainer requests
+   the hardware support context, **Then** the system produces a markdown artifact that documents current
+   board-definition inputs, common pin categories, and recurring variant-level capabilities from the repo.
+2. **Given** a maintainer reviewing an existing board, **When** they inspect the context artifact,
+   **Then** they can identify the board environment, hardware model identifiers, display-related fields,
+   radio pin definitions, input pins, and other commonly reused target-definition elements without
+   manually scanning many variant files.
+
+---
+
+### User Story 2 - Define New Board Intake (Priority: P2)
+
+As a firmware maintainer, I want to provide a small set of board inputs such as environment name,
+hardware model, display name, and source materials so the Copilot workflow can determine what new
+hardware support artifacts need to be created or filled in.
+
+**Why this priority**: A constrained intake contract is required before the workflow can safely generate
+variant files and PlatformIO environments for new hardware support.
+
+**Independent Test**: Can be tested independently by supplying the declared board inputs for a hypothetical
+new target and confirming the workflow identifies required artifacts, missing evidence, and board-definition
+fields that must be resolved before code generation proceeds.
+
+**Acceptance Scenarios**:
+
+1. **Given** a maintainer provides an environment name, hardware model, display name, and source references,
+   **When** the intake workflow runs, **Then** it identifies the expected target-definition artifacts,
+   required metadata fields, and unresolved board details that still need confirmation.
+2. **Given** the supplied materials do not establish enough hardware truth for safe generation,
+   **When** the workflow evaluates the request, **Then** it explicitly flags the missing pin mappings,
+   peripheral capabilities, or board metadata instead of guessing silently.
+
+---
+
+### User Story 3 - Generate Board Support Scaffolding (Priority: P3)
+
+As a firmware maintainer, I want the Copilot workflow to use the validated intake and reusable context to
+draft board-support artifacts such as `variant.h`, optional `variant.cpp`, and PlatformIO environment content
+with repository-specific metadata so I can add new hardware support consistently and with less manual setup.
+
+**Why this priority**: This delivers the actual acceleration benefit, but it depends on verified context and
+safe intake rules to avoid generating incorrect hardware support.
+
+**Independent Test**: Can be tested independently by running the workflow for a new board request and
+confirming it produces scaffold content or structured instructions that align with repository patterns and
+does not invent unsupported hardware details.
+
+**Acceptance Scenarios**:
+
+1. **Given** validated board inputs and sufficient source evidence, **When** the maintainer requests new
+   hardware support scaffolding, **Then** the workflow drafts the required board-support files and metadata
+   using existing repository conventions.
+2. **Given** the request would affect hardware flags, pin mappings, or build metadata beyond the available
+   evidence, **When** scaffolding is attempted, **Then** the workflow limits output to supported fields and
+   clearly marks unresolved items for human confirmation.
+
+---
+
+### Edge Cases
+
+- The requested board environment name conflicts with an existing PlatformIO environment or target directory.
+- The same hardware model appears under multiple existing naming conventions and the correct repository form is ambiguous.
+- A schematic or PDF source omits some pins or names them differently than the repository’s existing macros.
+- A target uses architecture defaults today, so the context artifact must distinguish explicitly declared pins from inherited defaults.
+- A board has multiple display or radio options, optional peripherals, or revision-specific pinouts that cannot be collapsed into one truth.
+- The request includes peripherals that exist in source material but are not currently supported by repository patterns.
+- A generated board definition would require changing shared defaults or introducing unverified power, timing, or RF assumptions.
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: The system MUST produce a repository-local hardware context artifact that documents the current
+  target-definition patterns used for board support in this firmware repository.
+- **FR-002**: The hardware context artifact MUST describe, at minimum, the board environment name,
+  hardware model identifier, display-related identifiers, radio pin group, input/button-related pins,
+  and other commonly reused pin or capability categories present at the device-target-definition level.
+- **FR-003**: The hardware context artifact MUST distinguish board-specific declarations from architecture-level
+  defaults or inherited behavior when that distinction affects new board support work.
+- **FR-004**: Users MUST be able to initiate the workflow by providing a minimal set of board inputs that includes
+  board environment name, hardware model, display name, and target architecture, with optional supporting source materials.
+  Architecture is required because expected artifacts and matched patterns cannot be determined without it.
+- **FR-005**: The intake workflow MUST identify which board-support artifacts are expected for the request,
+  including variant files and PlatformIO environment content where applicable.
+- **FR-006**: The intake workflow MUST surface missing or conflicting hardware evidence instead of inventing
+  unresolved pins, capabilities, metadata, or power assumptions.
+- **FR-007**: The workflow MUST preserve variant-scoped hardware truth by keeping generated or suggested values
+  scoped to the intended target architecture, board, and board revision when known.
+- **FR-008**: The workflow MUST support repository-specific metadata required for new PlatformIO environments,
+  including custom support metadata already used in this codebase.
+- **FR-009**: The workflow MUST be able to draft scaffold content for `variant.h`, optional `variant.cpp`, and
+  related target files only when the provided evidence is sufficient to do so safely.
+- **FR-010**: The workflow MUST record unresolved questions in a form the maintainer can act on before using any
+  scaffolded board support in the repository.
+- **FR-011**: The workflow MUST be applicable to current Meshtastic hardware target definitions across supported
+  architectures, while allowing architecture-specific details to remain architecture-scoped.
+- **FR-012**: The workflow MUST not change public protocol behavior, shared radio safety defaults, or unrelated
+  board definitions as part of preparing new hardware support context.
+
+Where relevant, requirements MUST also state:
+
+- affected architectures, boards, or modules: ESP32, ESP32-S3, ESP32-C3, nRF52, RP2040/RP2350, STM32WL, and Portduino-style target-definition patterns where present in repo conventions
+- whether behavior changes public defaults, protocol compatibility, or generated artifacts: this feature must not alter public mesh defaults or protocol compatibility; it may create or update documentation artifacts for board-support workflow context
+- any required validation evidence for high-risk mesh, hardware, or power behavior: targeted verification of generated context against representative variant files and naming patterns is required before relying on it for scaffolding
+
+### Key Entities _(include if feature involves data)_
+
+- **Hardware Support Context**: A repository-backed reference artifact that summarizes the current board-support
+  fields, common pin categories, variant capability macros, and target-definition conventions used across the firmware.
+- **Board Intake Request**: The maintainer-provided input set for a proposed new board, including environment name,
+  hardware model, display name, target architecture, and optional source materials such as schematics.
+- **Target Definition Pattern**: A reusable repository convention describing how a board is represented through
+  `variant.h`, optional companion files, PlatformIO environments, and board-specific metadata.
+- **Evidence Gap**: A missing, ambiguous, or conflicting hardware fact that blocks safe generation of new board support.
+- **Board Support Scaffold**: The draft output for new hardware support artifacts, limited to fields supported by
+  verified evidence and current repository conventions.
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: Maintainers can locate the common target-definition inputs and pin categories for an existing board in one artifact within 5 minutes, without manually reading multiple variant directories.
+- **SC-002**: For a representative set of existing boards, the context artifact correctly captures the board environment name, key capability categories, and primary pin groups with no unresolved mismatches after maintainer review.
+- **SC-003**: A maintainer can submit a new board intake request using the declared minimum inputs and receive a complete list of required board-support artifacts and unresolved evidence gaps in a single workflow pass.
+- **SC-004**: _(Post-launch metric — not a pre-merge acceptance gate)_ For new board requests with sufficient source evidence, the workflow reduces manual setup time for initial board-support scaffolding by at least 50% compared with manually assembling variant and PlatformIO definitions from scratch. A baseline timed comparison should be conducted after the first production intake.
+
+## Assumptions
+
+- The initial increment focuses on repository context and intake/scaffolding workflow support, not full autonomous end-to-end board enablement.
+- Maintainers using this workflow already have access to the repository, Copilot, and any board source materials they want to reference.
+- The first implementation may rely on repository-readable sources and manually supplied board details rather than automated PDF parsing.
+- Existing Meshtastic variant files and PlatformIO environments provide enough representative patterns to build a useful reusable context artifact.
+- The workflow will be allowed to stop and request clarification when hardware truth is incomplete instead of forcing a guessed output.

specs/129-hardware-support-agent/tasks.md

@@ -0,0 +1,170 @@
+# Tasks: Hardware Support Agent
+
+**Branch**: `129-hardware-support-agent`
+**Input**: Design documents from `specs/129-hardware-support-agent/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/board-intake-contract.md ✅
+
+**Note on existing work**: The Phase 3 (US1) inventory script and generated context artifact already exist.
+Tasks T001–T004 treat them as in-scope for validation and hardening rather than creation from scratch.
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: Confirm repository structure and tooling baseline for this feature.
+
+- [x] T001 Confirm `bin/generate_hardware_support_context.py` executes without errors from the repo root via `python3 bin/generate_hardware_support_context.py`
+- [x] T002 [P] Confirm `docs/hardware-support-context.md` exists and is committed or tracked in the working tree
+- [x] T003 [P] Clean up the duplicated `"Where relevant, requirements MUST also state:"` block in `specs/129-hardware-support-agent/spec.md`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Shared utilities and data structures that US2 and US3 both depend on.
+
+**⚠️ CRITICAL**: US2 and US3 cannot begin until this phase is complete.
+
+- [x] T004 Add a `BoardIntakeRequest` dataclass (or typed dict) capturing the fields from `specs/129-hardware-support-agent/data-model.md` in `bin/board_intake.py`
+- [x] T005 Add a `EvidenceGap` dataclass in `bin/board_intake.py` matching the data model
+- [x] T006 Add an `IntakeAssessment` dataclass in `bin/board_intake.py` matching the data model
+- [x] T007 Implement a `load_hardware_context(path)` helper in `bin/board_intake.py` that reads `docs/hardware-support-context.md` and returns architecture family names and metadata key list for use by the assessment logic
+
+**Checkpoint**: Shared data structures and context loader in place — US2 and US3 implementation can begin.
+
+---
+
+## Phase 3: User Story 1 — Build Reusable Hardware Context (Priority: P1) 🎯 MVP
+
+**Goal**: A single repository-backed markdown document accurately inventories current board-support patterns across all supported architectures so maintainers can start a new board definition from verified patterns.
+
+**Independent Test**: Run `python3 bin/generate_hardware_support_context.py` and manually spot-check output against four representative variants from different architectures.
+
+### Validation for User Story 1
+
+- [x] T008 [P] [US1] Spot-check generated `docs/hardware-support-context.md` against `variants/esp32/tbeam` — confirm radio pins, metadata keys, and category counts match the variant.h and platformio.ini declarations
+- [x] T009 [P] [US1] Spot-check against `variants/esp32s3/tlora-pager` — confirm all 17 `custom_meshtastic_*` metadata keys and high Connectivity/Other category macro count are reflected
+- [x] T010 [P] [US1] Spot-check against `variants/nrf52840/t-echo` — confirm nRF52-specific macros (`USE_LFXO`, `VARIANT_MCK`, nRF52-style SPI pins) appear correctly
+- [x] T011 [P] [US1] Spot-check against `variants/rp2040/rak11310` — confirm RP2040 architecture entry is present and radio pins match
+- [x] T012 [US1] Run `trunk fmt bin/generate_hardware_support_context.py` and fix any formatting issues
+
+### Implementation for User Story 1
+
+- [x] T013 [P] [US1] Add `--validate` CLI flag to `bin/generate_hardware_support_context.py` that prints a summary of how many variants were scanned, how many had metadata keys, and how many had no `variant.h` (for inherited-defaults audit)
+- [x] T014 [US1] Add a `## Inherited Defaults Note` section to the generated `docs/hardware-support-context.md` that lists architecture families known to rely on BSP/base-environment defaults rather than locally declared macros (informed by validate output)
+
+**Checkpoint**: `docs/hardware-support-context.md` is validated, formatted, and includes inherited-defaults guidance. US1 fully testable and deliverable independently.
+
+---
+
+## Phase 4: User Story 2 — Define New Board Intake (Priority: P2)
+
+**Goal**: A maintainer can provide an environment name, hardware model, display name, and architecture and receive back a structured assessment listing expected artifacts, required metadata, closest matching patterns, and any evidence gaps.
+
+**Independent Test**: Run the intake workflow against a sample hypothetical board (e.g., a new ESP32-S3 board with only minimum inputs) and confirm it returns a complete assessment with at least one evidence gap identified.
+
+### Validation for User Story 2
+
+- [x] T015 [P] [US2] Create `bin/fixtures/intake_minimal.json` with just the required fields for a hypothetical new ESP32-S3 board and confirm `bin/board_intake.py` parses it without error
+- [x] T016 [P] [US2] Create `bin/fixtures/intake_full.json` with all recommended fields and source materials and confirm the workflow marks `scaffold_ready: true`
+- [x] T016b [P] [US2] Create `bin/fixtures/intake_multi_env.json` representing a board with two display variants sharing one hardware model (e.g., a TFT and an e-ink variant) and confirm `assess_intake` flags `revision-scope` ambiguity as a blocking Evidence Gap rather than collapsing the options silently
+- [x] T017 [US2] Confirm `bin/board_intake.py --validate bin/fixtures/intake_minimal.json` correctly flags missing radio, display, and power evidence as blocking gaps
+
+### Implementation for User Story 2
+
+- [x] T018 [P] [US2] Implement `validate_intake(request: BoardIntakeRequest) -> list[str]` in `bin/board_intake.py` that checks required fields and detects environment-name conflicts against the existing architecture inventory in `docs/hardware-support-context.md`
+- [x] T019 [P] [US2] Implement `find_matched_patterns(request: BoardIntakeRequest, context) -> list[dict]` that returns the three closest existing board examples by architecture from the context document
+- [x] T020 [US2] Implement `build_evidence_gaps(request: BoardIntakeRequest) -> list[EvidenceGap]` that identifies missing pin group evidence (radio, display, GPS, power, input) based on declared source materials
+- [x] T021 [US2] Implement `assess_intake(request: BoardIntakeRequest, context) -> IntakeAssessment` combining T018–T020 to produce a full structured assessment
+- [x] T022 [US2] Implement `render_assessment_markdown(assessment: IntakeAssessment) -> str` that formats the assessment as a maintainer-readable markdown report
+- [x] T023 [US2] Add a CLI entry point `bin/board_intake.py <intake.json>` that prints the assessment markdown to stdout or an output file
+- [x] T024 [US2] Run `trunk fmt bin/board_intake.py` and fix any formatting issues
+
+**Checkpoint**: `bin/board_intake.py` fully processes a new board request and prints an assessment. US2 independently testable.
+
+---
+
+## Phase 5: User Story 3 — Generate Board Support Scaffolding (Priority: P3)
+
+**Goal**: When intake assessment marks `scaffold_ready: true`, the workflow drafts `variant.h`, optional `variant.cpp`, and PlatformIO environment content using repository conventions, with inline annotations for unresolved items.
+
+**Independent Test**: Run the scaffold generator for a fully-specified test case and confirm the output files follow existing repository patterns and include `// TODO:` markers for any fields not backed by supplied evidence.
+
+### Validation for User Story 3
+
+- [x] T025 [P] [US3] Run scaffold generator for `bin/fixtures/intake_full.json` and confirm `variant.h` output contains required radio pin group, capability macros, and metadata section
+- [x] T026 [P] [US3] Confirm scaffold generator emits `// TODO: verify —` annotations for any recommended fields absent from the intake fixture
+- [x] T027 [US3] Confirm generated PlatformIO env block includes all `custom_meshtastic_*` metadata keys from the contract and uses `extends` to reference the correct base environment for the declared architecture
+
+### Implementation for User Story 3
+
+- [x] T028 [P] [US3] Create `bin/board_scaffold.py` with a `generate_variant_h(assessment: IntakeAssessment, context) -> str` function that drafts a `variant.h` file using architecture-appropriate macro order from the context document
+- [x] T029 [P] [US3] Implement `generate_platformio_env(assessment: IntakeAssessment) -> str` in `bin/board_scaffold.py` that emits the PlatformIO environment block with `custom_meshtastic_*` fields
+- [x] T030 [US3] Implement `annotate_unresolved(content: str, gaps: list[EvidenceGap]) -> str` that inserts `// TODO: verify — {gap.description}` comments next to lines that correspond to unresolved evidence gaps
+- [x] T031 [US3] Implement `scaffold_board(assessment: IntakeAssessment, context, output_dir: Path)` which orchestrates T028–T030 and writes files to the proposed variant directory path
+- [x] T032 [US3] Add CLI entry point `bin/board_scaffold.py <intake.json> [--output-dir <path>]` that reads an intake file, runs the full intake + scaffold pipeline, and writes output
+- [x] T033 [US3] Guard scaffold entry: if `assess_intake` returns `scaffold_ready: false`, print the assessment report and exit with a non-zero code rather than generating files
+- [x] T034 [US3] Run `trunk fmt bin/board_scaffold.py` and fix any formatting issues
+
+**Checkpoint**: All three user stories independently functional. Hardware context, intake assessment, and scaffold generation each work as standalone deliverables.
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Custom Copilot agent integration, documentation, and final review.
+
+- [x] T035 [P] Create `.github/prompts/hardware-support.prompt.md` that routes the hardware support workflow to the custom agent
+- [x] T036 [P] Create `.github/agents/hardware-support.agent.md` with step-by-step instructions for the Copilot hardware-support workflow: context regeneration → intake → assessment → optional scaffold
+- [x] T037 [US1] Update `specs/129-hardware-support-agent/quickstart.md` Step 3 and Step 4 to reference the completed `bin/board_intake.py` CLI and describe the expected output shape
+- [x] T038 [P] Confirm that no firmware runtime files under `src/`, `variants/`, or `protobufs/` were modified as part of this feature (constitution compliance check)
+- [x] T039 Run `python3 bin/generate_hardware_support_context.py` one final time to confirm the regenerated artifact is up to date and passes spot-checks from T008–T011
+- [x] T040 Summarize any skipped validations, open `// TODO:` items in scaffold output, and any known limitations in `specs/129-hardware-support-agent/plan.md` under a `## Review Notes` section
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: No dependencies — start immediately
+- **Phase 2 (Foundational)**: Depends on Phase 1 — blocks US2 and US3
+- **Phase 3 (US1)**: Can start after Phase 1; does not depend on Phase 2
+- **Phase 4 (US2)**: Depends on Phase 2 (shared data structures)
+- **Phase 5 (US3)**: Depends on Phase 2 and Phase 4 (uses IntakeAssessment output)
+- **Phase 6 (Polish)**: Depends on all story phases
+
+### User Story Dependencies
+
+- **US1 (P1)**: Depends on Phase 1 only — fully independent MVP
+- **US2 (P2)**: Depends on Phase 2; integrates with US1 context document but not the script directly
+- **US3 (P3)**: Depends on Phase 2 and US2 `assess_intake` result
+
+### Parallel Opportunities
+
+**Within Phase 2**:
+
+- T004, T005, T006 can be written in parallel (same file, separate dataclasses — serialize to avoid conflicts)
+
+**Within Phase 3 (US1)**:
+
+- T008, T009, T010, T011 (spot-checks) are fully independent and can run in parallel
+- T013 [P] is independent of validation tasks
+
+**Within Phase 4 (US2)**:
+
+- T015, T016 fixture creation can run in parallel
+- T018 and T019 are independent of each other and can be implemented in parallel
+
+**Within Phase 5 (US3)**:
+
+- T028 and T029 are independent scaffold generators — can be written in parallel
+- T025 and T026 validation tasks are independent
+
+**Within Phase 6**:
+
+- T035, T036, T038 are independent files — can all be done in parallel
+
+### MVP Scope
+
+To deliver US1 as a standalone MVP: complete Phases 1 and 3 (T001–T003, T008–T014). This verifies the hardware context artifact is accurate and useful without requiring any intake or scaffold tooling.

src/DisplayFormatters.cpp

@@ -4,8 +4,7 @@ const char *DisplayFormatters::getModemPresetDisplayName(meshtastic_Config_LoRaC
                                                          bool usePreset)
 {
 
-    // If use_preset is false, always return "Custom" — callers such as RadioInterface and Channels
-    // rely on this being a stable literal for channel-name hashing and default-channel detection.
+    // If use_preset is false, always return "Custom"
     if (!usePreset) {
         return "Custom";
     }

src/FSCommon.cpp

@@ -79,46 +79,28 @@ bool copyFile(const char *from, const char *to)
 bool renameFile(const char *pathFrom, const char *pathTo)
 {
 #ifdef FSCom
+
+#ifdef ARCH_ESP32
+    // take SPI Lock
     spiLock->lock();
+    // rename was fixed for ESP32 IDF LittleFS in April
     bool result = FSCom.rename(pathFrom, pathTo);
     spiLock->unlock();
     return result;
 #else
-    return false;
+    // copyFile does its own locking.
+    if (copyFile(pathFrom, pathTo) && FSCom.remove(pathFrom)) {
+        return true;
+    } else {
+        return false;
+    }
+#endif
+
 #endif
 }
 
 #include <vector>
 
-/**
- * @brief Platform-agnostic filesystem format / wipe.
- *
- * On embedded targets (ESP32, NRF52, STM32WL, RP2040) this calls the
- * native FSCom.format() which erases and reinitialises the LittleFS
- * partition.
- *
- * On Portduino the fs::FS backend has no format() method. We instead
- * delete /prefs (the only meshtastic data directory written at runtime)
- * and return. rmDir("/prefs") is already called unconditionally by
- * factoryReset() so this is a proven primitive on Portduino.
- * FSBegin() is a no-op (#define FSBegin() true) on Portduino.
- *
- * @return true on success, false on failure or if no filesystem is configured.
- */
-bool fsFormat()
-{
-#ifdef FSCom
-#if defined(ARCH_PORTDUINO)
-    rmDir("/prefs");
-    return FSBegin();
-#else
-    return FSCom.format();
-#endif
-#else
-    return false;
-#endif
-}
-
 /**
  * @brief Get the list of files in a directory.
  *
@@ -141,21 +123,23 @@ std::vector<meshtastic_FileInfo> getFiles(const char *dirname, uint8_t levels)
 
     File file = root.openNextFile();
     while (file) {
-#ifdef ARCH_ESP32
-        const char *filepath = file.path();
-#else
-        const char *filepath = file.name();
-#endif
         if (file.isDirectory() && !String(file.name()).endsWith(".")) {
             if (levels) {
-                std::vector<meshtastic_FileInfo> subDirFilenames = getFiles(filepath, levels - 1);
+#ifdef ARCH_ESP32
+                std::vector<meshtastic_FileInfo> subDirFilenames = getFiles(file.path(), levels - 1);
+#else
+                std::vector<meshtastic_FileInfo> subDirFilenames = getFiles(file.name(), levels - 1);
+#endif
                 filenames.insert(filenames.end(), subDirFilenames.begin(), subDirFilenames.end());
                 file.close();
             }
         } else {
             meshtastic_FileInfo fileInfo = {"", static_cast<uint32_t>(file.size())};
-            strncpy(fileInfo.file_name, filepath, sizeof(fileInfo.file_name) - 1);
-            fileInfo.file_name[sizeof(fileInfo.file_name) - 1] = '\0';
+#ifdef ARCH_ESP32
+            strcpy(fileInfo.file_name, file.path());
+#else
+            strcpy(fileInfo.file_name, file.name());
+#endif
             if (!String(fileInfo.file_name).endsWith(".")) {
                 filenames.push_back(fileInfo);
             }
@@ -179,59 +163,98 @@ std::vector<meshtastic_FileInfo> getFiles(const char *dirname, uint8_t levels)
 void listDir(const char *dirname, uint8_t levels, bool del)
 {
 #ifdef FSCom
+#if (defined(ARCH_ESP32) || defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
     char buffer[255];
+#endif
     File root = FSCom.open(dirname, FILE_O_READ);
-    if (!root || !root.isDirectory())
+    if (!root) {
         return;
+    }
+    if (!root.isDirectory()) {
+        return;
+    }
 
     File file = root.openNextFile();
-    while (file && file.name()[0]) { // file.name()[0] check: workaround for Adafruit LittleFS nRF52 bug #4395
-#ifdef ARCH_ESP32
-        const char *filepath = file.path();
-#else
-        const char *filepath = file.name();
-#endif
+    while (
+        file &&
+        file.name()[0]) { // This file.name() check is a workaround for a bug in the Adafruit LittleFS nrf52 glue (see issue 4395)
         if (file.isDirectory() && !String(file.name()).endsWith(".")) {
             if (levels) {
-                listDir(filepath, levels - 1, del);
+#ifdef ARCH_ESP32
+                listDir(file.path(), levels - 1, del);
                 if (del) {
-                    LOG_DEBUG("Remove %s", filepath);
-                    strncpy(buffer, filepath, sizeof(buffer) - 1);
-                    buffer[sizeof(buffer) - 1] = '\0';
+                    LOG_DEBUG("Remove %s", file.path());
+                    strncpy(buffer, file.path(), sizeof(buffer));
                     file.close();
                     FSCom.rmdir(buffer);
                 } else {
                     file.close();
                 }
+#elif (defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
+                listDir(file.name(), levels - 1, del);
+                if (del) {
+                    LOG_DEBUG("Remove %s", file.name());
+                    strncpy(buffer, file.name(), sizeof(buffer));
+                    file.close();
+                    FSCom.rmdir(buffer);
+                } else {
+                    file.close();
+                }
+#else
+                LOG_DEBUG(" %s (directory)", file.name());
+                listDir(file.name(), levels - 1, del);
+                file.close();
+#endif
             }
         } else {
+#ifdef ARCH_ESP32
             if (del) {
-                LOG_DEBUG("Delete %s", filepath);
-                strncpy(buffer, filepath, sizeof(buffer) - 1);
-                buffer[sizeof(buffer) - 1] = '\0';
+                LOG_DEBUG("Delete %s", file.path());
+                strncpy(buffer, file.path(), sizeof(buffer));
                 file.close();
                 FSCom.remove(buffer);
             } else {
-                LOG_DEBUG(" %s (%i Bytes)", filepath, file.size());
+                LOG_DEBUG(" %s (%i Bytes)", file.path(), file.size());
                 file.close();
             }
+#elif (defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
+            if (del) {
+                LOG_DEBUG("Delete %s", file.name());
+                strncpy(buffer, file.name(), sizeof(buffer));
+                file.close();
+                FSCom.remove(buffer);
+            } else {
+                LOG_DEBUG(" %s (%i Bytes)", file.name(), file.size());
+                file.close();
+            }
+#else
+            LOG_DEBUG("   %s (%i Bytes)", file.name(), file.size());
+            file.close();
+#endif
         }
         file = root.openNextFile();
     }
 #ifdef ARCH_ESP32
-    const char *rootpath = root.path();
-#else
-    const char *rootpath = root.name();
-#endif
     if (del) {
-        LOG_DEBUG("Remove %s", rootpath);
-        strncpy(buffer, rootpath, sizeof(buffer) - 1);
-        buffer[sizeof(buffer) - 1] = '\0';
+        LOG_DEBUG("Remove %s", root.path());
+        strncpy(buffer, root.path(), sizeof(buffer));
         root.close();
         FSCom.rmdir(buffer);
     } else {
         root.close();
     }
+#elif (defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
+    if (del) {
+        LOG_DEBUG("Remove %s", root.name());
+        strncpy(buffer, root.name(), sizeof(buffer));
+        root.close();
+        FSCom.rmdir(buffer);
+    } else {
+        root.close();
+    }
+#else
+    root.close();
+#endif
 #endif
 }
 
@@ -245,7 +268,14 @@ void listDir(const char *dirname, uint8_t levels, bool del)
 void rmDir(const char *dirname)
 {
 #ifdef FSCom
+
+#if (defined(ARCH_ESP32) || defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
     listDir(dirname, 10, true);
+#elif defined(ARCH_NRF52)
+    // nRF52 implementation of LittleFS has a recursive delete function
+    FSCom.rmdir_r(dirname);
+#endif
+
 #endif
 }
 

src/FSCommon.h

@@ -52,7 +52,6 @@ void fsInit();
 void fsListFiles();
 bool copyFile(const char *from, const char *to);
 bool renameFile(const char *pathFrom, const char *pathTo);
-bool fsFormat();
 std::vector<meshtastic_FileInfo> getFiles(const char *dirname, uint8_t levels);
 void listDir(const char *dirname, uint8_t levels, bool del = false);
 void rmDir(const char *dirname);

src/Power.cpp

@@ -40,22 +40,6 @@
 #include "concurrency/LockGuard.h"
 #endif
 
-#if defined(ARCH_STM32WL) && defined(BATTERY_PIN)
-#include "stm32yyxx_ll_adc.h"
-
-/* Analog read resolution */
-#if defined(LL_ADC_RESOLUTION_12B)
-#define LL_ADC_RESOLUTION LL_ADC_RESOLUTION_12B
-#define BATTERY_SENSE_RESOLUTION_BITS 12
-#elif defined(LL_ADC_DS_DATA_WIDTH_12_BIT)
-#define LL_ADC_RESOLUTION LL_ADC_DS_DATA_WIDTH_12_BIT
-#define BATTERY_SENSE_RESOLUTION_BITS 12
-#else
-#error "ADC resolution could not be defined!"
-#endif
-#define ADC_RANGE (1 << BATTERY_SENSE_RESOLUTION_BITS)
-#endif
-
 #if defined(DEBUG_HEAP_MQTT) && !MESHTASTIC_EXCLUDE_MQTT
 #include "mqtt/MQTT.h"
 #include "target_specific.h"
@@ -94,31 +78,16 @@ static const adc_atten_t atten = ADC_ATTENUATION;
 #endif
 #endif // BATTERY_PIN && ARCH_ESP32
 
-#ifdef EXT_PWR_DETECT
-#ifndef EXT_PWR_DETECT_MODE
-#define EXT_PWR_DETECT_MODE INPUT
-// If using internal pull resistors, we can infer EXT_PWR_DETECT_VALUE
-#elif EXT_PWR_DETECT_MODE == INPUT_PULLUP
-#define EXT_PWR_DETECT_VALUE LOW
-#elif EXT_PWR_DETECT_MODE == INPUT_PULLDOWN
-#define EXT_PWR_DETECT_VALUE HIGH
-#endif
-#ifndef EXT_PWR_DETECT_VALUE
-#define EXT_PWR_DETECT_VALUE HIGH
-#endif
-#endif
-
 #ifdef EXT_CHRG_DETECT
 #ifndef EXT_CHRG_DETECT_MODE
-#define EXT_CHRG_DETECT_MODE INPUT
-// If using internal pull resistors, we can infer EXT_CHRG_DETECT_VALUE
-#elif EXT_CHRG_DETECT_MODE == INPUT_PULLUP
-#define EXT_CHRG_DETECT_VALUE LOW
-#elif EXT_CHRG_DETECT_MODE == INPUT_PULLDOWN
-#define EXT_CHRG_DETECT_VALUE HIGH
+static const uint8_t ext_chrg_detect_mode = INPUT;
+#else
+static const uint8_t ext_chrg_detect_mode = EXT_CHRG_DETECT_MODE;
 #endif
 #ifndef EXT_CHRG_DETECT_VALUE
-#define EXT_CHRG_DETECT_VALUE HIGH
+static const uint8_t ext_chrg_detect_value = HIGH;
+#else
+static const uint8_t ext_chrg_detect_value = EXT_CHRG_DETECT_VALUE;
 #endif
 #endif
 
@@ -359,17 +328,11 @@ class AnalogBatteryLevel : public HasBatteryLevel
             float scaled = 0;
 
             battery_adcEnable();
-#ifdef ARCH_STM32WL
-            // STM32 ADC with VREFINT runtime calibration
-            Vref = __LL_ADC_CALC_VREFANALOG_VOLTAGE(analogRead(AVREF), LL_ADC_RESOLUTION);
-            raw = analogRead(BATTERY_PIN);
-            scaled = __LL_ADC_CALC_DATA_TO_VOLTAGE(Vref, raw, LL_ADC_RESOLUTION);
-            scaled *= operativeAdcMultiplier;
-#elif defined(ARCH_ESP32) // ADC block for espressif platforms
+#ifdef ARCH_ESP32 // ADC block for espressif platforms
             raw = espAdcRead();
             scaled = esp_adc_cal_raw_to_voltage(raw, adc_characs);
             scaled *= operativeAdcMultiplier;
-#else                     // block for all other platforms
+#else // block for all other platforms
 #ifdef ARCH_NRF52
             concurrency::LockGuard saadcGuard(concurrency::nrf52SaadcLock);
 #endif
@@ -484,14 +447,28 @@ class AnalogBatteryLevel : public HasBatteryLevel
     virtual bool isBatteryConnect() override { return getBatteryPercent() != -1; }
 #endif
 
-    // Detect if an external power source is connected if we don’t have a PMIC;
-    // Firstly prefer EXT_PWR_DETECT GPIO if available,
-    // secondly try an nRF52-specific routine on some variants,
-    // lastly provide a fallback to indicate external power when fully charged.
+    /// If we see a battery voltage higher than physics allows - assume charger is
+    /// pumping in power On some boards we don't have the power management chip
+    /// (like AXPxxxx) so we use EXT_PWR_DETECT GPIO pin to detect external power
+    /// source
     virtual bool isVbusIn() override
     {
 #ifdef EXT_PWR_DETECT
-        return digitalRead(EXT_PWR_DETECT) == EXT_PWR_DETECT_VALUE;
+#if defined(HELTEC_CAPSULE_SENSOR_V3) || defined(HELTEC_SENSOR_HUB)
+        // if external powered that pin will be pulled down
+        if (digitalRead(EXT_PWR_DETECT) == LOW) {
+            return true;
+        }
+        // if it's not LOW - check the battery
+#else
+        // if external powered that pin will be pulled up
+        if (digitalRead(EXT_PWR_DETECT) == HIGH) {
+            return true;
+        }
+        // if it's not HIGH - check the battery
+#endif
+        // If we have an EXT_PWR_DETECT pin and it indicates no external power, believe it.
+        return false;
 
 // technically speaking this should work for all(?) NRF52 boards
 // but needs testing across multiple devices. NRF52 USB would not even work if
@@ -512,9 +489,9 @@ class AnalogBatteryLevel : public HasBatteryLevel
         }
 #endif
 #if defined(ELECROW_ThinkNode_M6)
-        return digitalRead(EXT_CHRG_DETECT) == EXT_CHRG_DETECT_VALUE || isVbusIn();
+        return digitalRead(EXT_CHRG_DETECT) == ext_chrg_detect_value || isVbusIn();
 #elif EXT_CHRG_DETECT
-        return digitalRead(EXT_CHRG_DETECT) == EXT_CHRG_DETECT_VALUE;
+        return digitalRead(EXT_CHRG_DETECT) == ext_chrg_detect_value;
 #elif defined(BATTERY_CHARGING_INV)
         return !digitalRead(BATTERY_CHARGING_INV);
 #else
@@ -553,11 +530,6 @@ class AnalogBatteryLevel : public HasBatteryLevel
     bool initial_read_done = false;
     float last_read_value = (OCV[NUM_OCV_POINTS - 1] * NUM_CELLS);
     uint32_t last_read_time_ms = 0;
-#ifdef ARCH_STM32WL
-    // 3300mV placeholder for STM32 errata where VREFINT factory calibration may be missing
-    // (e.g. STM32U0, see DS14756 Rev 3 §2.4.1 "VREFINT offset")
-    uint32_t Vref = 3300;
-#endif
 
 #if HAS_TELEMETRY && !MESHTASTIC_EXCLUDE_ENVIRONMENTAL_SENSOR && defined(HAS_RAKPROT)
 
@@ -647,10 +619,14 @@ Power::Power() : OSThread("Power")
 bool Power::analogInit()
 {
 #ifdef EXT_PWR_DETECT
-    pinMode(EXT_PWR_DETECT, EXT_PWR_DETECT_MODE);
+#if defined(HELTEC_CAPSULE_SENSOR_V3) || defined(HELTEC_SENSOR_HUB)
+    pinMode(EXT_PWR_DETECT, INPUT_PULLUP);
+#else
+    pinMode(EXT_PWR_DETECT, INPUT);
+#endif
 #endif
 #ifdef EXT_CHRG_DETECT
-    pinMode(EXT_CHRG_DETECT, EXT_CHRG_DETECT_MODE);
+    pinMode(EXT_CHRG_DETECT, ext_chrg_detect_mode);
 #endif
 
 #ifdef BATTERY_PIN
@@ -663,9 +639,7 @@ bool Power::analogInit()
 #define BATTERY_SENSE_RESOLUTION_BITS 10
 #endif
 
-#ifdef ARCH_STM32WL
-    analogReadResolution(BATTERY_SENSE_RESOLUTION_BITS);
-#elif defined(ARCH_ESP32) // ESP32 needs special analog stuff
+#ifdef ARCH_ESP32 // ESP32 needs special analog stuff
 
 #ifndef ADC_WIDTH // max resolution by default
     static const adc_bits_width_t width = ADC_WIDTH_BIT_12;
@@ -675,7 +649,7 @@ bool Power::analogInit()
 #ifndef BAT_MEASURE_ADC_UNIT // ADC1
     adc1_config_width(width);
     adc1_config_channel_atten(adc_channel, atten);
-#else                        // ADC2
+#else // ADC2
     adc2_config_channel_atten(adc_channel, atten);
 #ifndef CONFIG_IDF_TARGET_ESP32S3
     // ADC2 wifi bug workaround
@@ -705,7 +679,7 @@ bool Power::analogInit()
 
     // NRF52 ADC init moved to powerHAL_init in nrf52 platform
 
-#if !defined(ARCH_ESP32) && !defined(ARCH_STM32WL)
+#ifndef ARCH_ESP32
     analogReadResolution(BATTERY_SENSE_RESOLUTION_BITS);
 #endif
 
@@ -1002,14 +976,6 @@ int32_t Power::runOnce()
             powerFSM.trigger(EVENT_POWER_CONNECTED);
         }
 
-#ifdef PMU_POWER_BUTTON_IS_CANCEL
-        // cancel action also turns the screen on and off.
-        if (PMU->isPekeyShortPressIrq()) {
-            LOG_INFO("Input: Corona Button Click");
-            InputEvent event = {.inputEvent = (input_broker_event)INPUT_BROKER_CANCEL, .kbchar = 0, .touchX = 0, .touchY = 0};
-            inputBroker->injectInputEvent(&event);
-        }
-#endif
         /*
         Other things we could check if we cared...
 
@@ -1026,6 +992,13 @@ int32_t Power::runOnce()
             LOG_DEBUG("Battery removed");
         }
         */
+#ifndef T_WATCH_S3 // FIXME - why is this triggering on the T-Watch S3?
+        if (PMU->isPekeyLongPressIrq()) {
+            LOG_DEBUG("PEK long button press");
+            if (screen)
+                screen->setOn(false);
+        }
+#endif
 
         PMU->clearIrqStatus();
     }
@@ -1094,7 +1067,7 @@ void Power::attachPowerInterrupts()
     if (PMU) {
         attachInterrupt(
             PMU_IRQ,
-            []() {
+            [] {
                 pmu_irq = true;
                 power->setIntervalFromNow(0);
                 runASAP = true;
@@ -1397,16 +1370,19 @@ bool Power::axpChipInit()
     uint64_t pmuIrqMask = 0;
 
     if (PMU->getChipModel() == XPOWERS_AXP192) {
-        pmuIrqMask = XPOWERS_AXP192_VBUS_INSERT_IRQ | XPOWERS_AXP192_VBUS_REMOVE_IRQ | XPOWERS_AXP192_PKEY_SHORT_IRQ;
+        pmuIrqMask = XPOWERS_AXP192_VBUS_INSERT_IRQ | XPOWERS_AXP192_BAT_INSERT_IRQ | XPOWERS_AXP192_PKEY_SHORT_IRQ;
     } else if (PMU->getChipModel() == XPOWERS_AXP2101) {
-        pmuIrqMask = XPOWERS_AXP2101_VBUS_INSERT_IRQ | XPOWERS_AXP2101_VBUS_REMOVE_IRQ | XPOWERS_AXP2101_PKEY_SHORT_IRQ;
+        pmuIrqMask = XPOWERS_AXP2101_VBUS_INSERT_IRQ | XPOWERS_AXP2101_BAT_INSERT_IRQ | XPOWERS_AXP2101_PKEY_SHORT_IRQ;
     }
 
     pinMode(PMU_IRQ, INPUT);
 
-    // We wake on IRQ, so only enable the IRQs that we care about.
-    // we want USB plug and unplug to update the screen and LED status,
-    // and short press on the power button to trigger the "cancel" action in the UI (which also turns the screen on and off).
+    // we do not look for AXPXXX_CHARGING_FINISHED_IRQ & AXPXXX_CHARGING_IRQ
+    // because it occurs repeatedly while there is no battery also it could cause
+    // inadvertent waking from light sleep just because the battery filled we
+    // don't look for AXPXXX_BATT_REMOVED_IRQ because it occurs repeatedly while
+    // no battery installed we don't look at AXPXXX_VBUS_REMOVED_IRQ because we
+    // don't have anything hooked to vbus
     PMU->enableIRQ(pmuIrqMask);
 
     PMU->clearIrqStatus();
@@ -1872,7 +1848,7 @@ class SerialBatteryLevel : public HasBatteryLevel
     {
 #if defined(EXT_CHRG_DETECT)
 
-        return digitalRead(EXT_CHRG_DETECT) == EXT_CHRG_DETECT_VALUE;
+        return digitalRead(EXT_CHRG_DETECT) == ext_chrg_detect_value;
 
 #endif
         return false;
@@ -1881,7 +1857,7 @@ class SerialBatteryLevel : public HasBatteryLevel
     virtual bool isCharging() override
     {
 #ifdef EXT_CHRG_DETECT
-        return digitalRead(EXT_CHRG_DETECT) == EXT_CHRG_DETECT_VALUE;
+        return digitalRead(EXT_CHRG_DETECT) == ext_chrg_detect_value;
 
 #endif
         // by default, we check the battery voltage only
@@ -1903,10 +1879,10 @@ SerialBatteryLevel serialBatteryLevel;
 bool Power::serialBatteryInit()
 {
 #ifdef EXT_PWR_DETECT
-    pinMode(EXT_PWR_DETECT, EXT_PWR_DETECT_MODE);
+    pinMode(EXT_PWR_DETECT, INPUT);
 #endif
 #ifdef EXT_CHRG_DETECT
-    pinMode(EXT_CHRG_DETECT, EXT_CHRG_DETECT_MODE);
+    pinMode(EXT_CHRG_DETECT, ext_chrg_detect_mode);
 #endif
 
     bool result = serialBatteryLevel.runOnce();

src/PowerFSM.cpp

@@ -58,35 +58,6 @@ static bool isPowered()
     return !isPowerSavingMode && powerStatus && (!powerStatus->getHasBattery() || powerStatus->getHasUSB());
 }
 
-#if defined(T5_S3_EPAPER_PRO)
-static void t5BacklightOffForSleep()
-{
-    t5BacklightSetForcedBySleep(true);
-}
-
-static void t5BacklightWakeFromSleep()
-{
-    t5BacklightSetForcedBySleep(false);
-}
-
-static void t5BacklightOffForTimeout()
-{
-    t5BacklightSetForcedByTimeout(true);
-    t5TouchSetForcedByTimeout(true);
-}
-
-static void t5BacklightOnFromUserInput()
-{
-    t5BacklightHandleUserInput();
-    t5TouchHandleUserInput();
-}
-#else
-static void t5BacklightOffForSleep() {}
-static void t5BacklightWakeFromSleep() {}
-static void t5BacklightOffForTimeout() {}
-static void t5BacklightOnFromUserInput() {}
-#endif
-
 static void sdsEnter()
 {
     LOG_POWERFSM("State: SDS");
@@ -116,7 +87,6 @@ static void lsEnter()
     LOG_POWERFSM("lsEnter begin, ls_secs=%u", config.power.ls_secs);
     if (screen)
         screen->setOn(false);
-    t5BacklightOffForSleep();
     secsSlept = 0; // How long have we been sleeping this time
 
     // LOG_INFO("lsEnter end");
@@ -189,8 +159,6 @@ static void lsIdle()
 static void lsExit()
 {
     LOG_POWERFSM("State: lsExit");
-    // Lift the light-sleep force-off gate when leaving LS.
-    t5BacklightWakeFromSleep();
 }
 
 static void nbEnter()
@@ -212,8 +180,6 @@ static void darkEnter()
     setBluetoothEnable(true);
     if (screen)
         screen->setOn(false);
-    // Screen timeout enters DARK; ensure backlight also turns off.
-    t5BacklightOffForTimeout();
 }
 
 static void serialEnter()
@@ -323,13 +289,12 @@ void PowerFSM_setup()
     powerFSM.add_transition(&stateNB, &stateNB, EVENT_PACKET_FOR_PHONE, NULL, "Received packet, resetting win wake");
 
     // Handle press events - note: we ignore button presses when in API mode
-    powerFSM.add_transition(&stateLS, &stateON, EVENT_PRESS, t5BacklightOnFromUserInput, "Press");
-    powerFSM.add_transition(&stateNB, &stateON, EVENT_PRESS, t5BacklightOnFromUserInput, "Press");
-    powerFSM.add_transition(&stateDARK, isPowered() ? &statePOWER : &stateON, EVENT_PRESS, t5BacklightOnFromUserInput, "Press");
-    powerFSM.add_transition(&statePOWER, &statePOWER, EVENT_PRESS, t5BacklightOnFromUserInput, "Press");
-    powerFSM.add_transition(&stateON, &stateON, EVENT_PRESS, t5BacklightOnFromUserInput,
-                            "Press"); // reenter On to restart our timers
-    powerFSM.add_transition(&stateSERIAL, &stateSERIAL, EVENT_PRESS, t5BacklightOnFromUserInput,
+    powerFSM.add_transition(&stateLS, &stateON, EVENT_PRESS, NULL, "Press");
+    powerFSM.add_transition(&stateNB, &stateON, EVENT_PRESS, NULL, "Press");
+    powerFSM.add_transition(&stateDARK, isPowered() ? &statePOWER : &stateON, EVENT_PRESS, NULL, "Press");
+    powerFSM.add_transition(&statePOWER, &statePOWER, EVENT_PRESS, NULL, "Press");
+    powerFSM.add_transition(&stateON, &stateON, EVENT_PRESS, NULL, "Press"); // reenter On to restart our timers
+    powerFSM.add_transition(&stateSERIAL, &stateSERIAL, EVENT_PRESS, NULL,
                             "Press"); // Allow button to work while in serial API
 
     // Handle critically low power battery by forcing deep sleep
@@ -349,13 +314,11 @@ void PowerFSM_setup()
     powerFSM.add_transition(&stateSERIAL, &stateSHUTDOWN, EVENT_SHUTDOWN, NULL, "Shutdown");
 
     // Inputbroker
-    powerFSM.add_transition(&stateLS, &stateON, EVENT_INPUT, t5BacklightOnFromUserInput, "Input Device");
-    powerFSM.add_transition(&stateNB, &stateON, EVENT_INPUT, t5BacklightOnFromUserInput, "Input Device");
-    powerFSM.add_transition(&stateDARK, &stateON, EVENT_INPUT, t5BacklightOnFromUserInput, "Input Device");
-    powerFSM.add_transition(&stateON, &stateON, EVENT_INPUT, t5BacklightOnFromUserInput,
-                            "Input Device"); // restarts the sleep timer
-    powerFSM.add_transition(&statePOWER, &statePOWER, EVENT_INPUT, t5BacklightOnFromUserInput,
-                            "Input Device"); // restarts the sleep timer
+    powerFSM.add_transition(&stateLS, &stateON, EVENT_INPUT, NULL, "Input Device");
+    powerFSM.add_transition(&stateNB, &stateON, EVENT_INPUT, NULL, "Input Device");
+    powerFSM.add_transition(&stateDARK, &stateON, EVENT_INPUT, NULL, "Input Device");
+    powerFSM.add_transition(&stateON, &stateON, EVENT_INPUT, NULL, "Input Device");       // restarts the sleep timer
+    powerFSM.add_transition(&statePOWER, &statePOWER, EVENT_INPUT, NULL, "Input Device"); // restarts the sleep timer
 
     powerFSM.add_transition(&stateDARK, &stateON, EVENT_BLUETOOTH_PAIR, NULL, "Bluetooth pairing");
     powerFSM.add_transition(&stateON, &stateON, EVENT_BLUETOOTH_PAIR, NULL, "Bluetooth pairing");

src/RedirectablePrint.cpp

@@ -7,7 +7,6 @@
 #include "memGet.h"
 #include "mesh/generated/meshtastic/mesh.pb.h"
 #include <assert.h>
-#include <atomic>
 #include <cstring>
 #include <memory>
 #include <stdexcept>
@@ -21,22 +20,6 @@
 #if HAS_NETWORKING
 extern meshtastic::Syslog syslog;
 #endif
-
-namespace
-{
-std::atomic<bool> serialHalLogSuppressed{false};
-}
-
-void RedirectablePrint::setSerialHalLogSuppressed(bool suppressed)
-{
-    serialHalLogSuppressed.store(suppressed);
-}
-
-bool RedirectablePrint::isSerialHalLogSuppressed()
-{
-    return serialHalLogSuppressed.load();
-}
-
 void RedirectablePrint::rpInit()
 {
 #ifdef HAS_FREE_RTOS
@@ -154,7 +137,7 @@ void RedirectablePrint::log_to_serial(const char *logLevel, const char *format,
         if (color) {
             ::printf("\u001b[0m");
         }
-        ::printf("| %02d:%02d:%02d %u.%03u ", hour, min, sec, millis() / 1000, millis() % 1000);
+        ::printf("| %02d:%02d:%02d %u ", hour, min, sec, millis() / 1000);
 #else
         printf("%s ", logLevel);
         if (color) {
@@ -168,7 +151,7 @@ void RedirectablePrint::log_to_serial(const char *logLevel, const char *format,
         if (color) {
             ::printf("\u001b[0m");
         }
-        ::printf("| ??:??:?? %u.%03u ", millis() / 1000, millis() % 1000);
+        ::printf("| ??:??:?? %u ", millis() / 1000);
 #else
         printf("%s ", logLevel);
         if (color) {
@@ -294,10 +277,6 @@ meshtastic_LogRecord_Level RedirectablePrint::getLogLevel(const char *logLevel)
 void RedirectablePrint::log(const char *logLevel, const char *format, ...)
 {
 
-    if (isSerialHalLogSuppressed()) {
-        return;
-    }
-
     // append \n to format
     size_t len = strlen(format);
     auto newFormat = std::unique_ptr<char[]>(new char[len + 2]);

src/RedirectablePrint.h

@@ -24,11 +24,6 @@ class RedirectablePrint : public Print
   public:
     explicit RedirectablePrint(Print *_dest) : dest(_dest) {}
 
-    /// Suppress all log output while a SerialHal transaction is in progress.
-    // Unclear if this is necessary, but it seems to help with response speeds.
-    static void setSerialHalLogSuppressed(bool suppressed);
-    static bool isSerialHalLogSuppressed();
-
     /**
      * Set a new destination
      */

src/SafeFile.cpp

@@ -7,6 +7,10 @@ static File openFile(const char *filename, bool fullAtomic)
 {
     concurrency::LockGuard g(spiLock);
     LOG_DEBUG("Opening %s, fullAtomic=%d", filename, fullAtomic);
+#ifdef ARCH_NRF52
+    FSCom.remove(filename);
+    return FSCom.open(filename, FILE_O_WRITE);
+#endif
     if (!fullAtomic) {
         FSCom.remove(filename); // Nuke the old file to make space (ignore if it !exists)
     }
@@ -63,6 +67,9 @@ bool SafeFile::close()
     f.close();
     spiLock->unlock();
 
+#ifdef ARCH_NRF52
+    return true;
+#endif
     if (!testReadback())
         return false;
 

src/SerialConsole.cpp

@@ -30,9 +30,6 @@ SerialConsole *console;
 
 void consoleInit()
 {
-    if (console) {
-        return;
-    }
     auto sc = new SerialConsole(); // Must be dynamically allocated because we are now inheriting from thread
 
 #if defined(SERIAL_HAS_ON_RECEIVE)

src/airtime.h

@@ -19,8 +19,8 @@
 
   TX_LOG + RX_LOG = Total air time for a particular meshtastic channel.
 
-  TX_LOG + RX_ALL_LOG = Total air time for a particular meshtastic channel, including
-                        other lora radios.
+  TX_LOG + RX_LOG = Total air time for a particular meshtastic channel, including
+                    other lora radios.
 
   RX_ALL_LOG - RX_LOG = Other lora radios on our frequency channel.
 */

src/configuration.h

@@ -78,11 +78,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 // Configuration
 // -----------------------------------------------------------------------------
 
-// Pre-hop drop handling (compile-time flag).
-#ifndef MESHTASTIC_PREHOP_DROP
-#define MESHTASTIC_PREHOP_DROP 1
-#endif
-
 /// Convert a preprocessor name into a quoted string
 #define xstr(s) ystr(s)
 #define ystr(s) #s
@@ -234,7 +229,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define BME_ADDR 0x76
 #define BME_ADDR_ALTERNATE 0x77
 #define MCP9808_ADDR 0x18
-#define INA_ADDR 0x40 // same as SHT2X
+#define INA_ADDR 0x40
 #define INA_ADDR_ALTERNATE 0x41
 #define INA_ADDR_WAVESHARE_UPS 0x43
 #define INA3221_ADDR 0x42
@@ -247,8 +242,8 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define LPS22HB_ADDR 0x5C
 #define LPS22HB_ADDR_ALT 0x5D
 #define SFA30_ADDR 0x5D
-#define SHTXX_ADDR 0x44
-#define SHTXX_ADDR_ALT 0x45
+#define SHT31_4x_ADDR 0x44
+#define SHT31_4x_ADDR_ALT 0x45
 #define PMSA003I_ADDR 0x12
 #define QMA6100P_ADDR 0x12
 #define AHT10_ADDR 0x38
@@ -502,7 +497,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define MESHTASTIC_EXCLUDE_PKI 1
 #define MESHTASTIC_EXCLUDE_POWER_FSM 1
 #define MESHTASTIC_EXCLUDE_TZ 1
-#define MESHTASTIC_EXCLUDE_PKT_HISTORY_HASH 1
 #endif
 
 // Turn off all optional modules
@@ -519,7 +513,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define MESHTASTIC_EXCLUDE_REMOTEHARDWARE 1
 #define MESHTASTIC_EXCLUDE_STOREFORWARD 1
 #define MESHTASTIC_EXCLUDE_TEXTMESSAGE 1
-#define MESHTASTIC_EXCLUDE_TRAFFIC_MANAGEMENT 1
 #define MESHTASTIC_EXCLUDE_ATAK 1
 #define MESHTASTIC_EXCLUDE_CANNEDMESSAGES 1
 #define MESHTASTIC_EXCLUDE_NEIGHBORINFO 1

src/detect/ScanI2CTwoWire.cpp

@@ -136,9 +136,7 @@ bool ScanI2CTwoWire::i2cCommandResponseLength(ScanI2C::DeviceAddress addr, uint1
     return match;
 }
 
-#if HAS_TELEMETRY && !MESHTASTIC_EXCLUDE_AIR_QUALITY_SENSOR
-// FIXME Move to a separate file for detection of sensors that require more complex interactions?
-// For SEN5X detection
+/// for SEN5X detection
 // Note, this code needs to be called before setting the I2C bus speed
 // for the screen at high speed. The speed needs to be at 100kHz, otherwise
 // detection will not work
@@ -176,46 +174,6 @@ String readSEN5xProductName(TwoWire *i2cBus, uint8_t address)
 
     return String(productName);
 }
-#endif
-
-#if HAS_TELEMETRY && !MESHTASTIC_EXCLUDE_ENVIRONMENTAL_SENSOR
-bool detectSHT21SerialNumber(TwoWire *i2cBus, uint8_t address)
-{
-
-    i2cBus->beginTransmission(address);
-    i2cBus->write(0xFA);
-    i2cBus->write(0x0F);
-
-    if (i2cBus->endTransmission() != 0)
-        return false;
-
-    if (i2cBus->requestFrom(address, (uint8_t)8) != 8)
-        return false;
-
-    // Just flush the data
-    while (i2cBus->available() < 8) {
-        i2cBus->read();
-    }
-
-    i2cBus->beginTransmission(address);
-    i2cBus->write(0xFC);
-    i2cBus->write(0xC9);
-
-    if (i2cBus->endTransmission() != 0)
-        return false;
-
-    if (i2cBus->requestFrom(address, (uint8_t)6) != 6)
-        return false;
-
-    // Just flush the data
-    while (i2cBus->available() < 6) {
-        i2cBus->read();
-    }
-
-    // Assume we detect the SHT21 if something came back from the request
-    return true;
-}
-#endif
 
 #define SCAN_SIMPLE_CASE(ADDR, T, ...)                                                                                           \
     case ADDR:                                                                                                                   \
@@ -413,47 +371,27 @@ void ScanI2CTwoWire::scanPort(I2CPort port, uint8_t *address, uint8_t asize)
                 break;
 #endif
 #if !defined(M5STACK_UNITC6L)
-            case INA_ADDR: // Same as SHT2X
+            case INA_ADDR:
             case INA_ADDR_ALTERNATE:
-            case INA_ADDR_WAVESHARE_UPS: {
-                uint16_t mfg = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xFE), 2);
+            case INA_ADDR_WAVESHARE_UPS:
+                registerValue = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xFE), 2);
+                LOG_DEBUG("Register MFG_UID: 0x%x", registerValue);
+                if (registerValue == 0x5449) {
+                    registerValue = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xFF), 2);
+                    LOG_DEBUG("Register DIE_UID: 0x%x", registerValue);
 
-                LOG_DEBUG("Register MFG_UID: 0x%x", mfg);
-
-                // Only read DIE_UID for vendors we recognize as INA-compatible to avoid
-                // an extra I2C transaction + delay on other devices sharing this address.
-                if (mfg == 0x5449 || mfg == 0x190F) {
-                    uint16_t die = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xFF), 2);
-                    LOG_DEBUG("Register DIE_UID: 0x%x", die);
-
-                    // TI INA226 or fully compatible clones (e.g. TPA626)
-                    if (mfg == 0x5449 && die == 0x2260) {
+                    if (registerValue == 0x2260) {
                         logFoundDevice("INA226", (uint8_t)addr.address);
                         type = INA226;
-                    }
-                    // Silergy SQ52201 (INA226-compatible with different IDs)
-                    else if (mfg == 0x190F && die == 0x0000) {
-                        logFoundDevice("INA226 (SQ52201)", (uint8_t)addr.address);
-                        type = INA226;
-                    }
-                    // TI INA260
-                    else if (mfg == 0x5449) {
+                    } else {
                         logFoundDevice("INA260", (uint8_t)addr.address);
                         type = INA260;
                     }
-                }
-#if HAS_TELEMETRY && !MESHTASTIC_EXCLUDE_ENVIRONMENTAL_SENSOR
-                if (type == NONE && detectSHT21SerialNumber(i2cBus, (uint8_t)addr.address)) {
-                    logFoundDevice("SHTXX (SHT2X)", (uint8_t)addr.address);
-                    type = SHTXX;
-                }
-#endif
-                else { // Assume INA219 if none of the above ones are found
+                } else { // Assume INA219 if INA260 ID is not found
                     logFoundDevice("INA219", (uint8_t)addr.address);
                     type = INA219;
                 }
                 break;
-            }
             case INA3221_ADDR:
                 registerValue = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xFE), 2);
                 LOG_DEBUG("Register MFG_UID FE: 0x%x", registerValue);
@@ -510,19 +448,22 @@ void ScanI2CTwoWire::scanPort(I2CPort port, uint8_t *address, uint8_t asize)
                     }
                     break;
                 }
-            case SHTXX_ADDR:     // same as OPT3001_ADDR_ALT
-            case SHTXX_ADDR_ALT: // same as OPT3001_ADDR
+            case SHT31_4x_ADDR:     // same as OPT3001_ADDR_ALT
+            case SHT31_4x_ADDR_ALT: // same as OPT3001_ADDR
                 if (getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0x7E), 2) == 0x5449) {
                     type = OPT3001;
                     logFoundDevice("OPT3001", (uint8_t)addr.address);
-                } else { // SHTXX
-                    type = SHTXX;
-                    logFoundDevice("SHTXX", (uint8_t)addr.address);
+                } else if (i2cCommandResponseLength(addr, 0x89, 6)) { // SHT4x serial number (6 bytes inc. CRC)
+                    type = SHT4X;
+                    logFoundDevice("SHT4X", (uint8_t)addr.address);
+                } else {
+                    type = SHT31;
+                    logFoundDevice("SHT31", (uint8_t)addr.address);
                 }
 
                 break;
 
-                SCAN_SIMPLE_CASE(SHTC3_ADDR, SHTXX, "SHTXX", (uint8_t)addr.address)
+                SCAN_SIMPLE_CASE(SHTC3_ADDR, SHTC3, "SHTC3", (uint8_t)addr.address)
             case RCWL9620_ADDR:
                 // get MAX30102 PARTID
                 registerValue = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xFF), 1);
@@ -758,7 +699,6 @@ void ScanI2CTwoWire::scanPort(I2CPort port, uint8_t *address, uint8_t asize)
                     logFoundDevice("BMX160", (uint8_t)addr.address);
                     break;
                 } else {
-#if HAS_TELEMETRY && !MESHTASTIC_EXCLUDE_AIR_QUALITY_SENSOR
                     String prod = "";
                     prod = readSEN5xProductName(i2cBus, addr.address);
                     if (prod.startsWith("SEN55")) {
@@ -774,7 +714,6 @@ void ScanI2CTwoWire::scanPort(I2CPort port, uint8_t *address, uint8_t asize)
                         logFoundDevice("Sensirion SEN50", addr.address);
                         break;
                     }
-#endif
                     if (addr.address == BMX160_ADDR) {
                         type = BMX160;
                         logFoundDevice("BMX160", (uint8_t)addr.address);

src/gps/GPS.cpp

@@ -103,14 +103,6 @@ static int32_t gpsSwitch()
     if (gps) {
         int currentState = digitalRead(PIN_GPS_SWITCH);
 
-        // Respect explicit NOT_PRESENT mode and do not let the hardware switch re-enable GPS.
-        if (config.position.gps_mode == meshtastic_Config_PositionConfig_GpsMode_NOT_PRESENT) {
-            gps->disable();
-            lastState = currentState;
-            firstrun = false;
-            return 1000;
-        }
-
         // if the switch is set to zero, disable the GPS Thread
         if (firstrun)
             if (currentState == LOW)

src/graphics/Screen.cpp

@@ -39,7 +39,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include "draw/NodeListRenderer.h"
 #include "draw/NotificationRenderer.h"
 #include "draw/UIRenderer.h"
-#include "graphics/TFTColorRegions.h"
 #include "modules/CannedMessageModule.h"
 
 #if !MESHTASTIC_EXCLUDE_GPS
@@ -55,14 +54,12 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include "gps/RTC.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTPalette.h"
 #include "graphics/emotes.h"
 #include "graphics/images.h"
 #include "input/TouchScreenImpl1.h"
 #include "main.h"
 #include "mesh-pb-constants.h"
 #include "mesh/Channels.h"
-#include "mesh/Default.h"
 #include "mesh/generated/meshtastic/deviceonly.pb.h"
 #include "modules/ExternalNotificationModule.h"
 #include "modules/TextMessageModule.h"
@@ -71,6 +68,12 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include "target_specific.h"
 extern MessageStore messageStore;
 
+#if USE_TFTDISPLAY
+extern uint16_t TFT_MESH;
+#else
+uint16_t TFT_MESH = COLOR565(0x67, 0xEA, 0x94);
+#endif
+
 #if HAS_WIFI && !defined(ARCH_PORTDUINO)
 #include "mesh/wifi/WiFiAPClient.h"
 #endif
@@ -95,7 +98,6 @@ namespace graphics
 
 // This means the *visible* area (sh1106 can address 132, but shows 128 for example)
 #define IDLE_FRAMERATE 1 // in fps
-#define COMPASS_ACTIVE_FRAMERATE 20
 
 // DEBUG
 #define NUM_EXTRA_FRAMES 3 // text message and debug frame
@@ -105,27 +107,6 @@ namespace graphics
 // A text message frame + debug frame + all the node infos
 FrameCallback *normalFrames;
 static uint32_t targetFramerate = IDLE_FRAMERATE;
-#if GRAPHICS_TFT_COLORING_ENABLED
-static inline void prepareFrameColorRegions()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    clearTFTColorRegions();
-    // Full-frame FrameMono inversion for themes that need it (e.g. light themes).
-    if (isThemeFullFrameInvert()) {
-        setAndRegisterTFTColorRole(TFTColorRole::FrameMono, getThemeBodyFg(), getThemeBodyBg(), 0, 0, screen->getWidth(),
-                                   screen->getHeight());
-    }
-#endif
-}
-#endif
-
-static inline void updateUiFrame(OLEDDisplayUi *ui)
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    prepareFrameColorRegions();
-#endif
-    ui->update();
-}
 // Global variables for alert banner - explicitly define with extern "C" linkage to prevent optimization
 
 uint32_t logo_timeout = 5000; // 4 seconds for EACH logo
@@ -154,60 +135,6 @@ static bool heartbeat = false;
 
 extern bool hasUnreadMessage;
 
-static inline float wrapHeading360(float heading)
-{
-    if (heading < 0.0f) {
-        heading += 360.0f;
-    } else if (heading >= 360.0f) {
-        heading -= 360.0f;
-    }
-    return heading;
-}
-
-void Screen::setHeading(float heading)
-{
-    const float wrappedHeading = wrapHeading360(heading);
-
-    if (!hasCompass) {
-        hasCompass = true;
-        compassHeading = wrappedHeading;
-        return;
-    }
-
-    // Interpolate using shortest-path angular delta to avoid jumps around 0/360.
-    float delta = wrappedHeading - compassHeading;
-    if (delta > 180.0f) {
-        delta -= 360.0f;
-    } else if (delta < -180.0f) {
-        delta += 360.0f;
-    }
-
-    // Adaptive filtering:
-    // - Strong damping for tiny deltas (jitter)
-    // - Faster response for larger turns
-    const float absDelta = (delta >= 0.0f) ? delta : -delta;
-    if (absDelta < 1.0f) {
-        return;
-    }
-
-    float alpha = 0.35f;
-    if (absDelta > 25.0f) {
-        alpha = 0.85f;
-    } else if (absDelta > 10.0f) {
-        alpha = 0.65f;
-    }
-
-    float step = delta * alpha;
-    const float maxStep = 12.0f;
-    if (step > maxStep) {
-        step = maxStep;
-    } else if (step < -maxStep) {
-        step = -maxStep;
-    }
-
-    compassHeading = wrapHeading360(compassHeading + step);
-}
-
 // ==============================
 // Overlay Alert Banner Renderer
 // ==============================
@@ -244,7 +171,7 @@ void Screen::showOverlayBanner(BannerOverlayOptions banner_overlay_options)
     static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
     ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
     ui->setTargetFPS(60);
-    updateUiFrame(ui);
+    ui->update();
 }
 
 // Called to trigger a banner with custom message and duration
@@ -266,7 +193,7 @@ void Screen::showNodePicker(const char *message, uint32_t durationMs, std::funct
     static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
     ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
     ui->setTargetFPS(60);
-    updateUiFrame(ui);
+    ui->update();
 }
 
 // Called to trigger a banner with custom message and duration
@@ -290,7 +217,7 @@ void Screen::showNumberPicker(const char *message, uint32_t durationMs, uint8_t
     static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
     ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
     ui->setTargetFPS(60);
-    updateUiFrame(ui);
+    ui->update();
 }
 
 void Screen::showTextInput(const char *header, const char *initialText, uint32_t durationMs,
@@ -313,7 +240,7 @@ void Screen::showTextInput(const char *header, const char *initialText, uint32_t
     static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
     ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
     ui->setTargetFPS(60);
-    updateUiFrame(ui);
+    ui->update();
 }
 
 static void drawModuleFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y)
@@ -345,25 +272,10 @@ static void drawModuleFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int
 float Screen::estimatedHeading(double lat, double lon)
 {
     static double oldLat, oldLon;
-    static float b = -1.0f;
-    static uint32_t lastHeadingAtMs = 0;
-    const uint32_t now = millis();
-    const uint32_t gpsUpdateIntervalSecs =
-        Default::getConfiguredOrDefault(config.position.gps_update_interval, default_gps_update_interval);
-    uint32_t effectiveUpdateIntervalSecs = gpsUpdateIntervalSecs;
-    if (config.position.position_broadcast_smart_enabled) {
-        const uint32_t smartMinIntervalSecs = Default::getConfiguredOrDefault(
-            config.position.broadcast_smart_minimum_interval_secs, default_broadcast_smart_minimum_interval_secs);
-        if (smartMinIntervalSecs > effectiveUpdateIntervalSecs) {
-            effectiveUpdateIntervalSecs = smartMinIntervalSecs;
-        }
-    }
-    // Two expected update windows; keep arithmetic 32-bit to avoid pulling in larger 64-bit helpers.
-    const uint32_t headingStaleMs =
-        (effectiveUpdateIntervalSecs > (UINT32_MAX / 2000U)) ? UINT32_MAX : (effectiveUpdateIntervalSecs * 2000U);
+    static float b;
 
     if (oldLat == 0) {
-        // Need at least two position points before we can infer heading.
+        // just prepare for next time
         oldLat = lat;
         oldLon = lon;
 
@@ -371,20 +283,12 @@ float Screen::estimatedHeading(double lat, double lon)
     }
 
     float d = GeoCoord::latLongToMeter(oldLat, oldLon, lat, lon);
-    if (d < 10) { // haven't moved enough, keep previous heading (invalid until first real movement)
-        if (lastHeadingAtMs != 0 && (now - lastHeadingAtMs) >= headingStaleMs) {
-            // Heading is stale after prolonged no-movement; force reacquire.
-            b = -1.0f;
-            oldLat = lat;
-            oldLon = lon;
-        }
+    if (d < 10) // haven't moved enough, just keep current bearing
         return b;
-    }
 
     b = GeoCoord::bearing(oldLat, oldLon, lat, lon) * RAD_TO_DEG;
     oldLat = lat;
     oldLon = lon;
-    lastHeadingAtMs = now;
 
     return b;
 }
@@ -405,6 +309,30 @@ Screen::Screen(ScanI2C::DeviceAddress address, meshtastic_Config_DisplayConfig_O
 {
     graphics::normalFrames = new FrameCallback[MAX_NUM_NODES + NUM_EXTRA_FRAMES];
 
+    int32_t rawRGB = uiconfig.screen_rgb_color;
+
+    // Only validate the combined value once
+    if (rawRGB > 0 && rawRGB <= 255255255) {
+        LOG_INFO("Setting screen RGB color to user chosen: 0x%06X", rawRGB);
+        // Extract each component as a normal int first
+        int r = (rawRGB >> 16) & 0xFF;
+        int g = (rawRGB >> 8) & 0xFF;
+        int b = rawRGB & 0xFF;
+        if (r >= 0 && r <= 255 && g >= 0 && g <= 255 && b >= 0 && b <= 255) {
+            TFT_MESH = COLOR565(static_cast<uint8_t>(r), static_cast<uint8_t>(g), static_cast<uint8_t>(b));
+        }
+#ifdef TFT_MESH_OVERRIDE
+    } else if (rawRGB == 0) {
+        LOG_INFO("Setting screen RGB color to TFT_MESH_OVERRIDE: 0x%04X", TFT_MESH_OVERRIDE);
+        // Default to TFT_MESH_OVERRIDE if available
+        TFT_MESH = TFT_MESH_OVERRIDE;
+#endif
+    } else {
+        // Default best readable yellow color
+        LOG_INFO("Setting screen RGB color to default: (255,255,128)");
+        TFT_MESH = COLOR565(255, 255, 128);
+    }
+
 #if defined(USE_SH1106) || defined(USE_SH1107) || defined(USE_SH1107_128_64)
     dispdev = new SH1106Wire(address.address, -1, -1, geometry,
                              (address.port == ScanI2C::I2CPort::WIRE1) ? HW_I2C::I2C_TWO : HW_I2C::I2C_ONE);
@@ -467,13 +395,9 @@ Screen::Screen(ScanI2C::DeviceAddress address, meshtastic_Config_DisplayConfig_O
 #endif
 
 #if defined(USE_ST7789)
-    // Keep firmware and ST7789 driver region structs layout-compatible:
-    // we pass `graphics::colorRegions` through a type cast below.
-    static_assert(sizeof(graphics::TFTColorRegion) == sizeof(::TFTColorRegion),
-                  "graphics::TFTColorRegion layout must match ST7789 TFTColorRegion");
-    static_cast<ST7789Spi *>(dispdev)->setRGB(TFTPalette::White, (::TFTColorRegion *)colorRegions);
+    static_cast<ST7789Spi *>(dispdev)->setRGB(TFT_MESH);
 #elif defined(USE_ST7796)
-    static_cast<ST7796Spi *>(dispdev)->setRGB(TFTPalette::White);
+    static_cast<ST7796Spi *>(dispdev)->setRGB(TFT_MESH);
 #endif
 
     ui = new OLEDDisplayUi(dispdev);
@@ -524,11 +448,6 @@ void Screen::handleSetOn(bool on, FrameCallback einkScreensaver)
             delay(100);
 #endif
 #if !ARCH_PORTDUINO
-#if defined(USE_ST7789) && defined(VTFT_CTRL)
-            // Ensure panel power rail is enabled before sending wake commands.
-            pinMode(VTFT_CTRL, OUTPUT);
-            digitalWrite(VTFT_CTRL, LOW);
-#endif
             dispdev->displayOn();
 #endif
 
@@ -550,6 +469,10 @@ void Screen::handleSetOn(bool on, FrameCallback einkScreensaver)
             ui->init();
 #endif
 #if defined(USE_ST7789) && defined(VTFT_LEDA)
+#ifdef VTFT_CTRL
+            pinMode(VTFT_CTRL, OUTPUT);
+            digitalWrite(VTFT_CTRL, LOW);
+#endif
             ui->init();
 #ifdef ESP_PLATFORM
             analogWrite(VTFT_LEDA, BRIGHTNESS_DEFAULT);
@@ -590,22 +513,23 @@ void Screen::handleSetOn(bool on, FrameCallback einkScreensaver)
 #endif
 #ifdef USE_ST7789
             SPI1.end();
-            // Keep TFT control pins in deterministic states while timed-off.
-            // Floating/default pin states can corrupt panel edge rows on wake.
+#if defined(ARCH_ESP32)
 #ifdef VTFT_LEDA
-            pinMode(VTFT_LEDA, OUTPUT);
-            digitalWrite(VTFT_LEDA, !TFT_BACKLIGHT_ON);
+            pinMode(VTFT_LEDA, ANALOG);
 #endif
 #ifdef VTFT_CTRL
-            pinMode(VTFT_CTRL, OUTPUT);
-            digitalWrite(VTFT_CTRL, HIGH);
+            pinMode(VTFT_CTRL, ANALOG);
+#endif
+            pinMode(ST7789_RESET, ANALOG);
+            pinMode(ST7789_RS, ANALOG);
+            pinMode(ST7789_NSS, ANALOG);
+#else
+            nrf_gpio_cfg_default(VTFT_LEDA);
+            nrf_gpio_cfg_default(VTFT_CTRL);
+            nrf_gpio_cfg_default(ST7789_RESET);
+            nrf_gpio_cfg_default(ST7789_RS);
+            nrf_gpio_cfg_default(ST7789_NSS);
 #endif
-            pinMode(ST7789_RESET, OUTPUT);
-            digitalWrite(ST7789_RESET, HIGH);
-            pinMode(ST7789_RS, OUTPUT);
-            digitalWrite(ST7789_RS, HIGH);
-            pinMode(ST7789_NSS, OUTPUT);
-            digitalWrite(ST7789_NSS, HIGH);
 #endif
 #ifdef USE_ST7796
             SPI1.end();
@@ -660,16 +584,16 @@ void Screen::setup()
     static_cast<SH1106Wire *>(dispdev)->setSubtype(7);
 #endif
 
-#if defined(USE_ST7789)
-    static_assert(sizeof(graphics::TFTColorRegion) == sizeof(::TFTColorRegion),
-                  "graphics::TFTColorRegion layout must match ST7789 TFTColorRegion");
-    static_cast<ST7789Spi *>(dispdev)->setRGB(TFTPalette::White, (::TFTColorRegion *)colorRegions);
+#if defined(USE_ST7789) && defined(TFT_MESH)
+    // Apply custom RGB color (e.g. Heltec T114/T190)
+    static_cast<ST7789Spi *>(dispdev)->setRGB(TFT_MESH);
 #endif
 #if defined(MUZI_BASE)
     dispdev->delayPoweron = true;
 #endif
-#if defined(USE_ST7796)
-    static_cast<ST7796Spi *>(dispdev)->setRGB(TFTPalette::White);
+#if defined(USE_ST7796) && defined(TFT_MESH)
+    // Custom text color, if defined in variant.h
+    static_cast<ST7796Spi *>(dispdev)->setRGB(TFT_MESH);
 #endif
 
     // Initialize display and UI system
@@ -715,7 +639,7 @@ void Screen::setup()
 #endif
         {
             const char *region = myRegion ? myRegion->name : nullptr;
-            graphics::UIRenderer::drawBootIconScreen(region, display, state, x, y);
+            graphics::UIRenderer::drawIconScreen(region, display, state, x, y);
         }
     };
     ui->setFrames(alertFrames, 1);
@@ -754,9 +678,9 @@ void Screen::setup()
     //  Turn on display and trigger first draw
     handleSetOn(true);
     graphics::currentResolution = graphics::determineScreenResolution(dispdev->height(), dispdev->width());
-    updateUiFrame(ui);
+    ui->update();
 #ifndef USE_EINK
-    updateUiFrame(ui); // Some SSD1306 clones drop the first draw, so run twice
+    ui->update(); // Some SSD1306 clones drop the first draw, so run twice
 #endif
     serialSinceMsec = millis();
 
@@ -829,7 +753,7 @@ void Screen::forceDisplay(bool forceUiUpdate)
         do {
             startUpdate = millis(); // Handle impossibly unlikely corner case of a millis() overflow..
             delay(10);
-            updateUiFrame(ui);
+            ui->update();
         } while (ui->getUiState()->lastUpdate < startUpdate);
 
         // Return to normal frame rate
@@ -900,9 +824,9 @@ int32_t Screen::runOnce()
         static FrameCallback bootOEMFrames[] = {graphics::UIRenderer::drawOEMBootScreen};
         static const int bootOEMFrameCount = sizeof(bootOEMFrames) / sizeof(bootOEMFrames[0]);
         ui->setFrames(bootOEMFrames, bootOEMFrameCount);
-        updateUiFrame(ui);
+        ui->update();
 #ifndef USE_EINK
-        updateUiFrame(ui);
+        ui->update();
 #endif
         showingOEMBootScreen = false;
     }
@@ -993,28 +917,15 @@ int32_t Screen::runOnce()
 
     // this must be before the frameState == FIXED check, because we always
     // want to draw at least one FIXED frame before doing forceDisplay
-    updateUiFrame(ui);
+    ui->update();
 
     // Switch to a low framerate (to save CPU) when we are not in transition
     // but we should only call setTargetFPS when framestate changes, because
     // otherwise that breaks animations.
 
-    uint32_t desiredFramerate = IDLE_FRAMERATE;
-#if HAS_GPS && !defined(USE_EINK)
-    if (showingNormalScreen && hasCompass) {
-        const uint8_t currentFrame = ui->getUiState()->currentFrame;
-        if ((framesetInfo.positions.gps != 255 && currentFrame == framesetInfo.positions.gps) ||
-            (framesetInfo.positions.waypoint != 255 && currentFrame == framesetInfo.positions.waypoint) ||
-            (framesetInfo.positions.firstFavorite != 255 && currentFrame >= framesetInfo.positions.firstFavorite &&
-             currentFrame <= framesetInfo.positions.lastFavorite)) {
-            desiredFramerate = COMPASS_ACTIVE_FRAMERATE;
-        }
-    }
-#endif
-
-    if (targetFramerate != desiredFramerate && ui->getUiState()->frameState == FIXED) {
+    if (targetFramerate != IDLE_FRAMERATE && ui->getUiState()->frameState == FIXED) {
         // oldFrameState = ui->getUiState()->frameState;
-        targetFramerate = desiredFramerate;
+        targetFramerate = IDLE_FRAMERATE;
 
         ui->setTargetFPS(targetFramerate);
         forceDisplay();
@@ -1055,7 +966,7 @@ void Screen::setSSLFrames()
         // LOG_DEBUG("Show SSL frames");
         static FrameCallback sslFrames[] = {NotificationRenderer::drawSSLScreen};
         ui->setFrames(sslFrames, 1);
-        updateUiFrame(ui);
+        ui->update();
     }
 }
 
@@ -1091,7 +1002,7 @@ void Screen::setScreensaverFrames(FrameCallback einkScreensaver)
     do {
         startUpdate = millis(); // Handle impossibly unlikely corner case of a millis() overflow..
         delay(1);
-        updateUiFrame(ui);
+        ui->update();
     } while (ui->getUiState()->lastUpdate < startUpdate);
 
 #if defined(USE_EINK_PARALLELDISPLAY)
@@ -1286,7 +1197,7 @@ void Screen::setFrames(FrameFocus focus)
         for (size_t i = 0; i < nodeDB->getNumMeshNodes(); i++) {
             const meshtastic_NodeInfoLite *n = nodeDB->getMeshNodeByIndex(i);
             if (n && n->num != nodeDB->getNodeNum() && n->is_favorite) {
-                favoriteFrames.push_back(graphics::UIRenderer::drawFavoriteNode);
+                favoriteFrames.push_back(graphics::UIRenderer::drawNodeInfo);
             }
         }
 
@@ -1315,7 +1226,7 @@ void Screen::setFrames(FrameFocus focus)
     static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
     ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
 
-    prevFrame = -1; // Force drawFavoriteNode to pick a new node (because our list just changed)
+    prevFrame = -1; // Force drawNodeInfo to pick a new node (because our list just changed)
 
     // Focus on a specific frame, in the frame set we just created
     switch (focus) {
@@ -1466,15 +1377,9 @@ void Screen::blink()
     dispdev->setBrightness(254);
     while (count > 0) {
         dispdev->fillRect(0, 0, dispdev->getWidth(), dispdev->getHeight());
-#if GRAPHICS_TFT_COLORING_ENABLED
-        prepareFrameColorRegions();
-#endif
         dispdev->display();
         delay(50);
         dispdev->clear();
-#if GRAPHICS_TFT_COLORING_ENABLED
-        prepareFrameColorRegions();
-#endif
         dispdev->display();
         delay(50);
         count = count - 1;
@@ -1608,9 +1513,6 @@ void Screen::setFastFramerate()
 {
 #if defined(M5STACK_UNITC6L)
     dispdev->clear();
-#if GRAPHICS_TFT_COLORING_ENABLED
-    prepareFrameColorRegions();
-#endif
     dispdev->display();
 #endif
     // We are about to start a transition so speed up fps
@@ -1822,7 +1724,7 @@ int Screen::handleInputEvent(const InputEvent *event)
         static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
         ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
         setFastFramerate(); // Draw ASAP
-        updateUiFrame(ui);
+        ui->update();
         return 0;
     }
 
@@ -1837,7 +1739,7 @@ int Screen::handleInputEvent(const InputEvent *event)
         static OverlayCallback overlays[] = {graphics::UIRenderer::drawNavigationBar, NotificationRenderer::drawBannercallback};
         ui->setOverlays(overlays, sizeof(overlays) / sizeof(overlays[0]));
         setFastFramerate(); // Draw ASAP
-        updateUiFrame(ui);
+        ui->update();
 
         menuHandler::handleMenuSwitch(dispdev);
         return 0;

src/graphics/Screen.h

@@ -330,11 +330,15 @@ class Screen : public concurrency::OSThread
 
     // Function to allow the AccelerometerThread to set the heading if a sensor provides it
     // Mutex needed?
-    void setHeading(float heading);
+    void setHeading(long _heading)
+    {
+        hasCompass = true;
+        compassHeading = fmod(_heading, 360);
+    }
 
     bool hasHeading() { return hasCompass; }
 
-    float getHeading() { return compassHeading; }
+    long getHeading() { return compassHeading; }
 
     void setEndCalibration(uint32_t _endCalibrationAt) { endCalibrationAt = _endCalibrationAt; }
     uint32_t getEndCalibration() { return endCalibrationAt; }
@@ -788,4 +792,4 @@ extern std::vector<std::string> functionSymbol;
 extern std::string functionSymbolString;
 extern graphics::Screen *screen;
 
-#endif
+#endif

src/graphics/SharedUIDisplay.cpp

@@ -1,20 +1,16 @@
 #include "configuration.h"
 #if HAS_SCREEN
 #include "MeshService.h"
-#include "NodeDB.h"
 #include "RTC.h"
 #include "draw/NodeListRenderer.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTColorRegions.h"
-#include "graphics/TFTPalette.h"
 #include "graphics/draw/UIRenderer.h"
 #include "main.h"
 #include "meshtastic/config.pb.h"
 #include "modules/ExternalNotificationModule.h"
 #include "power.h"
 #include <OLEDDisplay.h>
-#include <cctype>
 #include <graphics/images.h>
 
 namespace graphics
@@ -69,12 +65,6 @@ uint32_t lastBlinkShared = 0;
 bool isMailIconVisible = true;
 uint32_t lastMailBlink = 0;
 
-static inline bool useClockHeaderAccentTheme(uint32_t themeId)
-{
-    return themeId == ThemeID::Pink || themeId == ThemeID::Creamsicle || themeId == ThemeID::MeshtasticGreen ||
-           themeId == ThemeID::ClassicRed || themeId == ThemeID::MonochromeWhite;
-}
-
 // *********************************
 // * Rounded Header when inverted *
 // *********************************
@@ -95,8 +85,7 @@ void drawRoundedHighlight(OLEDDisplay *display, int16_t x, int16_t y, int16_t w,
 // *************************
 // * Common Header Drawing *
 // *************************
-void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *titleStr, bool force_no_invert, bool show_date,
-                      bool transparent_background, bool use_title_color_override, uint16_t title_color_override)
+void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *titleStr, bool force_no_invert, bool show_date)
 {
     constexpr int HEADER_OFFSET_Y = 1;
     y += HEADER_OFFSET_Y;
@@ -111,93 +100,30 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
 
     const int screenW = display->getWidth();
     const int screenH = display->getHeight();
-    const int headerHeight = highlightHeight + 2;
-    const uint16_t headerColorForRoles = getThemeHeaderBg();
-    // Color TFT headers use a fixed dark background + white glyphs.
-    // Keep legacy inverted bitmap behavior only for monochrome displays.
-    const bool useInvertedHeaderStyle = (isInverted && !force_no_invert && !isTFTColoringEnabled() && !transparent_background);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    int statusLeftEndX = 0;
-    int statusRightStartX = screenW;
-    const bool isClockHeader = transparent_background && show_date && (!titleStr || titleStr[0] == '\0');
-    const auto activeThemeId = getActiveTheme().id;
-    const bool useClockHeaderAccent = isClockHeader && useClockHeaderAccentTheme(activeThemeId);
-#endif
-
-    {
-        const uint16_t headerColor = getThemeHeaderBg();
-        const uint16_t headerTextColor = getThemeHeaderText();
-        const uint16_t headerTitleColorForRole = use_title_color_override ? title_color_override : headerTextColor;
-        uint16_t headerStatusColor = getThemeHeaderStatus();
-#if GRAPHICS_TFT_COLORING_ENABLED
-        // Clock frame uses transparent header + date + empty title.
-        // For accent clock themes (Pink/Creamsicle + classic monochrome), tint
-        // status items (battery outline, %, date, mail icon) to the header accent.
-        if (useClockHeaderAccent) {
-            headerStatusColor = getThemeHeaderBg();
-        }
-
-        if (transparent_background) {
-            // Transparent clock headers should inherit whatever body off-color is
-            // already active under the header (important for light/inverted themes).
-            const uint16_t transparentBgColor = resolveTFTOffColorAt(0, headerHeight + 1, getThemeBodyBg());
-            setAndRegisterTFTColorRole(TFTColorRole::HeaderBackground, transparentBgColor, transparentBgColor, 0, 0, screenW,
-                                       headerHeight);
-            setTFTColorRole(TFTColorRole::HeaderTitle, headerTitleColorForRole, transparentBgColor);
-            setTFTColorRole(TFTColorRole::HeaderStatus, headerStatusColor, transparentBgColor);
-        } else if (useInvertedHeaderStyle) {
-            setAndRegisterTFTColorRole(TFTColorRole::HeaderBackground, headerColor, TFTPalette::Black, 0, 0, screenW,
-                                       headerHeight);
-            setTFTColorRole(TFTColorRole::HeaderTitle, headerColor, headerTitleColorForRole);
-            setTFTColorRole(TFTColorRole::HeaderStatus, headerColor, headerStatusColor);
-        } else {
-            setAndRegisterTFTColorRole(TFTColorRole::HeaderBackground, TFTPalette::Black, headerColor, 0, 0, screenW,
-                                       headerHeight);
-            setTFTColorRole(TFTColorRole::HeaderTitle, headerTitleColorForRole, headerColor);
-            setTFTColorRole(TFTColorRole::HeaderStatus, headerStatusColor, headerColor);
-        }
-#endif
 
+    if (!force_no_invert) {
         // === Inverted Header Background ===
-        if (useInvertedHeaderStyle) {
+        if (isInverted) {
             display->setColor(BLACK);
-            display->fillRect(0, 0, screenW, headerHeight);
+            display->fillRect(0, 0, screenW, highlightHeight + 2);
             display->setColor(WHITE);
             drawRoundedHighlight(display, x, y, screenW, highlightHeight, 2);
             display->setColor(BLACK);
         } else {
             display->setColor(BLACK);
-            display->fillRect(0, 0, screenW, headerHeight);
-// Keep the legacy white separator for monochrome displays only when header background is visible.
-#if !GRAPHICS_TFT_COLORING_ENABLED
-            if (!transparent_background) {
-                display->setColor(WHITE);
-                if (currentResolution == ScreenResolution::High) {
-                    display->drawLine(0, 20, screenW, 20);
-                } else {
-                    display->drawLine(0, 14, screenW, 14);
-                }
-            }
-#endif
-        }
-
-        if (transparent_background) {
+            display->fillRect(0, 0, screenW, highlightHeight + 2);
             display->setColor(WHITE);
+            if (currentResolution == ScreenResolution::High) {
+                display->drawLine(0, 20, screenW, 20);
+            } else {
+                display->drawLine(0, 14, screenW, 14);
+            }
         }
 
-#if GRAPHICS_TFT_COLORING_ENABLED
-        // TFT role coloring expects foreground glyph bits to be "set".
-        display->setColor(WHITE);
-#endif
-
         // === Screen Title ===
         const char *headerTitle = titleStr ? titleStr : "";
         const int titleWidth = UIRenderer::measureStringWithEmotes(display, headerTitle);
         const int titleX = (SCREEN_WIDTH - titleWidth) / 2;
-#if GRAPHICS_TFT_COLORING_ENABLED
-        const int titleRegionWidth = titleWidth + (config.display.heading_bold ? 3 : 2);
-        registerTFTColorRegion(TFTColorRole::HeaderTitle, titleX - 1, y, titleRegionWidth, FONT_HEIGHT_SMALL);
-#endif
         UIRenderer::drawStringWithEmotes(display, titleX, y, headerTitle, FONT_HEIGHT_SMALL, 1, config.display.heading_bold);
     }
     display->setTextAlignment(TEXT_ALIGN_LEFT);
@@ -226,17 +152,6 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
 
     bool useHorizontalBattery = (currentResolution == ScreenResolution::High && screenW >= screenH);
     const int textY = y + (highlightHeight - FONT_HEIGHT_SMALL) / 2;
-    bool hasBatteryFillRegion = false;
-    int16_t batteryFillRegionX = 0;
-    int16_t batteryFillRegionY = 0;
-    int16_t batteryFillRegionW = 0;
-    int16_t batteryFillRegionH = 0;
-#if GRAPHICS_TFT_COLORING_ENABLED
-    uint16_t batteryFillColor = getThemeBatteryFillColor(chargePercent);
-    if (useClockHeaderAccent) {
-        batteryFillColor = getThemeHeaderBg();
-    }
-#endif
 
     int batteryX = 1;
     int batteryY = HEADER_OFFSET_Y + 1;
@@ -265,15 +180,6 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
                 display->drawLine(batteryX + 5, batteryY + 12, batteryX + 10, batteryY + 12);
                 int fillWidth = 14 * chargePercent / 100;
                 display->fillRect(batteryX + 1, batteryY + 1, fillWidth, 11);
-#if GRAPHICS_TFT_COLORING_ENABLED
-                if (fillWidth > 0) {
-                    hasBatteryFillRegion = true;
-                    batteryFillRegionX = batteryX + 1;
-                    batteryFillRegionY = batteryY + 1;
-                    batteryFillRegionW = fillWidth;
-                    batteryFillRegionH = 11;
-                }
-#endif
             }
             batteryX += 18; // Icon + 2 pixels
         } else {
@@ -288,41 +194,21 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
                 int fillHeight = 8 * chargePercent / 100;
                 int fillY = batteryY - fillHeight;
                 display->fillRect(batteryX + 1, fillY + 10, 5, fillHeight);
-#if GRAPHICS_TFT_COLORING_ENABLED
-                if (fillHeight > 0) {
-                    hasBatteryFillRegion = true;
-                    batteryFillRegionX = batteryX + 1;
-                    batteryFillRegionY = fillY + 10;
-                    batteryFillRegionW = 5;
-                    batteryFillRegionH = fillHeight;
-                }
-#endif
             }
             batteryX += 9; // Icon + 2 pixels
         }
     }
-#if GRAPHICS_TFT_COLORING_ENABLED
-    statusLeftEndX = batteryX + 2;
-#endif
 
     if (chargePercent != 101) {
         // === Battery % Display ===
         char chargeStr[4];
         snprintf(chargeStr, sizeof(chargeStr), "%d", chargePercent);
         int chargeNumWidth = display->getStringWidth(chargeStr);
-        const int percentWidth = display->getStringWidth("%");
-        const int percentX = batteryX + chargeNumWidth - 1;
         display->drawString(batteryX, textY, chargeStr);
-        display->drawString(percentX, textY, "%");
-#if GRAPHICS_TFT_COLORING_ENABLED
-        statusLeftEndX = percentX + percentWidth + 2;
-#endif
+        display->drawString(batteryX + chargeNumWidth - 1, textY, "%");
         if (isBold) {
             display->drawString(batteryX + 1, textY, chargeStr);
-            display->drawString(percentX + 1, textY, "%");
-#if GRAPHICS_TFT_COLORING_ENABLED
-            statusLeftEndX = percentX + percentWidth + 3;
-#endif
+            display->drawString(batteryX + chargeNumWidth, textY, "%");
         }
     }
 
@@ -367,9 +253,6 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
             timeStrWidth = display->getStringWidth(timeStr);
         }
         timeX = screenW - xOffset - timeStrWidth + 3;
-#if GRAPHICS_TFT_COLORING_ENABLED
-        statusRightStartX = timeX - (useHorizontalBattery ? 22 : 16);
-#endif
 
         // === Show Mail or Mute Icon to the Left of Time ===
         int iconRightEdge = timeX - 2;
@@ -395,7 +278,7 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
                 int iconW = 16, iconH = 12;
                 int iconX = iconRightEdge - iconW;
                 int iconY = textY + (FONT_HEIGHT_SMALL - iconH) / 2 - 1;
-                if (useInvertedHeaderStyle) {
+                if (isInverted && !force_no_invert) {
                     display->setColor(WHITE);
                     display->fillRect(iconX - 1, iconY - 1, iconW + 3, iconH + 2);
                     display->setColor(BLACK);
@@ -410,7 +293,7 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
             } else {
                 int iconX = iconRightEdge - (mail_width - 2);
                 int iconY = textY + (FONT_HEIGHT_SMALL - mail_height) / 2;
-                if (useInvertedHeaderStyle) {
+                if (isInverted && !force_no_invert) {
                     display->setColor(WHITE);
                     display->fillRect(iconX - 1, iconY - 1, mail_width + 2, mail_height + 2);
                     display->setColor(BLACK);
@@ -426,7 +309,7 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
                 int iconX = iconRightEdge - mute_symbol_big_width;
                 int iconY = textY + (FONT_HEIGHT_SMALL - mute_symbol_big_height) / 2;
 
-                if (useInvertedHeaderStyle) {
+                if (isInverted && !force_no_invert) {
                     display->setColor(WHITE);
                     display->fillRect(iconX - 1, iconY - 1, mute_symbol_big_width + 2, mute_symbol_big_height + 2);
                     display->setColor(BLACK);
@@ -440,7 +323,7 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
                 int iconX = iconRightEdge - mute_symbol_width;
                 int iconY = textY + (FONT_HEIGHT_SMALL - mail_height) / 2;
 
-                if (useInvertedHeaderStyle) {
+                if (isInverted && !force_no_invert) {
                     display->setColor(WHITE);
                     display->fillRect(iconX - 1, iconY - 1, mute_symbol_width + 2, mute_symbol_height + 2);
                     display->setColor(BLACK);
@@ -468,9 +351,7 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
     } else {
         // === No Time Available: Mail/Mute Icon Moves to Far Right ===
         int iconRightEdge = screenW - xOffset;
-#if GRAPHICS_TFT_COLORING_ENABLED
-        statusRightStartX = screenW - (useHorizontalBattery ? 22 : 12);
-#endif
+
         bool showMail = false;
 
 #ifndef USE_EINK
@@ -512,16 +393,6 @@ void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *ti
             }
         }
     }
-#endif
-#if GRAPHICS_TFT_COLORING_ENABLED
-    registerTFTColorRegion(TFTColorRole::HeaderStatus, 0, 0, statusLeftEndX, headerHeight);
-    if (statusRightStartX < screenW) {
-        registerTFTColorRegion(TFTColorRole::HeaderStatus, statusRightStartX, 0, screenW - statusRightStartX, headerHeight);
-    }
-    if (hasBatteryFillRegion) {
-        registerTFTColorRegionDirect(batteryFillRegionX, batteryFillRegionY, batteryFillRegionW, batteryFillRegionH,
-                                     batteryFillColor, headerColorForRoles);
-    }
 #endif
     display->setColor(WHITE); // Reset for other UI
 }
@@ -559,23 +430,14 @@ void drawCommonFooter(OLEDDisplay *display, int16_t x, int16_t y)
         return;
 
     const int scale = (currentResolution == ScreenResolution::High) ? 2 : 1;
-    const int footerY = SCREEN_HEIGHT - (1 * scale) - (connection_icon_height * scale);
-    const int footerH = (connection_icon_height * scale) + (2 * scale);
-    const int iconX = 0;
-    const int iconY = SCREEN_HEIGHT - (connection_icon_height * scale);
-    const int iconW = connection_icon_width * scale;
-    const int iconH = connection_icon_height * scale;
-
-#if GRAPHICS_TFT_COLORING_ENABLED
-    // Only tint the link glyph itself on TFT; keep the footer background black.
-    setAndRegisterTFTColorRole(TFTColorRole::ConnectionIcon, TFTPalette::Blue, TFTPalette::Black, iconX, iconY, iconW, iconH);
-#endif
-
     display->setColor(BLACK);
-    display->fillRect(0, footerY, SCREEN_WIDTH, footerH);
+    display->fillRect(0, SCREEN_HEIGHT - (1 * scale) - (connection_icon_height * scale), (connection_icon_width * scale),
+                      (connection_icon_height * scale) + (2 * scale));
     display->setColor(WHITE);
     if (currentResolution == ScreenResolution::High) {
         const int bytesPerRow = (connection_icon_width + 7) / 8;
+        int iconX = 0;
+        int iconY = SCREEN_HEIGHT - (connection_icon_height * 2);
 
         for (int yy = 0; yy < connection_icon_height; ++yy) {
             const uint8_t *rowPtr = connection_icon + yy * bytesPerRow;
@@ -589,127 +451,65 @@ void drawCommonFooter(OLEDDisplay *display, int16_t x, int16_t y)
         }
 
     } else {
-        display->drawXbm(iconX, iconY, connection_icon_width, connection_icon_height, connection_icon);
+        display->drawXbm(0, SCREEN_HEIGHT - connection_icon_height, connection_icon_width, connection_icon_height,
+                         connection_icon);
     }
 }
 
 bool isAllowedPunctuation(char c)
 {
-    switch (c) {
-    case '.':
-    case ',':
-    case '!':
-    case '?':
-    case ';':
-    case ':':
-    case '-':
-    case '_':
-    case '(':
-    case ')':
-    case '[':
-    case ']':
-    case '{':
-    case '}':
-    case '\'':
-    case '"':
-    case '@':
-    case '#':
-    case '$':
-    case '/':
-    case '\\':
-    case '&':
-    case '+':
-    case '=':
-    case '%':
-    case '~':
-    case '^':
-    case ' ':
-        return true;
-    default:
-        return false;
-    }
+    const std::string allowed = ".,!?;:-_()[]{}'\"@#$/\\&+=%~^ ";
+    return allowed.find(c) != std::string::npos;
 }
 
-static inline size_t utf8CodePointLength(unsigned char lead)
+static void replaceAll(std::string &s, const std::string &from, const std::string &to)
 {
-    if ((lead & 0x80) == 0x00) {
-        return 1;
+    if (from.empty())
+        return;
+    size_t pos = 0;
+    while ((pos = s.find(from, pos)) != std::string::npos) {
+        s.replace(pos, from.size(), to);
+        pos += to.size();
     }
-    if ((lead & 0xE0) == 0xC0) {
-        return 2;
-    }
-    if ((lead & 0xF0) == 0xE0) {
-        return 3;
-    }
-    if ((lead & 0xF8) == 0xF0) {
-        return 4;
-    }
-    return 1;
 }
 
 std::string sanitizeString(const std::string &input)
 {
-    static constexpr char kReplacementChar = static_cast<char>(0xBF); // Inverted question mark in ISO-8859-1.
     std::string output;
-    output.reserve(input.size());
     bool inReplacement = false;
-    const size_t inputSize = input.size();
-    size_t i = 0;
-    while (i < inputSize) {
-        const unsigned char byte0 = static_cast<unsigned char>(input[i]);
-        char normalized = '\0';
-        size_t consumed = 0;
-        if (byte0 < 0x80) {
-            normalized = static_cast<char>(byte0);
-            consumed = 1;
-        } else if ((i + 2) < inputSize && byte0 == 0xE2 && static_cast<unsigned char>(input[i + 1]) == 0x80) {
-            // Smart punctuation: ' ' \" \" - -
-            switch (static_cast<unsigned char>(input[i + 2])) {
-            case 0x98:
-            case 0x99:
-                normalized = '\'';
-                consumed = 3;
-                break;
-            case 0x9C:
-            case 0x9D:
-                normalized = '\"';
-                consumed = 3;
-                break;
-            case 0x93:
-            case 0x94:
-                normalized = '-';
-                consumed = 3;
-                break;
-            default:
-                break;
-            }
-        } else if ((i + 1) < inputSize && byte0 == 0xC2 && static_cast<unsigned char>(input[i + 1]) == 0xA0) {
-            // Non-breaking space.
-            normalized = ' ';
-            consumed = 2;
-        }
-        if (consumed == 0) {
-            size_t seqLen = utf8CodePointLength(byte0);
-            if (seqLen > (inputSize - i)) {
-                seqLen = 1;
-            }
+
+    // Make a mutable copy so we can normalize UTF-8 “smart punctuation” into ASCII first.
+    std::string s = input;
+
+    // Curly single quotes: ‘ ’
+    replaceAll(s, "\xE2\x80\x98", "'"); // U+2018
+    replaceAll(s, "\xE2\x80\x99", "'"); // U+2019
+
+    // Curly double quotes: “ ”
+    replaceAll(s, "\xE2\x80\x9C", "\""); // U+201C
+    replaceAll(s, "\xE2\x80\x9D", "\""); // U+201D
+
+    // En dash / Em dash: – —
+    replaceAll(s, "\xE2\x80\x93", "-"); // U+2013
+    replaceAll(s, "\xE2\x80\x94", "-"); // U+2014
+
+    // Non-breaking space
+    replaceAll(s, "\xC2\xA0", " "); // U+00A0
+
+    // Now do your original sanitize pass over the normalized string.
+    for (unsigned char uc : s) {
+        char c = static_cast<char>(uc);
+        if (std::isalnum(uc) || isAllowedPunctuation(c)) {
+            output += c;
+            inReplacement = false;
+        } else {
             if (!inReplacement) {
-                output.push_back(kReplacementChar);
+                output += static_cast<char>(0xBF); // ISO-8859-1 for inverted question mark
                 inReplacement = true;
             }
-            i += seqLen;
-            continue;
         }
-        const unsigned char normalizedUc = static_cast<unsigned char>(normalized);
-        if (std::isalnum(normalizedUc) || isAllowedPunctuation(normalized)) {
-            output.push_back(normalized);
-            inReplacement = false;
-        } else if (!inReplacement) {
-            output.push_back(kReplacementChar);
-            inReplacement = true;
-        }
-        i += consumed;
     }
+
     return output;
 }
 

src/graphics/SharedUIDisplay.h

@@ -1,7 +1,6 @@
 #pragma once
 
 #include <OLEDDisplay.h>
-#include <stdint.h>
 #include <string>
 
 namespace graphics
@@ -53,8 +52,7 @@ void drawRoundedHighlight(OLEDDisplay *display, int16_t x, int16_t y, int16_t w,
 
 // Shared battery/time/mail header
 void drawCommonHeader(OLEDDisplay *display, int16_t x, int16_t y, const char *titleStr = "", bool force_no_invert = false,
-                      bool show_date = false, bool transparent_background = false, bool use_title_color_override = false,
-                      uint16_t title_color_override = 0);
+                      bool show_date = false);
 
 // Shared battery/time/mail header
 void drawCommonFooter(OLEDDisplay *display, int16_t x, int16_t y);

src/graphics/TFTColorRegions.cpp

@@ -1,819 +0,0 @@
-#include "TFTColorRegions.h"
-#include "NodeDB.h"
-#include "TFTPalette.h"
-
-#include <string.h>
-
-namespace graphics
-{
-TFTColorRegion colorRegions[MAX_TFT_COLOR_REGIONS];
-
-namespace
-{
-
-struct TFTRoleColorsBe {
-    uint16_t onColorBe;
-    uint16_t offColorBe;
-};
-
-static uint8_t colorRegionCount = 0;
-static constexpr uint32_t kFnv1aOffsetBasis = 2166136261u;
-static constexpr uint32_t kFnv1aPrime = 16777619u;
-
-static constexpr uint16_t toBe565(uint16_t color)
-{
-    return static_cast<uint16_t>((color >> 8) | (color << 8));
-}
-
-static constexpr bool kRoleIsBody[static_cast<size_t>(TFTColorRole::Count)] = {
-    false, // HeaderBackground
-    false, // HeaderTitle
-    false, // HeaderStatus
-    true,  // SignalBars
-    true,  // ConnectionIcon
-    true,  // UtilizationFill
-    true,  // FavoriteNode
-    true,  // ActionMenuBorder
-    true,  // ActionMenuBody
-    true,  // ActionMenuTitle
-    true,  // FrameMono
-    false, // BootSplash
-    true,  // FavoriteNodeBGHighlight
-    false, // NavigationBar
-    false  // NavigationArrow
-};
-
-static inline bool isBodyColorRole(TFTColorRole role)
-{
-    return kRoleIsBody[static_cast<size_t>(role)];
-}
-
-static inline bool isMonochromeTheme(uint32_t themeId)
-{
-    return themeId == ThemeID::MeshtasticGreen || themeId == ThemeID::ClassicRed || themeId == ThemeID::MonochromeWhite;
-}
-
-static inline uint16_t getMonochromeAccent(uint32_t themeId)
-{
-    return (themeId == ThemeID::MeshtasticGreen) ? TFTPalette::MeshtasticGreen
-           : (themeId == ThemeID::ClassicRed)    ? TFTPalette::ClassicRed
-                                                 : TFTPalette::White;
-}
-
-static inline void replaceColor(uint16_t &value, uint16_t from, uint16_t to)
-{
-    if (value == from) {
-        value = to;
-    }
-}
-
-static inline uint32_t fnv1aAppendByte(uint32_t hash, uint8_t value)
-{
-    return (hash ^ value) * kFnv1aPrime;
-}
-
-static inline uint32_t fnv1aAppendU16(uint32_t hash, uint16_t value)
-{
-    hash = fnv1aAppendByte(hash, static_cast<uint8_t>(value & 0xFF));
-    hash = fnv1aAppendByte(hash, static_cast<uint8_t>((value >> 8) & 0xFF));
-    return hash;
-}
-
-// Compile-time header color overrides (backward-compatible)
-#ifdef TFT_HEADER_BG_COLOR_OVERRIDE
-static constexpr uint16_t kHeaderBackground = TFT_HEADER_BG_COLOR_OVERRIDE;
-#else
-static constexpr uint16_t kHeaderBackground = TFTPalette::DarkGray;
-#endif
-
-#ifdef TFT_HEADER_TITLE_COLOR_OVERRIDE
-static constexpr uint16_t kTitleColor = TFT_HEADER_TITLE_COLOR_OVERRIDE;
-#else
-static constexpr uint16_t kTitleColor = TFTPalette::White;
-#endif
-
-#ifdef TFT_HEADER_STATUS_COLOR_OVERRIDE
-static constexpr uint16_t kStatusColor = TFT_HEADER_STATUS_COLOR_OVERRIDE;
-#else
-static constexpr uint16_t kStatusColor = TFTPalette::White;
-#endif
-
-// Theme definitions
-// Stored in kThemes[] and looked up by matching uiconfig.screen_rgb_color
-// against each entry's .uniqueIdentifier field.
-
-static const TFTThemeDef kThemes[] = {
-
-    // Default Dark (ThemeID::DefaultDark = 0)
-    {
-        ThemeID::DefaultDark, // id
-        "Default Dark",       // name
-        0,                    // uniqueIdentifier
-        // roles[TFTColorRole::Count]
-        {
-            {kHeaderBackground, TFTPalette::Black},    // HeaderBackground
-            {kHeaderBackground, kTitleColor},          // HeaderTitle
-            {kHeaderBackground, kStatusColor},         // HeaderStatus
-            {TFTPalette::Good, TFTPalette::Black},     // SignalBars
-            {TFTPalette::Blue, TFTPalette::Black},     // ConnectionIcon
-            {TFTPalette::Good, TFTPalette::Black},     // UtilizationFill
-            {TFTPalette::Yellow, TFTPalette::Black},   // FavoriteNode
-            {TFTPalette::DarkGray, TFTPalette::Black}, // ActionMenuBorder
-            {TFTPalette::White, TFTPalette::Black},    // ActionMenuBody
-            {TFTPalette::DarkGray, TFTPalette::White}, // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::White},    // FrameMono
-            {TFTPalette::White, TFTPalette::Black},    // BootSplash
-            {TFTPalette::Yellow, TFTPalette::Black},   // FavoriteNodeBGHighlight
-            {kStatusColor, kHeaderBackground},         // NavigationBar  (icon fg, bar bg)
-            {kTitleColor, TFTPalette::Black},          // NavigationArrow (arrow fg, body bg)
-        },
-        TFTPalette::Good,   // batteryFillGood
-        TFTPalette::Medium, // batteryFillMedium
-        TFTPalette::Bad,    // batteryFillBad
-        false,              // fullFrameInvert
-        true,               // visible
-    },
-
-    // Default Light (ThemeID::DefaultLight = 1)
-    {
-        ThemeID::DefaultLight, // id
-        "Default Light",       // name
-        1,                     // uniqueIdentifier
-        {
-            {TFTPalette::LightGray, TFTPalette::Black}, // HeaderBackground
-            {TFTPalette::LightGray, TFTPalette::Black}, // HeaderTitle
-            {TFTPalette::LightGray, TFTPalette::Black}, // HeaderStatus
-            {TFTPalette::Good, TFTPalette::White},      // SignalBars
-            {TFTPalette::Blue, TFTPalette::White},      // ConnectionIcon
-            {TFTPalette::Good, TFTPalette::White},      // UtilizationFill
-            {TFTPalette::Black, TFTPalette::Yellow},    // FavoriteNode
-            {TFTPalette::DarkGray, TFTPalette::White},  // ActionMenuBorder
-            {TFTPalette::Black, TFTPalette::White},     // ActionMenuBody
-            {TFTPalette::DarkGray, TFTPalette::Black},  // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::White},     // FrameMono
-            {TFTPalette::White, TFTPalette::Black},     // BootSplash
-            {TFTPalette::Black, TFTPalette::Yellow},    // FavoriteNodeBGHighlight
-            {TFTPalette::Black, TFTPalette::LightGray}, // NavigationBar  (icon fg, bar bg)
-            {TFTPalette::Black, TFTPalette::White},     // NavigationArrow (arrow fg, body bg)
-        },
-        TFTPalette::Good,   // batteryFillGood
-        TFTPalette::Medium, // batteryFillMedium
-        TFTPalette::Bad,    // batteryFillBad
-        true,               // fullFrameInvert
-        true,               // visible
-    },
-
-    // Christmas (ThemeID::Christmas = 2)
-    {
-        ThemeID::Christmas, // id
-        "Christmas",        // name
-        2,                  // uniqueIdentifier
-        {
-            {TFTPalette::ChristmasRed, TFTPalette::Black},  // HeaderBackground
-            {TFTPalette::ChristmasRed, TFTPalette::Gold},   // HeaderTitle
-            {TFTPalette::ChristmasRed, TFTPalette::Gold},   // HeaderStatus
-            {TFTPalette::ChristmasGreen, TFTPalette::Pine}, // SignalBars
-            {TFTPalette::Gold, TFTPalette::Pine},           // ConnectionIcon
-            {TFTPalette::ChristmasGreen, TFTPalette::Pine}, // UtilizationFill
-            {TFTPalette::Gold, TFTPalette::Pine},           // FavoriteNode
-            {TFTPalette::ChristmasRed, TFTPalette::Pine},   // ActionMenuBorder
-            {TFTPalette::White, TFTPalette::Pine},          // ActionMenuBody
-            {TFTPalette::ChristmasRed, TFTPalette::White},  // ActionMenuTitle
-            {TFTPalette::Pine, TFTPalette::White},          // FrameMono
-            {TFTPalette::White, TFTPalette::ChristmasRed},  // BootSplash
-            {TFTPalette::Gold, TFTPalette::Pine},           // FavoriteNodeBGHighlight
-            {TFTPalette::Gold, TFTPalette::ChristmasRed},   // NavigationBar  (icon fg, bar bg)
-            {TFTPalette::Gold, TFTPalette::Pine},           // NavigationArrow (arrow fg, body bg)
-        },
-        TFTPalette::ChristmasGreen, // batteryFillGood
-        TFTPalette::Gold,           // batteryFillMedium
-        TFTPalette::ChristmasRed,   // batteryFillBad
-        true,                       // fullFrameInvert
-        false,                      // visible
-    },
-
-    // Pink (ThemeID::Pink = 3) light variant
-    {
-        ThemeID::Pink, // id
-        "Pink",        // name
-        3,             // uniqueIdentifier
-        {
-            {TFTPalette::HotPink, TFTPalette::Black},     // HeaderBackground
-            {TFTPalette::HotPink, TFTPalette::White},     // HeaderTitle
-            {TFTPalette::HotPink, TFTPalette::White},     // HeaderStatus
-            {TFTPalette::DeepPink, TFTPalette::PalePink}, // SignalBars
-            {TFTPalette::HotPink, TFTPalette::PalePink},  // ConnectionIcon
-            {TFTPalette::DeepPink, TFTPalette::PalePink}, // UtilizationFill
-            {TFTPalette::Black, TFTPalette::HotPink},     // FavoriteNode
-            {TFTPalette::HotPink, TFTPalette::PalePink},  // ActionMenuBorder
-            {TFTPalette::Black, TFTPalette::PalePink},    // ActionMenuBody
-            {TFTPalette::HotPink, TFTPalette::White},     // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::White},       // FrameMono
-            {TFTPalette::White, TFTPalette::HotPink},     // BootSplash
-            {TFTPalette::Black, TFTPalette::HotPink},     // FavoriteNodeBGHighlight
-            {TFTPalette::White, TFTPalette::HotPink},     // NavigationBar  (icon fg, bar bg)
-            {TFTPalette::HotPink, TFTPalette::PalePink},  // NavigationArrow (arrow fg, body bg)
-        },
-        TFTPalette::DeepPink, // batteryFillGood
-        TFTPalette::HotPink,  // batteryFillMedium
-        TFTPalette::Bad,      // batteryFillBad
-        true,                 // fullFrameInvert
-        true,                 // visible
-    },
-
-    // Blue (ThemeID::Blue = 4) dark variant
-    {
-        ThemeID::Blue, // id
-        "Blue",        // name
-        4,             // uniqueIdentifier
-        {
-            {TFTPalette::DeepBlue, TFTPalette::Black},   // HeaderBackground
-            {TFTPalette::DeepBlue, TFTPalette::White},   // HeaderTitle
-            {TFTPalette::DeepBlue, TFTPalette::SkyBlue}, // HeaderStatus
-            {TFTPalette::SkyBlue, TFTPalette::Navy},     // SignalBars
-            {TFTPalette::SkyBlue, TFTPalette::Navy},     // ConnectionIcon
-            {TFTPalette::SkyBlue, TFTPalette::Navy},     // UtilizationFill
-            {TFTPalette::SkyBlue, TFTPalette::Navy},     // FavoriteNode
-            {TFTPalette::DeepBlue, TFTPalette::Navy},    // ActionMenuBorder
-            {TFTPalette::White, TFTPalette::Navy},       // ActionMenuBody
-            {TFTPalette::DeepBlue, TFTPalette::White},   // ActionMenuTitle
-            {TFTPalette::Navy, TFTPalette::White},       // FrameMono
-            {TFTPalette::White, TFTPalette::DeepBlue},   // BootSplash
-            {TFTPalette::SkyBlue, TFTPalette::Navy},     // FavoriteNodeBGHighlight
-            {TFTPalette::SkyBlue, TFTPalette::DeepBlue}, // NavigationBar  (icon fg, bar bg)
-            {TFTPalette::SkyBlue, TFTPalette::Black},    // NavigationArrow (arrow fg, body bg)
-        },
-        TFTPalette::SkyBlue, // batteryFillGood
-        TFTPalette::Medium,  // batteryFillMedium
-        TFTPalette::Bad,     // batteryFillBad
-        true,                // fullFrameInvert
-        true,                // visible
-    },
-
-    // Creamsicle (ThemeID::Creamsicle = 5)light variant
-    {
-        ThemeID::Creamsicle, // id
-        "Creamsicle",        // name
-        5,                   // uniqueIdentifier
-        {
-            {TFTPalette::CreamOrange, TFTPalette::Black}, // HeaderBackground
-            {TFTPalette::CreamOrange, TFTPalette::White}, // HeaderTitle
-            {TFTPalette::CreamOrange, TFTPalette::White}, // HeaderStatus
-            {TFTPalette::DeepOrange, TFTPalette::Cream},  // SignalBars
-            {TFTPalette::CreamOrange, TFTPalette::Cream}, // ConnectionIcon
-            {TFTPalette::DeepOrange, TFTPalette::Cream},  // UtilizationFill
-            {TFTPalette::Black, TFTPalette::CreamOrange}, // FavoriteNode
-            {TFTPalette::CreamOrange, TFTPalette::Cream}, // ActionMenuBorder
-            {TFTPalette::Black, TFTPalette::Cream},       // ActionMenuBody
-            {TFTPalette::CreamOrange, TFTPalette::White}, // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::White},       // FrameMono
-            {TFTPalette::White, TFTPalette::CreamOrange}, // BootSplash
-            {TFTPalette::Black, TFTPalette::CreamOrange}, // FavoriteNodeBGHighlight
-            {TFTPalette::White, TFTPalette::CreamOrange}, // NavigationBar  (icon fg, bar bg)
-            {TFTPalette::CreamOrange, TFTPalette::White}, // NavigationArrow (arrow fg, body bg)
-        },
-        TFTPalette::DeepOrange, // batteryFillGood
-        TFTPalette::Gold,       // batteryFillMedium
-        TFTPalette::Bad,        // batteryFillBad
-        true,                   // fullFrameInvert
-        true,                   // visible
-    },
-
-    // Meshtastic Green (ThemeID::MeshtasticGreen = 6) classic monochrome
-    // Pure single-color-on-black look.  Every role maps foreground pixels to
-    // the theme color and background pixels to Black.
-    {
-        ThemeID::MeshtasticGreen, // id
-        "Meshtastic Green",       // name
-        6,                        // uniqueIdentifier
-        {
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // HeaderBackground
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // HeaderTitle
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // HeaderStatus
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // SignalBars
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // ConnectionIcon
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // UtilizationFill
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // FavoriteNode
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // ActionMenuBorder
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // ActionMenuBody
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::MeshtasticGreen}, // FrameMono (bodyBg, bodyFg)
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // BootSplash
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // FavoriteNodeBGHighlight
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // NavigationBar
-            {TFTPalette::MeshtasticGreen, TFTPalette::Black}, // NavigationArrow
-        },
-        TFTPalette::Black, // batteryFillGood
-        TFTPalette::Black, // batteryFillMedium
-        TFTPalette::Black, // batteryFillBad
-        true,              // fullFrameInvert
-        true,              // visible
-    },
-
-    // Classic Red (ThemeID::ClassicRed = 7) classic monochrome
-    {
-        ThemeID::ClassicRed, // id
-        "Classic Red",       // name
-        7,                   // uniqueIdentifier
-        {
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // HeaderBackground
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // HeaderTitle
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // HeaderStatus
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // SignalBars
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // ConnectionIcon
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // UtilizationFill
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // FavoriteNode
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // ActionMenuBorder
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // ActionMenuBody
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::ClassicRed}, // FrameMono (bodyBg, bodyFg)
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // BootSplash
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // FavoriteNodeBGHighlight
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // NavigationBar
-            {TFTPalette::ClassicRed, TFTPalette::Black}, // NavigationArrow
-        },
-        TFTPalette::Black, // batteryFillGood
-        TFTPalette::Black, // batteryFillMedium
-        TFTPalette::Black, // batteryFillBad
-        true,              // fullFrameInvert
-        true,              // visible
-    },
-
-    // Monochrome White (ThemeID::MonochromeWhite = 8) classic monochrome
-    {
-        ThemeID::MonochromeWhite, // id
-        "Monochrome White",       // name
-        8,                        // uniqueIdentifier
-        {
-            {TFTPalette::White, TFTPalette::Black}, // HeaderBackground
-            {TFTPalette::White, TFTPalette::Black}, // HeaderTitle
-            {TFTPalette::White, TFTPalette::Black}, // HeaderStatus
-            {TFTPalette::White, TFTPalette::Black}, // SignalBars
-            {TFTPalette::White, TFTPalette::Black}, // ConnectionIcon
-            {TFTPalette::White, TFTPalette::Black}, // UtilizationFill
-            {TFTPalette::White, TFTPalette::Black}, // FavoriteNode
-            {TFTPalette::White, TFTPalette::Black}, // ActionMenuBorder
-            {TFTPalette::White, TFTPalette::Black}, // ActionMenuBody
-            {TFTPalette::White, TFTPalette::Black}, // ActionMenuTitle
-            {TFTPalette::Black, TFTPalette::White}, // FrameMono (bodyBg, bodyFg)
-            {TFTPalette::White, TFTPalette::Black}, // BootSplash
-            {TFTPalette::White, TFTPalette::Black}, // FavoriteNodeBGHighlight
-            {TFTPalette::White, TFTPalette::Black}, // NavigationBar
-            {TFTPalette::White, TFTPalette::Black}, // NavigationArrow
-        },
-        TFTPalette::Black, // batteryFillGood
-        TFTPalette::Black, // batteryFillMedium
-        TFTPalette::Black, // batteryFillBad
-        true,              // fullFrameInvert
-        true,              // visible
-    },
-};
-
-static constexpr size_t kInternalThemeCount = sizeof(kThemes) / sizeof(kThemes[0]);
-
-// Resolve the kThemes[] index for the currently persisted theme.  Called at
-// boot (indirectly via getActiveTheme()) and whenever the active theme is
-// queried, so uiconfig.screen_rgb_color remains the single source of truth.
-// Matches against .uniqueIdentifier - that's the field whose value is stored
-// in the user's config.  Falls back to 0 (DefaultDark) if no match is found,
-// which gracefully handles removed or retired themes.
-static inline size_t resolveThemeIndex()
-{
-    const uint32_t savedIdentifier = uiconfig.screen_rgb_color & 0x1F;
-    for (size_t i = 0; i < kInternalThemeCount; i++) {
-        if (kThemes[i].uniqueIdentifier == savedIdentifier)
-            return i;
-    }
-    return 0; // Default Dark fallback
-}
-
-static inline bool normalizeRegion(int16_t &x, int16_t &y, int16_t &width, int16_t &height)
-{
-    if (width <= 0 || height <= 0) {
-        return false;
-    }
-
-    if (x < 0) {
-        width += x;
-        x = 0;
-    }
-    if (y < 0) {
-        height += y;
-        y = 0;
-    }
-
-    return width > 0 && height > 0;
-}
-
-static inline void appendColorRegion(int16_t x, int16_t y, int16_t width, int16_t height, uint16_t onColorBe, uint16_t offColorBe)
-{
-    // Keep the last slot permanently disabled as a sentinel for ST7789 scans.
-    // This leaves MAX_TFT_COLOR_REGIONS - 1 usable entries.
-    if (colorRegionCount >= MAX_TFT_COLOR_REGIONS - 1) {
-        memmove(&colorRegions[0], &colorRegions[1], sizeof(TFTColorRegion) * (MAX_TFT_COLOR_REGIONS - 2));
-        colorRegionCount = MAX_TFT_COLOR_REGIONS - 2;
-    }
-
-    TFTColorRegion &region = colorRegions[colorRegionCount++];
-    region.x = x;
-    region.y = y;
-    region.width = width;
-    region.height = height;
-    region.onColorBe = onColorBe;
-    region.offColorBe = offColorBe;
-    region.enabled = true;
-
-    // Keep one disabled sentinel after the active range for ST7789 countColorRegions().
-    if (colorRegionCount < MAX_TFT_COLOR_REGIONS) {
-        colorRegions[colorRegionCount].enabled = false;
-    }
-    colorRegions[MAX_TFT_COLOR_REGIONS - 1].enabled = false;
-}
-
-// Current working role colors (big-endian).  Initialised to Dark defaults;
-// call loadThemeDefaults() after boot / theme change to refresh.
-static TFTRoleColorsBe roleColors[static_cast<size_t>(TFTColorRole::Count)] = {
-    {toBe565(kHeaderBackground), toBe565(TFTPalette::Black)},    // HeaderBackground
-    {toBe565(kHeaderBackground), toBe565(kTitleColor)},          // HeaderTitle
-    {toBe565(kHeaderBackground), toBe565(kStatusColor)},         // HeaderStatus
-    {toBe565(TFTPalette::Good), toBe565(TFTPalette::Black)},     // SignalBars
-    {toBe565(TFTPalette::Blue), toBe565(TFTPalette::Black)},     // ConnectionIcon
-    {toBe565(TFTPalette::Good), toBe565(TFTPalette::Black)},     // UtilizationFill
-    {toBe565(TFTPalette::Yellow), toBe565(TFTPalette::Black)},   // FavoriteNode
-    {toBe565(TFTPalette::DarkGray), toBe565(TFTPalette::Black)}, // ActionMenuBorder
-    {toBe565(TFTPalette::White), toBe565(TFTPalette::Black)},    // ActionMenuBody
-    {toBe565(TFTPalette::DarkGray), toBe565(TFTPalette::White)}, // ActionMenuTitle
-    {toBe565(TFTPalette::Black), toBe565(TFTPalette::White)},    // FrameMono
-    {toBe565(TFTPalette::White), toBe565(TFTPalette::Black)},    // BootSplash
-    {toBe565(TFTPalette::Yellow), toBe565(TFTPalette::Black)},   // FavoriteNodeBGHighlight
-    {toBe565(kStatusColor), toBe565(kHeaderBackground)},         // NavigationBar
-    {toBe565(kTitleColor), toBe565(TFTPalette::Black)}           // NavigationArrow
-};
-
-} // namespace
-
-// Theme accessors
-
-const TFTThemeDef &getActiveTheme()
-{
-    return kThemes[resolveThemeIndex()];
-}
-
-// Visible-theme accessors
-// These iterate only themes flagged .visible = true, preserving kThemes[]
-// order.  Menu code should use these so hidden themes don't appear in the
-// picker while still applying correctly if their ID is persisted.
-
-size_t getVisibleThemeCount()
-{
-    size_t count = 0;
-    for (size_t i = 0; i < kInternalThemeCount; i++) {
-        if (kThemes[i].visible)
-            count++;
-    }
-    return count;
-}
-
-const TFTThemeDef &getVisibleThemeByIndex(size_t visibleIndex)
-{
-    size_t seen = 0;
-    for (size_t i = 0; i < kInternalThemeCount; i++) {
-        if (!kThemes[i].visible)
-            continue;
-        if (seen == visibleIndex)
-            return kThemes[i];
-        seen++;
-    }
-    // Fallback: return first theme (never trust a bad index).
-    return kThemes[0];
-}
-
-size_t getActiveVisibleThemeIndex()
-{
-    const size_t active = resolveThemeIndex();
-    if (!kThemes[active].visible)
-        return SIZE_MAX;
-    size_t visibleIdx = 0;
-    for (size_t i = 0; i < active; i++) {
-        if (kThemes[i].visible)
-            visibleIdx++;
-    }
-    return visibleIdx;
-}
-
-uint16_t getThemeHeaderBg()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-#ifdef TFT_HEADER_BG_COLOR_OVERRIDE
-    return TFT_HEADER_BG_COLOR_OVERRIDE;
-#else
-    return kThemes[resolveThemeIndex()].roles[static_cast<size_t>(TFTColorRole::HeaderBackground)].onColor;
-#endif
-#else
-    return TFTPalette::DarkGray;
-#endif
-}
-
-uint16_t getThemeHeaderText()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-#ifdef TFT_HEADER_TITLE_COLOR_OVERRIDE
-    return TFT_HEADER_TITLE_COLOR_OVERRIDE;
-#else
-    return kThemes[resolveThemeIndex()].roles[static_cast<size_t>(TFTColorRole::HeaderTitle)].offColor;
-#endif
-#else
-    return TFTPalette::White;
-#endif
-}
-
-uint16_t getThemeHeaderStatus()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-#ifdef TFT_HEADER_STATUS_COLOR_OVERRIDE
-    return TFT_HEADER_STATUS_COLOR_OVERRIDE;
-#else
-    return kThemes[resolveThemeIndex()].roles[static_cast<size_t>(TFTColorRole::HeaderStatus)].offColor;
-#endif
-#else
-    return TFTPalette::White;
-#endif
-}
-
-uint16_t getThemeBodyBg()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    return kThemes[resolveThemeIndex()].roles[static_cast<size_t>(TFTColorRole::FrameMono)].onColor;
-#else
-    return TFTPalette::Black;
-#endif
-}
-
-uint16_t getThemeBodyFg()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    return kThemes[resolveThemeIndex()].roles[static_cast<size_t>(TFTColorRole::FrameMono)].offColor;
-#else
-    return TFTPalette::White;
-#endif
-}
-
-bool isThemeFullFrameInvert()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    return kThemes[resolveThemeIndex()].fullFrameInvert;
-#else
-    return false;
-#endif
-}
-
-uint16_t getThemeBatteryFillColor(int batteryPercent)
-{
-    const TFTThemeDef &theme = kThemes[resolveThemeIndex()];
-    if (batteryPercent <= 20) {
-        return theme.batteryFillBad;
-    }
-    if (batteryPercent <= 50) {
-        return theme.batteryFillMedium;
-    }
-    return theme.batteryFillGood;
-}
-
-void loadThemeDefaults()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    const TFTThemeDef &theme = kThemes[resolveThemeIndex()];
-    for (uint8_t i = 0; i < static_cast<uint8_t>(TFTColorRole::Count); i++) {
-        roleColors[i].onColorBe = toBe565(theme.roles[i].onColor);
-        roleColors[i].offColorBe = toBe565(theme.roles[i].offColor);
-    }
-#endif
-}
-
-// Role color assignment with theme-aware transforms
-
-void setTFTColorRole(TFTColorRole role, uint16_t onColor, uint16_t offColor)
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    return;
-#endif
-
-    const uint8_t index = static_cast<uint8_t>(role);
-    if (index >= static_cast<uint8_t>(TFTColorRole::Count)) {
-        return;
-    }
-
-    const uint32_t themeId = uiconfig.screen_rgb_color & 0x1F;
-    const bool isHighlightRole = (role == TFTColorRole::FavoriteNode || role == TFTColorRole::FavoriteNodeBGHighlight);
-    const bool isBodyRole = !isHighlightRole && isBodyColorRole(role);
-
-    // Classic monochrome themes collapse all non-black accents into one tone.
-    if (isMonochromeTheme(themeId)) {
-        if (onColor != TFTPalette::Black) {
-            onColor = getMonochromeAccent(themeId);
-        }
-    } else {
-        switch (themeId) {
-        case ThemeID::DefaultLight:
-            if (isHighlightRole) {
-                // High-contrast highlight chips on light UI.
-                onColor = TFTPalette::Black;
-                offColor = TFTPalette::Yellow;
-            } else if (isBodyRole) {
-                // Invert body colors for readability on white frames.
-                if (offColor == TFTPalette::Black && role != TFTColorRole::ActionMenuTitle) {
-                    offColor = TFTPalette::White;
-                }
-                replaceColor(onColor, TFTPalette::White, TFTPalette::Black);
-            }
-            break;
-        case ThemeID::Christmas:
-            if (isHighlightRole || isBodyRole) {
-                replaceColor(onColor, TFTPalette::Yellow, TFTPalette::Gold);
-                replaceColor(offColor, TFTPalette::Black, TFTPalette::Pine);
-            }
-            break;
-        case ThemeID::Pink:
-            if (isHighlightRole) {
-                onColor = TFTPalette::Black;
-                offColor = TFTPalette::HotPink;
-            } else if (isBodyRole) {
-                replaceColor(offColor, TFTPalette::Black, TFTPalette::PalePink);
-                replaceColor(onColor, TFTPalette::White, TFTPalette::Black);
-                replaceColor(onColor, TFTPalette::Yellow, TFTPalette::DeepPink);
-            }
-            break;
-        case ThemeID::Creamsicle:
-            if (isHighlightRole) {
-                onColor = TFTPalette::Black;
-                offColor = TFTPalette::CreamOrange;
-            } else if (isBodyRole) {
-                replaceColor(offColor, TFTPalette::Black, TFTPalette::Cream);
-                replaceColor(onColor, TFTPalette::White, TFTPalette::Black);
-                replaceColor(onColor, TFTPalette::Yellow, TFTPalette::DeepOrange);
-            }
-            break;
-        case ThemeID::Blue:
-            if (isHighlightRole || isBodyRole) {
-                replaceColor(onColor, TFTPalette::Yellow, TFTPalette::SkyBlue);
-                replaceColor(offColor, TFTPalette::Black, TFTPalette::Navy);
-            }
-            break;
-        default:
-            break;
-        }
-    }
-
-    roleColors[index].onColorBe = toBe565(onColor);
-    roleColors[index].offColorBe = toBe565(offColor);
-}
-
-// Region registration
-
-void registerTFTColorRegion(TFTColorRole role, int16_t x, int16_t y, int16_t width, int16_t height)
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    return;
-#endif
-
-    const uint8_t roleIndex = static_cast<uint8_t>(role);
-    if (roleIndex >= static_cast<uint8_t>(TFTColorRole::Count)) {
-        return;
-    }
-
-    if (!normalizeRegion(x, y, width, height)) {
-        return;
-    }
-
-    const TFTRoleColorsBe &colors = roleColors[roleIndex];
-    appendColorRegion(x, y, width, height, colors.onColorBe, colors.offColorBe);
-}
-
-void setAndRegisterTFTColorRole(TFTColorRole role, uint16_t onColor, uint16_t offColor, int16_t x, int16_t y, int16_t width,
-                                int16_t height)
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    (void)role;
-    (void)onColor;
-    (void)offColor;
-    (void)x;
-    (void)y;
-    (void)width;
-    (void)height;
-    return;
-#else
-    setTFTColorRole(role, onColor, offColor);
-    registerTFTColorRegion(role, x, y, width, height);
-#endif
-}
-
-void registerTFTColorRegionDirect(int16_t x, int16_t y, int16_t width, int16_t height, uint16_t onColor, uint16_t offColor)
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    return;
-#endif
-
-    if (!normalizeRegion(x, y, width, height))
-        return;
-
-    appendColorRegion(x, y, width, height, toBe565(onColor), toBe565(offColor));
-}
-
-void registerTFTActionMenuRegions(int16_t boxLeft, int16_t boxTop, int16_t boxWidth, int16_t boxHeight)
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    (void)boxLeft;
-    (void)boxTop;
-    (void)boxWidth;
-    (void)boxHeight;
-    return;
-#else
-    // Use theme-appropriate menu colors.
-    const TFTThemeDef &theme = kThemes[resolveThemeIndex()];
-    const TFTThemeRoleColor &menuBody = theme.roles[static_cast<size_t>(TFTColorRole::ActionMenuBody)];
-    const TFTThemeRoleColor &menuBorder = theme.roles[static_cast<size_t>(TFTColorRole::ActionMenuBorder)];
-
-    // Fill role includes a 1px shadow guard so stale frame edges are overwritten uniformly.
-    setAndRegisterTFTColorRole(TFTColorRole::ActionMenuBody, menuBody.onColor, menuBody.offColor, boxLeft - 1, boxTop - 1,
-                               boxWidth + 2, boxHeight + 2);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBody, boxLeft, boxTop - 2, boxWidth, 1);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBody, boxLeft, boxTop + boxHeight + 1, boxWidth, 1);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBody, boxLeft - 2, boxTop, 1, boxHeight);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBody, boxLeft + boxWidth + 1, boxTop, 1, boxHeight);
-
-    setAndRegisterTFTColorRole(TFTColorRole::ActionMenuBorder, menuBorder.onColor, menuBorder.offColor, boxLeft, boxTop, boxWidth,
-                               1);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBorder, boxLeft, boxTop + boxHeight - 1, boxWidth, 1);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBorder, boxLeft, boxTop, 1, boxHeight);
-    registerTFTColorRegion(TFTColorRole::ActionMenuBorder, boxLeft + boxWidth - 1, boxTop, 1, boxHeight);
-#endif
-}
-
-// Frame signature & utilities
-
-uint32_t getTFTColorFrameSignature()
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    return 0;
-#else
-    uint32_t hash = kFnv1aOffsetBasis;
-    hash = fnv1aAppendByte(hash, colorRegionCount);
-    for (uint8_t i = 0; i < colorRegionCount; i++) {
-        const TFTColorRegion &r = colorRegions[i];
-        hash = fnv1aAppendU16(hash, static_cast<uint16_t>(r.x));
-        hash = fnv1aAppendU16(hash, static_cast<uint16_t>(r.y));
-        hash = fnv1aAppendU16(hash, static_cast<uint16_t>(r.width));
-        hash = fnv1aAppendU16(hash, static_cast<uint16_t>(r.height));
-        hash = fnv1aAppendU16(hash, r.onColorBe);
-        hash = fnv1aAppendU16(hash, r.offColorBe);
-    }
-
-    return hash;
-#endif
-}
-
-uint8_t getTFTColorRegionCount()
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    return 0;
-#else
-    return colorRegionCount;
-#endif
-}
-
-void clearTFTColorRegions()
-{
-    for (uint8_t i = 0; i < colorRegionCount; i++) {
-        colorRegions[i].enabled = false;
-    }
-    if (colorRegionCount < MAX_TFT_COLOR_REGIONS) {
-        colorRegions[colorRegionCount].enabled = false;
-    }
-    colorRegionCount = 0;
-}
-
-uint16_t resolveTFTColorPixel(int16_t x, int16_t y, bool isset, uint16_t defaultOnColor, uint16_t defaultOffColor)
-{
-    for (int i = static_cast<int>(colorRegionCount) - 1; i >= 0; i--) {
-        const TFTColorRegion &r = colorRegions[i];
-        if (x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height) {
-            return isset ? r.onColorBe : r.offColorBe;
-        }
-    }
-    return isset ? defaultOnColor : defaultOffColor;
-}
-
-uint16_t resolveTFTOffColorAt(int16_t x, int16_t y, uint16_t defaultOffColor)
-{
-#if !GRAPHICS_TFT_COLORING_ENABLED
-    (void)x;
-    (void)y;
-    return defaultOffColor;
-#else
-    const uint16_t defaultOffBe = toBe565(defaultOffColor);
-    const uint16_t sampledBe = resolveTFTColorPixel(x, y, false, defaultOffBe, defaultOffBe);
-    return static_cast<uint16_t>((sampledBe >> 8) | (sampledBe << 8));
-#endif
-}
-
-} // namespace graphics

src/graphics/TFTColorRegions.h

@@ -1,163 +0,0 @@
-#pragma once
-
-#include "configuration.h"
-#include <stdint.h>
-
-namespace graphics
-{
-
-struct TFTColorRegion {
-    int16_t x;
-    int16_t y;
-    int16_t width;
-    int16_t height;
-    uint16_t onColorBe;
-    uint16_t offColorBe;
-    // Required by ST7789 driver: it scans until the first disabled entry.
-    bool enabled = false;
-};
-
-static constexpr size_t MAX_TFT_COLOR_REGIONS = 48;
-extern TFTColorRegion colorRegions[MAX_TFT_COLOR_REGIONS];
-
-enum class TFTColorRole : uint8_t {
-    HeaderBackground = 0,
-    HeaderTitle,
-    HeaderStatus,
-    SignalBars,
-    ConnectionIcon,
-    UtilizationFill,
-    FavoriteNode,
-    ActionMenuBorder,
-    ActionMenuBody,
-    ActionMenuTitle,
-    FrameMono,
-    BootSplash,
-    FavoriteNodeBGHighlight,
-    NavigationBar,
-    NavigationArrow,
-    Count
-};
-
-#if HAS_TFT || defined(ST7701_CS) || defined(ST7735_CS) || defined(ILI9341_DRIVER) || defined(ILI9342_DRIVER) ||                 \
-    defined(ST7789_CS) || defined(HX8357_CS) || defined(USE_ST7789) || defined(ILI9488_CS) || defined(ST7796_CS) ||              \
-    defined(USE_ST7796) || defined(HACKADAY_COMMUNICATOR)
-#define GRAPHICS_TFT_COLORING_ENABLED 1
-#else
-#define GRAPHICS_TFT_COLORING_ENABLED 0
-#endif
-
-static constexpr bool kTFTColoringEnabled = GRAPHICS_TFT_COLORING_ENABLED != 0;
-constexpr bool isTFTColoringEnabled()
-{
-    return kTFTColoringEnabled;
-}
-
-void setTFTColorRole(TFTColorRole role, uint16_t onColor, uint16_t offColor);
-void registerTFTColorRegion(TFTColorRole role, int16_t x, int16_t y, int16_t width, int16_t height);
-// Convenience helper for the common "set role then register one region" flow.
-void setAndRegisterTFTColorRole(TFTColorRole role, uint16_t onColor, uint16_t offColor, int16_t x, int16_t y, int16_t width,
-                                int16_t height);
-// Register a region using explicit colors (no role lookup). Use when the
-// color comes from a theme field rather than a role (e.g. battery fill).
-void registerTFTColorRegionDirect(int16_t x, int16_t y, int16_t width, int16_t height, uint16_t onColor, uint16_t offColor);
-void registerTFTActionMenuRegions(int16_t boxLeft, int16_t boxTop, int16_t boxWidth, int16_t boxHeight);
-uint32_t getTFTColorFrameSignature();
-uint8_t getTFTColorRegionCount();
-void clearTFTColorRegions();
-uint16_t resolveTFTColorPixel(int16_t x, int16_t y, bool isset, uint16_t defaultOnColor, uint16_t defaultOffColor);
-// Resolve effective region-mapped OFF color at a coordinate in native-endian RGB565.
-uint16_t resolveTFTOffColorAt(int16_t x, int16_t y, uint16_t defaultOffColor);
-
-// -- Theme engine ------------------------------------------------------
-// Each theme has four fields that work together:
-//
-//   id               - ThemeID:: constant, used for in-code references.
-//   name             - human-readable label shown in the theme picker.
-//   uniqueIdentifier - the stable numeric value persisted to
-//                      uiconfig.screen_rgb_color and restored at boot.
-//                      This is a CONTRACT with saved configs on disk - once
-//                      assigned, never reuse or renumber, even if the theme is
-//                      deleted or the kThemes[] array is reordered.
-//   visible          - controls whether a theme appears in the picker menu.
-//                      Hidden themes can still be restored and applied if their
-//                      uniqueIdentifier is persisted.
-//
-// Display order in the menu is controlled by kThemes[] array order among
-// themes where visible == true, NOT by any numeric value above.
-//
-// To add a new theme:
-//   1. Add a unique constant in ThemeID below (next unused value).
-//   2. Add a kThemes[] entry at the desired menu position, with a unique
-//      uniqueIdentifier that has never been used by any prior theme.
-//   3. Set visible=true if it should appear in the picker.
-//
-// To retire a theme without breaking saved configs:
-//   - Preferred: keep the entry and set visible=false so existing saved
-//     uniqueIdentifier values still resolve to the same theme.
-//   - If you remove the entry, resolveThemeIndex() falls back to DefaultDark
-//     when the persisted uniqueIdentifier no longer matches any theme.
-//   - Do NOT reuse a retired uniqueIdentifier for a future theme.
-namespace ThemeID
-{
-constexpr uint32_t DefaultDark = 0;
-constexpr uint32_t DefaultLight = 1;
-constexpr uint32_t Christmas = 2;
-constexpr uint32_t Pink = 3;
-constexpr uint32_t Blue = 4;
-constexpr uint32_t Creamsicle = 5;
-constexpr uint32_t MeshtasticGreen = 6;
-constexpr uint32_t ClassicRed = 7;
-constexpr uint32_t MonochromeWhite = 8;
-} // namespace ThemeID
-
-// Per-role color pair stored in native (little-endian) RGB565 format.
-struct TFTThemeRoleColor {
-    uint16_t onColor;
-    uint16_t offColor;
-};
-
-// Complete theme definition.
-struct TFTThemeDef {
-    uint32_t id;               // ThemeID constant - in-code identifier for this theme.
-    const char *name;          // Human-readable label shown in the theme picker.
-    uint32_t uniqueIdentifier; // Stable persisted value copied into uiconfig.screen_rgb_color.
-                               // Never reuse or renumber - see file-level notes above.
-    TFTThemeRoleColor roles[static_cast<size_t>(TFTColorRole::Count)];
-    uint16_t batteryFillGood;
-    uint16_t batteryFillMedium;
-    uint16_t batteryFillBad;
-    bool fullFrameInvert; // Apply full-frame FrameMono inversion (ST7789 light themes)
-    bool visible;         // Show in the theme picker menu.  Hidden themes still apply
-                          // correctly if their uniqueIdentifier is persisted (dev/legacy themes).
-};
-
-// Count of themes whose .visible flag is true.  Use this when building menus.
-size_t getVisibleThemeCount();
-
-// Access the Nth visible theme (0 .. getVisibleThemeCount()-1).  Hidden themes
-// are skipped, preserving kThemes[] order among the visible entries.
-const TFTThemeDef &getVisibleThemeByIndex(size_t visibleIndex);
-
-// Return the theme that matches uiconfig.screen_rgb_color (falls back to Dark).
-const TFTThemeDef &getActiveTheme();
-
-// Return the visible-theme index for the currently active theme, or SIZE_MAX
-// if the active theme is hidden (so menus can show "no selection").
-size_t getActiveVisibleThemeIndex();
-
-// Convenience accessors - safe to call even when coloring is compiled out.
-uint16_t getThemeHeaderBg();
-uint16_t getThemeHeaderText();
-uint16_t getThemeHeaderStatus();
-uint16_t getThemeBodyBg();
-uint16_t getThemeBodyFg();
-bool isThemeFullFrameInvert();
-uint16_t getThemeBatteryFillColor(int batteryPercent);
-
-// Reinitialise default roleColors from the active theme.  Call after a
-// theme change so that any role registered without a prior setTFTColorRole()
-// picks up theme-appropriate defaults.
-void loadThemeDefaults();
-
-} // namespace graphics

src/graphics/TFTDisplay.cpp

@@ -16,6 +16,12 @@
 extern SX1509 gpioExtender;
 #endif
 
+#ifdef TFT_MESH_OVERRIDE
+uint16_t TFT_MESH = TFT_MESH_OVERRIDE;
+#else
+uint16_t TFT_MESH = COLOR565(0x67, 0xEA, 0x94);
+#endif
+
 #if defined(ST7735S)
 #include <LovyanGFX.hpp> // Graphics and font library for ST7735 driver chip
 
@@ -1145,9 +1151,7 @@ static LGFX *tft = nullptr;
 #endif
 
 #include "SPILock.h"
-#include "TFTColorRegions.h"
 #include "TFTDisplay.h"
-#include "TFTPalette.h"
 #include <SPI.h>
 
 #ifdef UNPHONE
@@ -1157,25 +1161,6 @@ extern unPhone unphone;
 
 GpioPin *TFTDisplay::backlightEnable = NULL;
 
-namespace
-{
-static constexpr uint8_t kFullRepaintChunkRows = 8;
-
-static inline uint16_t getThemeDefaultOnColor()
-{
-    return graphics::TFTPalette::White;
-}
-
-static inline uint16_t getThemeDefaultOffColor()
-{
-#if GRAPHICS_TFT_COLORING_ENABLED
-    return graphics::getThemeBodyBg();
-#else
-    return TFT_BLACK;
-#endif
-}
-} // namespace
-
 TFTDisplay::TFTDisplay(uint8_t address, int sda, int scl, OLEDDISPLAY_GEOMETRY geometry, HW_I2C i2cBus)
 {
     LOG_DEBUG("TFTDisplay!");
@@ -1215,15 +1200,14 @@ TFTDisplay::~TFTDisplay()
         free(linePixelBuffer);
         linePixelBuffer = nullptr;
     }
-    if (repaintChunkBuffer != nullptr) {
-        free(repaintChunkBuffer);
-        repaintChunkBuffer = nullptr;
-    }
 }
 
 // Write the buffer to the display memory
 void TFTDisplay::display(bool fromBlank)
 {
+    if (fromBlank)
+        tft->fillScreen(TFT_BLACK);
+
     concurrency::LockGuard g(spiLock);
 
     uint32_t x, y;
@@ -1232,70 +1216,12 @@ void TFTDisplay::display(bool fromBlank)
     uint32_t x_FirstPixelUpdate;
     uint32_t x_LastPixelUpdate;
     bool isset, dblbuf_isset;
-    uint16_t colorTftWhite, colorTftBlack;
+    uint16_t colorTftMesh, colorTftBlack;
     bool somethingChanged = false;
 
-    // Theme defaults for non-role pixels.
-    const uint16_t defaultOnColor = getThemeDefaultOnColor();
-    const uint16_t defaultOffColor = getThemeDefaultOffColor();
-    static uint16_t lastDefaultOnColor = 0;
-    static uint16_t lastDefaultOffColor = 0;
-    static bool haveLastDefaults = false;
-    const bool themeDefaultsChanged =
-        !haveLastDefaults || (defaultOnColor != lastDefaultOnColor) || (defaultOffColor != lastDefaultOffColor);
-    const bool forceFullRepaint = fromBlank || themeDefaultsChanged;
-
-    // If theme defaults changed, reset panel background immediately so stale pixels don't linger.
-    if (forceFullRepaint) {
-        tft->fillScreen(defaultOffColor);
-    }
-
-    colorTftWhite = (defaultOnColor >> 8) | ((defaultOnColor & 0xFF) << 8);
-    colorTftBlack = (defaultOffColor >> 8) | ((defaultOffColor & 0xFF) << 8);
-
-#if GRAPHICS_TFT_COLORING_ENABLED
-    static uint32_t lastColorFrameSignature = 0;
-    const bool hasColorRegions = graphics::getTFTColorRegionCount() > 0;
-    const uint32_t colorFrameSignature = graphics::getTFTColorFrameSignature();
-    const bool forceFullColorRepaint = forceFullRepaint || (colorFrameSignature != lastColorFrameSignature);
-
-    // When region roles/layout changed, color can differ even with identical monochrome glyph bits.
-    // Repaint full frame only for those frames, then return to diff-based updates.
-    if (forceFullColorRepaint) {
-        for (uint32_t yStart = 0; yStart < displayHeight; yStart += kFullRepaintChunkRows) {
-            const uint32_t rowsThisChunk = min<uint32_t>(kFullRepaintChunkRows, displayHeight - yStart);
-            for (uint32_t row = 0; row < rowsThisChunk; row++) {
-                y = yStart + row;
-                y_byteIndex = (y / 8) * displayWidth;
-                y_byteMask = (1 << (y & 7));
-
-                uint16_t *chunkRow = repaintChunkBuffer + (row * displayWidth);
-                for (x = 0; x < displayWidth; x++) {
-                    isset = (buffer[x + y_byteIndex] & y_byteMask) != 0;
-                    if (hasColorRegions) {
-                        chunkRow[x] = graphics::resolveTFTColorPixel(static_cast<int16_t>(x), static_cast<int16_t>(y), isset,
-                                                                     colorTftWhite, colorTftBlack);
-                    } else {
-                        chunkRow[x] = isset ? colorTftWhite : colorTftBlack;
-                    }
-                }
-            }
-#if defined(HACKADAY_COMMUNICATOR)
-            tft->draw16bitBeRGBBitmap(0, yStart, repaintChunkBuffer, displayWidth, rowsThisChunk);
-#else
-            tft->pushImage(0, yStart, displayWidth, rowsThisChunk, repaintChunkBuffer);
-#endif
-        }
-
-        memcpy(buffer_back, buffer, displayBufferSize);
-        lastColorFrameSignature = colorFrameSignature;
-        haveLastDefaults = true;
-        lastDefaultOnColor = defaultOnColor;
-        lastDefaultOffColor = defaultOffColor;
-        graphics::clearTFTColorRegions();
-        return;
-    }
-#endif
+    // Store colors byte-reversed so that TFT_eSPI doesn't have to swap bytes in a separate step
+    colorTftMesh = __builtin_bswap16(TFT_MESH);
+    colorTftBlack = __builtin_bswap16(TFT_BLACK);
 
     y = 0;
     while (y < displayHeight) {
@@ -1304,7 +1230,7 @@ void TFTDisplay::display(bool fromBlank)
 
         // Step 1: Do a quick scan of 8 rows together. This allows fast-forwarding over unchanged screen areas.
         if (y_byteMask == 1) {
-            if (!forceFullRepaint) {
+            if (!fromBlank) {
                 for (x = 0; x < displayWidth; x++) {
                     if (buffer[x + y_byteIndex] != buffer_back[x + y_byteIndex])
                         break;
@@ -1322,14 +1248,13 @@ void TFTDisplay::display(bool fromBlank)
             }
         }
 
-        // Step 2: Scan this row for changed span (first and last changed pixel).
-        uint32_t x_FirstChanged = 0;
-        for (x_FirstChanged = 0; x_FirstChanged < displayWidth; x_FirstChanged++) {
-            isset = buffer[x_FirstChanged + y_byteIndex] & y_byteMask;
+        // Step 2: Scan each of the 8 rows individually. Find the first pixel in each row that needs updating
+        for (x_FirstPixelUpdate = 0; x_FirstPixelUpdate < displayWidth; x_FirstPixelUpdate++) {
+            isset = buffer[x_FirstPixelUpdate + y_byteIndex] & y_byteMask;
 
-            if (!forceFullRepaint) {
+            if (!fromBlank) {
                 // get src pixel in the page based ordering the OLED lib uses
-                dblbuf_isset = buffer_back[x_FirstChanged + y_byteIndex] & y_byteMask;
+                dblbuf_isset = buffer_back[x_FirstPixelUpdate + y_byteIndex] & y_byteMask;
                 if (isset != dblbuf_isset) {
                     break;
                 }
@@ -1339,42 +1264,26 @@ void TFTDisplay::display(bool fromBlank)
         }
 
         // Did we find a pixel that needs updating on this row?
-        if (x_FirstChanged < displayWidth) {
-            uint32_t x_LastChanged = displayWidth - 1;
-            while (x_LastChanged > x_FirstChanged) {
-                isset = buffer[x_LastChanged + y_byteIndex] & y_byteMask;
-                if (!forceFullRepaint) {
-                    dblbuf_isset = buffer_back[x_LastChanged + y_byteIndex] & y_byteMask;
+        if (x_FirstPixelUpdate < displayWidth) {
+
+            // Quickly write out the first changed pixel (saves another array lookup)
+            linePixelBuffer[x_FirstPixelUpdate] = isset ? colorTftMesh : colorTftBlack;
+            x_LastPixelUpdate = x_FirstPixelUpdate;
+
+            // Step 3: copy all remaining pixels in this row into the pixel line buffer,
+            // while also recording the last pixel in the row that needs updating
+            for (x = x_FirstPixelUpdate + 1; x < displayWidth; x++) {
+                isset = buffer[x + y_byteIndex] & y_byteMask;
+                linePixelBuffer[x] = isset ? colorTftMesh : colorTftBlack;
+
+                if (!fromBlank) {
+                    dblbuf_isset = buffer_back[x + y_byteIndex] & y_byteMask;
                     if (isset != dblbuf_isset) {
-                        break;
+                        x_LastPixelUpdate = x;
                     }
                 } else if (isset) {
-                    break;
+                    x_LastPixelUpdate = x;
                 }
-                x_LastChanged--;
-            }
-
-            // Align the first pixel for update to an even number so the total alignment of
-            // the data will be at 32-bit boundary, which is required by GDMA SPI transfers.
-            x_FirstPixelUpdate = x_FirstChanged & ~1U;
-            x_LastPixelUpdate = x_LastChanged | 1U;
-            if (x_LastPixelUpdate >= displayWidth) {
-                x_LastPixelUpdate = displayWidth - 1;
-            }
-
-            // Step 3: Copy only the changed span into the pixel line buffer.
-            for (x = x_FirstPixelUpdate; x <= x_LastPixelUpdate; x++) {
-                isset = buffer[x + y_byteIndex] & y_byteMask;
-#if GRAPHICS_TFT_COLORING_ENABLED
-                if (hasColorRegions) {
-                    linePixelBuffer[x] = graphics::resolveTFTColorPixel(static_cast<int16_t>(x), static_cast<int16_t>(y), isset,
-                                                                        colorTftWhite, colorTftBlack);
-                } else {
-                    linePixelBuffer[x] = isset ? colorTftWhite : colorTftBlack;
-                }
-#else
-                linePixelBuffer[x] = isset ? colorTftWhite : colorTftBlack;
-#endif
             }
 #if defined(HACKADAY_COMMUNICATOR)
             tft->draw16bitBeRGBBitmap(x_FirstPixelUpdate, y, &linePixelBuffer[x_FirstPixelUpdate],
@@ -1382,8 +1291,8 @@ void TFTDisplay::display(bool fromBlank)
 #else
             // Step 4: Send the changed pixels on this line to the screen as a single block transfer.
             // This function accepts pixel data MSB first so it can dump the memory straight out the SPI port.
-            tft->pushImage(x_FirstPixelUpdate, y, (x_LastPixelUpdate - x_FirstPixelUpdate + 1), 1,
-                           &linePixelBuffer[x_FirstPixelUpdate]);
+            tft->pushRect(x_FirstPixelUpdate, y, (x_LastPixelUpdate - x_FirstPixelUpdate + 1), 1,
+                          &linePixelBuffer[x_FirstPixelUpdate]);
 #endif
             somethingChanged = true;
         }
@@ -1392,14 +1301,6 @@ void TFTDisplay::display(bool fromBlank)
     // Copy the Buffer to the Back Buffer
     if (somethingChanged)
         memcpy(buffer_back, buffer, displayBufferSize);
-
-#if GRAPHICS_TFT_COLORING_ENABLED
-    lastColorFrameSignature = colorFrameSignature;
-#endif
-    haveLastDefaults = true;
-    lastDefaultOnColor = defaultOnColor;
-    lastDefaultOffColor = defaultOffColor;
-    graphics::clearTFTColorRegions();
 }
 
 void TFTDisplay::sdlLoop()
@@ -1613,7 +1514,7 @@ bool TFTDisplay::connect()
 #else
     tft->setRotation(3); // Orient horizontal and wide underneath the silkscreen name label
 #endif
-    tft->fillScreen(getThemeDefaultOffColor());
+    tft->fillScreen(TFT_BLACK);
 
     if (this->linePixelBuffer == NULL) {
         this->linePixelBuffer = (uint16_t *)malloc(sizeof(uint16_t) * displayWidth);
@@ -1623,14 +1524,6 @@ bool TFTDisplay::connect()
             return false;
         }
     }
-    if (this->repaintChunkBuffer == NULL) {
-        this->repaintChunkBuffer = (uint16_t *)malloc(sizeof(uint16_t) * displayWidth * kFullRepaintChunkRows);
-
-        if (!this->repaintChunkBuffer) {
-            LOG_ERROR("Not enough memory to create TFT repaint chunk buffer\n");
-            return false;
-        }
-    }
     return true;
 }
 

src/graphics/TFTDisplay.h

@@ -63,5 +63,4 @@ class TFTDisplay : public OLEDDisplay
     virtual bool connect() override;
 
     uint16_t *linePixelBuffer = nullptr;
-    uint16_t *repaintChunkBuffer = nullptr;
-};
+};

src/graphics/TFTPalette.h

@@ -1,70 +0,0 @@
-#pragma once
-
-#include <stdint.h>
-
-namespace graphics
-{
-namespace TFTPalette
-{
-
-constexpr uint16_t rgb565(uint8_t red, uint8_t green, uint8_t blue)
-{
-    return static_cast<uint16_t>(((red & 0xF8) << 8) | ((green & 0xFC) << 3) | ((blue & 0xF8) >> 3));
-}
-
-constexpr uint16_t Black = 0x0000;
-constexpr uint16_t White = 0xFFFF;
-constexpr uint16_t DarkGray = 0x4208;
-constexpr uint16_t Gray = 0x8410;
-constexpr uint16_t LightGray = 0xC618;
-
-constexpr uint16_t Red = rgb565(255, 0, 0);
-constexpr uint16_t Green = rgb565(0, 255, 0);
-constexpr uint16_t Blue = rgb565(0, 130, 252);
-constexpr uint16_t Yellow = rgb565(255, 255, 0);
-constexpr uint16_t Orange = rgb565(255, 165, 0);
-constexpr uint16_t Cyan = rgb565(0, 255, 255);
-constexpr uint16_t Magenta = rgb565(255, 0, 255);
-
-constexpr uint16_t Good = Green;
-constexpr uint16_t Medium = Yellow;
-constexpr uint16_t Bad = Red;
-
-// Christmas / seasonal accent colors
-constexpr uint16_t ChristmasRed = rgb565(178, 34, 34);
-constexpr uint16_t ChristmasGreen = rgb565(0, 128, 0);
-constexpr uint16_t Gold = rgb565(255, 215, 0);
-constexpr uint16_t Pine = rgb565(15, 35, 10);
-
-// Pink theme colors (light variant)
-constexpr uint16_t HotPink = rgb565(255, 105, 180);
-constexpr uint16_t PalePink = rgb565(255, 228, 235);
-constexpr uint16_t DeepPink = rgb565(200, 50, 120);
-
-// Blue theme colors (dark variant)
-constexpr uint16_t SkyBlue = rgb565(100, 180, 255);
-constexpr uint16_t Navy = rgb565(15, 15, 50);
-constexpr uint16_t DeepBlue = rgb565(30, 60, 120);
-
-// Creamsicle theme colors (light variant)
-constexpr uint16_t CreamOrange = rgb565(255, 140, 50);
-constexpr uint16_t DeepOrange = rgb565(220, 100, 20);
-constexpr uint16_t Cream = rgb565(255, 248, 235);
-
-// Classic monochrome theme accent colors (single-color-on-black themes)
-constexpr uint16_t MeshtasticGreen = rgb565(0x67, 0xEA, 0x94);
-constexpr uint16_t ClassicRed = rgb565(255, 64, 64);
-// Monochrome White reuses TFTPalette::White above.
-
-// Fast contrast picker for monochrome glyph overlays on arbitrary RGB565 backgrounds.
-// Uses channel-sum brightness approximation to keep code size small.
-constexpr uint16_t pickReadableMonoFg(uint16_t backgroundColor)
-{
-    const uint16_t r = (backgroundColor >> 11) & 0x1F;
-    const uint16_t g = (backgroundColor >> 5) & 0x3F;
-    const uint16_t b = backgroundColor & 0x1F;
-    return ((r + g + b) >= 70) ? DarkGray : White;
-}
-
-} // namespace TFTPalette
-} // namespace graphics

src/graphics/draw/ClockRenderer.cpp

@@ -145,7 +145,7 @@ void drawDigitalClockFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int1
     // === Set Title, Blank for Clock
     const char *titleStr = "";
     // === Header ===
-    graphics::drawCommonHeader(display, x, y, titleStr, true, true, true);
+    graphics::drawCommonHeader(display, x, y, titleStr, true, true);
 
     uint32_t rtc_sec = getValidTime(RTCQuality::RTCQualityDevice, true); // Display local timezone
     char timeString[16];
@@ -293,15 +293,11 @@ void drawDigitalClockFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int1
 // Draw an analog clock
 void drawAnalogClockFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y)
 {
-#if GRAPHICS_TFT_COLORING_ENABLED
-    // Clear previous frame pixels so moving hands don't leave stale artifacts on TFT light theme.
-    display->clear();
-#endif
     display->setTextAlignment(TEXT_ALIGN_LEFT);
     // === Set Title, Blank for Clock
     const char *titleStr = "";
     // === Header ===
-    graphics::drawCommonHeader(display, x, y, titleStr, true, true, true);
+    graphics::drawCommonHeader(display, x, y, titleStr, true, true);
 
     // clock face center coordinates
     int16_t centerX = display->getWidth() / 2;
@@ -482,4 +478,4 @@ void drawAnalogClockFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16
 } // namespace ClockRenderer
 
 } // namespace graphics
-#endif
+#endif

src/graphics/draw/CompassRenderer.cpp

@@ -1,6 +1,10 @@
 #include "configuration.h"
 #if HAS_SCREEN
 #include "CompassRenderer.h"
+#include "NodeDB.h"
+#include "UIRenderer.h"
+#include "configuration.h"
+#include "gps/GeoCoord.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
 #include <cmath>
@@ -9,103 +13,111 @@ namespace graphics
 {
 namespace CompassRenderer
 {
+
+// Point helper class for compass calculations
+struct Point {
+    float x, y;
+    Point(float x, float y) : x(x), y(y) {}
+
+    void rotate(float angle)
+    {
+        float cos_a = cos(angle);
+        float sin_a = sin(angle);
+        float new_x = x * cos_a - y * sin_a;
+        float new_y = x * sin_a + y * cos_a;
+        x = new_x;
+        y = new_y;
+    }
+
+    void scale(float factor)
+    {
+        x *= factor;
+        y *= factor;
+    }
+
+    void translate(float dx, float dy)
+    {
+        x += dx;
+        y += dy;
+    }
+};
+
 void drawCompassNorth(OLEDDisplay *display, int16_t compassX, int16_t compassY, float myHeading, int16_t radius)
 {
+    // Show the compass heading (not implemented in original)
+    // This could draw a "N" indicator or north arrow
+    // For now, we'll draw a simple north indicator
+    // const float radius = 17.0f;
     if (currentResolution == ScreenResolution::High) {
         radius += 4;
     }
-
-    const float northAngle = (uiconfig.compass_mode != meshtastic_CompassMode_FIXED_RING) ? -myHeading : 0.0f;
-    const int16_t nX = compassX + static_cast<int16_t>((radius - 1) * sinf(northAngle));
-    const int16_t nY = compassY - static_cast<int16_t>((radius - 1) * cosf(northAngle));
+    Point north(0, -radius);
+    if (uiconfig.compass_mode != meshtastic_CompassMode_FIXED_RING)
+        north.rotate(-myHeading);
+    north.translate(compassX, compassY);
 
     display->setFont(FONT_SMALL);
     display->setTextAlignment(TEXT_ALIGN_CENTER);
-#if !GRAPHICS_TFT_COLORING_ENABLED
     display->setColor(BLACK);
-    const int16_t nLabelWidth = display->getStringWidth("N");
     if (currentResolution == ScreenResolution::High) {
-        display->fillRect(nX - 8, nY - 1, nLabelWidth + 3, FONT_HEIGHT_SMALL - 6);
+        display->fillRect(north.x - 8, north.y - 1, display->getStringWidth("N") + 3, FONT_HEIGHT_SMALL - 6);
     } else {
-        display->fillRect(nX - 4, nY - 1, nLabelWidth + 2, FONT_HEIGHT_SMALL - 6);
+        display->fillRect(north.x - 4, north.y - 1, display->getStringWidth("N") + 2, FONT_HEIGHT_SMALL - 6);
     }
-#endif
     display->setColor(WHITE);
-    display->drawString(nX, nY - 3, "N");
-}
-
-void drawArrowToNode(OLEDDisplay *display, int16_t x, int16_t y, int16_t size, float bearing)
-{
-    const float radians = bearing * DEG_TO_RAD;
-    const float sinA = sinf(radians);
-    const float cosA = cosf(radians);
-    const float tipHalf = size * 0.5f;
-    const float lx = -(size / 6.0f);
-    const float ly = size / 4.0f;
-    const float rx = (size / 6.0f);
-    const float ry = size / 4.0f;
-    const float tx = 0.0f;
-    const float ty = size / 4.5f;
-
-    const int16_t tipX = static_cast<int16_t>(x + (tipHalf * sinA));
-    const int16_t tipY = static_cast<int16_t>(y - (tipHalf * cosA));
-    const int16_t leftX = static_cast<int16_t>(x + (lx * cosA) - (ly * sinA));
-    const int16_t leftY = static_cast<int16_t>(y + (lx * sinA) + (ly * cosA));
-    const int16_t rightX = static_cast<int16_t>(x + (rx * cosA) - (ry * sinA));
-    const int16_t rightY = static_cast<int16_t>(y + (rx * sinA) + (ry * cosA));
-    const int16_t tailX = static_cast<int16_t>(x + (tx * cosA) - (ty * sinA));
-    const int16_t tailY = static_cast<int16_t>(y + (tx * sinA) + (ty * cosA));
-
-    display->fillTriangle(tipX, tipY, leftX, leftY, tailX, tailY);
-    display->fillTriangle(tipX, tipY, rightX, rightY, tailX, tailY);
+    display->drawString(north.x, north.y - 3, "N");
 }
 
 void drawNodeHeading(OLEDDisplay *display, int16_t compassX, int16_t compassY, uint16_t compassDiam, float headingRadian)
 {
-    const int16_t size = static_cast<int16_t>(compassDiam * 0.6f);
-    drawArrowToNode(display, compassX, compassY, size, headingRadian * RAD_TO_DEG);
-}
+    Point tip(0.0f, -0.5f), tail(0.0f, 0.35f); // pointing up initially
+    float arrowOffsetX = 0.14f, arrowOffsetY = 0.9f;
+    Point leftArrow(tip.x - arrowOffsetX, tip.y + arrowOffsetY), rightArrow(tip.x + arrowOffsetX, tip.y + arrowOffsetY);
 
-bool getHeadingRadians(double lat, double lon, float &headingRadian)
-{
-    headingRadian = 0.0f;
+    Point *arrowPoints[] = {&tip, &tail, &leftArrow, &rightArrow};
 
-    if (uiconfig.compass_mode == meshtastic_CompassMode_FREEZE_HEADING)
-        return true;
-
-    if (!screen)
-        return false;
-
-    if (screen->hasHeading()) {
-        headingRadian = screen->getHeading() * DEG_TO_RAD;
-        return true;
+    for (int i = 0; i < 4; i++) {
+        arrowPoints[i]->rotate(headingRadian);
+        arrowPoints[i]->scale(compassDiam * 0.6);
+        arrowPoints[i]->translate(compassX, compassY);
     }
 
-    const float estimatedHeadingDeg = screen->estimatedHeading(lat, lon);
-    if (!(estimatedHeadingDeg >= 0.0f))
-        return false;
-
-    headingRadian = estimatedHeadingDeg * DEG_TO_RAD;
-    return true;
+#ifdef USE_EINK
+    display->drawTriangle(tip.x, tip.y, rightArrow.x, rightArrow.y, tail.x, tail.y);
+#else
+    display->fillTriangle(tip.x, tip.y, rightArrow.x, rightArrow.y, tail.x, tail.y);
+#endif
+    display->drawTriangle(tip.x, tip.y, leftArrow.x, leftArrow.y, tail.x, tail.y);
 }
 
-float adjustBearingForCompassMode(float bearingRadian, float headingRadian)
+void drawArrowToNode(OLEDDisplay *display, int16_t x, int16_t y, int16_t size, float bearing)
 {
-    if (uiconfig.compass_mode != meshtastic_CompassMode_FIXED_RING)
-        return bearingRadian - headingRadian;
+    float radians = bearing * DEG_TO_RAD;
 
-    return bearingRadian;
+    Point tip(0, -size / 2);
+    Point left(-size / 6, size / 4);
+    Point right(size / 6, size / 4);
+    Point tail(0, size / 4.5);
+
+    tip.rotate(radians);
+    left.rotate(radians);
+    right.rotate(radians);
+    tail.rotate(radians);
+
+    tip.translate(x, y);
+    left.translate(x, y);
+    right.translate(x, y);
+    tail.translate(x, y);
+
+    display->fillTriangle(tip.x, tip.y, left.x, left.y, tail.x, tail.y);
+    display->fillTriangle(tip.x, tip.y, right.x, right.y, tail.x, tail.y);
 }
 
-float radiansToDegrees360(float angleRadian)
+float estimatedHeading(double lat, double lon)
 {
-    constexpr float fullTurnDeg = 360.0f;
-    float degrees = angleRadian * RAD_TO_DEG;
-    if (degrees < 0.0f)
-        degrees += fullTurnDeg;
-    else if (degrees >= fullTurnDeg)
-        degrees -= fullTurnDeg;
-    return degrees;
+    // Simple magnetic declination estimation
+    // This is a very basic implementation - the original might be more sophisticated
+    return 0.0f; // Return 0 for now, indicating no heading available
 }
 
 uint16_t getCompassDiam(uint32_t displayWidth, uint32_t displayHeight)
@@ -125,4 +137,4 @@ uint16_t getCompassDiam(uint32_t displayWidth, uint32_t displayHeight)
 
 } // namespace CompassRenderer
 } // namespace graphics
-#endif
+#endif

src/graphics/draw/CompassRenderer.h

@@ -25,9 +25,7 @@ void drawNodeHeading(OLEDDisplay *display, int16_t compassX, int16_t compassY, u
 void drawArrowToNode(OLEDDisplay *display, int16_t x, int16_t y, int16_t size, float bearing);
 
 // Navigation and location functions
-bool getHeadingRadians(double lat, double lon, float &headingRadian);
-float adjustBearingForCompassMode(float bearingRadian, float headingRadian);
-float radiansToDegrees360(float angleRadian);
+float estimatedHeading(double lat, double lon);
 uint16_t getCompassDiam(uint32_t displayWidth, uint32_t displayHeight);
 
 } // namespace CompassRenderer

src/graphics/draw/DebugRenderer.cpp

@@ -11,8 +11,6 @@
 #include "gps/RTC.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTColorRegions.h"
-#include "graphics/TFTPalette.h"
 #include "graphics/TimeFormatters.h"
 #include "graphics/images.h"
 #include "main.h"
@@ -410,16 +408,7 @@ void drawLoRaFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x,
     display->drawString(nameX, getTextPositions(display)[line++], device_role);
 
     // === Third Row: Radio Preset ===
-    // For custom modem settings show the actual parameters; for presets use the preset name.
-    char modeStr[16];
-    if (!config.lora.use_preset) {
-        snprintf(modeStr, sizeof(modeStr), "BW%u-SF%u-CR%u", static_cast<unsigned>(config.lora.bandwidth),
-                 static_cast<unsigned>(config.lora.spread_factor), static_cast<unsigned>(config.lora.coding_rate));
-    } else {
-        strncpy(modeStr, DisplayFormatters::getModemPresetDisplayName(config.lora.modem_preset, false, true),
-                sizeof(modeStr) - 1);
-        modeStr[sizeof(modeStr) - 1] = '\0';
-    }
+    auto mode = DisplayFormatters::getModemPresetDisplayName(config.lora.modem_preset, false, config.lora.use_preset);
 
     char regionradiopreset[25];
     const char *region = myRegion ? myRegion->name : NULL;
@@ -427,7 +416,7 @@ void drawLoRaFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x,
         if (currentResolution == ScreenResolution::UltraLow) {
             snprintf(regionradiopreset, sizeof(regionradiopreset), "%s", region);
         } else {
-            snprintf(regionradiopreset, sizeof(regionradiopreset), "%s/%s", region, modeStr);
+            snprintf(regionradiopreset, sizeof(regionradiopreset), "%s/%s", region, mode);
         }
     }
     textWidth = display->getStringWidth(regionradiopreset);
@@ -471,11 +460,9 @@ void drawLoRaFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x,
     int chUtil_y = getTextPositions(display)[line] + 3;
 
     int chutil_bar_width = (currentResolution == ScreenResolution::High) ? 100 : 50;
-    int chutil_bar_max_fill = chutil_bar_width - 2; // Account for border
     int chutil_bar_height = (currentResolution == ScreenResolution::High) ? 12 : 7;
     int extraoffset = (currentResolution == ScreenResolution::High) ? 6 : 3;
     int chutil_percent = airTime->channelUtilizationPercent();
-    const int raw_chutil_percent = chutil_percent;
 
     int centerofscreen = SCREEN_WIDTH / 2;
     int total_line_content_width = (chUtil_x + chutil_bar_width + display->getStringWidth(chUtilPercentage) + extraoffset) / 2;
@@ -483,7 +470,7 @@ void drawLoRaFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x,
 
     display->drawString(starting_position, getTextPositions(display)[line], chUtil);
 
-    // Force 61% or higher to show a full 100% bar, text would still show related percent.
+    // Force 56% or higher to show a full 100% bar, text would still show related percent.
     if (chutil_percent >= 61) {
         chutil_percent = 100;
     }
@@ -496,9 +483,9 @@ void drawLoRaFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x,
     float weight3 = 0.20; // Weight for 40–100%
     float totalWeight = weight1 + weight2 + weight3;
 
-    int seg1 = chutil_bar_max_fill * (weight1 / totalWeight);
-    int seg2 = chutil_bar_max_fill * (weight2 / totalWeight);
-    int seg3 = chutil_bar_max_fill - seg1 - seg2; // Remainder absorbs rounding errors
+    int seg1 = chutil_bar_width * (weight1 / totalWeight);
+    int seg2 = chutil_bar_width * (weight2 / totalWeight);
+    int seg3 = chutil_bar_width * (weight3 / totalWeight);
 
     int fillRight = 0;
 
@@ -515,17 +502,7 @@ void drawLoRaFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x,
 
     // Fill progress
     if (fillRight > 0) {
-#if GRAPHICS_TFT_COLORING_ENABLED
-        uint16_t UtilizationFillColor = TFTPalette::Good;
-        if (raw_chutil_percent >= 60) {
-            UtilizationFillColor = TFTPalette::Bad;
-        } else if (raw_chutil_percent >= 35) {
-            UtilizationFillColor = TFTPalette::Medium;
-        }
-        setAndRegisterTFTColorRole(TFTColorRole::UtilizationFill, UtilizationFillColor, TFTPalette::Black,
-                                   starting_position + chUtil_x + 1, chUtil_y + 1, fillRight, chutil_bar_height - 2);
-#endif
-        display->fillRect(starting_position + chUtil_x + 1, chUtil_y + 1, fillRight, chutil_bar_height - 2);
+        display->fillRect(starting_position + chUtil_x, chUtil_y, fillRight, chutil_bar_height);
     }
 
     display->drawString(starting_position + chUtil_x + chutil_bar_width + extraoffset, getTextPositions(display)[line++],
@@ -598,17 +575,6 @@ void drawSystemScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x
         display->setColor(WHITE);
         display->drawRect(barX, barY, adjustedBarWidth, barHeight);
 
-#if GRAPHICS_TFT_COLORING_ENABLED
-        uint16_t UtilizationFillColor = TFTPalette::Good;
-        if (percent >= 80) {
-            UtilizationFillColor = TFTPalette::Bad;
-        } else if (percent >= 60) {
-            UtilizationFillColor = TFTPalette::Medium;
-        }
-        setAndRegisterTFTColorRole(TFTColorRole::UtilizationFill, UtilizationFillColor, TFTPalette::Black, barX + 1, barY + 1,
-                                   fillWidth - 1, barHeight - 2);
-#endif
-
         display->fillRect(barX, barY, fillWidth, barHeight);
         display->setColor(WHITE);
 #endif

src/graphics/draw/MenuHandler.cpp

@@ -11,7 +11,6 @@
 #include "buzz.h"
 #include "graphics/Screen.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTColorRegions.h"
 #include "graphics/draw/MessageRenderer.h"
 #include "graphics/draw/UIRenderer.h"
 #include "input/RotaryEncoderInterruptImpl1.h"
@@ -19,7 +18,6 @@
 #include "main.h"
 #include "mesh/Default.h"
 #include "mesh/MeshTypes.h"
-#include "mesh/RadioLibInterface.h"
 #include "modules/AdminModule.h"
 #include "modules/CannedMessageModule.h"
 #include "modules/ExternalNotificationModule.h"
@@ -27,10 +25,11 @@
 #include "modules/TraceRouteModule.h"
 #include <algorithm>
 #include <array>
-#include <cmath>
 #include <functional>
 #include <utility>
 
+extern uint16_t TFT_MESH;
+
 namespace graphics
 {
 
@@ -160,22 +159,31 @@ void menuHandler::LoraRegionPicker(uint32_t duration)
                 return;
             }
 
-            // Guard: without a reboot, reconfigure() applies the region directly.
-            // Reject LORA_24 on sub-GHz-only hardware — getRadio() used to catch this post-reboot.
-            // TODO: change this to either use the validateLoraConfig() logic or at least check the region for wideLora
-            // rather than a hardcoded check for LORA_24.
-            if (selectedRegion == meshtastic_Config_LoRaConfig_RegionCode_LORA_24 &&
-                !(RadioLibInterface::instance && RadioLibInterface::instance->wideLora())) {
-                LOG_WARN("Radio hardware does not support 2.4 GHz; ignoring region selection");
-                return;
-            }
-
             config.lora.region = selectedRegion;
             auto changes = SEGMENT_CONFIG;
 
+        // FIXME: This should be a method consolidated with the same logic in the admin message as well
+        // This is needed as we wait til picking the LoRa region to generate keys for the first time.
 #if !(MESHTASTIC_EXCLUDE_PKI_KEYGEN || MESHTASTIC_EXCLUDE_PKI)
-            if (crypto) {
-                crypto->ensurePkiKeys(config.security, owner);
+            if (!owner.is_licensed) {
+                bool keygenSuccess = false;
+                if (config.security.private_key.size == 32) {
+                    // public key is derived from private, so this will always have the same result.
+                    if (crypto->regeneratePublicKey(config.security.public_key.bytes, config.security.private_key.bytes)) {
+                        keygenSuccess = true;
+                    }
+
+                } else {
+                    LOG_INFO("Generate new PKI keys");
+                    crypto->generateKeyPair(config.security.public_key.bytes, config.security.private_key.bytes);
+                    keygenSuccess = true;
+                }
+                if (keygenSuccess) {
+                    config.security.public_key.size = 32;
+                    config.security.private_key.size = 32;
+                    owner.public_key.size = 32;
+                    memcpy(owner.public_key.bytes, config.security.public_key.bytes, 32);
+                }
             }
 #endif
             config.lora.tx_enabled = true;
@@ -191,6 +199,7 @@ void menuHandler::LoraRegionPicker(uint32_t duration)
             }
 
             service->reloadConfig(changes);
+            rebootAtMsec = (millis() + DEFAULT_REBOOT_SECONDS * 1000);
         });
 
     bannerOptions.durationMs = duration;
@@ -256,24 +265,13 @@ void menuHandler::FrequencySlotPicker()
     optionsEnumArray[options++] = 0;
 
     // Calculate number of channels (copied from RadioInterface::applyModemConfig())
-
     meshtastic_Config_LoRaConfig &loraConfig = config.lora;
     double bw = loraConfig.use_preset ? modemPresetToBwKHz(loraConfig.modem_preset, myRegion->wideLora)
                                       : bwCodeToKHz(loraConfig.bandwidth);
 
     uint32_t numChannels = 0;
     if (myRegion) {
-        // Match RadioInterface::applyModemConfig(): include padding, add spacing in numerator, and use round()
-        const double spacing = myRegion->profile->spacing;
-        const double padding = myRegion->profile->padding;
-        const double channelBandwidthMHz = bw / 1000.0;
-        const double numerator = (myRegion->freqEnd - myRegion->freqStart) + spacing;
-        const double denominator = spacing + (padding * 2) + channelBandwidthMHz;
-        if (denominator > 0.0) {
-            numChannels = static_cast<uint32_t>(round(numerator / denominator));
-        } else {
-            LOG_WARN("Invalid region configuration: non-positive channel spacing/width");
-        }
+        numChannels = (uint32_t)floor((myRegion->freqEnd - myRegion->freqStart) / (myRegion->spacing + (bw / 1000.0)));
     } else {
         LOG_WARN("Region not set, cannot calculate number of channels");
         return;
@@ -309,6 +307,7 @@ void menuHandler::FrequencySlotPicker()
 
         config.lora.channel_num = selected;
         service->reloadConfig(SEGMENT_CONFIG);
+        rebootAtMsec = (millis() + DEFAULT_REBOOT_SECONDS * 1000);
     };
 
     screen->showOverlayBanner(bannerOptions);
@@ -347,6 +346,7 @@ void menuHandler::radioPresetPicker()
             config.lora.channel_num = 0;        // Reset to default channel for the preset
             config.lora.override_frequency = 0; // Clear any custom frequency
             service->reloadConfig(SEGMENT_CONFIG);
+            rebootAtMsec = (millis() + DEFAULT_REBOOT_SECONDS * 1000);
         });
 
     screen->showOverlayBanner(bannerOptions);
@@ -2027,6 +2027,109 @@ void menuHandler::switchToMUIMenu()
     screen->showOverlayBanner(bannerOptions);
 }
 
+void menuHandler::TFTColorPickerMenu(OLEDDisplay *display)
+{
+    static const ScreenColorOption colorOptions[] = {
+        {"Back", OptionsAction::Back},
+        {"Default", OptionsAction::Select, ScreenColor(0, 0, 0, true)},
+        {"Meshtastic Green", OptionsAction::Select, ScreenColor(0x67, 0xEA, 0x94)},
+        {"Yellow", OptionsAction::Select, ScreenColor(255, 255, 128)},
+        {"Red", OptionsAction::Select, ScreenColor(255, 64, 64)},
+        {"Orange", OptionsAction::Select, ScreenColor(255, 160, 20)},
+        {"Purple", OptionsAction::Select, ScreenColor(204, 153, 255)},
+        {"Blue", OptionsAction::Select, ScreenColor(0, 0, 255)},
+        {"Teal", OptionsAction::Select, ScreenColor(16, 102, 102)},
+        {"Cyan", OptionsAction::Select, ScreenColor(0, 255, 255)},
+        {"Ice", OptionsAction::Select, ScreenColor(173, 216, 230)},
+        {"Pink", OptionsAction::Select, ScreenColor(255, 105, 180)},
+        {"White", OptionsAction::Select, ScreenColor(255, 255, 255)},
+        {"Gray", OptionsAction::Select, ScreenColor(128, 128, 128)},
+    };
+
+    constexpr size_t colorCount = sizeof(colorOptions) / sizeof(colorOptions[0]);
+    static std::array<const char *, colorCount> colorLabels{};
+
+    auto bannerOptions = createStaticBannerOptions(
+        "Select Screen Color", colorOptions, colorLabels, [display](const ScreenColorOption &option, int) -> void {
+            if (option.action == OptionsAction::Back) {
+                menuQueue = SystemBaseMenu;
+                screen->runNow();
+                return;
+            }
+
+            if (!option.hasValue) {
+                return;
+            }
+
+#if defined(HELTEC_MESH_NODE_T114) || defined(HELTEC_VISION_MASTER_T190) || defined(T_DECK) || defined(T_LORA_PAGER) ||          \
+    HAS_TFT || defined(HACKADAY_COMMUNICATOR)
+            const ScreenColor &color = option.value;
+            if (color.useVariant) {
+                LOG_INFO("Setting color to system default or defined variant");
+            } else {
+                LOG_INFO("Setting color to %s", option.label);
+            }
+
+            uint8_t r = color.r;
+            uint8_t g = color.g;
+            uint8_t b = color.b;
+
+            display->setColor(BLACK);
+            display->fillRect(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT);
+            display->setColor(WHITE);
+
+            if (color.useVariant || (r == 0 && g == 0 && b == 0)) {
+#ifdef TFT_MESH_OVERRIDE
+                TFT_MESH = TFT_MESH_OVERRIDE;
+#else
+                TFT_MESH = COLOR565(255, 255, 128);
+#endif
+            } else {
+                TFT_MESH = COLOR565(r, g, b);
+            }
+
+#if defined(HELTEC_MESH_NODE_T114) || defined(HELTEC_VISION_MASTER_T190)
+            static_cast<ST7789Spi *>(screen->getDisplayDevice())->setRGB(TFT_MESH);
+#endif
+
+            screen->setFrames(graphics::Screen::FOCUS_SYSTEM);
+            if (color.useVariant || (r == 0 && g == 0 && b == 0)) {
+                uiconfig.screen_rgb_color = 0;
+            } else {
+                uiconfig.screen_rgb_color =
+                    (static_cast<uint32_t>(r) << 16) | (static_cast<uint32_t>(g) << 8) | static_cast<uint32_t>(b);
+            }
+            LOG_INFO("Storing Value of %d to uiconfig.screen_rgb_color", uiconfig.screen_rgb_color);
+            saveUIConfig();
+#endif
+        });
+
+    int initialSelection = 0;
+    if (uiconfig.screen_rgb_color == 0) {
+        initialSelection = 1;
+    } else {
+        uint32_t currentColor = uiconfig.screen_rgb_color;
+        for (size_t i = 0; i < colorCount; ++i) {
+            if (!colorOptions[i].hasValue) {
+                continue;
+            }
+            const ScreenColor &color = colorOptions[i].value;
+            if (color.useVariant) {
+                continue;
+            }
+            uint32_t encoded =
+                (static_cast<uint32_t>(color.r) << 16) | (static_cast<uint32_t>(color.g) << 8) | static_cast<uint32_t>(color.b);
+            if (encoded == currentColor) {
+                initialSelection = static_cast<int>(i);
+                break;
+            }
+        }
+    }
+    bannerOptions.InitialSelected = initialSelection;
+
+    screen->showOverlayBanner(bannerOptions);
+}
+
 void menuHandler::rebootMenu()
 {
     static const char *optionsArray[] = {"Back", "Confirm"};
@@ -2214,9 +2317,9 @@ void menuHandler::screenOptionsMenu()
     bool hasSupportBrightness = false;
 #endif
 
-    enum optionsNumbers { Back, Brightness, FrameToggles, DisplayUnits, MessageBubbles, Theme };
-    static const char *optionsArray[7] = {"Back"};
-    static int optionsEnumArray[7] = {Back};
+    enum optionsNumbers { Back, Brightness, ScreenColor, FrameToggles, DisplayUnits, MessageBubbles };
+    static const char *optionsArray[6] = {"Back"};
+    static int optionsEnumArray[6] = {Back};
     int options = 1;
 
     // Only show brightness for B&W displays
@@ -2225,6 +2328,13 @@ void menuHandler::screenOptionsMenu()
         optionsEnumArray[options++] = Brightness;
     }
 
+    // Only show screen color for TFT displays
+#if defined(HELTEC_MESH_NODE_T114) || defined(HELTEC_VISION_MASTER_T190) || defined(T_DECK) || defined(T_LORA_PAGER) ||          \
+    HAS_TFT || defined(HACKADAY_COMMUNICATOR)
+    optionsArray[options] = "Screen Color";
+    optionsEnumArray[options++] = ScreenColor;
+#endif
+
     optionsArray[options] = "Frame Visibility";
     optionsEnumArray[options++] = FrameToggles;
 
@@ -2234,11 +2344,6 @@ void menuHandler::screenOptionsMenu()
     optionsArray[options] = "Message Bubbles";
     optionsEnumArray[options++] = MessageBubbles;
 
-#if GRAPHICS_TFT_COLORING_ENABLED
-    optionsArray[options] = "Theme";
-    optionsEnumArray[options++] = Theme;
-#endif
-
     BannerOverlayOptions bannerOptions;
     bannerOptions.message = "Display Options";
     bannerOptions.optionsArrayPtr = optionsArray;
@@ -2248,6 +2353,9 @@ void menuHandler::screenOptionsMenu()
         if (selected == Brightness) {
             menuHandler::menuQueue = menuHandler::BrightnessPicker;
             screen->runNow();
+        } else if (selected == ScreenColor) {
+            menuHandler::menuQueue = menuHandler::TftColorMenuPicker;
+            screen->runNow();
         } else if (selected == FrameToggles) {
             menuHandler::menuQueue = menuHandler::FrameToggles;
             screen->runNow();
@@ -2257,9 +2365,6 @@ void menuHandler::screenOptionsMenu()
         } else if (selected == MessageBubbles) {
             menuHandler::menuQueue = menuHandler::MessageBubblesMenu;
             screen->runNow();
-        } else if (selected == Theme) {
-            menuHandler::menuQueue = menuHandler::ThemeMenu;
-            screen->runNow();
         } else {
             menuQueue = SystemBaseMenu;
             screen->runNow();
@@ -2543,53 +2648,6 @@ void menuHandler::messageBubblesMenu()
     screen->showOverlayBanner(bannerOptions);
 }
 
-void menuHandler::themeMenu()
-{
-    // Build menu dynamically from the theme table.
-    // Only visible themes appear!
-    // Slot budget: 1 for "Back" + up to kMaxThemesInMenu visible themes.
-    // Bump kMaxThemesInMenu if you add more themes than will fit here.
-    constexpr size_t kMaxThemesInMenu = 15;
-    const size_t visibleCount = getVisibleThemeCount();
-    static const char *optionsArray[kMaxThemesInMenu + 1] = {"Back"};
-    const size_t shownCount = (visibleCount < kMaxThemesInMenu) ? visibleCount : kMaxThemesInMenu;
-    const int options = static_cast<int>(shownCount) + 1; // +1 for Back
-
-    for (size_t i = 0; i < shownCount; i++) {
-        optionsArray[i + 1] = getVisibleThemeByIndex(i).name;
-    }
-
-    BannerOverlayOptions bannerOptions;
-    bannerOptions.message = "Theme";
-    bannerOptions.optionsArrayPtr = optionsArray;
-    bannerOptions.optionsCount = options;
-
-    // Highlight the currently active theme (visible index + 1 for the Back
-    // offset).  If the active theme is hidden, leave selection on "Back".
-    const size_t activeVisible = getActiveVisibleThemeIndex();
-    bannerOptions.InitialSelected = (activeVisible == SIZE_MAX) ? 0 : static_cast<int>(activeVisible) + 1;
-
-    bannerOptions.bannerCallback = [](int selected) -> void {
-        if (selected == 0) {
-            // Back
-            menuHandler::menuQueue = menuHandler::ScreenOptionsMenu;
-            screen->runNow();
-        } else {
-            // Selection is an index into the VISIBLE themes (1-based, slot 0 is Back).
-            const size_t visibleIdx = static_cast<size_t>(selected - 1);
-            if (visibleIdx < getVisibleThemeCount()) {
-                // Persist the theme's uniqueIdentifier so boot-time
-                // resolveThemeIndex() can restore this theme on next startup.
-                uiconfig.screen_rgb_color = COLOR565(255, 255, (getVisibleThemeByIndex(visibleIdx).uniqueIdentifier & 0x1F) << 3);
-                loadThemeDefaults();
-                saveUIConfig();
-                screen->runNow();
-            }
-        }
-    };
-    screen->showOverlayBanner(bannerOptions);
-}
-
 void menuHandler::handleMenuSwitch(OLEDDisplay *display)
 {
     if (menuQueue != MenuNone)
@@ -2665,6 +2723,9 @@ void menuHandler::handleMenuSwitch(OLEDDisplay *display)
     case MuiPicker:
         switchToMUIMenu();
         break;
+    case TftColorMenuPicker:
+        TFTColorPickerMenu(display);
+        break;
     case BrightnessPicker:
         BrightnessPickerMenu();
         break;
@@ -2737,9 +2798,6 @@ void menuHandler::handleMenuSwitch(OLEDDisplay *display)
     case MessageBubblesMenu:
         messageBubblesMenu();
         break;
-    case ThemeMenu:
-        themeMenu();
-        break;
     }
     menuQueue = MenuNone;
 }
@@ -2751,4 +2809,4 @@ void menuHandler::saveUIConfig()
 
 } // namespace graphics
 
-#endif
+#endif

src/graphics/draw/MenuHandler.h

@@ -30,6 +30,7 @@ class menuHandler
         ResetNodeDbMenu,
         BuzzerModeMenuPicker,
         MuiPicker,
+        TftColorMenuPicker,
         BrightnessPicker,
         RebootMenu,
         ShutdownMenu,
@@ -54,8 +55,7 @@ class menuHandler
         NodeNameLengthMenu,
         FrameToggles,
         DisplayUnits,
-        MessageBubblesMenu,
-        ThemeMenu
+        MessageBubblesMenu
     };
     static screenMenus menuQueue;
     static uint32_t pickedNodeNum; // node selected by NodePicker for ManageNodeMenu
@@ -89,6 +89,7 @@ class menuHandler
     static void GPSPositionBroadcastMenu();
     static void BuzzerModeMenu();
     static void switchToMUIMenu();
+    static void TFTColorPickerMenu(OLEDDisplay *display);
     static void nodeListMenu();
     static void resetNodeDBMenu();
     static void BrightnessPickerMenu();
@@ -109,7 +110,6 @@ class menuHandler
     static void frameTogglesMenu();
     static void displayUnitsMenu();
     static void messageBubblesMenu();
-    static void themeMenu();
     static void textMessageMenu();
 
   private:
@@ -136,10 +136,23 @@ template <typename T> struct MenuOption {
     MenuOption(const char *labelIn, OptionsAction actionIn) : label(labelIn), action(actionIn), hasValue(false), value() {}
 };
 
+struct ScreenColor {
+    uint8_t r;
+    uint8_t g;
+    uint8_t b;
+    bool useVariant;
+
+    explicit ScreenColor(uint8_t rIn = 0, uint8_t gIn = 0, uint8_t bIn = 0, bool variantIn = false)
+        : r(rIn), g(gIn), b(bIn), useVariant(variantIn)
+    {
+    }
+};
+
 using RadioPresetOption = MenuOption<meshtastic_Config_LoRaConfig_ModemPreset>;
 using LoraRegionOption = MenuOption<meshtastic_Config_LoRaConfig_RegionCode>;
 using TimezoneOption = MenuOption<const char *>;
 using CompassOption = MenuOption<meshtastic_CompassMode>;
+using ScreenColorOption = MenuOption<ScreenColor>;
 using GPSToggleOption = MenuOption<meshtastic_Config_PositionConfig_GpsMode>;
 using GPSFormatOption = MenuOption<meshtastic_DeviceUIConfig_GpsCoordinateFormat>;
 using NodeNameOption = MenuOption<bool>;

src/graphics/draw/MessageRenderer.cpp

@@ -11,8 +11,6 @@
 #include "graphics/Screen.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTColorRegions.h"
-#include "graphics/TFTPalette.h"
 #include "graphics/TimeFormatters.h"
 #include "graphics/emotes.h"
 #include "main.h"
@@ -256,76 +254,6 @@ struct MessageBlock {
     bool mine;
 };
 
-#if GRAPHICS_TFT_COLORING_ENABLED
-static void setDarkModeBubbleRoleColors(uint32_t themeId, bool mine)
-{
-    uint16_t bubbleOnColor;
-    uint16_t bubbleOffColor;
-
-    if (themeId == ThemeID::Blue) {
-        bubbleOnColor = mine ? TFTPalette::Navy : TFTPalette::White;
-        bubbleOffColor = mine ? TFTPalette::SkyBlue : TFTPalette::DeepBlue;
-    } else {
-        bubbleOnColor = mine ? TFTPalette::Black : getThemeBodyFg();
-        bubbleOffColor = mine ? TFTPalette::SkyBlue : TFTPalette::DarkGray;
-    }
-
-    setTFTColorRole(TFTColorRole::ActionMenuBody, bubbleOnColor, bubbleOffColor);
-}
-
-static void registerRoundedBubbleFillRegion(int x, int y, int w, int h, int radius)
-{
-    if (w <= 0 || h <= 0) {
-        return;
-    }
-
-    if (radius <= 0 || w < 3 || h < 3) {
-        registerTFTColorRegion(TFTColorRole::ActionMenuBody, x, y, w, h);
-        return;
-    }
-
-    // Keep region count low so we don't churn MAX_TFT_COLOR_REGIONS while
-    // scrolling long message lists (which can flatten older bubble corners).
-    int capRows = 0;
-    if (radius >= 4 && h >= 5) {
-        capRows = 2; // 5 regions total (2 top caps + middle + 2 bottom caps)
-    } else if (radius >= 2 && h >= 3) {
-        capRows = 1; // 3 regions total
-    }
-    if (capRows <= 0) {
-        registerTFTColorRegion(TFTColorRole::ActionMenuBody, x, y, w, h);
-        return;
-    }
-
-    for (int row = 0; row < capRows; ++row) {
-        int inset = 0;
-        if (radius >= 4) {
-            inset = (row == 0) ? 2 : 1;
-        } else if (radius >= 2) {
-            inset = 1;
-        }
-        const int stripW = w - (inset * 2);
-        if (stripW <= 0) {
-            continue;
-        }
-
-        const int topY = y + row;
-        registerTFTColorRegion(TFTColorRole::ActionMenuBody, x + inset, topY, stripW, 1);
-
-        const int bottomY = y + h - 1 - row;
-        if (bottomY != topY) {
-            registerTFTColorRegion(TFTColorRole::ActionMenuBody, x + inset, bottomY, stripW, 1);
-        }
-    }
-
-    const int middleY = y + capRows;
-    const int middleH = h - (capRows * 2);
-    if (middleH > 0) {
-        registerTFTColorRegion(TFTColorRole::ActionMenuBody, x, middleY, w, middleH);
-    }
-}
-#endif
-
 static int getDrawnLinePixelBottom(int lineTopY, const std::string &line, bool isHeaderLine)
 {
     if (isHeaderLine) {
@@ -720,11 +648,6 @@ void drawTextMessageFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16
     const int contentBottom = scrollBottom; // already excludes nav line
     const int rightEdge = SCREEN_WIDTH - SCROLLBAR_WIDTH - RIGHT_MARGIN;
     const int bubbleGapY = std::max(1, MESSAGE_BLOCK_GAP / 2);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    const uint32_t themeId = getActiveTheme().id;
-    // Blue is a dark variant but uses full frame inversion, Keep it on the same filled bubble style as Default Dark.
-    const bool useDarkModeBubbleFill = showBubbles && (!isThemeFullFrameInvert() || themeId == ThemeID::Blue);
-#endif
 
     std::vector<int> lineTop;
     lineTop.resize(cachedLines.size());
@@ -763,17 +686,6 @@ void drawTextMessageFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16
             int visualBottom = getDrawnLinePixelBottom(lineTop[b.end], cachedLines[b.end], isHeader[b.end]);
             int bottomY = visualBottom + BUBBLE_PAD_Y;
 
-            // On high-res screens, keep a 1px gap under the header
-            if (currentResolution == ScreenResolution::High) {
-                const int minTopY = contentTop + 1;
-                if (topY < minTopY) {
-                    // Preserve bubble height when we push it down from the header.
-                    const int shift = minTopY - topY;
-                    topY = minTopY;
-                    bottomY += shift;
-                }
-            }
-
             if (bi + 1 < blocks.size()) {
                 int nextHeaderIndex = (int)blocks[bi + 1].start;
                 int nextTop = lineTop[nextHeaderIndex];
@@ -823,56 +735,24 @@ void drawTextMessageFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16
                 const int by = topY;
                 const int bw = bubbleW;
                 const int bh = bubbleH;
-#if GRAPHICS_TFT_COLORING_ENABLED
-                const bool drawBubbleOutline = !useDarkModeBubbleFill;
-#else
-                const bool drawBubbleOutline = true;
-#endif
-#if GRAPHICS_TFT_COLORING_ENABLED
-                if (useDarkModeBubbleFill) {
-                    setDarkModeBubbleRoleColors(themeId, b.mine);
-                    registerRoundedBubbleFillRegion(bx, by, bw, bh, r);
-                }
-#endif
 
-                if (drawBubbleOutline) {
-                    // Draw the 4 corner arcs using drawCircleQuads
-                    display->drawCircleQuads(bx + r, by + r, r, 0x2);                   // Top-left
-                    display->drawCircleQuads(bx + bw - r - 1, by + r, r, 0x1);          // Top-right
-                    display->drawCircleQuads(bx + r, by + bh - r - 1, r, 0x4);          // Bottom-left
-                    display->drawCircleQuads(bx + bw - r - 1, by + bh - r - 1, r, 0x8); // Bottom-right
+                // Draw the 4 corner arcs using drawCircleQuads
+                display->drawCircleQuads(bx + r, by + r, r, 0x2);                   // Top-left
+                display->drawCircleQuads(bx + bw - r - 1, by + r, r, 0x1);          // Top-right
+                display->drawCircleQuads(bx + r, by + bh - r - 1, r, 0x4);          // Bottom-left
+                display->drawCircleQuads(bx + bw - r - 1, by + bh - r - 1, r, 0x8); // Bottom-right
 
-                    // Draw the 4 edges between corners
-                    display->drawHorizontalLine(bx + r, by, bw - 2 * r);          // Top edge
-                    display->drawHorizontalLine(bx + r, by + bh - 1, bw - 2 * r); // Bottom edge
-                    display->drawVerticalLine(bx, by + r, bh - 2 * r);            // Left edge
-                    display->drawVerticalLine(bx + bw - 1, by + r, bh - 2 * r);   // Right edge
-                }
+                // Draw the 4 edges between corners
+                display->drawHorizontalLine(bx + r, by, bw - 2 * r);          // Top edge
+                display->drawHorizontalLine(bx + r, by + bh - 1, bw - 2 * r); // Bottom edge
+                display->drawVerticalLine(bx, by + r, bh - 2 * r);            // Left edge
+                display->drawVerticalLine(bx + bw - 1, by + r, bh - 2 * r);   // Right edge
             } else if (bubbleW > 1 && bubbleH > 1) {
                 // Fallback to simple rectangle for very small bubbles
-#if GRAPHICS_TFT_COLORING_ENABLED
-                const bool drawBubbleOutline = !useDarkModeBubbleFill;
-#else
-                const bool drawBubbleOutline = true;
-#endif
-#if GRAPHICS_TFT_COLORING_ENABLED
-                if (useDarkModeBubbleFill) {
-                    setDarkModeBubbleRoleColors(themeId, b.mine);
-                    registerTFTColorRegion(TFTColorRole::ActionMenuBody, bubbleX, topY, bubbleW, bubbleH);
-                }
-#endif
-                if (drawBubbleOutline) {
-                    display->drawRect(bubbleX, topY, bubbleW, bubbleH);
-                }
+                display->drawRect(bubbleX, topY, bubbleW, bubbleH);
             }
         }
     } // end if (showBubbles)
-#if GRAPHICS_TFT_COLORING_ENABLED
-    if (useDarkModeBubbleFill) {
-        // Restore theme role defaults so other screens keep their intended palette.
-        loadThemeDefaults();
-    }
-#endif
 
     // Render visible lines
     int lineY = yOffset;
@@ -892,7 +772,7 @@ void drawTextMessageFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16
                     headerX = x + textIndent;
                 }
                 graphics::UIRenderer::drawStringWithEmotes(display, headerX, lineY, cachedLines[i].c_str(), FONT_HEIGHT_SMALL, 1,
-                                                           true);
+                                                           false);
 
                 // Draw underline just under header text
                 int underlineY = lineY + FONT_HEIGHT_SMALL;

src/graphics/draw/NodeListRenderer.cpp

@@ -3,16 +3,11 @@
 #include "CompassRenderer.h"
 #include "NodeDB.h"
 #include "NodeListRenderer.h"
-#if !MESHTASTIC_EXCLUDE_STATUS
-#include "modules/StatusMessageModule.h"
-#endif
 #include "UIRenderer.h"
 #include "gps/GeoCoord.h"
 #include "gps/RTC.h" // for getTime() function
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTColorRegions.h"
-#include "graphics/TFTPalette.h"
 #include "graphics/images.h"
 #include "meshUtils.h"
 #include <algorithm>
@@ -97,41 +92,8 @@ std::string getSafeNodeName(OLEDDisplay *display, meshtastic_NodeInfoLite *node,
 
     // 1) Choose target candidate (long vs short) only if present
     const char *raw = nullptr;
-
-#if !MESHTASTIC_EXCLUDE_STATUS
-    // If long-name mode is enabled, and we have a recent status for this node,
-    // prefer "(short_name) statusText" as the raw candidate.
-    std::string composedFromStatus;
-    if (config.display.use_long_node_name && node && node->has_user && statusMessageModule) {
-        const auto &recent = statusMessageModule->getRecentReceived();
-        const StatusMessageModule::RecentStatus *found = nullptr;
-        for (auto it = recent.rbegin(); it != recent.rend(); ++it) {
-            if (it->fromNodeId == node->num && !it->statusText.empty()) {
-                found = &(*it);
-                break;
-            }
-        }
-
-        if (found) {
-            const char *shortName = node->user.short_name;
-            composedFromStatus.reserve(4 + (shortName ? std::strlen(shortName) : 0) + 1 + found->statusText.size());
-            composedFromStatus += "(";
-            if (shortName && *shortName) {
-                composedFromStatus += shortName;
-            }
-            composedFromStatus += ") ";
-            composedFromStatus += found->statusText;
-
-            raw = composedFromStatus.c_str(); // safe for now; we'll sanitize immediately into std::string
-        }
-    }
-#endif
-
-    // If we didn't compose from status, use normal long/short selection
-    if (!raw) {
-        if (node && node->has_user) {
-            raw = config.display.use_long_node_name ? node->user.long_name : node->user.short_name;
-        }
+    if (node && node->has_user) {
+        raw = config.display.use_long_node_name ? node->user.long_name : node->user.short_name;
     }
 
     // 2) Preserve UTF-8 names so emotes can be detected and rendered.
@@ -215,33 +177,6 @@ void drawScrollbar(OLEDDisplay *display, int visibleNodeRows, int totalEntries,
     }
 }
 
-static inline void applyFavoriteNodeNameColor(OLEDDisplay *display, const meshtastic_NodeInfoLite *node, const char *nodeName,
-                                              int16_t nameX, int16_t y, int nameMaxWidth)
-{
-    if (!display || !node || !node->is_favorite || !isTFTColoringEnabled() || !nodeName) {
-        return;
-    }
-
-    const int textWidth = UIRenderer::measureStringWithEmotes(display, nodeName);
-    const int regionWidth = min(textWidth, max(0, nameMaxWidth));
-    if (regionWidth <= 0) {
-        return;
-    }
-
-    // Node list rows can begin a couple of pixels inside header space.
-    // Clamp favorite-name color region below the header to avoid black overlap there.
-    const int16_t minContentY = static_cast<int16_t>(FONT_HEIGHT_SMALL + 1);
-    const int16_t regionY = max(y, minContentY);
-    const int16_t yClip = regionY - y;
-    const int16_t regionHeight = static_cast<int16_t>(FONT_HEIGHT_SMALL - yClip);
-    if (regionHeight <= 0) {
-        return;
-    }
-
-    setAndRegisterTFTColorRole(TFTColorRole::FavoriteNode, TFTPalette::Yellow, TFTPalette::Black, nameX, regionY, regionWidth,
-                               regionHeight);
-}
-
 // =============================
 // Entry Renderers
 // =============================
@@ -256,9 +191,6 @@ void drawEntryLastHeard(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int
     char nodeName[96];
     UIRenderer::truncateStringWithEmotes(display, getSafeNodeName(display, node, columnWidth).c_str(), nodeName, sizeof(nodeName),
                                          nameMaxWidth);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    applyFavoriteNodeNameColor(display, node, nodeName, nameX, y, nameMaxWidth);
-#endif
     bool isMuted = (node->bitfield & NODEINFO_BITFIELD_IS_MUTED_MASK) != 0;
 
     char timeStr[10];
@@ -307,20 +239,14 @@ void drawEntryHopSignal(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int
 
     int nameMaxWidth = getNodeNameMaxWidth(columnWidth, columnWidth - 25);
     int barsOffset = (currentResolution == ScreenResolution::High) ? (isLeftCol ? 20 : 24) : (isLeftCol ? 15 : 19);
-    constexpr int kBarCount = 4;
-    constexpr int kBarWidth = 2;
-    constexpr int kBarGap = 1;
+    int hopOffset = (currentResolution == ScreenResolution::High) ? (isLeftCol ? 21 : 29) : (isLeftCol ? 13 : 17);
 
     int barsXOffset = columnWidth - barsOffset;
-    int barsRightEdge = x + barsXOffset + ((kBarCount - 1) * (kBarWidth + kBarGap)) + kBarWidth;
 
     const int nameX = x + ((currentResolution == ScreenResolution::High) ? 6 : 3);
     char nodeName[96];
     UIRenderer::truncateStringWithEmotes(display, getSafeNodeName(display, node, columnWidth).c_str(), nodeName, sizeof(nodeName),
                                          nameMaxWidth);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    applyFavoriteNodeNameColor(display, node, nodeName, nameX, y, nameMaxWidth);
-#endif
     bool isMuted = (node->bitfield & NODEINFO_BITFIELD_IS_MUTED_MASK) != 0;
 
     display->setTextAlignment(TEXT_ALIGN_LEFT);
@@ -342,48 +268,28 @@ void drawEntryHopSignal(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int
         }
     }
 
-    const bool isZeroHop = node->has_hops_away && node->hops_away == 0;
+    // Draw signal strength bars
+    int bars = (node->snr > 5) ? 4 : (node->snr > 0) ? 3 : (node->snr > -5) ? 2 : (node->snr > -10) ? 1 : 0;
+    int barWidth = 2;
+    int barStartX = x + barsXOffset;
+    int barStartY = y + 1 + (FONT_HEIGHT_SMALL / 2) + 2;
 
-    // Show signal only for direct neighbors (0 hops)
-    if (isZeroHop) {
-        int bars = (node->snr > 5) ? 4 : (node->snr > 0) ? 3 : (node->snr > -5) ? 2 : (node->snr > -10) ? 1 : 0;
-        int barStartX = x + barsXOffset;
-        int barStartY = y + 1 + (FONT_HEIGHT_SMALL / 2) + 2;
-
-        if (bars > 0) {
-            uint16_t signalBarsColor = TFTPalette::Bad;
-            if (bars >= 3) {
-                signalBarsColor = TFTPalette::Good;
-            } else if (bars == 2) {
-                signalBarsColor = TFTPalette::Medium;
-            }
-
-            // Highest bar reaches 6 px in this renderer.
-            setAndRegisterTFTColorRole(TFTColorRole::SignalBars, signalBarsColor, TFTPalette::Black, barStartX, barStartY - 6,
-                                       (kBarCount * kBarWidth) + ((kBarCount - 1) * kBarGap), 6);
-        }
-
-        for (int b = 0; b < kBarCount; b++) {
-            if (b < bars) {
-                int height = (b * 2);
-                display->fillRect(barStartX + (b * (kBarWidth + kBarGap)), barStartY - height, kBarWidth, height);
-            }
+    for (int b = 0; b < 4; b++) {
+        if (b < bars) {
+            int height = (b * 2);
+            display->fillRect(barStartX + (b * (barWidth + 1)), barStartY - height, barWidth, height);
         }
     }
 
-    // Draw hop count + hop icon
-    if (node->has_hops_away && node->hops_away > 0) {
-        char hopCount[6];
-        snprintf(hopCount, sizeof(hopCount), "%d", node->hops_away);
+    // Draw hop count
+    char hopStr[6] = "";
+    if (node->has_hops_away && node->hops_away > 0)
+        snprintf(hopStr, sizeof(hopStr), "[%d]", node->hops_away);
 
-        const int hopCountWidth = display->getStringWidth(hopCount);
-        const int gap = 1;
-        const int totalWidth = hopCountWidth + gap + hop_width;
-        const int hopX = barsRightEdge - totalWidth;
-        const int iconY = y + (FONT_HEIGHT_SMALL - hop_height) / 2;
-
-        display->drawString(hopX, y, hopCount);
-        display->drawXbm(hopX + hopCountWidth + gap, iconY, hop_width, hop_height, hop);
+    if (hopStr[0] != '\0') {
+        int rightEdge = x + columnWidth - hopOffset;
+        int textWidth = display->getStringWidth(hopStr);
+        display->drawString(rightEdge - textWidth, y, hopStr);
     }
 }
 
@@ -398,9 +304,6 @@ void drawNodeDistance(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16
     char nodeName[96];
     UIRenderer::truncateStringWithEmotes(display, getSafeNodeName(display, node, columnWidth).c_str(), nodeName, sizeof(nodeName),
                                          nameMaxWidth);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    applyFavoriteNodeNameColor(display, node, nodeName, nameX, y, nameMaxWidth);
-#endif
     bool isMuted = (node->bitfield & NODEINFO_BITFIELD_IS_MUTED_MASK) != 0;
     char distStr[10] = "";
 
@@ -470,13 +373,14 @@ void drawNodeDistance(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16
         }
     }
 
-    const char *distanceLabel = (strlen(distStr) > 0) ? distStr : "?";
-    int offset = (currentResolution == ScreenResolution::High)
-                     ? (isLeftCol ? 7 : 10) // Offset for Wide Screens (Left Column:Right Column)
-                     : (isLeftCol ? 4 : 7); // Offset for Narrow Screens (Left Column:Right Column)
-    int rightEdge = x + columnWidth - offset;
-    int textWidth = display->getStringWidth(distanceLabel);
-    display->drawString(rightEdge - textWidth, y, distanceLabel);
+    if (strlen(distStr) > 0) {
+        int offset = (currentResolution == ScreenResolution::High)
+                         ? (isLeftCol ? 7 : 10) // Offset for Wide Screens (Left Column:Right Column)
+                         : (isLeftCol ? 4 : 7); // Offset for Narrow Screens (Left Column:Right Column)
+        int rightEdge = x + columnWidth - offset;
+        int textWidth = display->getStringWidth(distStr);
+        display->drawString(rightEdge - textWidth, y, distStr);
+    }
 }
 
 void drawEntryDynamic_Nodes(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth)
@@ -506,9 +410,6 @@ void drawEntryCompass(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16
     char nodeName[96];
     UIRenderer::truncateStringWithEmotes(display, getSafeNodeName(display, node, columnWidth).c_str(), nodeName, sizeof(nodeName),
                                          nameMaxWidth);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    applyFavoriteNodeNameColor(display, node, nodeName, nameX, y, nameMaxWidth);
-#endif
     bool isMuted = (node->bitfield & NODEINFO_BITFIELD_IS_MUTED_MASK) != 0;
 
     display->setTextAlignment(TEXT_ALIGN_LEFT);
@@ -530,8 +431,8 @@ void drawEntryCompass(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16
     }
 }
 
-void drawCompassArrow(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth,
-                      float myHeadingRadian, double userLat, double userLon)
+void drawCompassArrow(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth, float myHeading,
+                      double userLat, double userLon)
 {
     if (!nodeDB->hasValidPosition(node))
         return;
@@ -545,11 +446,11 @@ void drawCompassArrow(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16
     double nodeLat = node->position.latitude_i * 1e-7;
     double nodeLon = node->position.longitude_i * 1e-7;
     float bearing = GeoCoord::bearing(userLat, userLon, nodeLat, nodeLon);
-    float relativeBearing = CompassRenderer::adjustBearingForCompassMode(bearing, myHeadingRadian);
-    float relativeBearingDeg = CompassRenderer::radiansToDegrees360(relativeBearing);
+    float bearingToNode = RAD_TO_DEG * bearing;
+    float relativeBearing = fmod((bearingToNode - myHeading + 360), 360);
     // Shrink size by 2px
     int size = FONT_HEIGHT_SMALL - 5;
-    CompassRenderer::drawArrowToNode(display, centerX, centerY, size, relativeBearingDeg);
+    CompassRenderer::drawArrowToNode(display, centerX, centerY, size, relativeBearing);
     /*
     float angle = relativeBearing * DEG_TO_RAD;
     float halfSize = size / 2.0;
@@ -579,27 +480,12 @@ void drawCompassArrow(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16
     */
 }
 
-void drawCompassUnknown(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth, float, double,
-                        double)
-{
-    if (!nodeDB->hasValidPosition(node))
-        return;
-
-    bool isLeftCol = (x < SCREEN_WIDTH / 2);
-    int arrowXOffset = (currentResolution == ScreenResolution::High) ? (isLeftCol ? 22 : 24) : (isLeftCol ? 12 : 18);
-    int centerX = x + columnWidth - arrowXOffset;
-
-    display->setFont(FONT_SMALL);
-    display->setTextAlignment(TEXT_ALIGN_CENTER);
-    display->drawString(centerX, y, "?");
-}
-
 // =============================
 // Main Screen Functions
 // =============================
 
 void drawNodeListScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y, const char *title,
-                        EntryRenderer renderer, NodeExtrasRenderer extras, float headingRadian, double lat, double lon)
+                        EntryRenderer renderer, NodeExtrasRenderer extras, float heading, double lat, double lon)
 {
     const int COMMON_HEADER_HEIGHT = FONT_HEIGHT_SMALL - 1;
     const int rowYOffset = FONT_HEIGHT_SMALL - 3;
@@ -684,7 +570,7 @@ void drawNodeListScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t
         renderer(display, node, xPos, yPos, columnWidth);
 
         if (extras)
-            extras(display, node, xPos, yPos, columnWidth, headingRadian, lat, lon);
+            extras(display, node, xPos, yPos, columnWidth, heading, lat, lon);
 
         lastNodeY = max(lastNodeY, yPos + FONT_HEIGHT_SMALL);
         yOffset += rowYOffset;
@@ -764,9 +650,6 @@ void drawNodeListScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t
         display->fillRect(boxLeft, boxTop + boxHeight - 1, 1, 1);
         display->fillRect(boxLeft + boxWidth - 1, boxTop + boxHeight - 1, 1, 1);
         display->setColor(WHITE);
-#if GRAPHICS_TFT_COLORING_ENABLED
-        registerTFTActionMenuRegions(boxLeft, boxTop, boxWidth, boxHeight);
-#endif
 
         // Text
         display->drawString(boxLeft + padding, boxTop + padding, buf);
@@ -882,13 +765,9 @@ void drawDistanceScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t
 #endif
 void drawNodeListWithCompasses(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y)
 {
-    float headingRadian = 0.0f;
+    float heading = 0;
+    bool validHeading = false;
     auto ourNode = nodeDB->getMeshNode(nodeDB->getNodeNum());
-    if (!ourNode || !nodeDB->hasValidPosition(ourNode)) {
-        drawNodeListScreen(display, state, x, y, "Bearings", drawEntryCompass, drawCompassUnknown, headingRadian, 0.0, 0.0);
-        return;
-    }
-
     double lat = DegD(ourNode->position.latitude_i);
     double lon = DegD(ourNode->position.longitude_i);
 
@@ -900,12 +779,21 @@ void drawNodeListWithCompasses(OLEDDisplay *display, OLEDDisplayUiState *state,
         lastSwitchTime = now;
     }
 #endif
-    if (!CompassRenderer::getHeadingRadians(lat, lon, headingRadian)) {
-        drawNodeListScreen(display, state, x, y, "Bearings", drawEntryCompass, drawCompassUnknown, headingRadian, lat, lon);
-        return;
-    }
+    if (uiconfig.compass_mode != meshtastic_CompassMode_FREEZE_HEADING) {
+#if HAS_GPS
+        if (screen->hasHeading()) {
+            heading = screen->getHeading(); // degrees
+            validHeading = true;
+        } else {
+            heading = screen->estimatedHeading(lat, lon);
+            validHeading = !isnan(heading);
+        }
+#endif
 
-    drawNodeListScreen(display, state, x, y, "Bearings", drawEntryCompass, drawCompassArrow, headingRadian, lat, lon);
+        if (!validHeading)
+            return;
+    }
+    drawNodeListScreen(display, state, x, y, "Bearings", drawEntryCompass, drawCompassArrow, heading, lat, lon);
 }
 
 /// Draw a series of fields in a column, wrapping to multiple columns if needed

src/graphics/draw/NodeListRenderer.h

@@ -32,7 +32,7 @@ enum ListMode_Location { MODE_DISTANCE = 0, MODE_BEARING = 1, MODE_COUNT_LOCATIO
 
 // Main node list screen function
 void drawNodeListScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y, const char *title,
-                        EntryRenderer renderer, NodeExtrasRenderer extras = nullptr, float headingRadian = 0, double lat = 0,
+                        EntryRenderer renderer, NodeExtrasRenderer extras = nullptr, float heading = 0, double lat = 0,
                         double lon = 0);
 
 // Entry renderers
@@ -43,8 +43,8 @@ void drawEntryDynamic_Nodes(OLEDDisplay *display, meshtastic_NodeInfoLite *node,
 void drawEntryCompass(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth);
 
 // Extras renderers
-void drawCompassArrow(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth,
-                      float myHeadingRadian, double userLat, double userLon);
+void drawCompassArrow(OLEDDisplay *display, meshtastic_NodeInfoLite *node, int16_t x, int16_t y, int columnWidth, float myHeading,
+                      double userLat, double userLon);
 
 // Screen frame functions
 void drawLastHeardScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);

src/graphics/draw/NotificationRenderer.cpp

@@ -7,8 +7,6 @@
 #include "UIRenderer.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
-#include "graphics/TFTColorRegions.h"
-#include "graphics/TFTPalette.h"
 #include "graphics/images.h"
 #include "input/RotaryEncoderInterruptImpl1.h"
 #include "input/UpDownInterruptImpl1.h"
@@ -610,9 +608,6 @@ void NotificationRenderer::drawNotificationBox(OLEDDisplay *display, OLEDDisplay
     display->fillRect(boxLeft, boxTop + boxHeight - 1, 1, 1);
     display->fillRect(boxLeft + boxWidth - 1, boxTop + boxHeight - 1, 1, 1);
     display->setColor(WHITE);
-#if GRAPHICS_TFT_COLORING_ENABLED
-    registerTFTActionMenuRegions(boxLeft, boxTop, boxWidth, boxHeight);
-#endif
 
     // Draw Content
     int16_t lineY = boxTop + vPadding;
@@ -635,21 +630,7 @@ void NotificationRenderer::drawNotificationBox(OLEDDisplay *display, OLEDDisplay
             if (strchr(lineBuffer, 'p') || strchr(lineBuffer, 'g') || strchr(lineBuffer, 'y') || strchr(lineBuffer, 'j')) {
                 background_yOffset = -1;
             }
-            const int16_t titleBarY = boxTop + 1;
-            const int16_t titleBarHeight = effectiveLineHeight - background_yOffset;
-            display->fillRect(boxLeft, titleBarY, boxWidth, titleBarHeight);
-#if GRAPHICS_TFT_COLORING_ENABLED
-            if (alertBannerOptions > 0) {
-                const uint16_t titleTextColor =
-                    (getActiveTheme().id == ThemeID::DefaultLight) ? TFTPalette::Black : getThemeHeaderText();
-                // Keep title role away from border/corner pixels so rounded-corner masks are not remapped to the title text
-                // color.
-                if (boxWidth > 2 && titleBarHeight > 0) {
-                    setAndRegisterTFTColorRole(TFTColorRole::ActionMenuTitle, getThemeHeaderBg(), titleTextColor, boxLeft + 1,
-                                               titleBarY, boxWidth - 2, titleBarHeight);
-                }
-            }
-#endif
+            display->fillRect(boxLeft, boxTop + 1, boxWidth, effectiveLineHeight - background_yOffset);
             display->setColor(BLACK);
             int yOffset = 3;
             if (current_notification_type == notificationTypeEnum::node_picker) {
@@ -669,7 +650,6 @@ void NotificationRenderer::drawNotificationBox(OLEDDisplay *display, OLEDDisplay
                 const int barSpacing = 2;
                 const int barHeightStep = 2;
                 const int gap = 6;
-                const int maxBarHeight = totalBars * barHeightStep;
 
                 int textWidth = display->getStringWidth(lineBuffer, strlen(lineBuffer), true);
                 int barsWidth = totalBars * barWidth + (totalBars - 1) * barSpacing + gap;
@@ -684,20 +664,6 @@ void NotificationRenderer::drawNotificationBox(OLEDDisplay *display, OLEDDisplay
 
                 int baseX = groupStartX + textWidth + gap;
                 int baseY = lineY + effectiveLineHeight - 1;
-#if GRAPHICS_TFT_COLORING_ENABLED
-                if (graphics::bannerSignalBars > 0) {
-                    uint16_t signalBarsColor = TFTPalette::Medium;
-                    if (graphics::bannerSignalBars <= 1) {
-                        signalBarsColor = TFTPalette::Bad;
-                    } else if (graphics::bannerSignalBars >= 4) {
-                        signalBarsColor = TFTPalette::Good;
-                    }
-                    const int activeBars = min(graphics::bannerSignalBars, totalBars);
-                    const int regionWidth = activeBars * barWidth + (activeBars - 1) * barSpacing;
-                    setAndRegisterTFTColorRole(TFTColorRole::SignalBars, signalBarsColor, TFTPalette::Black, baseX,
-                                               baseY - maxBarHeight, regionWidth, maxBarHeight);
-                }
-#endif
                 for (int b = 0; b < totalBars; b++) {
                     int barHeight = (b + 1) * barHeightStep;
                     int x = baseX + b * (barWidth + barSpacing);

src/graphics/draw/UIRenderer.h

@@ -50,12 +50,10 @@ class UIRenderer
     // Navigation bar overlay
     static void drawNavigationBar(OLEDDisplay *display, OLEDDisplayUiState *state);
 
-    static void drawFavoriteNode(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);
+    static void drawNodeInfo(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);
 
     static void drawDeviceFocused(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);
 
-    static void drawBootIconScreen(const char *upperMsg, OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);
-
     // Icon and screen drawing functions
     static void drawIconScreen(const char *upperMsg, OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);
 

src/graphics/niche/Drivers/EInk/ED047TC1.cpp

@@ -25,116 +25,6 @@
 
 using namespace NicheGraphics::Drivers;
 
-#if defined(T5_S3_EPAPER_PRO_V2)
-// FastEPD helper symbols are defined in FastEPD.inl with C++ linkage.
-extern void bbepPCA9535DigitalWrite(uint8_t pin, uint8_t value);
-extern uint8_t bbepPCA9535DigitalRead(uint8_t pin);
-extern int bbepI2CWrite(unsigned char iAddr, unsigned char *pData, int iLen);
-extern int bbepI2CReadRegister(unsigned char iAddr, unsigned char u8Register, unsigned char *pData, int iLen);
-#endif
-
-namespace
-{
-#if defined(T5_S3_EPAPER_PRO_V2)
-// FastEPD default V2 power callback blocks forever waiting for PWRGOOD.
-// Replace it with a timeout-safe version so boot never deadlocks.
-int safeEPDiyV7EinkPower(void *pBBEP, int bOn)
-{
-    static bool warnedPgood = false;
-    static bool warnedTpsPg = false;
-    static bool warnedTpsWrite = false;
-
-    FASTEPDSTATE *pState = static_cast<FASTEPDSTATE *>(pBBEP);
-    if (!pState) {
-        return BBEP_ERROR_BAD_PARAMETER;
-    }
-
-    if (bOn == pState->pwr_on) {
-        return BBEP_SUCCESS;
-    }
-
-    if (bOn) {
-        bbepPCA9535DigitalWrite(8, 1);  // OE on
-        bbepPCA9535DigitalWrite(9, 1);  // GMOD on
-        bbepPCA9535DigitalWrite(13, 1); // WAKEUP on
-        bbepPCA9535DigitalWrite(11, 1); // PWRUP on
-        bbepPCA9535DigitalWrite(12, 1); // VCOM CTRL on
-        delay(1);
-
-        const uint32_t pgoodStart = millis();
-        bool pgoodSeen = false;
-        while (!bbepPCA9535DigitalRead(14)) { // CFG_PIN_PWRGOOD
-            if ((millis() - pgoodStart) > 1200) {
-                if (!warnedPgood) {
-                    LOG_WARN("ED047TC1: PWRGOOD timeout, continuing with fallback power-on path");
-                    warnedPgood = true;
-                }
-                break;
-            }
-            delay(1);
-        }
-        if (bbepPCA9535DigitalRead(14)) {
-            pgoodSeen = true;
-        }
-
-        uint8_t ucTemp[4] = {0};
-        ucTemp[0] = 0x01; // TPS_REG_ENABLE
-        ucTemp[1] = 0x3f; // enable rails
-        const int tpsEnableRc = bbepI2CWrite(0x68, ucTemp, 2);
-
-        const int vcom = pState->iVCOM / -10;
-        ucTemp[0] = 3; // VCOM registers 3+4 (L + H)
-        ucTemp[1] = static_cast<uint8_t>(vcom);
-        ucTemp[2] = static_cast<uint8_t>(vcom >> 8);
-        const int tpsVcomRc = bbepI2CWrite(0x68, ucTemp, 3);
-        if ((tpsEnableRc == 0 || tpsVcomRc == 0) && !warnedTpsWrite) {
-            LOG_WARN("ED047TC1: TPS write did not ACK, continuing with fallback");
-            warnedTpsWrite = true;
-        }
-
-        int iTimeout = 0;
-        uint8_t u8Value = 0;
-        while (iTimeout < 220 && ((u8Value & 0xfa) != 0xfa)) {
-            bbepI2CReadRegister(0x68, 0x0F, &u8Value, 1); // TPS_REG_PG
-            iTimeout++;
-            delay(1);
-        }
-        if (iTimeout >= 220 && !warnedTpsPg) {
-            if (pgoodSeen) {
-                LOG_WARN("ED047TC1: TPS power-good register timeout, panel may still work");
-            } else {
-                LOG_WARN("ED047TC1: TPS power-good register timeout after PWRGOOD fallback");
-            }
-            warnedTpsPg = true;
-        }
-
-        pState->pwr_on = 1;
-    } else {
-        bbepPCA9535DigitalWrite(8, 0);  // OE off
-        bbepPCA9535DigitalWrite(9, 0);  // GMOD off
-        bbepPCA9535DigitalWrite(11, 0); // PWRUP off
-        bbepPCA9535DigitalWrite(12, 0); // VCOM CTRL off
-        delay(1);
-        bbepPCA9535DigitalWrite(13, 0); // WAKEUP off
-        pState->pwr_on = 0;
-    }
-
-    return BBEP_SUCCESS;
-}
-#endif
-
-class SafeFastEPD : public FASTEPD
-{
-  public:
-    void installSafePowerHandler()
-    {
-#if defined(T5_S3_EPAPER_PRO_V2)
-        _state.pfnEinkPower = safeEPDiyV7EinkPower;
-#endif
-    }
-};
-} // namespace
-
 void ED047TC1::begin(SPIClass *spi, uint8_t pin_dc, uint8_t pin_cs, uint8_t pin_busy, uint8_t pin_rst)
 {
     // Parallel display — SPI parameters are not used
@@ -144,48 +34,24 @@ void ED047TC1::begin(SPIClass *spi, uint8_t pin_dc, uint8_t pin_cs, uint8_t pin_
     (void)pin_busy;
     (void)pin_rst;
 
-    SafeFastEPD *safeEpaper = new SafeFastEPD;
-    epaper = safeEpaper;
+    epaper = new FASTEPD;
 
-    int initRc = BBEP_ERROR_BAD_PARAMETER;
 #if defined(T5_S3_EPAPER_PRO_V1)
-    initRc = epaper->initPanel(BB_PANEL_LILYGO_T5PRO, 28000000);
+    epaper->initPanel(BB_PANEL_LILYGO_T5PRO, 28000000);
 #elif defined(T5_S3_EPAPER_PRO_V2)
-    initRc = epaper->initPanel(BB_PANEL_LILYGO_T5PRO_V2, 28000000);
+    epaper->initPanel(BB_PANEL_LILYGO_T5PRO_V2, 28000000);
     // Initialize all PCA9535 port-0 pins as outputs / HIGH
     for (int i = 0; i < 8; i++) {
         epaper->ioPinMode(i, OUTPUT);
         epaper->ioWrite(i, HIGH);
     }
-    // On this board, the physical side key is labeled IO48; electrically it maps to PCA9535 IO12 (bit 2 on port-1).
-    // FastEPD's generic V7 init drives 8..13 as outputs; force IO12 back to input
-    // so variant touch-control polling can read the key reliably.
-    epaper->ioPinMode(10, INPUT);
 #else
 #error "ED047TC1 driver: unsupported variant — define T5_S3_EPAPER_PRO_V1 or T5_S3_EPAPER_PRO_V2"
 #endif
 
-    if (initRc != BBEP_SUCCESS) {
-        LOG_ERROR("ED047TC1 initPanel failed rc=%d", initRc);
-        return;
-    }
-
-    safeEpaper->installSafePowerHandler();
-
-    const int modeRc = epaper->setMode(BB_MODE_1BPP);
-    if (modeRc != BBEP_SUCCESS) {
-        LOG_WARN("ED047TC1 setMode failed rc=%d", modeRc);
-    }
-
-    const int clearRc = epaper->clearWhite();
-    if (clearRc != BBEP_SUCCESS) {
-        LOG_WARN("ED047TC1 clearWhite failed rc=%d", clearRc);
-    }
-
-    const int fullRc = epaper->fullUpdate(true); // Blocking initial clear
-    if (fullRc != BBEP_SUCCESS) {
-        LOG_WARN("ED047TC1 initial fullUpdate failed rc=%d", fullRc);
-    }
+    epaper->setMode(BB_MODE_1BPP);
+    epaper->clearWhite();
+    epaper->fullUpdate(true); // Blocking initial clear
 }
 
 void ED047TC1::update(uint8_t *imageData, UpdateTypes type)
@@ -245,8 +111,9 @@ void ED047TC1::update(uint8_t *imageData, UpdateTypes type)
         epaper->fullUpdate(CLEAR_SLOW, false);
         epaper->backupPlane(); // Sync pPrevious so next partialUpdate has a correct baseline
     } else {
-        // FAST: true partial update - compares pCurrent vs pPrevious and only applies
-        // update waveform to rows that changed. partialUpdate() updates pPrevious.
+        // FAST: true partial update — compares pCurrent vs pPrevious and only applies
+        // the update waveform to rows that actually changed. Unchanged rows get a neutral
+        // signal (no visible effect). partialUpdate() updates pPrevious internally.
         epaper->partialUpdate(false, 0, dstTotalRows - 1);
     }
 }

src/graphics/niche/InkHUD/Applet.h

@@ -104,15 +104,6 @@ class Applet : public GFX
     virtual void onFreeText(char c) {}
     virtual void onFreeTextDone() {}
     virtual void onFreeTextCancel() {}
-    // Absolute display-space touch point, for touch-friendly UI interactions.
-    // Return true if consumed.
-    virtual bool onTouchPoint(uint16_t x, uint16_t y, bool longPress)
-    {
-        (void)x;
-        (void)y;
-        (void)longPress;
-        return false;
-    }
     // List of inputs which can be subscribed to
     enum InputMask {      // | No Joystick  |     With Joystick     |
         BUTTON_SHORT = 1, // | Button Click | Joystick Center Click |

src/graphics/niche/InkHUD/Applets/Bases/Map/MapApplet.cpp

@@ -43,8 +43,8 @@ void InkHUD::MapApplet::onRender(bool full)
 
         // Add white halo outline first
         constexpr int outlinePad = 1;
-        int boxSize = fontSmall.lineHeight() + 2; // scale with font so digit fits
-        int radius = max(2, boxSize / 6);
+        int boxSize = 11;
+        int radius = 2; // rounded corner radius
 
         // White halo background
         fillRoundedRect(x, y, boxSize + (outlinePad * 2), boxSize + (outlinePad * 2), radius + 1, WHITE);
@@ -143,19 +143,17 @@ void InkHUD::MapApplet::onRender(bool full)
         int16_t centerX = X(0.5) + (self.eastMeters * metersToPx);
         int16_t centerY = Y(0.5) - (self.northMeters * metersToPx);
 
-        int16_t r = fontSmall.lineHeight() / 2; // scale marker with font
-
         // White fill background + halo
-        fillCircle(centerX, centerY, r + 2, WHITE);
-        drawCircle(centerX, centerY, r + 2, WHITE);
+        fillCircle(centerX, centerY, 8, WHITE); // big white base
+        drawCircle(centerX, centerY, 8, WHITE); // crisp edge
 
         // Black bullseye on top
-        drawCircle(centerX, centerY, r, BLACK);
-        fillCircle(centerX, centerY, max(2, r / 4), BLACK);
+        drawCircle(centerX, centerY, 6, BLACK);
+        fillCircle(centerX, centerY, 2, BLACK);
 
         // Crosshairs
-        drawLine(centerX - r - 2, centerY, centerX + r + 2, centerY, BLACK);
-        drawLine(centerX, centerY - r - 2, centerX, centerY + r + 2, BLACK);
+        drawLine(centerX - 8, centerY, centerX + 8, centerY, BLACK);
+        drawLine(centerX, centerY - 8, centerX, centerY + 8, BLACK);
     }
 }
 
@@ -384,9 +382,9 @@ void InkHUD::MapApplet::drawLabeledMarker(meshtastic_NodeInfoLite *node)
 
     constexpr uint16_t paddingH = 2;
     constexpr uint16_t paddingW = 4;
-    uint16_t paddingInnerW = 2;                      // Zero'd out if no text
-    uint16_t markerSizeMax = fontSmall.lineHeight(); // Scale cross with font
-    uint16_t markerSizeMin = max(5, fontSmall.lineHeight() / 3);
+    uint16_t paddingInnerW = 2;            // Zero'd out if no text
+    constexpr uint16_t markerSizeMax = 12; // Size of cross (if marker uses a cross)
+    constexpr uint16_t markerSizeMin = 5;
 
     int16_t textX;
     int16_t textY;

src/graphics/niche/InkHUD/Applets/System/AppSwitcher/AppSwitcherApplet.cpp

@@ -1,545 +0,0 @@
-#ifdef MESHTASTIC_INCLUDE_INKHUD
-
-#include "./AppSwitcherApplet.h"
-
-#include "graphics/niche/InkHUD/InkHUD.h"
-#include "graphics/niche/InkHUD/Tile.h"
-
-#include <algorithm>
-#include <cctype>
-
-using namespace NicheGraphics;
-
-namespace
-{
-static constexpr uint16_t BODY_MARGIN_X = 8;
-static constexpr uint16_t BODY_MARGIN_Y = 6;
-static constexpr uint16_t SLOT_GAP_X = 8;
-static constexpr uint16_t SLOT_GAP_Y = 8;
-static constexpr uint8_t ICON_RADIUS = 8;
-static constexpr uint16_t FOOTER_PAD = 4;
-static constexpr uint16_t LABEL_BOTTOM_PAD = 1;
-static constexpr uint16_t LABEL_GAP_Y = 1;
-static constexpr uint16_t TITLE_H_PAD = 8;
-
-static constexpr uint8_t GRID_COLS = 3;
-static constexpr uint8_t GRID_ROWS = 4;
-static constexpr uint8_t ICON_NATIVE_SIZE = 48;
-static constexpr uint8_t ICON_OUTLINE_STROKE = 1;
-
-enum class IconKind : uint8_t { GENERIC, ALL_MESSAGES, DMS, CHANNEL, POSITIONS, RECENTS, HEARD, FAVORITES };
-
-struct GridLayout {
-    uint16_t footerH = 0;
-    uint16_t bodyTop = 0;
-    uint16_t bodyBottom = 0;
-    uint16_t slotW = 0;
-    uint16_t slotH = 0;
-    uint16_t iconBox = 0;
-};
-
-/*
- * Icons sourced from Material Design Icons PNG set (Apache 2.0):
- * https://github.com/material-icons/material-icons-png
- *
- * Families used: outline-2x (48x48)
- * apps, markunread, chat, forum, place, history, hearing, star_border
- */
-static constexpr uint64_t icon_generic_apps[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL,
-    0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL,
-    0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL,
-    0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x00FF0FF0FF00ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_all_messages[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x07FFFFFFFFE0ULL, 0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL,
-    0x0FC0000003F0ULL, 0x0FE0000007F0ULL, 0x0FF800001FF0ULL, 0x0FFE00007FF0ULL, 0x0FFF0000FFF0ULL, 0x0F7FC003FEF0ULL,
-    0x0F1FE007F8F0ULL, 0x0F07F81FE0F0ULL, 0x0F03FE7FC0F0ULL, 0x0F00FFFF00F0ULL, 0x0F007FFE00F0ULL, 0x0F001FF800F0ULL,
-    0x0F0007E000F0ULL, 0x0F0003C000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL,
-    0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL,
-    0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL, 0x07FFFFFFFFE0ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_dms[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x07FFFFFFFFE0ULL, 0x0FFFFFFFFFF0ULL,
-    0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL,
-    0x0F0FFFFFF0F0ULL, 0x0F0FFFFFF0F0ULL, 0x0F0FFFFFF0F0ULL, 0x0F0FFFFFF0F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL,
-    0x0F0FFFFFF0F0ULL, 0x0F0FFFFFF0F0ULL, 0x0F0FFFFFF0F0ULL, 0x0F0FFFFFF0F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL,
-    0x0F0FFFF000F0ULL, 0x0F0FFFF000F0ULL, 0x0F0FFFF000F0ULL, 0x0F0FFFF000F0ULL, 0x0F00000000F0ULL, 0x0F00000000F0ULL,
-    0x0F00000000F0ULL, 0x0F00000000F0ULL, 0x0F7FFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFF0ULL, 0x0FFFFFFFFFE0ULL,
-    0x0FF000000000ULL, 0x0FE000000000ULL, 0x0FC000000000ULL, 0x0F8000000000ULL, 0x0F0000000000ULL, 0x0E0000000000ULL,
-    0x0C0000000000ULL, 0x080000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_channel[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x0FFFFFFFC000ULL, 0x0FFFFFFFC000ULL,
-    0x0FFFFFFFC000ULL, 0x0FFFFFFFC000ULL, 0x0F000003C000ULL, 0x0F000003C000ULL, 0x0F000003C000ULL, 0x0F000003C000ULL,
-    0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F000003C3F0ULL,
-    0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F000003C3F0ULL, 0x0F7FFFFFC3F0ULL, 0x0FFFFFFFC3F0ULL,
-    0x0FFFFFFFC3F0ULL, 0x0FFFFFFFC3F0ULL, 0x0FF0000003F0ULL, 0x0FE0000003F0ULL, 0x0FC0000003F0ULL, 0x0F80000003F0ULL,
-    0x0F0FFFFFFFF0ULL, 0x0E0FFFFFFFF0ULL, 0x0C0FFFFFFFF0ULL, 0x080FFFFFFFF0ULL, 0x000FFFFFFFF0ULL, 0x000FFFFFFFF0ULL,
-    0x000000000FF0ULL, 0x0000000007F0ULL, 0x0000000003F0ULL, 0x0000000001F0ULL, 0x0000000000F0ULL, 0x000000000070ULL,
-    0x000000000030ULL, 0x000000000010ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_positions[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x00001FF80000ULL, 0x00007FFE0000ULL,
-    0x0001FFFF8000ULL, 0x0003FFFFC000ULL, 0x0007FFFFE000ULL, 0x000FF00FF000ULL, 0x000FC003F000ULL, 0x001F8001F800ULL,
-    0x001F0000F800ULL, 0x003F07E0FC00ULL, 0x003E0FF07C00ULL, 0x003E1FF87C00ULL, 0x003E1FF87C00ULL, 0x003E1FF87C00ULL,
-    0x003E1FF87C00ULL, 0x003E1FF87C00ULL, 0x003E1FF87C00ULL, 0x003E0FF07C00ULL, 0x003E07E07C00ULL, 0x001F0000F800ULL,
-    0x001F0000F800ULL, 0x001F8001F800ULL, 0x000F8001F000ULL, 0x000FC003F000ULL, 0x0007C003E000ULL, 0x0007E007E000ULL,
-    0x0003F00FC000ULL, 0x0003F00FC000ULL, 0x0001F81F8000ULL, 0x0001FC3F8000ULL, 0x0000FC3F0000ULL, 0x00007E7E0000ULL,
-    0x00003FFC0000ULL, 0x00003FFC0000ULL, 0x00001FF80000ULL, 0x00000FF00000ULL, 0x00000FF00000ULL, 0x000007E00000ULL,
-    0x000003C00000ULL, 0x000001800000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_recents[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-    0x00000FFF0000ULL, 0x00003FFFC000ULL, 0x0000FFFFF000ULL, 0x0001FFFFF800ULL, 0x0007FFFFFE00ULL, 0x000FF801FF00ULL,
-    0x000FE0007F00ULL, 0x001FC0003F80ULL, 0x003F00000FC0ULL, 0x003F00000FC0ULL, 0x007E00E007E0ULL, 0x007C00E003E0ULL,
-    0x00FC00E003F0ULL, 0x00F800E001F0ULL, 0x00F800E001F0ULL, 0x00F800E001F0ULL, 0x00F800E001F0ULL, 0x00F800E001F0ULL,
-    0x3FFFC0F001F0ULL, 0x1FFF80FC01F0ULL, 0x0FFF00FF01F0ULL, 0x07FE003F81F0ULL, 0x03FC001FC1F0ULL, 0x01F80007C3F0ULL,
-    0x00F0000183E0ULL, 0x0060000007E0ULL, 0x000000000FC0ULL, 0x000000000FC0ULL, 0x0001C0003F80ULL, 0x0003E0007F00ULL,
-    0x0007F801FF00ULL, 0x0007FFFFFE00ULL, 0x0001FFFFF800ULL, 0x0000FFFFF000ULL, 0x00003FFFC000ULL, 0x00000FFF0000ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_heard[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000800000000ULL, 0x001C00000000ULL, 0x003E01FF8000ULL, 0x007F07FFE000ULL,
-    0x007E1FFFF800ULL, 0x00FC3FFFFC00ULL, 0x00F87FFFFE00ULL, 0x01F8FF00FF00ULL, 0x01F0FC003F00ULL, 0x01F1F8001F80ULL,
-    0x03E1F0000F80ULL, 0x03E3F07E0FC0ULL, 0x03E3E0FF07C0ULL, 0x03E3E1FF87C0ULL, 0x03E3E1FF87C0ULL, 0x03E3E1FF87C0ULL,
-    0x03E3E1FF8000ULL, 0x03E3E1FF8000ULL, 0x03E3E1FF8000ULL, 0x03E3E0FF0000ULL, 0x03E3F07E0000ULL, 0x03E1F0000000ULL,
-    0x01F1F8000000ULL, 0x01F1F8000000ULL, 0x01F8FC000000ULL, 0x00F87E000000ULL, 0x00FC7F800000ULL, 0x007E3FC00000ULL,
-    0x007F1FE00000ULL, 0x003E0FF00000ULL, 0x001C03F00000ULL, 0x000801F80000ULL, 0x000000F80000ULL, 0x000000FC0000ULL,
-    0x0000007C07C0ULL, 0x0000007E07C0ULL, 0x0000003F0FC0ULL, 0x0000003FFFC0ULL, 0x0000001FFF80ULL, 0x0000000FFF00ULL,
-    0x00000007FE00ULL, 0x00000003FC00ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-static constexpr uint64_t icon_favorites[48] = {
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000001800000ULL, 0x000001800000ULL,
-    0x000003C00000ULL, 0x000003C00000ULL, 0x000003C00000ULL, 0x000007E00000ULL, 0x000007E00000ULL, 0x00000FF00000ULL,
-    0x00000FF00000ULL, 0x00001FF80000ULL, 0x00001FF80000ULL, 0x00001E780000ULL, 0x00003E7C0000ULL, 0x003FFC3FFC00ULL,
-    0x0FFFFC3FFFF0ULL, 0x0FFFF81FFFF0ULL, 0x03FFF81FFFC0ULL, 0x01F800001F80ULL, 0x00FC00003F00ULL, 0x007E00007E00ULL,
-    0x003F8001FC00ULL, 0x001FC003F800ULL, 0x000FE007F000ULL, 0x0003E007C000ULL, 0x0003E007C000ULL, 0x0003C003C000ULL,
-    0x0003C003C000ULL, 0x0003C3C3C000ULL, 0x0007CFF3E000ULL, 0x00079FF9E000ULL, 0x0007FFFFE000ULL, 0x0007FE7FE000ULL,
-    0x000FFC3FF000ULL, 0x000FF00FF000ULL, 0x000FC003F000ULL, 0x000F8001F000ULL, 0x001E00007000ULL, 0x001800001800ULL,
-    0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL, 0x000000000000ULL,
-};
-
-using IconBitmap = const uint64_t *;
-
-IconBitmap iconBitmapForKind(IconKind kind)
-{
-    switch (kind) {
-    case IconKind::ALL_MESSAGES:
-        return icon_all_messages;
-    case IconKind::DMS:
-        return icon_dms;
-    case IconKind::CHANNEL:
-        return icon_channel;
-    case IconKind::POSITIONS:
-        return icon_positions;
-    case IconKind::RECENTS:
-        return icon_recents;
-    case IconKind::HEARD:
-        return icon_heard;
-    case IconKind::FAVORITES:
-        return icon_favorites;
-    case IconKind::GENERIC:
-    default:
-        return icon_generic_apps;
-    }
-}
-
-GridLayout computeLayout(const InkHUD::Applet *applet)
-{
-    GridLayout layout;
-
-    const uint16_t w = applet->width();
-    const uint16_t h = applet->height();
-
-    layout.footerH = InkHUD::Applet::fontSmall.lineHeight() + (FOOTER_PAD * 2);
-    layout.bodyTop = BODY_MARGIN_Y;
-    layout.bodyBottom = (h > (layout.footerH + BODY_MARGIN_Y)) ? (h - layout.footerH - BODY_MARGIN_Y) : layout.bodyTop;
-
-    const uint16_t bodyW = (w > (BODY_MARGIN_X * 2)) ? (w - (BODY_MARGIN_X * 2)) : 1;
-    const uint16_t bodyH = (layout.bodyBottom > layout.bodyTop) ? (layout.bodyBottom - layout.bodyTop) : 1;
-    const uint16_t gapsX = SLOT_GAP_X * (GRID_COLS - 1);
-    const uint16_t gapsY = SLOT_GAP_Y * (GRID_ROWS - 1);
-
-    layout.slotW = (bodyW > gapsX) ? ((bodyW - gapsX) / GRID_COLS) : 1;
-    layout.slotH = (bodyH > gapsY) ? ((bodyH - gapsY) / GRID_ROWS) : 1;
-
-    const uint16_t maxIconW = (layout.slotW > 6) ? (layout.slotW - 6) : layout.slotW;
-    const uint16_t maxIconH = (layout.slotH > (InkHUD::Applet::fontSmall.lineHeight() + LABEL_GAP_Y + LABEL_BOTTOM_PAD + 6))
-                                  ? (layout.slotH - InkHUD::Applet::fontSmall.lineHeight() - LABEL_GAP_Y - LABEL_BOTTOM_PAD - 6)
-                                  : layout.slotH / 2;
-    layout.iconBox = std::max<uint16_t>(20, std::min<uint16_t>(maxIconW, maxIconH));
-    return layout;
-}
-
-std::string lowercase(const char *name)
-{
-    if (!name)
-        return "";
-    std::string out(name);
-    std::transform(out.begin(), out.end(), out.begin(), [](unsigned char c) { return (char)std::tolower(c); });
-    return out;
-}
-
-IconKind iconKindForAppletName(const char *name)
-{
-    const std::string lower = lowercase(name);
-    if (lower.find("all message") != std::string::npos || lower.find("messages") != std::string::npos)
-        return IconKind::ALL_MESSAGES;
-    if (lower.find("dm") != std::string::npos)
-        return IconKind::DMS;
-    if (lower.find("channel") != std::string::npos)
-        return IconKind::CHANNEL;
-    if (lower.find("position") != std::string::npos)
-        return IconKind::POSITIONS;
-    if (lower.find("recent") != std::string::npos)
-        return IconKind::RECENTS;
-    if (lower.find("heard") != std::string::npos)
-        return IconKind::HEARD;
-    if (lower.find("favorite") != std::string::npos)
-        return IconKind::FAVORITES;
-    return IconKind::GENERIC;
-}
-
-void drawIconBitmapScaled(InkHUD::Applet *applet, IconBitmap bmp48, int16_t left, int16_t top, uint16_t boxSize, uint16_t color)
-{
-    if (!bmp48 || boxSize == 0)
-        return;
-
-    auto srcOn = [bmp48](int16_t sx, int16_t sy) -> bool {
-        if (sx < 0 || sy < 0 || sx >= ICON_NATIVE_SIZE || sy >= ICON_NATIVE_SIZE)
-            return false;
-        const uint64_t rowBits = bmp48[sy];
-        return (rowBits & (1ULL << (47 - sx))) != 0;
-    };
-
-    for (uint16_t y = 0; y < boxSize; y++) {
-        const uint8_t srcY = (uint8_t)((y * ICON_NATIVE_SIZE) / boxSize);
-        for (uint16_t x = 0; x < boxSize; x++) {
-            const uint8_t srcX = (uint8_t)((x * ICON_NATIVE_SIZE) / boxSize);
-            if (!srcOn(srcX, srcY))
-                continue;
-
-            const uint16_t w = std::min<uint16_t>(ICON_OUTLINE_STROKE, boxSize - x);
-            const uint16_t h = std::min<uint16_t>(ICON_OUTLINE_STROKE, boxSize - y);
-            applet->fillRect(left + x, top + y, w, h, color);
-        }
-    }
-}
-} // namespace
-
-InkHUD::AppSwitcherApplet::AppSwitcherApplet()
-{
-    alwaysRender = true;
-}
-
-void InkHUD::AppSwitcherApplet::rebuildActiveAppletList()
-{
-    activeAppletIndices.clear();
-
-    const auto &settings = inkhud->persistence->settings;
-    const uint8_t tileCount = std::min<uint8_t>(settings.userTiles.count, Persistence::MAX_TILES_GLOBAL);
-    const uint8_t focusedTile = (tileCount > 0) ? std::min<uint8_t>(settings.userTiles.focused, tileCount - 1) : 0;
-
-    // Applets displayed on other tiles should not be selectable here.
-    std::vector<bool> occupiedOnOtherTiles(inkhud->userApplets.size(), false);
-    for (uint8_t tile = 0; tile < tileCount; tile++) {
-        if (tile == focusedTile)
-            continue;
-
-        const uint8_t appletIndex = settings.userTiles.displayedUserApplet[tile];
-        if (appletIndex < occupiedOnOtherTiles.size())
-            occupiedOnOtherTiles[appletIndex] = true;
-    }
-
-    for (uint8_t i = 0; i < inkhud->userApplets.size(); i++) {
-        Applet *a = inkhud->userApplets.at(i);
-        if (a && a->isActive() && !occupiedOnOtherTiles[i])
-            activeAppletIndices.push_back(i);
-    }
-}
-
-uint8_t InkHUD::AppSwitcherApplet::cardsPerPage() const
-{
-    return GRID_COLS * GRID_ROWS;
-}
-
-uint8_t InkHUD::AppSwitcherApplet::currentPage() const
-{
-    const uint8_t cpp = cardsPerPage();
-    if (cpp == 0)
-        return 0;
-    return selectedIndex / cpp;
-}
-
-void InkHUD::AppSwitcherApplet::stepPage(int8_t delta)
-{
-    if (activeAppletIndices.empty())
-        return;
-
-    const uint8_t cpp = cardsPerPage();
-    const uint8_t pageCount = std::max<uint8_t>(1, (activeAppletIndices.size() + cpp - 1) / cpp);
-    int16_t nextPage = (int16_t)currentPage() + delta;
-    while (nextPage < 0)
-        nextPage += pageCount;
-    while (nextPage >= pageCount)
-        nextPage -= pageCount;
-
-    selectedIndex = std::min<uint8_t>((uint8_t)(nextPage * cpp), activeAppletIndices.size() - 1);
-    requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-}
-
-void InkHUD::AppSwitcherApplet::clampSelection()
-{
-    if (activeAppletIndices.empty()) {
-        selectedIndex = 0;
-        return;
-    }
-
-    if (selectedIndex >= activeAppletIndices.size())
-        selectedIndex = activeAppletIndices.size() - 1;
-}
-
-void InkHUD::AppSwitcherApplet::activateSelectedApplet()
-{
-    if (activeAppletIndices.empty()) {
-        sendToBackground();
-        requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-        return;
-    }
-
-    const uint8_t appletIndex = activeAppletIndices.at(selectedIndex);
-
-    sendToBackground();
-    inkhud->showApplet(appletIndex);
-}
-
-void InkHUD::AppSwitcherApplet::onForeground()
-{
-    rebuildActiveAppletList();
-    clampSelection();
-    handleInput = true;
-    lockRequests = true;
-    requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-}
-
-void InkHUD::AppSwitcherApplet::onBackground()
-{
-    handleInput = false;
-    lockRequests = false;
-
-    if (borrowedTileOwner)
-        borrowedTileOwner->bringToForeground();
-
-    Tile *t = getTile();
-    if (t)
-        t->assignApplet(borrowedTileOwner);
-    borrowedTileOwner = nullptr;
-}
-
-void InkHUD::AppSwitcherApplet::show(Tile *t)
-{
-    if (!t)
-        return;
-
-    borrowedTileOwner = t->getAssignedApplet();
-    if (borrowedTileOwner)
-        borrowedTileOwner->sendToBackground();
-
-    t->assignApplet(this);
-    bringToForeground();
-}
-
-void InkHUD::AppSwitcherApplet::onRender(bool full)
-{
-    (void)full;
-
-    const GridLayout layout = computeLayout(this);
-    const uint8_t cpp = cardsPerPage();
-    const uint8_t page = currentPage();
-    const uint8_t pageStart = page * cpp;
-
-    setFont(fontMedium);
-    setTextColor(BLACK);
-
-    fillRect(0, 0, width(), height(), WHITE);
-    drawRect(0, 0, width(), height(), BLACK);
-
-    if (activeAppletIndices.empty()) {
-        setFont(fontSmall);
-        printAt(width() / 2, height() / 2, "No Available Applets", CENTER, MIDDLE);
-        return;
-    }
-
-    for (uint8_t i = 0; i < cpp; i++) {
-        const uint8_t idx = pageStart + i;
-        if (idx >= activeAppletIndices.size())
-            break;
-
-        const uint8_t row = i / GRID_COLS;
-        const uint8_t col = i % GRID_COLS;
-        const int16_t slotL = BODY_MARGIN_X + (col * (layout.slotW + SLOT_GAP_X));
-        const int16_t slotT = layout.bodyTop + (row * (layout.slotH + SLOT_GAP_Y));
-        const bool selected = (idx == selectedIndex);
-
-        const uint8_t appletIndex = activeAppletIndices.at(idx);
-        Applet *a = inkhud->userApplets.at(appletIndex);
-        if (!a)
-            continue;
-
-        const int16_t iconLeft = slotL + ((layout.slotW - layout.iconBox) / 2);
-        const int16_t iconTop = slotT + 1;
-
-        // Requested style: icon in outlined rounded square only (no filled box, no outer app card).
-        drawRoundRect(iconLeft, iconTop, layout.iconBox, layout.iconBox, ICON_RADIUS, BLACK);
-        if (selected)
-            drawRoundRect(iconLeft + 2, iconTop + 2, layout.iconBox - 4, layout.iconBox - 4, ICON_RADIUS, BLACK);
-
-        const IconBitmap bmp = iconBitmapForKind(iconKindForAppletName(a->name));
-        drawIconBitmapScaled(this, bmp, iconLeft + 3, iconTop + 3, layout.iconBox - 6, BLACK);
-
-        setFont(fontSmall);
-        std::string label = a->name ? a->name : "Applet";
-        const uint16_t maxLabelW = layout.slotW > 4 ? (layout.slotW - 4) : layout.slotW;
-        if (getTextWidth(label) > maxLabelW) {
-            while (!label.empty() && getTextWidth(label + "...") > maxLabelW)
-                label.pop_back();
-            label = label.empty() ? "..." : label + "...";
-        }
-        const int16_t labelY = iconTop + layout.iconBox + LABEL_GAP_Y;
-        setTextColor(BLACK);
-        printAt(slotL + (layout.slotW / 2), labelY, label.c_str(), CENTER, TOP);
-
-        if (a->isForeground())
-            fillCircle(iconLeft + layout.iconBox - 4, iconTop + 4, 2, BLACK);
-    }
-
-    const uint8_t pageCount = std::max<uint8_t>(1, (activeAppletIndices.size() + cpp - 1) / cpp);
-    if (pageCount > 1) {
-        setFont(fontSmall);
-        setTextColor(BLACK);
-        const int16_t footerY = height() - layout.footerH + FOOTER_PAD;
-        printAt(TITLE_H_PAD, footerY, "<", LEFT, TOP);
-        printAt(width() - TITLE_H_PAD, footerY, ">", RIGHT, TOP);
-        const std::string pageText = std::to_string(page + 1) + "/" + std::to_string(pageCount);
-        printAt(width() / 2, footerY, pageText.c_str(), CENTER, TOP);
-    }
-}
-
-bool InkHUD::AppSwitcherApplet::onTouchPoint(uint16_t x, uint16_t y, bool longPress)
-{
-    (void)longPress;
-
-    Tile *t = getTile();
-    if (!t || activeAppletIndices.empty())
-        return true;
-
-    const uint16_t tileL = t->getLeft();
-    const uint16_t tileT = t->getTop();
-    const uint16_t tileR = tileL + t->getWidth();
-    const uint16_t tileB = tileT + t->getHeight();
-    if (x < tileL || x >= tileR || y < tileT || y >= tileB)
-        return false;
-
-    const GridLayout layout = computeLayout(this);
-    const uint8_t cpp = cardsPerPage();
-    const uint8_t page = currentPage();
-    const uint8_t pageStart = page * cpp;
-    const int16_t localX = (int16_t)x - (int16_t)tileL;
-    const int16_t localY = (int16_t)y - (int16_t)tileT;
-
-    for (uint8_t i = 0; i < cpp; i++) {
-        const uint8_t idx = pageStart + i;
-        if (idx >= activeAppletIndices.size())
-            break;
-
-        const uint8_t row = i / GRID_COLS;
-        const uint8_t col = i % GRID_COLS;
-        const int16_t slotL = BODY_MARGIN_X + (col * (layout.slotW + SLOT_GAP_X));
-        const int16_t slotT = layout.bodyTop + (row * (layout.slotH + SLOT_GAP_Y));
-
-        if (localX < slotL || localX >= (slotL + (int16_t)layout.slotW))
-            continue;
-        if (localY < slotT || localY >= (slotT + (int16_t)layout.slotH))
-            continue;
-
-        selectedIndex = idx;
-        clampSelection();
-        activateSelectedApplet();
-        return true;
-    }
-
-    const uint8_t pageCount = std::max<uint8_t>(1, (activeAppletIndices.size() + cpp - 1) / cpp);
-    if (pageCount <= 1)
-        return true;
-
-    const int16_t footerTop = height() - layout.footerH;
-    if (localY >= footerTop) {
-        if (localX < (int16_t)(width() / 3))
-            stepPage(-1);
-        else if (localX >= (int16_t)((width() * 2) / 3))
-            stepPage(1);
-    }
-
-    return true;
-}
-
-void InkHUD::AppSwitcherApplet::onButtonShortPress()
-{
-    if (activeAppletIndices.empty())
-        return;
-
-    selectedIndex = (selectedIndex + 1) % activeAppletIndices.size();
-    clampSelection();
-    requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-}
-
-void InkHUD::AppSwitcherApplet::onButtonLongPress()
-{
-    activateSelectedApplet();
-}
-
-void InkHUD::AppSwitcherApplet::onExitShort()
-{
-    sendToBackground();
-    requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-}
-
-void InkHUD::AppSwitcherApplet::onNavUp()
-{
-    if (activeAppletIndices.empty())
-        return;
-
-    if (selectedIndex == 0)
-        selectedIndex = activeAppletIndices.size() - 1;
-    else
-        selectedIndex--;
-
-    clampSelection();
-    requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-}
-
-void InkHUD::AppSwitcherApplet::onNavDown()
-{
-    if (activeAppletIndices.empty())
-        return;
-
-    selectedIndex = (selectedIndex + 1) % activeAppletIndices.size();
-    clampSelection();
-    requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-}
-
-#endif

src/graphics/niche/InkHUD/Applets/System/AppSwitcher/AppSwitcherApplet.h

@@ -1,51 +0,0 @@
-#ifdef MESHTASTIC_INCLUDE_INKHUD
-
-#pragma once
-
-#include "configuration.h"
-
-#include "graphics/niche/InkHUD/SystemApplet.h"
-
-#include <vector>
-
-namespace NicheGraphics::InkHUD
-{
-
-class Tile;
-
-class AppSwitcherApplet : public SystemApplet
-{
-  public:
-    AppSwitcherApplet();
-
-    void onForeground() override;
-    void onBackground() override;
-    void onRender(bool full) override;
-
-    void onButtonShortPress() override;
-    void onButtonLongPress() override;
-    void onExitShort() override;
-    void onNavUp() override;
-    void onNavDown() override;
-    bool onTouchPoint(uint16_t x, uint16_t y, bool longPress) override;
-
-    // Open the app switcher on a user tile and temporarily replace the tile's owner.
-    void show(Tile *t);
-
-  private:
-    void rebuildActiveAppletList();
-    void clampSelection();
-    uint8_t cardsPerPage() const;
-    uint8_t currentPage() const;
-    void stepPage(int8_t delta);
-    void activateSelectedApplet();
-
-    std::vector<uint8_t> activeAppletIndices;
-    uint8_t selectedIndex = 0;
-
-    Applet *borrowedTileOwner = nullptr;
-};
-
-} // namespace NicheGraphics::InkHUD
-
-#endif

src/graphics/niche/InkHUD/Applets/System/Keyboard/KeyboardApplet.cpp

@@ -1,100 +1,155 @@
 #ifdef MESHTASTIC_INCLUDE_INKHUD
 #include "./KeyboardApplet.h"
 
-#include <cctype>
-
 using namespace NicheGraphics;
 
-namespace
-{
-bool usePortraitKeyboardSizing()
-{
-    InkHUD::InkHUD *inkhud = InkHUD::InkHUD::getInstance();
-    return inkhud && inkhud->height() > inkhud->width();
-}
-} // namespace
-
 InkHUD::KeyboardApplet::KeyboardApplet()
 {
-    mode = MODE_TEXT;
-    lastTypingMode = MODE_TEXT;
-    emotePage = 0;
-    selectedKey = 0;
-    prevSelectedKey = 0;
-    normalizeSelection();
+    // Calculate row widths
+    for (uint8_t row = 0; row < KBD_ROWS; row++) {
+        rowWidths[row] = 0;
+        for (uint8_t col = 0; col < KBD_COLS; col++)
+            rowWidths[row] += keyWidths[row * KBD_COLS + col];
+    }
 }
 
 void InkHUD::KeyboardApplet::onRender(bool full)
 {
-    const bool showSelection = showSelectionHighlight();
+    uint16_t em = fontSmall.lineHeight(); // 16 pt
+    uint16_t keyH = Y(1.0) / KBD_ROWS;
+    int16_t keyTopPadding = (keyH - fontSmall.lineHeight()) / 2;
 
-    if (full) {
-        for (uint8_t i = 0; i < KBD_KEY_COUNT; i++)
-            drawKey(i, showSelection && i == selectedKey);
-    } else if (showSelection && selectedKey != prevSelectedKey) {
-        drawKey(prevSelectedKey, false);
-        drawKey(selectedKey, true);
+    if (full) { // Draw full keyboard
+        for (uint8_t row = 0; row < KBD_ROWS; row++) {
+
+            // Calculate the remaining space to be used as padding
+            int16_t keyXPadding = X(1.0) - ((rowWidths[row] * em) >> 4);
+
+            // Draw keys
+            uint16_t xPos = 0;
+            for (uint8_t col = 0; col < KBD_COLS; col++) {
+                Color fgcolor = BLACK;
+                uint8_t index = row * KBD_COLS + col;
+                uint16_t keyX = ((xPos * em) >> 4) + ((col * keyXPadding) / (KBD_COLS - 1));
+                uint16_t keyY = row * keyH;
+                uint16_t keyW = (keyWidths[index] * em) >> 4;
+                if (index == selectedKey) {
+                    fgcolor = WHITE;
+                    fillRect(keyX, keyY, keyW, keyH, BLACK);
+                }
+                drawKeyLabel(keyX, keyY + keyTopPadding, keyW, keys[index], fgcolor);
+                xPos += keyWidths[index];
+            }
+        }
+    } else { // Only draw the difference
+        if (selectedKey != prevSelectedKey) {
+            // Draw previously selected key
+            uint8_t row = prevSelectedKey / KBD_COLS;
+            int16_t keyXPadding = X(1.0) - ((rowWidths[row] * em) >> 4);
+            uint16_t xPos = 0;
+            for (uint8_t i = prevSelectedKey - (prevSelectedKey % KBD_COLS); i < prevSelectedKey; i++)
+                xPos += keyWidths[i];
+            uint16_t keyX = ((xPos * em) >> 4) + (((prevSelectedKey % KBD_COLS) * keyXPadding) / (KBD_COLS - 1));
+            uint16_t keyY = row * keyH;
+            uint16_t keyW = (keyWidths[prevSelectedKey] * em) >> 4;
+            fillRect(keyX, keyY, keyW, keyH, WHITE);
+            drawKeyLabel(keyX, keyY + keyTopPadding, keyW, keys[prevSelectedKey], BLACK);
+
+            // Draw newly selected key
+            row = selectedKey / KBD_COLS;
+            keyXPadding = X(1.0) - ((rowWidths[row] * em) >> 4);
+            xPos = 0;
+            for (uint8_t i = selectedKey - (selectedKey % KBD_COLS); i < selectedKey; i++)
+                xPos += keyWidths[i];
+            keyX = ((xPos * em) >> 4) + (((selectedKey % KBD_COLS) * keyXPadding) / (KBD_COLS - 1));
+            keyY = row * keyH;
+            keyW = (keyWidths[selectedKey] * em) >> 4;
+            fillRect(keyX, keyY, keyW, keyH, BLACK);
+            drawKeyLabel(keyX, keyY + keyTopPadding, keyW, keys[selectedKey], WHITE);
+        }
     }
 
     prevSelectedKey = selectedKey;
 }
 
-void InkHUD::KeyboardApplet::drawKey(uint8_t index, bool selected)
+// Draw the key label corresponding to the char
+// for most keys it draws the character itself
+// for ['\b', '\n', ' ', '\x1b'] it draws special glyphs
+void InkHUD::KeyboardApplet::drawKeyLabel(uint16_t left, uint16_t top, uint16_t width, char key, Color color)
 {
-    uint16_t keyX = 0;
-    uint16_t keyY = 0;
-    uint16_t keyW = 0;
-    uint16_t keyH = 0;
-    if (!getKeyBounds(index, keyX, keyY, keyW, keyH))
-        return;
-    if (keyW == 0 || keyH == 0)
-        return;
-
-    // Translate absolute tile coordinates into applet-local coordinates.
-    const int16_t localX = keyX - getTile()->getLeft();
-    const int16_t localY = keyY - getTile()->getTop();
-    const bool enabled = isKeyEnabledAt(index);
-
-    // Clean background first so hidden keys never leave stale pixels when mode changes.
-    fillRect(localX, localY, keyW, keyH, WHITE);
-
-    if (!enabled)
-        return;
-
-    fillRoundRect(localX, localY, keyW, keyH, KEY_RADIUS, selected ? BLACK : WHITE);
-    drawRoundRect(localX, localY, keyW, keyH, KEY_RADIUS, BLACK);
-
-    const int16_t labelTop = localY + ((keyH - fontSmall.lineHeight()) / 2);
-    drawKeyLabel(localX, labelTop, keyW, getKeyLabelAt(index), selected ? WHITE : BLACK);
-}
-
-void InkHUD::KeyboardApplet::drawKeyLabel(uint16_t left, uint16_t top, uint16_t width, const std::string &label, Color color)
-{
-    if (label.empty())
-        return;
-
-    setTextColor(color);
-    uint16_t textW = getTextWidth(label);
-    if (textW > width) {
-        // Keep labels readable in narrow keys.
-        textW = getTextWidth("..");
-        printAt(left + ((width - textW) >> 1), top, "..");
-        return;
+    if (key == '\b') {
+        // Draw backspace glyph: 13 x 9 px
+        /**
+         *         [][][][][][][][][]
+         *       [][]              []
+         *     [][]    []      []  []
+         *   [][]        []  []    []
+         * [][]            []      []
+         *   [][]        []  []    []
+         *     [][]    []      []  []
+         *       [][]              []
+         *         [][][][][][][][][]
+         */
+        const uint8_t bsBitmap[] = {0x0f, 0xf8, 0x18, 0x08, 0x32, 0x28, 0x61, 0x48, 0xc0,
+                                    0x88, 0x61, 0x48, 0x32, 0x28, 0x18, 0x08, 0x0f, 0xf8};
+        uint16_t leftPadding = (width - 13) >> 1;
+        drawBitmap(left + leftPadding, top + 1, bsBitmap, 13, 9, color);
+    } else if (key == '\n') {
+        // Draw done glyph: 12 x 9 px
+        /**
+         *                     [][]
+         *                   [][]
+         *                 [][]
+         *               [][]
+         *             [][]
+         * [][]      [][]
+         *   [][]  [][]
+         *     [][][]
+         *       []
+         */
+        const uint8_t doneBitmap[] = {0x00, 0x30, 0x00, 0x60, 0x00, 0xc0, 0x01, 0x80, 0x03,
+                                      0x00, 0xc6, 0x00, 0x6c, 0x00, 0x38, 0x00, 0x10, 0x00};
+        uint16_t leftPadding = (width - 12) >> 1;
+        drawBitmap(left + leftPadding, top + 1, doneBitmap, 12, 9, color);
+    } else if (key == ' ') {
+        // Draw space glyph: 13 x 9 px
+        /**
+         *
+         *
+         *
+         *
+         * []                      []
+         * []                      []
+         * [][][][][][][][][][][][][]
+         *
+         *
+         */
+        const uint8_t spaceBitmap[] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80,
+                                       0x08, 0x80, 0x08, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x00};
+        uint16_t leftPadding = (width - 13) >> 1;
+        drawBitmap(left + leftPadding, top + 1, spaceBitmap, 13, 9, color);
+    } else if (key == '\x1b') {
+        setTextColor(color);
+        std::string keyText = "ESC";
+        uint16_t leftPadding = (width - getTextWidth(keyText)) >> 1;
+        printAt(left + leftPadding, top, keyText);
+    } else {
+        setTextColor(color);
+        if (key >= 0x61)
+            key -= 32; // capitalize
+        std::string keyText = std::string(1, key);
+        uint16_t leftPadding = (width - getTextWidth(keyText)) >> 1;
+        printAt(left + leftPadding, top, keyText);
     }
-
-    uint16_t leftPadding = (width - textW) >> 1;
-    printAt(left + leftPadding, top, label);
 }
 
 void InkHUD::KeyboardApplet::onForeground()
 {
-    handleInput = true;
-    mode = MODE_TEXT;
-    lastTypingMode = MODE_TEXT;
-    emotePage = 0;
+    handleInput = true; // Intercept the button input for our applet
+
+    // Select the first key
     selectedKey = 0;
     prevSelectedKey = 0;
-    normalizeSelection();
 }
 
 void InkHUD::KeyboardApplet::onBackground()
@@ -104,12 +159,32 @@ void InkHUD::KeyboardApplet::onBackground()
 
 void InkHUD::KeyboardApplet::onButtonShortPress()
 {
-    inputSelectedKey(false);
+    char key = keys[selectedKey];
+    if (key == '\n') {
+        inkhud->freeTextDone();
+        inkhud->closeKeyboard();
+    } else if (key == '\x1b') {
+        inkhud->freeTextCancel();
+        inkhud->closeKeyboard();
+    } else {
+        inkhud->freeText(key);
+    }
 }
 
 void InkHUD::KeyboardApplet::onButtonLongPress()
 {
-    inputSelectedKey(true);
+    char key = keys[selectedKey];
+    if (key == '\n') {
+        inkhud->freeTextDone();
+        inkhud->closeKeyboard();
+    } else if (key == '\x1b') {
+        inkhud->freeTextCancel();
+        inkhud->closeKeyboard();
+    } else {
+        if (key >= 0x61)
+            key -= 32; // capitalize
+        inkhud->freeText(key);
+    }
 }
 
 void InkHUD::KeyboardApplet::onExitShort()
@@ -126,377 +201,57 @@ void InkHUD::KeyboardApplet::onExitLong()
 
 void InkHUD::KeyboardApplet::onNavUp()
 {
-    if (selectedKey < KBD_COLS)
+    if (selectedKey < KBD_COLS) // wrap
         selectedKey += KBD_COLS * (KBD_ROWS - 1);
-    else
+    else // move 1 row back
         selectedKey -= KBD_COLS;
 
-    normalizeSelection();
-    requestFastKeyboardRefresh();
+    // Request rendering over the previously drawn render
+    requestUpdate(EInk::UpdateTypes::FAST, false);
+    // Force an update to bypass lockRequests
+    inkhud->forceUpdate(EInk::UpdateTypes::FAST);
 }
 
 void InkHUD::KeyboardApplet::onNavDown()
 {
     selectedKey += KBD_COLS;
-    selectedKey %= KBD_KEY_COUNT;
-    normalizeSelection();
-    requestFastKeyboardRefresh();
+    selectedKey %= (KBD_COLS * KBD_ROWS);
+
+    // Request rendering over the previously drawn render
+    requestUpdate(EInk::UpdateTypes::FAST, false);
+    // Force an update to bypass lockRequests
+    inkhud->forceUpdate(EInk::UpdateTypes::FAST);
 }
 
 void InkHUD::KeyboardApplet::onNavLeft()
 {
-    if (selectedKey % KBD_COLS == 0)
+    if (selectedKey % KBD_COLS == 0) // wrap
         selectedKey += KBD_COLS - 1;
-    else
+    else // move 1 column back
         selectedKey--;
 
-    normalizeSelection();
-    requestFastKeyboardRefresh();
+    // Request rendering over the previously drawn render
+    requestUpdate(EInk::UpdateTypes::FAST, false);
+    // Force an update to bypass lockRequests
+    inkhud->forceUpdate(EInk::UpdateTypes::FAST);
 }
 
 void InkHUD::KeyboardApplet::onNavRight()
 {
-    if (selectedKey % KBD_COLS == KBD_COLS - 1)
+    if (selectedKey % KBD_COLS == KBD_COLS - 1) // wrap
         selectedKey -= KBD_COLS - 1;
-    else
+    else // move 1 column forward
         selectedKey++;
 
-    normalizeSelection();
-    requestFastKeyboardRefresh();
-}
-
-bool InkHUD::KeyboardApplet::onTouchPoint(uint16_t x, uint16_t y, bool longPress)
-{
-    // If touch is outside our tile, let other handlers process it.
-    if (!getTile())
-        return false;
-    const uint16_t tileL = getTile()->getLeft();
-    const uint16_t tileT = getTile()->getTop();
-    const uint16_t tileR = tileL + getTile()->getWidth();
-    const uint16_t tileB = tileT + getTile()->getHeight();
-    if (x < tileL || x >= tileR || y < tileT || y >= tileB)
-        return false;
-
-    const int16_t hitIndex = getKeyIndexAt(x, y);
-    // Consume touches that land in keyboard whitespace/disabled cells so we don't
-    // fall back to generic short-press behavior (which would type the old selection).
-    if (hitIndex < 0)
-        return true;
-
-    const uint8_t newSelected = (uint8_t)hitIndex;
-    if (selectedKey != newSelected) {
-        selectedKey = newSelected;
-        normalizeSelection();
-        if (showSelectionHighlight())
-            requestFastKeyboardRefresh();
-    }
-
-    if (!isKeyEnabledAt(selectedKey))
-        return true;
-
-    inputSelectedKey(longPress);
-    return true;
-}
-
-bool InkHUD::KeyboardApplet::getKeyBounds(uint8_t index, uint16_t &left, uint16_t &top, uint16_t &width, uint16_t &height)
-{
-    if (index >= KBD_KEY_COUNT || !getTile())
-        return false;
-
-    const uint16_t tileW = getTile()->getWidth();
-    const uint16_t tileH = getTile()->getHeight();
-    const uint16_t tileL = getTile()->getLeft();
-    const uint16_t tileT = getTile()->getTop();
-    const uint8_t row = index / KBD_COLS;
-    const uint8_t col = index % KBD_COLS;
-
-    const uint16_t totalGapY = KEY_GAP_Y * (KBD_ROWS + 1);
-    const uint16_t keyH = (tileH > totalGapY) ? ((tileH - totalGapY) / KBD_ROWS) : (tileH / KBD_ROWS);
-    top = tileT + KEY_GAP_Y + row * (keyH + KEY_GAP_Y);
-    height = keyH;
-
-    const uint16_t totalGapX = KEY_GAP_X * (KBD_COLS + 1);
-    const uint16_t rowSpace = (tileW > totalGapX) ? (tileW - totalGapX) : tileW;
-    uint32_t rowUnits = 0;
-    const uint8_t rowStart = row * KBD_COLS;
-    for (uint8_t i = 0; i < KBD_COLS; i++) {
-        rowUnits += getKeyWidthAt(rowStart + i);
-    }
-    if (rowUnits == 0)
-        return false;
-
-    uint32_t cursorX = tileL + KEY_GAP_X;
-    for (uint8_t i = 0; i < col; i++) {
-        const uint8_t rowIndex = rowStart + i;
-        const uint32_t keyW = ((uint32_t)rowSpace * getKeyWidthAt(rowIndex)) / rowUnits;
-        cursorX += keyW + KEY_GAP_X;
-    }
-
-    left = (uint16_t)cursorX;
-
-    if (col == (KBD_COLS - 1)) {
-        const uint32_t rightEdge = tileL + tileW - KEY_GAP_X;
-        width = (rightEdge > cursorX) ? (uint16_t)(rightEdge - cursorX) : 0;
-    } else {
-        width = (uint16_t)(((uint32_t)rowSpace * getKeyWidthAt(index)) / rowUnits);
-    }
-
-    return true;
-}
-
-int16_t InkHUD::KeyboardApplet::getKeyIndexAt(uint16_t x, uint16_t y)
-{
-    for (uint8_t i = 0; i < KBD_KEY_COUNT; i++) {
-        uint16_t keyL = 0;
-        uint16_t keyT = 0;
-        uint16_t keyW = 0;
-        uint16_t keyH = 0;
-        if (!getKeyBounds(i, keyL, keyT, keyW, keyH))
-            return -1;
-
-        if (keyW == 0 || keyH == 0)
-            continue;
-
-        if (x >= keyL && x < (keyL + keyW) && y >= keyT && y < (keyT + keyH))
-            return i;
-    }
-
-    return -1;
-}
-
-void InkHUD::KeyboardApplet::inputSelectedKey(bool longPress)
-{
-    inputKeyCode(getKeyCodeAt(selectedKey), longPress);
-}
-
-void InkHUD::KeyboardApplet::inputKeyCode(int16_t keyCode, bool longPress)
-{
-    if (keyCode == KEY_NONE)
-        return;
-
-    if (keyCode >= KEY_EMOTE_SLOT_BASE) {
-        const uint8_t slot = (uint8_t)(keyCode - KEY_EMOTE_SLOT_BASE);
-        const uint16_t emoteIndex = emotePage * EMOTE_SLOT_COUNT + slot;
-        if (emoteIndex < fontEmoteCount)
-            inkhud->freeText((char)fontEmotes[emoteIndex]);
-        return;
-    }
-
-    switch (keyCode) {
-    case KEY_BACKSPACE:
-        inkhud->freeText('\b');
-        return;
-    case KEY_SEND:
-        inkhud->freeTextDone();
-        inkhud->closeKeyboard();
-        return;
-    case KEY_EMOTE_TOGGLE:
-        toggleEmoteMode();
-        return;
-    case KEY_PUNCT_TOGGLE:
-    case KEY_ALPHA_TOGGLE:
-        togglePunctuationMode();
-        return;
-    case KEY_EMOTE_UP:
-        pageEmotes(false);
-        return;
-    case KEY_EMOTE_DOWN:
-        pageEmotes(true);
-        return;
-    default:
-        break;
-    }
-
-    if (keyCode >= 0 && keyCode <= 0xFF) {
-        char key = (char)keyCode;
-        if (longPress && key >= 'a' && key <= 'z')
-            key = (char)std::toupper((unsigned char)key);
-        inkhud->freeText(key);
-    }
-}
-
-int16_t InkHUD::KeyboardApplet::getKeyCodeAt(uint8_t index) const
-{
-    if (index >= KBD_KEY_COUNT)
-        return KEY_NONE;
-
-    if (mode == MODE_TEXT)
-        return textKeys[index];
-    if (mode == MODE_PUNCT)
-        return punctKeys[index];
-
-    // Emote mode
-    if (index < EMOTE_SLOT_COUNT) {
-        const uint16_t emoteIndex = emotePage * EMOTE_SLOT_COUNT + index;
-        if (emoteIndex < fontEmoteCount)
-            return KEY_EMOTE_SLOT_BASE + index;
-        return KEY_NONE;
-    }
-
-    // Emote controls on the bottom row
-    switch (index - EMOTE_SLOT_COUNT) {
-    case 0:
-        return KEY_EMOTE_UP;
-    case 1:
-        return KEY_EMOTE_DOWN;
-    case 2:
-        return KEY_ALPHA_TOGGLE;
-    case 3:
-        return ',';
-    case 4:
-        return ' ';
-    case 5:
-        return '.';
-    case 6:
-        return KEY_SEND;
-    case 7:
-        return KEY_BACKSPACE;
-    default:
-        return KEY_NONE;
-    }
-}
-
-uint16_t InkHUD::KeyboardApplet::getKeyWidthAt(uint8_t index) const
-{
-    if (index >= KBD_KEY_COUNT)
-        return 0;
-
-    if (mode == MODE_EMOTE)
-        return emoteKeyWidths[index];
-    return typingKeyWidths[index];
-}
-
-std::string InkHUD::KeyboardApplet::getKeyLabelAt(uint8_t index) const
-{
-    const int16_t keyCode = getKeyCodeAt(index);
-    if (keyCode == KEY_NONE)
-        return "";
-
-    if (keyCode >= KEY_EMOTE_SLOT_BASE) {
-        const uint8_t slot = (uint8_t)(keyCode - KEY_EMOTE_SLOT_BASE);
-        const uint16_t emoteIndex = emotePage * EMOTE_SLOT_COUNT + slot;
-        if (emoteIndex < fontEmoteCount)
-            return std::string(1, (char)fontEmotes[emoteIndex]);
-        return "";
-    }
-
-    switch (keyCode) {
-    case KEY_BACKSPACE:
-        return "DEL";
-    case KEY_SEND:
-        return "SEND";
-    case KEY_EMOTE_TOGGLE:
-        return std::string(1, (char)0x03); // Smiling face icon from InkHUD emote font map
-    case KEY_PUNCT_TOGGLE:
-        return "!#1";
-    case KEY_ALPHA_TOGGLE:
-        return "ABC";
-    case KEY_EMOTE_UP:
-        return "UP";
-    case KEY_EMOTE_DOWN:
-        return "DN";
-    default:
-        break;
-    }
-
-    if (keyCode >= 0 && keyCode <= 0xFF) {
-        const char c = (char)keyCode;
-        if (c == ' ')
-            return "SPACE";
-        if (c >= 'a' && c <= 'z')
-            return std::string(1, (char)std::toupper((unsigned char)c));
-        return std::string(1, c);
-    }
-
-    return "";
-}
-
-bool InkHUD::KeyboardApplet::isKeyEnabledAt(uint8_t index) const
-{
-    return getKeyCodeAt(index) != KEY_NONE;
-}
-
-void InkHUD::KeyboardApplet::normalizeSelection()
-{
-    if (selectedKey >= KBD_KEY_COUNT)
-        selectedKey = 0;
-
-    if (isKeyEnabledAt(selectedKey))
-        return;
-
-    for (uint8_t i = 0; i < KBD_KEY_COUNT; i++) {
-        if (isKeyEnabledAt(i)) {
-            selectedKey = i;
-            return;
-        }
-    }
-}
-
-void InkHUD::KeyboardApplet::togglePunctuationMode()
-{
-    if (mode == MODE_EMOTE) {
-        mode = lastTypingMode;
-    } else {
-        mode = (mode == MODE_TEXT) ? MODE_PUNCT : MODE_TEXT;
-        lastTypingMode = mode;
-    }
-
-    normalizeSelection();
-    requestFastKeyboardRefresh(true);
-}
-
-void InkHUD::KeyboardApplet::toggleEmoteMode()
-{
-    if (mode == MODE_EMOTE) {
-        mode = lastTypingMode;
-    } else {
-        lastTypingMode = mode;
-        mode = MODE_EMOTE;
-    }
-
-    emotePage = 0;
-    normalizeSelection();
-    requestFastKeyboardRefresh(true);
-}
-
-void InkHUD::KeyboardApplet::pageEmotes(bool down)
-{
-    if (mode != MODE_EMOTE)
-        return;
-
-    const uint8_t maxPage = (fontEmoteCount == 0) ? 0 : (uint8_t)((fontEmoteCount - 1) / EMOTE_SLOT_COUNT);
-
-    if (down) {
-        if (emotePage < maxPage)
-            emotePage++;
-    } else {
-        if (emotePage > 0)
-            emotePage--;
-    }
-
-    normalizeSelection();
-    requestFastKeyboardRefresh(true);
-}
-
-void InkHUD::KeyboardApplet::requestFastKeyboardRefresh(bool full)
-{
-    requestUpdate(EInk::UpdateTypes::FAST, full);
-}
-
-bool InkHUD::KeyboardApplet::showSelectionHighlight() const
-{
-    // On touch-capable devices, prioritize input throughput over per-key highlight updates.
-    // E-ink refresh can lag rapid taps; skipping highlight avoids update-induced input latency.
-    return !inkhud->hasTouchEnabledProvider();
+    // Request rendering over the previously drawn render
+    requestUpdate(EInk::UpdateTypes::FAST, false);
+    // Force an update to bypass lockRequests
+    inkhud->forceUpdate(EInk::UpdateTypes::FAST);
 }
 
 uint16_t InkHUD::KeyboardApplet::getKeyboardHeight()
 {
-    // Keep touch keys tall and roomy for finger input.
-    // In portrait orientation we increase row height for larger touch targets.
-    const uint16_t rowUnit = fontSmall.lineHeight() + 8;
-    const uint8_t rowScale = usePortraitKeyboardSizing() ? 3 : 2;
-    const uint16_t keyH = rowUnit * rowScale;
-    return (keyH * KBD_ROWS) + (KEY_GAP_Y * (KBD_ROWS + 1));
+    const uint16_t keyH = fontSmall.lineHeight() * 1.2;
+    return keyH * KBD_ROWS;
 }
 #endif

src/graphics/niche/InkHUD/Applets/System/Keyboard/KeyboardApplet.h

@@ -12,7 +12,6 @@ System Applet to render an on-screen keyboard
 #include "graphics/niche/InkHUD/InkHUD.h"
 #include "graphics/niche/InkHUD/SystemApplet.h"
 #include <string>
-
 namespace NicheGraphics::InkHUD
 {
 
@@ -32,111 +31,34 @@ class KeyboardApplet : public SystemApplet
     void onNavDown() override;
     void onNavLeft() override;
     void onNavRight() override;
-    bool onTouchPoint(uint16_t x, uint16_t y, bool longPress) override;
 
     static uint16_t getKeyboardHeight(); // used to set the keyboard tile height
 
   private:
-    enum KeyCode : int16_t {
-        KEY_NONE = -1,
-        KEY_BACKSPACE = 256,
-        KEY_SEND,
-        KEY_EMOTE_TOGGLE,
-        KEY_PUNCT_TOGGLE,
-        KEY_ALPHA_TOGGLE,
-        KEY_EMOTE_UP,
-        KEY_EMOTE_DOWN,
-        KEY_EMOTE_SLOT_BASE = 512
-    };
-
-    enum KeyboardMode : uint8_t { MODE_TEXT = 0, MODE_PUNCT = 1, MODE_EMOTE = 2 };
-
-    void drawKey(uint8_t index, bool selected);
-    void drawKeyLabel(uint16_t left, uint16_t top, uint16_t width, const std::string &label, Color color);
-    bool getKeyBounds(uint8_t index, uint16_t &left, uint16_t &top, uint16_t &width, uint16_t &height);
-    int16_t getKeyIndexAt(uint16_t x, uint16_t y);
-    void inputSelectedKey(bool longPress);
-    void inputKeyCode(int16_t keyCode, bool longPress);
-    int16_t getKeyCodeAt(uint8_t index) const;
-    uint16_t getKeyWidthAt(uint8_t index) const;
-    std::string getKeyLabelAt(uint8_t index) const;
-    bool isKeyEnabledAt(uint8_t index) const;
-    void normalizeSelection();
-    void togglePunctuationMode();
-    void toggleEmoteMode();
-    void pageEmotes(bool down);
-    void requestFastKeyboardRefresh(bool full = false);
-    bool showSelectionHighlight() const;
+    void drawKeyLabel(uint16_t left, uint16_t top, uint16_t width, char key, Color color);
 
     static const uint8_t KBD_COLS = 11;
-    static const uint8_t KBD_ROWS = 5;
-    static const uint8_t KBD_KEY_COUNT = KBD_COLS * KBD_ROWS;
-    static const uint8_t EMOTE_SLOT_COUNT = KBD_COLS * (KBD_ROWS - 1); // top 4 rows
-    static constexpr uint8_t fontEmotes[] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x08, 0x09, 0x0B, 0x0C, 0x0E, 0x0F, 0x10, 0x11,
-                                             0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F};
-    static constexpr uint8_t fontEmoteCount = sizeof(fontEmotes) / sizeof(fontEmotes[0]);
+    static const uint8_t KBD_ROWS = 4;
 
-    // Text keyboard (requested layout):
-    // row 0: 1..0
-    // row 1: q..p
-    // row 2: a..l
-    // row 3: EMO, z..m, DEL
-    // row 4: !#1, comma, space, period, SEND
-    const int16_t textKeys[KBD_KEY_COUNT] = {
-        // row 0
-        '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', KEY_NONE,
-        // row 1
-        'q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p', KEY_NONE,
-        // row 2
-        'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', KEY_NONE, KEY_NONE,
-        // row 3
-        KEY_EMOTE_TOGGLE, 'z', 'x', 'c', 'v', 'b', 'n', 'm', KEY_BACKSPACE, KEY_NONE, KEY_NONE,
-        // row 4
-        KEY_PUNCT_TOGGLE, ',', ' ', '.', KEY_SEND, KEY_NONE, KEY_NONE, KEY_NONE, KEY_NONE, KEY_NONE, KEY_NONE};
+    const char keys[KBD_COLS * KBD_ROWS] = {
+        '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '\b',  // row 0
+        'q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p', '\n',  // row 1
+        'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', '!', ' ',   // row 2
+        'z', 'x', 'c', 'v', 'b', 'n', 'm', ',', '.', '?', '\x1b' // row 3
+    };
 
-    // Punctuation keyboard (toggle via !#1/ABC)
-    const int16_t punctKeys[KBD_KEY_COUNT] = {
-        // row 0
-        '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', KEY_NONE,
-        // row 1
-        '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', KEY_NONE,
-        // row 2
-        '-', '_', '=', '+', '[', ']', '{', '}', '/', '?', KEY_NONE,
-        // row 3
-        KEY_EMOTE_TOGGLE, ';', ':', '\'', '"', '<', '>', '\\', KEY_BACKSPACE, KEY_NONE, KEY_NONE,
-        // row 4
-        KEY_ALPHA_TOGGLE, ',', ' ', '.', KEY_SEND, KEY_NONE, KEY_NONE, KEY_NONE, KEY_NONE, KEY_NONE, KEY_NONE};
+    // This array represents the widths of each key in points
+    // 16 pt = line height of the text
+    const uint16_t keyWidths[KBD_COLS * KBD_ROWS] = {
+        16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 24, // row 0
+        16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 24, // row 1
+        16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 24, // row 2
+        16, 16, 16, 16, 16, 16, 16, 10, 10, 12, 40  // row 3
+    };
 
-    const uint16_t typingKeyWidths[KBD_KEY_COUNT] = {// row 0
-                                                     12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 0,
-                                                     // row 1
-                                                     12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 0,
-                                                     // row 2
-                                                     12, 12, 12, 12, 12, 12, 12, 12, 12, 0, 0,
-                                                     // row 3
-                                                     18, 12, 12, 12, 12, 12, 12, 12, 20, 0, 0,
-                                                     // row 4
-                                                     20, 12, 56, 12, 24, 0, 0, 0, 0, 0, 0};
-
-    const uint16_t emoteKeyWidths[KBD_KEY_COUNT] = {// row 0
-                                                    12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
-                                                    // row 1
-                                                    12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
-                                                    // row 2
-                                                    12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
-                                                    // row 3
-                                                    12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
-                                                    // row 4 controls
-                                                    14, 14, 18, 12, 40, 12, 20, 18, 0, 0, 0};
-
-    uint8_t selectedKey = 0;
+    uint16_t rowWidths[KBD_ROWS];
+    uint8_t selectedKey = 0; // selected key index
     uint8_t prevSelectedKey = 0;
-    uint8_t emotePage = 0;
-    KeyboardMode mode = MODE_TEXT;
-    KeyboardMode lastTypingMode = MODE_TEXT;
-    static constexpr uint8_t KEY_GAP_X = 3;
-    static constexpr uint8_t KEY_GAP_Y = 4;
-    static constexpr uint8_t KEY_RADIUS = 4;
 };
 
 } // namespace NicheGraphics::InkHUD

src/graphics/niche/InkHUD/Applets/System/Menu/MenuAction.h

@@ -109,7 +109,6 @@ enum MenuAction {
     TOGGLE_CHANNEL_POSITION,
     SET_CHANNEL_PRECISION,
     // Display
-    SET_DISPLAY_TIMEOUT,
     TOGGLE_DISPLAY_UNITS,
     // Network
     TOGGLE_WIFI,
@@ -120,4 +119,4 @@ enum MenuAction {
 
 } // namespace NicheGraphics::InkHUD
 
-#endif
+#endif

src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.cpp

@@ -8,7 +8,6 @@
 #include "RTC.h"
 #include "Router.h"
 #include "airtime.h"
-#include "graphics/niche/Utils/FlashData.h"
 #include "main.h"
 #include "mesh/generated/meshtastic/deviceonly.pb.h"
 #include "power.h"
@@ -28,16 +27,6 @@ static constexpr uint8_t MENU_TIMEOUT_SEC = 60; // How many seconds before menu
 // These are offered to users as possible values for settings.recentlyActiveSeconds
 static constexpr uint8_t RECENTS_OPTIONS_MINUTES[] = {2, 5, 10, 30, 60, 120};
 
-struct DisplayTimeoutOption {
-    uint32_t seconds;
-    const char *label;
-};
-
-static constexpr DisplayTimeoutOption DISPLAY_TIMEOUT_OPTIONS[] = {
-    {0, "Forever"},      {30, "30 secs"},     {60, "1 min"},     {5 * 60, "5 min"},
-    {15 * 60, "15 min"}, {30 * 60, "30 min"}, {60 * 60, "1 hr"},
-};
-
 struct PositionPrecisionOption {
     uint8_t value; // proto value
     const char *metric;
@@ -50,77 +39,6 @@ static constexpr PositionPrecisionOption POSITION_PRECISION_OPTIONS[] = {
     {12, "5.8 km", "3.6 mi"},   {11, "12 km", "7.3 mi"}, {10, "23 km", "15 mi"},
 };
 
-static const char *getDisplayTimeoutLabel(uint32_t timeoutSeconds)
-{
-    constexpr uint8_t optionCount = sizeof(DISPLAY_TIMEOUT_OPTIONS) / sizeof(DISPLAY_TIMEOUT_OPTIONS[0]);
-    for (uint8_t i = 0; i < optionCount; i++) {
-        if (DISPLAY_TIMEOUT_OPTIONS[i].seconds == timeoutSeconds) {
-            return DISPLAY_TIMEOUT_OPTIONS[i].label;
-        }
-    }
-
-    return "Custom";
-}
-
-static bool supportsFreeTextKeyboard(const InkHUD::InkHUD *inkhud, const InkHUD::Persistence::Settings *settings)
-{
-    return !inkhud->twoWayRocker && (settings->joystick.enabled || inkhud->hasTouchEnabledProvider());
-}
-
-static bool useTouchFriendlyMenuLayout(const InkHUD::InkHUD *inkhud)
-{
-    return inkhud != nullptr && inkhud->hasTouchEnabledProvider();
-}
-
-static uint16_t getMenuItemHeightPx(const InkHUD::InkHUD *inkhud)
-{
-    const bool touchFriendly = useTouchFriendlyMenuLayout(inkhud);
-    const uint16_t lineH = touchFriendly ? InkHUD::Applet::fontMedium.lineHeight() : InkHUD::Applet::fontSmall.lineHeight();
-    const float rowScale = touchFriendly ? 1.9f : 1.6f;
-    uint16_t itemH = (uint16_t)(lineH * rowScale);
-    if (itemH == 0) {
-        itemH = 1;
-    }
-    return itemH;
-}
-
-#if defined(T5_S3_EPAPER_PRO)
-namespace
-{
-static constexpr uint32_t T5_BACKLIGHT_PREFS_VERSION = 1;
-
-struct T5BacklightPrefs {
-    uint32_t version = T5_BACKLIGHT_PREFS_VERSION;
-    bool keepOn = true;
-};
-
-T5BacklightPrefs t5BacklightPrefs;
-bool t5BacklightPrefsLoaded = false;
-
-bool loadT5BacklightKeepOn()
-{
-    if (!t5BacklightPrefsLoaded) {
-        T5BacklightPrefs loaded;
-        const bool ok = FlashData<T5BacklightPrefs>::load(&loaded, "t5_backlight");
-        if (ok && loaded.version == T5_BACKLIGHT_PREFS_VERSION) {
-            t5BacklightPrefs = loaded;
-        }
-        t5BacklightPrefsLoaded = true;
-    }
-
-    return t5BacklightPrefs.keepOn;
-}
-
-void saveT5BacklightKeepOn(bool keepOn)
-{
-    loadT5BacklightKeepOn();
-    t5BacklightPrefs.version = T5_BACKLIGHT_PREFS_VERSION;
-    t5BacklightPrefs.keepOn = keepOn;
-    FlashData<T5BacklightPrefs>::save(&t5BacklightPrefs, "t5_backlight");
-}
-} // namespace
-#endif
-
 InkHUD::MenuApplet::MenuApplet() : concurrency::OSThread("MenuApplet")
 {
     // No timer tasks at boot
@@ -129,11 +47,7 @@ InkHUD::MenuApplet::MenuApplet() : concurrency::OSThread("MenuApplet")
     // Note: don't get instance if we're not actually using the backlight,
     // or else you will unintentionally instantiate it
     if (settings->optionalMenuItems.backlight) {
-#if defined(T5_S3_EPAPER_PRO)
-        t5BacklightSetUserEnabled(loadT5BacklightKeepOn());
-#else
         backlight = Drivers::LatchingBacklight::getInstance();
-#endif
     }
 
     // Initialize the Canned Message store
@@ -162,11 +76,9 @@ void InkHUD::MenuApplet::onForeground()
     // backlight on always when menu opens.
     // Courtesy to T-Echo users who removed the capacitive touch button
     if (settings->optionalMenuItems.backlight) {
-#if !defined(T5_S3_EPAPER_PRO)
         assert(backlight);
         if (!backlight->isOn())
             backlight->peek();
-#endif
     }
 
     // Prevent user applets requesting update while menu is open
@@ -194,11 +106,9 @@ void InkHUD::MenuApplet::onBackground()
     // Item in options submenu allows keeping backlight on after menu is closed
     // If this item is deselected we will turn backlight off again, now that menu is closing
     if (settings->optionalMenuItems.backlight) {
-#if !defined(T5_S3_EPAPER_PRO)
         assert(backlight);
         if (!backlight->isLatched())
             backlight->off();
-#endif
     }
 
     // Stop the auto-timeout
@@ -267,8 +177,24 @@ static void applyLoRaRegion(meshtastic_Config_LoRaConfig_RegionCode region)
     auto changes = SEGMENT_CONFIG;
 
 #if !(MESHTASTIC_EXCLUDE_PKI_KEYGEN || MESHTASTIC_EXCLUDE_PKI)
-    if (crypto) {
-        crypto->ensurePkiKeys(config.security, owner);
+    if (!owner.is_licensed) {
+        bool keygenSuccess = false;
+
+        if (config.security.private_key.size == 32) {
+            if (crypto->regeneratePublicKey(config.security.public_key.bytes, config.security.private_key.bytes)) {
+                keygenSuccess = true;
+            }
+        } else {
+            crypto->generateKeyPair(config.security.public_key.bytes, config.security.private_key.bytes);
+            keygenSuccess = true;
+        }
+
+        if (keygenSuccess) {
+            config.security.public_key.size = 32;
+            config.security.private_key.size = 32;
+            owner.public_key.size = 32;
+            memcpy(owner.public_key.bytes, config.security.public_key.bytes, 32);
+        }
     }
 #endif
 
@@ -423,14 +349,17 @@ void InkHUD::MenuApplet::execute(MenuItem item)
         handleFreeText = true;
         cm.freeTextItem.rawText.erase(); // clear the previous freetext message
         freeTextMode = true;             // render input field instead of normal menu
-        if (supportsFreeTextKeyboard(inkhud, settings))
+        // Open the on-screen keyboard only for full joystick devices
+        if (settings->joystick.enabled && !inkhud->twoWayRocker)
             inkhud->openKeyboard();
         break;
 
-    case STORE_CANNEDMESSAGE_SELECTION: {
-        const uint8_t prefixItems = supportsFreeTextKeyboard(inkhud, settings) ? 2 : 1;
-        cm.selectedMessageItem = &cm.messageItems.at(cursor - prefixItems);
-    } break;
+    case STORE_CANNEDMESSAGE_SELECTION:
+        if (!settings->joystick.enabled || inkhud->twoWayRocker)
+            cm.selectedMessageItem = &cm.messageItems.at(cursor - 1); // Minus one: offset for the initial "Send Ping" entry
+        else
+            cm.selectedMessageItem = &cm.messageItems.at(cursor - 2); // Minus two: offset for the "Send Ping" and free text entry
+        break;
 
     case SEND_CANNEDMESSAGE:
         cm.selectedRecipientItem = &cm.recipientItems.at(cursor);
@@ -509,27 +438,14 @@ void InkHUD::MenuApplet::execute(MenuItem item)
         break;
 
     case TOGGLE_BACKLIGHT:
-        // Note: backlight is already on in this situation.
-        // This toggle controls whether it should remain on when menu closes.
-#if defined(T5_S3_EPAPER_PRO)
-    {
-        const bool keepOn = !t5BacklightIsUserEnabled();
-        t5BacklightSetUserEnabled(keepOn);
-        saveT5BacklightKeepOn(keepOn);
-        if (item.checkState)
-            *(item.checkState) = keepOn;
-    }
-#else
-        if (!backlight)
-            backlight = Drivers::LatchingBacklight::getInstance();
+        // Note: backlight is already on in this situation
+        // We're marking that it should *remain* on once menu closes
+        assert(backlight);
         if (backlight->isLatched())
             backlight->off();
         else
             backlight->latch();
-        if (item.checkState)
-            *(item.checkState) = backlight->isLatched();
-#endif
-    break;
+        break;
 
     case TOGGLE_12H_CLOCK:
         config.display.use_12h_clock = !config.display.use_12h_clock;
@@ -627,17 +543,6 @@ void InkHUD::MenuApplet::execute(MenuItem item)
     }
 
     // Display
-    case SET_DISPLAY_TIMEOUT: {
-        // cursor - 1 because index 0 is "Back"
-        const uint8_t index = cursor - 1;
-        constexpr uint8_t optionCount = sizeof(DISPLAY_TIMEOUT_OPTIONS) / sizeof(DISPLAY_TIMEOUT_OPTIONS[0]);
-        if (index < optionCount) {
-            config.display.screen_on_secs = DISPLAY_TIMEOUT_OPTIONS[index].seconds;
-            nodeDB->saveToDisk(SEGMENT_CONFIG);
-        }
-        break;
-    }
-
     case TOGGLE_DISPLAY_UNITS:
         if (config.display.units == meshtastic_Config_DisplayConfig_DisplayUnits_IMPERIAL)
             config.display.units = meshtastic_Config_DisplayConfig_DisplayUnits_METRIC;
@@ -1004,16 +909,11 @@ void InkHUD::MenuApplet::showPage(MenuPage page)
         previousPage = MenuPage::ROOT;
         items.push_back(MenuItem("Back", previousPage));
         // Optional: backlight
-        if (settings->optionalMenuItems.backlight) {
-#if defined(T5_S3_EPAPER_PRO)
-            keepBacklightOn = t5BacklightIsUserEnabled();
-#else
-            if (!backlight)
-                backlight = Drivers::LatchingBacklight::getInstance();
-            keepBacklightOn = backlight->isLatched();
-#endif
-            items.push_back(MenuItem("Keep Backlight On", MenuAction::TOGGLE_BACKLIGHT, MenuPage::OPTIONS, &keepBacklightOn));
-        }
+        if (settings->optionalMenuItems.backlight)
+            items.push_back(MenuItem(backlight->isLatched() ? "Backlight Off" : "Keep Backlight On", // Label
+                                     MenuAction::TOGGLE_BACKLIGHT,                                   // Action
+                                     MenuPage::EXIT                                                  // Exit once complete
+                                     ));
 
         // Options Toggles
         items.push_back(MenuItem("Applets", MenuPage::APPLETS));
@@ -1225,9 +1125,6 @@ void InkHUD::MenuApplet::showPage(MenuPage page)
         items.push_back(MenuItem("12-Hour Clock", MenuAction::TOGGLE_12H_CLOCK, MenuPage::NODE_CONFIG_DISPLAY,
                                  &config.display.use_12h_clock));
 
-        nodeConfigLabels.emplace_back("Screen Timeout: " + std::string(getDisplayTimeoutLabel(config.display.screen_on_secs)));
-        items.push_back(MenuItem(nodeConfigLabels.back().c_str(), MenuAction::NO_ACTION, MenuPage::NODE_CONFIG_DISPLAY_TIMEOUT));
-
         const char *unitsLabel =
             (config.display.units == meshtastic_Config_DisplayConfig_DisplayUnits_IMPERIAL) ? "Units: Imperial" : "Units: Metric";
 
@@ -1237,13 +1134,6 @@ void InkHUD::MenuApplet::showPage(MenuPage page)
         break;
     }
 
-    case NODE_CONFIG_DISPLAY_TIMEOUT:
-        previousPage = MenuPage::NODE_CONFIG_DISPLAY;
-        items.push_back(MenuItem("Back", previousPage));
-        populateDisplayTimeoutPage();
-        items.push_back(MenuItem("Exit", MenuPage::EXIT));
-        break;
-
     case NODE_CONFIG_BLUETOOTH: {
         previousPage = MenuPage::NODE_CONFIG;
         items.push_back(MenuItem("Back", previousPage));
@@ -1512,14 +1402,10 @@ void InkHUD::MenuApplet::onRender(bool full)
     if (items.size() == 0)
         LOG_ERROR("Empty Menu");
 
-    const bool touchFriendlyLayout = useTouchFriendlyMenuLayout(inkhud);
-    AppletFont menuItemFont = touchFriendlyLayout ? fontMedium : fontSmall;
-    setFont(menuItemFont);
-
     // Dimensions for the slots where we will draw menuItems
     const float padding = 0.05;
-    const uint16_t itemH = getMenuItemHeightPx(inkhud);
-    const int16_t selectInsetY = touchFriendlyLayout ? 3 : 2;
+    const uint16_t itemH = fontSmall.lineHeight() * 1.6;
+    const int16_t selectInsetY = 2;
     const int16_t itemW = width() - X(padding) - X(padding);
     const int16_t itemL = X(padding);
     const int16_t itemR = X(1 - padding);
@@ -1552,11 +1438,6 @@ void InkHUD::MenuApplet::onRender(bool full)
         itemT = max(siT + siH, 0);            // Offset the first menu entry, so menu starts below the system info panel
     }
 
-    // drawSystemInfoPanel() changes font state (clock/info text).
-    // Restore the active menu font so ROOT page item text matches other menu pages,
-    // including touch-friendly layouts.
-    setFont(menuItemFont);
-
     // Draw menu items
     // ===================
 
@@ -1584,6 +1465,8 @@ void InkHUD::MenuApplet::onRender(bool full)
 
         // Header (non-selectable section label)
         if (item.isHeader) {
+            setFont(fontSmall);
+
             // Header text (flush left)
             printAt(itemL + X(padding), center, item.label, LEFT, MIDDLE);
 
@@ -1592,17 +1475,8 @@ void InkHUD::MenuApplet::onRender(bool full)
             drawLine(itemL + X(padding), underlineY, itemR - X(padding), underlineY, BLACK);
         } else {
             // Box, if currently selected
-            if (cursorShown && i == cursor && (!touchFriendlyLayout || !hideTouchSelectionHighlight)) {
-                const int16_t selTop = itemT + selectInsetY;
-                const int16_t selH = itemH - (selectInsetY * 2);
-                drawRect(itemL, selTop, itemW, selH, BLACK);
-                // Touch layouts need a stronger visual cue than a thin outline.
-                if (touchFriendlyLayout) {
-                    const int16_t markerInset = 3;
-                    const int16_t markerW = 4;
-                    fillRect(itemL + markerInset, selTop + markerInset, markerW, max(1, selH - (markerInset * 2)), BLACK);
-                }
-            }
+            if (cursorShown && i == cursor)
+                drawRect(itemL, itemT + selectInsetY, itemW, itemH - (selectInsetY * 2), BLACK);
 
             // Indented normal item text
             printAt(itemL + X(padding * 2), center, item.label, LEFT, MIDDLE);
@@ -1610,9 +1484,9 @@ void InkHUD::MenuApplet::onRender(bool full)
 
         // Checkbox, if relevant
         if (item.checkState) {
-            const uint16_t cbWH = menuItemFont.lineHeight(); // Checkbox: width / height
-            const int16_t cbL = itemR - X(padding) - cbWH;   // Checkbox: left
-            const int16_t cbT = center - (cbWH / 2);         // Checkbox : top
+            const uint16_t cbWH = fontSmall.lineHeight();  // Checkbox: width / height
+            const int16_t cbL = itemR - X(padding) - cbWH; // Checkbox: left
+            const int16_t cbT = center - (cbWH / 2);       // Checkbox : top
             // Checkbox ticked
             if (*(item.checkState)) {
                 drawRect(cbL, cbT, cbWH, cbWH, BLACK);
@@ -1641,102 +1515,13 @@ void InkHUD::MenuApplet::onRender(bool full)
     }
 }
 
-bool InkHUD::MenuApplet::onTouchPoint(uint16_t x, uint16_t y, bool longPress)
-{
-    (void)longPress;
-
-    if (freeTextMode || !getTile()) {
-        return false;
-    }
-
-    const uint16_t tileL = getTile()->getLeft();
-    const uint16_t tileT = getTile()->getTop();
-    const uint16_t tileR = tileL + getTile()->getWidth();
-    const uint16_t tileB = tileT + getTile()->getHeight();
-    if (x < tileL || x >= tileR || y < tileT || y >= tileB) {
-        return false;
-    }
-
-    if (items.empty()) {
-        return true;
-    }
-
-    // Direct touch controls should act as activity and keep the menu open.
-    OSThread::setIntervalFromNow(MENU_TIMEOUT_SEC * 1000UL);
-
-    // If button-driven selection is active on touch-first layouts, clear it as soon as
-    // touch interaction resumes so touch behavior remains direct/tap-first.
-    if (useTouchFriendlyMenuLayout(inkhud)) {
-        cursorShown = false;
-        hideTouchSelectionHighlight = true;
-    }
-
-    const int16_t localY = (int16_t)y - (int16_t)tileT;
-
-    // Keep geometry in sync with onRender() so touch hit-testing matches what users see.
-    const uint16_t itemH = getMenuItemHeightPx(inkhud);
-    int16_t itemT = 0;
-    uint8_t slotCount = (height() - itemT) / itemH;
-    if (slotCount == 0) {
-        slotCount = 1;
-    }
-    const uint16_t &siH = systemInfoPanelHeight;
-    const uint8_t slotsObscured = ceilf(siH / (float)itemH);
-
-    if (currentPage == ROOT) {
-        int16_t siT = 0;
-        const int16_t scrollThreshold = (int16_t)slotCount - (int16_t)slotsObscured - 1;
-        if (scrollThreshold >= 0 && (int16_t)cursor >= scrollThreshold) {
-            siT = 0 - ((cursor - scrollThreshold) * itemH);
-        }
-        itemT = max((int16_t)(siT + siH), (int16_t)0);
-    }
-
-    const uint8_t firstItem = (cursor < slotCount) ? 0 : (cursor - (slotCount - 1));
-    uint16_t visibleEnd = (uint16_t)firstItem + (uint16_t)slotCount;
-    const uint8_t maxIndex = (uint8_t)items.size() - 1;
-    if (visibleEnd > maxIndex) {
-        visibleEnd = maxIndex;
-    }
-    const uint8_t lastItem = (uint8_t)visibleEnd;
-
-    for (uint8_t i = firstItem; i <= lastItem; i++) {
-        const int16_t rowTop = itemT;
-        const int16_t rowBottom = itemT + itemH;
-
-        if (localY >= rowTop && localY < rowBottom) {
-            if (items.at(i).isHeader) {
-                // Consume taps on headers so they don't fall back to button semantics.
-                return true;
-            }
-
-            cursor = i;
-            cursorShown = true;
-            execute(items.at(cursor));
-
-            if (!wantsToRender()) {
-                requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-            }
-            return true;
-        }
-
-        itemT += itemH;
-    }
-
-    // Consume taps on menu whitespace so we don't trigger button-like fallback behavior.
-    return true;
-}
-
 void InkHUD::MenuApplet::onButtonShortPress()
 {
     if (!freeTextMode) {
         // Push the auto-close timer back
         OSThread::setIntervalFromNow(MENU_TIMEOUT_SEC * 1000UL);
 
-        // Touch-first nodes keep user-button short-press as "advance selection" in menus.
-        // Any button-driven navigation should restore visible highlight.
-        hideTouchSelectionHighlight = false;
-        if (!settings->joystick.enabled || useTouchFriendlyMenuLayout(inkhud)) {
+        if (!settings->joystick.enabled) {
             if (!cursorShown) {
                 cursorShown = true;
                 // Select the first item that isn't a header
@@ -1797,32 +1582,6 @@ void InkHUD::MenuApplet::onNavUp()
     if (!freeTextMode) {
         OSThread::setIntervalFromNow(MENU_TIMEOUT_SEC * 1000UL);
 
-        // Touch-first menus: swipe up/down should scroll only.
-        // Keep cursor movement for scroll math, but selection box is hidden in onRender().
-        if (useTouchFriendlyMenuLayout(inkhud)) {
-            hideTouchSelectionHighlight = true;
-            if (!cursorShown) {
-                cursorShown = true;
-                cursor = items.size() - 1;
-                while (items.at(cursor).isHeader) {
-                    if (cursor == 0) {
-                        cursorShown = false;
-                        break;
-                    }
-                    cursor--;
-                }
-            } else {
-                do {
-                    if (cursor == 0)
-                        cursor = items.size() - 1;
-                    else
-                        cursor--;
-                } while (items.at(cursor).isHeader);
-            }
-            requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-            return;
-        }
-
         if (!cursorShown) {
             cursorShown = true;
             // Select the last item that isn't a header
@@ -1852,29 +1611,6 @@ void InkHUD::MenuApplet::onNavDown()
     if (!freeTextMode) {
         OSThread::setIntervalFromNow(MENU_TIMEOUT_SEC * 1000UL);
 
-        // Touch-first menus: swipe up/down should scroll only.
-        // Keep cursor movement for scroll math, but selection box is hidden in onRender().
-        if (useTouchFriendlyMenuLayout(inkhud)) {
-            hideTouchSelectionHighlight = true;
-            if (!cursorShown) {
-                cursorShown = true;
-                cursor = 0;
-                while (cursor < items.size() && items.at(cursor).isHeader) {
-                    cursor++;
-                }
-                if (cursor >= items.size()) {
-                    cursorShown = false;
-                    cursor = 0;
-                }
-            } else {
-                do {
-                    cursor = (cursor + 1) % items.size();
-                } while (items.at(cursor).isHeader);
-            }
-            requestUpdate(Drivers::EInk::UpdateTypes::FAST);
-            return;
-        }
-
         if (!cursorShown) {
             cursorShown = true;
             // Select the first item that isn't a header
@@ -2007,17 +1743,6 @@ void InkHUD::MenuApplet::populateRecentsPage()
     }
 }
 
-void InkHUD::MenuApplet::populateDisplayTimeoutPage()
-{
-    constexpr uint8_t optionCount = sizeof(DISPLAY_TIMEOUT_OPTIONS) / sizeof(DISPLAY_TIMEOUT_OPTIONS[0]);
-    for (uint8_t i = 0; i < optionCount; i++) {
-        displayTimeoutSelected[i] = (config.display.screen_on_secs == DISPLAY_TIMEOUT_OPTIONS[i].seconds);
-        nodeConfigLabels.emplace_back(DISPLAY_TIMEOUT_OPTIONS[i].label);
-        items.push_back(MenuItem(nodeConfigLabels.back().c_str(), MenuAction::SET_DISPLAY_TIMEOUT, MenuPage::NODE_CONFIG_DISPLAY,
-                                 &displayTimeoutSelected[i]));
-    }
-}
-
 // MenuItem entries for the "send" page
 // Dynamically creates menu items based on available canned messages
 void InkHUD::MenuApplet::populateSendPage()
@@ -2025,8 +1750,8 @@ void InkHUD::MenuApplet::populateSendPage()
     // Position / NodeInfo packet
     items.push_back(MenuItem("Ping", MenuAction::SEND_PING, MenuPage::EXIT));
 
-    // Show the Free Text option on any node that supports the on-screen keyboard.
-    if (supportsFreeTextKeyboard(inkhud, settings))
+    // If joystick is available, include the Free Text option
+    if (settings->joystick.enabled && !inkhud->twoWayRocker)
         items.push_back(MenuItem("Free Text", MenuAction::FREE_TEXT, MenuPage::SEND));
 
     // One menu item for each canned message

src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.h

@@ -35,7 +35,6 @@ class MenuApplet : public SystemApplet, public concurrency::OSThread
     void onFreeText(char c) override;
     void onFreeTextDone() override;
     void onFreeTextCancel() override;
-    bool onTouchPoint(uint16_t x, uint16_t y, bool longPress) override;
     void onRender(bool full) override;
 
     void show(Tile *t); // Open the menu, onto a user tile
@@ -49,12 +48,11 @@ class MenuApplet : public SystemApplet, public concurrency::OSThread
     void execute(MenuItem item);  // Perform the MenuAction associated with a MenuItem, if any
     void showPage(MenuPage page); // Load and display a MenuPage
 
-    void populateSendPage();           // Dynamically create MenuItems including canned messages
-    void populateRecipientPage();      // Dynamically create a page of possible destinations for a canned message
-    void populateAppletPage();         // Dynamically create MenuItems for toggling loaded applets
-    void populateAutoshowPage();       // Dynamically create MenuItems for selecting which applets can autoshow
-    void populateRecentsPage();        // Create menu items: a choice of values for settings.recentlyActiveSeconds
-    void populateDisplayTimeoutPage(); // Create menu items for config.display.screen_on_secs
+    void populateSendPage();      // Dynamically create MenuItems including canned messages
+    void populateRecipientPage(); // Dynamically create a page of possible destinations for a canned message
+    void populateAppletPage();    // Dynamically create MenuItems for toggling loaded applets
+    void populateAutoshowPage();  // Dynamically create MenuItems for selecting which applets can autoshow
+    void populateRecentsPage();   // Create menu items: a choice of values for settings.recentlyActiveSeconds
 
     void drawInputField(uint16_t left, uint16_t top, uint16_t width, uint16_t height,
                         const std::string &text); // Draw input field for free text
@@ -67,9 +65,8 @@ class MenuApplet : public SystemApplet, public concurrency::OSThread
     MenuPage startPageOverride = MenuPage::ROOT;
     MenuPage currentPage = MenuPage::ROOT;
     MenuPage previousPage = MenuPage::EXIT;
-    uint8_t cursor = 0;                       // Which menu item is currently highlighted
-    bool cursorShown = false;                 // Is *any* item highlighted? (Root menu: no initial selection)
-    bool hideTouchSelectionHighlight = false; // Touch scrolling keeps cursor for paging math, but can hide highlight
+    uint8_t cursor = 0;       // Which menu item is currently highlighted
+    bool cursorShown = false; // Is *any* item highlighted? (Root menu: no initial selection)
     bool freeTextMode = false;
     uint16_t systemInfoPanelHeight = 0; // Need to know before we render
     uint16_t menuTextLimit = 200;
@@ -83,8 +80,6 @@ class MenuApplet : public SystemApplet, public concurrency::OSThread
     // Recents menu checkbox state (derived from settings.recentlyActiveSeconds)
     static constexpr uint8_t RECENTS_COUNT = 6;
     bool recentsSelected[RECENTS_COUNT] = {};
-    static constexpr uint8_t DISPLAY_TIMEOUT_COUNT = 7;
-    bool displayTimeoutSelected[DISPLAY_TIMEOUT_COUNT] = {};
 
     // Data for selecting and sending canned messages via the menu
     // Placed into a sub-class for organization only
@@ -121,8 +116,7 @@ class MenuApplet : public SystemApplet, public concurrency::OSThread
 
     Applet *borrowedTileOwner = nullptr; // Which applet we have temporarily replaced while displaying menu
 
-    bool invertedColors = false;  // Helper to display current state of config.display.displaymode in InkHUD options
-    bool keepBacklightOn = false; // Helper to display current backlight latch state in InkHUD options
+    bool invertedColors = false; // Helper to display current state of config.display.displaymode in InkHUD options
 };
 
 } // namespace NicheGraphics::InkHUD