deal-clock

Every deadline of every deal on one timeline, so nothing slips. It shows an agent each date in a contract, who owes what, and the reminder to send each party before it comes due.

Whoever builds or runs the app will find the rest in docs/TECHNICAL.md.

A five-minute tour on the sample deals

Eight sample deals are already in, so the first screen is never empty. Four are open: 1418 Alder Lane, 77 Harbor View Dr (Unit 4B), 9 Orchard Row and 2210 Juniper Court. Three closed earlier this year: 35 Mill Pond Road, 602 Cedar Heights Blvd and 14 Saltmarsh Lane. One, 58 Larkspur Way, closed a year ago today, so its home anniversary note waits in Review. No sample date falls on a weekend or a federal holiday. The samples stay current: every time the app starts, the ones nobody has touched move forward so the screen always looks like today.

Signed in, the same steps are in the app under Tour in the header, each with a link to the page it names. In the terminal press G for the same steps.

1. Sign in. Tap Sign in on the first page and use your forge account.

Until you do, you see only what deal-clock does and a still picture of a made-up deal; no real deal is read. Once in, you land on the clock with 77 Harbor View Dr, Unit 4B, 1418 Alder Lane, 9 Orchard Row and 2210 Juniper Court.

1. Read the clock. One lane per open deal. Time runs left to right and

today is the dark line down the middle. Every date in a contract is a marker: red is overdue (the inspection on 77 Harbor View Dr), amber is due within three days, teal is coming up, grey is done (the earlier dates on 1418 Alder Lane, which closes in a few days). Under the heading, one line adds up your book, 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" (the November count follows the month you open it in). Below the clock, This week lists every open date that is overdue or due in the next seven days, with who owes it.

1. Open a deal. Tap the red inspection marker on 77 Harbor View Dr. A

sheet opens with the date, who owes it (the buyer), what is owed, and the reminders for each party. Tap the address to open the deal's page: every date, every party, the messages you have sent. The inspection there reads "10:30 am · 77 Harbor View Dr, Unit 4B", the time and place the buyer has to be at.

1. Mark a date done. On 1418 Alder Lane, open a coming date such as

Financing and tap Mark done. The marker turns grey and its reminders stop. Reopen puts it back.

1. Move a date, with a reason. Back on Harbor View, open the inspection

marker and tap Move this date: pick a new date and say why ("Inspector delayed"). The marker jumps, and the sheet lists the move, the reason and who made it. A "Date changed" notice is drafted for each party the date concerns. On 9 Orchard Row the appraisal has already been moved; open it to see where from and to, and why.

1. Review and approve today's reminders. Tap Review in the header. The

first reminder is marked "Start here": it is the clock's most pressing one. Each unsent reminder shows the words it would send, already filled in, for a party such as the buyer Samuel Reyes. Edit them if you like, then Send, Don't send (it asks why) or Tomorrow. Send records your approval and offers Open in Mail or Open in Messages, which open your own app with the words: deal-clock never sends anything itself. The count in the header goes down. Under a deal's dates, Coming reminders lists what the app will draft next, by day, party and date; each is drafted for your approval and nothing is sent by itself. The terminal's deal view lists the same.

1. Hand the client a timeline. On 1418 Alder Lane's page tap **Client

timeline: its dates in order, who owes each, and what the buyer or seller does for it, with no controls. Tap Print** for a one-page handout for Maya and Tom Okafor.

1. Print the week. Beside the This week heading tap **Print this

week** for a one-page sheet of the same rows, ready for the Monday office meeting. It starts with the overdue Harbor View inspection, then the days ahead, including the closing on 1418 Alder Lane. Each overdue row names who owes it and whether they were told ("Last told Nov 6" or "Not told yet"); declined and held drafts don't count.

1. See People. Open People in the header. Each person on your deals

