Kilbas · Kilbas · May 1, 2026 · May 1, 2026
diff --git a/docs/ai/SESSION_HANDOFF.md b/docs/ai/SESSION_HANDOFF.md
@@ -0,0 +1,91 @@
+# Session Handoff
+
+**Last updated:** 2026-05-01
+
+This file is updated at the end of every session. It is the single source of truth for "where are we right now."
+
+---
+
+## Current Branch
+
+`claude/install-superpowers-plugin-XIYZI`
+
+---
+
+## Phase 1 Status: Complete
+
+Phase 1 (Foundation) is fully implemented. The codebase has:
+
+- Next.js 15 App Router application at `apps/web/`
+- PostgreSQL schema via Prisma (workspaces, users, contacts, invitations, import_batches, audit_events, auth_sessions)
+- Auth.js v5 with Credentials provider + Argon2id passwords
+- Role-based access control (owner / admin / member)
+- Excel import with deduplication and 4-bucket report
+- Agent-flag toggle with cross-user conflict detection (SELECT FOR UPDATE)
+- Audit log (append-only, admin/owner visibility)
+- Docker Compose production deployment (app + db)
+- CI: GitHub Actions (lint, typecheck, unit tests, e2e tests)
+
+Spec: `docs/superpowers/specs/2026-04-28-influenceflow-phase-1-design.md`
+Plan: `docs/superpowers/plans/2026-04-28-influenceflow-phase-1.md`
+
+---
+
+## Phase 2 Status: Planned, Not Started
+
+Phase 2 (Bulk email engine) is fully designed but not yet implemented.
+
+All design decisions are recorded in `docs/product/PHASE_2_PRODUCT_DECISIONS.md`.
+
+**Summary of what Phase 2 adds:**
+- Brief model (campaign configuration)
+- Contact buckets (cold → first_sent → replied → etc.)
+- LLM-generated first emails with review queue
+- Bulk send with BullMQ + Redis worker
+- Per-member SMTP configuration
+- Tracking pixel (workspace-level toggle)
+- Rate limiting (default 50 emails/day/member, configurable per workspace)
+
+Spec: `docs/superpowers/specs/2026-04-30-influenceflow-phase-2-design.md` *(to be created)*
+Plan: `docs/superpowers/plans/2026-04-30-influenceflow-phase-2.md` *(to be created)*
+
+---
+
+## What Was Done in the Last Session (2026-05-01)
+
+- Created session orientation documentation:
+  - `docs/ai/START_HERE.md`
+  - `docs/ai/TASK_RUNBOOK.md`
+  - `docs/ai/SESSION_HANDOFF.md` (this file)
+  - `docs/product/PRODUCT_VISION.md`
+  - `docs/product/PHASES.md`
+  - `docs/product/PHASE_2_PRODUCT_DECISIONS.md`
+
+No application code was changed.
+
+---
+
+## What Should Be Done Next
+
+1. Create the Phase 2 spec: `docs/superpowers/specs/2026-04-30-influenceflow-phase-2-design.md`
+2. Create the Phase 2 implementation plan: `docs/superpowers/plans/2026-04-30-influenceflow-phase-2.md`
+3. Start Phase 2 implementation (see `docs/product/PHASE_2_PRODUCT_DECISIONS.md` for all decisions).
+
+**Suggested Phase 2 implementation order:**
+1. Add Redis + BullMQ to Docker Compose and `apps/worker/` scaffold
+2. Prisma schema additions (briefs, contact_buckets, email_jobs, smtp_configs)
+3. Contact bucket state machine
+4. Brief CRUD UI (admin/owner)
+5. LLM email generation with retry logic
+6. Review queue UI (edit + inline AI refinement)
+7. Bulk send worker with rate limiting
+8. Tracking pixel
+9. SMTP per-member configuration UI
+
+---
+
+## Known Issues / Gotchas
+
+- Phase 2 design decisions are finalized (see `docs/product/PHASE_2_PRODUCT_DECISIONS.md`) — do not redesign without explicit user approval.
+- The `apps/web/` layout anticipates `apps/worker/` in Phase 2 but no monorepo tooling is added yet.
+- Contact bucket transitions have strict rules (see `docs/product/PHASE_2_PRODUCT_DECISIONS.md`) — the import flow, the send worker, and the UI all need to respect them.
diff --git a/docs/ai/START_HERE.md b/docs/ai/START_HERE.md
@@ -0,0 +1,108 @@
+# START HERE — New Session Orientation
+
+**Read this first. It takes 2 minutes and replaces 30 minutes of codebase spelunking.**
+
+---
+
+## What is InfluenceFlow?
+
+Self-hosted, single-tenant CRM for blogger outreach. A marketing team uses it to manage contacts (bloggers), send outreach emails, and eventually run an autonomous LLM negotiation agent. One Docker Compose command deploys it.
+
+Single repo, single database, one deployment — phases stack on top of each other.
+
+---
+
+## Current Status
+
+| Phase | Status |
+|---|---|
+| Phase 1 — Foundation (contacts, import, auth, team, audit log) | **Complete** |
+| Phase 2 — Bulk email engine (briefs, outbound SMTP, LLM first emails, review queue, buckets) | **Planned, not started** |
+| Phase 3+ | Future |
+
+---
+
+## Key Documents
+
+| Document | Purpose |
+|---|---|
+| `docs/ai/TASK_RUNBOOK.md` | How to pick up a task and work on it |
+| `docs/ai/SESSION_HANDOFF.md` | What the last session did; what's next |
+| `docs/product/PRODUCT_VISION.md` | Full product vision and goals |
+| `docs/product/PHASES.md` | Per-phase scope and status |
+| `docs/product/PHASE_2_PRODUCT_DECISIONS.md` | All Phase 2 design decisions (read before implementing) |
+| `docs/superpowers/specs/2026-04-28-influenceflow-phase-1-design.md` | Full Phase 1 spec (authoritative) |
+
+---
+
+## Codebase at a Glance
+
+```
+apps/web/                  # Next.js 15 App Router — the only app right now
+  prisma/schema.prisma     # Single Prisma schema
+  src/app/                 # Pages and API routes
+  src/lib/                 # Pure utilities (db, auth, audit, excel, logger)
+  src/server/              # Business logic server actions
+  tests/                   # Vitest (unit) + Playwright (e2e)
+docs/
+  ai/                      # Session orientation docs (this folder)
+  product/                 # Product vision and phase docs
+  superpowers/specs/       # Detailed design specs per phase
+  superpowers/plans/       # Step-by-step implementation plans
+docker-compose.yml         # Production: app + db
+docker-compose.dev.yml     # Dev: db only
+```
+
+---
+
+## Tech Stack (one-liner per concern)
+
+- **Language:** TypeScript (strict)
+- **Framework:** Next.js 15 App Router — UI + API in one process
+- **UI:** React 19 + Tailwind CSS + shadcn/ui
+- **Database:** PostgreSQL 16 via Prisma ORM
+- **Auth:** Auth.js v5, Credentials provider, Argon2id passwords
+- **Validation:** Zod
+- **Logging:** Pino (structured JSON)
+- **Tests:** Vitest (unit) + Playwright (e2e)
+- **CI:** GitHub Actions
+- **Phase 2 additions:** Redis, BullMQ, worker process (`apps/worker/`)
+
+---
+
+## Roles (quick reference)
+
+| Role | Sees | Can do |
+|---|---|---|
+| `owner` | Everything | All admin powers; cannot be deleted or demoted |
+| `admin` | Everything | Full CRUD across workspace; manages team |
+| `member` | Own contacts only | Import, edit, toggle agent flag on own contacts |
+
+---
+
+## Development Quick Start
+
+```bash
+docker compose -f docker-compose.dev.yml up -d   # Start Postgres
+cp .env.example apps/web/.env                    # Fill in secrets
+cd apps/web
+pnpm install
+pnpm prisma migrate dev
+pnpm prisma db seed                              # Creates workspace + owner
+pnpm dev                                         # http://localhost:3000
+```
+
+Tests:
+```bash
+pnpm test        # Vitest unit tests
+pnpm test:e2e    # Playwright e2e (starts dev server automatically)
+```
+
+---
+
+## Before You Write Any Code
+
+1. Read `docs/ai/SESSION_HANDOFF.md` to know what the previous session left off.
+2. If working on Phase 2, read `docs/product/PHASE_2_PRODUCT_DECISIONS.md` — all key decisions are already made.
+3. Check the git log: `git log --oneline -20`
+4. Run `pnpm test` to confirm the baseline is green.
diff --git a/docs/ai/TASK_RUNBOOK.md b/docs/ai/TASK_RUNBOOK.md
@@ -0,0 +1,120 @@
+# Task Runbook — How to Work on InfluenceFlow
+
+This document is for any Claude Code session picking up work on this project.
+
+---
+
+## Orientation Checklist (do this before touching code)
+
+- [ ] Read `docs/ai/START_HERE.md` (project overview, stack, quick start)
+- [ ] Read `docs/ai/SESSION_HANDOFF.md` (what was done last; what's next)
+- [ ] Run `git log --oneline -20` to see recent commits
+- [ ] Run `pnpm test` from `apps/web/` — all tests must be green before you start
+
+---
+
+## Branch Convention
+
+All work goes on the feature branch specified by the session. The current designated branch is `claude/install-superpowers-plugin-XIYZI`. Never push to `main` directly.
+
+```bash
+git checkout claude/install-superpowers-plugin-XIYZI
+git pull origin claude/install-superpowers-plugin-XIYZI
+```
+
+---
+
+## How to Pick Up a Task
+
+1. Find the implementation plan for the phase you are working on:
+   - Phase 1: `docs/superpowers/plans/2026-04-28-influenceflow-phase-1.md`
+   - Phase 2: `docs/superpowers/plans/2026-04-30-influenceflow-phase-2.md` *(to be created when Phase 2 starts)*
+2. Look for unchecked `- [ ]` items — those are incomplete tasks.
+3. Read the corresponding spec for the phase before implementing:
+   - Phase 1 spec: `docs/superpowers/specs/2026-04-28-influenceflow-phase-1-design.md`
+   - Phase 2 decisions: `docs/product/PHASE_2_PRODUCT_DECISIONS.md`
+4. Implement one task at a time; commit after each task.
+
+---
+
+## Commit Convention
+
+```
+<type>: <short description>
+
+<optional body>
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`
+
+Example:
+```
+feat: add bulk send queue with BullMQ
+
+Implements the worker job for Phase 2 outbound email dispatch.
+Rate-limited to workspace-configured cap (default 50/day/member).
+```
+
+---
+
+## Code Conventions
+
+- **All business logic** lives in `apps/web/src/server/` as server actions.
+- **Pure utilities** (no DB, no session) live in `apps/web/src/lib/`.
+- **Pages and API routes** call server actions — no business logic in components.
+- **Zod** for all input validation at boundaries (API routes, server actions).
+- **Pino** for logging (`import { logger } from '@/lib/logger'`).
+- **Every mutation** writes an audit event in the same transaction.
+- **No comments** unless the WHY is non-obvious. No doc-comment blocks.
+- TypeScript strict mode — no `any`, no `// @ts-ignore`.
+
+---
+
+## Testing Convention
+
+- Unit tests (`tests/unit/`) cover pure lib functions and server logic in isolation.
+- E2E tests (`tests/e2e/`) cover critical user flows end-to-end via Playwright.
+- Test order: RED → GREEN → COMMIT for each behavior.
+- Never skip tests to make CI green — fix the underlying issue.
+
+---
+
+## Adding a New Phase
+
+When starting a new phase:
+
+1. Create the spec: `docs/superpowers/specs/YYYY-MM-DD-influenceflow-phase-N-design.md`
+2. Create the plan: `docs/superpowers/plans/YYYY-MM-DD-influenceflow-phase-N.md`
+3. Update `docs/product/PHASES.md` — change the phase status.
+4. Update `docs/ai/SESSION_HANDOFF.md` with current state.
+5. Update `README.md` if the deployment model changes.
+
+---
+
+## Infrastructure Changes (Phase 2+)
+
+Phase 2 adds `apps/worker/` and requires Redis. When adding the worker:
+
+- Add `apps/worker/` alongside `apps/web/` (same repo, no monorepo tooling yet).
+- Add `redis` and `worker` services to `docker-compose.yml`.
+- Shared BullMQ queue definitions go in a `packages/queues/` package if needed, otherwise inline in worker.
+
+---
+
+## Pushing Work
+
+```bash
+git push -u origin claude/install-superpowers-plugin-XIYZI
+```
+
+If the push fails due to network error, retry up to 4 times with exponential backoff (2s, 4s, 8s, 16s). Do NOT force-push unless explicitly instructed.
+
+---
+
+## When You're Done with a Session
+
+Update `docs/ai/SESSION_HANDOFF.md`:
+- What you completed (with commit SHAs if helpful).
+- What is in progress or blocked.
+- What should be done next.
+- Any gotchas or decisions made during the session.