From 1a3461611db8d5acc5ebebdbb9cc6af43bd74086 Mon Sep 17 00:00:00 2001
From: Julien Calixte <julien.calixte@theodo.com>
Date: Sun, 7 Jun 2026 11:26:29 +0200
Subject: [PATCH] docs(readme): document search endpoints and backfill

---
 README.md | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index b0a25e6..21d4132 100644
--- a/README.md
+++ b/README.md
@@ -41,13 +41,38 @@ docker run -p 8080:8080 -v litenote-data:/data litenote-jetstream
 
 ## API
 
-| Endpoint                         | Description                        |
-| -------------------------------- | ---------------------------------- |
-| `GET /notes?cursor=&limit=`      | Paginated notes from all users     |
-| `GET /:did/notes?cursor=&limit=` | Paginated notes for a specific DID |
+| Endpoint                             | Description                                                                                     |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `GET /notes?cursor=&limit=`          | Paginated notes from all users (discoverable only)                                              |
+| `GET /:did/notes?cursor=&limit=`     | Paginated notes for a specific DID (discoverable only)                                          |
+| `GET /search?q=&cursor=&limit=`      | Full-text fuzzy search across discoverable notes. Returns `{ results, cursor? }`                |
+| `GET /:did/search?q=&cursor=&limit=` | Owner-scoped search incl. non-discoverable. Requires `Authorization: Bearer <jwt>` for that DID |
+
+Search hits include `{ did, rkey, title, snippet, score, publishedAt }`. The
+`snippet` is a sentence-bounded fragment from the matching content with the
+query terms wrapped in `<em>` tags. Queries use OpenSearch `multi_match` with
+`fuzziness: AUTO`, so small typos still match.
 
 ## Environment Variables
 
-| Variable      | Default    | Description                      |
-| ------------- | ---------- | -------------------------------- |
-| `SQLITE_PATH` | `notes.db` | Path to the SQLite database file |
+| Variable              | Default    | Description                                                                                            |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
+| `SQLITE_PATH`         | `notes.db` | Path to the SQLite database file                                                                       |
+| `OPENSEARCH_URL`      | _(unset)_  | OpenSearch base URL (e.g. `http://opensearch:9200`). When unset, indexing and search degrade to no-ops |
+| `OPENSEARCH_USERNAME` | _(unset)_  | Optional basic-auth user                                                                               |
+| `OPENSEARCH_PASSWORD` | _(unset)_  | Optional basic-auth password                                                                           |
+| `OPENSEARCH_INDEX`    | `notes`    | Index name to read/write                                                                               |
+| `ADMIN_DIDS`          | _(empty)_  | Comma-separated DIDs allowed to hit `/admin/*`                                                         |
+
+## OpenSearch backfill
+
+Note content arrives via the jetstream firehose only for new and updated
+records. To populate the index with pre-existing notes, run:
+
+```bash
+OPENSEARCH_URL=http://localhost:9200 deno task backfill:search
+```
+
+The script reads every DID in the local SQLite database, resolves each one's
+PDS, and reindexes their notes via `com.atproto.repo.listRecords`. Safe to
+re-run; document IDs are deterministic (`<did>:<rkey>`).