vayl-mcp 0.1.0__tar.gz

vayl_mcp-0.1.0/COMPLIANCE.md

@@ -0,0 +1,222 @@
+# Vayl — EU Compliance Deployment Guide
+
+For a Data Protection Officer / privacy counsel evaluating Vayl for deployment that processes
+**EU residents' personal data**, in the **on-premise / self-hosted** model (your organization runs
+Vayl inside your own environment).
+
+> **This is not legal advice.** It is a technical mapping of Vayl's features to the obligations you
+> are likely to face, and an honest split of who is responsible for what. Your DPO / counsel makes
+> the final determination for your specific processing. Vayl provides *building blocks*; it does not,
+> and cannot, make your organization compliant.
+
+## Roles (this is the foundation)
+
+In the on-prem model:
+
+| Party | Role under GDPR | Consequence |
+|---|---|---|
+| **Your organization** (the deployer) | **Data controller** | You carry the obligations below. |
+| **Vayl** (the software vendor) | **Not a processor** — it runs on your infrastructure and the vendor never receives your data | No controller↔vendor DPA needed for the local deployment. |
+| **Your chosen LLM/embedding provider** *(only if cloud)* | **Sub-processor** | You need a DPA + a transfer basis with them. **Avoided entirely if you use the local model** (Vayl's default). |
+
+## The two decisions that dominate your compliance
+
+1. **LLM choice = your international-transfer position.**
+   - **Local model (Vayl's default): personal data never leaves the machine.** No sub-processor, no
+     Art. 44 transfer, strong data residency. This is the compliant-by-default configuration.
+   - **Cloud model (e.g. US-hosted): memory text is sent to that provider.** That provider becomes a
+     sub-processor; you need a DPA and a **Chapter V transfer basis** (adequacy, EU-US Data Privacy
+     Framework certification, or SCCs + a Transfer Impact Assessment). For EU data, prefer a local or
+     EU-hosted model.
+2. **EU AI Act risk class = your *use case*, not Vayl.** A memory layer isn't classified on its own;
+   the *system it's part of* is. See "EU AI Act" below.
+
+## GDPR — obligations and the responsibility split
+
+| GDPR requirement | Owner | What Vayl provides |
+|---|---|---|
+| **Lawful basis** (Art. 6) — consent / legitimate interest / contract | **You** | — |
+| **Transparency / privacy notice** (Art. 13–14) | **You** | — |
+| **Data-subject access** (Art. 15) | **You** run the process | `list_memories`, `get_memory`, `history` |
+| **Rectification** (Art. 16) | **You** | `update_memory` (audit-preserving) |
+| **Erasure / right to be forgotten** (Art. 17) | **You** | `delete(subject)` / `delete_all()` — **hard delete**, history and graph included |
+| **Restriction / objection** (Art. 18, 21) | **You** | scope isolation via `user_id`/`agent_id`/`run_id` |
+| **Portability / access** (Art. 20, 15) | **You** | ✅ `export_memory` — machine-readable JSON: statements (active + history) **plus decision snapshots, audit entries, and receipts** about the subject |
+| **Accountability** (Art. 5(2)) | **Shared** | ✅ append-only `audit_log` — who / what / when, for every data operation |
+| **Storage limitation** (Art. 5(1)(e)) | **You** set the policy | ✅ `purge_expired` — hard-delete records older than N days; flags extend it to audit / decisions / receipts (audit chain stays verifiable via a signed anchor) |
+| **Security of processing** (Art. 32) | **Shared** | **encryption at rest** (on by default), auth, localhost-only, no telemetry, parameterized queries |
+| **Records of Processing** (Art. 30) | **You** | data-flow description (this doc + `SECURITY.md`) |
+| **DPIA** (Art. 35) — likely required for AI profiling / large-scale | **You** | inputs: architecture, data-flow, security controls, this doc |
+| **Processor agreement** (Art. 28) | **You**, *only if* using a cloud LLM | local default avoids it |
+| **Breach notification** (Art. 33–34, 72h) | **You** | — |
+| **DPO** (Art. 37), if required | **You** | — |
+| **Privacy by design & default** (Art. 25) | **Shared** | local-first, erasure built in, encrypted, minimal egress |
+
+### Storage limitation & retention (Art. 5(1)(e)) — read this carefully
+Vayl is **event-sourced**: `forget` **retracts but retains history** (auditable), while
+`delete`/`delete_all` **hard-erase** everything. These are different tools for different obligations:
+- Map a **retention/minimization** policy to periodic `delete` of stale subjects.
+- Map a **data-subject erasure request** to **`delete`/`delete_all`**, *not* `forget` — `forget`
+  keeps the value in history, which does **not** satisfy Art. 17.
+
+Vayl provides `purge_expired(older_than_days)` to enforce a retention window (and `audit_log` records
+every erasure as evidence). You still set and document the *policy*; schedule the purge accordingly.
+
+### Erasure vs. accountability — a tension to resolve explicitly
+`delete`/`delete_all` hard-erase the **facts**, but the **audit log and erasure receipts deliberately
+retain an (encrypted) reference to the subject** — that retention *is* the accountability feature
+(Art. 5(2)), and it is in tension with erasure (Art. 17). Decide and document one of:
+- **Encrypted retention** — the audit/receipt detail is Fernet ciphertext at rest (pseudonymized),
+  retained under Art. 17(3)(b)/(e) (legal obligation / legal claims) for a defined period; **or**
+- **Crypto-shredding** — destroy the encryption key to render the retained references unrecoverable
+  (effective erasure of the audit detail too); **or**
+- **Redaction** — purge/anonymize the audit entries for that subject.
+
+The signed **erasure receipt** proves the facts were deleted; the retained (encrypted) audit reference
+is your accountability trail — choose its fate per your retention policy, don't leave it implicit.
+
+**Decision snapshots are redacted on erasure.** Decision records snapshot the beliefs behind an
+action — including the personal values. `delete`/`delete_all` therefore also **redact the erased
+values from those snapshots**: the decision rows and summaries remain (the accountability record of
+*what* was decided), the value is replaced with an explicit redaction marker, the decision is
+**re-signed** so verification still passes, and the redaction itself is recorded in the audit log.
+Retention for the append-only tables exists too: `purge_expired(include_audit / include_decisions /
+include_receipts)` — the audit chain stays verifiable across purges via a **signed retention anchor**.
+
+### Special-category data (Art. 9)
+If the agent may store health, biometric, racial, political, religious, sexual-orientation, or
+trade-union data, that is special-category: you generally need **explicit consent** (or another Art. 9
+condition) and heightened safeguards. Vayl's encryption-at-rest helps with Art. 32 but does **not**
+provide the legal basis.
+
+### Automated decision-making (Art. 22)
+If Vayl's memory feeds **automated decisions with legal or similarly significant effects**, data
+subjects have rights to human intervention and to contest. Vayl gives you concrete controls for this
+(see "Trust-layer controls" below): the **safety gate** (`check_before_act` / `safe_recall`) is a
+testable human-in-the-loop trigger — it refuses to act on disputed/low-confidence/stale memory and
+routes to a human — while **belief provenance** and **`explain_decision`** supply the "meaningful
+information about the logic" a data subject can be given, and the basis on which they contest.
+
+## EU AI Act
+
+Vayl is a component of an AI system. Your obligations depend on how you use it:
+
+- **Roles:** you are typically the **deployer** (and possibly **provider** if you build the agent);
+  the foundation-model vendor is the **GPAI provider**. Obligations differ per role.
+- **Risk classification (your use case decides):**
+  - **Prohibited** practices (e.g. social scoring, certain biometric categorization) — do not deploy.
+  - **High-risk** (Annex III: employment, credit, education, essential services, biometric,
+    law-enforcement, migration): triggers conformity assessment, risk management, logging, human
+    oversight, technical documentation. If your agent operates here, the **system** is high-risk.
+    Several of these duties map to Vayl's trust layer — **logging/traceability (Art. 12)** → the
+    tamper-evident audit + decision records; **human oversight (Art. 14)** → the safety gate;
+    **transparency (Art. 13)** → provenance/`explain_decision`; **accuracy (Art. 15)** →
+    reconciliation. See "Trust-layer controls" below. These *support* the obligations; they don't
+    discharge them.
+  - **Limited-risk** (a chatbot / assistant interacting with people): **transparency** — you must
+    inform users they are interacting with AI, and label AI-generated content where applicable.
+  - **Minimal-risk:** most back-office memory use — no specific AI Act obligations.
+- **GPAI obligations** sit mainly with the **model provider**. Using a **local open model** reduces
+  your exposure to third-party GPAI dependencies.
+
+The AI Act applies in phases; confirm the current applicable dates and your classification with counsel.
+
+## Trust-layer controls — provenance, safety gate, verifiable memory
+
+Beyond the data-subject-rights tooling above, Vayl implements a *trust layer* that maps directly to
+GDPR accountability/accuracy and to EU AI Act high-risk duties. These are the controls to put in front
+of a DPO evaluating **agent autonomy** — the "can we let it act, and can we prove why it did" question.
+
+| Feature | What it does | Serves |
+|---|---|---|
+| **Belief provenance** (`recall(explain=True)`) | Returns the exact facts behind an answer — value, **who asserted it** (source), confidence, what it superseded | GDPR Art. 15/22 (meaningful info about the logic); AI Act Art. 13 (transparency) |
+| **Decision audit** (`record_decision` / `explain_decision`) | Immutable, **signed** snapshot of the beliefs behind an agent action — answers "why did it do X?" even after the facts change | GDPR Art. 5(2) accountability, Art. 22 (contest a decision); AI Act Art. 12 (record-keeping) |
+| **Safety gate** (`check_before_act` / `safe_recall`) | Refuses to *act* on disputed / low-confidence / stale / superseded memory; surfaces it for a human | GDPR Art. 22 (human intervention); AI Act Art. 14 (human oversight) |
+| **Tamper-evident audit** (`verify_audit`) | Hash-chained + Ed25519-signed audit log; proves it wasn't edited, reordered, or truncated | GDPR Art. 5(1)(f) integrity, Art. 5(2); AI Act Art. 12 |
+| **Signed erasure receipts** (`delete` → `verify_receipt`) | A third-party-verifiable proof that an erasure happened | GDPR Art. 17 (demonstrate erasure) |
+| **Knowledge attestation** (`attest`) | Signed proof of what was held at a point in time | Accountability / evidentiary |
+| **Source attribution** (`remember(source=…)`) | Records which agent/person/connector asserted each fact; drives source-aware reconciliation in shared spaces | Accuracy (5(1)(d)), accountability, data provenance |
+| **Public-key verification** (`export_public_key`) | Anyone verifies receipts, attestations, and the audit chain **without the secret key or DB access** | Independent auditability |
+
+**Human oversight (Art. 22 / AI Act Art. 14) — how to wire it.** Put `check_before_act` (or
+`safe_recall`) on the path to any autonomous action with legal or significant effect. When it returns
+BLOCKED/WITHHELD, route to a human. That is a concrete, testable oversight control — not a policy
+promise — and provenance + `explain_decision` give the reviewer the "why" they need to act or contest.
+
+**Key management (Art. 32).** The encryption (Fernet) and signing (Ed25519) keys underpin these
+guarantees. Vayl supports **HashiCorp Vault Transit** envelope encryption out of the box
+(`VAYL_KMS=vault`): the master key never leaves Vault, only a *wrapped* key blob sits on the Vayl host,
+and the key is unwrapped into memory at startup — so custody moves **off the data host** (a key beside
+the DB protects against file copy, not machine theft). Self-hosted Vault keeps that custody on your own
+infrastructure, consistent with the sovereignty posture. Vayl **fails closed** if the KMS is unreachable
+(refuses to start rather than run unencrypted). The tamper-evidence and receipts are only as strong as
+the custody of the signing key — treat Vault access, and key rotation, accordingly.
+
+## Sector overlays (if applicable)
+- **Finance:** DORA (operational resilience, ICT risk).
+- **Essential / important entities:** NIS2 (security measures, incident reporting).
+- **Health:** national health-data law and the European Health Data Space.
+
+These govern your environment, not Vayl specifically.
+
+## Why Vayl fits an EU deployment
+- **Data residency:** local/on-prem + **local-LLM default → personal data stays on the machine.**
+- **Security:** **encrypted at rest** (Art. 32), authenticated, localhost-only, no telemetry.
+- **Data-subject rights, built in:** erasure, access, rectification map to concrete tools.
+- **Auditability:** the history/change-log evidences what was held and when it changed.
+
+This equips you to comply; it does not replace your legal basis, notices, DPIA, or DPO sign-off.
+
+## Evidence of implemented controls — verify each yourself
+
+Vayl does **not** self-declare compliance (that is your deployment's property, validated by your
+auditor). What it *can* prove is the **technical controls it implements** — and every one below is
+**independently verifiable** by the referenced command or automated test. This is auditor-grade
+evidence, not a claim. Run the full suite with `pytest` (151 automated tests).
+
+| Control (requirement) | What Vayl does | How to prove it |
+|---|---|---|
+| **Encryption at rest** (Art. 32) | Content columns are Fernet ciphertext on disk | Store a fact, then `strings vayl.db \| grep <the value>` → **nothing**; the raw `value` column is `gAAAAA…`. Test: `test_crypto.py::test_data_is_ciphertext_at_rest_but_plaintext_on_read` |
+| **Right to erasure** (Art. 17) | `delete` / `delete_all` hard-delete rows **incl. history and graph** | After erasure, `export_memory` returns `count: 0` and `history` is empty; `audit_log` shows a `delete(erasure)` entry. Test: `test_store.py::test_delete_hard_erases_a_subject_including_history` |
+| **Access & portability** (Art. 15/20) | `export_memory` → machine-readable JSON (statements + decisions + audit + receipts) | Call `export_memory`; output is valid JSON with every record. Test: `test_compliance.py::test_export_is_machine_readable_and_includes_history` |
+| **Rectification** (Art. 16) | `update_memory` retires the old value to history, sets the new one active | Test: `test_apply.py::test_update_is_audit_preserving` |
+| **Accountability** (Art. 5(2)) | Append-only `audit_log` records who/what/when for every data op | Do any operation, then `audit_log` shows the timestamped entry. Test: `test_compliance.py::test_audit_records_who_what_when_newest_first` |
+| **Storage limitation** (Art. 5(1)(e)) | `purge_expired(days)` hard-deletes rows older than N days | Test: `test_compliance.py::test_expire_deletes_only_old_rows` |
+| **Data residency / no egress** | Defaults to a local LLM — no data leaves the host | Boot with no LLM env → it uses local Ollama. Test: `test_config.py::test_out_of_the_box_is_local_ollama_no_egress` |
+| **Access control** | `vayl-server` requires a Bearer credential on every request; roles grant capabilities (RBAC), fail-closed | Request without / with an invalid key → `401`; a valid key binds its principal. Tests: `test_api.py::test_missing_key_is_401`, `test_invalid_or_malformed_key_is_401`, `test_valid_key_binds_the_principal_for_the_request` |
+| **Space isolation** (data minimization) | `(user_id, agent_id, run_id)` scoping | Test: `test_store.py::test_agent_spaces_are_isolated_for_the_same_user` |
+| **No telemetry** | Only outbound call is the LLM/embedder you configure | Code review — grep for network calls; there are no analytics/telemetry endpoints |
+| **Injection resistance** (Art. 32) | All SQL parameterized | Code review of `store.py`; stress-tested with injection strings |
+| **Tamper-evident audit** (Art. 5(1)(f), 5(2)) | Audit log is hash-chained + Ed25519-signed | `verify_audit` reports INTACT; edit any row → it names the broken seq. Tests: `test_audit.py::test_tampering_a_detail_breaks_the_chain`, `::test_signed_chain_verifies_and_signature_tamper_is_caught` |
+| **Proof of erasure** (Art. 17) | `delete` issues a signed, third-party-verifiable receipt | `verify_receipt` → VALID; edit any field → INVALID. Tests: `test_receipts.py::test_erasure_receipt_verifies_with_public_key_only`, `::test_editing_any_payload_field_invalidates_the_receipt` |
+| **Decision accountability** (Art. 5(2), 22) | Immutable **signed** snapshot of the beliefs behind an action | Snapshot survives later fact changes; receipt verifies. Tests: `test_decisions.py::test_snapshot_is_immutable_across_later_fact_changes`, `::test_signed_receipt_verifies_and_tamper_is_caught` |
+| **Human-oversight hook** (Art. 22 / AI Act 14) | Safety gate refuses to act on unsafe memory | `check_before_act`/`safe_recall` BLOCK on flagged/low-conf/stale. Tests: `test_safety.py::test_check_blocks_a_flagged_conflict`, `::test_safe_recall_withholds_on_low_confidence` |
+| **Belief provenance** (Art. 15/22, AI Act 13) | Recall returns the exact facts + source used to answer | Test: `test_apply.py::test_query_with_provenance_returns_exact_facts_used` |
+| **Independent verifiability** | Public key verifies receipts/attestations/chain without the secret | `export_public_key`, then `receipts.verify(receipt, public_key)` off-box → True. Test: `test_receipts.py::test_persisted_receipt_roundtrips_and_stays_verifiable` |
+
+**What this proves and what it doesn't.** It proves Vayl *implements* these controls, verifiably.
+It does **not** prove your *deployment* is compliant — that additionally requires your legal basis,
+notices, DPIA, RoPA, retention decisions, AI-Act classification, and your auditor's/DPO's sign-off
+(and, for a certification, an accredited assessor). Vayl provides the evidence; you and your auditor
+provide the compliance.
+
+## DPO / controller checklist
+
+- [ ] Establish and document a **lawful basis** for the processing.
+- [ ] Publish a **privacy notice** covering the memory processing.
+- [ ] Complete a **DPIA** (AI + personal-data processing is typically in scope).
+- [ ] Maintain **Records of Processing** (Art. 30).
+- [ ] Choose the **local/EU model** for data residency; if cloud, put a **DPA + transfer basis** in place.
+- [ ] Define a **retention schedule**; map erasure requests to `delete`/`delete_all` (not `forget`).
+- [ ] Implement the **data-subject-rights workflow** using Vayl's tools.
+- [ ] Confirm **special-category** handling (Art. 9) and **Art. 22** human oversight if relevant.
+- [ ] Put the **safety gate** (`check_before_act` / `safe_recall`) on autonomous-action paths and route BLOCKED/WITHHELD to a human (Art. 22 / AI Act Art. 14).
+- [ ] Decide the **audit/receipt retention vs. crypto-shred** policy for erased subjects (see "Erasure vs. accountability").
+- [ ] Use **`VAYL_KMS=vault`** (HashiCorp Vault Transit) for production key custody; enable rotation, keep the master key off the data host.
+- [ ] Classify the system under the **AI Act** and meet the applicable transparency/high-risk duties.
+- [ ] Keep OS **full-disk encryption** and access controls on the host (see `SECURITY.md`).
+- [ ] Have counsel/DPO **sign off** before go-live; commission a **security/pen test**.
+
+## Disclaimer
+Vayl is early-stage software, is not certified, and makes no compliance guarantee. This guide is a
+technical aid for your assessment, not a legal opinion. Determinations rest with your DPO and counsel.

vayl_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to Vayl
+
+Thanks for your interest in contributing! Bug reports, docs, tests, new LLM providers, and
+reconciliation edge cases are especially welcome.
+
+The full contributor guide — setup, the free-threaded workflow, benchmarks, and the project layout —
+lives in the README:
+
+👉 **[README → Contributing](README.md#contributing)**
+
+## TL;DR
+
+```bash
+git clone https://github.com/vayl-dev/vayl && cd vayl
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,server,postgres]"
+pytest            # 475 offline unit tests (deterministic, no LLM/network)
+ruff check .      # lint
+```
+
+## Ground rules
+
+- Keep the **core at two dependencies** (`mcp`, `cryptography`); anything heavier goes behind an
+  optional extra in `pyproject.toml`.
+- Unit tests stay **offline and deterministic** — LLM-dependent checks belong in `benchmarks/`.
+- New behaviour needs a test, and `ruff check .` must pass.
+- The audit hash-chain is a security guarantee: changes under `src/vayl/security/audit.py` need a
+  concurrency test (see `tests/test_accountability.py`).
+- For anything substantial, **open an issue first** so we can align on approach before a big PR.
+
+By contributing, you agree your contributions are licensed under **Apache-2.0**.
+
+## Reporting issues
+
+- **Bugs & feature requests:** open a [GitHub issue](https://github.com/vayl-dev/vayl/issues).
+- **Security vulnerabilities:** please do **not** open a public issue — contact the maintainer
+  privately instead. Vayl's threat model and shared-responsibility matrix are in
+  [`SECURITY.md`](SECURITY.md).

vayl_mcp-0.1.0/DEPLOY.md

@@ -0,0 +1,207 @@
+# Deploying Vayl (self-hosted)
+
+A step-by-step runbook to stand up Vayl in your own environment. Aimed at an ops/platform engineer;
+follow it top to bottom. End state: an authenticated Vayl memory server your agents connect to over
+HTTPS, running entirely on your infrastructure.
+
+> Vayl is self-hosted: your data (and, with Vault, your keys) never leave your environment. The one
+> external dependency is the **LLM** — and even that can be a model you host (Ollama / vLLM / an
+> EU-hosted endpoint), so there's no egress at all if you want none.
+
+---
+
+## 0. Prerequisites
+
+- **Docker** + **Docker Compose** on a Linux host (2 vCPU / 4 GB RAM is enough if you use a *hosted*
+  LLM; running a local model needs much more — see the LLM note below).
+- **An LLM endpoint** — either your own OpenAI-compatible API (OpenAI, Azure OpenAI, an EU-hosted
+  provider, vLLM), or Ollama running on the host. Vayl needs a chat model **and** an embedding model.
+- A **DNS name + TLS cert** for production (any reverse proxy works; a Caddy example is below).
+- (Optional) Postgres, HashiCorp Vault, an OIDC IdP, an enterprise license — all covered as options.
+
+---
+
+## 1. Get the files
+
+**If your vendor gave you an image** (the usual case): put
+`docker-compose.client.yml`, `.env.example`, and this file in a directory, then log in to the registry
+with the pull credentials you were given:
+
+```bash
+docker login ghcr.io          # (or your vendor's registry) with the credentials provided
+cp .env.example .env
+```
+Throughout this runbook, use `docker compose -f docker-compose.client.yml …` for compose commands.
+
+**If you're building from source** (vendor/internal): clone the repo and use plain `docker compose`:
+
+```bash
+git clone <vayl-repo> vayl && cd vayl
+cp .env.example .env
+```
+
+## 2. Configure — edit `.env`
+
+Open `.env`. **The LLM block is the only required part.** Pick one:
+
+**Path A — your existing LLM (recommended for production):**
+```env
+LLM_PROVIDER=openai
+OPENAI_BASE_URL=https://your-endpoint/v1     # OpenAI, Azure OpenAI, EU-hosted, vLLM…
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-5-mini                       # 0% silently-wrong on messy data; gpt-5-nano is cheaper but weaker on corrections
+EMBED_BASE_URL=https://your-endpoint/v1
+EMBED_API_KEY=sk-...
+EMBED_MODEL=text-embedding-3-small
+```
+
+**Path B — Ollama on the host (no egress; needs RAM/GPU; weaker on small models):**
+```bash
+# on the Docker host:
+ollama serve &                 # if not already running
+ollama pull qwen2.5:3b         # chat model     ollama pull nomic-embed-text   # embeddings
+```
+```env
+LLM_PROVIDER=openai
+OPENAI_BASE_URL=http://host.docker.internal:11434/v1
+OPENAI_API_KEY=ollama
+OPENAI_MODEL=qwen2.5:3b
+EMBED_BASE_URL=http://host.docker.internal:11434/v1
+EMBED_API_KEY=ollama
+EMBED_MODEL=nomic-embed-text
+```
+> **LLM quality matters.** Vayl's reconciliation is only as good as the model. A 3B local model is fine
+> for a demo but weak on hard cases; use a strong hosted model (or a larger local one) for production.
+
+Encryption (`VAYL_ENCRYPT=on`) and auth (`VAYL_AUTH_REQUIRED=1`) are on by default — leave them.
+
+## 3. Start
+
+```bash
+docker compose up -d --build
+docker compose logs -f vayl        # watch for "Uvicorn running" / "Application startup complete"
+```
+
+## 4. Bootstrap the first admin (one-off)
+
+The server requires authenticated principals. Mint the first admin and **copy the key — it's shown once**:
+
+```bash
+docker compose run --rm vayl python -c "import mcp_server as s; print(s.create_principal('admin', role='admin'))"
+```
+
+Use that admin key to create the day-to-day principals your agents/users will use (roles:
+`admin` / `member` / `agent` / `viewer` / `auditor`) — via the `create_principal` tool, or repeat the
+command above with a different name/role.
+
+## 5. Verify
+
+```bash
+curl -s localhost:8080/healthz     # {"status":"ok"}
+curl -s localhost:8080/readyz      # {"status":"ready"}   (DB reachable)
+curl -s localhost:8080/metrics     # Prometheus metrics
+
+# a real call requires the admin key and the MCP protocol; quickest smoke — auth is enforced:
+curl -s -o /dev/null -w "%{http_code}\n" -X POST localhost:8080/mcp        # → 401 (no key = rejected)
+```
+`health` (via the tool) also checks the LLM + embedder are reachable — run it once you've connected a
+client (below). If it reports `llm: FAIL`, your LLM env in `.env` is wrong.
+
+## 6. Put TLS in front (production)
+
+Do **not** expose `:8080` directly. Terminate TLS at a reverse proxy. Simplest — add Caddy to the stack:
+
+`Caddyfile`:
+```
+vayl.your-domain.com {
+    reverse_proxy vayl:8080
+}
+```
+Add to `docker-compose.yml`:
+```yaml
+  caddy:
+    image: caddy:2
+    ports: ["443:443", "80:80"]
+    volumes: ["./Caddyfile:/etc/caddy/Caddyfile", "caddy-data:/data"]
+    depends_on: [vayl]
+# and add `caddy-data:` under top-level volumes
+```
+(nginx/Traefik/your ingress work the same — proxy `https://vayl.your-domain.com` → `vayl:8080`.)
+
+## 7. Connect an agent / MCP client
+
+Vayl speaks **MCP over streamable-HTTP** at `/mcp`, Bearer-authenticated. Point any MCP client
+(Claude Desktop, Cursor, your agent framework) at it:
+
+```
+URL:    https://vayl.your-domain.com/mcp
+Header: Authorization: Bearer vayl_sk_<the principal's key>
+```
+
+The client then has the memory tools (`remember`, `recall`, `check_before_act`, …) gated by that
+principal's role.
+
+---
+
+## Options (skip any you don't need)
+
+**Postgres (scale-out / multiple server processes):**
+```bash
+# in .env:  VAYL_DATABASE_URL=postgresql://vayl:vayl@postgres:5432/vayl   (change the password!)
+docker compose --profile postgres up -d
+```
+Same-space writes serialize across processes via an advisory lock; different spaces run in parallel.
+
+**HashiCorp Vault (key custody off the host):**
+```bash
+# one-time in Vault:  vault secrets enable transit && vault write -f transit/keys/vayl
+# in .env:
+VAYL_KMS=vault
+VAULT_ADDR=https://vault.internal:8200
+VAULT_TOKEN=<a token with transit encrypt/decrypt on the vayl key>
+```
+The master key never leaves Vault; only a wrapped blob sits on the host. If Vault is unreachable, Vayl
+**fails closed** (won't start) rather than run unencrypted.
+
+**Enterprise license (raise seat cap / unlock features):** set `VAYL_VENDOR_PUBKEY` + `VAYL_LICENSE`
+in `.env` (from your vendor). Check with the `license_status` tool. Omit → Community edition.
+
+**SSO / OIDC (human login via your IdP; requires a license):** set `VAYL_OIDC_ISSUER`,
+`VAYL_OIDC_AUDIENCE`, `VAYL_OIDC_JWKS_URL`. Users then present an IdP JWT as the Bearer token; API keys
+still work alongside.
+
+**Graph recall (Neo4j):** `docker compose --profile graph up -d`, set `VAYL_GRAPH=1` + `NEO4J_*`.
+
+---
+
+## Operations
+
+- **Backups:** back up the `vayl-data` volume (SQLite DB + keys) — or your Postgres, if used. The
+  `<db>.key*` files are the *only* way to decrypt at-rest data; back them up securely (or use Vault,
+  where the master key is in Vault and only a wrapped blob is on the host).
+- **Upgrades:** `git pull && docker compose up -d --build`. Schema migrations are automatic and
+  backward-compatible.
+- **Logs & metrics:** `docker compose logs -f vayl`; scrape `/metrics` (Prometheus) from your monitoring.
+- **Rotation:** rotate principal keys with `revoke_principal` + `create_principal`. For the master key,
+  rotate in Vault (`VAYL_KMS=vault`).
+
+## Security checklist (before go-live)
+
+- [ ] TLS terminating in front; `:8080` not publicly exposed.
+- [ ] `VAYL_ENCRYPT=on` and `VAYL_AUTH_REQUIRED=1` (defaults — confirm they weren't overridden).
+- [ ] Admin key stored in your secrets manager; least-privilege roles for agents (`agent`/`member`, not `admin`).
+- [ ] For regulated/sensitive data: `VAYL_KMS=vault`, and read `COMPLIANCE.md` (GDPR / AI-Act mapping) + `SECURITY.md`.
+- [ ] Changed default Postgres/Neo4j passwords if you enabled those profiles.
+- [ ] Backups of the data volume (and keys) tested.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `remember`/`recall` error, or `health` shows `llm: FAIL` | LLM env wrong in `.env`. For Ollama-on-host, `OPENAI_BASE_URL=http://host.docker.internal:11434/v1` and the model is pulled. |
+| Every call returns **401** | No/invalid `Authorization: Bearer vayl_sk_…`. Bootstrap an admin (step 4) and use its key. |
+| Server won't start with `VAYL_KMS=vault` | Vault unreachable or the transit key missing — this is **fail-closed** by design. Fix `VAULT_ADDR`/`VAULT_TOKEN` / create the transit key. |
+| `readyz` → 503 | Database not reachable (Postgres down, or bad `VAYL_DATABASE_URL`). |
+| "Seat limit reached" on `create_principal` | Community cap hit — install an Enterprise license, or revoke an unused principal. |
+
+Questions during onboarding? That's expected for a first deploy — reach your Vayl contact.