From 7d1eb57b888e8e567700975105a2a505632cf91a Mon Sep 17 00:00:00 2001
From: Eric Searcy <eric@linuxfoundation.org>
Date: Wed, 15 Jul 2026 11:38:11 -0700
Subject: [PATCH] Add gh-pages install script, CIMD metadata, and docs
 publishing

- Add curl-style install.sh and Auth0 CIMD client-metadata.json on the new
  gh-pages branch, served via GitHub Pages.
- Add a publish-docs job to the release-tag workflow that generates
  Markdown CLI reference docs via 'lfx docs' and publishes them to
  gh-pages/docs/cli.md on every tagged release.
- Document the curl-style installer as the primary install method in the
  README, with go install as an alternative.
- Document the gh-pages branch and its maintenance in AGENTS.md.

Assisted-by: github-copilot:claude-sonnet-5
Signed-off-by: Eric Searcy <eric@linuxfoundation.org>
---
 .github/workflows/release-tag.yml | 46 +++++++++++++++++++++++++++++++
 AGENTS.md                         | 25 +++++++++++++++--
 README.md                         | 15 ++++++++--
 3 files changed, 80 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml
index 05dc550..69e362a 100644
--- a/.github/workflows/release-tag.yml
+++ b/.github/workflows/release-tag.yml
@@ -43,3 +43,49 @@ jobs:
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-docs:
+    name: Publish CLI docs to gh-pages
+    needs: goreleaser
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff  # v5.6.0
+        with:
+          go-version-file: go.mod
+          cache: false
+
+      - name: Generate CLI reference docs
+        run: go run ./cmd/lfx docs --output ./docs-out
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          ref: gh-pages
+          path: gh-pages
+          persist-credentials: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish docs
+        run: |
+          mkdir -p gh-pages/docs
+          cp docs-out/cli.md gh-pages/docs/cli.md
+          cd gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet -- docs/cli.md; then
+            echo "No changes to docs/cli.md; skipping commit."
+            exit 0
+          fi
+          git add docs/cli.md
+          git commit -s -m "docs: publish CLI reference for ${GITHUB_REF_NAME}"
+          git push origin gh-pages
diff --git a/AGENTS.md b/AGENTS.md
index 9755211..02bc6c7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,8 +49,9 @@ Credential storage (system keychain via `99designs/keyring`) and the Auth0
 CIMD client are tracked separately.
 
 **No container build**: this project produces binary artifacts only,
-distributed via GitHub Releases and `go install`. There is no Dockerfile,
-Helm chart, or container image pipeline.
+distributed via GitHub Releases, the `install.sh` curl-style installer
+hosted on `gh-pages`, and `go install`. There is no Dockerfile, Helm
+chart, or container image pipeline.
 
 ## Development Workflow
 
@@ -157,13 +158,31 @@ between files in the same package.
 
 The hidden `lfx docs` command generates Markdown reference documentation
 for all commands via `cli-docs.ToMarkdown()`, intended for local agent use
-and future publishing to the `gh-pages` branch:
+and for publishing to the `gh-pages` branch:
 
 ```bash
 lfx docs                    # Print to stdout
 lfx docs --output ./docs     # Write to ./docs/cli.md
 ```
 
+## gh-pages Branch
+
+The `gh-pages` branch is a static asset branch (not source code) served at
+`https://linuxfoundation.github.io/lfx-cli/`. It holds:
+
+- `install.sh` -- the curl-style installer referenced in the README
+- `client-metadata.json` -- the CIMD (Client ID Metadata Document) for the
+  LFX CLI's Auth0 Device Code client; this URL *is* the client_id (see
+  `auth0-terraform`'s `clients_cimd.tf` for the corresponding client
+  definition)
+- `docs/cli.md` -- generated CLI reference docs, republished on every
+  tagged release by the **Publish Tagged Release** workflow's
+  `publish-docs` job (see `.github/workflows/release-tag.yml`)
+
+Only edit `install.sh` or `client-metadata.json` directly on `gh-pages`
+when the install flow or CIMD metadata changes; `docs/cli.md` is
+regenerated automatically and should not be hand-edited.
+
 ## Release Process
 
 Releases follow [semantic versioning](https://semver.org/) (`vMAJOR.MINOR.PATCH`).
diff --git a/README.md b/README.md
index feff76f..7d4dcc4 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,20 @@ token`).
 ## Installation
 
 ```bash
-go install github.com/linuxfoundation/lfx-cli/cmd/lfx@latest
+curl -sSL https://linuxfoundation.github.io/lfx-cli/install.sh | sh
 ```
 
-Prebuilt binaries for Linux, macOS, and Windows are also published on the
-[Releases](https://github.com/linuxfoundation/lfx-cli/releases) page.
+This downloads the correct prebuilt binary for your OS/architecture from the
+[Releases](https://github.com/linuxfoundation/lfx-cli/releases) page,
+verifies its checksum, and installs it to `/usr/local/bin` (or `~/.local/bin`
+if that's not writable). Set `LFX_CLI_VERSION` to pin a specific release, or
+`LFX_CLI_INSTALL_DIR` to override the install location.
+
+Alternatively, install with Go:
+
+```bash
+go install github.com/linuxfoundation/lfx-cli/cmd/lfx@latest
+```
 
 ## Usage