feat(find): restrict a search to one observe-source

Source sizes differ by three orders of magnitude -- on the reporting
machine codex-sessions holds 260,623 transcript lines against 518 in
usmc-working, out of 290,902 observed entries. BM25 hands the whole first
page to the transcripts, so a subject-matter search comes back looking
empty and the index appears not to contain the entry at all.

find() now takes --source <id>[,<id>] (and find(source=...)), a WHERE
condition on the observed/<source-id>/ namespace applied before the
ranking -- in all three stages, because wiring it into the exact FTS pass
alone would drop the filter silently on any multi-word query. Without a
query the flag lists the source, since FTS5 has nothing to match on.
--type and --limit are passed through from the CLI as well; find()
already accepted them.

The find command parses its own flags now: the CLI has no argparse and
joined everything after `find` into the query, so --source would have
become a search word.

Read-only: no schema migration, no new index, recall() untouched, and the
new parameter is appended with a None default.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BoFKxJmj9pU5Q8a6yN8HBn

Author: Lukas Geiger

CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 2026-08-13
+
+`find()` can be restricted to one observe-source, so a small source is no
+longer buried by a large one.
+
+- **`--source <id>[,<id>]` / `find(source=...)`** filters on the
+  `observed/<source-id>/…` namespace as a `WHERE` condition -- before the
+  ranking, and in all three stages of `find()`: exact FTS, the multi-word OR
+  fallback, and the LIKE fallback. Wiring it into only the first stage would
+  have dropped the filter silently on any multi-word query.
+  - Why it was needed: source sizes differ by three orders of magnitude. On
+    the reporting machine `codex-sessions` holds 260,623 transcript lines
+    against 518 in `usmc-working`, out of 290,902 `observed` entries total.
+    BM25 hands the entire first page to the transcripts, so a subject-matter
+    search returns nothing usable and reads as "not in the index".
+  - A source id matches a whole path segment, so `--source usmc` does not
+    pull in `usmc-working`. A leading `observed/` is optional, several ids
+    are OR-ed, and `_`/`%` in an id are escaped instead of acting as LIKE
+    wildcards.
+- **`--source` without a query lists the source**, newest first. FTS5 needs a
+  term to match; "show me everything from this source" has none, so that case
+  takes a plain `WHERE`/`ORDER BY updated` path instead of returning nothing.
+- **`--type` and `--limit` are now reachable from the CLI.** `find()` already
+  accepted both; only the command line did not pass them through.
+- **The `find` command parses its own flags.** The CLI has no argparse and
+  joined everything after `find` into the query, so `--source` would have
+  become a search word. `_parse_find_args()` splits options from search terms,
+  accepts `--flag value` and `--flag=value`, and reports unknown options and
+  missing values instead of silently searching for them.
+- Documented in `README.md` and `README_de.md`, including the pre-existing
+  workaround for older versions (pass the source id as a search word -- entry
+  names are in the full-text index) and the boundary against `extra_tags`,
+  which labels a source at registration time rather than narrowing one search.
+- Test suite grew from 86 to 108 tests.
+
+Read-only change: no schema migration, no new index, `recall()` untouched, and
+existing `find()` callers keep their behaviour (the new parameter is appended
+and defaults to `None`).
+
 ## 2026-08-05
 
 Fixed: the never-index list missed Windows paths on non-Windows hosts.

README.md

