docs(agents): correct a stale claim and record what ADR-0026 changed

[fvadicamo]

Documentation only. No code changes. Touches .claude/CLAUDE.md, the versioned agent-instructions file every Claude Code session in this repo reads.

The stale claim

It still said:

This is also why reindex is a no-op in Qdrant mode (BUG-021): it reads the empty document_chunks table.

True until #102 fixed it. Now actively misleading: an agent reading this today would not investigate a reindex that produced nothing, because the instructions tell it a reindex never works in Qdrant mode anyway. That is precisely the doc/code drift this recent bug family was made of.

What replaces it

• document_chunks is private to the pgvector provider (ADR-0026). No other module may read it; every chunk path goes through the VectorStoreProvider Protocol. Stated with the reason, because the reason is the whole point: modules that queried that table directly in Qdrant mode did not fail — they reported success.
• A new vector store provider must implement delete_index_version() and must refuse to delete its own active version (ActiveIndexVersionError → ERR-INDEX-001, 409). The failure mode it guards is not "an old index version survives", it is "the live index is emptied".
• A dormant capability is not harmless, it is only not yet dangerous. Three gaps in this family were armed by their own fix:

Latent gap	Harmless while…	Armed by
DELETE had no namespace binding	the delete deleted nothing	its own fix — it became a cross-namespace deletion
the vektra-app tests had never worked	nobody ran them	wiring them into CI
no cleanup for an old index version	reindex wrote nothing	its own fix — every reindex now doubles storage

The rule: verify empirically, do not trust the reports. Bugs in this family return 200 OK and a reassuring status field.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded guidance for switching between vector-store providers and locating chunk content.
  • Documented safeguards for preventing deletion of an active index version.
  • Added troubleshooting guidance for verifying destructive operations through direct data counts rather than status messages.

[coderabbitai]

Warning

Review limit reached

@fvadicamo, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 54 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fc01b6ef-4133-4559-bad6-fbb3f3ae6808

📥 Commits

Reviewing files that changed from the base of the PR and between 8d6fa94 and f6213f8.

📒 Files selected for processing (1)

• .claude/CLAUDE.md

📝 Walkthrough

Walkthrough

Expanded .claude/CLAUDE.md with ADR-0026 guidance for provider-owned chunk storage, active index deletion safeguards, and verification of dormant capabilities.

Changes

Index provider guidance

Layer / File(s)	Summary
Provider storage and deletion safety .claude/CLAUDE.md	Documents Qdrant and pgvector chunk ownership, routes chunk operations through VectorStoreProvider, and specifies ActiveIndexVersionError behavior for deleting an active version.
Dormant capability verification .claude/CLAUDE.md	Adds examples of latent gaps becoming active and requires row/point counts to verify operations instead of relying solely on successful status signals.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• vektralabs/vektra-stack#97: Updates the same guidance around Qdrant-versus-pgvector chunk storage and reindex behavior.

Suggested labels: documentation, component:index

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the documentation update and the ADR-0026-related corrections described in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-instructions-post-adr-0026

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request updates .claude/CLAUDE.md to document architectural decisions (ADR-0026) regarding vector store chunk ownership, emphasizing that document_chunks is private to the pgvector provider and that other modules must use the VectorStoreProvider Protocol. It also adds a section on validating dormant capabilities and verifying results empirically. The review feedback points out that the list of Qdrant payload fields in the documentation is missing index_version and should refer to the entire metadata dictionary rather than just metadata.chunk_level.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.