ai: Establish conductor documentation and governance framework (#4780)

Signed-off-by: James Rich <2199651+jamesarich@users.noreply.github.com>

conductor/archive/desktop_parity_20260311/index.md

@@ -0,0 +1,5 @@
+# Track desktop_parity_20260311 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/desktop_parity_20260311/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "desktop_parity_20260311",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-03-11T12:00:00Z",
+  "updated_at": "2026-03-11T12:00:00Z",
+  "description": "continue bringing desktop up to parity with android"
+}

conductor/archive/desktop_parity_20260311/plan.md

@@ -0,0 +1,41 @@
+# Implementation Plan
+
+## Phase 1: Navigation Parity [checkpoint: 5b8e194]
+- [x] Task: Extract shared navigation contracts f7e0c2e
+    - [x] Define shared top-level destinations and route metadata in `core:navigation`.
+    - [x] Update Android `TopLevelDestination` to use the shared contract.
+    - [x] Update Desktop `DesktopDestination` to use the shared contract.
+    - [x] Add parity tests for navigation routing.
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Navigation Parity' (Protocol in workflow.md)
+
+## Phase 2: DI Parity [checkpoint: 5bdc099]
+- [x] Task: Migrate Desktop Koin Modules 93fd600
+    - [x] Configure KSP for the JVM target in necessary modules.
+    - [x] Ensure Koin annotations are processed for Desktop.
+    - [x] Replace manual ViewModel wiring in `DesktopKoinModule` with generated modules.
+- [x] Task: Conductor - User Manual Verification 'Phase 2: DI Parity' (Protocol in workflow.md)
+
+## Phase 3: Connections Parity [checkpoint: 4be5732]
+- [x] Task: Create `feature:connections` module 242faa6
+    - [x] Set up the KMP module structure with `commonMain`, `androidMain`, and `jvmMain` (or `desktopMain`).
+    - [x] Move device discovery UI and ViewModels from `app` and `desktop` into the new module.
+    - [x] Consolidate the Connections UI into a shared screen in `feature:connections`.
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Connections Parity' (Protocol in workflow.md)
+
+## Phase 4: UI/Feature Parity [checkpoint: e83a07a]
+- [x] Task: Implement missing Map and Chart features on Desktop 128ee3b
+    - [x] Evaluate and implement a KMP-friendly mapping library or placeholder for Desktop.
+    - [x] Refactor Vico charts or provide a KMP charting alternative/placeholder for Desktop.
+- [x] Task: Refinement - Connections UI and Messaging Parity c98db4f
+    - [x] Hide unsupported transports (BLE/USB) on Desktop via BuildUtils proxy.
+    - [x] Update message titles to resolve channel names for broadcasts.
+    - [x] Add snackbar for no-op gaps (delivery info).
+    - [x] Shared AnimatedConnectionsNavIcon for "blinky light" parity.
+    - *Note: Connection type filtering is currently hardcoded via BuildUtils.sdkInt. This should be refactored to use dynamic transport discovery once the 'Extract hardware transport' track is complete.*
+- [x] Task: Conductor - User Manual Verification 'Phase 4: UI/Feature Parity' (Protocol in workflow.md) e83a07a
+
+## Phase 5: Multi-Target Hardening [checkpoint: 91784a9]
+- [x] Task: Clean up remaining platform-specific leaks f5f1e29
+    - [x] Ensure `commonMain` is free of any `java.*` dependencies.
+    - [x] Verify test suite passes on both Android and Desktop JVM targets.
+- [x] Task: Conductor - User Manual Verification 'Phase 5: Multi-Target Hardening' (Protocol in workflow.md) 91784a9

conductor/archive/desktop_parity_20260311/spec.md

@@ -0,0 +1,25 @@
+# Track Specification: Desktop Parity & Multi-Target Hardening
+
+## Overview
+This track aims to bring the Desktop target up to parity with the Android app and lay the foundation for future targets (like iOS). This involves eliminating duplicated code, fixing structural gaps, and sharing UI, navigation, and DI contracts across platforms.
+
+## Functional Requirements
+- **Connections Parity:** Consolidate device discovery (BLE/USB/TCP) from the app and desktop into a shared `feature:connections` module.
+- **DI Parity:** Remove manual ViewModel wiring in `DesktopKoinModule` and transition to using KSP-generated Koin modules for Desktop.
+- **UI/Feature Parity:** Implement missing map and charting functionality on Desktop, or provide robust KMP abstractions where direct translation isn't possible.
+- **Navigation Parity:** Extract shared navigation contracts to stop drift between Android and Desktop shells (following `decisions/navigation3-parity-2026-03.md`).
+
+## Non-Functional Requirements
+- **Architecture Readiness:** Ensure code abstractions support the subsequent addition of an iOS target.
+- **Structural Purity:** `commonMain` must be completely free of platform-specific APIs (like `java.*` or Android-specific APIs).
+
+## Acceptance Criteria
+- Device discovery screens share UI and view models in `feature:connections`.
+- Desktop DI uses generated modules without manual ViewModel instantiation.
+- Map and charting features are either functioning on Desktop or have solid KMP placeholders.
+- Android and Desktop Navigation shells utilize shared configuration and metadata.
+- Both functional and structural parity goals are verified through automated builds and testing where applicable.
+
+## Out of Scope
+- Full deployment to iOS or other unannounced platforms (only preparing the architecture).
+- Deep refactoring of underlying hardware interactions beyond what is necessary to expose a shared UI contract.

