# 🛠️ Development

Working on `mail-intake` itself.

---

## 📂 Repository layout

| Path | Purpose |
|---|---|
| `mail_intake/` | The library package (adapters, auth, credentials, parsers, ingestion, models) |
| `mail_intake/*.pyi` | Type stubs kept in sync with implementations |
| `tests/` | Unit and integration tests (mock transports, no live mail) |
| `docs/lib/` | Generated library reference (docforge, flat layout) |
| `docs/mcp/` | Machine-readable bundle served by the MCP server |
| `docs/wiki/` | This hand-written wiki |

---

## 🔧 Setup

```bash
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
```

> OAuth credential files (`credentials*.json`, `token.pickle`,
> `client_secret_*.json`) are gitignored — keep them out of the repository.

---

## 🧪 Tests

Run the suite (no network or live Gmail required):

```bash
.venv/Scripts/pytest
```

Coverage spans ingestion flows, credential stores, parsers, and auth against
mock providers.

---

## ✅ Quality gates

The CI quality gate runs, matching the Drone pipeline:

```bash
.venv/Scripts/black --check .
.venv/Scripts/ruff check .
.venv/Scripts/mypy
.venv/Scripts/pytest
```

---

## 📝 Building documentation (docforge)

The site is generated by [`docforge`](https://git.aetoskia.com/aetos/doc-forge)
and served per kind under `site/{kind}`:

```bash
doc-forge build \
  --mkdocs --mcp --wiki \
  --module-is-source --module mail_intake \
  --site-name "Mail Intake"
```

- `--module-is-source` renders the flat `docs/lib/` layout (no nesting under
  `mail_intake/`), matching `docforge.nav.yml` and `docs/mkdocs.lib.yml`.
- `--mcp` regenerates the structured bundle in `docs/mcp/`.
- `--wiki` builds this wiki.

Preview locally:

```bash
doc-forge serve --lib
doc-forge serve --wiki
doc-forge serve --mcp
```

---

## 📚 Read Next

- [Extending Mail Intake](03_extending.md) — custom adapters and stores.
- [Overview](01_overview.md) — the core architecture.