feat(docs): publish YARD API docs + llms.txt to GitHub Pages

[gjtorikian]

Summary

• Adds a YARD-based API reference for the workos gem (HTML + Markdown via yard-markdown), published to GitHub Pages on tag pushes (docs.workos.com/sdk/ruby).
• Workflow tars docs/_site manually and uploads via actions/upload-artifact named "github-pages" to avoid actions/upload-pages-artifact, which Socket flagged for a ghaArgToSink taint.
• Adds script/llms-txt to generate an llms.txt index (per llmstxt.org) at the site root, so LLM tooling can locate per-class refs in one fetch.
• Adds script/docs and script/docs-serve for local builds and previews; ignores docs/_site and .yardoc.

Test plan

• Run script/docs locally and confirm docs/_site/index.html, per-class .md files, and llms.txt are generated.
• Run script/docs-serve and confirm the site renders at http://localhost:4000.
• Trigger the Publish API Docs workflow via workflow_dispatch and verify the build job's github-pages artifact contains the tarred site.
• Confirm the deploy job succeeds and the published site loads.

---

[greptile-apps]

Greptile Summary

This PR adds a YARD-based API documentation pipeline — publishing HTML and Markdown docs plus an llms.txt index to GitHub Pages on tag pushes, with local build and preview scripts.

• Adds .github/workflows/docs.yml to build and deploy the docs site on v* tag pushes or manual dispatch; the deploy job is missing the pages: write and id-token: write permissions that actions/deploy-pages requires, so every deploy will fail until that is fixed.
• Adds script/docs, script/docs-serve, and script/llms-txt for local doc generation and serving; the scripts correctly scope the docs bundle group and are otherwise well-structured.
• Adds yard, yard-markdown, and webrick to a new docs Gemfile group so they are not pulled into production or CI non-docs installs.

Confidence Score: 4/5

The workflow will fail on every attempted deploy because the deploy job lacks the permissions that actions/deploy-pages requires.

The build and scripting logic is sound, but the deploy job omits the pages: write and id-token: write permissions that actions/deploy-pages needs to obtain an OIDC token and publish the site. Every tag push or manual dispatch will build successfully then fail at the deploy step, meaning no docs are ever published until this is corrected.

.github/workflows/docs.yml — the deploy job permissions block needs attention.

Important Files Changed

Filename	Overview
.github/workflows/docs.yml	New CI workflow for publishing YARD docs to GitHub Pages; deploy job is missing the required pages: write and id-token: write permissions, causing it to always fail at the deploy-pages step.
script/docs	Build script that installs the docs bundle group and runs YARD twice (HTML then Markdown) before generating llms.txt; logic is correct and intentional per inline comments.
script/llms-txt	Ruby script that walks docs/_site for Markdown files, extracts first-level headings, and writes an llms.txt index; logic looks correct.
script/docs-serve	Local dev server script; correctly supports both live-reload (YARD server) and static modes.
Gemfile	Adds a docs group with yard, yard-markdown, and webrick; properly isolated so they are not installed in non-docs environments.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub (tag push / dispatch)
    participant Build as build job
    participant SA as actions/configure-pages
    participant UA as actions/upload-artifact
    participant Deploy as deploy job
    participant DP as actions/deploy-pages
    participant Pages as GitHub Pages

    GH->>Build: trigger workflow
    Build->>Build: checkout + setup-ruby
    Build->>Build: ./script/docs (yard HTML + MD + llms.txt)
    Build->>SA: configure-pages
    Build->>Build: tar docs/_site to artifact.tar
    Build->>UA: "upload artifact (name=github-pages)"
    UA-->>Build: artifact stored
    Build-->>Deploy: needs: build complete
    Deploy->>DP: deploy-pages (needs pages:write + id-token:write)
    DP->>Pages: publish site
    Pages-->>Deploy: page_url

Loading

_{Reviews (3): Last reviewed commit: "style(lint): use double quotes inside in..." | Re-trigger Greptile}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[greptile-apps]

The deploy job is missing the pages: write and id-token: write permissions that actions/deploy-pages requires. Without id-token: write the OIDC token is never issued, so the action cannot authenticate with the GitHub Pages deployment API and the job will always fail at the deploy step.

Suggested change

	deploy:
	needs: build
	environment:
	name: github-pages
	url: ${{ steps.deployment.outputs.page_url }}
	runs-on: ubuntu-latest
	steps:
	deploy:
	needs: build
	environment:
	name: github-pages
	url: ${{ steps.deployment.outputs.page_url }}
	runs-on: ubuntu-latest
	permissions:
	pages: write
	id-token: write
	steps: