Consolidate agent skills and fix stale docs (Windows deploy, repo map, design docs)

[michaelneale]

Agents (and humans) working in this repo now get accurate, consolidated how-to skills for every platform, a repo map that matches the actual workspace, and design docs that no longer describe the retired external llama-server/rpc-server world as current fact.

Skills consolidation (.skills/)

• deploy-macos (rewritten, renamed from deploy) — the old skill described the pre-embedded-runtime world: rpc-server/llama-server/.dylib bundles, ~/.models/ storage, manual GGUF pre-download. Rewritten for the single-binary embedded runtime: release install (incl. --service launchd), dev-bundle deploy with codesign/xattr quarantine fix, verification, troubleshooting.
• deploy-windows (new) — captures the install.ps1 work from Fix Windows install on PowerShell 5.1 (irm | iex and missing checksum sidecar) #828: irm | iex flow, flavor selection (cuda-blackwell/cuda/rocm/vulkan/cpu), the PowerShell 5.1 [ValidateSet]-under-iex and response-less-WebException checksum gotchas, contrib/windows helpers, curl.exe vs the IWR alias, verification, troubleshooting.
• mesh-join (new) — creating/joining/publishing meshes: invite-token flow, --auto/public mesh, named meshes, mDNS LAN mode, NAT/--bind-ip/--bind-port/Docker-bridge gotchas, multi-node verification.
• connect-agents (new) — pointing Goose/Claude Code/OpenCode/Pi or any OpenAI client at a mesh: built-in launchers, auto vs mesh vs exact model ids, QA probes, blackboard + MCP.
• deploy-linux-gpu — cross-links to the sibling skills, systemd --service install path added.
• .skills/README.md (new) — index plus the shared ground rules (single binary, never pre-download models, --headless ≠ quiet, prefer mesh-llm stop) so conflicting instructions can't silently reappear.

Repo map and process docs

• AGENTS.md — removed phantom docs (MoE_PLAN, MoE_DEPLOY_DESIGN, LLAMA_CPP_FORK, docs/moe/) and phantom crates (mesh-api, mesh-api-ffi, mesh-host-core); documented the real CLI split (mesh-llm-cli / mesh-llm-commands / crates/mesh-llm/src/commands/ — the host-runtime src/cli/ directory referenced by three placement rules no longer exists); expanded the crate list to cover ~20 unlisted crates; fixed just clean-ui → just ui-clean, the version-bump location (workspace Cargo.toml), the in-tree plugin list (only blobstore remains in-tree), and the deploy snippet ("three binaries" → single binary).
• Release flow — AGENTS.md and RELEASE.md now lead with the actual process: dispatch the Release workflow from the GitHub Actions UI (workflow_dispatch with version input, skip_gpu_bundles/canary options). The previously documented just release v0.X.Y recipe does not exist.

Design doc corrections

Only stale-as-fact content was changed; future-looking proposals were left alone, and historical content got explicit status framing instead of rewrites:

• DESIGN.md — architecture tree updated to the real mesh-llm-host-runtime module layout (no src/cli/, no network/rewrite.rs); NodeRole comments, the QUIC stream table, bootstrap proxy, and B2B transfer sections no longer claim external llama-server/rpc-server processes.
• METRICS.md — /api/runtime/llama producer flow corrected: snapshots come from the embedded runtime's lane status (LocalRuntimeModelHandle::llama_slots_snapshot), not an external llama-server /metrics+/slots poller.
• message_protocol.md — added the missing 0x0a PLUGIN_MESH_STREAM and 0x0d SUBPROTOCOL rows to the stream-type table (both already documented in prose / implemented in protocol/mod.rs).
• VIRTUAL_LLM.md — status note mapping the llama-server-era hook design to the current in-process implementation paths (inference/skippy/hooks.rs, skippy-server before-chat hooks) and marking the llama-patches/ + sync.sh co-iteration setup as gone.
• MODEL_ROUTER.md — marked Phase 1 as shipped (network/router.rs) with a pointer to ROUTER_V2.md.
• LLAMA_STAGE_INTEGRATION_PLAN.md — marked completed/historical so its "Current State" section (external runtime processes) can't be read as current.

Validation

