Release & Developer Experience

[ggondim]

Summary

Polish for public release: packaging, deployment, observability, and documentation.

Tasks

Packaging & Deployment

• Docker image published to GHCR
• docker compose production profile
• Helm chart for Kubernetes deployment
• npx create-openthreads or bun create openthreads scaffold

Observability

• Structured JSON logging (configurable log level)
• Metrics endpoint (Prometheus-compatible): messages in/out, active threads, response latency, A2H intent counts
• OpenTelemetry traces for request flows (inbound → route → outbound → reply)

Documentation

• API reference (OpenAPI spec auto-generated from routes)
• Channel setup guides (per platform)
• Self-hosting guide (Docker, env vars, MongoDB setup)
• Custom adapter authoring guide (ChannelAdapter interface)
• Custom storage adapter guide (StorageAdapter interface)

Examples

• Example: n8n integration (webhook consumer)
• Example: LangGraph integration
• Example: plain HTTP webhook consumer (curl-level)

A2H Layer 2 Preparation

• Stub types for Layer 2 intents: POLICY, REVOKE, DELEGATE, SCOPE
• Extension point in Reply Engine for future intent handlers
• Monitor twilio-labs/a2h-spec for Layer 2 stabilization

Acceptance Criteria

• docker compose up starts a fully working OpenThreads instance
• Helm chart deploys to a Kubernetes cluster
• OpenAPI spec is auto-generated and accessible at /api/docs
• All example integrations work end-to-end
• Prometheus metrics endpoint returns meaningful data

Dependencies

• Integration Testing & Hardening #15 (Integration Testing & Hardening) — release after testing is solid

References

• PLAN.md — Phase 7

[claude]

@claude Implement this issue.

• Base branch: meta/17
• Target your PR to meta/17
• Include fixes #16 in the PR body

[claude]

Claude finished @claude[bot]'s task in 11m 5s —— View job • claude/17-issue-16-20260410-2355 • Create PR ➔

---

Implementing Issue #16: Release & Developer Experience

• Read CLAUDE.md and explore codebase structure
• Understand existing code
• Packaging & Deployment
  • Dockerfile for OpenThreads server (multi-stage Bun build)
  • docker-compose.yml production profile (--profile production starts app + MongoDB)
  • Helm chart scaffold (deploy/helm/openthreads/ — deployment, service, ingress, HPA, secret)
  • create-openthreads scaffold (packages/create-openthreads/, bunx create-openthreads <name>)
• Observability
  • Structured JSON logger with configurable LOG_LEVEL + LOG_FORMAT env vars
  • Prometheus metrics endpoint (GET /api/metrics) with counters for messages in/out, A2H intents, fanout, HTTP requests
  • OpenTelemetry tracing in instrumentation.ts (enabled via OTEL_EXPORTER_OTLP_ENDPOINT)
• A2H Layer 2 Preparation
  • Stub types for POLICY, REVOKE, DELEGATE, SCOPE + isLayer1Intent()/isLayer2Intent() guards
  • IntentHandlerRegistry extension point (reply-engine/intent-handler.ts)
• Documentation (docs/self-hosting.md, docs/adapter-authoring.md, docs/channels/slack.md, docs/channels/telegram.md)
• Examples (examples/plain-http/, examples/n8n/, examples/langgraph/)
• Committed and pushed