# Deploy — GitHub Pages

The public static site (see [docs/site.md](site.md)) is published to **GitHub Pages**
by the [`.github/workflows/pages.yml`](../.github/workflows/pages.yml) workflow.

> **Want a public URL without enabling GitHub Pages?** The **Cloudflare Pages** path
> ([deploy-cloudflare.md](deploy-cloudflare.md)) serves the same built site at a
> `*.pages.dev` URL independently of GitHub Pages enablement. The two paths are not
> exclusive — either, both, or neither can be live.

## Pages URL

Once Pages is enabled (see the gate below), the site serves at:

> **https://mickywin22.github.io/azimuth/**

(GitHub project-site URL for `mickywin22/azimuth`. If the repo is later served from a
custom domain, this URL changes accordingly.)

## How it works

On every push to `main` (and on manual `workflow_dispatch`), the workflow:

1. checks out the repo,
2. installs Python 3.12 + the `site` extra (`uv pip install --system -e ".[site]"` —
   the `markdown` renderer; the rest of the build is pure-stdlib),
3. builds the site with `python scripts/build_site.py --out _site` (this also renders
   the cross-channel knowledge graph, `graph.json` + `graph.html`),
4. uploads `_site` as a Pages artifact (`actions/upload-pages-artifact@v3`),
5. publishes it (`actions/deploy-pages@v4`) to the `github-pages` environment.

The build output (`_site/`, like `site/`) is gitignored — it is regenerated by the
workflow on every run, never committed.

## READY-TO-FLIP gate (Michael's manual step)

**The site is not live until Michael explicitly enables GitHub Pages.** The repo itself is
public (flipped 2026-07-20), but that only makes Pages *possible* — it does not turn Pages
on. Publishing still waits on the one manual enablement step below.

**Skip-not-fail (no red X while Pages is off).** The workflow's `preflight` job probes the
Pages REST API and emits an `enabled` verdict; the `build` and `deploy` jobs run only when
`enabled == 'true'`. While Pages is disabled the whole workflow **skips green** — it never
red-fails, so pushing to `main` (and every daily-ingest commit) no longer floods a red X.
Once Pages is enabled the next push auto-deploys with no further change.

> This gate keys on Pages **enablement**, not repo **visibility**. The earlier
> `if: !repository.private` gate went stale the moment the repo flipped public — it then
> ran build+deploy and 404'd because Pages was still off. Enablement is the real blocker.

To flip the site live (Michael only, when ready):

1. **Settings → Pages → Build and deployment → Source: `GitHub Actions`.**
2. Re-run the `Deploy site to GitHub Pages` workflow (Actions tab → that workflow →
   *Run workflow*), or push any commit to `main`.
3. The site appears at the Pages URL above; the live URL is also shown on the workflow
   run's `deploy` job summary.

To take it back offline: Settings → Pages → set Source to *None* (or disable Pages).

## Repository metadata (the About box)

The GitHub **About** box (description · website · topics) is the very first thing a
visitor reads — before the README. It is repo *settings*, not repo *content*, so it is
versioned here as the single source of truth and applied with `gh`:

```bash
gh repo edit mickywin22/azimuth \
  --description "Public demonstrator of the HemySphere L1/L2/L3 vault doctrine — daily L1 ingest of WorldMonitor open-intelligence data, weekly AI-synthesised L2 briefs, and a queryable cross-channel knowledge graph, published as a read-only static site." \
  --homepage "https://mickywin22.github.io/azimuth/" \
  --add-topic python --add-topic knowledge-graph --add-topic knowledge-management \
  --add-topic second-brain --add-topic digital-garden --add-topic open-data \
  --add-topic osint --add-topic static-site --add-topic github-pages
```

If the description or topics change, edit **this block first**, then re-run it —
never hand-edit the About box alone, or the repo and its docs drift apart.
(The homepage URL goes live only after the Pages flip above; setting it early is
harmless — GitHub renders it as a plain link.)

## Validate the workflow locally

```bash
# YAML / schema sanity (no network, no deploy)
python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/pages.yml')); print('pages.yml: valid YAML')"

# Reproduce the exact build the workflow runs
python scripts/build_site.py --out _site
```

For full GitHub Actions schema linting, run [`actionlint`](https://github.com/rhysd/actionlint)
if installed (`actionlint .github/workflows/pages.yml`).
