feat: Add API docs generation and llms.txt index

[gjtorikian]

Summary

• Wire up phpDocumentor to emit HTML and parallel Markdown into docs/_site, so humans and AI agents share the same source paths.
• Add a Publish API Docs GitHub Pages workflow that builds and deploys on v* tags (and on manual dispatch).
• Generate an llms.txt index at the site root (per llmstxt.org) listing Core, Service, and Exception classes, with the 600+ generated Resource DTOs called out separately so they don't drown the list.
• Motivation: the PHP SDK had no published reference unlike its sibling SDKs, and the new docs site needed a curated entry point that LLMs could land on without crawling 700+ files.

Test plan

• ./script/docs runs cleanly locally and produces docs/_site/index.html, parallel .md files, and docs/_site/llms.txt.
• llms.txt lists every class under lib/WorkOS, lib/WorkOS/Service, and lib/WorkOS/Exception with working relative links.
• ./script/docs-serve serves the site for spot-checking.
• Trigger the Publish API Docs workflow via workflow_dispatch and confirm the Pages deploy succeeds.

[greptile-apps]

Greptile Summary

This PR adds API documentation generation for the WorkOS PHP SDK using phpDocumentor, producing both HTML and parallel Markdown output in docs/_site, an llms.txt index for AI agent discoverability, and a GitHub Pages deployment workflow triggered on version tags.

• script/docs orchestrates three passes (HTML, Markdown, llms.txt) and downloads the phpDocumentor PHAR at runtime from an unpinned URL with no integrity check, which is a supply-chain risk given the CI environment has pages: write and id-token: write permissions.
• .github/workflows/docs.yml is missing a composer install step; without it, vendor/saggre/phpdocumentor-markdown won't exist and the build will exit with an error before producing any output.

Confidence Score: 3/5

The deployment workflow will fail on every run due to missing composer setup, and the PHAR download lacks a version pin or integrity check in a job with write access to GitHub Pages.

Two independent defects block the feature from working: the CI job never runs composer install so the Markdown pass always exits with an error, and the phpDocumentor PHAR is fetched from a floating URL with no checksum in a job that holds id-token: write and pages: write scopes. Both need to be addressed before the workflow can safely and reliably deploy docs.

.github/workflows/docs.yml (missing composer step) and script/docs (unpinned, unverified PHAR download) are the two files that need fixes before this is ready to merge.

Security Review

• Unverified remote binary execution (script/docs, line 8): phpDocumentor.phar is downloaded from https://phpdoc.org/phpDocumentor.phar and immediately executed with no pinned version and no SHA-256 or similar integrity check. A compromised CDN response or MITM would result in arbitrary code running inside the CI environment, which has pages: write and id-token: write permissions.

Important Files Changed

Filename	Overview
.github/workflows/docs.yml	New GitHub Pages deployment workflow; missing composer install step causes every CI run to fail at the Markdown documentation pass.
script/docs	Orchestrates HTML + Markdown doc generation and llms.txt; downloads phpDocumentor PHAR from an unpinned URL with no integrity verification, posing a supply-chain risk.
script/docs-serve	Simple local dev-server script; builds docs if not present then serves with PHP's built-in server. No issues found.
phpdoc.dist.xml	Standard phpDocumentor config pointing at lib/, outputting to docs/_site. No issues found.
composer.json	Adds saggre/phpdocumentor-markdown as a dev dependency for the Markdown template pass. No issues found.
.gitignore	Adds ignores for generated doc output, the downloaded PHAR, and phpDocumentor cache. No issues found.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Actions
    participant Build as build job
    participant PD as phpdoc.org
    participant Pages as GitHub Pages

    GH->>Build: "trigger (v* tag / workflow_dispatch)"
    Build->>Build: checkout + setup-php
    Note over Build: composer install missing
    Build->>PD: curl phpDocumentor.phar (unpinned)
    PD-->>Build: latest PHAR (no checksum)
    Build->>Build: Pass 1 HTML output
    Build->>Build: Pass 2 Markdown output (fails if vendor/ absent)
    Build->>Build: Pass 3 generate llms.txt
    Build->>Build: tar docs/_site to artifact.tar
    Build->>Pages: upload-artifact
    Pages-->>GH: deploy-pages

Loading

_{Reviews (1): Last reviewed commit: "feat: Generate llms.txt index in API doc..." | Re-trigger Greptile}

[greptile-apps]

Missing composer install before running docs script

./script/docs checks for vendor/saggre/phpdocumentor-markdown/themes/markdown and immediately exits with an error (exit 1) if it's not found, but the workflow has no composer install step. Every CI run triggered by a tag push or workflow_dispatch will fail at the Markdown pass, producing no deployed site.

[greptile-apps]

Unpinned and unverified PHAR download

The comment says "Pin a recent stable version" but the URL https://phpdoc.org/phpDocumentor.phar always resolves to the latest release — there is no version pinned. More importantly, the downloaded PHAR is executed immediately with no integrity check (no SHA-256 comparison). If phpdoc.org serves a different binary or is compromised between runs, the malicious artifact will be run silently during every CI doc build.