# Pharos documentation site From the repository root: ```sh 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](../devops/ansible/roles/edge/tasks/documentation.yml) 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: ```sh 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](../dx/common/GUIDE.md). 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: ```sh 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: ```sh 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](content/public/brand/README.md) record the Pharos visual reference and bundled font licence.