From 943e60feccb7dae98b4b1f90427f74b2ee0852a4 Mon Sep 17 00:00:00 2001
From: Trenton Holmes <797416+stumpylog@users.noreply.github.com>
Date: Mon, 17 Aug 2026 20:27:38 -0700
Subject: [PATCH] docs: clarify quoted date-keyword phrases and dropped *_id
 field aliases

Add a sentence to the "Supported date keywords" advanced-search section
noting that multi-word date keywords must be quoted (e.g.
added:"previous month") -- whoosh-compat requires quoting where the
unquoted form used to work. Also document that the old undocumented
*_id field aliases (tag_id, owner_id, viewer_id, correspondent_id,
document_type_id, storage_path_id, type_id, path_id) are no longer
recognized: a query using one now silently folds to a literal-text
search instead of matching the intended structured field.
---
 docs/usage.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/usage.md b/docs/usage.md
index ac17c300d..6ab05f410 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -919,6 +919,14 @@ original_filename:invoice.pdf
 - `original_filename` matches the filename of the document as originally
   consumed.
 
+Older, undocumented `*_id` field prefixes (`tag_id`, `owner_id`, `viewer_id`,
+`correspondent_id`, `document_type_id`, `storage_path_id`, `type_id`, and
+`path_id`) are no longer recognized advanced-search fields. A query using one
+of them (e.g. `tag_id:5`) does not error; it silently falls back to a literal
+text search for that string, which will almost never match real document
+content. Use the corresponding named field (`tag`, `correspondent`,
+`document_type`, etc.) instead.
+
 Matching inexact words:
 
 ```
@@ -927,6 +935,9 @@ produ*name
 
 Matching natural date keywords:
 
+Multi-word date keywords must be quoted (e.g. `added:"previous month"`); an
+unquoted multi-word keyword is not recognized as a date keyword.
+
 ```
 added:today
 modified:yesterday