Add mux docs/skills to CLI + docs updated

[Joshalphonse]

The CLI needs docs that act as agent skills. This keeps our Mux docs the single source of truth for all Mux documentation and info.

• Followed the Agent Skills standard
• AGENTS.MD is a pathway for other agents like (Cursor, Codex etc... ) to find the skills. Claude does a better job of just using SKILLS.MD.
• There are instructions to make the skills more discoverable by agents.
• GHA action to keep docs up to date on a daily sync and basis
• Update notifier available so that CLI users and Agents can see when the docs are updated and they can install it.
• Whenever a developer updates the CLI on their machine we also fetch for the latest docs as well so the docs are not stale.

User can also run the following commands

1. mux docs update — Downloads the latest docs from GitHub
2. mux docs update --check — Reports whether newer docs are available

---

Note

Medium Risk
Moderate risk due to new GitHub Actions workflows that publish/delete releases and modify Homebrew formula generation, which could affect release automation and distribution. Most other changes are additive documentation content and should be low risk.

Overview
Adds automated docs syncing and distribution: a scheduled sync-docs workflow pulls MDX guides from muxinc/mux.com via scripts/sync-docs.sh, and a publish-docs workflow packages docs/, skill/, AGENTS.md, and docs-version.json into a docs-latest GitHub prerelease.

Updates the tagged release pipeline to also build/upload a mux-docs.tar.gz artifact and (when present) include it in Homebrew installs by generating a resource "docs" stanza and installing docs into share/mux.

Adds AGENTS.md and expands README.md guidance around the bundled agent skill/docs and discovering installed paths via mux docs path --json, alongside a large import of new/updated guide content under docs/guides/.

^{Written by Cursor Bugbot for commit ddff86b. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Homebrew formula omits docs-version.json from install
  • Added docs-version.json to the Homebrew install list in both the checked-in formula and the release workflow’s generated formula template.

Or push these changes by commenting:

@cursor push 091ac6422d

Preview (091ac6422d)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -170,6 +170,7 @@
                 (share/"mux").install "docs"
                 (share/"mux").install "skill"
                 (share/"mux").install "AGENTS.md"
+                (share/"mux").install "docs-version.json"
               end
             end
 

diff --git a/Formula/mux.rb b/Formula/mux.rb
--- a/Formula/mux.rb
+++ b/Formula/mux.rb
@@ -37,6 +37,7 @@
       (share/"mux").install "docs"
       (share/"mux").install "skill"
       (share/"mux").install "AGENTS.md"
+      (share/"mux").install "docs-version.json"
     end
   end

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Homebrew formula omits docs-version.json from install

Medium Severity

The docs tarball is created with docs-version.json included (tar -czf mux-docs.tar.gz docs/ skill/ AGENTS.md docs-version.json), but the Homebrew resource("docs").stage block only installs docs, skill, and AGENTS.md — it never installs docs-version.json. Since mux docs update --check reports whether newer docs are available, the CLI likely needs the local docs-version.json to compare against the remote version. Homebrew users would be missing this metadata file, potentially breaking the update-check feature.

Additional Locations (1)

• .github/workflows/release.yml#L168-L173

 

[Joshalphonse]

@dylanjha Would just need to discuss the GHA actions sync. Need to make a Github App Token

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}