docs(vault): update all docs for v1.0 API (trust_tier, upsert, get_multiple)

- Rename trust= to trust_tier= in all code examples across 9 docs + README
- Rename trust_min to min_trust_tier in api-reference search() signature
- Add upsert() and get_multiple() to api-reference
- Add migration, deployment, troubleshooting to docs/index.md
- Fix migration.md before/after examples (were clobbered by sed)
- Document get_content() quarantine behavior

Author: bradleygauthier

README.md

@@ -165,7 +165,7 @@ vault = Vault("./my-knowledge")
 
 # Add with trust tiers
 vault.add("Incident response: acknowledge within 15 minutes...",
-          name="sop-incident.md", trust="canonical")
+          name="sop-incident.md", trust_tier="canonical")
 
 # Trust-weighted search (deduplicated, with freshness decay)
 results = vault.search("incident response")
@@ -205,7 +205,7 @@ vault = Vault("./knowledge", role="admin")        # + export, import, config
 ### Batch Import
 
 ```python
-resources = vault.add_batch(["doc1.md", "doc2.md", "doc3.md"], trust="working")
+resources = vault.add_batch(["doc1.md", "doc2.md", "doc3.md"], trust_tier="working")
 ```
 
 ### Memory Layers

docs/api-reference.md

@@ -44,7 +44,7 @@ vault.add(
     source: str | Path | bytes,
     *,
     name: str | None = None,
-    trust: TrustTier | str = "working",
+    trust_tier: TrustTier | str = "working",
     classification: DataClassification | str = "internal",
     layer: MemoryLayer | str | None = None,
     collection: str | None = None,
@@ -67,7 +67,7 @@ Content is screened by the Membrane pipeline before indexing. Flagged content is
 vault.add_batch(
     sources: list[str | Path | bytes],
     *,
-    trust: TrustTier | str = "working",
+    trust_tier: TrustTier | str = "working",
     tenant_id: str | None = None,
     **kwargs,
 ) -> list[Resource]
@@ -81,13 +81,23 @@ vault.add_batch(
 vault.get(resource_id: str) -> Resource
 ```
 
+### get_multiple()
+
+```python
+vault.get_multiple(resource_ids: list[str]) -> list[Resource]
+```
+
+Batch retrieval in a single query. Missing IDs are silently omitted.
+
+<!-- VERIFIED: vault.py:473-485 -->
+
 ### get_content()
 
 ```python
 vault.get_content(resource_id: str) -> str
 ```
 
-Reassembles chunks in order to return the full text content.
+Reassembles chunks in order to return the full text content. Quarantined resources raise `VaultError`.
 
 <!-- VERIFIED: vault.py:406-420 -->
 
@@ -97,7 +107,7 @@ Reassembles chunks in order to return the full text content.
 vault.list(
     *,
     tenant_id: str | None = None,
-    trust: TrustTier | str | None = None,
+    trust_tier: TrustTier | str | None = None,
     classification: DataClassification | str | None = None,
     layer: MemoryLayer | str | None = None,
     collection: str | None = None,
@@ -118,7 +128,7 @@ vault.update(
     resource_id: str,
     *,
     name: str | None = None,
-    trust: TrustTier | str | None = None,
+    trust_tier: TrustTier | str | None = None,
     classification: DataClassification | str | None = None,
     tags: list[str] | None = None,
     metadata: dict[str, Any] | None = None,
@@ -146,6 +156,23 @@ Creates a new resource with the new content and supersedes the old one. Returns
 
 <!-- VERIFIED: vault.py:422-464 -->
 
+### upsert()
+
+```python
+vault.upsert(
+    source: str | Path | bytes,
+    *,
+    name: str | None = None,
+    trust_tier: TrustTier | str = "working",
+    tenant_id: str | None = None,
+    **kwargs,
+) -> Resource
+```
+
+Add-or-replace atomically. If a resource with the same name and tenant exists, supersedes it. Otherwise creates new.
+
+<!-- VERIFIED: vault.py:562-611 -->
+
 ---
 
 ## Search
@@ -160,7 +187,7 @@ vault.search(
     top_k: int = 10,
     offset: int = 0,                    # Pagination
     threshold: float = 0.0,
-    trust_min: TrustTier | str | None = None,
+    min_trust_tier: TrustTier | str | None = None,
     layer: MemoryLayer | str | None = None,
     collection: str | None = None,
     as_of: date | None = None,          # Point-in-time

docs/getting-started.md

@@ -55,16 +55,16 @@ Creates `./my-knowledge/` with SQLite database and audit log. No configuration r
 ```python
 # From text
 vault.add("Incident response: acknowledge within 15 minutes...",
-          name="sop-incident.md", trust="canonical")
+          name="sop-incident.md", trust_tier="canonical")
 
 # From a file
-vault.add("path/to/report.pdf", trust="working")
+vault.add("path/to/report.pdf", trust_tier="working")
 
 # With tenant isolation
 vault.add("Tenant-specific content", tenant_id="site-123")
 
 # Batch add
-vault.add_batch(["doc1.md", "doc2.md", "doc3.md"], trust="working")
+vault.add_batch(["doc1.md", "doc2.md", "doc3.md"], trust_tier="working")
 ```
 
 Resources are automatically: chunked, hashed (SHA3-256), screened by Membrane, indexed, and audited.

docs/index.md

@@ -21,14 +21,17 @@ Governed knowledge store for autonomous organizations. Every fact has provenance
 | [Streaming & Telemetry](streaming-and-telemetry.md) | Real-time events, operation metrics |
 | [CLI Reference](cli.md) | All 15 commands |
 | [FastAPI Integration](fastapi.md) | 22+ REST endpoints |
+| [Migration Guide](migration.md) | Breaking changes from v0.x to v1.0 |
+| [Deployment Guide](deployment.md) | PostgreSQL, SSL, encryption, production checklist |
+| [Troubleshooting](troubleshooting.md) | Error codes (VAULT_000-700), common issues |
 
 ## Quick Start
 
 ```python
 from qp_vault import Vault
 
 vault = Vault("./my-knowledge")
-vault.add("quarterly-report.pdf", trust="canonical")
+vault.add("quarterly-report.pdf", trust_tier="canonical")
 results = vault.search("Q3 revenue projections")
 print(results[0].content, results[0].trust_tier)
 ```

docs/lifecycle.md

@@ -43,7 +43,7 @@ vault = Vault("./knowledge")
 policy = vault.add(
     "Security policy for remote access...",
     name="security-policy-v2.md",
-    trust="canonical",
+    trust_tier="canonical",
     lifecycle="draft",
 )
 
@@ -69,8 +69,8 @@ except LifecycleError as e:
 When a newer version replaces an older one:
 
 ```python
-v1 = vault.add("Policy v1", name="policy-v1.md", trust="canonical")
-v2 = vault.add("Policy v2 with PQ crypto", name="policy-v2.md", trust="canonical")
+v1 = vault.add("Policy v1", name="policy-v1.md", trust_tier="canonical")
+v2 = vault.add("Policy v2 with PQ crypto", name="policy-v2.md", trust_tier="canonical")
 
 # Supersede: v1 -> SUPERSEDED, linked to v2
 old, new = vault.supersede(v1.id, v2.id)
@@ -108,7 +108,7 @@ from datetime import date
 vault.add(
     "Q4 2025 budget allocation",
     name="budget-q4-2025.md",
-    trust="canonical",
+    trust_tier="canonical",
     valid_from=date(2025, 10, 1),
     valid_until=date(2025, 12, 31),
 )

docs/memory-layers.md

@@ -37,16 +37,16 @@ vault.add("SOC2 Type II audit completed 2025-12-15",
 Get a scoped view that auto-applies layer defaults:
 
 ```python
-# OPERATIONAL: adds with trust=WORKING by default
+# OPERATIONAL: adds with trust_tier=WORKING by default
 ops = vault.layer(MemoryLayer.OPERATIONAL)
 await ops.add("runbook-content", name="runbook.md")
-# Equivalent to: vault.add(..., trust="working", layer="operational")
+# Equivalent to: vault.add(..., trust_tier="working", layer="operational")
 
-# STRATEGIC: adds with trust=CANONICAL by default
+# STRATEGIC: adds with trust_tier=CANONICAL by default
 strategic = vault.layer(MemoryLayer.STRATEGIC)
 await strategic.add("architecture decision", name="adr.md")
 
-# COMPLIANCE: adds with trust=CANONICAL, and every search is audited
+# COMPLIANCE: adds with trust_tier=CANONICAL, and every search is audited
 compliance = vault.layer(MemoryLayer.COMPLIANCE)
 await compliance.add("audit evidence", name="audit.pdf")
 results = await compliance.search("SOC2")
@@ -103,12 +103,12 @@ from qp_vault.config import VaultConfig, LayerDefaults
 config = VaultConfig(
     layer_defaults={
         "operational": LayerDefaults(
-            trust="working",
+            trust_tier="working",
             half_life_days=60,        # Faster freshness decay
             search_boost=2.0,         # Higher priority in search
         ),
         "compliance": LayerDefaults(
-            trust="canonical",
+            trust_tier="canonical",
             retention="permanent",
             audit_reads=True,
         ),

docs/migration.md

@@ -9,12 +9,12 @@ qp-vault 1.0 locks the API. Three parameter renames are the only breaking change
 Affects: `add()`, `list()`, `update()`, `add_batch()`, `replace()`.
 
 ```python
-# Before (v0.16 and earlier)
+# v0.x (old)
 vault.add("document.pdf", trust="canonical")
 vault.list(trust="working")
 vault.update(resource_id, trust="canonical")
 
-# After (v1.0)
+# v1.0 (new)
 vault.add("document.pdf", trust_tier="canonical")
 vault.list(trust_tier="working")
 vault.update(resource_id, trust_tier="canonical")
@@ -25,10 +25,10 @@ vault.update(resource_id, trust_tier="canonical")
 Affects: `search()`, `search_with_facets()`.
 
 ```python
-# Before
+# v0.x (old)
 results = vault.search("query", trust_min="working")
 
-# After
+# v1.0 (new)
 results = vault.search("query", min_trust_tier="working")
 ```
 
@@ -37,14 +37,12 @@ results = vault.search("query", min_trust_tier="working")
 Affects: VaultConfig TOML files and programmatic config.
 
 ```python
-# Before
-from qp_vault.config import VaultConfig, LayerDefaults
-
+# v0.x (old)
 config = VaultConfig(layer_defaults={
     "operational": LayerDefaults(trust="working"),
 })
 
-# After
+# v1.0 (new)
 config = VaultConfig(layer_defaults={
     "operational": LayerDefaults(trust_tier="working"),
 })
@@ -55,14 +53,11 @@ config = VaultConfig(layer_defaults={
 For most codebases, a find-and-replace handles it:
 
 ```bash
-# Parameter renames
 sed -i 's/trust="canonical"/trust_tier="canonical"/g' your_code.py
 sed -i 's/trust="working"/trust_tier="working"/g' your_code.py
 sed -i 's/trust="ephemeral"/trust_tier="ephemeral"/g' your_code.py
 sed -i 's/trust="archived"/trust_tier="archived"/g' your_code.py
 sed -i 's/trust_min=/min_trust_tier=/g' your_code.py
-
-# Config field
 sed -i 's/LayerDefaults(trust=/LayerDefaults(trust_tier=/g' your_code.py
 ```
 

docs/multi-tenancy.md

@@ -8,8 +8,8 @@ qp-vault supports multi-tenant isolation via `tenant_id` on all operations.
 vault = Vault("./knowledge")
 
 # Add with tenant isolation
-vault.add("Tenant A document", tenant_id="site-123", trust="canonical")
-vault.add("Tenant B document", tenant_id="site-456", trust="working")
+vault.add("Tenant A document", tenant_id="site-123", trust_tier="canonical")
+vault.add("Tenant B document", tenant_id="site-456", trust_tier="working")
 
 # Search scoped to tenant
 results = vault.search("document", tenant_id="site-123")

docs/trust-tiers.md

@@ -32,12 +32,12 @@ This means official SOPs always surface above drafts, even when drafts are sligh
 
 ```python
 # On creation
-vault.add("SOP content", trust="canonical")
-vault.add("Draft notes", trust="working")
-vault.add("Standup notes", trust="ephemeral")
+vault.add("SOP content", trust_tier="canonical")
+vault.add("Draft notes", trust_tier="working")
+vault.add("Standup notes", trust_tier="ephemeral")
 
 # After creation
-vault.update(resource_id, trust="canonical")
+vault.update(resource_id, trust_tier="canonical")
 ```
 
 Trust changes emit a `TRUST_CHANGE` audit event.