# Requirements: Flynn Operator DX

**Defined:** 2026-02-09
**Core Value:** Make Flynn easier to reason about, configure, and monitor

## v1 Requirements

Requirements for this milestone. Each maps to roadmap phases.

### Daemon Decomposition

- [x] **DECO-01**: Model client creation logic extracted from daemon/index.ts into src/daemon/models.ts with the same public interface
- [x] **DECO-02**: Channel adapter setup logic extracted into src/daemon/channels.ts
- [x] **DECO-03**: Agent cache and factory logic extracted into src/daemon/agents.ts
- [x] **DECO-04**: Memory store and vector store initialization extracted into src/daemon/memory.ts
- [x] **DECO-05**: Tool registration and policy wiring extracted into src/daemon/tools.ts
- [x] **DECO-06**: Message routing logic extracted into src/daemon/routing.ts (test file already exists)
- [x] **DECO-07**: daemon/index.ts reduced to a thin composition root that imports and wires extracted modules
- [x] **DECO-08**: All 1077+ existing tests continue to pass after decomposition

### Config Overlays

- [x] **CONF-01**: User can set FLYNN_ENV environment variable to select a config overlay (e.g., docker, production)
- [x] **CONF-02**: Config loader merges environment-specific overlay file on top of base config with deep merge
- [x] **CONF-03**: flynn doctor validates that the selected environment overlay file exists when FLYNN_ENV is set

### Live Ops Dashboard

- [x] **DASH-01**: Dashboard shows core counters: messages processed, active sessions, queue depth, daemon uptime
- [x] **DASH-02**: Dashboard shows model call metrics: per-call latency, tokens/sec throughput, error rates by provider
- [x] **DASH-03**: Dashboard shows live event stream: scrollable log of errors and events with timestamps and context
- [x] **DASH-04**: Dashboard shows active request tracking: in-flight requests, recent tool executions, active agent sessions
- [x] **DASH-05**: Gateway exposes /health endpoint returning JSON status for liveness/readiness checks

## v2 Requirements

Deferred to future milestone. Tracked but not in current roadmap.

### Observability

- **OBSV-01**: Structured JSON logging framework (pino or similar) replacing console.log
- **OBSV-02**: Request tracing with correlation IDs across channel → agent → model → tool chain
- **OBSV-03**: Prometheus-compatible metrics endpoint for external monitoring

### Config

- **CONF-04**: Deep merge semantics for overlay files (objects merge, arrays replace)
- **CONF-05**: Convention-based overlay file discovery (config/default.yaml + config/{env}.yaml)
- **CONF-06**: Hot reload of config changes without daemon restart

### Code Quality

- **QUAL-01**: ESLint configuration with @typescript-eslint/recommended
- **QUAL-02**: Reduce `as any` casts by creating proper mock factories and wrapper types
- **QUAL-03**: Test coverage for security-sensitive file tools

## Out of Scope

| Feature | Reason |
|---------|--------|
| New channel adapters | Not the focus — separate milestone |
| Agent intelligence (sub-agents, planning) | Separate milestone |
| Companion apps (macOS, iOS, Android) | Massive scope, different project |
| Skill registry / marketplace | Community feature, premature |
| Onboard wizard | Operator already knows the system |
| Multi-tenant / team features | Single-operator tool |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| DECO-01 | Phase 1 | Complete |
| DECO-02 | Phase 1 | Complete |
| DECO-03 | Phase 1 | Complete |
| DECO-04 | Phase 1 | Complete |
| DECO-05 | Phase 1 | Complete |
| DECO-06 | Phase 1 | Complete |
| DECO-07 | Phase 1 | Complete |
| DECO-08 | Phase 1 | Complete |
| CONF-01 | Phase 2 | Complete |
| CONF-02 | Phase 2 | Complete |
| CONF-03 | Phase 2 | Complete |
| DASH-01 | Phase 3 | Complete |
| DASH-02 | Phase 3 | Complete |
| DASH-03 | Phase 3 | Complete |
| DASH-04 | Phase 3 | Complete |
| DASH-05 | Phase 3 | Complete |

**Coverage:**
- v1 requirements: 16 total
- Mapped to phases: 16
- Unmapped: 0

---
*Requirements defined: 2026-02-09*
*Last updated: 2026-02-13 after Phase 3 completion*