Milvus + local-Postgres documentation gaps from tire-kick session

[phernandez]

Docs follow-ups from the Milvus tire-kick session (#1235)

Verified gaps in docs/semantic-search.md (and adjacent), all observed hands-on:

• No local-Postgres user quickstart. Everything Postgres in the repo is framed as
  test infrastructure; a user enabling Milvus must reverse-engineer
  docker-compose-postgres.yml + BASIC_MEMORY_DATABASE_BACKEND/DATABASE_URL from the
  justfile. One short "run Postgres locally" section would unblock the whole Milvus path.
• Fresh-switch step is undocumented: flipping semantic_vector_index requires
  bm reindex --embeddings (incremental suffices — verified: 8,689 chunks re-owned in
  ~3 min); the docs only mention reindex in the migration-cleanup narrative.
• The pre-reindex degraded window is undocumented (see Vector search silently degrades when configured index has no ready manifest rows #1236): vector returns
  nothing and hybrid quietly serves FTS-only until the reindex runs.
• Milvus Lite .db reality: pymilvus hard-requires the .db suffix and an existing
  parent directory, and what it creates is a directory tree (collections/, databases/,
  LOCK), not a file. Errors for bad shapes are raw pymilvus exceptions with no pointer to
  the milvus_uri setting.
• milvus_database is ignored by Milvus Lite (no named-database support); it's
  passed unconditionally as db_name.
• Stale rows after pgvector→milvus: the old pgvector projection
  (search_vector_embeddings, 8,689 rows in the session) remains on disk indefinitely;
  document the manual cleanup or note the disk cost until a cleanup command exists.

Positive findings worth stating in docs while editing: identical vector rankings and
scores (4-decimal agreement) across sqlite-vec/pgvector/Milvus Lite on a 222-entity
corpus; dimension-mismatch refusal message is excellent; missing-extra error is excellent;
30s timeout honored on unreachable servers; collections reload across processes (#1185).

[claude]

Claude finished @phernandez's task in 35s —— View job

---

Triage

Type: Documentation — this is a docs-gap report, not a code defect. All items are follow-ups from hands-on Milvus/local-Postgres testing during the #1235 tire-kick session, targeting docs/semantic-search.md and adjacent pages.

Component: None of the repo-labeled components apply directly (not Cloud-specific). In prose: touches semantic search / vector index docs, Milvus Lite (milvus_uri, milvus_database), and local Postgres setup (docker-compose-postgres.yml, BASIC_MEMORY_DATABASE_BACKEND / DATABASE_URL).

Priority: Medium. Nothing is broken — these are usability/onboarding gaps that would block or confuse a user enabling Milvus or local Postgres, particularly the missing quickstart and the undocumented degraded-search window (which overlaps with the bug in #1236).

Complexity: Simple–Medium. Most items are additive documentation (a local-Postgres quickstart section, a bm reindex --embeddings note, Milvus Lite .db path/directory-shape caveats, a note that milvus_database is a no-op for Milvus Lite, and either a stale pgvector-rows cleanup note or pointer to a future cleanup command). No code changes required for the checklist as written.

Duplicates: None found. This is a distinct, docs-scoped sub-issue of the #1235 tracking issue, and calls out #1236 (degraded-search window) as the related root-cause bug rather than duplicating it.

No missing-info follow-ups needed — the report already includes concrete verification detail (chunk counts, timings, exact behaviors) for each gap.