source: .forge/design/prototypes/feature-detail.md · generated — edit the markdown, not this file

Empire Teas CRM — Feature Detail Reference

PRD × Prototype Cross-Reference

Purpose. .forge/project-prd.md states each in-scope feature in one paragraph — enough to scope it, not enough to picture it. The client-approved prototype shows how each feature behaves on screen. This document merges the two: the PRD’s priority and rationale plus the prototype’s concrete UI, fields, and flows, feature by feature.

Sources.

  • .forge/project-prd.md (live contract) — including §Functional Surface, §Users and Access, §Scope and Boundaries, §Phasing.
  • .forge/design/prototypes/crm/ — the client-approved CRM prototype, read as a bundle. Screens are cited by name (Dashboard, Lead Triage, Pipeline, Accounts, Samples, Quotes, Activities, Pricing, Inbox — the Products screen was removed on 2026-09-15) rather than by section number. The descriptions below are of the original, crm/. The current copy, crm-current/, draws the same design in the built CRM’s look (README.md): there Lead Triage is Leads (a list page and a record page), Inbox is Email, the top bar is gone, and Contacts and the Settings pages were added. Fields and flows described here hold for both unless the built app decided otherwise.
  • .forge/design/architecture.md — where the PRD’s decisions have a structural consequence the prototype does not yet reflect (notably bulk pricing).

How much to trust each half. Per .claude/rules/source-trust.md, the prototype is high authority on UX, flows and screens — it is client-approved, and what it shows is what the client signed off looking at. It is only medium authority on domain facts: the grade lists, stage names, certification sets and thresholds in it are our design, not client-confirmed (risk R-03). So read a prototype field list here as “this is the shape we drew”, not “the client asked for these values” — and where a domain value is load-bearing for a spec, confirm it with the client rather than citing this document. On any conflict, the PRD and approved specs win.

Method and scope. Illustrative numbers, sample company names, and mock figures from the demo data are left out throughout — those are prototype-seeded values that will not carry over. What is kept is the structure: which fields exist, what each screen shows, and how the flows behave. Where the prototype doesn’t show a feature, or shows it differently from what is now decided, that is flagged rather than glossed over.

Feature range. The PRD’s in-scope surface is F1–F26, F31–F34, and F36 (as of 2026-10-11, F16 and F31 are dropped and kept here as records — PRD Revs 60 and 61). F27–F30 and F35 were dropped on 2026-10-11 (PRD Rev 66) and are covered in a closing section. There are no features numbered F27–F30 or F35 in the functional surface, and F36 (the trade-show capture PWA) is in V1 scope — see its entry below.

Legend: P0 = must-have to replace Pipedrive · P1 = high-value domain/AI/parity · P2 = enhancement. Priorities are as recorded in .forge/features.md.

Note on prototype-inventory.md. .forge/discovery/inventories/prototype-inventory.md was captured 2026-07-06 against an earlier, much smaller build of the prototype. The prototype has since grown substantially — it now carries a login screen, a role switcher, a Pricing screen (the Products catalog it carried for a while was removed 2026-09-15 — PRD Rev 27), an Inbox, sequences, pipeline configuration, attachments, a migration wizard, and a working global search, none of which the inventory records. Where this document and that inventory disagree, this document reflects the current prototype; the inventory needs re-capturing.


Core CRM — system of record

F1 — Accounts (organizations + contacts) — P0

PRD says: 360° customer records — profile, certifications required, preferred packaging, Incoterms, contacts, communication timeline, linked deals/samples/quotes, past orders, LTV, dormancy.

Prototype (Accounts screen):

  • Two-pane layout. Left: account list with a Dormant chip on stale accounts, type line, LTV, and a last-contact label.
  • Right detail header: type · region, company, LTV, a last-contact label, with three actions — Edit account, Enrol in sequence, Compose email.
  • AI account briefing (this is F13 rendered here): badge “BEFORE YOU MEET THIS CUSTOMER”, caption “AI suggested · synthesised from timeline & open opps”, a narrative line, then Open items (bullets), Suggested next move, and an amber Reorder/upsell trigger.
  • Profile grid: Customer type · Region · Certifications (chips) · Preferred packaging (chips) · Incoterms (chips).
  • Buying standards & prices (added 2026-09-11; reshaped 2026-09-14/15 — one price per standard, no catalog): a row per Buying Standard the account holds — bulk and private label — standard no · grade · Price / kg · Current/Expiring/Expired chip · valid until — each expanding to this week’s price, the week-on-week movement, validity, the price-history graph (one series per standard) and a link to the full-history drawer; no cost or profit here — the account section is a sales view (price plus profit % would reconstruct cost), so both live on the Pricing screen and the quote only. Roles holding the manage-standards permission get Add standard, Edit standard and Archive (archiving keeps the history and drops the standard out of quoting and the weekly round; a number is never reused) and Update this week’s prices; roles that can edit get Email this week’s prices to contacts (a mock — see the prototype README’s proposals list). An account with no standards shows a one-line empty state to those who may add one and nothing to anyone else. Until 2026-09-14 the rows carried a price board per destination market and an unpriced-markets chip — superseded by PRD Rev 23.
  • Product briefs section (private-label deals only): product, stage, status badge, click-through.
  • Contacts: initials avatar, name, role · email.
  • Communication timeline: colour-dotted, dated entries (kinds: lead / order / sample / call / quote / note / email).
  • Open opportunities: product, stage · owner · days-in-stage, value, volume, View in pipeline →.
  • Past orders: monospace ref, description, value, date — read-only. (The subtitle read “— via ERP” until 2026-09-04; see the ERP note below.)
  • New account modal: Company, Country, Region, Customer type, Est. LTV, Required certs, Preferred packaging, Incoterms + primary contact. Edit account is the same minus company, plus “add another contact.”

F2 — Pipeline / Deals (independent pipelines, Kanban, drag-and-drop) — P0

PRD says: Private Label (10 stages) and Bulk (4 stages) boards; deal cards with value, volume, certs, owner, age-in-stage alerting. Deals are created with title/value/currency/owner/person/org/pipeline+stage/expected-close/label plus custom fields, and can move between pipelines.

Prototype (Pipeline screen):

  • Header naming the active pipeline, with a running total for Open value / Weighted forecast / Won this quarter.
  • Pipeline tabs (Private Label / Bulk by default), Configure (gear → F24), New pipeline (+ → F24).
  • Kanban columns: status name, an AUTO badge on sample-driven stages, a count, and aggregate value.
  • Deal cards: company, country · product, value + volume, certification chips, owner-initials avatar, an age-in-stage label, and a colour-coded age dot (green → amber → red once past the stage’s rotting threshold).
  • Drag-and-drop is pointer-based. Sample-driven columns refuse manual drops — a toast explains that sample stages move automatically from the Samples page. This is the F6 coupling; see F6.
  • Clicking a card opens the Deal Detail drawer — the richest overlay in the prototype. Sections appear conditionally, driven by the stage kind configured in F24 (standard / brief / sample / quote / won):
Section Appears when Contents
Header always id · pipeline · stage, company, product, Enrol in sequence, close
Metrics always Value · Volume · Owner
Certifications recorded on the deal deal has certs “Certifications recorded on the deal” + chips (relabelled 2026-09-02 from “This deal’s product holds”; the F9 panel beneath reads the linked standards)
Activity & call log always Log call/meeting (the F16 product-brief assistant that would read these notes was dropped, PRD Rev 61)
Files (F33) always +Attach; name, size · by · when
Communication (F20) always Compose; linked emails w/ state badge, subject, preview
Samples (F6) the pipeline has sample stages (not the deal’s current stage) Request sample; rounds as “Round N” + summary
Quote (F7) quote stage reached, or the deal sits on the single stage immediately before it Open linked quote / Generate quote
Cert mismatch (F9) the deal’s account is matched and requires certifications Warning or green all-clear
Export-doc checklist (F10) always; content derived from destination + held certs Assembled/outstanding count, toggle rows; a simplified “no commercial value” note at pre-commercial stages
Product brief (F8) brief stage reached, or deal sits before it Draft/Update with AI, editable rows, complete/incomplete summary
ERP handoff (F19) the deal’s current stage is of kind won Readiness rows, Generate handoff document

Note on the gating. These conditions are not uniform, and the differences are deliberate. Samples keys off whether the pipeline contains sample stages at all, so the section persists across the deal’s life. Quote and Product brief use a reached-or-immediately-before rule — a comment in the source explains why: otherwise a 10-stage Private Label deal would offer “Generate quote” back at New inquiry. Cert mismatch is shown from the very start, per F9’s “before quoting” intent.

