#Pharos documentation site

From the repository root:

pnpm install --frozen-lockfile
pnpm docs:check
pnpm docs:preview

Preview binds to http://127.0.0.1:3001. pnpm docs:dev prepares sources and starts the development server. After editing a source, run pnpm --filter @pharos/docs prepare:site again, or restart docs:dev, to refresh the generated tree.

#Sources and build

• content/guides/ contains the current Pharos Platform user guides. These own the homepage and primary navigation.
• content/contributing/ groups development, architecture, learning, operations and historical references. Keep these out of the primary user navigation.
• Root policy files, root operational guides, decision/design catalogues, Beto context READMEs, all registered Metallo context READMEs, API guides and contract READMEs are assembled into the site by scripts/prepare.mjs.
• .site/ and doc_build/ are ignored build output. Edit the authoritative source.
• Code examples marked with example comments are extracted from source at build time. A missing symbol fails preparation.
• Every rendered source page links to a bundled source snapshot, including unpublished local changes. /build and /build-info.json record commit, branch, local-change status and UTC build time.
• Retained pages keep their URLs and show compatibility notices. Unresolved historical links are rendered as unavailable references and recorded in /historical-links.json. Unresolved links in new learning and landing pages fail preparation.

The Rspress version and Mermaid plugin are pinned in package.json and the root lockfile. Mermaid renders in the browser with strict security. The former PNG renderer and assets remain tracked for provenance; the active build uses the interactive renderer. The glossary is ordinary Markdown with links to retained terms.

#History and educational attribution

provenance.json is the immutable relocation ledger under ADR 0042. Keep the exact move commit through merge. Do not squash it together with content edits. education-provenance.json records the imported educational sources and hashes; the learning section retains their MIT licence. integration-baseline.json identifies the reviewed integration revision. Directory links and extracted examples use the current build commit. Update the baseline only after reviewing the changed sources.

#Verification and publication

pnpm docs:check type-checks configuration/theme code, builds the site and checks generated navigation, internal links/assets, source metadata and example expansion. pnpm docs:test:browser checks navigation, diagrams, source snapshots and mobile layout. The documentation GitHub Actions workflow builds the same frozen workspace and uploads the static site for review. Use the delivery command below for the local and staging documentation hosts. For a separate subpath deployment, set RSPRESS_BASE_PATH and verify that build. The relocated .gitlab-ci.yml records the retirement of the old Pages pipeline.

Delivery changes also require PYTHONPATH=scripts python3 -m unittest scripts/test_documentation.py and uv run --project devops --frozen python scripts/documentation_edge_smoke.py. Run the latter on the configured dev box or build runner with Docker. It checks real TLS, clean URLs, build identity and denied requests in disposable Nginx containers, without reading the installed platform's certificates.

#Deploy documentation

Documentation is a static artifact served by the existing Nginx edge. Delivery owns /opt/pharos-documentation and the pharos-documentation Nginx files. It leaves application deployments and the edge's application route file in place. The edge task keeps this configuration with its existing owner.

Use a clean commit and the repository's pinned Node/pnpm and devops toolchains. For a dev box, select your own SSH alias:

pnpm docs:deploy --environment devbox --ssh your-dev-box

The result is https://docs.localtest.me. Prepare the dev box and its trusted local HTTPS connection using the dev-box guide. The edge serves the same site on its operator and workload listeners, so the ordinary workstation connection carries it. Delivery signs only a documentation leaf with the box's existing CA and preserves that CA and the application certificates.

For staging, a sudoer checks out the reviewed documentation commit on their administration machine and uses their SSH alias for the staging edge:

pnpm docs:deploy --environment staging --ssh staging-edge --ask-become-pass

Omit --ask-become-pass when the account has passwordless sudo. The password prompt is local to the operator's terminal. An existing private inventory can instead supply the connection settings, with an explicit edge host or group:

pnpm docs:deploy --environment staging --inventory /private/site/hosts.yml --limit platform-edge

Staging serves https://docs.staging.pharosfactory.ai. Its DNS must already reach the selected edge. The edge needs the installed Certbot client, an existing ACME account and the existing renewal scheduler. The documentation task adds its own HTTP-01 route and renewal hook and requests only this hostname's certificate. Private connection and sudo settings stay in the existing inventory.

Each delivery checks the clean build revision, hashes the archive and every extracted file, then switches a versioned release pointer atomically. It verifies /build-info.json through trusted HTTPS. A failed activation restores the previous pointer and documentation configuration. Earlier releases are retained for rollback. --skip-build reuses an already verified clean build at the current commit. For rollback, check out the required earlier documentation commit and run the same command; confirm the served revision afterwards.

The public artifact contains the guides and their source snapshots. Keep private settings, credentials and machine-specific instructions outside those sources. The brand asset notes record the Pharos visual reference and bundled font licence.