feat: auto-generated showcase site (commands.json + llms.txt + GitHub Pages)

[jklaassenjc]

Summary

Borrows the pattern from jamf-cli's generator/site/. Generates a public command catalog from internal/schema — the same source jc schema uses, so single source of truth. Adding a new command means: edit schema.go, run make site, commit. The verify-site CI gate catches "forgot to regenerate" on PRs; the deploy-site workflow regenerates at deploy time as belt-and-suspenders so Pages always reflects what's actually shipping.

What's included

• cmd/sitegen/main.go — renders the schema manifest into three artifacts:
  • docs/site/commands.json — manifest + sidebar categories
  • docs/site/llms.txt — short index per llmstxt.org spec
  • docs/site/llms-full.txt — full agent-facing reference
• docs/site/index.html — vanilla HTML+JS, zero build dependencies:
  • ⌘K-focusable filter searches name, description, category, subcommands, every flag
  • Category sidebar with scroll-spy active state
  • Per-command card: subcommand chips + flags table
  • Dark/light mode follows prefers-color-scheme
  • Hand-curated long-form paragraphs (with inline `code` / *italic*) for commands where the one-line description undersells the feature
• internal/schema/schema.go — adds optional Long field to CommandEntry. Populated for the 7 commands in Setup + AI & Automation in this PR; the field is omitempty so other commands can be enriched incrementally.
• Makefile — make site to regenerate, make verify-site to diff against committed artifacts.
• .github/workflows/verify-site.yml — PR-time stale-catalog detector. Path-filtered to schema, sitegen, docs/site/, and Makefile changes.
• .github/workflows/deploy-site.yml — main-merge deploy via actions/upload-pages-artifact + actions/deploy-pages.
• README.md — site link in header, contributor notes under Development.

Why this design

• Single source of truth: internal/schema already powers jc schema, the MCP server, and jc ask. Reusing it means the catalog can never drift from what the CLI actually exposes.
• No build pipeline: vanilla HTML+JS. Anyone can read or edit index.html directly. No npm, no bundler, no version pinning.
• Defense in depth on staleness: verify-site (PR gate) + regenerate-at-deploy (workflow). One can fail; the other catches.
• Version field stripped from commands.json so git-describe churn doesn't churn the artifact every commit.

Manual step after merge

Enable Pages for the repo: Settings → Pages → Source: GitHub Actions. URL will be https://thejumpcloud.github.io/jc-cli/.

Stats

• 38 commands rendered under 9 categories
• 7 commands have long-form elaborations (auth, config, recipe, mcp, schema, ask, explain)
• llms-full.txt is ~16 KB; well-formed markdown
• commands.json is ~33 KB

Test plan

• make site regenerates all four artifacts deterministically
• make verify-site clean against committed copies
• make verify-site exits non-zero when artifacts drift (sanity-checked by editing schema and re-running)
• Local browser walk: ⌘K filter, sidebar nav, scroll-spy, dark/light mode, mobile breakpoint
• All four artifacts serve over python3 -m http.server and return 200
• go vet ./... clean
• go test ./internal/schema/... ./internal/api/... clean
• After merge: enable Pages in Settings → Pages → Source: GitHub Actions, then verify https://thejumpcloud.github.io/jc-cli/ resolves

Refs KLA-442

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation, static site generation, and CI only; no runtime CLI or API behavior changes beyond optional schema manifest fields.

Overview
Adds a schema-driven public command catalog for GitHub Pages: new cmd/sitegen renders schema.BuildCommandManifest() into commands.json, llms.txt, and llms-full.txt (with sidebar categories; version omitted from JSON to avoid churn).

Makefile gains make site and make verify-site (diff committed artifacts vs fresh generation). CI: verify-site on PRs when schema/site paths change; deploy-site on main runs make site then publishes docs/site via GitHub Pages.

docs/site/index.html is a static, no-build UI that loads commands.json (search, categories, command cards). internal/schema: optional Long on CommandEntry with copy for seven Setup/AI commands. README links the catalog and documents the regenerate workflow.

^{Reviewed by Cursor Bugbot for commit e479d43. Bugbot is set up for automated code reviews on this repo. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	github/​actions/​deploy-pages@​d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e
	github/​actions/​upload-pages-artifact@​56afc609e74202658d3ffba0e8f6dda462b719fa
	github/​actions/​configure-pages@​983d7736d9b0ae728b81ab479565c72886d7745b
	github/​actions/​checkout@​93cb6efe18208431cddfb8368fd83d5badbf9bfd

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: github actions/upload-artifact is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → github/actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa → github/actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore github/actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Reviewed by Cursor Bugbot for commit 9469f96. Configure here.}