Public: anyone can read this; the crew can change it.
The README reads like a five-minute tour a realtor can follow, and the terminal, MCP and API details live in docs/TECHNICAL.md #168
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/162-the-readme-reads-like-a-five-minute-tour → main 2 commits fork
2 files
changed +194
−262
README.md +134 −262
| @@ -4,291 +4,163 @@ Every deadline of every deal on one timeline, so nothing slips. It shows an | ||
| 4 | 4 | agent each date in a contract, who owes what, and the reminder to send each |
| 5 | 5 | party before it comes due. |
| 6 | 6 | |
| 7 | The technical part (running it, the API, MCP, the terminal, the files, roles) | |
| 8 | is in [](docs/TECHNICAL.md). | |
| 7 | Whoever builds or runs the app will find the rest in | |
| 8 | [](docs/TECHNICAL.md). | |
| 9 | 9 | |
| 10 | ## Try it on the sample deals | |
| 10 | ## A five-minute tour on the sample deals | |
| 11 | 11 | |
| 12 | Seven sample deals are already in, so the first screen is never empty. Four are open. Three closed earlier this year: 35 Mill Pond Road, 602 Cedar Heights Blvd and 14 Saltmarsh Lane. The closed ones are off the clock, This week, reminders and the calendar. They sit in the Closed list with their prices, and they fill the book line under the clock's heading, which reads like "4 open · $1,693,400 under contract · 2 close in November · 3 closed this year, $1,375,000 · $45,328 commission pending · $37,395 earned this year". Sign in first (see below). You land on **the clock**: each deal is a lane, time runs | |
| 13 | left to right, and today is the dark line down the middle. Every date in a | |
| 14 | contract is a marker on its lane: red is overdue, amber is due within three | |
| 15 | days, teal is coming up, grey is done. The samples stay current: each time | |
| 16 | the app starts, the ones nobody has touched move forward together by the days | |
| 17 | since they were last set, so the screen always looks like today. Under the | |
| 18 | clock, **This week** lists every open date that is overdue or due in the next | |
| 19 | seven days, day by day (Overdue, Today, then each day), with the deal's | |
| 20 | address, who owes it and how urgent it is; tap a row to open its sheet. It | |
| 21 | reads well on a phone, with no sideways scrolling. **Print this week** beside | |
| 22 | its heading opens a one-page sheet of the same rows for the Monday office | |
| 23 | meeting (with Find on, only the matching deals); press Print or your | |
| 24 | browser's print. In the terminal, press w | |
| 25 | for the same list; over MCP, an agent asks for the `this_week` tool. | |
| 12 | Seven sample deals are already in, so the first screen is never empty. Four | |
| 13 | are open: 1418 Alder Lane, 77 Harbor View Dr (Unit 4B), 9 Orchard Row and 2210 | |
| 14 | Juniper Court. Three closed earlier this year: 35 Mill Pond Road, 602 Cedar | |
| 15 | Heights Blvd and 14 Saltmarsh Lane. The samples stay current: every time the | |
| 16 | app starts, the ones nobody has touched move forward so the screen always | |
| 17 | looks like today. | |
| 26 | 18 | |
| 27 | Adding a party on a deal's page offers **Use someone from your other deals**: tap Use beside a lender from another sample deal and the form fills with their name, role, email and phone, which you can still change before Add party. | |
| 19 | 1. **Sign in.** Tap **Sign in** on the first page and use your forge account. | |
| 20 | Until you do, you see only what deal-clock does and a still picture of a | |
| 21 | made-up deal; no real deal is read. Once in, you land on the clock with | |
| 22 | 77 Harbor View Dr, Unit 4B, 1418 Alder Lane, 9 Orchard Row and 2210 Juniper | |
| 23 | Court. | |
| 24 | 2. **Read the clock.** One lane per open deal. Time runs left to right and | |
| 25 | today is the dark line down the middle. Every date in a contract is a | |
| 26 | marker: red is overdue (the inspection on 77 Harbor View Dr), amber is due | |
| 27 | within three days, teal is coming up, grey is done (the earlier dates on | |
| 28 | 1418 Alder Lane, which closes in a few days). Under the heading, one line | |
| 29 | adds up your book, like "4 open · $1,693,400 under contract · 2 close in | |
| 30 | November · 3 closed this year, $1,375,000 · $45,328 commission pending · | |
| 31 | $37,395 earned this year" (the November count follows the month you open it | |
| 32 | in). Below the clock, **This week** lists every open date that is overdue or | |
| 33 | due in the next seven days, with who owes it. | |
| 34 | 3. **Open a deal.** Tap the red inspection marker on 77 Harbor View Dr. A | |
| 35 | sheet opens with the date, who owes it (the buyer), what is owed, and the | |
| 36 | reminders for each party. Tap the address to open the deal's page: every | |
| 37 | date, every party, the messages you have sent. | |
| 38 | 4. **Mark a date done.** On 1418 Alder Lane, open a coming date such as | |
| 39 | Financing and tap **Mark done**. The marker turns grey and its reminders | |
| 40 | stop. **Reopen** puts it back. | |
| 41 | 5. **Move a date, with a reason.** Back on Harbor View, open the inspection | |
| 42 | marker and tap **Move this date**: pick a new date and say why ("Inspector | |
| 43 | delayed"). The marker jumps, and the sheet lists the move, the reason and | |
| 44 | who made it. A "Date changed" notice is drafted for each party the date | |
| 45 | concerns. On 9 Orchard Row the appraisal has already been moved; open it to | |
| 46 | see where from and to, and why. | |
| 47 | 6. **Review and approve today's reminders.** Tap **Review** in the header. Each | |
| 48 | unsent reminder shows the words it would send, already filled in, for a | |
| 49 | party such as the buyer Samuel Reyes. Edit them if you like, then **Send**, | |
| 50 | **Don't send** (it asks why) or **Tomorrow**. Send records your approval and | |
| 51 | offers **Open in Mail** or **Open in Messages**, which open your own app with | |
| 52 | the words: deal-clock never sends anything itself. The count in the header | |
| 53 | goes down. | |
| 54 | 7. **Hand the client a timeline.** On 1418 Alder Lane's page tap **Client | |
| 55 | timeline**: its dates in order, who owes each, and what the buyer or seller | |
| 56 | does for it, with no controls. Tap **Print** for a one-page handout for Maya | |
| 57 | and Tom Okafor. | |
| 58 | 8. **Print the week.** Beside the **This week** heading tap **Print this | |
| 59 | week** for a one-page sheet of the same rows, ready for the Monday office | |
| 60 | meeting. It starts with the overdue Harbor View inspection, then the days | |
| 61 | ahead, including the closing on 1418 Alder Lane. | |
| 62 | 9. **See People.** Open **People** in the header. Each person on your deals | |
| 63 | appears once, with every open date they owe across all deals, soonest | |
| 64 | first. Try Priya Nair, the lender on both 1418 Alder Lane and 9 Orchard Row. | |
| 65 | Tap a number to call or text, an address to write. | |
| 66 | 10. **Set up your Profile.** Open **Profile** in the header and type your name, | |
| 67 | brokerage, phone and email. They appear in the header, on the client | |
| 68 | timeline and at the foot of every new reminder. (Only an admin can save | |
| 69 | it; **Use defaults** goes back to the sample agent.) | |
| 28 | 70 | |
| 29 | Before calling a lender or an inspector, open **People** in the header: each | |
| 30 | person on your deals appears once, with every open date they owe across all | |
| 31 | deals, soonest first (try Priya Nair, who works both 1418 Alder Lane and 9 Orchard | |
| 32 | Row). Tap a number to call or text, an address to write. In the terminal, press P; over MCP, ask for `list_people`. | |
| 71 | ## Finding a deal | |
| 33 | 72 | |
| 34 | To find a deal, type part of its address, or of a buyer's, seller's or other | |
| 35 | party's name, phone or email, into **Find a deal** above the clock and press | |
| 36 | Find (try `harbor`). The clock, This week and today's reminders narrow to the | |
| 37 | deals that match, with no JavaScript needed; **Clear** brings them all back. | |
| 38 | In the terminal, press / and type the same, then enter; the dates, week and | |
| 39 | reminders views narrow to it, and / then enter alone clears it. An agent finds | |
| 40 | a deal by name the same way: over MCP, `list_deals` takes an optional `query` | |
| 41 | ("what's left on the Elm Street deal?"), and `GET /api/deals?q=elm` does the | |
| 42 | same; a query over 100 characters or with control characters is refused (400, | |
| 43 | `{error:"invalid", field:"q"}`). | |
| 73 | Type part of an address, or of a buyer's, seller's or other party's name, | |
| 74 | phone or email, into **Find a deal** above the clock and press Find (try | |
| 75 | `harbor`). The clock, This week and today's reminders narrow to the matches; | |
| 76 | **Clear** brings them back. The **Side** choice beside it narrows to deals | |
| 77 | where you are the buyer's agent or the listing agent. 9 Orchard Row is a | |
| 78 | listing in the samples. | |
| 44 | 79 | |
| 45 | To add a date over the API, `POST /api/deals/:id/deadlines` with `label` (1 to | |
| 46 | 100 characters), `due` (YYYY-MM-DD), `owes` (a party role) and optionally `what` | |
| 47 | and `lead_days` (1 to 30). It answers 201 with the date, or 400 naming the | |
| 48 | field. A label typed exactly as a suggestion (`/openapi.json` lists them) sets | |
| 49 | that date's reminder lead unless `lead_days` is given. It is the deal update | |
| 50 | cell, like the page and MCP `add_date`. | |
| 80 | ## Opening and shaping a deal | |
| 51 | 81 | |
| 52 | Signed out, `/` shows what deal-clock does, three short points, a still picture of the clock drawn from a made-up deal, and one **Sign in** button; no real deal is read. | |
| 82 | **New deal** asks for an address, buyer, seller, contract date and closing | |
| 83 | date, and which side you are on. The standard lengths (earnest money deposit 3 | |
| 84 | days, inspection 10, appraisal 21, financing 30, title 14, final walkthrough | |
| 85 | the day before closing) are filled in and you can change them; **Check the | |
| 86 | dates** shows every date the deal would get without saving anything. On a deal's page | |
| 87 | you can add a party (**Use someone from your other deals** fills in a person | |
| 88 | you already have), fix a typo with Edit, add a date the contract added (an HOA | |
| 89 | review), waive a contingency the buyer gave up, change who owes a date, correct | |
| 90 | the address, and set the closing time and place. A date on a weekend or | |
| 91 | federal holiday says so and offers **Move to** the next business day. For an | |
| 92 | addendum that moves several dates, **Amend the contract** takes one reason and | |
| 93 | sends each party one notice. Every date also takes a short working note only | |
| 94 | you see. A deal that falls through is marked with **Fell through…** and moves to | |
| 95 | the Closed list; **Reopen** brings it back. Closing a deal is marking its | |
| 96 | Closing date done: it steps off the clock, and a month later a drafted "How is | |
| 97 | the new home?" check-in waits in Review. | |
| 53 | 98 | |
| 54 | 1. **Look at the clock.** You see four lanes: 77 Harbor View Dr, Unit 4B | |
| 55 | (the inspection date has passed, so its marker is red), 1418 Alder Lane | |
| 56 | (closing in a few days, with the earlier dates grey), 9 Orchard Row (the | |
| 57 | appraisal was moved), and 2210 Juniper Court (just signed, everything | |
| 58 | still ahead). | |
| 59 | 2. **Open a marker.** Tap the red inspection marker on Harbor View. A sheet | |
| 60 | opens with the date, who owes it (the buyer), what is owed, and the reminders | |
| 61 | for each party, grouped as 3 days before, the morning of, and an | |
| 62 | Overdue follow-up to the buyer, because the date passed without being marked | |
| 63 | done (it waits under Reminders for today until you send or decline it). It | |
| 64 | also has two buttons: Mark done, and Move this date. Each date has a | |
| 65 | Reminds N days before setting (1 to 30; Financing starts at 7), which you | |
| 66 | can change on its sheet. The clock itself | |
| 67 | stays small: a deal's sheets are fetched the first time you tap one of its | |
| 68 | dates, a blink later. | |
| 69 | 3. **Read and edit a reminder.** In the sheet, tap a party's reminder. You | |
| 70 | see the words it would send, in a subject field and a message field, | |
| 71 | already filled in. Change the message; the subject can run to 150 | |
| 72 | characters and the message to 2000. On the review page, a party with no | |
| 73 | email or phone shows **Email** and **Phone** fields and a **Save contact** | |
| 74 | button; save it and you land back on the same draft with the contact | |
| 75 | shown and your edited words kept. A party can keep both: a lender is | |
| 76 | emailed and a buyer is texted from the same deal. Send without a contact still records | |
| 77 | your approval, and your Mail then opens with no recipient. | |
| 78 | 4. **Send it.** Tap Send. Send records your approval and offers **Open in | |
| 79 | Mail** and **Open in Messages** (both when the party has an email and a | |
| 80 | phone, one otherwise), each opening your own app with the words: nothing is sent by the app itself. A | |
| 81 | short notice at the top of the page reads "Reminder sent." with one link, | |
| 82 | **Open in Mail** (an email on file) or **Open in Messages** (a phone), that | |
| 83 | you tap to send from your own app; with neither on file it says "No email | |
| 84 | or phone on file". The reminder now shows "Sent" with | |
| 85 | today's date, your edited words, not the original draft, and the same link. Under the | |
| 86 | clock, the heading "Reminders for today" counts what is left ("14 to send" | |
| 87 | becomes "13 to send"; when nothing is left it reads "all sent"). Each row | |
| 88 | there opens the sheet of the date it is for, where the reminder is edited, | |
| 89 | sent or declined. Many to get through? **Review all**, beside that heading, | |
| 90 | walks you through them one page at a time: Send or Don't send, and the next | |
| 91 | one appears; Skip leaves one for later. Wherever you are, the header's **Review** link carries the same count ("Review 3") and opens that walk with one tap. | |
| 92 | Decided against a message? Beside Send, **Don't send** asks why (up to 200 | |
| 93 | characters). The reminder stops counting as "to send" and reads "Not sent: | |
| 94 | <reason> · <who>"; the reason is kept, and **Undo** makes it a draft again. | |
| 95 | Not ready to approve one? **Tomorrow** holds it: it leaves today's list and the count, and returns at the top tomorrow as "Held from <weekday>" with your edited words (hold it again to push it another day). Changed your mind? **Bring back** on the deal's Messages list returns it to today at once; in the terminal, press H on the reminders list to see the held ones and B to bring the one under the cursor back. In the terminal, press h on the reminders list. | |
| 96 | To keep a client informed about the whole deal, a deal's page also has a | |
| 97 | **Status update** card for each buyer and seller with an email or phone: a | |
| 98 | draft of what is done, what is next and who owes it, and when it closes, | |
| 99 | which you edit and send or decline like any reminder; it is offered again | |
| 100 | only after a date on the deal is done, moved, added or removed. In the | |
| 101 | terminal, open the deal, move to a buyer or seller and press S: type send to | |
| 102 | record the draft as written (to change the words, use the page), or no and a | |
| 103 | reason. Over MCP: `draft_status_update` and `send_status_update`. | |
| 104 | Every message you sent is kept: open 1418 Alder Lane's page and find | |
| 105 | **Messages**, newest first, each with who it went to, which date and | |
| 106 | moment, the day it was sent, and (tap it open) the exact words you approved | |
| 107 | with the link to open them again. | |
| 108 | In the terminal: open the deal with o, then press s. | |
| 109 | 5. **Move a date, with a reason.** Open the same marker again and use Move | |
| 110 | this date: pick a new date and say why ("Inspector delayed"). The marker | |
| 111 | jumps to the new date, and the sheet lists the move, the reason and who | |
| 112 | made it. No other date moves. A *Date changed* notice is drafted for each | |
| 113 | party the date reminds, naming the old and the new date (not the reason); | |
| 114 | it waits under Reminders for today like any other, and you send, edit or | |
| 115 | decline it. Move the date again and an unsent notice is replaced. If you move a date to or past the closing date, the move | |
| 116 | still happens, but the notice says so, the date's marker on the clock | |
| 117 | carries a ! and the sheet and the deal page say which dates now fall | |
| 118 | after closing. For an addendum that moves several dates, use *Amend the | |
| 119 | contract* on the deal page instead: one reason, and each party gets one | |
| 120 | notice listing every change. | |
| 121 | If a date was entered against the wrong party, or the contract hands it | |
| 122 | over (a repair, say), open its sheet and change *Owed by*: its reminders | |
| 123 | from then on go to the new party, and the sent ones stay as they were. | |
| 124 | 6. **See a date that was moved.** On 9 Orchard Row, open the appraisal | |
| 125 | marker. The sheet shows where it moved from and to, with the reason | |
| 126 | the appraiser gave. | |
| 127 | 7. **Mark a date done.** On Alder Lane, open a coming date and tap Mark | |
| 128 | done. The marker turns grey and its reminders stop. Reopen puts it back. | |
| 129 | When the buyer gives a contingency up on purpose, tap Waive instead (it | |
| 130 | asks once): on 2210 Juniper Court the appraisal is already waived, grey | |
| 131 | and marked Waived, still counted as settled, with no reminders; Un-waive | |
| 132 | brings it back as it was. A deal that falls through is marked with | |
| 133 | *Fell through…* at the foot of its page (it asks once and takes a short | |
| 134 | reason) and moves to the Closed list marked Fell through; *Reopen* on its | |
| 135 | page puts it back on the clock with its dates as they were. | |
| 136 | 8. **Add a party.** Tap the address 2210 Juniper Court to open the deal's | |
| 137 | page. It lists every date and every party. Under "Add a party" pick a | |
| 138 | role (the title company, say), type a name and an email or phone, and | |
| 139 | add it. The party appears in the list, and the dates that concern them now | |
| 140 | have reminders for them. | |
| 141 | Made a typo? Each party has Edit (fix the name or email; the next | |
| 142 | reminder uses it) and Remove (its unsent reminders go with it). Remove asks once: it opens | |
| 143 | a line saying what goes and a Yes, remove button. | |
| 144 | 9. **Add a date.** On the same page, add a date the contract added, such as | |
| 145 | an HOA review: a name, a date, who owes it. It joins the deal's list and | |
| 146 | the clock. A date you added has a Remove this date button in its sheet | |
| 147 | (it asks once, like every removal, including Remove this deal), for when the contract drops it; the standard dates cannot be removed, only | |
| 148 | moved or marked done. | |
| 149 | A date on a weekend or US federal holiday says "not a business day · next is Mon, Nov 30"; tap Move to (N in the terminal) to take that day, reason kept. | |
| 150 | 10. **Open a new deal.** Back on the clock, tap New deal. Type an address, | |
| 151 | buyer, seller, contract date and closing date. The standard lengths are | |
| 152 | already filled in (earnest money deposit 3 days, inspection 10, appraisal 21, financing 30, title 14, | |
| 153 | final walkthrough the day before closing) and you can change them; tick | |
| 154 | Count business days to skip weekends. Tap Check the dates to see every | |
| 155 | date the deal would get (label, weekday and date, who owes it) without | |
| 156 | saving anything; a refused form comes back with what you typed and the | |
| 157 | reason beside its field. In the terminal, press c instead of n for the same | |
| 158 | list. Tap Open deal. You land on the new | |
| 159 | deal's page with every date worked out, and it has its own lane on the clock. | |
| 160 | 11. **Close a deal.** Open a deal's page, tap Open on its Closing date and | |
| 161 | mark it done. The deal steps off the clock into the Closed card below it, | |
| 162 | its reminders stop, and its page says "Closed on …". Everything on it still | |
| 163 | opens; reopen the Closing date and the deal is back on the clock. | |
| 164 | A month after you marked it done, a drafted "How is the new home?" check-in | |
| 165 | to your past clients (the buyers, the sellers, or both, by the deal's side) | |
| 166 | waits in Review and the header count; send, edit, hold or decline it like any reminder. | |
| 167 | 12. **Download the calendar file.** On a deal's page, tap Add to calendar. | |
| 168 | You get a calendar file with every date of the deal and two | |
| 169 | alarms for each: one as many days ahead as that date's Reminds N days | |
| 170 | before setting, and one the morning of. Open it in your own calendar app. On the clock, | |
| 171 | Add all to calendar does the same for every open date of every open deal. Download spreadsheet gives the same dates as one file that opens in Excel or Numbers; the Closed list links one with the closed deals too. | |
| 172 | 13. **Print the client timeline.** On a sample deal's page, tap Client | |
| 173 | timeline: its dates in order, who owes each and whether it is done, | |
| 174 | upcoming or overdue, with no controls. Under each open date is one line of what the buyer or seller | |
| 175 | does for it (both, labelled, on a deal for both sides); the terminal prints it dim | |
| 176 | under the date and the MCP tool returns it as the date's `todo` list. Tap Print to make the one-page handout | |
| 177 | for a buyer or seller (the browser's own print works too). In the terminal, open the deal with o and press | |
| 178 | t; over MCP, an agent asks for the `client_timeline` tool. | |
| 179 | When a deal closes, Print broker file on its page makes the one page for the brokerage's transaction file: price, earnest money, commission, every party, every date with the day it was done, waived or moved, and every message you approved or declined, in your words; it is yours alone, not the client's handout. In the terminal, open the deal with o and press f. | |
| 180 | 14. **Fix an address.** On a deal's page, Edit address corrects a typo in | |
| 181 | place: the clock, the client timeline, the calendar file and unsent drafts | |
| 182 | carry the new address, and reminders already sent keep their words. In the | |
| 183 | terminal open the deal and press A; over MCP, the `update_address` tool. | |
| 184 | **Price and earnest money.** A deal may carry a sale price and an earnest | |
| 185 | money amount, in whole dollars (digits only, up to 100,000,000): set them | |
| 186 | when you open the deal, or tap Edit price and earnest money on its page. Under the clock's heading one line adds up your book ("6 open · $2,410,000 under contract · 2 close in November · 3 closed this year, $1,180,000"; once any deal has a commission rate it ends "· $31,000 commission pending · $9,000 earned this year" (open deals with a price and a rate; deals closed this year; the three closed sample deals show it; the figure is on this line only, never on This week or the printed sheet); deals without a price add no dollars and are noted, deals that fell through count in none), and each Closed line shows its price. | |
| 187 | The deal's page and the client timeline show them as `$425,000`, a deal | |
| 188 | with none shows nothing, and the earnest money reminder says the amount | |
| 189 | ("Your $12,750 earnest money deposit is due Nov 7"). The sample deals carry | |
| 190 | figures. Over MCP, the `update_figures` tool; the terminal does not edit them. | |
| 191 | **Commission.** A deal may carry your commission rate, typed as `2.5` or | |
| 192 | `2.5%` (0 to 10, at most two decimals; anything else is refused and keeps | |
| 193 | what you typed), set when you open the deal or under Edit price, earnest | |
| 194 | money and commission. The deal's page then reads "Commission 2.5% · $11,250", | |
| 195 | or "Commission 2.5%" with "add the price to see the amount" while the | |
| 196 | price is missing. It is yours alone: the client timeline, the printed | |
| 197 | handout and every reminder draft never show it. Over the API and MCP it is | |
| 198 | `commission_rate`, in hundredths of a percent (250 is 2.5%). The sample | |
| 199 | deals carry a rate. | |
| 200 | **Closing time and place.** The closing may carry a time (a quarter hour | |
| 201 | from 7:00 am to 8:00 pm) and a place (up to 200 characters): tap Edit | |
| 202 | closing time and place on the deal's page, and clear either by leaving it | |
| 203 | blank. The page and the client timeline read "Closing Nov 21 · 2:00 pm · | |
| 204 | Lakeside Title, 400 Main St", the closing and final walk-through reminders | |
| 205 | say them, and the calendar file makes closing a one-hour event with its | |
| 206 | location (local time, no time zone); with no time it stays an all-day | |
| 207 | event. Moving the closing date keeps them, and the date-changed notice | |
| 208 | names them. The sample closing this week has both. Over MCP, the | |
| 209 | `update_closing` tool; in the terminal, press C on a deal and answer the time | |
| 210 | and the place (blank clears), and the deal view shows the same closing line. | |
| 211 | **Which side you are on.** Each deal says whether you are the buyer's agent, | |
| 212 | the listing agent or both, chosen when you open it (Buyer's agent unless you | |
| 213 | say otherwise) and changed with Save side on its page. A small label, "Buyer | |
| 214 | side", "Listing" or "Both sides", sits beside the address on the clock, the | |
| 215 | deal's page, This week and the Closed list. The **Side** choice beside Find | |
| 216 | narrows the clock to Buyer or Listing deals (a deal for both sides shows under | |
| 217 | each) and combines with a search; the Print link keeps it. 9 Orchard Row is a | |
| 218 | listing in the samples, and Restore the sample deals brings that back. Over MCP, | |
| 219 | In the terminal, `n` asks the side last (Buyer's agent, Listing agent or Both; enter is Buyer's agent, any other word is refused), the clock, This week and the deal show the label, and Y on a deal changes it. A side that is not buyer, listing or both is refused with 422 on the page, the API and the terminal alike. `list_deals` takes `side` and `set_side` changes it; `GET /api/deals?side=listing` does the same. | |
| 220 | Each date also carries a short working note only you see, such as "Appraisal ordered, AMC says Thursday": write it in the date's sheet (Save note), or press T on a date in the terminal; it shows under the date, in This week and on the printed week, and never on a client page or in a message. | |
| 221 | 15. **Put the samples back.** After the walk-through, an admin taps Sample | |
| 222 | deals below the clock, then Restore the sample deals and confirms: the seven | |
| 223 | samples (the three closed ones too) return as they were, dated from today, and the deals you opened are | |
| 224 | left alone. Only an admin sees it. In the terminal press R; over MCP, the `restore_samples` tool. | |
| 225 | 16. **Put it on your phone.** In your phone's browser, choose Add to Home Screen: | |
| 226 | the deal-clock mark sits beside the app's name, and it opens full screen | |
| 227 | like any app. The same mark is the browser tab's icon. | |
| 99 | **Status update.** A deal's page offers each buyer and seller a drafted summary | |
| 100 | of what is done, what is next and when it closes, which you edit and send or | |
| 101 | decline like any reminder. **Messages** on the page keeps every message you | |
| 102 | approved, in your words. | |
| 228 | 103 | |
| 229 | ## Activity: who approved what | |
| 104 | ## Commission and your year | |
| 105 | ||
| 106 | A deal can carry a sale price, earnest money and your commission rate (typed | |
| 107 | as `2.5` or `2.5%`). The deal's page then reads "Commission 2.5% · $11,250", | |
| 108 | and the book line under the clock ends with the commission pending on open | |
| 109 | deals and the commission earned on deals closed this year. Commission is yours | |
| 110 | alone: it never appears on the client timeline, a handout or a reminder. | |
| 111 | The Closed list shows each closed deal's price, and **Print broker file** on a | |
| 112 | closed deal makes the one page for the brokerage's transaction file: price, | |
| 113 | earnest money, commission, every party, every date with the day it was done, | |
| 114 | waived or moved, and every message you approved or declined. | |
| 115 | ||
| 116 | ## Activity | |
| 230 | 117 | |
| 231 | 118 | An admin sees **Activity** in the header: the newest hundred things anyone |
| 232 | tried to change, one plain line each — who (or "someone not signed in"), what | |
| 233 | ("sent a reminder", "declined a reminder", "moved a date", "saved the | |
| 234 | profile"), on which deal (linked while it exists), when, and, if it was | |
| 235 | refused, why. **Messages** narrows it to sends, declines and undos, so the | |
| 236 | sales meeting can show that every message that went out was approved by a | |
| 237 | named person at a stated time; **Older** pages back. In the terminal press L, | |
| 238 | then m for only messages, o for older and y for newer. A signed-in user who is | |
| 239 | not an admin is told no; a stranger is asked to sign in. **Download | |
| 240 | spreadsheet** saves the same trail (every row, or only messages) as a CSV file | |
| 241 | for a compliance file. | |
| 119 | tried to change, one plain line each (who, what, on which deal, when, and why | |
| 120 | it was refused if it was). **Messages** narrows it to sends, declines and | |
| 121 | undos, so the sales meeting can show that every message that went out was | |
| 122 | approved by a named person at a stated time. Anyone else is told no. | |
| 123 | ||
| 124 | ## Spreadsheets and calendar | |
| 125 | ||
| 126 | On a deal's page, **Add to calendar** gives a file with every date of the deal | |
| 127 | and two alarms for each: one as many days ahead as that date's "Reminds N days | |
| 128 | before" setting, and one the morning of. On the clock, **Add all to calendar** | |
| 129 | does it for every open date. **Download spreadsheet** gives the same dates as | |
| 130 | one file that opens in Excel or Numbers; the Closed list links one that | |
| 131 | includes closed deals. | |
| 242 | 132 | |
| 243 | 133 | ## Make it yours |
| 244 | 134 | |
| 245 | The app ships with a sample agent. To carry your own, open **Profile** in the | |
| 246 | header and type your name, brokerage, phone (digits, spaces, `+ ( ) - .`) and | |
| 247 | email once. Below them, **A line of your own at the end of every message** is | |
| 248 | optional: one line, up to 200 characters, like "Text me anytime, I answer within | |
| 249 | the hour". Every new draft carries it above the sign-off; sent and held drafts | |
| 250 | keep their words. **Use defaults** goes back to the sample. Only an admin can save it; | |
| 251 | over the API it is `GET/PUT/DELETE /api/profile` (DELETE is Use defaults), over MCP | |
| 252 | `get_profile` and `set_profile`. In the terminal press I, then e to edit (enter | |
| 253 | keeps a field, including the line, which `-` clears) or U for the defaults; a guest or a non-admin sees it read-only. | |
| 135 | The app ships with a sample agent; the Profile in step 10 replaces it. Each | |
| 136 | deal sets how many days before a date its reminder goes (1 to 30), and your | |
| 137 | Profile may add one line of your own to the end of every message ("Text me | |
| 138 | anytime, I answer within the hour"). Whoever runs the app can set your usual | |
| 139 | contract lengths once; see the technical page. On your phone, choose Add to | |
| 140 | Home Screen: the deal-clock mark sits beside the name and it opens full screen. | |
| 254 | 141 | |
| 255 | They show in the header (the phone and email are tap-to-call and | |
| 256 | tap-to-write), on the client timeline you hand to buyers and sellers, and in | |
| 257 | the terminal. Every new reminder draft ends with your name and brokerage, then | |
| 258 | your phone and email, so a party can call or write back straight from it. | |
| 259 | Reminders you already sent keep the words you approved. A phone or email that | |
| 260 | does not look right is refused, and the form names the field. | |
| 261 | ||
| 262 | Your contracts may use other standard contingency lengths. Set them once and | |
| 263 | every New deal form, its date preview, the API and the MCP tool start from them | |
| 264 | (you can still change any length for one deal): | |
| 265 | ||
| 266 | - `DEAL_CLOCK_EARNEST_DAYS` (brief: 3), `DEAL_CLOCK_INSPECTION_DAYS` (10), `DEAL_CLOCK_APPRAISAL_DAYS` (21), | |
| 267 | `DEAL_CLOCK_FINANCING_DAYS` (30), `DEAL_CLOCK_TITLE_DAYS` (14): days after the | |
| 268 | contract date. | |
| 269 | - `DEAL_CLOCK_WALKTHROUGH_DAYS` (1): days before closing. | |
| 270 | - `DEAL_CLOCK_BUSINESS_DAYS`: `1` to count business days by default; otherwise | |
| 271 | calendar days. | |
| 272 | ||
| 273 | A length that is missing, not a whole number, or outside 0 to 180 is the | |
| 274 | brief's, with a line in the log. The sample deals always use the brief's. | |
| 142 | **Put the samples back.** After the tour, an admin taps **Sample deals** below | |
| 143 | the clock, then **Restore the sample deals** and confirms: the seven samples | |
| 144 | return as they were, dated from today, and the deals you opened are left alone. | |
| 275 | 145 | |
| 276 | 146 | ## What is real, and what is not yet |
| 277 | 147 | |
| 278 | 148 | - **Real:** the dates and their math, mark done, moves with their reasons, |
| 279 | 149 | who owes what, the reminder drafts and editing them, the record of what was |
| 280 | sent, the reasons for messages you chose not to send, the calendar file, and adding parties, dates and deals. | |
| 281 | - **Real:** the clock, a deal page and the client timeline are tested to answer in under 50 ms with 200 deals. | |
| 282 | - **Real:** every page is checked for keyboard and screen-reader use: a skip link, labelled fields, named buttons and links, one heading outline. | |
| 150 | sent, the reasons for messages you chose not to send, the calendar file, and | |
| 151 | adding parties, dates and deals. | |
| 152 | - **Real:** the clock, a deal page and the client timeline answer in under 50 | |
| 153 | ms with 200 deals. | |
| 154 | - **Real:** every page is checked for keyboard and screen-reader use. | |
| 283 | 155 | - **Simulated:** sending. Send records that a reminder went out and keeps the |
| 284 | 156 | words that were approved; no email or text message leaves the app. |
| 285 | 157 | - **Not in this prototype (phase two):** real email or text messages, |
| 286 | 158 | e-signature, document storage, and reading the dates out of a contract PDF. |
| 287 | 159 | |
| 288 | ## Signing in, and who can remove a deal | |
| 160 | ## Signing in | |
| 289 | 161 | |
| 290 | Deals are private. Sign in with your forge account to see the clock or a | |
| 291 | deal, and to open deals, mark dates done, move them, add dates and parties, | |
| 292 | and send reminders. A visitor who is not signed in is asked to sign in and | |
| 293 | sees nothing of any deal. Only the agent who opened a deal, or an admin, can | |
| 294 | remove it, so the sample deals can be removed by an admin only. | |
| 162 | Deals are private. Sign in with your forge account to see the clock or a deal, | |
| 163 | and to open deals, mark dates done, move them, add dates and parties, and send | |
| 164 | reminders. A visitor who is not signed in sees nothing of any deal. Only the | |
| 165 | agent who opened a deal, or an admin, can remove it, so the sample deals can be | |
| 166 | removed by an admin only. |
docs/TECHNICAL.md +60
| @@ -351,3 +351,63 @@ validates and words them. The calendar file writes a timed closing as floating l | ||
| 351 | 351 | ### Side |
| 352 | 352 | |
| 353 | 353 | `deal.side` (`buyer`, `listing` or `both`; migration default `buyer`) says which side the agent represents. `src/side.ts` holds the words, `sideOf` (nothing or blank is `buyer`, anything but the three words is refused with 422 and `field: "side"`) and `onSide` (the narrowing: a `both` deal is on each side). It is an `update` of the deal, audited as one: `PATCH /api/deals/:id` with `side`, `POST /deals/:id/side`, MCP `set_side`. `GET /` and `GET /week` take `?side=buyer|listing|all` beside `?q=`; `GET /api/deals` and `list_deals` take `side` too. `GET /reminders/today` does not narrow by side. No new contract cell. |
| 354 | ||
| 355 | ## By feature: keys, tools and routes | |
| 356 | ||
| 357 | What the README's tour and sections do, door by door. The terminal keys are | |
| 358 | those of `src/terminal.ts`; the tools are those of `src/mcp.ts`. | |
| 359 | ||
| 360 | - **This week.** Terminal `w`; MCP `this_week`; page `/week` (Print this week). | |
| 361 | - **People.** Terminal `P`; MCP `list_people`; `GET /api/people`. | |
| 362 | - **Find a deal.** Terminal `/` then the text and enter (the dates, week and | |
| 363 | reminders views narrow; `/` then enter alone clears it). MCP `list_deals` takes | |
| 364 | an optional `query` ("what's left on the Elm Street deal?") and `side`; | |
| 365 | `GET /api/deals?q=elm` and `GET /api/deals?side=listing` do the same. A query | |
| 366 | over 100 characters or with control characters is a 400, | |
| 367 | `{error:"invalid", field:"q"}`. A side that is not buyer, listing or both is a | |
| 368 | 422 on the page, the API and the terminal alike. | |
| 369 | - **Add a date over the API.** `POST /api/deals/:id/deadlines` with `label` (1 to | |
| 370 | 100 characters), `due` (YYYY-MM-DD), `owes` (a party role) and optionally `what` | |
| 371 | and `lead_days` (1 to 30). It answers 201 with the date, or 400 naming the | |
| 372 | field. A label typed exactly as a suggestion (`/openapi.json` lists them) sets | |
| 373 | that date's reminder lead unless `lead_days` is given. It is the deal update | |
| 374 | cell, like the page and MCP `add_date`. | |
| 375 | - **Reminders.** Terminal: `h` holds on the reminders list, `H` shows held ones, | |
| 376 | `B` brings one back. | |
| 377 | - **Status update.** Terminal: open the deal, move to a buyer or seller, press | |
| 378 | `S` (type `send`, or `no` and a reason). MCP `draft_status_update` and | |
| 379 | `send_status_update`. | |
| 380 | - **Messages.** Terminal: open the deal with `o`, then `s`. | |
| 381 | - **Client timeline.** Terminal: `o` then `t`. MCP `client_timeline`, which returns | |
| 382 | each date's one-line "what you do" as its `todo` list. The terminal prints it | |
| 383 | dim under the date. | |
| 384 | - **Broker file.** Terminal: open the deal with `o` and press `f`. | |
| 385 | - **Fix an address.** Terminal: open the deal and press `A`; MCP `update_address`. | |
| 386 | - **Price, earnest money, commission.** MCP `update_figures` (the terminal does | |
| 387 | not edit them). Over the API and MCP the rate is `commission_rate`, in | |
| 388 | hundredths of a percent (250 is 2.5%). The rate is 0 to 10 with at most two | |
| 389 | decimals on the page; anything else is refused and keeps what was typed. | |
| 390 | - **Closing time and place.** MCP `update_closing`; terminal `C` on a deal asks | |
| 391 | the time and the place (blank clears). The calendar file writes a timed | |
| 392 | closing as a one-hour event with its location in local time, no time zone. | |
| 393 | - **Side.** Terminal: `n` asks the side last (Buyer's agent, Listing agent or | |
| 394 | Both; enter is Buyer's agent, any other word is refused) and `Y` on a deal | |
| 395 | changes it. MCP `set_side`. | |
| 396 | - **Date note.** Terminal `T` on a date. | |
| 397 | - **New deal preview.** Terminal `c` instead of `n` lists the dates without saving. | |
| 398 | - **Move to next business day.** `N` in the terminal. | |
| 399 | - **Restore the samples.** Terminal `R`; MCP `restore_samples` (admin only). | |
| 400 | - **Activity.** Terminal `L`, then `m` for only messages, `o` for older and `y` | |
| 401 | for newer. Download spreadsheet is the same trail as a CSV file. | |
| 402 | - **Profile.** `GET/PUT/DELETE /api/profile` (DELETE is Use defaults); MCP | |
| 403 | `get_profile` and `set_profile`; terminal `I`, then `e` to edit (enter keeps a | |
| 404 | field, including the line, which `-` clears) or `U` for the defaults; a guest or | |
| 405 | a non-admin sees it read-only. Phone accepts digits, spaces and `+ ( ) - .`. | |
| 406 | - **Contract lengths.** Set once, every New deal form, its date preview, the API | |
| 407 | and the MCP tool start from them: `DEAL_CLOCK_EARNEST_DAYS` (3), | |
| 408 | `DEAL_CLOCK_INSPECTION_DAYS` (10), `DEAL_CLOCK_APPRAISAL_DAYS` (21), | |
| 409 | `DEAL_CLOCK_FINANCING_DAYS` (30), `DEAL_CLOCK_TITLE_DAYS` (14): days after the | |
| 410 | contract date; `DEAL_CLOCK_WALKTHROUGH_DAYS` (1): days before closing; | |
| 411 | `DEAL_CLOCK_BUSINESS_DAYS`: `1` to count business days by default. A length that | |
| 412 | is missing, not a whole number, or outside 0 to 180 is the brief's, with a line | |
| 413 | in the log. The sample deals always use the brief's. |
new above
offline