appears once, with every open date they owe across all deals, soonest first. Try Priya Nair, the lender on both 1418 Alder Lane and 9 Orchard Row. Each person also shows when you last sent them a reminder or notice, and about what ("Last heard Nov 6 · Financing, 12 Oak Lane"), or "Nothing sent yet"; declined and held drafts don't count. Type a name, phone, email or address into Find a person to narrow the list (try "priya"); Clear brings everyone back. Tap a number to call or text, an address to write. In the terminal press P, then / to find a person (enter alone clears it); over MCP ask for list_people.

1. Set up your Profile. Open Profile in the header and type your name,

brokerage, phone and email. They appear in the header, on the client timeline and at the foot of every new reminder. (Only an admin can save it; Use defaults goes back to the sample agent.)

Holding a reminder for later

On the review page, Tomorrow holds a draft until the next morning. To hold it longer, pick a "Bring back on" date (today or later, up to a year ahead) first. It stays out of the count and the list until that morning, then returns under Today's reminders marked "Back from hold", with your edited words. The deal's page says "Returns" and the date while it waits. In the terminal, h on a reminder asks for the date; leave it blank for tomorrow.

How people like to be reached

A realtor knows who answers texts and who only reads email. When you add a party, or open Edit beside one on the deal page, choose Reaches best by: text, email or phone call (or no preference). People then shows "Reaches best by text" beside the name, and so does each draft on the review page. It is a note for you: the drafted words stay the same, and the choice travels in the all-deals export. In the terminal, p (add a party) and e (correct one) ask the same question, and the deal view, P and the reminders list show the answer. The sample parties carry a mix.

Papers a date needs

A date is rarely just a date: the inspection needs the signed access form, financing needs the lender's approval letter. Open a date on the deal page and use Papers to list up to eight of them (names only, 1 to 80 characters; nothing is stored) and Mark in as each arrives. A standard date offers one suggestion, such as "Lender's approval letter" for Financing, and adds it only when you press Add suggested. The deal page says "2 of 3 papers in" under the date; the client timeline lists what is still needed under the date, with papers already in struck through and marked "in". Marking a date done while papers are open asks once ("2 papers still open. Mark done anyway?") and then goes ahead. The all-deals export carries the papers (older files without them still import). Two sample deals carry a few.

In the terminal, i on a date shows its papers ("2 of 3 papers in" also shows beside the date) and asks for one command: add NAME, in N, out N, remove N, or suggest to take the offered paper. x asks once, "2 papers still open. Mark done anyway?", and goes ahead on yes.

Finding a deal

Type part of an address, or of a buyer's, seller's or other party's name, phone or email, into Find a deal above the clock and press Find (try harbor). The clock, This week and today's reminders narrow to the matches; Clear brings them back. The Side choice beside it narrows to deals where you are the buyer's agent or the listing agent. The Closing choice (Any, This week, This month, Later) narrows to deals by closing date and composes with Find and Side, and the Review all link carries it to today's reminders; This week is today and the six days after, This month runs to the month's end, and an unknown value is refused. 9 Orchard Row is a listing in the samples; on a listing, add "Listing agreement expires" as a date and the clock and the deal page flag a closing that falls after it (9 Orchard Row shows the flag). It is yours alone: it is never on the client timeline and no party is drafted anything about it. You see it on the clock, in This week and on the deal's page, and the calendar file gives it an alarm 30 days ahead.

Opening and shaping a deal

