docs(repo): give the READMEs a header block and shorter guides

.changeset/shorter-readmes.md

@@ -0,0 +1,6 @@
+---
+'@gatepost/core': patch
+'@gatepost/client': patch
+---
+
+The README of each package is shorter and links the docs site for the full guide and the reference.

README.md

@@ -1,50 +1,58 @@
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup-dark.svg">
-  <img src="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup.svg" alt="gatepost" height="48">
-</picture>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup-dark.svg">
+    <img src="https://raw.githubusercontent.com/gatepost-dev/.github/main/brand/gatepost-lockup.svg" alt="Gatepost" width="240">
+  </picture>
+</p>
+
+<h1 align="center">Gatepost for TypeScript</h1>
+
+<p align="center">TypeScript packages for Nigeria's National Digital Postcode.</p>
+
+<p align="center">
+  <a href="https://github.com/gatepost-dev/js/actions/workflows/ci.yml"><img src="https://github.com/gatepost-dev/js/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="https://github.com/gatepost-dev/js/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-Apache--2.0-blue?style=flat" alt="Licence: Apache-2.0"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/gatepost-dev/js"><img src="https://api.scorecard.dev/projects/github.com/gatepost-dev/js/badge" alt="OpenSSF Scorecard"></a>
+</p>
+
+<p align="center">
+  <a href="https://gatepost-dev.github.io/docs/">Docs</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://gatepost-dev.github.io/docs/playground/">Playground</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://gatepost-dev.github.io/docs/guides/typescript/">TypeScript guide</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md">Contributing</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://github.com/gatepost-dev/js/discussions">Discussions</a>
+</p>
 
-# Gatepost for TypeScript
+> Unofficial. Not made or endorsed by NIPOST.
 
-TypeScript packages for Nigeria's National Digital Postcode.
+## Packages
 
-> Unofficial. Not made or endorsed by NIPOST.
+| Package                                         | What it is                                      | Status                     |
+| ----------------------------------------------- | ----------------------------------------------- | -------------------------- |
+| [`@gatepost/core`](packages/core)               | Parse, check and format postcodes offline.      | Alpha, not on npm yet      |
+| [`@gatepost/client`](packages/client)           | Call NIPOST's gateway, with retries and limits. | Alpha, not on npm yet      |
+| [`@gatepost/mock-server`](packages/mock-server) | Mock NIPOST's gateway for client tests.         | Private, never goes to npm |
+
+## Example
+
+```ts
+import { parse } from '@gatepost/core';
+
+const parsed = parse('ek 01 a03 fk 01');
+if (parsed.ok) {
+  parsed.value.canonical; // 'EK-01-A03-FK-01'
+}
+```
 
-| Package                                         | What it does                                        |
-| ----------------------------------------------- | --------------------------------------------------- |
-| [`@gatepost/core`](packages/core)               | Parse, check and format postcodes offline.          |
-| [`@gatepost/client`](packages/client)           | Call NIPOST's gateway, with retries and limits.     |
-| [`@gatepost/mock-server`](packages/mock-server) | Mock NIPOST's gateway for client tests. Not on npm. |
+The [TypeScript guide](https://gatepost-dev.github.io/docs/guides/typescript/) and the [client guide](https://gatepost-dev.github.io/docs/guides/typescript-client/) show every function. The [reference](https://gatepost-dev.github.io/docs/reference/js/core/) lists every export.
 
 ## Develop
 
-You need Node 24, `corepack enable`, Python 3.11 or later and `uv`.
-
-    git clone --recurse-submodules https://github.com/gatepost-dev/js
-    pnpm install
-    pnpm check
-
-`pnpm check` also builds the packages. Then it runs publint, attw, size-limit and API Extractor on
-the result, and it starts each built package once. It checks the licence of each dependency and of
-each file, and it checks the workflows with zizmor. It starts REUSE and zizmor with `uvx` at pinned
-versions. REUSE needs an encoding detector, and `uvx` installs REUSE without one, so the script pins
-`charset-normalizer` as well. Renovate updates the three pins. After a change to the public API of a
-package, run `pnpm --filter <package> run api:update` and commit its `etc/<name>.api.md`. For each
-change to a package, add a change file with `pnpm changeset`, or with `pnpm changeset --empty` when
-the change needs no release. The pull request job fails without a change file.
-
-A squash merge writes the commit message from the title and the body of the pull request. The same
-job lints that message. Write the title as a Conventional Commits header with a scope, and end the
-body with your `Signed-off-by` line. A line of the body has at most 100 characters, and a web form
-does not wrap lines, so break them yourself. The title and the suffix `(#N)` that GitHub adds have
-at most 72 characters together.
-
-The mutation run (`pnpm --filter @gatepost/core run mutation`) uses Stryker's command runner in
-place, because the Stryker Vitest runner does not match Vitest 5 test names. After a run that
-stops hard, run `git checkout packages/core && rm -rf packages/core/.stryker-tmp`, which also
-discards your uncommitted changes in that folder.
-
-Read [`CONTRIBUTING.md`](https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md) and
-`CODING_STANDARDS.md` before you open a pull request.
+Read [`docs/develop.md`](docs/develop.md) for the set-up, the checks and the rules for a pull request. Then read the [contributing guide](https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md).
 
 ## Licence
 

docs/develop.md

@@ -0,0 +1,34 @@
+# Develop Gatepost for TypeScript
+
+This page holds the steps for a maintainer of the repo. The [contributing guide](https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md) of the organisation holds the rules for every Gatepost repo.
+
+## Set up and check
+
+You need Node 24, `corepack enable`, Python 3.11 or later and `uv`.
+
+    git clone --recurse-submodules https://github.com/gatepost-dev/js
+    pnpm install
+    pnpm check
+
+`pnpm check` also builds the packages. Then it runs publint, attw, size-limit and API Extractor on
+the result, and it starts each built package once. It checks the licence of each dependency and of
+each file, and it checks the workflows with zizmor. It starts REUSE and zizmor with `uvx` at pinned
+versions. REUSE needs an encoding detector, and `uvx` installs REUSE without one, so the script pins
+`charset-normalizer` as well. Renovate updates the three pins. After a change to the public API of a
+package, run `pnpm --filter <package> run api:update` and commit its `etc/<name>.api.md`. For each
+change to a package, add a change file with `pnpm changeset`, or with `pnpm changeset --empty` when
+the change needs no release. The pull request job fails without a change file.
+
+A squash merge writes the commit message from the title and the body of the pull request. The same
+job lints that message. Write the title as a Conventional Commits header with a scope, and end the
+body with your `Signed-off-by` line. A line of the body has at most 100 characters, and a web form
+does not wrap lines, so break them yourself. The title and the suffix `(#N)` that GitHub adds have
+at most 72 characters together.
+
+The mutation run (`pnpm --filter @gatepost/core run mutation`) uses Stryker's command runner in
+place, because the Stryker Vitest runner does not match Vitest 5 test names. After a run that
+stops hard, run `git checkout packages/core && rm -rf packages/core/.stryker-tmp`, which also
+discards your uncommitted changes in that folder.
+
+Read [`CONTRIBUTING.md`](https://github.com/gatepost-dev/.github/blob/main/CONTRIBUTING.md) and
+`CODING_STANDARDS.md` before you open a pull request.