From 6f50c1dc6c07cf5fa89a29fe1045f6dedf39b91a Mon Sep 17 00:00:00 2001
From: James <james@jongsma.me>
Date: Sun, 22 Mar 2026 06:01:33 -0400
Subject: [PATCH] chore: auto-commit uncommitted changes

---
 .DS_Store               | Bin 0 -> 10244 bytes
 ._.DS_Store             | Bin 0 -> 4096 bytes
 docs/._DATAROOM-SPEC.md | Bin 0 -> 4096 bytes
 docs/DATAROOM-SPEC.md   | 836 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 836 insertions(+)
 create mode 100644 .DS_Store
 create mode 100644 ._.DS_Store
 create mode 100644 docs/._DATAROOM-SPEC.md
 create mode 100644 docs/DATAROOM-SPEC.md

diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..38d6848161b439ced1b0b0947598476768436dd3
GIT binary patch
literal 10244
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

literal 0
HcmV?d00001

diff --git a/._.DS_Store b/._.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..28c42fb20a1f27e695fb64323501fc6476578b13
GIT binary patch
literal 4096
zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIhYCu0iY;W;207T
z1d#ygV5q>VXjE`C1V%$(Gz3ONU^E0qLtr!nMnhmU1V%$(Gz3ONU^E1%90H6$^FSC3
z<U%qsixrAei}Op1l2aAZ@{6(+GV@AO^GY)F^AdA%Div~4(@GSQauV~hfn8mwt|3jK
N`XBBU83wuk{{h!d9M%8;

literal 0
HcmV?d00001

diff --git a/docs/._DATAROOM-SPEC.md b/docs/._DATAROOM-SPEC.md
new file mode 100644
index 0000000000000000000000000000000000000000..05857d6067852e7f074ad02db030e8fd2a68d3fb
GIT binary patch
literal 4096
zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIUt(=a103vf+zv&
zU;(n1plM+SngkLTU|^6+&d=3LEGWoH)yqjNE-5WeO-V^CNmULAhUj4w0n*$I45A2i
z1x5K~sd<Tc$*DjoMtLC7$-rQakk3smNd%gaXqD~j;**$^niFrHno^mbRFPMdXr5A4
zkd$SXZIWA1VwPEC0@PeowLcR`F>pH;$%1G`CWh6i>AeXz<=1_RmVKqEK6~f9%=fFh
zsv<Aiv#ma*W^+aPiqnqc%5%F#CO_Grt|2_rW2d5d`GJK~7f%$Je(Y@3<Bv(<?_Vi-
zO?|L<%M!V>raECF&8)ZjZk^|R_$DMx{6vo4JnicYr!3vhS+7|vaJHc}$7F*npX94c
z#wJURm27<H)%YB6+i<+!+s{40M*Y;a(*^rM?ivN7Aut*OqaiRF0;3@?8UmvsFd71*
zAut*OqaiRF0{BCK5hxA9U?3Ngky)%zlv<o$T9llskd|MRt&o{llA2eNnV*-KlT)dX
flbTkdkd%{{mksO-Lv;;l3f2E`ugEaS{r?XD{9=o%

literal 0
HcmV?d00001

diff --git a/docs/DATAROOM-SPEC.md b/docs/DATAROOM-SPEC.md
new file mode 100644
index 0000000..0bad070
--- /dev/null
+++ b/docs/DATAROOM-SPEC.md
@@ -0,0 +1,836 @@
+# Dataroom Architecture
+
+| | |
+|---|---|
+| **Version** | 1.3 |
+| **Date** | 2026-03-22 |
+| **Author** | Johan Jongsma |
+| **Status** | Draft — for review by Misha |
+
+*How files, request lists, visibility, tasks, and notifications fit together.*
+
+## The Problem with "Multiple Datarooms"
+
+Traditional deal platforms (and DropBox-based workflows) create separate folder trees for each buyer. This causes:
+
+- **File duplication** — the same income statement exists in 5 folders, each potentially a different version
+- **Sync nightmares** — Seller uploads v3, IB updates Buyer A's folder but forgets Buyer B
+- **No single source of truth** — which copy is current?
+- **Rigid structure** — adding a buyer means cloning an entire folder tree
+
+DealSpace solves this by storing every file **once** and controlling **who can see it** through visibility rules. A "dataroom" is not a place where files live — it's a **lens** that shows each party the files they're allowed to see.
+
+---
+
+## Parties
+
+| Role | Description |
+|------|-------------|
+| **IB** (Investment Bank) | Runs the deal. Pays for DealSpace. Controls all visibility and routing. The intermediary between Seller and Buyers. |
+| **Seller** | The company being sold. Uploads documents when requested. Never sees who is asking — all requests come through the IB. |
+| **Buyer / PE** | Interested parties evaluating the company. Each buyer sees only what the IB has shared with them. Buyers never see each other. |
+
+---
+
+## Organizations & People
+
+Organizations and people exist **across deals** — they're platform-level entities, not per-project copies. When an IB adds "Blackstone" to three different deals, it's the same org record, with the same people. Only their **role** and **permissions** vary per deal.
+
+### Organizations
+
+```
+org_id          — unique, platform-wide
+name            — "Blackstone"
+domains         — ["blackstone.com"] (for auto-matching users)
+logo            — URL
+website, phone, address, etc.
+```
+
+An org is created once (typically via scrape when first encountered) and reused across deals. When the IB looks up `blackstone.com` for a second deal, DealSpace returns the existing record — no re-scrape.
+
+### People
+
+People belong to an organization. Their profile is platform-level, but their **role in a deal** is per-deal.
+
+```
+person (platform-level):
+  name            — "Sarah Chen"
+  email           — "schen@blackstone.com"
+  title           — "Managing Director"
+  phone, photo, bio, linkedin
+
+deal membership (per-deal):
+  person          → Sarah Chen
+  org             → Blackstone
+  deal_role       — "lead_contact" | "reviewer" | "uploader" | "viewer"
+```
+
+### Deal Roles
+
+Within a deal, each person has a role that determines what they can do and what gets routed to them:
+
+| Deal Role | Description | Typical Person |
+|-----------|-------------|----------------|
+| `deal_lead` | Primary contact for this org in the deal. Receives all communications. Can delegate. | MD, Partner, VP |
+| `reviewer` | Reviews and approves documents before they go up the chain. | Director, Senior Associate |
+| `uploader` | Uploads documents to answer requests. Cannot approve. | Associate, Analyst, Assistant |
+| `viewer` | Read-only access to the dataroom. No tasks. | Observers, junior staff, advisors |
+| `admin` | Manages the org's team within the deal. Can add/remove people. | Office manager, deal coordinator |
+
+A person can hold multiple roles (e.g., `deal_lead` + `admin`).
+
+### Automated Routing
+
+Deal roles enable semi-automated task routing. When the IB assigns a task to an org (not a specific person), DealSpace routes it based on roles:
+
+**Inbound request to Seller org:**
+```
+IB assigns "Provide Statement KLM" to Seller org
+  → auto-routes to Seller's deal_lead (CFO)
+  → CFO can accept, or delegate to a reviewer/uploader in their org
+```
+
+**Category-based routing:**
+Organizations can configure routing rules per document category:
+
+```
+Seller org routing rules:
+  Financial/*        → CFO (deal_lead)
+  Legal/*            → General Counsel (reviewer)
+  HR/*               → VP People (reviewer)
+  Operations/*       → COO (reviewer)
+  IT/*               → CTO (reviewer)
+  (default)          → CFO (deal_lead)
+```
+
+When a request for "Employee benefits summary" comes in tagged `HR`, it skips the CFO and goes directly to VP People. The CFO still has visibility (as deal_lead) but doesn't have to manually route every request.
+
+**Approval chains:**
+The routing rules also define who approves on the way back:
+
+```
+Assistant uploads "Employee Benefits Summary.pdf"
+  → auto-returns to VP People (reviewer) for approval
+  → VP People approves → auto-returns to CFO (deal_lead)
+  → CFO approves → returns to IB
+```
+
+The IB can override any auto-routing — these are defaults, not constraints.
+
+### The IB's Own Team
+
+When the IB creates a deal, their org is automatically added as the first party. The 3-4 bankers working the deal are visible in the Parties tab, with roles:
+
+```
+Muskepo (IB):
+  Michael Muskepo — deal_lead
+  Sarah Kim       — reviewer
+  James Park      — uploader, admin
+```
+
+This makes it clear to the Seller and to IB management who's running the deal.
+
+### Advisors
+
+Sellers often bring their own advisors — accountants, lawyers, consultants. These are separate orgs added to the deal with their own roles:
+
+```
+Seller: Acme Corp
+  CFO, COO, etc.
+
+Seller's Counsel: Baker McKenzie
+  Partner (reviewer) — reviews legal docs before release
+  Associate (uploader) — prepares and uploads legal docs
+
+Seller's Accountant: Deloitte
+  Partner (reviewer) — reviews financial docs
+  Manager (uploader) — prepares financial docs
+```
+
+Each advisor org has its own routing rules and visibility scope. The IB controls what each advisor can see — typically limited to their domain (legal advisor sees Legal/*, not Financial/*).
+
+---
+
+## The Deal Lifecycle
+
+### Phase 1: Preparation
+
+1. IB creates the deal in DealSpace
+2. IB loads their **standard request list** (template) — the checklist of everything they typically need from a seller
+3. IB adds the Seller org to the deal
+4. IB assigns requests to people at the Seller org
+5. Seller uploads documents to answer each request
+6. These uploads form the **internal dataroom** — only visible to the IB
+
+### Phase 2: Initial Offering
+
+7. IB reviews the internal dataroom
+8. IB selects a subset of documents to include in the offering
+9. IB shares those documents with "all buyers" — this is the **public dataroom**
+10. Buyers are invited to the deal and see only the shared documents
+11. Buyers receive a notification: "N documents available"
+
+### Phase 3: Due Diligence
+
+12. Each buyer submits their **own request list** — questions and document requests specific to their evaluation
+13. IB receives these requests. For each one, IB either:
+    - **Links an existing file** — "we already have this from Phase 1"
+    - **Goes back to the Seller** — assigns a new task to get the information
+14. When the Seller provides new documents, IB decides visibility:
+    - Share with the requesting buyer only
+    - Share with all buyers (if it's common-sense information)
+15. When sharing with all buyers, others are notified via batched digest
+
+### Phase 4: Narrowing
+
+16. Some buyers drop out, some advance
+17. IB may revoke access for eliminated buyers
+18. Remaining buyers get deeper access — more sensitive documents shared
+19. Process repeats until deal closes
+
+### Phase 5: Confirmatory Due Diligence
+
+20. Preferred buyer selected — deal enters final phase
+21. Many documents are **refreshed** (updated financials, revised contracts, etc.)
+22. Refreshed documents replace the originals silently — no new-document notification
+23. Buyer already has access; they see the latest version next time they open it
+24. New documents in this phase are shared directly, also without fanfare
+25. The dataroom is now a living reference, not a drip feed
+
+---
+
+## Data Model
+
+### Objects (files)
+
+Every file is stored exactly once.
+
+```
+object_id        — unique identifier
+project_id       — which deal this belongs to
+filename         — "Q3-2025-Income-Statement.pdf"
+category         — ["Financial", "Historical", "Income Statements"]
+stage            — draft | review | published
+uploaded_by      — user who uploaded it
+uploaded_at      — timestamp
+```
+
+### Document Versioning
+
+When a document is updated (e.g., Seller uploads a refreshed income statement), the new version does **not** go live automatically. It follows an approval flow:
+
+```
+Seller uploads v2 of "Income Statement Q3"
+  → v2 stored as pending, v1 still served to buyers
+  → Anonymization runs on v2 (using existing entity registry)
+  → If no new entities detected and deal is in confirmatory stage:
+      auto-approve → v2 replaces v1 silently
+  → Otherwise:
+      IB reviews anonymized v2 → approves → v2 replaces v1
+```
+
+Once approved:
+- v2 **replaces** v1 — all existing answer links and visibility rules carry over automatically
+- v1 is retained in version history but no longer served by default
+- Buyers who already downloaded v1 see v2 next time they open the dataroom
+
+**Notification behavior depends on deal stage:**
+
+| Deal Stage | Version Update Behavior |
+|------------|------------------------|
+| Phase 2-3 (active DD) | Notify buyers: "Updated document available" |
+| Phase 4 (narrowing) | Notify only if IB explicitly flags it |
+| Phase 5 (confirmatory) | Silent replacement — no notification |
+
+- IB can always see the full version history and compare versions
+- Audit log records who downloaded which version and when
+- If a buyer downloaded v1 and v2 replaces it, the audit log retains both records
+
+### Folder Structure
+
+The `category` field is a list of tags that creates the illusion of a folder tree:
+
+```
+Financial/
+  Historical/
+    Income Statements/
+      Q3-2025-Income-Statement.pdf    ← category: ["Financial","Historical","Income Statements"]
+      Q4-2025-Income-Statement.pdf
+  Projections/
+    ...
+Legal/
+  Corporate/
+    Articles of Incorporation.pdf     ← category: ["Legal","Corporate"]
+```
+
+This is a **UI presentation of tags**, not actual nested storage. A file can appear in multiple categories. The IB's "standard dataroom structure" is a category template applied to new deals.
+
+### Request Lists
+
+The driver of all document flow. Three types in a typical deal:
+
+| Request List | From | To | Purpose |
+|-------------|------|-----|---------|
+| IB Standard RL | IB | Seller | "Give us everything we need to sell your company" |
+| Buyer A RL | Buyer A | IB | "We need these specific things to evaluate" |
+| Buyer B RL | Buyer B | IB | Different buyer, different questions |
+
+Each request list contains **requests** — individual line items like "Provide audited financial statements for the last 3 years."
+
+### Answer Links (many-to-many)
+
+A single file can answer multiple requests from multiple request lists.
+
+```
+Request: "Audited financials 2023-2025"  (from IB Standard RL)
+  └── links to → Q3-2025-Income-Statement.pdf
+
+Request: "Historical P&L"  (from Buyer A RL)
+  └── links to → Q3-2025-Income-Statement.pdf  ← same file, different request
+
+Request: "Revenue breakdown by quarter"  (from Buyer B RL)
+  └── links to → Q3-2025-Income-Statement.pdf  ← same file again
+```
+
+The file exists once. Three requests point to it. No duplication.
+
+### Q&A (Text Answers)
+
+Not every request needs a document. Buyers often ask questions that require a text answer:
+
+- *"What is the customer concentration?"*
+- *"Are there any pending litigations?"*
+- *"What's the current headcount by department?"*
+
+These are handled as **text answers** on a request — same routing and visibility rules as document answers, just without a file attachment.
+
+#### LLM-Suggested Answers
+
+When a buyer asks a question, the answer may already exist — buried in a document that was uploaded for a completely different request. The LLM scans the existing document set and suggests answers:
+
+```
+Buyer B asks: "What is the customer concentration?"
+
+LLM finds: In "2025-Annual-Report.pdf" (uploaded for Buyer A's request
+"Revenue breakdown"), page 14 states: "Top 5 customers represent 42%
+of revenue, with the largest customer at 11%."
+
+Suggested answer: "Top 5 customers = 42% of revenue; largest = 11%
+(source: 2025 Annual Report, p.14)"
+```
+
+The IB reviews the suggestion, edits if needed, and approves. The answer is posted to Buyer B's request with the source document optionally linked.
+
+This works because:
+- Documents are flat with content summaries — the LLM can search across all of them
+- The answer might come from a document uploaded for the IB's own RL, or from a different buyer's request
+- Buyers never see that the answer was sourced from another buyer's request — they just see the answer
+
+#### Q&A Visibility
+
+Same rules as documents:
+- IB sees all Q&A across all buyers
+- Each buyer sees only their own questions and the answers shared with them
+- Seller sees questions as "IB asks..." — never the original buyer
+
+### Object Visibility
+
+Who can see each file is controlled by explicit visibility rules.
+
+```
+object_id    — which file
+scope        — "internal" | "all_buyers" | "org:{org_id}"
+granted_by   — which IB user authorized this
+granted_at   — when
+```
+
+A single file can have multiple visibility entries:
+
+| object_id | scope | meaning |
+|-----------|-------|---------|
+| doc-123 | `internal` | IB can see it (always present) |
+| doc-123 | `all_buyers` | Every buyer in the deal sees it |
+| doc-456 | `internal` | IB only — not shared yet |
+| doc-456 | `org:buyer-A` | Only Buyer A sees this |
+| doc-789 | `internal` | Uploaded by Seller, under IB review |
+
+#### How Each Party's "Dataroom" is Derived
+
+**IB (internal view):** All objects in the project. Plus metadata showing sharing status ("not shared", "shared with all", "Buyer A only").
+
+**Seller:** Objects they uploaded + objects the IB explicitly shared with them (e.g., the request list, IB comments).
+
+**Buyer A:** Objects where visibility scope includes `all_buyers` OR `org:buyer-A`. This is their "dataroom." They have no knowledge that other documents or other buyers exist.
+
+**Buyer B:** Same logic, different org_id → completely different view of the same underlying file set.
+
+---
+
+## RBAC
+
+### Permissions Matrix
+
+| Action | IB | Seller | Buyer |
+|--------|-----|--------|-------|
+| Upload files | Yes | Yes (answering requests) | No |
+| See all files in deal | Yes | No | No |
+| See own uploads | Yes | Yes | N/A |
+| See shared files | Yes | Only what's shared with them | Only what's shared with them |
+| Change file visibility | Yes | No | No |
+| Share with specific buyer | Yes | No | No |
+| Share with all buyers | Yes | No | No |
+| Revoke buyer access | Yes | No | No |
+| See who has access to a file | Yes | No | No |
+| See other buyers exist | Yes | Configurable | Never |
+| Download (full) | Yes | No | No |
+| Download (watermarked) | Configurable | Yes | Yes |
+| Create request list | Yes | No | Yes (their own RL) |
+| Assign tasks | Yes | Within their org | No |
+| See who requested a document | Yes | Never (anonymized by IB) | Own requests only |
+
+### Anonymization & Redaction
+
+Seller documents often contain information that must not reach buyers in raw form — customer names, vendor names, employee names, contract counterparties, sometimes even the Seller's own name (the company is often code-named, e.g., "Project Atlas").
+
+This is not simple find-and-replace. It requires **consistent entity replacement across the entire dataroom** — if "Acme Corp" appears in 40 documents, it must become "Customer A" in all 40.
+
+#### Entity Registry
+
+Each deal maintains an **entity registry** — a mapping table of real names to anonymized labels:
+
+```
+Entity Registry — Project Atlas:
+
+  Customers:
+    Acme Corp           → Customer A
+    Globex Industries   → Customer B
+    Initech             → Customer C
+
+  Vendors:
+    Smith & Sons        → Vendor A
+    Delta Logistics     → Vendor B
+
+  Employees:
+    Jane Rodriguez      → [redacted] / "the VP of Sales"
+
+  The Company:
+    Springfield Manufacturing → "the Company" / "Project Atlas"
+```
+
+This registry is **deal-wide**. Every document processed through the anonymization layer uses the same mapping, ensuring consistency.
+
+#### LLM-Assisted Detection
+
+When the IB uploads or reviews a document before sharing:
+
+1. LLM scans the document and identifies entities — company names, person names, addresses, phone numbers, contract counterparties
+2. Each entity is matched against the registry:
+   - **Known entity** → auto-replaced with its alias ("Acme Corp" → "Customer A")
+   - **New entity** → flagged for IB to classify and assign an alias
+3. IB reviews the anonymized version and approves
+
+```
+LLM detected 3 entities in "Top-Customers-2025.xlsx":
+
+  ✓ Acme Corp → Customer A  (auto-matched from registry)
+  ✓ Globex Industries → Customer B  (auto-matched)
+  ⚠ Wayne Enterprises → [NEW — assign alias?]
+    Suggested: Customer D
+
+  [Approve All]  [Review Individually]
+```
+
+#### Consistency Across Documents
+
+The entity registry ensures that:
+- "Acme Corp" in the revenue breakdown is the same "Customer A" as in the contracts folder
+- A buyer reading the financial model and then a customer contract sees consistent references
+- When a new document mentions a previously-registered entity, it's auto-replaced without IB intervention
+
+#### What Gets Anonymized
+
+| Category | Treatment |
+|----------|-----------|
+| Customer names | Replaced: "Customer A", "Customer B", ... |
+| Vendor/supplier names | Replaced: "Vendor A", "Vendor B", ... |
+| Employee names (below C-suite) | Redacted or replaced with role: "the VP of Sales" |
+| C-suite names | Usually kept (buyers need to know who they're dealing with) |
+| The company itself | Replaced with codename until LOI stage |
+| Addresses, phone numbers | Redacted unless relevant |
+| Contract values | IB decides per document — sometimes ranges replace exact figures |
+
+#### Versioning & Anonymization
+
+Two versions of each document exist internally:
+
+- **Original** — as uploaded by the Seller, with all real names. Only visible to IB.
+- **Anonymized** — processed through the entity registry. This is what buyers see.
+
+When the Seller uploads a new version, the anonymization runs again using the same registry. The IB reviews the anonymized output (not the original — they've already seen that). If no new entities are detected, it can auto-approve.
+
+#### Approval Flow
+
+```
+Seller uploads document
+  → LLM scans for entities
+  → Known entities auto-replaced via registry
+  → New entities flagged for IB
+  → IB assigns aliases for new entities (added to registry)
+  → IB reviews anonymized version
+  → IB approves → document available in buyer datarooms
+```
+
+In later deal stages (confirmatory), anonymization may be relaxed — the buyer knows who the company is by then. The IB controls this per-stage.
+
+### Watermarking
+
+Every download by a Seller or Buyer is watermarked at serve time:
+
+```
+{user_name} · {org_name} · {datetime} · CONFIDENTIAL
+```
+
+This is non-negotiable and cannot be disabled. IB downloads may optionally be watermarked.
+
+### Buyer Isolation
+
+Buyers must never:
+- See other buyers' names, org names, or any identifying information
+- Know how many other buyers exist
+- See documents shared exclusively with other buyers
+- See other buyers' request lists or questions
+
+This is enforced at the **data layer**, not just the UI. Queries for buyer users filter by their org's visibility scope before results leave the database.
+
+---
+
+## Task Chain
+
+A request becomes a **task** when it needs action from someone. Tasks route through a chain of people, tracking who assigned it and who it should return to.
+
+### Example Flow
+
+Buyer C submits a request: *"Provide Statement KLM"*
+
+```
+1. Buyer C asks
+   → appears in IB's task inbox
+
+2. IB assigns to Seller CFO
+   → assignee: CFO
+   → return_to: IB
+   → origin: Buyer C (hidden from Seller)
+   → CFO sees: "IB requests Statement KLM"
+
+3. CFO delegates to Director of Operations
+   → assignee: Director
+   → return_to: CFO
+
+4. Director delegates to Assistant
+   → assignee: Assistant
+   → return_to: Director
+
+5. Assistant completes the work, uploads the file
+   → task returns to Director
+
+6. Director reviews, approves
+   → task returns to CFO
+
+7. CFO approves
+   → task returns to IB
+
+8. IB reviews, anonymizes if needed
+   → releases to Buyer C's dataroom
+   → Buyer C's request is marked as answered
+```
+
+### Fields on Each Request
+
+```
+assignee_id   — who currently owns this task
+return_to_id  — who it goes back to when done
+origin_id     — who originally asked (hidden from Seller)
+stage         — open | in_progress | review | complete
+due_date      — optional deadline
+```
+
+### Auto-Flow
+
+When the current assignee marks a task as **complete** or **approved**, the system automatically reassigns to `return_to_id`. No manual handoff needed — the task flows back up the chain by itself:
+
+```
+Assistant completes → auto-assigns to Director
+Director approves   → auto-assigns to CFO
+CFO approves        → auto-assigns to IB
+```
+
+If the reviewer **rejects**, the task flows back down to the previous assignee with a note.
+
+### Visibility Along the Chain
+
+**IB sees everything.** Regardless of where a task currently sits in the chain, the IB can see:
+- Current assignee ("sitting with: Assistant, Seller Org")
+- How long it's been there
+- The full chain history (who had it, for how long)
+- Whether it's at risk of missing a deadline
+
+**Delegators see their subtree.** The CFO who delegated to the Director can see that the Director re-delegated to the Assistant, and that the Assistant has had it for 3 days. The Assistant cannot see that the CFO delegated it — only that the Director assigned it.
+
+### Nudging
+
+Tasks that sit too long get nudged automatically:
+
+| Condition | Action |
+|-----------|--------|
+| Task unactioned for 48h | Remind current assignee |
+| Task unactioned for 5 days | Escalate to the person who delegated it |
+| Task approaching due date (2 days) | Remind assignee + notify delegator |
+| Task overdue | Notify IB + delegator + assignee |
+
+Nudge frequency is configurable per deal. Nudges go to individuals, not broadcast.
+
+### Key Rules
+
+- **Seller never sees the origin.** The CFO sees "IB requests Statement KLM", not "Buyer C wants Statement KLM." The IB is always the visible requester.
+- **Each person in the chain sees it in their task inbox.** "My Tasks" shows everything currently assigned to you.
+- **The chain is unbounded.** CFO → Director → Assistant → Intern → ... → back up the chain. Each handoff is tracked.
+- **Approval on the way back up.** Each person in the return chain reviews before passing it up. Any person can reject and send it back down.
+- **IB always has full visibility.** Even when a task is 4 levels deep in the Seller's org, the IB can see exactly where it is and who's holding it up.
+
+---
+
+## LLM-Assisted Matching
+
+When a buyer submits a request list, many items will overlap with documents already in the internal dataroom. Instead of the IB manually hunting through hundreds of files, the LLM suggests matches.
+
+### How It Works
+
+1. Buyer B submits their RL with 80 line items
+2. DealSpace runs each request against the existing document set (filename, category, content summary, linked request text)
+3. The LLM returns suggested matches with confidence:
+
+```
+Request: "Audited financial statements 2023-2025"
+  → Suggested match: Q3-2025-Income-Statement.pdf (92% confidence)
+  → Suggested match: 2024-Annual-Audit-Report.pdf (88% confidence)
+  → No match found for: "Environmental compliance certificates"
+```
+
+4. IB reviews the suggestions in a single approval screen:
+   - **Accept** — link the file to the request, set visibility for Buyer B
+   - **Reject** — not the right document, will need to source it
+   - **Accept + share with all** — this is common-sense info, share with everyone
+
+5. Unmatched requests become tasks, routed to the Seller
+
+### What the LLM Matches On
+
+- Document filename and category tags
+- The original request text that the document answered (from the IB's own RL)
+- Document content summary (extracted at upload time)
+- Semantic similarity — "P&L" matches "Profit and Loss Statement" matches "Income Statement"
+
+### IB Always Approves
+
+The LLM never auto-shares. Every suggestion requires explicit IB approval. The LLM saves time finding candidates — the IB makes the decision.
+
+---
+
+## Notifications
+
+### The Problem
+
+When IB shares a document with all buyers, each buyer should know. But:
+- Don't spam — 50 documents shared in one afternoon shouldn't mean 50 emails
+- Stay relevant — don't notify about documents a buyer already has
+- Respect isolation — never leak information about other buyers
+
+### Batched Digests
+
+Notifications are **batched** per buyer, delivered as periodic digests:
+
+```
+Subject: 12 new documents available — Project Atlas
+
+Hi Sarah,
+
+12 new documents have been added to your dataroom since your last visit:
+
+  Financial (4)
+    • Q3 2025 Income Statement
+    • Q4 2025 Income Statement
+    • 2025 Balance Sheet
+    • Revenue Breakdown by Region
+
+  Legal (3)
+    • Articles of Incorporation
+    • Board Resolutions 2024-2025
+    • Shareholder Agreement
+
+  Operations (5)
+    • ...
+
+View your dataroom: [link]
+```
+
+### Batching Rules
+
+- **Frequency:** Configurable per deal — hourly, daily, or on-demand
+- **Deduplication:** Only notify about documents the buyer hasn't seen yet
+- **Relevance:** If a document was shared because Buyer A asked for it, and Buyer B already has it via a different request link, don't include it in Buyer B's digest
+- **Grouping:** Group by category (the same tags used for the folder view)
+
+### Task Notifications
+
+Task assignments are **near-immediate but coalesced** — if the IB assigns 10 requests to the CFO in one sitting, they arrive as a single notification, not 10 emails. Coalescing window: 15 minutes.
+
+```
+Subject: 3 new requests assigned to you — Project Atlas
+
+You have 3 new requests:
+
+  • Provide Statement KLM (due: Mar 28)
+  • Board meeting minutes 2024 (due: Mar 30)
+  • Employee headcount by department (due: Apr 2)
+
+View your tasks: [link]
+```
+
+### Daily Status Digest
+
+Every active participant gets a daily summary (morning, their timezone) of their open tasks:
+
+```
+Subject: Your daily update — Project Atlas
+
+Tasks assigned to you: 5
+  • 2 new (assigned yesterday)
+  • 1 due today: "Provide Statement KLM"
+  • 1 overdue (3 days): "Environmental compliance certs"
+  • 1 in progress
+
+Tasks you're waiting on: 3
+  • Delegated to J. Smith (2 days ago, no action yet)
+  • Delegated to M. Lee (completed, pending your review)
+  • Delegated to R. Patel (in progress)
+```
+
+No daily digest is sent if nothing has changed since the last one.
+
+---
+
+## Deal Stages & Gates
+
+A deal progresses through defined stages. Each stage controls default behavior for notifications, visibility, and document updates.
+
+```
+preparation → offering → due_diligence → narrowing → confirmatory → closed
+```
+
+| Stage | Description | Notification Default |
+|-------|-------------|---------------------|
+| `preparation` | IB collecting from Seller | No buyer access |
+| `offering` | Initial docs shared with buyers | Notify on new shares |
+| `due_diligence` | Buyers asking questions, requesting docs | Notify on new shares |
+| `narrowing` | Fewer buyers, deeper access | Notify only if IB flags |
+| `confirmatory` | Final buyer, refreshing docs | Silent — no notifications |
+| `closed` | Deal done | Dataroom frozen, read-only |
+
+### Stage Transitions
+
+- IB controls stage transitions manually
+- Moving to `closed` freezes the dataroom — no uploads, no visibility changes, download-only
+- Moving to `confirmatory` switches notification behavior to silent by default
+- Revoking a buyer's access can happen at any stage (buyer eliminated)
+
+### Deadline Gates
+
+The IB can set deadlines on stages:
+
+- "Round 1 bids due by March 30" — after which buyer access may be frozen or restricted
+- "Final documents due April 15" — Seller deadline for all outstanding requests
+- Deadlines trigger automated reminders via the nudging system
+
+---
+
+## Audit Trail
+
+Every meaningful action is logged. This is non-negotiable — the audit log cannot be disabled, paused, or tampered with.
+
+### What's Logged
+
+| Event | Details Recorded |
+|-------|-----------------|
+| Document uploaded | Who, when, filename, category, size |
+| Document viewed | Who, when, which version |
+| Document downloaded | Who, when, which version, watermark ID |
+| Visibility changed | Who granted/revoked, which file, which party |
+| Request created | Who, which RL, text |
+| Request answered | Who, text/file, which request |
+| Task assigned | Who assigned, to whom, which request |
+| Task completed | Who, when, how long it took |
+| Login | Who, when, IP, device |
+| Stage transition | Who, from/to stage, when |
+| Access granted/revoked | Who, which org, by whom |
+
+### Analytics for IB
+
+The audit trail isn't just compliance — it's a **buyer engagement signal**. The IB can see:
+
+- **Activity heatmap** — which buyers are actively reviewing documents vs. going cold
+- **Document interest** — which files get the most views/downloads (signals what matters to buyers)
+- **Response time** — how quickly each buyer engages with new documents
+- **Coverage** — which documents a buyer hasn't opened yet
+
+```
+Buyer A: Last active 2 hours ago, downloaded 47 of 150 docs, avg response: 4 hours
+Buyer B: Last active 12 days ago, downloaded 3 of 150 docs — likely dropping out
+Buyer C: Downloaded everything within 24 hours — very engaged
+```
+
+This helps the IB prioritize which buyers to focus on, and when to follow up.
+
+### Retention
+
+Audit logs are retained for the life of the deal plus a configurable retention period (default: 7 years, per regulatory requirements). Logs are immutable — append-only, no edits, no deletes.
+
+---
+
+## Standard Templates
+
+IB firms reuse the same structure across deals. DealSpace supports templates for:
+
+### Request List Templates
+A standard checklist (e.g., "M&A Due Diligence — Full") that can be loaded into any new deal. Contains sections and individual request items, but no answers or files.
+
+### Dataroom Category Templates
+A standard folder structure (e.g., "Financial / Historical / ...", "Legal / Corporate / ...") that defines the category tags available in a deal. When the Seller uploads a file, they pick from these categories.
+
+Templates are org-level resources — each IB firm maintains their own library.
+
+---
+
+## Summary
+
+| Concept | Implementation |
+|---------|---------------|
+| File | Stored once as an Object, tagged with categories |
+| Folder structure | UI rendering of category tags, not physical nesting |
+| Dataroom | A filtered view based on the viewer's visibility scope |
+| Internal dataroom | All objects (IB-only view) |
+| Buyer's dataroom | Objects where scope = `all_buyers` or `org:{buyer}` |
+| Request → File link | Answer Links (many-to-many) |
+| Q&A | Text answers on requests, same visibility rules as documents |
+| "Copy file to another dataroom" | Add a visibility scope entry (no file duplication) |
+| Document versioning | Replace-in-place, notification behavior varies by deal stage |
+| Task routing | assignee_id / return_to_id / origin_id chain, auto-flow on completion |
+| Task nudging | Automated escalation at 48h, 5d, near-deadline, overdue |
+| LLM matching | Suggests document + text matches for buyer requests, IB approves |
+| Notifications | Batched digests for documents, coalesced for tasks, daily status |
+| Audit trail | Every view, download, share, assignment — immutable, always on |
+| Buyer analytics | Engagement signals from audit data — activity, interest, coverage |
+| Deal stages | preparation → offering → DD → narrowing → confirmatory → closed |
+| Organizations | Platform-level, reused across deals, matched by domain |
+| People | Belong to orgs, deal roles determine routing and permissions |
+| Auto-routing | Tasks route by org deal_role + category-based rules |
+| Advisors | Separate orgs with scoped visibility (legal sees Legal/*, etc.) |