# Warmbox Documentation

Planning artifacts for evolving Warmbox from a barebone MVP into a production-grade cold email warmup platform and eventual SaaS.

## Decisions (confirmed)

| Decision | Choice |
|----------|--------|
| Deployment | **Hybrid** — self-hosted + web UI first; architecture ready for multi-tenant SaaS later |
| Satellite pool | **Own satellites first**; optional shared peer network in a later phase |
| Warmup duration | **30–45 days** recommended default |
| Reply rate default | **30%** (max recommended **45%**) |
| Daily volume | Min **1**, default max **40**, hard cap **50** |

## Document index

| # | Document | Purpose |
|---|----------|---------|
| 00 | [Product Brief](./00-product-brief.md) | Vision, personas, success metrics |
| 01 | [Current State & Gaps](./01-current-state-and-gaps.md) | MVP inventory vs target |
| 02 | [Glossary](./02-glossary.md) | Domain language |
| 03 | [Domain Model](./03-domain-model.md) | Future entities & relationships |
| 04 | [Warmup Recipes](./04-warmup-recipes.md) | Grow, Flat, Randomized, Custom specs |
| 05 | [Primary & Satellite Topology](./05-primary-satellite-topology.md) | Multi-primary warmup design |
| 06 | [Scheduling & Timing](./06-scheduling-and-timing.md) | Duration, windows, jitter |
| 07 | [Reply Rate Engine](./07-reply-rate-engine.md) | Probabilistic replies |
| 08 | [Spam Rescue](./08-spam-rescue-and-placement.md) | Rescue, placement tracking |
| 09 | [AI Content Policy](./09-ai-content-policy.md) | Safe B2B content rules |
| 10 | [Statistics & Reporting](./10-statistics-and-reporting.md) | Metrics & dashboards |
| 11 | [ESP Compliance Playbook](./11-esp-compliance-playbook.md) | Anti-detection, DNS, policies |
| 12 | [Architecture](./12-architecture.md) | System design (hybrid → SaaS) |
| 13 | [API Evolution](./13-api-evolution.md) | REST roadmap |
| 14 | [Frontend UX Spec](./14-frontend-ux-spec.md) | Web UI screens & flows |
| 15 | [Security & Compliance](./15-security-and-compliance.md) | Credentials, privacy, legal |
| 16 | [Roadmap](./16-roadmap.md) | Phased delivery plan |
| 17 | [Agile Epics & Backlog](./17-agile-epics-backlog.md) | Epics, stories, integrations |
| 18 | [Open Questions](./18-open-questions.md) | Unresolved decisions |
| 19 | [Risk Register](./19-risk-register.md) | Risks & mitigations |

## How to use these docs

1. **Product** — Start with `00`, `16`, `17` for prioritization.
2. **Engineering** — Use `03`–`13` as implementation specs per integration.
3. **Each sprint** — Pick one epic from `17`, cross-reference the relevant spec doc, update `18` when decisions are made.

## Agile workflow (recommended)

```
Epic (17) → Technical spec (03–13) → Implementation PR → Stats/metrics validation (10)
```

Sprints should ship **vertical slices** (e.g. "Primary inbox + Grow recipe + daily stats") rather than horizontal layers only.