New deal asks for an address, buyer, seller (with an optional email and phone for each), contract date and closing date, and which side you are on. Each mistake is named in a sentence beside its field and nothing is saved until all are right; a good deal lands on its own page with every date and the reminders drafted. Both doors ask for the contacts: the terminal's n asks for each party's email or phone after the side and cash questions (enter skips; an answer with an @ is the email, anything else the phone). The standard lengths (earnest money deposit 3 days, inspection 10, appraisal 21, financing 30, title 14, final walkthrough the day before closing) are filled in and you can change them; Check the dates shows every date the deal would get without saving anything. Tick Cash offer (no loan) and the deal gets no appraisal or financing date and no lender is asked for anything; "Cash" shows beside the side. On a deal's page you can add a party (Use someone from your other deals fills in a person you already have), fix a typo with Edit, add a date the contract added (an HOA review), waive a contingency the buyer gave up, change who owes a date, correct the address, and set the closing time and place. If two of your open deals close the same day less than two hours apart, an amber "Also closing at 2:30 pm" line names the other deal on This week, on both deals' pages and in the terminal's deal view; an inspection, walkthrough or closing less than two hours from another of your timed appointments that day gets an "Also at 10:00 am: Inspection, 12 Elm St" line the same way. An Inspection or Final walkthrough row has Set time and place too (a time on a quarter hour and one line for where, either optional; clear both to remove them): the buyer sees them beside the date on the client timeline, your calendar file gives that event the time (in your Profile time zone) and location, and the reminder says "10:00 am at 12 Elm St". In the terminal press @ on the date; over MCP use set_appointment; both show it on the date. A date on a weekend or federal holiday says so and offers Move to the next business day. Slid a date by mistake? Its row on the deal page offers Undo move (back to Nov 20): one tap puts it back, with its reminders (in the terminal, U on the date). It is offered only to whoever made that move, once (one level), and nothing once the date is done, waived or moved again by someone else. For an addendum that moves several dates, Amend the contract takes one reason and sends each party one notice. When buyer and seller agree to close on another day, Closing moved takes the new date and a reason, then lists every open date that would shift by the same days with its old and new value (weekends and holidays roll to a business day; dates you added are left alone). Untick any that should stay; nothing changes until you confirm. In the terminal press V on a deal: it asks for the new date and the reason, prints the same list, and takes yes to move them all or the numbers of the dates to keep where they are. Every date also takes a short working note only you see. Each deal also has a Private note box (up to 500 characters) that never reaches a draft, the client timeline or anything printed; in the terminal, open the deal and press K to see it and write a new one. A deal that falls through is marked with Fell through… and moves to the Closed list; Reopen brings it back. Closing a deal is marking its Closing date done: it steps off the clock, and a month later a drafted "How is the new home?" check-in waits in Review, and a year after, a "Happy home anniversary" note to each past client that gently asks for referrals.

Status update. A deal's page offers each buyer and seller a drafted summary of what is done, what is next and when it closes, which you edit and send or decline like any reminder. Messages on the page keeps every message you approved, in your words.

Commission and your year

A deal can carry a sale price, earnest money and your commission rate (typed as 2.5 or 2.5%). The deal's page then reads "Commission 2.5% · $11,250", and the book line under the clock ends with the commission pending on open deals and the commission earned on deals closed this year. Commission is yours alone: it never appears on the client timeline, a handout or a reminder. The Closed list shows each closed deal's price and "Closed in N days" (the contract date to the day its Closing date was marked done; deals that fell through are listed apart and left out). Under the book line, the year's pace reads "Average 34 days to close · fastest 21 days · slowest 52 days" over deals closed this year, or says in words that none has closed yet. Print broker file on a closed deal 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.

Activity

An admin sees Activity in the header: the newest hundred things anyone tried to change, one plain line each (who, what, on which deal, when, and why it was refused if it was). Messages narrows it to sends, declines and undos, so the sales meeting can show that every message that went out was approved by a named person at a stated time. Anyone else is told no.

Download spreadsheet, at the foot of the Activity page, gives every line (not just the newest hundred) as one file that opens in Excel or Numbers. With Messages chosen it holds only the messages. Only an admin sees the button.

Spreadsheets and calendar

On a deal's page, Add to calendar gives a file with every date of the deal and two alarms for each: one as many days ahead as that date's "Reminds N days before" setting, and one the morning of. On the clock, Add all to calendar does it for every open date. Download spreadsheet gives the same dates as one file that opens in Excel or Numbers; the Closed list links one that includes closed deals.

