chore(ai): modernize and unify agent tooling and instructions (#5087)

.github/copilot-commit-message-instructions.md

@@ -0,0 +1,27 @@
+# GitHub Copilot Commit Message Instructions
+
+<role>
+You are an expert Git maintainer enforcing Conventional Commits.
+</role>
+
+<instructions>
+1. **Format:** Use the Conventional Commits format: `<type>(<scope>): <subject>` (Replace angle brackets with actual text, do NOT output angle brackets).
+2. **Types allowed:**
+   - `feat` (new feature for the user, not a new feature for build script)
+   - `fix` (bug fix for the user, not a fix to a build script)
+   - `docs` (changes to the documentation)
+   - `style` (formatting, missing semi colons, etc; no production code change)
+   - `refactor` (refactoring production code, e.g. KMP migration, extracting to commonMain)
+   - `test` (adding missing tests, refactoring tests; no production code change)
+   - `chore` (updating grunt tasks etc; no production code change)
+3. **Scope:** Use the module or logical component as the scope (e.g., `ui`, `navigation`, `ble`, `firmware`, `deps`, `ai`).
+4. **Subject line:** 
+   - Use the imperative, present tense: "change" not "changed" nor "changes".
+   - Do not capitalize the first letter.
+   - Do not use a period (.) at the end.
+   - Keep it under 50 characters if possible.
+5. **Body (Optional but recommended for large diffs):** 
+   - Leave one blank line after the subject.
+   - Explain *why* the change was made, not just *what* changed.
+   - If migrating to KMP or extracting to `commonMain`, explicitly state "Decoupled from Android framework".
+</instructions>

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
-# Meshtastic Android - Agent Guide
+# Meshtastic Android - GitHub Copilot Guide
 
-**Canonical instructions live in [`AGENTS.md`](../AGENTS.md).** This file exists at `.github/copilot-instructions.md` so GitHub Copilot discovers it automatically.
+> **Note:** The canonical instructions for all AI Agents have been deduplicated. 
 
-See [AGENTS.md](../AGENTS.md) for architecture, conventions, execution protocol, and coding standards.
-See [docs/agent-playbooks/README.md](../docs/agent-playbooks/README.md) for version baselines and task recipes.
+You MUST immediately read and internalize the unified instructions located at the root of the repository in `AGENTS.md`. 
+After reading `AGENTS.md`, consult the `.skills/` directory for task-specific playbooks.

.github/copilot-pull-request-instructions.md

@@ -0,0 +1,18 @@
+# GitHub Copilot Pull Request Instructions
+
+<role>
+You are an expert open-source maintainer. Your goal is to write clear, professional, and highly structured Pull Request descriptions based on the provided diffs.
+</role>
+
+<instructions>
+1. **Remove Boilerplate:** Always delete the "tips" section at the top of the `PULL_REQUEST_TEMPLATE.md` before generating your text.
+2. **Context First:** Start with a clear, 1-2 sentence summary of *why* this change is being made. If the branch name or commits reference an issue (e.g., `fix-1234`), explicitly add `Fixes #1234` or `Resolves #1234`.
+3. **Structured Changes:** Break down the code changes into bullet points categorized by:
+   - 🌟 **New Features** (UI, modules, logic)
+   - 🛠️ **Refactoring & Architecture** (KMP migrations, Koin DI updates)
+   - 🐛 **Bug Fixes**
+   - 🧹 **Chores** (Dependencies, formatting, docs)
+4. **Architecture Callouts:** If the diff includes moving files from `androidMain` to `commonMain`, or migrating from Android Views to Compose, highlight this as a "KMP Migration Milestone".
+5. **Testing Callouts:** If the diff includes changes to `commonTest` or mentions tests, add a section called "Testing Performed" and list the tests that were added/modified.
+6. **No "Magic" Text:** Do not invent URLs or insert fake image placeholders. Leave the HTML comment block for images intact so the user can manually add their screenshots.
+</instructions>

.github/instructions/android-source-set.instructions.md

@@ -0,0 +1,11 @@
+---
+applyTo: "**/androidMain/**/*.kt"
+---
+
+# Android Source-Set Rules
+
+- This is `androidMain` — Android framework imports (`android.*`, `java.*`) are allowed here.
+- Do NOT put business logic here. Business logic belongs in `commonMain`.
+- If you find identical pure-Kotlin logic in both `androidMain` and `jvmMain`, extract it to `commonMain`.
+- Use `expect`/`actual` only for small platform primitives. Prefer interfaces + DI.
+- Keep `expect` declarations in `FileIo.kt` and shared helpers in `FileIoUtils.kt` to avoid JVM duplicate class errors.

.github/instructions/build-logic.instructions.md

@@ -0,0 +1,10 @@
+---
+applyTo: "build-logic/**/*.kt"
+---
+
+# Build-Logic Convention Plugin Rules
+
+- Prefer lazy Gradle configuration (`configureEach`, `withPlugin`, provider APIs).
+- Avoid `afterEvaluate` unless there is no viable lazy alternative.
+- Check `gradle/libs.versions.toml` for version catalog aliases before adding new ones.
+- Convention plugins: `meshtastic.kmp.feature`, `meshtastic.kmp.library`, `meshtastic.kmp.jvm.android`, `meshtastic.koin`.

.github/instructions/ci-workflows.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "**/*.yml"
+excludeAgent: "code-review"
+---
+
+# CI Workflow Rules
+
+- Prefer explicit Gradle task paths (`app:lintFdroidDebug`) over shorthand (`lintDebug`).
+- CI uses `.github/ci-gradle.properties` — don't assume local `gradle.properties` values.
+- CI passes `-Pci=true` to enable full processor usage via `maxParallelForks`.
+- Use `fetch-depth: 0` only where needed (spotless ratcheting, version code). Use `fetch-depth: 1` otherwise.
+- Desktop build matrix: `macos-latest`, `windows-latest`, `ubuntu-24.04`, `ubuntu-24.04-arm`.
+- Lightweight jobs (labelers, triage, stale): use `ubuntu-24.04-arm` runners.
+- Gradle-heavy jobs: use `ubuntu-24.04` runners.

.github/instructions/kmp-common.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: "**/commonMain/**/*.kt"
+---
+
+# KMP commonMain Rules
+
+- NEVER import `java.*` or `android.*` in `commonMain`.
+- Use `org.meshtastic.core.common.util.ioDispatcher` instead of `Dispatchers.IO`.
+- Use Okio (`BufferedSource`/`BufferedSink`) instead of `java.io.*`.
+- Use `kotlinx.coroutines.sync.Mutex` instead of `java.util.concurrent.locks.*`.
+- Use `atomicfu` or Mutex-guarded `mutableMapOf()` instead of `ConcurrentHashMap`.
+- Use `jetbrains-*` catalog aliases for lifecycle/navigation dependencies.
+- Use `compose-multiplatform-*` catalog aliases for CMP dependencies.
+- Never use plain `androidx.compose` dependencies in `commonMain`.
+- Strings: use `stringResource(Res.string.key)` from `core:resources`. No hardcoded strings.
+- CMP `stringResource` only supports `%N$s` and `%N$d` — pre-format floats with `NumberFormatter.format()`.
+- Check `gradle/libs.versions.toml` before adding dependencies.