Add mux docs/skills to CLI + docs updated

.github/workflows/publish-docs.yml

@@ -0,0 +1,48 @@
+name: Publish Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "skill/**"
+      - "AGENTS.md"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Publish Docs Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generate docs-version.json
+        run: |
+          cat > docs-version.json << EOF
+          {
+            "date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "commit": "${{ github.sha }}"
+          }
+          EOF
+
+      - name: Create docs tarball
+        run: tar -czf mux-docs.tar.gz docs/ skill/ AGENTS.md docs-version.json
+
+      - name: Delete existing docs-latest release
+        run: gh release delete docs-latest --yes --cleanup-tag || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create docs-latest release
+        run: |
+          gh release create docs-latest \
+            --title "Latest Documentation" \
+            --notes "Automatically updated documentation bundle. Last updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --prerelease \
+            mux-docs.tar.gz \
+            docs-version.json
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -3,7 +3,7 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 permissions:
   contents: write
@@ -38,9 +38,30 @@ jobs:
           name: mux-${{ matrix.target }}
           path: ./dist/mux-${{ matrix.target }}
 
+  docs:
+    name: Package Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Generate docs-version.json
+        run: |
+          cat > docs-version.json << EOF
+          {
+            "date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "commit": "${{ github.sha }}"
+          }
+          EOF
+      - name: Create docs tarball
+        run: tar -czf mux-docs.tar.gz docs/ skill/ AGENTS.md docs-version.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: mux-docs
+          path: mux-docs.tar.gz
+
   release:
     name: Create Release
-    needs: build
+    needs: [build, docs]
+    if: always() && needs.build.result == 'success'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/download-artifact@v4
@@ -61,8 +82,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '24'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
       - uses: actions/download-artifact@v4
         with:
           path: artifacts
@@ -88,6 +109,7 @@ jobs:
           echo "darwin_x64=$(sha256sum artifacts/mux-darwin-x64 | cut -d ' ' -f1)" >> "$GITHUB_OUTPUT"
           echo "linux_arm64=$(sha256sum artifacts/mux-linux-arm64 | cut -d ' ' -f1)" >> "$GITHUB_OUTPUT"
           echo "linux_x64=$(sha256sum artifacts/mux-linux-x64 | cut -d ' ' -f1)" >> "$GITHUB_OUTPUT"
+          echo "docs=$(sha256sum artifacts/mux-docs.tar.gz | cut -d ' ' -f1)" >> "$GITHUB_OUTPUT"
 
       - name: Generate GitHub App token
         id: app-token
@@ -136,9 +158,20 @@ jobs:
               end
             end
 
+            resource "docs" do
+              url "${BASE_URL}/mux-docs.tar.gz"
+              sha256 "${{ steps.checksums.outputs.docs }}"
+            end
+
             def install
               binary = Dir.glob("mux-*").first || "mux"
               bin.install binary => "mux"
+
+              resource("docs").stage do
+                (share/"mux").install "docs"
+                (share/"mux").install "skill"
+                (share/"mux").install "AGENTS.md"
+              end
             end
 
             test do

.github/workflows/sync-docs.yml

@@ -0,0 +1,44 @@
+name: Sync Mux Docs
+
+on:
+  schedule:
+    - cron: '0 6 * * *' # Daily at 6am UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout CLI repo
+        uses: actions/checkout@v4
+
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.MUX_COM_APP_ID }}
+          private-key: ${{ secrets.MUX_COM_APP_PRIVATE_KEY }}
+          owner: muxinc
+          repositories: mux.com
+
+      - name: Run sync script
+        run: bash scripts/sync-docs.sh
+        env:
+          MUX_COM_TOKEN: ${{ steps.app-token.outputs.token }}
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: 'docs: sync guides from muxinc/mux.com'
+          title: 'docs: sync guides from muxinc/mux.com'
+          body: |
+            Automated sync of MDX guide files from `muxinc/mux.com`.
+
+            This PR was created automatically by the `sync-docs` workflow.
+          branch: docs-sync
+          delete-branch: true
+          labels: documentation

AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Instructions — Mux CLI
+
+## Mux Documentation
+
+The `docs/guides/` directory contains the full Mux documentation as MDX files, synced from the `muxinc/mux.com` repo. Use these files as the authoritative source for Mux API behavior, concepts, and integration patterns.
+
+For searching and using the docs, see the canonical guide in `skill/SKILL.md`.
+
+### Repo-specific notes
+
+- MDX files have YAML frontmatter with `title`, `product`, and `description` fields. They may contain JSX components; focus on the prose and code blocks for factual content.
+- Docs are synced daily via GitHub Actions. Run `bash scripts/sync-docs.sh` to update locally.
+- For installed copies of the CLI, prefer `mux docs path --json` over guessing npm, Homebrew, or shell-install locations.

Formula/mux.rb

@@ -24,9 +24,20 @@ class Mux < Formula
     end
   end
 
+  resource "docs" do
+    url "https://github.com/muxinc/cli/releases/download/v#{version}/mux-docs.tar.gz"
+    sha256 "PLACEHOLDER"
+  end
+
   def install
     binary = Dir.glob("mux-*").first || "mux"
     bin.install binary => "mux"
+
+    resource("docs").stage do
+      (share/"mux").install "docs"
+      (share/"mux").install "skill"
+      (share/"mux").install "AGENTS.md"
+    end
   end
 
   test do

README.md

@@ -52,6 +52,19 @@ npx @mux/cli
 curl -fsSL https://raw.githubusercontent.com/muxinc/cli/main/install.sh | bash
 ```
 
+### Agent skill and bundled docs
+
+The CLI ships with bundled Mux docs plus a standards-aligned `SKILL.md` so agents can use the CLI consistently across npm, Homebrew, and shell installs.
+
+To discover the installed paths:
+
+```bash
+mux docs path --json
+```
+
+This prints the paths to the bundled docs, packaged skill, and `AGENTS.md`.
+AI agents, use `mux docs path --json` to discover the Mux docs and skills
+
 ### Download the binary
 
 Download the latest binary for your platform from [GitHub Releases](https://github.com/muxinc/cli/releases):