feat(vector): page-aware PDF chunking for predictable per-page retrieval

Add PageAwareChunker, which splits paginated documents (PDFs) on page
boundaries first and only character-splits pages larger than chunk_size.
No chunk spans a page boundary, so page_number is always exact and stored
excerpts never lead with a neighbouring page's text. When chunk_size is at
least the largest page, this yields exactly one chunk per page: a
predictable vector count (== page count), a flat per-page embedding cost,
and zero cross-page overlap duplication.

Gated by DOCUMENT_CHUNK_PAGE_AWARE (default true). When false, the legacy
char-based DocumentChunker + post-hoc assign_page_numbers path runs
unchanged. Only doc_type="file" with page_boundaries (PDFs) takes the
page-aware path; notes/deck/news are unaffected.

Measured on a 15-page record (query "leadership award louis", target =
top-half of page 15): char-based degraded the target to dense-rank 10 at
cs=2048 (OCR) and mislabeled its page; page-aware restored rank 1 across
every fusion/modality and chunk size, with correct page labels and clean
snippets.

BREAKING CHANGE: PDFs are re-chunked page-aware by default. Existing
deployments will re-index PDF content on the next vector sync (different
chunk counts and page_number labels). Set DOCUMENT_CHUNK_PAGE_AWARE=false
to retain the previous char-based behaviour.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/unit/test_config.py

@@ -167,6 +167,20 @@ class TestChunkConfigValidation:
         assert settings.document_chunk_size == 2048
         assert settings.document_chunk_overlap == 200
 
+    def test_page_aware_enabled_by_default(self):
+        """Page-aware chunking is on by default."""
+        assert Settings().document_chunk_page_aware is True
+
+    @patch.dict(
+        os.environ,
+        {"DOCUMENT_CHUNK_PAGE_AWARE": "false"},
+        clear=True,
+    )
+    def test_page_aware_disabled_via_env(self):
+        """DOCUMENT_CHUNK_PAGE_AWARE=false disables page-aware chunking."""
+        _reload_config()
+        assert get_settings().document_chunk_page_aware is False
+
     def test_valid_chunk_settings(self):
         """Test valid chunk size and overlap configuration."""
         settings = Settings(