# Documents, links and data rooms

Ray holds two kinds of material, and the words are never mixed. A **document** is a file Ray keeps: it has versions, and a version never changes. A **link** is an address somewhere else (a Drive folder, a live model, a demo video): what is behind it can change, and Ray cannot see inside it. `save_document` registers either; `list_records` with `kind: "document_reference"` and `get_record` read them, and a document's record carries `file_url`, a short-lived link to read the file yourself when a brief or a message needs what is in it. Say when you could not open it.

## Storing a file

How the file gets in is not the person's concern: they ask for the document to be stored, and you pick the way your client allows.

1. **A small file (under about 45 KB as base64)**: `save_document` with `file_base64`, `media_type` and `file_name`, the way a photo goes to `enrich_profile`.
2. **Anything larger**: `request_document_upload` with the file's exact size, its SHA-256 (64 lowercase hex digits) and its media type. It returns an address, the headers and a ready `command` (`curl --upload-file …`). Send the bytes with exactly those headers; the store refuses bytes whose SHA-256 differs. Then `save_document` with `upload` set to the returned refcode. A lost answer is safe to retry: pass the same `retry_key`, and Ray returns the document it already saved.
3. **When your client cannot send a request to an address**: say so, and give the person the link the result carries (`page`), where they drop the file on the Documents page. Do not paste a file's bytes into a note or a link as a substitute.

A capture rule of Observe stores nothing, so the address is refused under it; under Suggest the save is a proposal the person approves. Uploading the file for something recorded as a link makes a new document; the link and its sharing history stay as they were. When the company replaces a deck, archive the old document's latest version with `archive_document`: it leaves the library and new drafts, its sharing history and the rooms that hold it stay, and `archived: false` brings it back. Only an owner or admin can remove a document's file, from its page, and the record of the version stays.

## The round's data room

A round has one data room, shared by every deal in it. It has **tiers**, named levels in order and cumulative (such as Overview, Deep dive, Diligence); each item sits in one tier, and a deal that has a tier sees it and everything below. A tier may name the deal stage that opens it: a deal that reaches that stage is raised to the tier by Ray itself, and never lowered by itself. The room grows in **releases**: a draft you prepare, then publish, after which that release never changes, and the next change is the next release. An investor always sees the latest published release.

The room is written only through these tools; the pages show it and have no forms for it.

- `save_data_room`: the round's room (made if there is none), its name, the welcome line shown on the room's welcome page, its tiers with their opening stages, and the draft's narrative and whole list of items (each a document or link refcode with its tier, whether a document may be downloaded, and a note).
- `add_to_data_room` and `remove_from_data_room`: change the draft, keeping the rest. Taking something out of what is published starts the next draft from the published release without it.
- `publish_data_room`: publish the draft (give `revision`, which the result of each change to the draft and `get_room_activity` carry, so a draft that changed since is refused), withdraw the latest release, or discard the draft. Withdrawing the only release stops every link until something is published again.
- `grant_data_room_access`: a deal's access at a tier, and a link for each person named, who must be on the deal; named nobody, the deal's primary contact gets a link if nobody has one. Set `new_links` for a link that may have been passed on: the old address stops at once. The same call raises or lowers a deal's tier.
- `revoke_data_room_access`: the deal's whole access, or only the links of the people named. A revoked access stays revoked until it is granted again; a stage change does not bring it back.
- `get_room_activity`: for a round, the room with its tiers, draft, releases and every deal with access; for a deal, its tier, each person's link with its use, and, for a member who runs the account, the link itself.

Publishing, withdrawing, granting and revoking are for owners and admins; drafts and tiers need the documents capability. All of it follows the capture rules like any other write, so under Suggest it is a proposal the person approves. A link works while the deal is active or committed, the round is active, and a release is published; a deal marked passed or withdrawn stops its links, and `update_deal` says whose. When a stage move raises a deal's tier, the result says so and whether a link was issued.

Ray makes each person's link and sends nothing. A tool's result never carries the link: read it with `get_room_activity`, or `get_email_context` when drafting the message, and put it in a message the person sends; both return links only to a member who runs the account. The person can also copy it from the deal's room page and see the room as that link shows it. PDFs can be read in the room; other files can only be downloaded, and links open at their address.

## What a room records, and what you may say

`get_room_activity` returns each person's link, and its use: visits, the last time it was opened, documents opened, time reading, downloads, links followed, requests for access, and whether it was opened from more than one browser. The same comes back in `get_meeting_brief` and `get_email_context` as `data_rooms`.

Name the link, never the person: "Sarah Chen's link opened the deck, 6 minutes on the financials." Nobody signs in and a link can be forwarded, so what a link did is what someone holding it did. You may add what the use suggests, as a reading and not a fact ("that is a lot of time on the model; a good moment to follow up"), and propose a follow-up or a higher tier. A request for access from the room makes one open task on the deal for its owner, and Ray marks it done when the deal's access comes to cover that tier, whether you grant it or the deal's stage raises it; the result says so. Never move a deal's stage or record contact because of room use, and never say a download completed or a page was read: Ray sees a download requested and a page on screen.