# Repository Guidelines
## Project Structure & Module Organization
- `packages/` hosts the Node implementation:
- `packages/cli/` CLI entry + command definitions
- `packages/core/` IMAP/SMTP + storage + account migration
- `packages/shared/` path resolution + JSON contract helpers
- `packages/workflows/` digest/monitor/inbox workflows
- `mailbox-cli/` contains the npm launcher + platform binary packages.
- `scripts/` contains build helpers (notably `scripts/build_binary.js`).
- `docs/` holds CLI contract + release docs; legacy Python/MCP docs remain under `docs/archive/`.
## Build, Test, and Development Commands
- Install dependencies: `pnpm install`
- Run tests: `pnpm test`
- Build local pkg binary (and copy into `mailbox-cli` platform package): `pnpm build:binary`
- Run dev CLI: `pnpm -C packages/cli test` or `node packages/cli/bin/mailbox.js --help`
## Coding Style & Naming Conventions
- Node.js (JavaScript). Keep modules small and side-effect-light.
- Prefer explicit error objects in JSON output (`success`, `error`).
- Avoid breaking JSON contract; add fields in a forward-compatible way.
## Testing Guidelines
- Contract tests live under `packages/cli/test/` (vitest). Use `MAILBOX_TEST_MODE=1` to avoid live IMAP/SMTP.
- Prefer schema validation (`docs/cli_json_schemas/*`) to lock minimum stable JSON shapes.
## Commit & Pull Request Guidelines
- Follow the Conventional Commit style seen in history (`feat:`, `fix:`, `refactor:`); keep subjects ≤72 chars.
- Include a brief body noting user-facing changes, risks, and docs updated.
- PRs should describe context and testing performed (`pnpm test`, `pnpm build:binary`).
- Link issues or TODOs and request reviewers for affected areas (operations, services, scripts).
## Security & Configuration Tips
- Never commit secrets; keep `data/` contents (accounts, DBs, logs, attachments) local and gitignored.
- Use environment variables or `.env` for provider credentials; prefer config templates in `config_templates/` and examples in `examples/`.
- When debugging, scrub email addresses and tokens from shared logs.
