Contact relationship workspace, Gmail intelligence, and daily debrief

[brycejohnson1417]

Goal

Create one private master specification and deliver the approved PICC contact and account relationship-management program through three independently testable releases.

Product scope

Release 1: Operational UI foundation

• Replace oversized sync panels everywhere with one compact, collapsed-by-default sync disclosure showing Last Sync and status.
• Remove redundant Contacts and Accounts headers and explanatory copy.
• Redesign Contacts as a light, actionable mobile-first directory that clearly shows name, dispensary, email, phone, contact types, and direct actions.
• Redesign mobile account cards to show dispensary, rep, customer/account status, overdue status, Pay Days Avg., and Nabis Ranking; remove address from cards and reserve a non-overlapping alphabet-rail gutter.
• Add New Follow-Up on Accounts.
• Add Email, Text, and Call actions from Contacts, contact detail, and the Contacts section on Account Details.
• Open Gmail compose for email, the phone messaging composer for text, and the dialer for calls.
• After returning from an external communication action, prompt for Completed, Did Not Connect, or Cancel, then offer Set Follow-Up.
• Add per-rep default follow-up dates in Settings.
• Support favorites, relationship frequency, last seen, timeline, reminders, relevant details, Instagram, LinkedIn, Save to Phone Contacts, Merge With, Archive, and Delete.
• Add the same Add Contact flow from Contacts, Accounts, Account Details, the Account Details contact section, and Map beneath Subway Lines.
• Support multi-select contact types: Primary Contact, 2nd Contact, PPP 🎨 Palette: Add ARIA labels to icon-only buttons in territory workspace #2, PPP 🛡️ Sentinel: [HIGH] Fix XSS vulnerability in ppp-savings-panel.tsx #3, and Billing Contact.
• Before any typed CRM field replacement, show current and proposed contacts and require an explicit Keep or Replace decision.
• Always preserve and freshly verify the base Associated Contacts relation.
• Merge via field-by-field preview, combine non-conflicting data, require choices for conflicts, and archive the duplicate by default.

Release 2: Individual Gmail intelligence

• Each rep connects their own @piccplatform.com Gmail account in Settings.
• Use minimum Google scopes and encrypted refresh credentials.
• Match email activity by normalized contact email.
• Show verified sent/received events, safe previews, exact Gmail thread links, and Last Seen updates.
• Never represent a draft as sent.
• Keep rep mailbox data private to that rep unless a future sharing decision explicitly changes the rule.
• Suggested Contacts are real Gmail correspondents not already matched to PICC.
• Show suggestion evidence and possible dispensary without automatically writing records.
• Quick Add prefills the contact form but requires the rep to confirm account and contact types.
• Home adds Resurfaced Contacts with Why Surfaced, First Met, Last Met/Seen, account context, suggested next steps, Copy, Open iMessage/Text, and Open Gmail.
• Resurfacing and suggested copy use deterministic, evidence-backed rules and never fabricate context.

Release 3: Daily debrief

• Per-rep enablement, delivery time, timezone, section toggles, test send, last-send status, delivery history, and retry controls.
• Include due/overdue follow-ups, open PPP onboarding, sampled non-customers ranked by most recent sample delivery, and resurfaced contacts.
• Include direct PICC and Gmail links.
• Use a Vercel Cron trigger, deterministic server-side assembly, an email-provider adapter, and an idempotent per-rep/day delivery ledger.
• Core scheduling, ranking, and message generation must not require an LLM.

Explicitly deferred

PICC Device Sync for automatic Apple or Android call, SMS, iMessage, or RCS history. Calls and texts remain launch-plus-rep-confirmation workflows until a separate device-sync program is approved.

Explicit exclusions

WhatsApp, Facebook, Messenger, X, groups, Enhance Contact, configurable social-network lists, automatic Gmail-suggestion writes, and all retired GHL, Bizly, native worker, payroll, or vendor-day dispatch surfaces.

Data definitions

• Overdue Status uses CRM account status plus Days Overdue.
• Pay Days Avg. is calculated from supported Nabis payment dates and exposes Unavailable when the evidence is insufficient.
• Nabis Ranking uses trailing 90-day net paid sales among matched active retailers and exposes Unavailable when the evidence is insufficient.
• Warm leads are sampled non-customers not closed/inactive and are ordered by most recent sample delivery, with documented fallback behavior.
• Open PPP onboarding is determined from the existing PPP and Headset connection statuses.
• Last Seen advances only from verified Gmail activity or a rep-confirmed interaction.

Safety boundaries

• No typed CRM field is overwritten silently.
• Gmail suggestions never create records automatically.
• Merge, archive, and delete have distinct semantics and confirmation.
• Delete is destructive and approval-lane.
• Production schema migrations, OAuth scopes/credentials, new secrets/provider setup, production Notion writes, and destructive production changes require approval before merge or execution.
• Exact live Notion field types must be verified read-only before implementing typed writes.

Acceptance and validation

• Every request and screenshot annotation is mapped to a release and observable test.
• RED-first unit coverage for deterministic logic and safety checks.
• Integration coverage for Gmail OAuth/matching, Notion read-write-readback, merge/archive/delete, cron idempotency, and email-provider boundaries.
• Playwright coverage for real mobile and desktop workflows.
• Visual proof at mobile, short desktop, and full desktop viewports.
• Full npm run verify and npm run test:e2e before completion claims.

Public traceability

GitHub issue: brycejohnson1417/Picc-web-app#163

Detailed product requirements remain in this private Linear control plane.

[linear-code]

BRY-115