docs: add deployment guides, compose files, and agent instruction docs

Author: Thomas Tupper

.cursor/rules/foxmemory-deploy.mdc

@@ -0,0 +1,10 @@
+---
+description: Rules for Cursor in foxmemory-deploy
+globs:
+  - "*.yml"
+  - "docs/**/*.md"
+alwaysApply: true
+---
+- Keep deployment instructions reproducible and explicit.
+- Keep compose.one.yml and compose.split.yml coherent.
+- Never introduce plaintext secrets.

.env.example

@@ -0,0 +1,3 @@
+# Copy to .env and customize
+FOXMEMORY_INFER_IMAGE=ghcr.io/foxlight-foundation/foxmemory-infer:latest
+FOXMEMORY_STORE_IMAGE=ghcr.io/foxlight-foundation/foxmemory-store:latest

.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+# GitHub Copilot Instructions
+
+This repo packages deployment topology.
+- Favor explicit compose config over magic.
+- Keep commands copy/paste safe.
+- Update docs whenever compose behavior changes.

AGENTS.md

@@ -0,0 +1,11 @@
+# Agent Instructions (foxmemory-deploy)
+
+## Priority
+1. Keep deployment examples reproducible.
+2. Keep one-node and split modes both functional.
+3. Document all env vars and defaults.
+
+## Rules
+- Never hardcode private credentials.
+- Keep compose files minimal and explicit.
+- Update README + runbook when topology changes.

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+- Read `AGENTS.md` first.
+- Validate compose syntax before committing.
+- Keep docs aligned with actual files/commands.

CODEX.md

@@ -0,0 +1,5 @@
+# CODEX.md
+
+- Preserve reproducible deployment commands.
+- Keep one-node and split compose files in sync with docs.
+- Avoid hidden assumptions about host paths/secrets.

README.md

@@ -1,7 +1,34 @@
 # foxmemory-deploy
 
-Initial scaffold for Foxlight Foundation memory infrastructure.
+Deployment pack for FoxMemory services.
 
-## Status
+## Why this exists
+This repo makes FoxMemory reproducible for others: one-command local deploy, clear environment config, and documented deployment topologies.
 
-Scaffolded v0.
+## Deployment modes
+1. **One-node mode** (`compose.one.yml`)
+   - infer + store together on one host
+2. **Split mode** (`compose.split.yml`)
+   - infer and store independently deployable
+
+## Quick start
+```bash
+cp .env.example .env
+docker compose -f compose.one.yml up -d
+```
+
+Then verify:
+```bash
+curl -s http://localhost:8081/health
+curl -s http://localhost:8082/health
+```
+
+## Files
+- `compose.one.yml`
+- `compose.split.yml`
+- `.env.example`
+- `docs/RUNBOOK.md`
+
+## Notes
+- Current images default to GHCR references.
+- Can be switched to Docker Hub tags once registry workflow is updated.

compose.one.yml

@@ -0,0 +1,13 @@
+services:
+  infer:
+    image: ghcr.io/foxlight-foundation/foxmemory-infer:latest
+    container_name: foxmemory-infer
+    ports:
+      - "8081:8081"
+  store:
+    image: ghcr.io/foxlight-foundation/foxmemory-store:latest
+    container_name: foxmemory-store
+    ports:
+      - "8082:8082"
+    depends_on:
+      - infer

compose.split.yml

@@ -0,0 +1,12 @@
+services:
+  infer:
+    image: ghcr.io/foxlight-foundation/foxmemory-infer:latest
+    ports:
+      - "8081:8081"
+
+  store:
+    image: ghcr.io/foxlight-foundation/foxmemory-store:latest
+    ports:
+      - "8082:8082"
+    environment:
+      - FOXMEMORY_INFER_URL=http://infer:8081

docs/RUNBOOK.md

@@ -0,0 +1,21 @@
+# Runbook
+
+## Start
+```bash
+docker compose -f compose.one.yml up -d
+```
+
+## Stop
+```bash
+docker compose -f compose.one.yml down
+```
+
+## Health checks
+```bash
+curl -s http://localhost:8081/health
+curl -s http://localhost:8082/health
+```
+
+## Troubleshooting
+- image pull errors: verify registry auth/tag
+- service unavailable: inspect `docker compose logs`