fix(vault): include shared docs in agent read paths (#917)

- Patch vault_search, ListDocuments, CountDocuments, ListTreeEntries to
  include shared docs (agent_id IS NULL) for agents in the tenant
- Keep DELETE/GetDocument/GetByBasename strict (auth-intent)
- Add CHECK invariant vault_documents_scope_consistency (PG migration
  000055 NOT VALID, SQLite triggers v24) to prevent future drift
- Update docs and changelog

Affects PostgreSQL and SQLite (desktop edition).

docs/17-changelog.md

@@ -52,6 +52,7 @@ Integration / chaos / RBAC / tracing coverage + user documentation + copy-paste
 ### Fixed
 - **`PGHookStore.GetByID` + `SqliteHookStore.GetByID`** now enforce tenant scope: non-master callers only see own + global rows. Previously returned any row by UUID which leaked cross-tenant.
 - **Existing pipeline integration tests** now call `security.SetAllowLoopbackForTest(true)` via shared helper; no longer flake on SSRF block for httptest endpoints.
+- **Vault**: Shared docs (`scope='shared'`, `agent_id=NULL`) are now visible to agents via `vault_search`, `ListDocuments`, `CountDocuments`. Previously excluded by strict `agent_id = $N` predicate after migration 000046 made `agent_id` nullable. Also fixes single-team filter to include shared docs. Adds CHECK invariant (migration 000055) to prevent future scope/ownership drift. Affects PostgreSQL and SQLite (desktop edition). (#917)
 
 ### Testing
 - All hook integration tests pass under `TEST_DATABASE_URL` PG container (7 new test files, 18 new top-level tests)

docs/24-knowledge-vault.md

@@ -46,6 +46,27 @@ Documents are scoped by **tenant** (isolation), **agent** (per-agent namespace),
 - **team**: Team workspace documents (team_context_files)
 - **shared**: Cross-tenant shared knowledge (future)
 
+### Document Scope & Ownership
+
+| scope | agent_id | team_id | Visibility |
+|-------|----------|---------|------------|
+| personal | set  | NULL   | Owning agent only (within tenant) |
+| team     | NULL | set    | Members of the team (within tenant) |
+| shared   | NULL | NULL   | All agents within the tenant |
+| custom   | any  | any    | User-defined via `custom_scope` |
+
+#### DB Invariant (migration 000055)
+
+A CHECK constraint enforces the above table: `vault_documents_scope_consistency`. Rejects inserts/updates that violate the scope × ownership relationship. `scope='custom'` is unconstrained (user-defined scopes).
+
+#### Agent Read Semantics
+
+`vault_search`, `ListDocuments`, `CountDocuments` return:
+- Docs owned by the agent (`agent_id = <agent>`)
+- PLUS shared docs (`agent_id IS NULL`)
+
+Within a team context (RunContext with TeamID set), results also include team-scoped docs for that team. Tenant isolation (`tenant_id = <tenant>`) is always enforced.
+
 ---
 
 ## 2. Data Model