conductor/archive/doc_consolidation_20260311/index.md

@@ -0,0 +1,5 @@
+# Track doc_consolidation_20260311 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/doc_consolidation_20260311/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "doc_consolidation_20260311",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-03-11T00:00:00Z",
+  "updated_at": "2026-03-11T00:00:00Z",
+  "description": "Implement document consolidation plan"
+}

conductor/archive/doc_consolidation_20260311/plan.md

@@ -0,0 +1,35 @@
+# Implementation Plan: Implement document consolidation plan
+
+## Phase 1: Prune and Consolidate Session Artifacts
+- [x] Task: Consolidate session artifacts into `docs/archive/kmp-phase3-testing-consolidation.md`. [d8becb2]
+    - [x] Write Tests (Verify documentation structure)
+    - [x] Read all 12+ session update files.
+    - [x] Create `kmp-phase3-testing-consolidation.md` with merged key findings and test coverage metrics.
+- [x] Task: Delete redundant point-in-time files from `docs/agent-playbooks/`. [d8becb2]
+    - [x] Write Tests (Verify file removal)
+    - [x] Delete `CHECKLIST-testing-consolidation.md` and other 11 listed files.
+- [x] Task: Relocate remaining planning documents. [d8becb2]
+    - [x] Write Tests (Verify correct destination paths)
+    - [x] Merge `phase-4-desktop-completion-plan.md` into `docs/roadmap.md` under Phase 4 Desktop section and delete the original.
+    - [x] Move `kmp-feature-migration-plan.md` to `docs/archive/`.
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Prune and Consolidate Session Artifacts' (Protocol in workflow.md) [checkpoint: d8becb2]
+
+## Phase 2: Synthesize Status & Roadmap
+- [x] Task: Update `docs/kmp-status.md`. [37fd055]
+    - [x] Write Tests (Verify updated metric output)
+    - [x] Update testing score to reflect Phase 3 completion (80 tests across 6 features).
+- [x] Task: Update `docs/roadmap.md`. [37fd055]
+    - [x] Write Tests (Verify roadmap section exists)
+    - [x] Mark Phase 3 as substantially complete.
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Synthesize Status & Roadmap' (Protocol in workflow.md) [checkpoint: 37fd055]
+
+## Phase 3: Verify and Validate Best Practices
+- [x] Task: Update `AGENTS.md` and playbooks for 2026 KMP Best Practices. [85db394]
+    - [x] Write Tests (Verify updated content)
+    - [x] Document Koin Annotations (K2) best practices in `AGENTS.md` and `di-navigation3-anti-patterns-playbook.md`.
+    - [x] Document Shared ViewModels (MVI) recommendations.
+- [x] Task: Documentation Quality Checks. [85db394]
+    - [x] Write Tests (Verify links resolve)
+    - [x] Update `docs/agent-playbooks/README.md`.
+    - [x] Rename `testing-quick-ref.sh` to `testing-quick-ref.md` and update internal references.
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Verify and Validate Best Practices' (Protocol in workflow.md) [checkpoint: 85db394]

conductor/archive/doc_consolidation_20260311/spec.md

