HEY

Build me an email client with HEY's screening and bundling ideas, running on
top of a mailbox I already pay for (Fastmail, Gmail, anything with IMAP).
Requirements:

- A local web app: Node + Express + better-sqlite3, binds to localhost;
  imapflow for reading, nodemailer for sending, creds in .env.
- The screener: mail from first-time senders lands in a screening view where I
  approve or block; decisions persist in SQLite and apply to all future mail.
- Bundles: approved senders get a category; newsletters render in a batched
  feed view, receipts in a paper-trail list; only approved humans hit the
  inbox.
- Reply-later: mark a thread and it sits in a persistent to-answer stack until
  cleared.
- Write decisions back as IMAP folders and labels so my phone's mail app
  roughly mirrors the sorting.
- Strip remote images in the reading pane by default.
- No accounts of its own, no telemetry; mail stays at my provider.
- Out of scope: running an SMTP server, custom domains, and mobile apps. Do not
  replace the mail service itself; deliverability and spam reputation are the
  product and cannot be rebuilt solo.
- README: per-provider app-password setup, and a warning that Gmail OAuth is a
  project of its own, use an app password or Fastmail to keep this a weekend.

# AGENTS.md — Build guide for HEY

## Project scope
Build a personal mail client on top of IMAP/SMTP or a hosted mailbox; do not try to replace the global email service layer casually.

Catalogue verdict: no. You can build an email client, but replacing HEY means running a trustworthy email service: deliverability, spam filtering, abuse handling, storage, mobile apps, and reputation.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- existing email provider or mailbox
- IMAP/SMTP APIs
- spam filtering if hosting
- domain/DNS if custom email

## Stack and architecture
- A local web app: Node + Express + better-sqlite3, binds to localhost; imapflow for reading, nodemailer for sending, creds in .env.
- The screener: mail from first-time senders lands in a screening view where I approve or block; decisions persist in SQLite and apply to all future mail.
- Interface for this consumer email service workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Record delivery failures and retries by message ID; never duplicate a send after restart.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: email deliverability.

## Agent implementation rules
- Project rule, data: The screener: mail from first-time senders lands in a screening view where I approve or block; decisions persist in SQLite and apply to all future mail.
- Project rule, behavior: Bundles: approved senders get a category; newsletters render in a batched feed view, receipts in a paper-trail list; only approved humans hit the inbox.
- Project rule, recovery: Record delivery failures and retries by message ID; never duplicate a send after restart.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this consumer email service operation with sample or user-owned data: Bundles: approved senders get a category; newsletters render in a batched feed view, receipts in a paper-trail list; only approved humans hit the inbox.
- Show a concrete result or export: Reply-later: mark a thread and it sits in a persistent to-answer stack until cleared.
- State the practical limit: email deliverability.

## Engineering roadmap
1. Phase 1, architecture and data: A local web app: Node + Express + better-sqlite3, binds to localhost; imapflow for reading, nodemailer for sending, creds in .env. The screener: mail from first-time senders lands in a screening view where I approve or block; decisions persist in SQLite and apply to all future mail.
2. Phase 2, implement: Bundles: approved senders get a category; newsletters render in a batched feed view, receipts in a paper-trail list; only approved humans hit the inbox.
3. Phase 3, implement: Reply-later: mark a thread and it sits in a persistent to-answer stack until cleared.
4. Phase 4, review and output: Build a personal mail client on top of IMAP/SMTP or a hosted mailbox; do not try to replace the global email service layer casually. Reply-later: mark a thread and it sits in a persistent to-answer stack until cleared.
5. Phase 5, recovery and acceptance: Record delivery failures and retries by message ID; never duplicate a send after restart. Verify this invariant with a saved fixture: A reconnect must not duplicate mail; after an ambiguous send response, retain pending status until the provider confirms it. State the practical limit: email deliverability.

## Paid-product capabilities outside this build
- email deliverability
- spam/abuse systems
- storage reliability
- mobile apps
- identity/reputation
- support

## Implementation prompt
Build me an email client with HEY's screening and bundling ideas, running on
top of a mailbox I already pay for (Fastmail, Gmail, anything with IMAP).
Requirements:

- A local web app: Node + Express + better-sqlite3, binds to localhost;
  imapflow for reading, nodemailer for sending, creds in .env.
- The screener: mail from first-time senders lands in a screening view where I
  approve or block; decisions persist in SQLite and apply to all future mail.
- Bundles: approved senders get a category; newsletters render in a batched
  feed view, receipts in a paper-trail list; only approved humans hit the
  inbox.
- Reply-later: mark a thread and it sits in a persistent to-answer stack until
  cleared.
- Write decisions back as IMAP folders and labels so my phone's mail app
  roughly mirrors the sorting.
- Strip remote images in the reading pane by default.
- No accounts of its own, no telemetry; mail stays at my provider.
- Out of scope: running an SMTP server, custom domains, and mobile apps. Do not
  replace the mail service itself; deliverability and spam reputation are the
  product and cannot be rebuilt solo.
- README: per-provider app-password setup, and a warning that Gmail OAuth is a
  project of its own, use an app password or Fastmail to keep this a weekend.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.