docs: overhaul consumer and maintainer documentation

[divyarajmasani]

What this PR does

Overhauls the framework documentation so implementors can integrate the library from a complete example and maintainers have an explicit development workflow. It also audits the existing reference material against the shipped implementation, correcting stale behavior and filling the highest-impact API, installation, upgrade, and troubleshooting gaps.

Closes

Closes #92

Changes

• Add a complete getting-started guide covering installation, plugin/theme bootstrap, modules, registration, and intentionally shared services.
• Add maintainer, upgrading, and troubleshooting guides, and connect them through the README and documentation index.
• Correct the Composer installation path for a package that is not published on public Packagist.
• Correct Singleton, Loader, AbstractRESTController, and AbstractSettingsPage behavior to match the implementation.
• Document PHP, WordPress, and optional OpenSSL requirements and clarify the zero-Composer-runtime-dependency guarantee.
• Expand reference coverage for WP-CLI, asset helpers, loader hooks, Cache/SWR, FeatureSelector, Timer, Logger, and Transients.
• Replace the misleading host-side composer check workflow with the actual PHPCS, PHPStan, and wp-env test commands.
• Update contributor, AI-review, class-inventory, and changelog documentation.

How I verified

$ git diff --check
# no output

$ # Validate every repository-local Markdown link target.
Local Markdown links: OK

$ # Compare the documented class inventory with inc/.
# no undocumented shipped class, interface, or trait reported

The branch changes documentation and instruction files only; no inc/ runtime file is modified.

Acceptance criteria

Runtime behavior

• No runtime behavior changes.
• Documented examples and behavior were checked against the implementation and tests.

Code quality

• Diff whitespace validation passes.
• Repository-local Markdown links resolve.
• Shipped class/interface/trait inventory is represented in the documentation.
• PHP lint, static analysis, and PHPUnit were not rerun because this is a documentation-only change.

Housekeeping

• CHANGELOG.md entry added under ## [Unreleased].

Reviewer notes

• The versioning guide keeps inc/Contracts/ as the explicitly documented contract surface while treating removal of a public class or method as a major consumer impact.
• Branching, release publication, security policy, and automated documentation-drift enforcement are not invented here; the maintainer guide calls out that a complete authoritative release procedure is not currently defined.
• The quickstart is framework-generic and does not assume an unpublished skeleton-specific file layout.

AI assistance

I gathered the initial requirements and defined the documentation direction. AI was used to audit the repository against those requirements, expand the identified topics, and assist with drafting and refining the documentation.

Screenshots / terminal output

Not applicable; documentation-only change.

[divyarajmasani]

The test command, may need some confirmation and consolidation. If we are planning to only support the wp-env lead test setup we can just update the composer script to run this npm script.

[divyarajmasani]

Clear dependencies, we may want to amend these, but need to keep at the top.

[divyarajmasani]

Documentation

URL: https://opensource.rtcamp.com/wp-framework/

Summary

Adds a Docusaurus documentation site and a GitHub Actions workflow to build and deploy it to GitHub Pages.

Markdown stays in docs/ alongside the framework source. Docusaurus configuration, styles, tests, and locked Node dependencies live on the separate docs-config branch. This keeps website tooling and generated files out of the framework branch.

The implementation is self-contained and does not depend on the shared workflow being developed in wp-tooling.

Build and deployment

The publishing workflow:

1. Checks out the documentation source into source/.
2. Checks out the latest docs-config into site/.
3. Sets up Node.js 22 and installs dependencies using npm ci.
4. Reads the site URL and base path from GitHub Pages.
5. Runs configuration tests and builds the documentation.
6. Uploads site/build/ as a Pages artifact with seven-day retention.
7. Deploys eligible builds through the github-pages environment.

GitHub Pages serves the generated HTML, CSS, and JavaScript. No application server is required, and generated files are not committed to Git. The earlier documentation output branch is unused.

Workflow triggers

Event	Result
Documentation or workflow changes pushed to gh/92-documentation	Builds and deploys to the existing Pages site
Documentation or workflow changes in a PR targeting main	Builds and uploads an artifact without deploying
Manual publishing-workflow run	Builds; deploys only from an allowed branch
Push or PR targeting docs-config	Validates the configuration against documentation from main and uploads a preview artifact
Successful config-push validation, once the publishing workflow exists on the default branch	Rebuilds documentation from main and deploys using the latest configuration

Failed configuration runs and configuration PRs do not trigger production deployment. Production runs share a concurrency group to cancel superseded runs; PR validation runs are separate.

Documentation behavior

• Sidebar navigation is generated automatically, with ordering and labels controlled by Markdown front matter.
• Documentation links remain internal site links.
• Relative links to framework source files are converted into GitHub links for the selected source ref.
• Broken documentation links, broken anchors, and missing linked source files fail the build.
• noIndex: true adds robots metadata asking compliant search engines not to index the site. The site remains publicly accessible.

Site URL and asset paths

Docusaurus derives its url and baseUrl from the GitHub Pages configuration. For deployment under /wp-framework/, generated asset paths must also start with /wp-framework/.

After changing the Pages domain or path, re-run all jobs on the publishing workflow to rebuild with the updated configuration. An empty commit will not trigger the workflow because its push trigger filters for changes to docs/** or the workflow file.

Local development

Requires Node.js 22+. Create a separate configuration checkout beside the framework checkout:

git clone --single-branch --branch docs-config \
  https://github.com/rtCamp/wp-framework.git \
  ../wp-framework-docs-config

From the framework checkout:

export DOCS_SOURCE="$PWD"
export DOCS_SOURCE_REF="gh/92-documentation"

cd ../wp-framework-docs-config
npm ci
npm test
npm start -- --host 127.0.0.1 --no-open

Open http://127.0.0.1:3000/wp-framework/. Changes to Markdown in the framework checkout are watched directly.

To build and preview production output:

npm run build
npm run serve -- --host 127.0.0.1 --no-open

Use an HTTP server to preview downloaded artifacts; opening index.html directly will not resolve absolute asset paths correctly.

Permissions and dependencies

• Builds require read access to repository contents and Pages configuration.
• The deployment job uses pages: write and id-token: write.
• Deployment uses the built-in GITHUB_TOKEN; no custom token or branch-write permission is required.
• Actions are pinned to full commit SHAs.
• Pages actions use Node.js 24-compatible releases; the Docusaurus build runs on Node.js 22.

Before merging

The deployment branch is temporarily configured for testing.

• Change push.branches from gh/92-documentation to main.
• Remove gh/92-documentation from the deployment job’s allowed refs.
• Remove the temporary branch allowance from the github-pages environment.
• Keep docs-config as a separate branch; do not merge it into main.

Deployments from the temporary branch update the existing live Pages site, not a separate preview URL.

Validation

• All four configuration tests passed.
• Updated documentation built successfully.
• Workflow lint and whitespace checks passed.
• GitHub configuration validation and Pages deployment succeeded after upgrading the actions.
• Updated workflow runs completed without Node.js 20 deprecation warnings.
• Local build verified noindex metadata in all 12 generated HTML pages.

[divyarajmasani]

The need for a separate branch to keep the Docusaurus configs away from the main repository. This is an implementation of a concept, the Docusaurus config and the site build can be moved out to a shared GitHub workflow. And then we can use the same workflow for all repositories where we need the similar documentation.

Shared workflow, config would allow us to set the same design / feature parity for the documentation.

Cc: @aryanjasala