Make it yours

The app ships with a sample agent; the Profile in step 10 replaces it. Each deal sets how many days before a date its reminder goes (1 to 30), and your Profile may add one line of your own to the end of every message ("Text me anytime, I answer within the hour"). Set your time zone on the Profile so "today" is your day, not the server's. Choose a voice there too: Warm (the friendly wording, the default) or Brief (the same facts in shorter sentences, no pleasantry paragraph); the page shows a sample of each, and the terminal's profile (I, then e) and the set_profile tool set it too, for an admin only. New drafts use it; a message already sent, or held, keeps the words it had when you sent or held it. Whoever runs the app can set your usual contract lengths once; see the technical page. On your phone, choose Add to Home Screen: the deal-clock mark sits beside the name and it opens full screen.

Keep your deals. On the Profile, Download all my deals saves one file with every deal you can read: addresses, figures, dates, parties, notes, every move with its reason, closed and fell-through deals, and the exact words of every message you sent. In the terminal, press E to save the same file. If you ever stop using the app, you keep them.

Bring deals back. Switching laptops or accounts? On the Profile, under Bring deals back from a file, choose the file you downloaded and press the button. Each deal returns as yours, with its dates (done, waived, moved), parties, notes, side, cash flag, closing time and place; closed and fell-through deals stay so. A deal already in your book with the same address and contract date is skipped, so doing it twice adds nothing. The record of messages sent or declined is not brought back. A file with a mistake in any deal brings nothing, and says which deal and field. In the terminal, press E to write your file, and O to bring deals back from a file in the exports folder (enter alone takes the newest).

Put the samples back. After the tour, an admin taps Sample deals below the clock, then Restore the sample deals and confirms: the eight samples return as they were, dated from today, and the deals you opened are left alone.

What is real, and what is not yet

• Real: the dates and their math, mark done, moves with their reasons,

who owes what, the reminder drafts and editing them, the record of what was sent, the reasons for messages you chose not to send, the calendar file, and adding parties, dates and deals.

• Real: download all your deals in one file and bring them back on another

laptop or account; see Keep your deals.

• Real: a time and place for a closing, inspection or final walkthrough,

shown to the buyer, in your calendar file and in the reminder; see Opening and shaping a deal.

• Real: two appointments on the same day less than two hours apart are

flagged on both deals; see Opening and shaping a deal.

• Real: a listing agreement that expires before the closing is flagged;

see Finding a deal.

• Real: "How is the new home?" and home-anniversary notes are drafted for

your approval after a closing; nothing goes until you send it; see Opening and shaping a deal.

• Real: the Activity record of what was tried and approved (admins see it)

and its spreadsheet; see Activity.

• Real: commission on each deal and your year's pending and earned totals;

see Commission and your year.

• Real: the clock, a deal page, the client timeline, People, the reminder

review (Today's reminders) and the printed This week sheet answer in under 50 ms with 200 deals; src/speed.test.ts pins each.

• Real: every page is checked for keyboard and screen-reader use.
• Simulated: sending. Send records that a reminder went out and keeps the

words that were approved; no email or text message leaves the app.

• Not in this prototype (phase two): real email or text messages,

e-signature, document storage, and reading the dates out of a contract PDF.

Signing in

Deals are private. Sign in with your forge account to see the clock or a deal, and to open deals, mark dates done, move them, add dates and parties, and send reminders. A visitor who is not signed in sees nothing of any deal. Only the agent who opened a deal, or an admin, can remove it, so the sample deals can be removed by an admin only.

Starting with your own deals

After the sales meeting, open Profile, choose Clear sample deals… and confirm. Every sample deal you have not changed goes, with its dates, contacts and messages; a sample you edited and every deal you opened stay. The clock then says how to add your first deal, and the samples are not written again when the app restarts. (An admin can still bring them back with Restore the sample deals on the clock.) Only an admin can clear them.