# Publishing and the full website

## One source, two reading surfaces

GitHub Markdown is the source of truth. The complete documentation is rendered directly at **proof21.xyz/docs/** by the website build. GitBook can remain an optional editorial/read-only mirror on its free hostname. The website does not proxy a paid GitBook subdirectory feature.

No automatic Git Sync, public website, or domain change is implied by these files. GitBook updates must be synchronized explicitly until the connection is configured.

## Build and inspect

From the repository root, install the pinned website parser and run the generator:

```bash
python3 -m pip install -r requirements-web.txt
python3 scripts/build_site.py
python3 scripts/check_site.py
python3 -m http.server 4173 --bind 127.0.0.1 --directory site
```

The generator reads the navigation allowlist in docs/SUMMARY.md, renders Markdown to static HTML, copies versioned SVG diagrams, and creates search, sitemap, RSS, and machine-documentation outputs. It never copies ops/, credentials, or the repository root into the public site.

The site has no database or paid runtime dependency. No Sites subscription is required. A prebuilt output can be served by an ordinary static host.

## Vercel configuration

The repository-root vercel.json sets the output directory to site and the build command explicitly. Import the repository with the Other framework preset and repository root as the build root. The deployment must serve **only site/**, not the repository root. A full repo build root is needed so the generator can read docs/ and brand/.

Vercel Hobby is not a commercial entitlement. Select an appropriate plan or another static host; no billing change has been authorized here. Preview noindex is not authentication. Use deployment protection for private review. [1]

## Free GitBook

GitBook Free/Basic can publish public documentation on its own hostname and includes Git Sync and machine-readable docs. Custom domains and advanced branding have paid-plan requirements. An unpublished workspace does not require paid visitor authentication merely to keep drafts private. [2]

## Domains and social links

The selected origin is proof21.xyz. Configure project-specific DNS only after a hosting project exists; preserve email and verification records. The .ai domain is planned, not confirmed.

X and LinkedIn destinations are unset until the owner supplies exact URLs. GitHub is still private; preview links say so, and public builds hide a private source link. A GitBook editor link is never used as a public docs destination.

## Sources

1. [Vercel fair use](https://vercel.com/docs/limits/fair-use-guidelines)
2. [GitBook pricing](https://www.gitbook.com/pricing)