Build and serve this site

The documentation is a static VitePress site. Its pages are Markdown in docs/; navigation and theme settings live in docs/.vitepress/. Local search is built from the pages and does not require a search service.

Local development

From the repository root:

npm ci --ignore-scripts
npm run docs:dev

Open the URL printed by VitePress. Changes to Markdown appear as you edit.

Build and preview

npm run docs:build
npm run docs:preview

The output is docs/.vitepress/dist/. Serve that directory with any static HTTP server. For a site hosted under a subdirectory, set the base path at build time:

DOCS_BASE=/fah-sdk/ npm run docs:build
DOCS_BASE=/fah-sdk/ npm run docs:preview

Open the printed URL under /fah-sdk/. The path must begin and end with /. CI builds this subdirectory configuration and archives the static output as fah-sdk-docs. The container build below uses / for a dedicated hostname.

Build and test the serving image

With Docker running, build the same Linux image used by the publisher:

docker buildx build --platform linux/amd64 --provenance=false --load \
  -f Dockerfile.docs --build-arg SOURCE_COMMIT="$(git rev-parse HEAD)" \
  -t fah-sdk-docs:local .
node scripts/test-docs-image.mjs fah-sdk-docs:local

The test starts and removes a local container. It checks every documentation page, referenced assets, cache headers, health, missing paths and the restricted runtime. The image serves HTTP on port 8080, reports 200 ok at /healthz, and runs as UID/GID 101:101. It accepts a read-only root filesystem with a writable /tmp of 32 MiB. It needs no database, migration command, secrets, persistent storage or Google identity. HTML uses Cache-Control: no-cache; fingerprinted assets use immutable caching. The image contains built pages and Nginx; Node and the build workspace stay in the build stage.

Publish a staging image and request a version bump

Publish docs image builds and smoke-tests the image on pull requests and main pushes. Publishing is opt-in through the repository variable DOCS_PUBLISH_ENABLED=true. When enabled, only a main push can publish; the staging-images environment should allow only the protected main branch. The publisher pushes the exact tested image to us-west1-docker.pkg.dev/portal-interactive/fah-staging/sdk-docs, then records its immutable registry digest and source commit in the run's staging-images-sdk-docs-<attempt> artifact. It omits migrationImage because the image is stateless.

After that workflow succeeds, Notify platform of docs image sends the run ID and attempt to projportal/fah-platform. Platform verifies the completed run and artifact before opening or updating a staging manifest PR. The first verified publication fills the reviewed docs registration; subsequent publications change only the source commit and image digest. The target hostname is docs.fah.portal-interactive.com, initially assigned to staging. Neither workflow merges the PR, runs Pulumi update, deploys containers or modifies DNS.

Configure these values before enabling publication:

Name	Type	Purpose
GCP_DOCS_WIF_PROVIDER	Actions variable	Full Workload Identity Federation provider name
GCP_DOCS_PUBLISH_SERVICE_ACCOUNT	Actions variable	Dedicated image publisher service account email
GCP_RELEASE_WIF_PROVIDER	Actions variable	SDK notification WIF provider (separate from publisher)
GCP_RELEASE_SERVICE_ACCOUNT	Actions variable	SDK notification service account, with access to the App key secret
FAH_RELEASE_APP_ID	Actions variable	Platform release GitHub App ID
FAH_RELEASE_APP_KEY_VERSION	Actions variable	portal-interactive/fah-release-app-private-key/<numeric-version>
DOCS_PUBLISH_ENABLED	Actions variable	Set to true after registry, federation and platform receiver are ready

Use a short-lived federated token. Grant the publisher roles/artifactregistry.writer only on the existing fah-staging repository and roles/iam.workloadIdentityUser only to the trusted SDK publisher identity. The federation condition must restrict repository/owner IDs, main ref, staging-images environment and this publisher workflow. No GCP JSON key or GKE deployment permission is needed. The registry and identity are prerequisites; these workflows do not create them. The App needs installation access to this SDK repo for platform's run/artifact reads, and platform Contents write for dispatch.

The notification job uses the staging-notify environment, restricted to main. Its dedicated WIF identity is bound to this repository's numeric ID and the exact notify-docs-image.yml workflow with workflow_run; the publisher cannot read the App key. The notifier fetches the pinned PEM version from Secret Manager and passes the masked result to the App token action. Do not store the PEM in GitHub secrets, Pulumi config or Git. Platform's Python bootstrap/CI programs define these GCP resources; GitHub App registration, installation and variables wait for admin setup. Keep DOCS_PUBLISH_ENABLED at repository scope so both build and publish jobs see it. Other variables can be scoped to staging-images or staging-notify as appropriate.

See platform's docs release setup for App installation permissions, preview credentials, namespace, HTTPS and DNS prerequisites, and its autobump contract for the authoritative event and descriptor schemas. Merge the platform receiver to its default branch before enabling the publisher. To retry notification after fixing setup, rerun the notification job for the original successful publication. Rebuilding the same commit with a different digest requires manual review; a new source commit is a new version. If publishing failed before a descriptor was uploaded, rerun all jobs in the publisher: image artifacts are scoped to the run attempt and retained for one day. Rerunning only the failed publish job cannot reuse an image from a different attempt.

Check content before publishing

The build rejects broken internal page links. Run the browser checks after installing Chromium:

npx playwright install chromium
npm run test:docs

They exercise page loading, local search and mobile navigation on the built site, including its configured base path. For a subdirectory build, run DOCS_BASE=/fah-sdk/ npm run test:docs.

Write pages around a developer task: prerequisites, a complete example, the expected result and relevant limits. Use accurate public API names. Explain behavior and constraints without requiring access to internal discussions. Keep source attribution and license notices with their designated records.

Reference ownership

Each topic has one definition page. Tutorials demonstrate those definitions and link back to them. The site is generated directly from the Markdown pages; update the owning page when a requirement changes.

Topic	Definition page
State transitions and resource ownership	Game lifecycle
Input schemes, sampling and coordinates	Input
HUD formatting and visual effects	HUD and visual feedback
Game audio APIs, patterns and decoded loops	Audio
Graphics APIs, camera fitting, pixel budgets and GPU cleanup	Graphics
Environment, layout and gameplay constraints	Game requirements
Transport, commands and message payloads	Host protocol
Manifest fields, media and generated metadata	Game manifest
Inspection and capture controls	Test hook