Refactor code structure for improved readability and maintainability

docs/openviking_adapter_config.md

@@ -0,0 +1,93 @@
+# OpenViking Adapter Config
+
+## Overview
+
+Memory Gateway v2 keeps the OpenViking ingest adapter in `offline` / `skeleton`
+mode by default. In the default configuration it does not send any HTTP
+requests.
+
+## Modes
+
+### Offline
+
+`mode: offline`
+
+The adapter must not touch the network. It returns fixture-backed normalized
+results through the existing skeleton path.
+
+### Skeleton
+
+`mode: skeleton`
+
+This behaves like `offline` for now. It keeps the same normalized result path
+without sending HTTP requests.
+
+### Real
+
+Real mode is enabled only when:
+
+- `mode: real`
+
+When real mode is active, the adapter may send an HTTP request for OpenViking
+ingest only. Commit and retrieve remain offline/skeleton in the current phase.
+The legacy `enabled` field is retained for config compatibility, but it does
+not open the network path by itself.
+
+## Config Fields
+
+- `base_url`
+  The OpenViking API base URL.
+- `api_key`
+  Token used only for request headers.
+- `timeout`
+  Request timeout in seconds.
+- `verify_ssl`
+  TLS verification toggle for the real HTTP path.
+- `ingest_path`
+  Configurable ingest endpoint path template. The current placeholder is
+  `/api/v1/sessions/{session_id}/messages`.
+
+## Example Config
+
+### Offline Example
+
+```yaml
+openviking:
+  enabled: false
+  mode: offline
+  url: http://localhost:1933
+  timeout: 30
+  verify_ssl: true
+```
+
+### Real Example
+
+```yaml
+openviking:
+  enabled: false
+  mode: real
+  url: https://openviking.example.internal
+  api_key: YOUR_OPENVIKING_TOKEN
+  timeout: 30
+  verify_ssl: true
+  ingest_path: /api/v1/sessions/{session_id}/messages
+```
+
+## Security
+
+Runtime ingest requests may temporarily include `content` while the current
+request is in flight. Memory Gateway does not persist `content`,
+`raw_request`, `messages`, or `transcript` into SQLite metadata, outbox
+payloads, or audit summaries.
+
+`api_key` / tokens are used only in request headers. They do not belong in:
+
+- adapter result metadata
+- audit summaries
+- persisted MemoryRef metadata
+- error messages
+
+## Notes
+
+The current ingest endpoint path is still a configurable placeholder. It should
+be calibrated once the real OpenViking API contract is stable.