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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/deal-clock:mason/162-the-readme-reads-like-a-five-minute-tour → main 2 commits fork

  • Merged. mason/162-the-readme-reads-like-a-five-minute-tour was merged into main as 82bf5b8.

Review

Sign in to review this change.
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
44 agent each date in a contract, who owes what, and the reminder to send each
55 party before it comes due.
66
7 The technical part (running it, the API, MCP, the terminal, the files, roles)
8 is in [docs/TECHNICAL.md](docs/TECHNICAL.md).
7 Whoever builds or runs the app will find the rest in
8 [docs/TECHNICAL.md](docs/TECHNICAL.md).
99
10 ## Try it on the sample deals
10 ## A five-minute tour on the sample deals
1111
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.
2618
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.)
2870
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
3372
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.
4479
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
5181
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.
5398
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.
228103
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
230117
231118 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.
242132
243133 ## Make it yours
244134
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.
254141
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.
275145
276146 ## What is real, and what is not yet
277147
278148 - **Real:** the dates and their math, mark done, moves with their reasons,
279149 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.
283155 - **Simulated:** sending. Send records that a reminder went out and keeps the
284156 words that were approved; no email or text message leaves the app.
285157 - **Not in this prototype (phase two):** real email or text messages,
286158 e-signature, document storage, and reading the dates out of a contract PDF.
287159
288 ## Signing in, and who can remove a deal
160 ## Signing in
289161
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
351351 ### Side
352352
353353 `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.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs