diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-07 14:51:02 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-07 14:51:02 +0000 |
| commit | bd14783d3f32abecf8d50bfd352e3695363ea5e2 (patch) | |
| tree | aeab9cb505ee336f149ba9ed2ec1480eba2f83a4 | |
| parent | ac20f209da4740ae8a79b7a1482c540fc4846fa2 (diff) | |
| download | genenetwork4-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.md | 41 |
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 |