• Every file/crate/script/recipe path referenced in the updated AGENTS.md and design docs verified to exist (automated existence sweep, zero misses).
• Stream-type table checked against crates/mesh-llm-host-runtime/src/protocol/mod.rs; metrics producer flow traced through runtime/local.rs → runtime_data/producers.rs; release flow checked against .github/workflows/release.yml.
• Windows skill facts checked against install.ps1, commit cb3a818 (Fix Windows install on PowerShell 5.1 (irm | iex and missing checksum sidecar) #828), and contrib/windows/.
• GIT_MASTER=1 git diff --check clean. Docs/skills-only change — no code paths touched.

Summary by CodeRabbit

• Documentation
  • Added .skills/README.md overview and mapping of repo skills
  • Added skill docs: connect-agents, mesh-join; updated deploy-macos, deploy-windows, deploy-linux-gpu; removed legacy deploy guide
  • Expanded AGENTS.md and RELEASE.md guidance
  • Updated multiple design docs (architecture, model router, virtual-LLM, metrics, message protocol) to reflect current runtime and staging model behavior

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 66816a25-71f7-4748-bb0f-2fa79962c8fc

📥 Commits

Reviewing files that changed from the base of the PR and between 96507ea and 2e04ce4.

📒 Files selected for processing (1)

• docs/design/DESIGN.md

✅ Files skipped from review due to trivial changes (1)

• docs/design/DESIGN.md

---

📝 Walkthrough

Walkthrough

This pull request restructures documentation across the mesh-llm repository. It introduces a new .skills/ framework organizing platform-specific deployment and connectivity guides, removes generic deployment documentation, updates developer workspace orientation and release automation guidance, and aligns design documentation with the completed staged-runtime architecture migration.

Changes

Documentation Restructure for Skills Framework and Architecture

Layer / File(s)	Summary
Skills framework and index .skills/README.md	Introduces the organizational model for agent skills, mapping each skill to use cases and documenting shared ground rules and skill sources.
Platform-specific deployment skills .skills/deploy-linux-gpu/SKILL.md, .skills/deploy-macos/SKILL.md, .skills/deploy-windows/SKILL.md	Comprehensive guides for installing and operating mesh-llm on each platform, including service setup, verification, log locations, and troubleshooting. Removes generic .skills/deploy/SKILL.md in favor of platform-focused documentation.
Network connectivity and agent integration skills .skills/connect-agents/SKILL.md, .skills/mesh-join/SKILL.md	Guides for connecting external agents/clients to mesh-llm's OpenAI-compatible API and for creating/joining multi-node mesh deployments with discovery, model splitting, and ownership configuration.
Developer workspace and release automation documentation AGENTS.md, RELEASE.md, crates/mesh-llm-ui/AGENTS.md	Updates repository orientation, workspace crate ownership, module structure rules, deployed bundle responsibilities, and documents GitHub Actions workflow-dispatch release flow. Corrects UI tooling commands.
Design documentation architecture updates docs/design/DESIGN.md, docs/design/LLAMA_STAGE_INTEGRATION_PLAN.md, docs/design/METRICS.md, docs/design/MODEL_ROUTER.md, docs/design/VIRTUAL_LLM.md, docs/design/message_protocol.md	Updates design docs to reflect staged-runtime architecture: clarifies terminology, updates stream type definitions, rewrites metrics and transfer flows, and adds status notes marking Phase 1 implementation and historical rationale.

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly summarizes the PR's main focus: consolidating agent skills documentation and correcting stale documentation in Windows deploy, repository map, and design docs. It accurately reflects the comprehensive documentation update across multiple files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch micn/skills-and-docs-refresh

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/design/DESIGN.md (1)

21-21: 💤 Low value

Add language specifier to fenced code block.

The code block at line 21 lacks a language tag, triggering markdownlint MD040. Add text or sh to the opening fence.

🔧 Proposed fix

-```
+```text
 crates/mesh-llm-host-runtime/src/

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/design/DESIGN.md` at line 21, The fenced code block opening fence at the
reported location is missing a language specifier (causing markdownlint MD040);
update the opening triple-backtick to include a language like `text` or `sh` so
the block becomes a fenced block with a language tag (e.g., change the opening
fence for the snippet that contains "crates/mesh-llm-host-runtime/src/" to use
```text or ```sh).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/design/DESIGN.md`:
- Line 21: The fenced code block opening fence at the reported location is
missing a language specifier (causing markdownlint MD040); update the opening
triple-backtick to include a language like `text` or `sh` so the block becomes a
fenced block with a language tag (e.g., change the opening fence for the snippet
that contains "crates/mesh-llm-host-runtime/src/" to use ```text or ```sh).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2cddb0d7-d3c2-47d9-9921-f755d770fea9

📥 Commits

Reviewing files that changed from the base of the PR and between f25aa0d and 96507ea.

📒 Files selected for processing (16)

• .skills/README.md
• .skills/connect-agents/SKILL.md
• .skills/deploy-linux-gpu/SKILL.md
• .skills/deploy-macos/SKILL.md
• .skills/deploy-windows/SKILL.md
• .skills/deploy/SKILL.md
• .skills/mesh-join/SKILL.md
• AGENTS.md
• RELEASE.md
• crates/mesh-llm-ui/AGENTS.md
• docs/design/DESIGN.md
• docs/design/LLAMA_STAGE_INTEGRATION_PLAN.md
• docs/design/METRICS.md
• docs/design/MODEL_ROUTER.md
• docs/design/VIRTUAL_LLM.md
• docs/design/message_protocol.md

💤 Files with no reviewable changes (1)

• .skills/deploy/SKILL.md