@@ -0,0 +1,13 @@
+# Track Specification: Implement document consolidation plan
+
+## Objective
+Consolidate, prune, verify, and validate project plans and documentation against 2026 Kotlin Multiplatform (KMP) best practices and the latest dependency standards.
+
+## Background & Motivation
+The `docs/agent-playbooks/` directory has accumulated numerous point-in-time session summaries, checklists, and status reports (e.g., `SESSION-FINAL-SUMMARY.md`, `TEST-VERIFICATION-REPORT.md`) during the Phase 3 testing consolidation sprint. These files clutter the directory and dilute the actual "playbooks" (reusable guides). Additionally, the project documentation (`kmp-status.md`, `roadmap.md`, `AGENTS.md`) needs to be synthesized to reflect the recently completed work and validated against 2026 KMP industry standards (e.g., Koin K2 compiler plugin best practices, shared ViewModels, Navigation 3).
+
+## Scope
+1. **Prune and Consolidate Session Artifacts:** Merge the key findings into a single historical record (`docs/archive/kmp-phase3-testing-consolidation.md`) and delete 12+ redundant point-in-time files. Relocate `phase-4-desktop-completion-plan.md` into `docs/roadmap.md` and move `kmp-feature-migration-plan.md` to `docs/archive/`.
+2. **Synthesize Status & Roadmap:** Update `docs/kmp-status.md` and `docs/roadmap.md` with new testing metrics (80 tests across 6 features) and expanded Phase 4 Desktop tasks.
+3. **Verify and Validate against 2026 KMP Best Practices:** Validate the usage of Koin `@Module` and `@KoinViewModel` annotations in `commonMain` according to Koin 4.2 native compiler plugin best practices. Update `AGENTS.md` and `di-navigation3-anti-patterns-playbook.md` to officially recommend this pattern and multiplatform `androidx.lifecycle.ViewModel` in `commonMain`.
+4. **Documentation Quality Checks:** Verify `README.md` in playbooks correctly points to retained playbooks. Rename `testing-quick-ref.sh` to `testing-quick-ref.md` and update internal references.

conductor/archive/extract_hardware_transport_20260311/index.md

@@ -0,0 +1,5 @@
+# Track extract_hardware_transport_20260311 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/extract_hardware_transport_20260311/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "extract_hardware_transport_20260311",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-03-11T00:00:00Z",
+  "updated_at": "2026-03-11T00:00:00Z",
+  "description": "extract hardware/transport layers out of :app into dedicated :core modules"
+}

conductor/archive/extract_hardware_transport_20260311/plan.md

@@ -0,0 +1,37 @@
+# Implementation Plan: Extract hardware/transport layers out of :app into dedicated :core modules
+
+## Phase 1: Define Shared Interface and Extract Stream Framing [checkpoint: 80a39a5]
+- [x] Task: Create `RadioTransport` interface in `core:repository/commonMain`. a47f399
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Move `StreamFrameCodec` logic to `core:network/commonMain`. cc1ff26
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Refactor existing `IRadioInterface` usages to point to the new `RadioTransport` interface (preparation step). 1b4cec6
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Define Shared Interface and Extract Stream Framing' (Protocol in workflow.md) 80a39a5
+
+## Phase 2: Extract Platform Transports
+- [x] Task: Move TCP transport implementation to `core:network/jvmAndroidMain`. [8688070]
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Move BLE transport implementation to `core:ble/androidMain`. [8688070]
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Move Serial/USB transport implementation to `core:service/androidMain`. [8688070]
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Extract Platform Transports' (Protocol in workflow.md) [checkpoint: 8688070]
+
+## Phase 3: Desktop Unification and Cleanup
+- [x] Task: Retire `DesktopRadioInterfaceService` in the `desktop` module.
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Update the `desktop` DI graph to inject the shared `TcpTransport` implementation.
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Delete the old `app/repository/radio/` directory.
+    - [x] Write Tests
+    - [x] Implement Feature
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Desktop Unification and Cleanup' (Protocol in workflow.md) [checkpoint: 8688070]

conductor/archive/extract_hardware_transport_20260311/spec.md

@@ -0,0 +1,22 @@
+# Track Specification: Extract hardware/transport layers out of :app into dedicated :core modules
+
+## Overview
+This track addresses a critical modularity gap identified in the KMP architecture review: the Radio interface layer is currently locked within the `app` module and is non-KMP. The goal is to define a shared `RadioTransport` interface in `core:repository` and fully extract all transport implementations (BLE, TCP, USB) from `app/repository/radio/` into their appropriate `core` modules.
+
+## Functional Requirements
+- **Define `RadioTransport` Interface:** Create a new `RadioTransport` interface in `core:repository/commonMain` to replace the existing `IRadioInterface`.
+- **Extract Stream Framing:** Move `StreamFrameCodec`-based framing logic to `core:network/commonMain`.
+- **Extract BLE Transport:** Move the BLE transport implementation (`NordicBleInterface`, etc.) to `core:ble/androidMain`.
+- **Extract TCP Transport:** Move the TCP transport implementation to `core:network/jvmAndroidMain`.
+- **Extract Serial/USB Transport:** Move the Serial/USB transport implementation to `core:service/androidMain`.
+- **Unify Desktop Transport:** Retire Desktop's parallel `DesktopRadioInterfaceService` and migrate it to use the shared `RadioTransport` and `TcpTransport`.
+
+## Acceptance Criteria
+- [ ] A `RadioTransport` interface exists in `core:repository/commonMain`.
+- [ ] No transport logic (BLE, TCP, USB) remains in `app/repository/radio/`.
+- [ ] The `app` and `desktop` modules successfully compile and run using the extracted transport layers.
+- [ ] The `desktop` module uses the shared `TcpTransport` implementation instead of its own duplicate logic.
+
+## Out of Scope
+- Rewriting the underlying logic of the transports (e.g., changing how Nordic BLE works). This is purely a structural extraction and KMP alignment.
+- Extracting non-transport components (like the Connections UI) from the `app` module.

