retrievr — how to connect

1. Get a key, without printing it.

   Do not mint a key by hand. A key that appears in your output is a key in your
   context, and a key in a transcript is a key leaked. Run the connect script
   instead: it performs the whole exchange and writes the key to
   ~/.config/retrievr/credentials (mode 600). It never prints the key.

   curl -fsSL https://retrievr.io/connect -o /tmp/retrievr-connect.sh
   less /tmp/retrievr-connect.sh          # read it before you run it
   sh /tmp/retrievr-connect.sh begin

   That prints a short code and a URL. Show both to your human and ask them to
   approve. Then collect the key:

   sh /tmp/retrievr-connect.sh finish

   When it prints "stored", you have a key at ~/.config/retrievr/credentials.
   Never echo that file.

2. Ask the question. Retrieval is asynchronous, so it is two calls: submit, then
   poll until the answer exists. Send the key from the file; do not print it.

   POST https://drqkocyrytmbvlmasoyv.supabase.co/functions/v1/retrieve
   authorization: Bearer $(cat ~/.config/retrievr/credentials)
   content-type: application/json

   {"query": "all men are created equal", "k": 10}

   202 {"job_id":"<id>","status":"pending","interval":2}   submitted

     401 {"error":"invalid_api_key"}         the key is unknown or revoked
     402 {"error":"insufficient_credit"}     the balance is spent; top up first
     400 {"error":"invalid_request"}         bad JSON, or an empty query

   A query costs $0.01 and is charged when it is accepted, so a job that is
   submitted has already been paid for. At a zero balance the call is refused.

   Poll the job. Wait at least "interval" seconds between polls.

   GET https://drqkocyrytmbvlmasoyv.supabase.co/functions/v1/retrieve-job/<job_id>
   authorization: Bearer $(cat ~/.config/retrievr/credentials)

   200 {"status":"pending"}                      still embedding
   200 {"status":"complete",
        "results":[{"chunk_id":"...","text":"...","title":"...",
                    "author":"...","section_path":"...","doc_id":"...",
                    "chunk_index":0,"char_start":0,"char_end":0,
                    "parent_start":0,"parent_end":0,"licence":"...","score":0.0328}],
        "retrieval_ms": 1208}
   200 {"status":"failed","error":"..."}       the embedding job failed
   404 {"error":"not_found"}                    no such job, or not yours
   410 {"error":"expired_token"}                the job outlived its window

   k is clamped to 1-50; the default is 10. Every result carries its own
   citation, so no second lookup is needed to render it. "text" is the parent
   passage, not the embedded chunk: char_start/char_end address the chunk and
   parent_start/parent_end the passage, so you can quote either.