Document ecosystem state and integration contract

docs/openclaw-integration-contract.md

@@ -0,0 +1,102 @@
+# OpenClaw Integration Contract
+
+## Purpose
+
+This document defines the first safe integration contract between OpenClaw and
+AtoCore.
+
+The goal is to let OpenClaw consume AtoCore as an external context service
+without degrading OpenClaw's existing baseline behavior.
+
+## Integration Principles
+
+- OpenClaw remains the runtime and orchestration layer
+- AtoCore remains the context enrichment layer
+- AtoCore is optional at runtime
+- if AtoCore is unavailable, OpenClaw must continue operating normally
+- initial integration is read-only
+- OpenClaw should not automatically write memories, project state, or ingestion
+  updates during the first integration batch
+
+## First Safe Responsibilities
+
+OpenClaw may use AtoCore for:
+
+- health and readiness checks
+- context building for contextual prompts
+- retrieval/query support
+- project-state lookup when a project is detected
+
+OpenClaw should not yet use AtoCore for:
+
+- automatic memory write-back
+- automatic reflection
+- conflict resolution decisions
+- replacing OpenClaw's own memory system
+
+## First API Surface
+
+OpenClaw should treat these as the initial contract:
+
+- `GET /health`
+  - check service readiness
+- `GET /sources`
+  - inspect source registration state
+- `POST /context/build`
+  - ask AtoCore for a budgeted context pack
+- `POST /query`
+  - use retrieval when useful
+
+Additional project-state inspection can be added if needed, but the first
+integration should stay small and resilient.
+
+## Failure Behavior
+
+OpenClaw must treat AtoCore as additive.
+
+If AtoCore times out, returns an error, or is unavailable:
+
+- OpenClaw should continue with its own normal baseline behavior
+- no hard dependency should block the user's run
+- no partially written AtoCore state should be assumed
+
+## Suggested OpenClaw Configuration
+
+OpenClaw should eventually expose configuration like:
+
+- `ATOCORE_ENABLED`
+- `ATOCORE_BASE_URL`
+- `ATOCORE_TIMEOUT_MS`
+- `ATOCORE_FAIL_OPEN`
+
+Recommended first behavior:
+
+- enabled only when configured
+- low timeout
+- fail open by default
+- no writeback enabled
+
+## Suggested Usage Pattern
+
+1. OpenClaw receives a user request
+2. OpenClaw decides whether the request is contextual enough to query AtoCore
+3. If yes, OpenClaw calls AtoCore
+4. If AtoCore returns usable context, OpenClaw includes it
+5. If AtoCore fails or returns nothing useful, OpenClaw proceeds normally
+
+## Deferred Work
+
+- memory promotion rules
+- identity and preference write flows
+- reflection loop
+- automatic ingestion requests from OpenClaw
+- write-back policy
+- conflict-resolution integration
+
+## Precondition Before Wider Ingestion
+
+Before bulk ingestion of projects or ecosystem notes:
+
+- the AtoCore service should be reachable from the T420
+- the OpenClaw failure fallback path should be confirmed
+- the initial contract should be documented and stable