conductor/archive/kmp_doc_review_20260313/index.md

@@ -0,0 +1,5 @@
+# Track kmp_doc_review_20260313 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/kmp_doc_review_20260313/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "kmp_doc_review_20260313",
+  "type": "chore",
+  "status": "new",
+  "created_at": "2026-03-13T12:00:00Z",
+  "updated_at": "2026-03-13T12:00:00Z",
+  "description": "do a thorough review of the project docs for quality and veracity against the current codebase and recent changes - use tooling as needed. Evaluate updating project documentation for clarity and context. Synthesize and condense documentation and plans as needed. Be sure to thoroughly investigate the current state of the codebase and it's migration to kmp."
+}

conductor/archive/kmp_doc_review_20260313/plan.md

@@ -0,0 +1,23 @@
+# Implementation Plan
+
+## Phase 1: Context Gathering and Codebase Investigation [checkpoint: b644b50]
+- [x] Task: Investigate current state of KMP migration [42c36f0]
+    - [x] Run tooling to analyze KMP modules (`core:*`) vs Android-only modules.
+    - [x] Identify discrepancies between actual code structure and current documentation.
+- [x] Task: Review existing documentation [d87b7a2]
+    - [x] Review Conductor strategy docs (`conductor/`).
+    - [x] Review Root docs (`README.md`, `AGENTS.md`, `GEMINI.md`).
+    - [x] Review `docs/` directory contents.
+- [x] Task: Conductor - User Manual Verification 'Context Gathering and Codebase Investigation' (Protocol in workflow.md) [b644b50]
+
+## Phase 2: Synthesis and Condensation [checkpoint: 40e7c58]
+- [x] Task: Synthesize documentation [8c57f14]
+    - [x] Consolidate related guides into single sources of truth.
+    - [x] Update documentation to reflect recent KMP migration findings.
+- [x] Task: Archive legacy documentation [14b19c5]
+    - [x] Identify outdated or redundant documents.
+    - [x] Move identified documents into an `archive/` directory.
+- [x] Task: Formulate next steps proposal [2bd7655]
+    - [x] Draft a proposed plan for remaining KMP migrations based on investigation.
+    - [x] Document the proposal in the relevant file (e.g., `kmp-status.md`).
+- [x] Task: Conductor - User Manual Verification 'Synthesis and Condensation' (Protocol in workflow.md) [40e7c58]

conductor/archive/kmp_doc_review_20260313/spec.md

@@ -0,0 +1,24 @@
+# Overview
+This track involves a thorough review, synthesis, and condensation of the project's documentation for quality and veracity against the current codebase and recent changes. It includes a deep investigation into the current state of the codebase, specifically focusing on its migration to Kotlin Multiplatform (KMP).
+
+# Functional Requirements
+- Conduct a comprehensive review of Conductor strategy docs (`conductor/`), Root repository docs (e.g., `README.md`, `AGENTS.md`), the `docs/` directory, and inline source code docstrings.
+- Investigate the current state of KMP migration across the codebase.
+- Synthesize and condense existing documentation into clarified, updated guides.
+- Archive old, redundant, or outdated documentation.
+- Formulate a proposed plan and next steps for the remaining KMP migrations.
+
+# Non-Functional Requirements
+- Ensure documentation is accurate, clear, and contextually aligned with recent codebase changes.
+- Use appropriate tooling to analyze the codebase and verify documentation claims.
+
+# Acceptance Criteria
+- [ ] A consolidated, up-to-date documentation structure exists.
+- [ ] Legacy or redundant documents are moved to an archive folder.
+- [ ] An accurate report of the current KMP migration status is produced.
+- [ ] A proposal for the next steps in the KMP migration is documented.
+- [ ] Conductor docs, Root docs, the `docs/` directory, and key docstrings align with the actual codebase implementation.
+
+# Out of Scope
+- Actually executing the proposed KMP migrations (this track is purely documentation and planning).
+- Modifying application business logic or UI code.

