diff options
Diffstat (limited to 'docs')
| -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 |
