feat: start the docs site

.editorconfig

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 The Gatepost authors
+# SPDX-License-Identifier: Apache-2.0
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 100
+
+[*.php]
+indent_size = 4

.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: 2026 The Gatepost authors
+# SPDX-License-Identifier: Apache-2.0
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # The js submodule holds its own spec submodule.
+          submodules: recursive
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          # The oldest Python that the scripts in the spec repo support.
+          python-version: '3.11'
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          # pnpm check starts reuse and zizmor with uvx. No lock file keys a cache.
+          enable-cache: false
+      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          # The newest PHP. The PHP package supports 8.1 and later, and its own CI tests 8.1.
+          php-version: '8.4'
+          tools: composer
+          coverage: none
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm sdk
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm check
+      - if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          # The built site, so a reviewer can open the pages of a pull request.
+          name: site
+          path: dist
+          retention-days: 7
+
+  commits:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    env:
+      BASE: ${{ github.event.pull_request.base.sha }}
+      HEAD: ${{ github.event.pull_request.head.sha }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # The checks read each commit from the base to the head.
+          fetch-depth: 0
+          submodules: true
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec commitlint --from "$BASE" --to "$HEAD"
+      - name: Check each commit message for agent tells
+        run: |
+          for sha in $(git rev-list "$BASE..$HEAD"); do
+            git log -1 --format=%B "$sha" > "$RUNNER_TEMP/message"
+            python3 spec/scripts/check-tells --commit-msg "$RUNNER_TEMP/message"
+          done
+
+  secrets:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # gitleaks must read the whole history.
+          fetch-depth: 0
+          persist-credentials: false
+      - run: |
+          image=ghcr.io/gitleaks/gitleaks # v8.30.1
+          digest=sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f
+          docker run --rm -v "$PWD:/repo" "$image@$digest" git /repo

.github/workflows/links.yml

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 The Gatepost authors
+# SPDX-License-Identifier: Apache-2.0
+name: links
+
+# The links to other sites change without a commit here, so a weekly job checks them. A pull
+# request checks only the links inside the site, which need no network.
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  external:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: recursive
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          php-version: '8.4'
+          tools: composer
+          coverage: none
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm sdk
+      - run: pnpm build
+      - run: pnpm links:external

.github/workflows/pages.yml

@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 The Gatepost authors
+# SPDX-License-Identifier: Apache-2.0
+name: pages
+
+# Each push to main publishes the site on GitHub Pages. The ci workflow checks the same commit.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: recursive
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          # The newest PHP. The PHP package supports 8.1 and later, and its own CI tests 8.1.
+          php-version: '8.4'
+          tools: composer
+          coverage: none
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm sdk
+      - run: pnpm build
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    # A manual run may start from any branch. Only main may publish.
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.github/workflows/pull-request.yml

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2026 The Gatepost authors
+# SPDX-License-Identifier: Apache-2.0
+name: pull request
+
+# A squash merge puts the title and the body of the pull request on main as the commit message.
+# An edit of the title or the body does not push a commit, so it must start this job again.
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pull-request-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  squash-message:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: true
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      # The title and the body come through env, so that no text of the pull request ends up
+      # inside the script.
+      - name: Check the message that the squash merge puts on main
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+          NUMBER: ${{ github.event.pull_request.number }}
+          BODY: ${{ github.event.pull_request.body }}
+        run: |
+          printf '%s (#%s)\n\n%s\n' "$TITLE" "$NUMBER" "$BODY" > "$RUNNER_TEMP/message"
+          python3 spec/scripts/check-tells --squash-msg "$RUNNER_TEMP/message" --no-scope
+          pnpm exec commitlint --edit "$RUNNER_TEMP/message"

.gitignore

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2026 The Gatepost authors
+# SPDX-License-Identifier: Apache-2.0
+node_modules/
+dist/
+temp/
+coverage/
+.astro/
+test-results/
+playwright-report/
+# What the build writes from the spec, the doc comments and the mock gateway.
+src/content/docs/spec/
+src/content/docs/reference/
+src/generated/

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "spec"]
+	path = spec
+	url = https://github.com/gatepost-dev/spec
+[submodule "js"]
+	path = js
+	url = https://github.com/gatepost-dev/js
+[submodule "php"]
+	path = php
+	url = https://github.com/gatepost-dev/php

.prettierignore

@@ -0,0 +1,10 @@
+pnpm-lock.yaml
+spec
+js
+php
+dist
+temp
+coverage
+.astro
+src/content/docs/spec
+src/content/docs/reference

.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "printWidth": 100,
+  "plugins": ["prettier-plugin-astro"]
+}

AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+This repo is part of Gatepost, unofficial open-source developer tools for Nigeria's National Digital Postcode. This repo holds the docs site: the guides, the API reference, the spec pages and the playground. It reads the SDKs and the spec from the submodules `js`, `php` and `spec`.
+
+## Read first
+
+- `CODING_STANDARDS.md` and the two files it names hold the rules. Cite rule IDs, such as `API-3`, in reviews and commit bodies.
+- `CONTEXT.md` is the glossary. Name things with its terms in code, tests, docs and commits.
+- `spec/` holds the grammar, with its Interface section, and the vectors. The spec wins over code and over these docs.
+
+## Rules that no config file shows
+
+- If the task needs a public symbol that the Interface section of `spec/grammar.md` does not list, add nothing, not even an internal helper. Stop, and say that a spec change must come first (API-1, CS-8).
+- Call only the documented NIPOST gateway endpoints.
+- Commit only NIPOST's published test codes and synthetic values, such as `FC-01-Z99-ZZ-01`.
+- Sign off each commit with `git commit -s`. The person who opens the pull request is the only author. Leave out co-author lines for AI tools.
+- Change `main` only through pull requests. Keep the history of `main` and of other people's branches as it is: never force-push to them.
+- If a commit lacks its sign-off, run `git rebase --signoff` with the base branch. Then push to your own branch with `--force-with-lease`.
+- Send every call to the gateway through the client. The client limits how many calls run at once.
+- Write prose in plain British English, with short sentences in the active voice.
+- Some agent tools change a typed backslash-u escape, such as the one for an en dash, into the character itself. Build such characters with code, for example `chr(0x2013)` in Python or `String.fromCodePoint(0x2013)` in TypeScript. In data and prose, write `U+2013`.
+- Load nothing from another website: no fonts, scripts, styles, images or analytics. The site tests fail on each one.
+
+## Done means all of these
+
+1. A failing test came first, and it passes now.
+2. `pnpm check` passes. It runs the formatter, linters, tests, every code example, the accessibility checks, `check-tells`, REUSE and zizmor.
+3. Each code example on a hand-written page runs in CI and shows the result that it gets.
+4. A page that describes the public interface matches the spec and the SDK version in the submodules.
+5. Each new domain term is in `CONTEXT.md`.
+6. The diff touches only the lines that the task needs.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CODING_STANDARDS.md

@@ -0,0 +1,8 @@
+# Coding standards
+
+This repo follows two files. Both are part of its standard:
+
+1. `spec/standards/CODING_STANDARDS.md` holds the rules for every Gatepost repo.
+2. `spec/standards/languages/typescript.md` holds the rules for TypeScript.
+
+Rules for this repo only: the site is not a package, so it has no change files, no changelog and no API report. Its commits use no scope, as in the spec repo (GIT-1).