about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-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