conductor/code_styleguides/general.md

@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.

conductor/doc-consolidation-plan.md

@@ -0,0 +1,53 @@
+# Objective
+Consolidate, prune, verify, and validate project plans and documentation against 2026 Kotlin Multiplatform (KMP) best practices and the latest dependency standards.
+
+# Background & Motivation
+The `docs/agent-playbooks/` directory has accumulated numerous point-in-time session summaries, checklists, and status reports (e.g., `SESSION-FINAL-SUMMARY.md`, `TEST-VERIFICATION-REPORT.md`) during the Phase 3 testing consolidation sprint. These files clutter the directory and dilute the actual "playbooks" (reusable guides). Additionally, the project documentation (`kmp-status.md`, `roadmap.md`, `AGENTS.md`) needs to be synthesized to reflect the recently completed work and validated against 2026 KMP industry standards (e.g., Koin K2 compiler plugin best practices, shared ViewModels, Navigation 3).
+
+# Proposed Solution
+
+## 1. Prune and Consolidate Session Artifacts
+- **Consolidate:** Merge the key findings, test coverage metrics (80 tests across 6 features), and testing patterns from the 12+ session update files into a single historical record: `docs/archive/kmp-phase3-testing-consolidation.md`.
+- **Prune:** Delete the following redundant point-in-time files from `docs/agent-playbooks/`:
+  - `CHECKLIST-testing-consolidation.md`
+  - `FINAL-STATUS-tests-fixed.md`
+  - `MIGRATION-COMPLETE-SUMMARY.md`
+  - `SESSION-FINAL-SUMMARY.md`
+  - `SESSION-STATUS-2026-03-11.md`
+  - `TEST-VERIFICATION-REPORT.md`
+  - `fix-core-domain-tests.md`
+  - `kmp-testing-consolidation-slice.md`
+  - `phase-1-feature-commontest-bootstrap.md`
+  - `phase-3-completion.md`
+  - `phase-3-implementation-plan.md`
+  - `phase-3-integration-tests-started.md`
+- **Relocate:** 
+  - Extract the contents of `phase-4-desktop-completion-plan.md` and merge them into `docs/roadmap.md` under the Phase 4 Desktop section. Delete the original file.
+  - Move `kmp-feature-migration-plan.md` to `docs/archive/` since Phase 3 is mostly complete.
+
+## 2. Synthesize Status & Roadmap
+- **Update `docs/kmp-status.md`:** Update the testing score (currently 5/10) to reflect the completion of Phase 3 integration testing (80 tests across 6 features, test doubles in `core:testing`).
+- **Update `docs/roadmap.md`:** Mark Phase 3 as substantially complete. Expand the Phase 4 (Desktop Feature Completion) section using the consolidated plan details.
+
+## 3. Verify and Validate against 2026 KMP Best Practices
+Based on a review of 2026 KMP standards and the project's current dependencies (`Koin 4.2.0-RC1`, `Compose Multiplatform 1.11.0-alpha03`, `Navigation 3 1.1.0-alpha03`):
+- **Koin Annotations (K2):** The project's decision to move Koin `@Module` and `@KoinViewModel` annotations into `commonMain` aligns perfectly with Koin 4.2 native compiler plugin best practices. The documentation (`AGENTS.md`, `docs/decisions/architecture-review-2026-03.md`) will be validated and explicitly updated to affirm that this is the correct architectural pattern, not a "portability tradeoff".
+- **Shared ViewModels (MVI):** Ensure playbook documentation explicitly recommends utilizing the multiplatform `androidx.lifecycle.ViewModel` in `commonMain` to maintain a single source of truth, heavily relying on `StateFlow`.
+- **Navigation 3:** The hybrid parity strategy (shared route contracts, platform adapters) is validated as the 2026 standard for Compose Multiplatform.
+
+## 4. Documentation Quality Checks
+- Verify `docs/agent-playbooks/README.md` correctly points only to the retained playbooks.
+- Rename `testing-quick-ref.sh` to `testing-quick-ref.md` for proper markdown rendering and update internal references.
+
+# Implementation Steps
+1. Create `docs/archive/kmp-phase3-testing-consolidation.md` and synthesize the 12+ session artifacts into it.
+2. Delete the 12+ redundant session files from `docs/agent-playbooks/`.
+3. Update `docs/kmp-status.md` and `docs/roadmap.md` with the new testing metrics and Phase 4 desktop tasks.
+4. Rename `testing-quick-ref.sh` to `testing-quick-ref.md` and update internal references.
+5. Update `docs/agent-playbooks/README.md` to reflect the pruned directory.
+6. Refine `AGENTS.md` and `docs/agent-playbooks/di-navigation3-anti-patterns-playbook.md` to validate Koin K2 multiplatform annotations as the officially recommended pattern.
+
+# Verification & Testing
+- Run `ls docs/agent-playbooks/` to ensure only high-signal playbooks remain.
+- Ensure `docs/kmp-status.md` reflects an updated test maturity score (e.g., 8/10).
+- Run `git status` and `git diff` to ensure changes are accurate.

