about summary refs log tree commit diff
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 14:51:02 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 14:51:02 +0000
commitbd14783d3f32abecf8d50bfd352e3695363ea5e2 (patch)
treeaeab9cb505ee336f149ba9ed2ec1480eba2f83a4
parentac20f209da4740ae8a79b7a1482c540fc4846fa2 (diff)
downloadgenenetwork4-bd14783d3f32abecf8d50bfd352e3695363ea5e2.tar.gz
docs/www: point the assistant at the repository, not the forge UI
The instruction page is now also the way to get the rest of the docs:
clone the repo and read docs/. Measured, so the numbers are real -- a
--depth 1 --sparse clone of docs is ~2.5 MB in a couple of seconds; the
plain --depth 1 clone is 17 MB, almost all of it source tree the reader
does not need.

Why clone rather than fetch: the forge's tree pages sit behind Anubis (a
browser proof-of-work challenge) and its raw endpoint answers 403, so a
plain HTTPS fetch of a Markdown file returns an HTML challenge page. The
git smart-HTTP endpoints pass, so clone works -- which is what makes
this instruction usable at all.

Also says how to tell whether the docs match the running build
(`git log -1 --format=%h` against the `git` field of /gn4/version).

* docs/www/ai-instruction.md: "Get this document, and the rest of the
docs, by cloning", ahead of the numbered sections.
-rw-r--r--docs/www/ai-instruction.md41
1 files changed, 40 insertions, 1 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md
index 2e3a59d..6b5a418 100644
--- a/docs/www/ai-instruction.md
+++ b/docs/www/ai-instruction.md
@@ -11,7 +11,46 @@ so `/gn4/species` below means `https://vesuvio.pu.ac.ke/gn4/species`.
 `/gn4/` is a 404 from the front end, not from the API.
 
 Machine-readable description of every endpoint: `GET /gn4/openapi.json`.
-Endpoint-by-endpoint prose: [`../../README.md`](../../README.md).
+Endpoint-by-endpoint prose: the repository's `README.md`.
+
+## Get this document, and the rest of the docs, by cloning
+
+The documentation lives in the public repository, which is small and
+worth cloning before you start — it is the authoritative version, and
+this copy may lag behind it:
+
+```sh
+git clone --depth 1 --sparse https://git.genenetwork.org/genenetwork4
+cd genenetwork4 && git sparse-checkout set docs
+ls docs docs/www
+```
+
+That is about 2.5 MB and a couple of seconds (the repository's pack is
+under 2 MB; `--sparse` just avoids writing the 17 MB source tree you do
+not need). Drop `--sparse`/`sparse-checkout` if you want the whole tree.
+Then read:
+
+| file | what it is |
+|---|---|
+| `docs/www/ai-instruction.md` | this page |
+| `docs/search-engines.md` | how `/search` works, engines, quirks |
+| `docs/nginx.md` | how the deployment is proxied (operator-level) |
+| `README.md` | every endpoint, parameter and response shape |
+| `docs/www/operator-checklist.md` | for whoever runs the deployment, not for you |
+
+**Clone; do not fetch the web UI.** `https://git.genenetwork.org/…/tree/…`
+pages sit behind a browser proof-of-work challenge (Anubis), and the
+forge's raw endpoint answers `403`, so a plain HTTP fetch of a file
+returns an HTML challenge page rather than Markdown. The git protocol
+itself passes, which is why `git clone` works. If a fetch does come back
+as HTML mentioning Anubis, stop — do not retry, and use the copy of this
+document you were given.
+
+To check you and the server are looking at the same revision, compare
+the clone's `git -C genenetwork4 log -1 --format=%h` with the `git` field of
+`GET /gn4/version`; they need not match exactly (docs can be newer than
+the running build), but a large gap means the API may not have what the
+docs describe.
 
 ```
 1. You are given a token     → by the GeneNetwork team, out of band