@@ -278,6 +278,44 @@ af.observe_source_add("usmc-lessons", "sqlite_table",
                                 "tags": "category"})
 ```
 
+### Searching one source instead of all of them
+
+Sources differ in size by three orders of magnitude. On this machine
+`codex-sessions` holds 260,000 transcript lines while `usmc-working` holds
+518 notes — so BM25 hands the whole first page to the transcripts, and a
+subject-matter search comes back looking empty. `find()` therefore takes a
+source filter:
+
+```bash
+gardener find --source usmc-working store welle
+gardener find --source usmc-working,usmc-facts store
+gardener find --source usmc-working              # no query: list the source
+gardener find --type memory --limit 5 store      # also exposed: type, limit
+```
+
+```python
+af.find("store welle", source="usmc-working")
+af.find("store", source=["usmc-working", "usmc-facts"])
+af.find("", source="usmc-working", limit=50)     # list, newest first
+```
+
+The filter is a `WHERE` condition on the `observed/<source-id>/…` namespace
+and runs **before** the ranking, in all three stages of `find()` (exact FTS,
+multi-word OR fallback, LIKE fallback). A source id matches the whole path
+segment, so `--source usmc` does not pull in `usmc-working`; a leading
+`observed/` may be written or omitted. `--source` and the `source` field in a
+result are different things — the field names the database (`user`/`system`).
+
+> [!NOTE]
+> **Older versions without `--source`:** pass the source id as a search word,
+> `gardener find usmc-working store`. Entry names are part of the full-text
+> index, so this works — it just ranks weaker than a real filter, because the
+> id competes with the query terms instead of restricting the candidate set.
+
+This is the query-time counterpart to `extra_tags` below: `extra_tags` labels a
+source when it is registered, for consumers that group several sources under one
+name; `--source` narrows a single search to a named source and needs no foresight.
+
 ### What a source can never index
 
 A source config points an adapter at whatever glob it likes, so the

README_de.md

@@ -280,6 +280,45 @@ af.observe_source_add("gemini-archive", "agent_transcripts",
                        zip_inner="*/.system_generated/logs/transcript.jsonl")
 ```
 
+### Eine Quelle suchen statt alle
+
+Quellen unterscheiden sich um drei Grössenordnungen: Auf dieser Maschine hält
+`codex-sessions` 260.000 Transkriptzeilen, `usmc-working` 518 Notizen — BM25 gibt
+die ganze erste Seite also den Transkripten, und eine Fachsuche sieht aus, als
+gäbe es nichts. `find()` nimmt deshalb einen Quellenfilter entgegen:
+
+```bash
+gardener find --source usmc-working store welle
+gardener find --source usmc-working,usmc-facts store
+gardener find --source usmc-working              # ohne Suchbegriff: Quelle auflisten
+gardener find --type memory --limit 5 store      # ebenfalls neu durchgereicht
+```
+
+```python
+af.find("store welle", source="usmc-working")
+af.find("store", source=["usmc-working", "usmc-facts"])
+af.find("", source="usmc-working", limit=50)     # auflisten, neueste zuerst
+```
+
+Der Filter ist eine `WHERE`-Bedingung auf den Namensraum `observed/<quell-id>/…`
+und wirkt **vor** dem Ranking, in allen drei Stufen von `find()` (exakte
+FTS-Suche, Mehrwort-ODER-Fallback, LIKE-Fallback). Eine Quell-ID matcht das ganze
+Pfadsegment, `--source usmc` zieht also nicht `usmc-working` mit; ein
+vorangestelltes `observed/` darf man schreiben oder weglassen. `--source` und das
+Feld `source` im Ergebnis sind zweierlei — das Feld benennt die Datenbank
+(`user`/`system`).
+
+> [!NOTE]
+> **Ältere Versionen ohne `--source`:** die Quell-ID als Suchwort mitgeben,
+> `gardener find usmc-working store`. Eintragsnamen stehen im Volltextindex, das
+> funktioniert also — es rankt nur schwächer als ein echter Filter, weil die ID
+> mit den Suchbegriffen konkurriert, statt die Kandidatenmenge einzuschränken.
+
+Das ist das Gegenstück zur Abfragezeit zu `extra_tags` weiter unten: `extra_tags`
+etikettiert eine Quelle bei der Registrierung, für Konsumenten, die mehrere
+Quellen unter einem Namen bündeln; `--source` verengt eine einzelne Suche auf
+eine benannte Quelle und braucht keine Vorausplanung.
+
 ### Was eine Quelle niemals indexieren kann
 
 Eine Quellen-Konfiguration richtet den Adapter auf einen beliebigen Glob —

ROADMAP.md

@@ -2,8 +2,8 @@
 
 **🇩🇪 [Deutsche Version](ROADMAP_de.md)**
 
-> Updated: 2026-08-01
-> Current release: v0.3.1 (prototype)
+> Updated: 2026-08-13
+> Current release: v0.4.0 (prototype)
 
 ## Prototype (v0.1) — DONE
 

ROADMAP_de.md

@@ -2,8 +2,8 @@
 
 **🇬🇧 [English Version](ROADMAP.md)**
 
-> Aktualisiert: 2026-08-01
-> Aktuelle Version: v0.3.1 (Prototyp)
+> Aktualisiert: 2026-08-13
+> Aktuelle Version: v0.4.0 (Prototyp)
 
 ## Prototyp (v0.1) — ERLEDIGT