conductor/index.md

@@ -0,0 +1,14 @@
+# Project Context
+
+## Definition
+- [Product Definition](./product.md)
+- [Product Guidelines](./product-guidelines.md)
+- [Tech Stack](./tech-stack.md)
+
+## Workflow
+- [Workflow](./workflow.md)
+- [Code Style Guides](./code_styleguides/)
+
+## Management
+- [Tracks Registry](./tracks.md)
+- [Tracks Directory](./tracks/)

conductor/product-guidelines.md

@@ -0,0 +1,19 @@
+# Product Guidelines
+
+## Brand Voice and Tone
+- **Technical yet Accessible:** Communicate complex networking and hardware concepts clearly without being overly academic.
+- **Reliable and Authoritative:** The app is a utility for critical, off-grid communication. Language should convey stability and safety.
+- **Community-Oriented:** Encourage open-source participation and community support.
+
+## UX Principles
+- **Offline-First:** Assume the user has no cellular or Wi-Fi connection. All core functions must work locally via the mesh network.
+- **Adaptive Layouts:** Support multiple form factors seamlessly (phones, tablets, desktop) using Material 3 Adaptive Scaffold principles.
+- **Information Density:** Give power users access to detailed metrics (SNR, battery, hop limits) without overwhelming beginners. Use progressive disclosure.
+
+## Prose Style
+- **Clarity over cleverness:** Use plain English.
+- **Action-oriented:** Button labels and prompts should start with strong verbs (e.g., "Send", "Connect", "Export").
+- **Consistent Terminology:** 
+  - Use "Node" for devices on the network.
+  - Use "Channel" for communication groups.
+  - Use "Direct Message" for 1-to-1 communication.

conductor/product.md

@@ -0,0 +1,24 @@
+# Initial Concept
+A tool for using Android with open-source mesh radios.
+
+# Product Guide
+
+## Overview
+Meshtastic-Android is a Kotlin Multiplatform (KMP) application designed to facilitate communication over off-grid, decentralized mesh networks using open-source hardware radios.
+
+## Target Audience
+- Off-grid communication enthusiasts and hobbyists
+- Outdoor adventurers needing reliable communication without cellular networks
+- Emergency response and disaster relief teams
+
+## Core Features
+- Direct communication with Meshtastic hardware (via BLE, USB, TCP)
+- Decentralized text messaging across the mesh network
+- Adaptive node and contact management
+- Offline map rendering and device positioning
+- Device configuration and firmware updates
+
+## Key Architecture Goals
+- Provide a robust, shared KMP core (`core:model`, `core:repository`, `core:domain`, `core:data`, `core:network`) to support multiple platforms (Android, Desktop, iOS)
+- Ensure offline-first functionality and resilient data persistence (Room KMP)
+- Decouple UI logic into shared components (`core:ui`, `feature:*`) using Compose Multiplatform

conductor/tech-stack.md

@@ -0,0 +1,23 @@
+# Tech Stack
+
+## Programming Language
+- **Kotlin Multiplatform (KMP):** The core logic is shared across Android, Desktop, and iOS using `commonMain`.
+
+## Frontend Frameworks
+- **Compose Multiplatform:** Shared UI layer for rendering on Android and Desktop.
+- **Jetpack Compose:** Used where platform-specific UI (like charts or permissions) is necessary on Android.
+
+## Architecture
+- **MVI / Unidirectional Data Flow:** Shared view models using the multiplatform `androidx.lifecycle.ViewModel`.
+- **JetBrains Navigation 3:** Multiplatform fork for state-based, compose-first navigation without relying on `NavController`.
+
+## Dependency Injection
+- **Koin 4.2:** Leverages Koin Annotations and the K2 Compiler Plugin for pure compile-time DI, completely replacing Hilt.
+
+## Database & Storage
+- **Room KMP:** Shared local database using multiplatform `DatabaseConstructor`.
+- **Jetpack DataStore:** Shared preferences.
+
+## Networking & Transport
+- **Ktor:** Multiplatform HTTP client for web services and TCP streaming.
+- **Coroutines & Flows:** For asynchronous programming and state management.