Not in the prototype: the New Deal modal does not carry the full PRD field set (expected-close date, label, currency selection, custom fields), and deals cannot be moved between pipelines.


F3 — Activities (tasks, follow-ups, reminders) — P0

PRD says: Grouped Overdue/Today/Upcoming/Completed, filters, mark-done, activity types (call/meeting/task/deadline/email/lunch plus admin-defined custom types), linked to accounts/deals/leads.

Prototype (Activities screen):

  • Header + List / Calendar toggle + New activity.
  • Calendar view: day-columns across the week, today highlighted, colour-dotted clickable chips per item.
  • List view: filter pills (All / Overdue / Today / Upcoming), then four groups — Overdue (red), Today (amber), Upcoming (green), Completed (muted, struck through) — each with its own count. Each row: type dot, title, type · account · owner, a due chip, Mark done where applicable.
  • Outreach sequences panel (always visible, ties to F25): badge “AI-DRAFTED STEPS · YOU APPROVE”; per sequence — name, an enrollment count, and the step list as “Day N” + step label.
  • New activity modal: Type, Due date, Title, Assigned to, Account, Link to deal, Agenda.
  • Activity Detail drawer: type dot + type · owner, title, account, a due-status badge, Open deal → where linked, Agenda/talking points, Meeting notes (“feeds the AI product brief”), Save notes, Mark done.

Not in the prototype: admin-defined custom activity types (the type list is fixed).


F4 — Pipedrive data migration — P0

PRD says: One-time import of leads, contacts, organizations, deal history, notes, activities, and business-critical custom fields, with dedup and cleaning. Migration approach is confirmed, not open (OQ-21, resolved 2026-08-02): migrate everything, preserve original Pipedrive IDs for audit, and let AI triage flag junk after import rather than dropping records beforehand. Shares its import engine with F23.

Prototype (Migrate from Pipedrive modal, from the New menu): a 3-step wizard —

  1. Detect — surfaces counts of leads, contacts, organizations, deals, and custom fields found in the source export.
  2. AI triage progress — a progress indicator while records are classified.
  3. Results — a breakdown into qualified / nurture / spam / duplicate buckets → Import into CRM.

Two caveats, both material:

  • Fidelity: the source file is a mock CSV, the progress bar is static rather than tracking real work, and the result breakdown is fixed rather than computed. The screen demonstrates the shape of the wizard, not working migration logic.
  • ⚠️ Behavioural conflict with OQ-21. The prototype’s results step labels one bucket “Spam — archived, not imported” — i.e. it drops records before import. That is precisely the approach OQ-21 rejected. The built version must import everything (IDs preserved) and triage afterwards. Do not treat the prototype’s bucket copy as the specification.

F5 — Authentication, users, roles & ownership — P0

PRD says: Per-user login with role-based access across all six roles, plus record ownership/assignment. Includes an Administrator user-management surface: create a user and assign their role at creation, change a role later, deactivate/offboard (reassigning owned records and releasing the mailbox connection), and reset credentials — across both login paths. The mechanics are undecided and gate this feature’s spec (OQ-51; permission-level semantics is OQ-53).

Settled since, by AD #34 / AD #35 / AD #36 (2026-09-24) — read these over the paragraph above, which is the PRD text as this document last quoted it: sign-in is Microsoft-only (AD #28), so there are no credentials to reset; a sign-in succeeds only for an active user the administrator created beforehand (no auto-provisioning, no invitation); users are deactivated and reactivated, never deleted, deactivation ends their sessions and is refused for oneself, for the last administrator, while the user has direct reports, and while they own records (F5-c; bulk reassignment is F5-h). No role is predefined — the six are the recommended set Empire’s administrator builds, plus the Managing Director role; only an editable IT Admin role and user are seeded, by migration (F5-k). The catalog is view / manage per entity plus a few special keys, with all user, role and hierarchy administration and all configuration under one settings.manage (access.manage held the administration until AD #34’s refinement of 2026-10-26) (answering OQ-51 and OQ-53(a); the Tea Room and Executive role contents, OQ-53(b), stay open). Records are owned and can be shared, transitively, with one visibility rule for lists and records (F5-f; the sharing screens are F5-g). Every write and security event is audited (F39).

Prototype:

  • Login screen: decorative left panel with the pitch line; right card offers a single Continue with Microsoft button (real SSO logo). Footer: “Role-based access · every action audited.” There is no auth validation — the button signs you in as the demo persona. Updated 2026-09-04 for AD #28 (PRD Rev 20; design-system Rev 10): the prototype previously offered Continue with Google and a Work email + Password fallback alongside it, and both were removed when Microsoft became the sole login path — so the screen and the PRD agree, with no drift row owed. The pre-change version is git history.
  • Role switcher (sidebar, bottom): avatar + name + role; a popover “View the demo as” swaps roles live so UI permissions change — switching to Sales Rep and attempting to approve a quote is refused. This demonstrates the mechanism of role-based UI gating.

⚠️ Known drift — the prototype’s role model is incomplete.

