diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..045d6ce
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,293 @@
+# Poimen Application Deployment
+
+## Overview
+
+Poimen is a unified application consisting of three services:
+- **poimen-memory**: Memory/Graph RAG service
+- **poimen-workflows**: Temporal orchestration + API
+- **poimen-frontend**: Next.js frontend
+
+All services are deployed together as a single application in the `poimen` namespace.
+
+## Local Development
+
+### Prerequisites
+- Docker
+- Docker Compose
+- Node.js 18+
+- Go 1.21+
+- Python 3.11+
+
+### Start Local Stack
+
+```bash
+docker-compose up -d
+```
+
+This starts:
+- PostgreSQL (memory + workflows DBs)
+- Redis (cache)
+- Temporal (workflow orchestration)
+- poimen-memory (8000)
+- poimen-workflows (8080)
+- poimen-workflows-worker
+- poimen-frontend (3000)
+
+### Access Services
+
+- Frontend: http://localhost:3000
+- Workflows API: http://localhost:8080
+- Memory API: http://localhost:8000
+- Temporal UI: http://localhost:8233
+
+### Stop Stack
+
+```bash
+docker-compose down
+```
+
+## Building & Pushing Images
+
+### Build All Services
+
+```bash
+./build-push.sh latest
+```
+
+Or specific services:
+
+```bash
+docker build -t forgejo.riotpiao.com/rock/poimen-memory:v1.0.0 ./memory
+docker push forgejo.riotpiao.com/rock/poimen-memory:v1.0.0
+```
+
+### Image Tagging Strategy
+
+- `latest`: Development/staging
+- `v1.0.0`, `v1.0.1`, etc.: Production releases
+- `main-{commit-hash}`: CI/CD automated builds
+
+## Kubernetes Deployment
+
+### Prerequisites
+
+- Kubernetes cluster (1.24+)
+- kubectl configured
+- Kustomize installed
+- Registry credentials configured
+
+### Deploy to Cluster
+
+```bash
+cd k8s
+./deploy.sh -a
+```
+
+Or with specific tags:
+
+```bash
+./deploy.sh -m v1.0.0 -w v1.0.0 -f v1.0.0
+```
+
+### Verify Deployment
+
+```bash
+kubectl get pods -n poimen
+kubectl get svc -n poimen
+kubectl logs -n poimen -l app=poimen-workflows
+```
+
+## Configuration
+
+### Environment Variables
+
+Configure in `k8s/poimen-application.yaml` under `spec.template.spec.env`:
+
+**Common:**
+- `TEMPORAL_HOST`: Temporal server (default: temporal:7233)
+- `DATABASE_URL`: PostgreSQL connection
+- `JWT_SECRET`: JWT signing key
+- `LOG_LEVEL`: debug|info|warn|error
+
+**Memory Service:**
+- `REDIS_URL`: Redis connection
+- `ELASTICSEARCH_URL`: Optional full-text search
+
+**Workflows Service:**
+- `MEMORY_SERVICE_URL`: Internal memory service URL
+
+**Frontend:**
+- `NEXT_PUBLIC_WORKFLOWS_API`: External workflows API
+- `NEXT_PUBLIC_MEMORY_API`: External memory API
+- `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`: Auth provider
+
+### Secrets
+
+Create secrets before deployment:
+
+```bash
+kubectl create secret generic poimen-db-credentials \
+  --from-literal=memory-url="postgresql://..." \
+  --from-literal=workflows-url="postgresql://..." \
+  -n poimen
+
+kubectl create secret generic poimen-secrets \
+  --from-literal=jwt-secret="..." \
+  --from-literal=oauth-client-id="..." \
+  --from-literal=oauth-client-secret="..." \
+  -n poimen
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│             LoadBalancer Service            │
+│          poimen-frontend:80→3000            │
+└─────────────────┬───────────────────────────┘
+                  │
+          ┌───────┴────────┐
+          ▼                ▼
+   ┌──────────────┐  ┌──────────────┐
+   │   Frontend   │  │  Workflows   │
+   │   (3000)     │  │   API (8080) │
+   │   2 replicas │  │  2 replicas  │
+   └──────────────┘  └──────┬───────┘
+          │                 │
+          │           ┌─────┴─────┐
+          │           ▼           ▼
+          │      ┌─────────────────────┐
+          │      │  Temporal Cluster   │
+          │      │  (External)         │
+          │      └─────────────────────┘
+          │
+          └──────────────────┬──────────────┐
+                             ▼              ▼
+                    ┌──────────────┐  ┌──────────────┐
+                    │   Memory     │  │  PostgreSQL  │
+                    │  (8000)      │  │  (5432)      │
+                    │  1 replica   │  │              │
+                    └──────────────┘  └──────────────┘
+```
+
+## Scaling
+
+### Horizontal Scaling
+
+Adjust replicas in `k8s/poimen-application.yaml`:
+
+```yaml
+spec:
+  replicas: 3  # Increase this
+```
+
+Or patch:
+
+```bash
+kubectl patch deployment poimen-workflows -p '{"spec":{"replicas":3}}' -n poimen
+```
+
+### Resource Requests/Limits
+
+Add to container spec:
+
+```yaml
+resources:
+  requests:
+    cpu: 100m
+    memory: 256Mi
+  limits:
+    cpu: 500m
+    memory: 512Mi
+```
+
+## Monitoring & Logging
+
+### Check Status
+
+```bash
+kubectl get pods -n poimen -w
+kubectl describe pod <pod-name> -n poimen
+kubectl logs -n poimen -f -l app=poimen-workflows --all-containers=true
+```
+
+### Health Checks
+
+All services expose `/health` endpoint:
+
+```bash
+curl http://poimen-workflows:8080/health
+curl http://poimen-memory:8000/health
+curl http://poimen-frontend:3000/
+```
+
+## Updates & Rollbacks
+
+### Rolling Update
+
+```bash
+./deploy.sh -w v1.0.1
+```
+
+Kubernetes automatically rolls out with health checks.
+
+### View Rollout Status
+
+```bash
+kubectl rollout status deploy/poimen-workflows -n poimen
+```
+
+### Rollback
+
+```bash
+kubectl rollout undo deploy/poimen-workflows -n poimen
+```
+
+## Troubleshooting
+
+### Services Can't Connect
+
+Check service DNS:
+```bash
+kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup poimen-workflows
+```
+
+### Database Migrations Failing
+
+```bash
+kubectl exec -it <workflows-pod> -n poimen -- \
+  ./workflows migrate up
+```
+
+### Temporal Worker Not Picking Up Activities
+
+Check worker logs:
+```bash
+kubectl logs -n poimen -l app=poimen-workflows --all-containers=true | grep -i activity
+```
+
+Verify activities registered in `cmd/worker/main.go`
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Build & Push Poimen
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build & Push
+        run: ./build-push.sh main-${{ github.sha }}
+```
+
+### Automatic Deployment
+
+Configure ArgoCD to watch `k8s/` directory for updates.