conductor/tracks.md

@@ -0,0 +1,3 @@
+# Project Tracks
+
+This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.

conductor/workflow.md

@@ -0,0 +1,333 @@
+# Project Workflow
+
+## Guiding Principles
+
+1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md`
+2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation
+3. **Test-Driven Development:** Write unit tests before implementing functionality
+4. **High Code Coverage:** Aim for >80% code coverage for all modules
+5. **User Experience First:** Every decision should prioritize user experience
+6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
+
+## Task Workflow
+
+All tasks follow a strict lifecycle:
+
+### Standard Task Workflow
+
+1. **Select Task:** Choose the next available task from `plan.md` in sequential order
+
+2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
+
+3. **Write Failing Tests (Red Phase):**
+   - Create a new test file for the feature or bug fix.
+   - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
+   - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.
+
+4. **Implement to Pass Tests (Green Phase):**
+   - Write the minimum amount of application code necessary to make the failing tests pass.
+   - Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
+
+5. **Refactor (Optional but Recommended):**
+   - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
+   - Rerun tests to ensure they still pass after refactoring.
+
+6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
+   ```bash
+   pytest --cov=app --cov-report=html
+   ```
+   Target: >80% coverage for new code. The specific tools and commands will vary by language and framework.
+
+7. **Document Deviations:** If implementation differs from tech stack:
+   - **STOP** implementation
+   - Update `tech-stack.md` with new design
+   - Add dated note explaining the change
+   - Resume implementation
+
+8. **Commit Code Changes:**
+   - Stage all code changes related to the task.
+   - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`.
+   - Perform the commit.
+
+9. **Attach Task Summary with Git Notes:**
+   - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
+   - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change.
+   - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
+     ```bash
+     # The note content from the previous step is passed via the -m flag.
+     git notes add -m "<note content>" <commit_hash>
+     ```
+
+10. **Get and Record Task Commit SHA:**
+    - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash.
+    - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`.
+
+11. **Commit Plan Update:**
+    - **Action:** Stage the modified `plan.md` file.
+    - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`).
+
+### Phase Completion Verification and Checkpointing Protocol
+
+**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
+
+1.  **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
+
+2.  **Ensure Test Coverage for Phase Changes:**
+    -   **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
+    -   **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` to get a precise list of all files modified during this phase.
+    -   **Step 2.3: Verify and Create Tests:** For each file in the list:
+        -   **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`).
+        -   For each remaining code file, verify a corresponding test file exists.
+        -   If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`).
+
+3.  **Execute Automated Tests with Proactive Debugging:**
+    -   Before execution, you **must** announce the exact shell command you will use to run the tests.
+    -   **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`"
+    -   Execute the announced command.
+    -   If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance.
+
+4.  **Propose a Detailed, Actionable Manual Verification Plan:**
+    -   **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase.
+    -   You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes.
+    -   The plan you present to the user **must** follow this format:
+
+        **For a Frontend Change:**
+        ```
+        The automated tests have passed. For manual verification, please follow these steps:
+
+        **Manual Verification Steps:**
+        1.  **Start the development server with the command:** `npm run dev`
+        2.  **Open your browser to:** `http://localhost:3000`
+        3.  **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly.
+        ```
+
+        **For a Backend Change:**
+        ```
+        The automated tests have passed. For manual verification, please follow these steps:
+
+        **Manual Verification Steps:**
+        1.  **Ensure the server is running.**
+        2.  **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
+        3.  **Confirm that you receive:** A JSON response with a status of `201 Created`.
+        ```
+
+5.  **Await Explicit User Feedback:**
+    -   After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**"
+    -   **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation.
+
+6.  **Create Checkpoint Commit:**
+    -   Stage all changes. If no changes occurred in this step, proceed with an empty commit.
+    -   Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`).
+
+7.  **Attach Auditable Verification Report using Git Notes:**
+    -   **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation.
+    -   **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit.
+
+8.  **Get and Record Phase Checkpoint SHA:**
+    -   **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`).
+    -   **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: <sha>]`.
+    -   **Step 8.3: Write Plan:** Write the updated content back to `plan.md`.
+
+9. **Commit Plan Update:**
+    - **Action:** Stage the modified `plan.md` file.
+    - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
+
+10.  **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note.
+
+### Quality Gates
+
+Before marking any task complete, verify:
+
+- [ ] All tests pass
+- [ ] Code coverage meets requirements (>80%)
+- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`)
+- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc)
+- [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types)
+- [ ] No linting or static analysis errors (using the project's configured tools)
+- [ ] Works correctly on mobile (if applicable)
+- [ ] Documentation updated if needed
+- [ ] No security vulnerabilities introduced
+
+## Development Commands
+
+**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.**
+
+### Setup
+```bash
+# Example: Commands to set up the development environment (e.g., install dependencies, configure database)
+# e.g., for a Node.js project: npm install
+# e.g., for a Go project: go mod tidy
+```
+
+### Daily Development
+```bash
+# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format)
+# e.g., for a Node.js project: npm run dev, npm test, npm run lint
+# e.g., for a Go project: go run main.go, go test ./..., go fmt ./...
+```
+
+### Before Committing
+```bash
+# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests)
+# e.g., for a Node.js project: npm run check
+# e.g., for a Go project: make check (if a Makefile exists)
+```
+
+## Testing Requirements
+
+### Unit Testing
+- Every module must have corresponding tests.
+- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach).
+- Mock external dependencies.
+- Test both success and failure cases.
+
+### Integration Testing
+- Test complete user flows
+- Verify database transactions
+- Test authentication and authorization
+- Check form submissions
+
+### Mobile Testing
+- Test on actual iPhone when possible
+- Use Safari developer tools
+- Test touch interactions
+- Verify responsive layouts
+- Check performance on 3G/4G
+
+## Code Review Process
+
+### Self-Review Checklist
+Before requesting review:
+
+1. **Functionality**
+   - Feature works as specified
+   - Edge cases handled
+   - Error messages are user-friendly
+
+2. **Code Quality**
+   - Follows style guide
+   - DRY principle applied
+   - Clear variable/function names
+   - Appropriate comments
+
+3. **Testing**
+   - Unit tests comprehensive
+   - Integration tests pass
+   - Coverage adequate (>80%)
+
+4. **Security**
+   - No hardcoded secrets
+   - Input validation present
+   - SQL injection prevented
+   - XSS protection in place
+
+5. **Performance**
+   - Database queries optimized
+   - Images optimized
+   - Caching implemented where needed
+
+6. **Mobile Experience**
+   - Touch targets adequate (44x44px)
+   - Text readable without zooming
+   - Performance acceptable on mobile
+   - Interactions feel native
+
+## Commit Guidelines
+
+### Message Format
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, missing semicolons, etc.
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests
+- `chore`: Maintenance tasks
+
+### Examples
+```bash
+git commit -m "feat(auth): Add remember me functionality"
+git commit -m "fix(posts): Correct excerpt generation for short posts"
+git commit -m "test(comments): Add tests for emoji reaction limits"
+git commit -m "style(mobile): Improve button touch targets"
+```
+
+## Definition of Done
+
+A task is complete when:
+
+1. All code implemented to specification
+2. Unit tests written and passing
+3. Code coverage meets project requirements
+4. Documentation complete (if applicable)
+5. Code passes all configured linting and static analysis checks
+6. Works beautifully on mobile (if applicable)
+7. Implementation notes added to `plan.md`
+8. Changes committed with proper message
+9. Git note with task summary attached to the commit
+
+## Emergency Procedures
+
+### Critical Bug in Production
+1. Create hotfix branch from main
+2. Write failing test for bug
+3. Implement minimal fix
+4. Test thoroughly including mobile
+5. Deploy immediately
+6. Document in plan.md
+
+### Data Loss
+1. Stop all write operations
+2. Restore from latest backup
+3. Verify data integrity
+4. Document incident
+5. Update backup procedures
+
+### Security Breach
+1. Rotate all secrets immediately
+2. Review access logs
+3. Patch vulnerability
+4. Notify affected users (if any)
+5. Document and update security procedures
+
+## Deployment Workflow
+
+### Pre-Deployment Checklist
+- [ ] All tests passing
+- [ ] Coverage >80%
+- [ ] No linting errors
+- [ ] Mobile testing complete
+- [ ] Environment variables configured
+- [ ] Database migrations ready
+- [ ] Backup created
+
+### Deployment Steps
+1. Merge feature branch to main
+2. Tag release with version
+3. Push to deployment service
+4. Run database migrations
+5. Verify deployment
+6. Test critical paths
+7. Monitor for errors
+
+### Post-Deployment
+1. Monitor analytics
+2. Check error logs
+3. Gather user feedback
+4. Plan next iteration
+
+## Continuous Improvement
+
+- Review workflow weekly
+- Update based on pain points
+- Document lessons learned
+- Optimize for user happiness
+- Keep things simple and maintainable