Prototype PRD
Roles 4 in the approved build — Sales Manager, Sales Rep, R&D / Sample Owner, Administrator; the switcher grew to the six roles plus Managing Director on 2026-09-07 6 recommended — those four plus Tea Room (pricing) and Executive/Management (read-only) — plus the Managing Director role; none predefined: Empire’s administrator creates them from the catalog, and only an editable IT Admin role is seeded (AD #34, 2026-09-24; was “not seeded, AD #32”)
Quote approval Every quote gated on Sales Manager or Administrator Reps quote freely at or above the gross-profit floor; only sub-floor quotes escalate, to a holder of quote.approve_sub_floor — the Managing Director role in the recommended configuration (AD #34: configuration, not code)
Weekly price publishing Ungated — any role can publish Holders of price.publish — the Tea Room in the recommended configuration (AD #34)
Permission levels Binary (manager or not) View / manage per entity plus a few special keys on a configurable catalog — no category axis (OQ-47 → AD #30/#32, refined by AD #34, 2026-09-24; AI is not a grantable level). Was: per-permission categories read / edit / execute (AD #32)
User management Absent in the approved build; Users & roles screens added 2026-09-07 as a team proposal (their template markers, two-role person and AI-assist chip are superseded by AD #32, 2026-09-11; their access behaviour is superseded by AD #34/#35 — rows below) Required — create / assign the one role / set the manager / deactivate / reactivate, all under settings.manage, as pages under Settings; no credential reset (Microsoft-only sign-in)

⚠️ Drift added 2026-09-24 — the prototype’s access and sharing behaviour predates AD #34 and AD #35. Verified in the prototype source on 2026-09-24; cited by function or on-screen text, not line number.

Prototype Decided (AD #34 / AD #35)
Permission catalog seedPermCatalog — a catalog of View / Manage / Act kinds: quotes with margin, separate “view published weekly prices” and “view cost and floor” permissions, four email permissions (open a mailbox by scope, view linked mail, send from a record, bulk send), a read-only view users and the reporting line permission beside manage users, roles and the reporting line, two settings permissions (pipelines and custom fields; AI features) and a view the full audit log permission <entity>.view / <entity>.manage per entity (manage implies view) plus settings.manage, email.manage, price.publish, quote.approve_sub_floor. buying_standard.view covers the whole build-up (no cost key); email.manage is your own mailbox only (no role opens another person’s); user, role and hierarchy administration and all configuration are one settings.manage (it absorbed access.manage on 2026-10-26; no read-only user list — pickers use a minimal directory); no audit screen in V1 (AD #36)
The Act kind in the role editor Each role shows how many outward-acting (Act) permissions it holds, the editor warns on them, and granting one raises a toast “… is an outward-acting permission” No category axis — no Act count, no warning (AD #34)
The system Administrator role Marked system, shown with a System role badge and “Cannot be deleted — there is always one Administrator” No superadmin and no system role. The seeded IT Admin role is ordinary: renamed, re-permissioned, and deleted once no user — active or deactivated — holds it (AD #34, F5-k)
Last-administrator protection Enforced only in setUserRole, keyed on the system role; toggleGrant removes any permission from any role with no check At least one active user always holds settings.manage (access.manage until 2026-10-26), enforced at four points: deactivating a holder, changing a holder’s role, editing a role to drop the key, deleting a role (AD #34)
Role-name checks Admin navigation, Executive editing and several screens decide by role name or the system flag Every check names a permission key, never a role (AD #26, AD #34)
Adding a user “Demo only — a real invite creates the account against the person’s Empire Microsoft 365 sign-in” No invitation. The administrator pre-creates the user; sign-in succeeds when the verified email matches that active user (AD #34)
Who is offered in the share picker Everyone except the owner and me; a user whose role holds no lead permission is offered, marked “No lead access” Only active users whose role holds the entity’s view key and who do not already reach the record; people who already reach it are not listed; people whose role cannot view the record type are not listed (AD #35)
“Already reaches the record” reachesWithoutShare counts the owner, the reporting subtree and all scope — not records shared with someone below The reporting-line rule includes records shared with anyone below me (shares roll up — AD #35), and the entity’s all key reaches every record (AD #37)
Reach per permission (added 2026-09-27) The role editor sets a reach — own / team / everyone — on each permission No reach to set (AD #37): every key reaches down the reporting line, and one All records tick per owned entity reaches every record
Onward sharing Footer: “A colleague you share with cannot pass it on further”; mayShareLead lets only the owner or a manager above share Transitive: anyone whose role holds the entity’s manage and who reaches the record — including through a share — may share it (AD #35)
Removing a share The × on every share chip removes it, for whoever is looking, with no permission check Removing a share needs manage access to the record; anyone with it may remove any share (AD #35)

Treat the prototype as illustrative of role-based UI gating and of the share affordance’s placement, not as the access model. The Tea Room and Executive role contents are Empire’s configuration (OQ-53 closed 2026-09-24 as not required); the model itself is AD #34’s (FS-6 shipped the earlier one and F5-k realigns it). This paragraph said, until 2026-09-24, that those columns must be completed before Foundation slice 6 — FS-6 has since shipped.


Tea-domain workflows

F6 — Sample tracking (multi-round lifecycle) — P1

PRD says: 7-state lifecycle board + management table; multi-round per deal; courier/tracking; overdue-feedback nudges; “where it’s stuck” reasons. Typical rounds range from 1–2 when matching an existing client sample to 6–7 when developing a new standard, almost always closing before 10 (OQ-11, confirmed 2026-08-03).

Prototype (Samples screen):

  • Header summarising counts in flight, overdue for feedback, and awaiting R&D prep, plus a Lifecycle board / Management table toggle.

  • A red AI nudge banner naming specific overdue samples, closing with “You approve before anything sends.”

  • Lifecycle board — 7 columns: Requested → Blended/Prepared → Dispatched → Delivered → Feedback due → Feedback received → Outcome. Cards show account, round label, country · product, owner avatar, a due badge, and conditionally courier + tracking, outcome text, a Draft feedback chase button (overdue only), and a state-labelled advance button.

  • Management table — Sample/account · State · Owner · Due · Status — where it’s stuck (plain-language, e.g. “buyer feedback overdue,” “in transit — check courier,” “awaiting R&D prep”).

  • Sample state drives deal stage automatically — the single most detailed piece of business logic in the prototype, and verified in its source:

    Sample state Deal moves to
    Requested / Blended-Prepared 1st sample stage
    Dispatched / Delivered 2nd sample stage
    Feedback due / Feedback received 3rd sample stage
    Outcome = Approved the stage after the sample block
    Outcome = Revision/Rejected stays put, a new round is auto-created

    Advancing also resets the deal’s age-in-stage clock. This is why sample-driven Kanban columns carry the AUTO badge and refuse manual drags (F2).

  • Modals: Dispatch sample (Courier selection + Tracking number — auto-generated if left blank), Log buyer feedback (free text), Set sample outcome (Approved / Revision requested / Rejected + notes).

Deferred (PRD): courier/tracking API integration. V1 stores courier and tracking number as manual fields, as the prototype does.


F7 — Quotes with 8-item readiness checklist + approval gate — P1

PRD says: Quote records, aging, revision history, line items drawn from the account’s buying standards (F26 — no products catalog since PRD Rev 27), and a payment-terms field (LC / Open Account / DA / CAD / advance, per customer — OQ-10 confirmed). The system computes the quote’s gross-profit % from the standard’s cost. Submission is blocked until the 8-item checklist passes; a quote at or above the required gross-profit floor needs no special approval, while a sub-floor quote is blocked pending Managing Director approval (OQ-40).

Prototype (Quotes screen) — the most logic-dense area:

  • List: header stats summarising active quotes, how many are aging, and how many are awaiting approval. Cards: quote id, a colour-coded aging badge, account, product, value, and a checklist-progress count.
  • Detail:
    • Header: id · status, account, product · country, value, margin, ✎ Edit quote.
    • “Before this quote can go out” — plain-language restatement of failing checklist items (explicitly not AI-generated).
    • Price validity / stale-price banner when a bulk quote’s price is expiring or expired, with ↻ Refresh price — re-prices line items from the standards’ live published prices, updates the visible total, clears the banner, and logs a revision. The quote is treated as only as fresh as its stalest market-priced line.
    • Readiness checklist — 8 rows, tick/cross, with a readiness percentage. The items are Product spec · Quantity · Packaging · Incoterm · Currency · Destination · Certifications · Margin & approval, matching the PRD exactly.
    • Quote details: Quantity · Packaging · Incoterm · Currency · Destination · Certifications, plus (bulk only) Price basis (market · this week) and Price validity (Current/Expiring/Expired chip).
    • Line items (standards & custom): name, qty × price/kg, line total, Product subtotal (the prototype’s label — the lines are standards).
    • Additional costs (freight, certification, export docs): label + amount, Cost additions subtotal.
    • Similar past quotes (F14): badge AI MATCHED — reference, description, margin · outcome. Not built — F7-e dropped 2026-10-11 (PRD Rev 61).
    • Revision history: version, note, timestamp.
    • Margin entry: “A human calculates margin — the AI never sets price.” Setting it flips the 8th checklist item.
    • Approve: gated to Sales Manager or Administrator; on approval, opens an AI-drafted cover email for review and send. As Sales Rep the button refuses — demonstrating this live is the point.
  • Quote builder modal (new quote or edit): a picker over that account’s buying standards (since 2026-09-15 — was a catalog picker); line items (qty in tonnes, discount); a live confirmation line pricing from the standard’s published price (the destination-market dropdown went with the market axis on 2026-09-14); Additional costs; terms; a live checklist-progress indicator.

⚠️ Drift to carry into the spec:

  • Payment terms are absent from the prototype. The PRD requires the field (OQ-10 confirmed). Add it.
  • Margin is manually entered, not computed. The PRD requires the system to compute gross-profit % from the standard’s cost and check it against a floor. A free-text margin field is not the same mechanism and will not support the sub-floor gate.
  • The approval gate is the wrong shape, not merely missing a tier — see F5’s table.

F8 — Product briefs (private label) — P1

PRD says: A structured internal brief — tea type, blend profile, origin requirement, packaging format, pack size, outer packaging, volume, target market, required certifications. Missing values render as “Needs confirmation,” and blocking open questions must be resolved before the brief is complete and ready for R&D/packaging handoff. One brief per private-label deal.

Prototype: lives inside the Deal Detail drawer, shown once the brief stage is reached (or while the deal sits before it): status badge, Draft with AI / Update with AI (not built — F16 dropped, PRD Rev 61; the rep fills the brief), editable field rows with a placeholder for anything unresolved, a Certifications-required field, an “Open questions — blocking handoff” block, and a complete/incomplete summary. The AI product-brief assistant modal (F16, badge F16 · HITL) is the entry point: paste rough call notes → Draft brief with AI produces this structured draft for a human to confirm.


F9 — Certification mismatch check — P1

PRD says: Cross-checks buyer-required certifications (from the account) against the certifications the deal’s buying standards hold (F26 — the standard carries them; there is no catalog since PRD Rev 27) and flags the gap, or confirms all present.

Prototype: a section in the Deal Detail drawer, shown whenever cert data is present — either a warning naming the required certification the linked standard doesn’t hold, or a green all-clear (deals carry standardNos since 2026-09-15; the held side is the linked standards’ certs for bulk and the product brief’s for private label).

Dependency to watch: F9 is gated on OQ-9 (where the standards’ held-certification data lives) and on the client supplying certification data. The proposal’s fallback if that data doesn’t arrive is to simplify F9 to a manual checklist.


F10 — Export documentation checklist — P1

PRD says: Generates the required document set per destination country plus the standards’ held certifications, toggleable as assembled — base documents + per-country documents + per-certification documents. For pre-commercial (sample) stages it explains the simplified “no commercial value” customs path. The CRM references the correct set; it does not file to SLTB or ASYCUDA.

Prototype: a Deal Detail drawer section explaining the document set is based on destination and the certifications the standard holds, with an assembled/outstanding count and clickable toggle rows per required document; earlier stages show the simplified no-commercial-value note. Driven by the seeded Export Document Rule reference data (base docs, per-country docs, per-certification docs) — the most PRD-relevant admin-managed reference-data surface in the prototype.


AI productivity layer (human-in-the-loop throughout)

F11 — Lead triage with AI scoring & drafted replies — P1

PRD says: Inbound-inquiry queue with AI priority P1–P3 + confidence (three levels, Rev 55), a hot/cold status from how recently the buyer last wrote (hot within 30 days, a setting; not AI — Rev 55), summary, “why this priority,” spam/duplicate detection, recommended next action, editable AI-drafted follow-up generated when a person presses the draft button (Rev 56 — not drafted in advance); approve/convert/archive actions. Every lead captures a first-class lead source (Website, Trade Fair, Referral, Email, Other) feeding the F17 leads-by-source breakdown. The full backlog is triaged as a one-time recovery pass.

Prototype (Lead Triage screen) — the answer to the stale-lead backlog:

  • Left queue: title + a shown-vs-total-backlog count; a green banner “AI has summarised, scored & drafted replies. You approve every action.” (drafts are made on request since PRD Rev 56, so the banner’s “drafted replies” no longer holds); status pills (New/Approved/Converted/Archived/All); priority pills (All/P1–P4 — the PRD now has three levels, P1–P3, Rev 55; the prototype has no hot/cold indicator); three dropdowns — country, buyer type, and lead source; lead cards with priority badge, an optional SPAM/DUPLICATE tag, country · buyer · received, product line, and a confidence bar. A footer note that more leads remain in the backlog. Empty state: “Queue clear for these filters.”
  • Right detail: priority badge + lead id/received + company; meta grid (Country, Buyer type, Est. value, Channel = lead source); AI Summary (badge, source, summary text, confidence bar, “Why this priority” reasoning); Recommended next action; Draft follow-up (new leads only — badge AI DRAFTED · EDITABLE, flipping to “· edited by you” once touched; footnote “pricing intentionally omitted (human-set)”) with three actions: Approve & send (files as sent email, matches/creates account, marks lead Approved), Convert to opportunity (opens New Deal pre-filled, badge CONVERTING LEAD), Archive/nurture. Processed leads show a PROCESSED badge and the actual email sent, or a note that none was.

F12 — AI inquiry extraction from email — P1

PRD says: Extract structured fields (buyer/company, country, tea type/grade, volume with units, packaging, certifications, Incoterm, destination port, timeline) from inbound inquiry text into a CRM draft; unknown fields returned null, never guessed. V1 triggers on manual paste or forward-in; an automated inbound-email trigger and multilingual extraction are deferred.

Prototype: the New lead from inquiry modal (New menu, tagged F12): paste email → Extract with AI → extracted field rows to confirm → Create lead from extraction. Copy explicitly stresses “anything not stated is returned blank, never guessed.”


F13 — AI account briefing — P1

PRD says: Pre-meeting synthesis of an account — who they are, what they’ve ordered and sampled, open items, a last-communication summary, a suggested next move, and a reorder/upsell trigger, synthesised from the timeline, open opps, and ERP order history.

Prototype: this is the Accounts screen’s AI briefing block described under F1 — badge “BEFORE YOU MEET THIS CUSTOMER,” narrative + Open items + Suggested next move + amber Reorder/upsell trigger.


F14 — AI quote assistant — P1

PRD says: Flags every missing or incomplete quote input and relevant risk, and surfaces comparable past quotes for pricing reference. Prepares inputs only — never sets or approves price.

Prototype: two pieces inside the Quotes screen (F7) — the “Before this quote can go out” plain-language gap list, and the Similar past quotes panel (badge AI MATCHED) showing reference, description, margin and outcome for comparable historical quotes. The Similar past quotes panel is not built — F7-e dropped 2026-10-11 (PRD Rev 61); the PRD’s F14 no longer surfaces comparable quotes.


F15 — AI dashboard: morning briefing + “what’s stuck” + ranked leads — P1

PRD says: Personalised daily narrative and blocker read across leads/opps/samples/quotes, with click-through. All are read-and-decide aids; the human actions them.

Prototype (Dashboard screen):

  • Header: current date + a personalised greeting. (A “last synced with ERP” note sat here until 2026-09-04; see the ERP note below.)
  • AI Morning Briefing — badge, a provenance line describing what it was drafted from, and a named narrative (a specific hot lead, a quote stuck on margin approval, overdue samples), with click-through CTAs.
  • “What’s stuck — and why” — badge AI SUGGESTED, several colour-dotted, clickable rows spanning samples, quotes, negotiation momentum, incomplete briefs, and dormant accounts.
  • High-priority leads to triage — badge AI RANKED, several cards with a priority score, country · buyer type, and a one-line AI read.

(F15 and F17 are the same screen: F17 is the KPI/funnel substrate, F15 the AI narrative layer on top.)


F16 — AI product-brief assistant — P2

Dropped from V1 on 2026-10-11 (PRD Rev 61). Not built; a rep fills the product brief by hand. The text below is kept as the record of what was planned.

PRD says: Turn a salesperson’s rough call or email notes into a structured product-brief draft, inferring fields and flagging open questions for human completion.

Prototype: covered under F8 — the modal opened from the Deal drawer: paste rough notes → Draft brief with AI, badge F16 · HITL.

Scheduling note: F16 is scheduled last in Phase 2 and is the cheapest scope lever under R-ARCH-001.


Visibility & handoff

F17 — Dashboard & operational KPIs — P0

PRD says: Avg inquiry response (target <12h), follow-ups due today (+overdue), samples overdue for feedback, quotes aging >7 days ($ at risk), dormant high-value accounts; a pipeline-by-stage funnel with pipeline toggle and footer stats (open value, weighted forecast, won this quarter, in final negotiation); and a leads-by-source breakdown. Ad-hoc reporting is served by filterable, exportable list views (F32/F23) rather than a separate report builder.

Prototype: the structural half of the Dashboard —

  • Five KPI cards matching the PRD’s five, each with a sub-stat (a target and prior-period comparison, an overdue sub-count, the oldest overdue sample, a value-at-risk figure, a silence threshold).
  • Pipeline by stage — tabs, a horizontal bar per stage, Open board →, footer: Open value / Weighted forecast (amber) / Won this quarter (green).
  • Leads by source — a bar per source, Open Lead Triage →, a footer total.

Fidelity caveat: the five KPI figures are literal values in the prototype source, not computed from state — illustrative placeholders. The funnel and the sample/quote summary counts are computed. Worth saying plainly when demoing.


F18 — Stale/aging alerts & dormant-account detection — P1

PRD says: Per-stage rotting thresholds (differing per stage and pipeline — 14 days of silence means nothing in a 5-month private-label cycle but is urgent in a 3-week bulk cycle), quote aging, and dormant reorder-ready account detection. Feeds the dashboard “what’s stuck” and KPI cards. Thresholds are discovery-driven.

Prototype: three surfaces carry this — (1) the rotting age-dot on deal cards turning red past a stage’s idle threshold, configured per stage in F24; (2) the Quotes list’s aging badges and the value-at-risk KPI; (3) the Dormant chip on Accounts plus the dashboard’s dormant-accounts KPI and a named example in “What’s stuck.”


F19 — CRM→ERP handoff on Won — P1

PRD says: On a Won deal, produce a structured handoff document after a readiness checklist passes — quote approved and pricing confirmed, certifications verified, and for private label the product brief complete. Automated API sync is deferred pending confirmation the new ERP exposes an API (AD #10).

Prototype: a Deal Detail drawer section appearing once a deal is Won: readiness rows, Generate handoff document, then a confirmation. It explicitly notes automated sync is pending ERP API confirmation — this is the manual document path, not a real integration.

Sequencing note: F19 sits in Phase 2. Deals can reach Won before it exists, so the first Won deals are handed off by hand — say so to the client rather than let it surface live.


CRM parity & communication

F20 — Email in the CRM (two-way sync + send + templates + tracking) — P0

PRD says: Two-way sync of each user’s Microsoft 365 mailbox via Graph — the only provider in V1 scope (AD #16) — so mail auto-links to the matching contact, deal and lead and lands on the account timeline. The shared info@ inquiries mailbox connects alongside per-user mailboxes as an unowned connection and feeds lead intake. Since 2026-09-24 (lead decision): V1 brings info@ in by forwarding — an inquiry is forwarded to a rep, whose own synced mailbox brings it into the CRM — and the shared inbox (F20-e) has left V1. Mailboxes are per-user only; no role reads another person’s mailbox (AD #34). Reps compose, reply and send from within a deal/contact and from an in-CRM inbox, with CC and BCC on every compose. Email templates (starter plus custom, team-shareable) support merge fields; open and link tracking and scheduled send are included; F20 itself sends one email at a time — group/bulk sending was dropped from F20 on 2026-09-11 (Rev 23) and, since Rev 28 (2026-09-16), is the separate feature F37 — a stretch candidate until 2026-10-09, committed to Phase 2 as F37-a and F37-b (Rev 57); F37-a was built early and is accepted with Phase 1 (Rev 100), and F37-b is started early in Phase 1 (Rev 102). Spec F20 without F37; F37 builds on F20’s send path.

Prototype (Inbox screen):

  • Subtitle: “Two-way sync · auto-linked to records.”
  • Left: thread cards with a direction label, message count, a state badge (received / sent / delivered / opened / clicked), subject, account · when, preview.
  • Right: thread detail with each message showing direction/state badge, party, timestamp, body, and Reply with AI draft. Messages carry a linked reference to the lead, deal or quote they belong to.
  • Compose email modal (also reachable from Accounts and the Deal drawer): To / Cc / Bcc / Subject / Body, Send + AI draft; footer notes merge fields, human-set pricing, and tracking.

Not built in the prototype: template management, merge-field configuration and scheduled send as distinct surfaces. They are referenced in copy and committed in the PRD, but not demoable.

Bulk sending IS in the prototype, and is NOT F20 (added 2026-09-16, PRD Rev 28). Two screens demo the stretch candidate F37, both labelled Stretch — not committed on-screen so a demo cannot be mistaken for a commitment: a Send to all clients action on the Pricing screen (F37(a) — the weekly round as a batch of per-account emails, with a review step stating recipient and email counts and that each client sees only their own standards) and a Newsletter composer on the Inbox screen (F37(b) — audience, subject, body, per-recipient preview, and an explicit unsubscribe/consent notice carrying OQ-62). Both are demo-only and send nothing. Update 2026-10-09 (PRD Rev 57): F37 is now committed to Phase 2 as F37-a (the price broadcast) and F37-b (bulk email to a saved contact list, adding a per-send summary of deliveries, opens and clicks that the Newsletter screen does not show), so the on-screen Stretch labels are out of date. The screens remain inputs to F37-a’s and F37-b’s specs, never F20 requirements.


F21 — Activity calendar & calendar sync — P1

PRD says: A calendar view of activities in day / week / list views with a left-rail filter of activity types and drag-to-reschedule; two-way calendar sync with Microsoft 365 via Graph (future events only; recurring events managed in the source).

Prototype: the Calendar toggle inside Activities — day-columns across the week, today highlighted, colour-dotted clickable chips.

Not in the prototype: day and list views (week only), the activity-type filter rail, and drag-to-reschedule. The external Microsoft 365 two-way sync isn’t modelled either — there is no connected-calendar state to show. All build-time items.


F22 — Contact sync (auto-pull from the connected mailbox) — P2

PRD says (Rev 107): Read each user’s Outlook contacts every hour, one way into the CRM; offer the ones the CRM does not hold on the user’s own From Outlook review list, where the user adds them (choosing the account) or dismisses them; fill only empty fields on contacts the CRM already holds. Matching by every email address keeps a person already in the CRM under any of their addresses from being added again; a person held under different addresses can still become two contacts.

Prototype gap: not represented yet. The F22 spec (.forge/specs/F22-contact-sync-spec.md, FR-10 and FR-11) defines the From Outlook page at /contacts/from-outlook, its button on the contacts page and a switch in the mailbox settings; they are drawn in crm-current/ before F22’s frontend work items are planned.

Scope note: F22 is P2 and is a named scope lever.


F23 — Data import & export (CSV/Excel) — P1

PRD says: An ongoing spreadsheet import beyond the one-time F4 migration — upload XLS/XLSX/CSV of leads, contacts, organizations, deals, buying standards or activities; auto-map columns to fields (creating custom fields during mapping); one row links the person + org + deal it contains; resolve duplicates by merge-or-create at finish. Plus CSV/Excel export of any filtered list view.

Prototype: only the one-time F4 migration wizard (mocked). General-purpose repeatable import/export with header mapping and list-view export isn’t built.

Phasing (PRD reconciliation note, 2026-08-06): the import engine is built in Phase 1 to serve F4’s migration; F23 in Phase 2 is the work of exposing it as a general-purpose user-facing tool. Do not read “F23 is Phase 2” as “no import code until Phase 2.”


F24 — Configurable pipelines (admin stages + probability + rotting) — P1

PRD says: Admins create and edit pipelines — name, add/reorder/rename stages, set each stage’s win probability (0–100%) driving the weighted forecast, and each stage’s rotting threshold in idle days (the clock resets on any activity, note, email or edit). Ships seeded with the two tea pipelines as editable defaults. Because AI features and automations key off stage semantics, stage edits are validated against the domain workflow (AD #11: a stable non-editable stage_type sits under the editable display name).

Prototype: Configure pipeline modal (gear icon on the Pipeline screen): reorderable stage rows (drag handle) with Stage name, Kind (Standard / Brief / Quote / Won-handoff), Win %, Rot (days), and delete — sample stages are locked and shown as “Sample (auto).” Add-stage row plus Delete this pipeline. New pipeline modal: Name + a checkbox to include the auto-driven sample stages. The seeded config carries per-stage prob, rot and kind, exactly the three attributes the PRD names.


F25 — Outreach sequences — P1

PRD says: A multi-step cadence of email steps and follow-up task steps, enrolled on a deal or lead. Reps build sequences from templates or from scratch; AI generates each step’s email with a chosen tone and length, and a human approves before anything sends. Enrollment can be manual or triggered by a lead/deal condition. Drives re-engagement of the triaged lead backlog and dormant accounts.

Prototype: Enrol in sequence modal (from the Account detail or Deal drawer): sequence picker; copy “AI drafts each email step… a human approves before anything sends.” The Outreach sequences panel on Activities shows each sequence’s name, target, enrollment count, and step list as “Day N” + step label under badge “AI-DRAFTED STEPS · YOU APPROVE.” Seeded sequences carry both email and task step kinds, matching the PRD.

Not in the prototype: the sequence builder (creating/editing steps), tone and length controls, and condition-triggered enrollment.


F26 — Buying standards & weekly pricing (deal line items) — P1

PRD says (Rev 27, 2026-09-15): there is no separate products catalog. The sellable record — for bulk and private label alike — is the client-specific Buying Standard: a unique, never-reused running number on one account, carrying tea grade, origin/region, brand (Thurson / Hyson / Akina / Ceylon Wild Harvest — OQ-20) and held certifications, plus its cost and price history. Standards are created, edited and archived (archiving keeps the price history and removes the standard from quoting and the weekly round). Standards attach to a deal as line items with quantity and discount, rolling up into deal value; the standards book is the single source of truth for the F9 cert-mismatch check and F7 quote line items. A separate price-lookup page is not built (F26-e dropped, PRD Rev 61); the Standards book (F26-b), the account page and the Tea Room’s round with its History (F26-f) cover finding a price.

Bulk pricing (confirmed 2026-08-03): the priced unit is a client-specific Buying Standard — a grade/blend spec a client buys, identified by a unique running number never reused across clients; a client typically buys 4–5 standards, each carrying its own weekly price. One price per standard per week — it does not vary by customer or destination market (PRD Rev 23, 2026-09-11, revising OQ-38) — and it is not volume-tiered. A published price holds until the next weekly Colombo auction, with a manual override — a single clock shared with the quote. The Tea Room sets and publishes weekly prices. The standards book retains price history and a per-standard cost used to compute gross profit at quote time. The published price is FOB Colombo in USD, with CIF and other currencies handled per-quote via the cost build-up. Private-label items are standards too (Rev 27, revising OQ-37); whether they are weekly-priced or quoted per deal is OQ-61.

Prototype — the catalog is gone; the Buying Standards book is the one sellable list (2026-09-15, harness PR #88). The Products nav entry, screen, detail panel and Add product modal were removed outright. The seed now carries two private-label standards alongside the bulk ones, and every surface that read the catalog reads standards instead: the quote picker (scoped to that account’s standards), the F9 certification check (deals carry standardNos, not productIds), global search (its placeholder now reads “Search accounts, deals, leads, quotes, standards, samples…”) and the deal form’s type-ahead. Standards are added, edited and archived from both the account section and the Pricing screen, gated on the manage-standards permission — the add / edit modal carries Client · Product / blend name · Grade · Type · Origin · Held certifications · Cost / kg · the four-field weekly price build-up (2026-09-16 — see the paragraph below), and archiving keeps the price history and drops the standard out of quoting and the weekly round (numbers are never reused, so create always mints a fresh one). The Pricing screen is reached by permission, not role (AD #26): a role holding View published weekly prices gets it read-only, without costs. (Prototype behaviour. Under AD #34, 2026-09-24, there is no separate published-price permission: buying_standard.view opens the whole book, costs included, and a role that should see only prices sees each account’s final USD price on the account page under account.view — drift row below.) The market axis went the day before (2026-09-14, PRD Rev 23): one price, one validUntil, one weekly series per standard; a Price / kg column on the account table; no destination-market dropdown on the quote.

Prototype — the weekly price is entered as a FOUR-FIELD BUILD-UP, not one number (2026-09-16). Empire’s weekly workbook derives a price in steps, and the prototype now shows all four: weekly price (LKR) → + overhead (LKR) → converted (USD) → final price (USD). Only the final USD figure is required — the three working figures are optional, so a price typed straight in is still a legitimate entry. The same four appear in both places a price is set: the add / edit-standard modal (where they now show on edit as well as create — previously the single opening-price field was create-only) and the Update this week’s price modal, which is where they change week to week. The seed derives the working figures back from each standard’s final price at 327.5 LKR/USD, so the demo reads as a consistent chain.

This is a settled team decision — Tharinda, 2026-09-17 — carried by PRD Rev 31 — the prototype renders it, it does not propose it. The PRD, architecture.md § Weekly Bulk Pricing Subsystem, the workbook schema doc and the client-facing PRD all carry the four-figure build-up; OQ-43 is refined, not reversed (USD is still the only published currency and still not a price-key axis — what changed is that the LKR working behind the figure is kept rather than discarded). The three working columns are in forge-et-be/docs/data-model.md §2.5 and on main (F26-a). The FX rate and overhead are kept per price row (PRD Rev 53, team decision — Tharinda, 2026-10-06): the rate is a column on the price row, which F26-c adds, and the overhead is the difference between the two LKR figures. The prototype’s seed still uses one rate and one overhead for the whole week; that is one case the model holds, not the rule. The unit of the base numbers stays open in OQ-59 (F26-c builds on LKR per kg).

One prototype-versus-model gap to know when demoing: the prototype now has two write paths into a price (standard-edit and the weekly modal), because a form that shows a field on create and hides it on edit reads as a bug. The real system has one, since price rows are append-only (AD #14) and an edit is a new row — reconciling the two is F26’s, and the prototype deliberately does not pre-empt it.

The two paragraphs below describe the 2026-09-11 re-homing that preceded this and are kept as history — read the Products-screen and per-market details in them as superseded.

Prototype (history) — bulk pricing was re-homed onto the ACCOUNT and a Tea Room Pricing screen on 2026-09-11. Until then the whole price board hung off the catalog product, which is the structural drift the table below used to lead with. The pricing data was unchanged — same standards, same numbers, same (standard, market, validity) grain (the market axis has since been dropped by PRD Rev 23) — but it moved to where it belongs:

  • Accounts screen — “Buying standards & prices” (see F1): the rows a rep actually reads, each expanding to that standard’s price board, history graph and full-history drawer.
  • Pricing screen (new, Tea Room’s workspace): every client’s standards at once — Standard · Client · Grade · Spec · Markets priced · Status (Published / Draft pending / Gap) — with a search over client, standard number, grade and market (never a dropdown: the client reports ~35,000 standards issued), a header showing this week’s validity window, published and draft-pending counts, and the unpriced-markets list that blocks quoting. Selecting a standard shows its price board, cost + profit floor, profit % per market, and price history. ↻ Update this week’s prices opens the same weekly modal as before, scoped to that standard.
  • Products screen — now the catalog it says it is — removed 2026-09-15 (PRD Rev 27); it had become a catalog with a standards summary line and no price board, and the private-label goods it listed are now standards on their accounts.
  • Role rendering (client/roles-and-permissions.md): cost, profit floor and profit % are Tea Room only (A-10 — this tightens the old behaviour, which showed cost to every role); publishing is Tea Room only (A-20); the Administrator sees the Pricing screen read-only (A-22’s no-fallback-publisher default); every other role has no Pricing nav entry, and the route is gated too, not just the nav button. Hidden, not greyed (design-system §9).
  • Modals: Add product to catalog — removed 2026-09-15; replaced by the add / edit / archive-standard modals described above; Update this week’s price (effective-from + valid-until dates with an end-after-start guard, the standard it is editing named in the banner, one New price input per destination market, Save draft / Publish this week’s price) — unchanged except that its Save/Publish buttons are now Tea Room only, and it is reachable from the account and the Pricing screen instead of the catalog.
  • Two affordances on these screens are team proposals, not client-confirmed — Import this week’s sheet (a button and an explainer; no parser, no file input) and Email this week’s prices to contacts (a toast; no compose flow). Both trace to a September 2026 follow-up meeting with no debrief filed. See the prototype README’s proposals list.

⚠️ Drift — smaller than it was, and the remaining rows are about temporality, not structure. Two rounds have closed the structural half: Buying Standards became the priced unit on 2026-08-31, and the re-homing above (2026-09-11) moved the price board off the catalog onto the account and the Pricing screen. What is left is the clock and the write model.

Prototype PRD / architecture.md Status
What is priced A client-specific Buying Standard with its own running number and cost, resolved through the account A client-specific Buying Standard — an entity in its own right, N:1 Account, with a unique running number never reused across clients. A client buys 4–5 of them ✅ Closed 2026-08-31
Where it is shown The account carries its standards and their prices; the Tea Room’s Pricing screen carries the weekly round across every client; the catalog links to them Price hangs off the standard, not the product; the Tea Room owns the weekly publish (OQ-39) ✅ Closed 2026-09-11
Who may publish Tea Room only; Administrator read-only; no nav entry or route for anyone else Holders of price.publish — the Tea Room in the recommended configuration (AD #34, 2026-09-24; was “Tea Room only”) ✅ Closed 2026-09-11 — the prototype’s gate is a permission and matches the recommended configuration
Cost visibility Cost, floor and profit % render on the Pricing screen and the quote only, behind the cost permission — never on the account section, which is a sales view (2026-09-15) Reps see published prices and their quote’s margin %, never cost screens (A-10, now the recommended configuration). AD #34 (2026-09-24) has no cost permission: buying_standard.view covers the whole build-up — costs, margins, floor, LKR figures — and account.view shows only the final USD price on the account page ✅ Closed 2026-09-11, tightened 2026-09-15 for where costs render; ⚠️ re-opened 2026-09-24 for which permission — the prototype’s separate cost and published-price permissions do not exist in AD #34’s catalog
Publication A draft → published transition: drafts are excluded from quoting by _resolveStandardPrice and shown as Draft — not quotable A draft → published state transition, audited. Draft prices are invisible to quoting; publishing stamps the validity window and writes an audit entry ◐ Shape right, no audit entry — the prototype records no publisher or timestamp
Price rows Overwritten per week; history is a separate appended array Effective-dated rows, never updated in place (AD #14). Every read is “price for standard X as of date Z” ⚠️ Open — the prototype is not a model of the write path
Validity anchor Two typed dates (effective-from + valid-until) with an end-after-start guard Validity anchors to a numbered auction_sale row, not a weekday or ISO week. Sale days shift week to week, so “the next auction” is not derivable from the calendar (SP-ARCH-003 §2.3) ⚠️ Open — deliberate: a forward auction calendar is a thing somebody has to maintain
Brand No brand field on the Buying Standard or the Deal Required — own-brand goods are first-class (OQ-20; the attribute lives on the standard since PRD Rev 27) ⚠️ Open
Catalog fields (retired 2026-09-15 — the add-product modal went with the catalog; the add / edit-standard modal carries Client · name · Grade · Type · Origin · Held certifications · Cost / kg · the four-field weekly price build-up) — ✅ Closed by PRD Rev 27
Products catalog Removed outright (2026-09-15) — the Buying Standard is the sellable record for bulk and private label PRD Rev 27 says the same; the backend’s shipped product table / catalog package / product.* keys are a recorded hand-off (Tharinda) ✅ Closed 2026-09-15
Standards lifecycle Add / edit / archive from the account section and the Pricing screen, gated on the manage-standards permission; archive keeps history, drops the standard out of quoting and the weekly round PRD Rev 27 records the same lifecycle; the data model’s buying_standard.is_active is the archive flag ✅ Closed 2026-09-15
Private-label pricing Private-label standards seeded with a price like bulk ones OQ-61 — weekly-priced or quoted per deal? Default: quoted per deal ⚠️ Open

The prototype is a good illustration of the pricing UX and now of its ownership — where a price lives, who publishes it, and who may see the cost behind it all read correctly. It is still not a model of the pricing write path: prices are mutated in place with no audit row and validity is two typed dates rather than a numbered auction sale. Building those as drawn would keep the wrong clock and lose temporality, which cannot be retrofitted without rewriting every read path (AD #14).

Decided 2026-09-11 — the prototype’s per-market price board is superseded. Empire said on 2026-09-09 that a standard’s price does not vary between customers or regions; the weekly price workbook they shared afterwards carries one row per standard per week, and the few cross-tab differences in it are data drift and mis-keyed numbers, not a pricing rule. PRD Rev 23 records one price per standard per week and revises OQ-38. The prototype’s per-market board was collapsed by harness PR #88 (2026-09-15): the account section, the Pricing screen and the quote builder now show one price per standard, and the market dropdown is gone. The data-model §2.2 change landed in forge-et-be (PR #20, Tharinda — AD #31).

Spike status — SP-ARCH-003 is resolved and merged (2026-08-21). The bulk-pricing data model is settled and DDL-verified against PostgreSQL 17 — an assertion suite gated by a bidirectional check that the document and the executable proof scripts have not drifted apart. (FS-14 removed the split’s core-only acceptance proof and merged the proof scripts onto one public schema; the drift check remains.) Two consequences for anyone specing F26:

  • The authoritative schema is forge-et-be/docs/data-model.md §2, not bulk-tea-pricing.md, whose §7 DDL is superseded in four places (the priced unit, currency/Incoterm leaving the price key, the provenance FK’s home, and cost moving to its own grain). Its domain half stands. The PRD’s F26 paragraph still points at the research doc as “a candidate data model” — that pointer is now out of date; read the reconciliation table in the data model instead.
  • LineItem joins the entangled entities carrying a typed 1:1 extension table (line_item_bulk_price). A bulk quote line’s price provenance points at the pricing tables, so it lives in that extension table rather than as columns on line_item. AD #29 (2026-09-07) retired the reuse goal, and AD #31 (2026-09-09, FS-14) collapsed the split to one public schema — so the former core → tea FK guard that once forced this placement is gone. The typed-extension shape stays as the data model (data-model.md §2) until F26 revisits it; that data model is now owned by Tharinda (AD #31).

Both spike PRs are on main — forge-et-harness#21 and forge-et-be#6, merged 2026-08-21. F26’s blocked_by is clear, FS-2 is unblocked, and data-model.md §2.13 enumerates which of the two builds what.

Client dependency: Tea Room price list plus costs.


F31 — Global search — P0

Dropped from V1 on 2026-10-11 (PRD Rev 60). Not built; each list screen has its own search. The text below is kept as the record of what was planned.

PRD says: Persistent search across accounts, contacts, deals, leads, quotes, buying standards and samples, matching on name, company, email, id and key fields, returning grouped results with click-through, scoped to each user’s record visibility.

Prototype: top-bar search with placeholder “Search accounts, deals, leads, quotes, standards, samples…” (standards since 2026-09-15). It is wired in the current build — live filtering across six record types, results grouped by type with a label and sub-line, capped at five per group, each result navigating straight to the record and clearing the query. Friendly “No matches” empty state.

Two gaps: contacts are not searched (the PRD lists them), and there is no visibility scoping — the prototype has no per-user record ownership to scope against.

Correction to earlier notes: the prototype’s search was decorative in the 2026-07-06 build, and both prototype-inventory.md and the PRD’s F31 wording (“replaces the prototype’s decorative search bar”) still describe it that way. It has since been implemented.


F32 — List/table views, saved filters & bulk actions — P1

PRD says: Every core entity gets a sortable, column-configurable list/table view alongside its board/detail views. Users save filtered views (personal or shared) and run bulk actions on a selection — edit a field, reassign owner, add an activity, enrol in a sequence, delete, or export. With F17, this is the reporting surface in place of a separate report builder.

Prototype gap: the Activities screen has a grouped list with filter pills, the Pricing screen has a fixed table, and Quotes/Accounts/Leads have master-detail lists — but there is no column configuration, no saved-view mechanism, and no bulk-action toolbar anywhere. A build-time feature described in the PRD, not demoable.


F33 — File attachments — P1

PRD says: Attach files to any core record — deals, accounts, contacts, quotes, samples and product briefs. Central for artwork, packaging mock-ups, buyer POs, spec sheets and certification PDFs. Files list uploader, date and size; uploads are validated (type/size) and scanned, and access is scoped to the record’s visibility.

Prototype: the Files section inside the Deal Detail drawer — always visible, +Attach action, entries showing file name, size · uploader · when. The empty state names the artifact types this is for.

Not in the prototype: attachment on records other than deals, and the validation/virus-scan pipeline (Foundation slice 11; AD-O-4 open).


F34 — Admin custom fields — P1

PRD says: Administrators define custom fields per entity (account, contact, deal, lead, quote, buying standard, sample) — text, number, date, single/multi-select and similar — on top of the typed tea-domain schema, so business-critical Pipedrive fields migrate as first-class fields. Custom fields appear on forms, list views, filters and import mapping, and are admin-audited as schema changes. Stored as a JSONB column per entity (AD #8) — distinct from the typed core/tea extension tables.

Prototype gap: no admin custom-field builder and no custom-field rendering anywhere — forms, list views, filters or import mapping. A PRD-only feature at this stage.


Companion app

F36 — Trade-show lead capture app (PWA) — P1

PRD says: A standalone installable PWA in its own repository (forge-et-pwa), hosted at its own URL (AD #20/#22), so reps capture leads on the exhibition floor without opening the CRM. Photograph a business card or scan a badge QR — a capture whose upload fails is kept on the phone and sent again when the app is open with a connection (F36-a; the offline queue, F36-e, was dropped 2026-10-11 — PRD Rev 64) — an AI vision call reads the card into structured fields, and a research/scoring pass on the same AIProvider seam (human-reviewed) ranks the lead, and the app tells the rep in an in-app notification — the capture app sends no email and uses no WhatsApp (AD #42, PRD Rev 94, 2026-11-12; until then a notification email via SES). A captured lead waits in the app until a person reviews it: converting it creates the CRM lead through the F11 intake with lead-source tracking, owned by whoever converted it; rejecting it keeps it in the capture app only. Cards and badges are captured one at a time, and using the app needs its own key, capture.use (PRD Rev 95, 2026-11-12; until then captured leads went straight to the F11 triage intake). Added 2026-09-09 (PRD Rev 23): badge QR confirmed as needed; an existing-client check during the scan (whether the organisation or person is already a customer and how often Empire deals with them — needs an account/contact lookup from the app); a same-day generic follow-up email to stand visitors (dropped 2026-10-11, PRD Rev 63 — OQ-60 closed); campaign planning is already in the POC and is not a new ask.

Scope: full — Option C, decided 2026-08-18: capture + AI card read + research/scoring + notifications (in-app since 2026-11-12). The reduced capture-and-feed shape is retained as a descope lever at the mid-November checkpoint. Organizer-provided bulk attendee lists remain an F23 import + F11 triage path; this feature is per-lead floor capture, and since PRD Rev 96 (2026-11-12) also planning before a show in Phase 1: the Plan tab’s campaigns, exhibitor list upload (read without AI), exhibitors added by hand, visit notes and visited marks (F36-a), and the research and ranking of every exhibitor (F36-c). The reduced capture-and-feed shape keeps the review in the app.

Not in the CRM prototype — F36 is a separate application. Its reference build is the near-complete POC published read-only as the sibling forge-et-pwa-poc repo, whose own plan docs record most of its epics done: a deployed backend, an API-integrated (not hardcoded) frontend, and four post-MVP features (campaign-aware scoring, bulk-pile/camera-roll capture, pre-show exhibitor targeting, expo intelligence). A browsable frozen snapshot with demo data baked in sits at .forge/design/prototypes/pwa/ — double-click it, no server needed.

Porting rule: the frontend is the portable half; the POC’s Python/Supabase/Fly backend does not port — its stack decisions all yield to AD #19–#23, making it a proven reference for the pipeline, API contract and prompt design rather than reusable code. Never write to the POC repo. Theme alignment is still outstanding, and the F36 scope delta against the POC’s real contents is tracked as OQ-55.

Delivery: a parallel work-stream alongside the Phase 2 work (placed there at Gate 3), with the descope checkpoint held during Phase 2, date to be set (client/project-timeline.md §2).


Dropped — not built, and not planned after V1

F27 (website chatbot / live chat), F28 (email campaigns), F29 (data enrichment), F30 (LinkedIn integration), and F35 (sales goals & targets) have no representation in the prototype — no screens, no modals, no mentions.

They were dropped on 2026-10-11 (PRD Rev 66) and are not planned after V1 either. Before that they were deferred from V1 outright: A scope decision on 2026-08-20 (PRD Rev 16) removed every “promote to V1 if the Pipedrive audit shows…” clause: the audit-contingent framing left V1 scope undetermined until week 1 against a low-contingency schedule, and an add-on promoted late is the least affordable kind of scope growth.

The Pipedrive add-on questions (OQ-23, OQ-29) decide no scope. They give early warning where Empire relies on one of these today, so any gap against the “nothing lost on migration” promise is raised with the client as a change request, not discovered at UAT.


What the prototype gets right that the PRD states more abstractly

  • Human-in-the-loop is enforced in the UI, not just documented: the Sales Rep role genuinely cannot approve a quote; every AI output carries explicit “you approve” framing; margin and pricing fields are manual-entry only; the AI-drafted lead reply omits pricing by design and marks itself “edited by you” once touched.
  • The sample↔pipeline coupling (F6↔F2) is the single most detailed piece of business logic in the prototype and is worth walking slowly in any review — it is the concrete demonstration of “models the tea export workflow as first-class” from the PRD’s problem statement, including the auto-created follow-on round when an outcome is a rejection.
  • The export-document rules engine (F10) — base + per-country + per-certification composition over a real reference-data set — is the second-best-worked example, and closely matches the PRD’s intended model.

Things to flag rather than demo as final (prototype/PRD drift)

Area Prototype shows PRD / decisions now say
Bulk pricing write model Buying Standards are the priced unit and live on the account (2026-08-31 / 2026-09-11), but price rows are still overwritten per week with no audit entry Priced unit is a client-specific Buying Standard (N:1 Account, unique running number), effective-dated rows, publish as an audited draft→published transition
Price validity anchor Two typed dates — a calendar-week model Anchored to a numbered auction sale; sale days shift, so the next auction is not derivable from the calendar
Roles 4 in the switcher 6 recommended — adds Tea Room and Executive/Management (read-only); none predefined — only an editable IT Admin role is seeded (AD #34)
Access model and sharing A View / Manage / Act catalog, a non-deletable system Administrator, role-name checks, owner-or-manager-only sharing that cannot be passed on, a picker that offers users who cannot see the record, an unguarded share removal, an invitation toast The AD #34 / AD #35 model — see the F5 drift table above (added 2026-09-24)
Weekly price publishing Ungated Resolved 2026-09-11 — Tea Room only; Administrator read-only; no nav entry or route for other roles Holders of price.publish — the Tea Room in the recommended configuration (AD #34)
Quote approval Every quote gated on Sales Manager+ At-or-above the GP floor needs no approval; only sub-floor escalates, to a holder of quote.approve_sub_floor — the Managing Director role in the recommended configuration (AD #34)
Quote margin Manually typed by a human System-computed gross-profit % from the standard’s cost, checked against a floor
Payment terms Absent from the quote Required field — LC / Open Account / DA / CAD / advance
Brand attribute No brand field on the Buying Standard or the Deal Own-brand goods are first-class, confirmed in scope (the attribute lives on the standard — PRD Rev 27)
Migration triage One bucket reads “Spam — archived, not imported” Import everything, preserve original Pipedrive IDs, triage after import
Global search Wired, but omits contacts and has no visibility scoping Not built — dropped 2026-10-11 (PRD Rev 60); each list screen has its own search
Calendar Week grid only Day / week / list views, activity-type filter rail, drag-to-reschedule, two-way M365 sync
Catalog fields Retired 2026-09-15 — the catalog and its add-product modal are gone PRD Rev 27: no products catalog; the Buying Standard is the sellable record
Bulk price axis Resolved 2026-09-14/15 (harness PR #88) — one price per standard everywhere; the market dropdown is gone One price per standard per week (PRD Rev 23)
Private-label pricing Private-label standards carry a price like bulk ones OQ-61 — weekly-priced or quoted per deal (default: per deal)
Quote validity A validity clock per market price Single shared clock tied to the weekly auction with manual override — the prototype’s approach is a close practical match

Also remember: the dashboard’s five KPI figures, the AI Morning Briefing narrative, the “What’s stuck” rows, the ranked-lead cards, and the backlog count are illustrative placeholders in the current prototype build — literal values in the source, not computed. Real numbers arrive with the backend; their presence is not evidence the logic exists.


Verification note

Checked on 2026-08-21 against the prototype source, and against project-prd.md at PRD Rev 16 (2026-08-20), with project-prd-signals.md, project-prd-history.md, features.md and architecture.md used to confirm open-question status, priorities and structural decisions.

Repo state at time of writing. All four repos synced to origin/main: harness bd8a6fd, forge-et-be 526a27d, forge-et-fe 08e699f, forge-et-pwa 22b4050. project-prd.md, project-prd-signals.md, project-prd-history.md, features.md, prototype-inventory.md and the prototype bundle itself were unchanged across that sync, so nothing in the cross-reference moved. What did land — AD #25 (Spring Boot 4.1.x + Spock 2.4-groovy-5.0), PWA-snapshot opening notes, and lessons L-006/L-007 — does not bear on this document.

Re-checked after the SP-ARCH-003 PRs landed (harness f7fe4cf, forge-et-be e106fb1, both 2026-08-21). Only the F26 entry moved: its pending-merge caveat is gone and the schema pointer is now live. Nothing else in the cross-reference is affected — the two PRs touched the pricing schema and the harness’s record of it, not the PRD or the prototype.

Re-checked 2026-09-24 for the access-model decisions (AD #34, AD #35, AD #36) and the info@ decision. The F5 entry gains a note on what is now settled and a second drift table for the prototype’s access and sharing behaviour; its first drift table, the F26 publishing and cost-visibility rows, the F20 info@ sentence and the closing flag table are restated in permission keys. The new drift claims were checked in the prototype source (crm/crm-prototype.dc.html) on 2026-09-24: seedPermCatalog and its View / Manage / Act kinds, the outward-acting toast and counts, the system role and its badge and “Cannot be deleted” text, setUserRole and toggleGrant, the add-user toast, the share picker’s “No lead access” marking, reachesWithoutShare, mayShareLead, the “cannot pass it on further” footer and the unguarded share-removal button. The prototype itself was not changed.

When to re-verify. This document is derived: it merges two live sources and holds no authority of its own. Re-check it against the prototype bundle and the PRD on any PRD revision, any change to .forge/design/prototypes/crm/, and before specing a feature whose entry is load-bearing. A section that has drifted is worse than an absent one, because it reads as current.

What was verified directly in the prototype source — every drift claim and every “not in the prototype” statement in this document, plus: the role list and the quote-approval gate; the login handler; the sample→deal-stage mapping and auto-created follow-on round; the AUTO badge and drop refusal; the eight readiness-checklist labels; the absence of a brand field, payment terms and drag-to-reschedule; the Add-product modal’s field set; the New Deal modal’s field set; the products table columns; global search’s wiring, its six record types and its omission of contacts; the deal-drawer section gating conditions; the pipeline-config stage attributes (prob, rot, kind); the sequence step kinds; the migration wizard’s “Spam — archived, not imported” bucket; the lead-source options; and the dashboard KPI values being literals rather than computed.

What was not re-derived from source — routine descriptive detail carried forward from the earlier draft of this document where spot-checks agreed: exact button labels, badge captions, modal field orderings, and list-card compositions on screens whose structure was otherwise confirmed. These are low-risk (they describe surface copy, not behaviour or data model) but they are inherited, not independently re-read. If a spec is going to hang on one of them, open the prototype and look.

Two harness artifacts were found stale in the process and are not used as sources here:

  • .forge/discovery/inventories/prototype-inventory.md — captured 2026-07-06 against a far smaller prototype; misses nine screens’ worth of subsequent work and states as absent several features that now exist.
  • project-prd.md F31’s phrase “replaces the prototype’s decorative search bar” — search is now implemented in the prototype.

Generated from .forge/design/prototypes/feature-detail.md by .claude/lib/render-docs-html.js. Markdown is canonical.