docs: add agent-guided mesh installation runbook by michaelneale · Pull Request #1003 · Mesh-LLM/mesh-llm

michaelneale · 2026-07-15T20:52:14Z

Summary

add an assistant-led workflow for setting up a private mesh
cover release selection, hardware survey, node enrollment, serving plans, diagnostics, and agent-harness connection
include secret-safe journaling and real-world failure references

Status

Draft preserved from the earlier installation-guide work for review and refinement.

Summary by CodeRabbit

Documentation
- Added new agent-facing runbooks for setting up a private Mesh LLM, including supervised install flow, capability/model discovery, node enrollment, topology planning, and bounded serving verification.
- Published the setup guide as a new website page for easy access.
Build & Deployment
- Updated website build/publishing instructions and artifact output mapping to match the generated site structure.
- Adjusted the website publishing workflow to include the new setup guide in the deployed pages artifact.

coderabbitai · 2026-07-15T20:52:23Z

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: ff5d22de-1187-40d6-bf4a-9489498eac71

📥 Commits

Reviewing files that changed from the base of the PR and between f68e388 and a5d8afe.

📒 Files selected for processing (4)

.github/workflows/website-pages.yml
AGENTS.md
docs/setup-mesh
install.md

🚧 Files skipped from review as they are similar to previous changes (2)

AGENTS.md
docs/setup-mesh

📝 Walkthrough

Walkthrough

Adds comprehensive interactive Mesh LLM installation runbooks covering setup, enrollment, topology, diagnostics, harness integration, and completion reporting. The website build now publishes the root runbook as docs/setup-mesh, with updated artifact documentation.

Changes

Mesh setup runbook

Layer / File(s)	Summary
Runbook operating rules and environment discovery `install.md`, `docs/setup-mesh`	Defines interactive approval, verification, release detection, hardware surveying, and evidence-based model selection workflows.
Mesh launch, enrollment, and topology planning `install.md`, `docs/setup-mesh`	Documents supervised startup, invite-token enrollment, node join validation, inference checks, and topology planning for independent, replica, and split deployments.
Failure diagnosis, harness integration, and completion records `install.md`, `docs/setup-mesh`	Adds failure classification, remote investigation guidance, harness integration, tool-call validation, secret-free journaling, completion reporting, and references.
Website artifact publication contract `website/.eleventy.js`, `.github/workflows/website-pages.yml`, `AGENTS.md`, `website/AGENTS.md`	Publishes `install.md` as `setup-mesh`, stages the generated artifact, updates workflow triggers, and documents generated website paths.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: i386, ndizazzoeriwa

Sequence Diagram(s)

sequenceDiagram
  participant Assistant
  participant MeshCLI
  participant MainNode
  participant AdditionalNode
  Assistant->>MeshCLI: start supervised serve with JSON logs
  MeshCLI->>MainNode: emit invite token and serve status
  Assistant->>AdditionalNode: run generated enrollment block
  AdditionalNode->>MainNode: join private mesh
  Assistant->>MainNode: poll status and model endpoints
  Assistant->>MainNode: run bounded chat completion

🚥 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 clearly matches the main change: adding an agent-guided Mesh installation runbook in docs.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch wip/mesh-install-guide

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

github-actions · 2026-07-15T20:52:23Z

This pull request is currently a draft. Reviews will not take place until the PR is marked as ready for review.

ndizazzo

@michaelneale These are my agent review findings, after feeding it to Sol to follow

michaelneale · 2026-07-17T00:44:07Z

@ndizazzo you want to push some changes and take this one over - mostly I am focussing on the wording to guide the agent, but could use with some eyes on making sure it shows up on website right and does reasonable stuff, so feel free to push away.

ndizazzo · 2026-07-17T11:18:55Z

@michaelneale SG, generally I try to comment only JIC things are still being worked on, but I can take over if you want to focus elsewhere

…m issue links - Add a goal->section routing table so single-machine goals (e.g. local coding agent) take a short path instead of the full multi-node mesh runbook. - Instruct assistants to filter `models installed` output down to runnable models, excluding layer-package internals and split shards, and show at most three candidates. Workaround for #1004. - Collapse the GitHub issue reference list into inline pointers; the operational lessons are already folded into the relevant sections.

…unbook

coderabbitai

Actionable comments posted: 2

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

Inline comments:
In `@AGENTS.md`:
- Around line 41-42: Update the generated-artifact manifest in AGENTS.md to
include docs/funding.json and docs/.well-known/ alongside the existing docs
entries, matching the Eleventy passthrough copy set. The corresponding entries
in website/AGENTS.md require no direct change because they already provide the
reference manifest.

In `@install.md`:
- Around line 496-498: Update the “Node joins as standby” diagnosis in
install.md to state that standby is expected only when enrollment omitted
--model; otherwise treat it as evidence of a failed serving launch. Regenerate
docs/setup-mesh from the corrected install.md wording at its corresponding
section.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 362a26ef-b518-4afb-82c6-bf5be0f3d29c

📥 Commits

Reviewing files that changed from the base of the PR and between b84dd14 and f68e388.

📒 Files selected for processing (5)

AGENTS.md
docs/setup-mesh
install.md
website/.eleventy.js
website/AGENTS.md

ndizazzo reviewed Jul 16, 2026

View reviewed changes

Comment thread website/.eleventy.js

Comment thread docs/setup-mesh Outdated

Comment thread install.md Outdated

Comment thread install.md Outdated

ndizazzo self-assigned this Jul 17, 2026

michaelneale and others added 5 commits July 17, 2026 07:48

WIP: add agent-guided mesh installation runbook

9ede8d8

Publish install runbook at meshllm.cloud/setup-mesh

3701841

Add setup-mesh self-reference and absolute doc links in install runbook

ab11e3c

docs: add split serving preflight and failure signatures to install r…

f68e388

…unbook

ndizazzo force-pushed the wip/mesh-install-guide branch from 1da241c to f68e388 Compare July 17, 2026 11:48

ndizazzo marked this pull request as ready for review July 17, 2026 11:57

github-actions Bot requested a review from i386 July 17, 2026 11:58

github-actions Bot assigned michaelneale Jul 17, 2026

coderabbitai Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread install.md Outdated

address feedback items in PR

a5d8afe

ndizazzo merged commit d982c3f into main Jul 17, 2026
18 checks passed

ndizazzo deleted the wip/mesh-install-guide branch July 17, 2026 15:30

coderabbitai Bot mentioned this pull request Jul 28, 2026

Document canonical Homebrew tap #1102

Merged

Navigation Menu

Uh oh!

Uh oh!

docs: add agent-guided mesh installation runbook - #1003

docs: add agent-guided mesh installation runbook#1003
ndizazzo merged 6 commits into
mainfrom
wip/mesh-install-guide

michaelneale commented Jul 15, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 15, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Jul 15, 2026

Uh oh!

ndizazzo left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michaelneale commented Jul 17, 2026

Uh oh!

ndizazzo commented Jul 17, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

michaelneale commented Jul 15, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Status

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Jul 15, 2026

Uh oh!

ndizazzo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michaelneale commented Jul 17, 2026

Uh oh!

ndizazzo commented Jul 17, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

michaelneale commented Jul 15, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 15, 2026 •

edited

Loading

ndizazzo left a comment •

edited

Loading