Public: anyone can read this; the crew can change it.

A realtor reads the README in one go: what it does, a five-minute walk through the sample deals, and what is not real yet, with the technical part kept separate #18

Merged opened this

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

Merged

The README is now a plain-words page for the agent. Everything technical has moved to a new docs/TECHNICAL.md. No code changed.

Notes

shipped production is serving it deploy d2eada7

opened this

The README is now a plain-words page for the agent. Everything technical has moved to a new docs/TECHNICAL.md. No code changed. I did not run bun test or tsc, and the pull's description (this message) does not list tests as passing. The diff is docs only, and nothing in src or scripts reads the README. The bun x tsc --noEmit I ran printed its help text instead of type errors. scripts/fast.ts doesn't exist, and docs/VISION.md isn't in the repo either.

What moved where

  • README.md (about 860 words, no code blocks, no file paths):

- two sentences on what the app is for; - Try it on the sample deals, an 11-step walk with what the agent sees at each step; - What is real, and what is not yet; - how to sign in and who can remove a deal; - one line linking to docs/TECHNICAL.md.

  • docs/TECHNICAL.md (new): the old "For whoever runs it" section, the shape and file table, the door, the audit trail, roles and "Any interface" are moved over word for word. I added a short settings section above them, holding the header-name settings (DEAL_CLOCK_AGENT, DEAL_CLOCK_BROKERAGE), TZ, and a note that sending is simulated.
  • AGENTS.md: it had no links to README sections. I added a rule saying the README is for the agent and anything technical goes in docs/TECHNICAL.md, and the Finish line now points there for how to run it.

The walk covers

  • Opening a marker on 77 Harbor View, which has the overdue inspection.
  • Reading and editing a reminder, then sending it.
  • Moving a date with a reason.
  • The moved appraisal on 9 Orchard Row.
  • Marking a date done on 1418 Alder Lane, which closes this week.
  • Adding a party and then a date on 2210 Juniper Court, the one just signed.
  • Opening a new deal and downloading the calendar file.

Nothing for #9, #12 or #13 is in it.

Checked against bun run src/server.ts on fresh data with a signed identity

  • Sample deals: the four lanes exist and are in the states described (overdue inspection, closing in 4 days, moved appraisal with its reason, just signed).
  • Reminders: they are grouped 3 days before and the morning of. The draft opens as editable subject and message fields. After a send with edited words, the sheet shows "Sent" with the edited words.
  • Moving and marking done: a move with a reason shows as "Moved … → …: reason · person". A done date says "Done, so no reminders go out", and the button becomes Reopen.
  • Adding: a new party appears in the list and gets reminders. Opening a new deal redirects to its page with every date worked out.
  • Calendar file: the download is an .ics named after the address, with a 3-days-before alarm and a morning-of alarm.
  • Sign-in and removal: the sign-in prompt for visitors who aren't signed in is in the page code. Sample deals have the author "Sample data", so only an admin can remove them.

Not checked in a browser or on a preview: tapping a marker, the jump of a moved marker on the timeline, the in-page confirmation text, and the "to send" count going down after a send. I checked what the pages and routes contain, not how they look.

I also did not read the source for the phrase "Reopen puts it back"; the Reopen button is confirmed.

Left out: a screenshot or visual check, and any README text about the terminal, MCP or API, which now live only in docs/TECHNICAL.md.

🤖 Generated with Claude Code

Closes #15

2 earlier comments · 1 event
commented

The README is now a plain-words page for the agent. Everything technical has moved to a new docs/TECHNICAL.md. No code changed. I did not run bun test or tsc, and the pull's description (this message) does not list tests as passing. The diff is docs only, and nothing in src or scripts reads the README. The bun x tsc --noEmit I ran printed its help text instead of type errors. scripts/fast.ts doesn't exist, and docs/VISION.md isn't in the repo either.

What moved where

  • README.md (about 860 words, no code blocks, no file paths):

- two sentences on what the app is for; - Try it on the sample deals, an 11-step walk with what the agent sees at each step; - What is real, and what is not yet; - how to sign in and who can remove a deal; - one line linking to docs/TECHNICAL.md.

  • docs/TECHNICAL.md (new): the old "For whoever runs it" section, the shape and file table, the door, the audit trail, roles and "Any interface" are moved over word for word. I added a short settings section above them, holding the header-name settings (DEAL_CLOCK_AGENT, DEAL_CLOCK_BROKERAGE), TZ, and a note that sending is simulated.
  • AGENTS.md: it had no links to README sections. I added a rule saying the README is for the agent and anything technical goes in docs/TECHNICAL.md, and the Finish line now points there for how to run it.

The walk covers

  • Opening a marker on 77 Harbor View, which has the overdue inspection.
  • Reading and editing a reminder, then sending it.
  • Moving a date with a reason.
  • The moved appraisal on 9 Orchard Row.
  • Marking a date done on 1418 Alder Lane, which closes this week.
  • Adding a party and then a date on 2210 Juniper Court, the one just signed.
  • Opening a new deal and downloading the calendar file.

Nothing for #9, #12 or #13 is in it.

Checked against bun run src/server.ts on fresh data with a signed identity

  • Sample deals: the four lanes exist and are in the states described (overdue inspection, closing in 4 days, moved appraisal with its reason, just signed).
  • Reminders: they are grouped 3 days before and the morning of. The draft opens as editable subject and message fields. After a send with edited words, the sheet shows "Sent" with the edited words.
  • Moving and marking done: a move with a reason shows as "Moved … → …: reason · person". A done date says "Done, so no reminders go out", and the button becomes Reopen.
  • Adding: a new party appears in the list and gets reminders. Opening a new deal redirects to its page with every date worked out.
  • Calendar file: the download is an .ics named after the address, with a 3-days-before alarm and a morning-of alarm.
  • Sign-in and removal: the sign-in prompt for visitors who aren't signed in is in the page code. Sample deals have the author "Sample data", so only an admin can remove them.

Not checked in a browser or on a preview: tapping a marker, the jump of a moved marker on the timeline, the in-page confirmation text, and the "to send" count going down after a send. I checked what the pages and routes contain, not how they look.

I also did not read the source for the phrase "Reopen puts it back"; the Reopen button is confirmed.

Left out: a screenshot or visual check, and any README text about the terminal, MCP or API, which now live only in docs/TECHNICAL.md.

🤖 Generated with Claude Code

commented

I merged main into the branch, resolved the one conflict in README.md, and pushed. bun test passes (88 tests, 0 failures). I didn't run bun x tsc --noEmit or bun scripts/gate.ts this time.

main had added a way to correct a party's name or contact, remove a party, and remove a date the contract dropped (#16). That change edited the paragraphs of the old README that this pull moves out, so I kept this pull's README and carried those additions over:

  • README.md: step 8 of the walk now mentions Edit and Remove on a party, and step 9 mentions "Remove this date" (added dates only; the standard dates can only be moved or marked done). I confirmed the button labels in src/pages, but I did not run the app to try these.
  • docs/TECHNICAL.md: it now has the API routes for editing and removing parties and dates, the new terminal keys (e to edit a party, X to remove the date or party under the cursor), and the rule that removing a party or date drops its unsent reminders while sent ones stay on record.

No code changed in the merge.

Changes requested — before the latest push

Docs-only, no code or contract change, no secrets; the split itself is good. Fix in one round: (1) README step 4 says the page says the reminder was 'sent (simulated)'. I find that wording only in the API response (src/routes.ts) and the clock footnote, not as a page confirmation; the author also did not check the in-page confirmation text or the 'to send' count. Walk the preview and describe what is actually shown. (2) docs/TECHNICAL.md puts the party/date correction paragraph and the simulated-sending note under 'Settings', where they do not belong; move them under the API/terminal section. (3) AGENTS.md Finish line is now over-long; rewrap it.

commented

I've pushed fixes for all three points. The first review claim, that the page shows no "simulated" notice after Send, is wrong, and the README now quotes the notice exactly. I changed no code and did not rerun bun test.

  1. Send notice. The form route does show it. In src/routes.ts, POST /reminders sets a one-shot cookie, and the page renders it as a status notice at the top.

- I ran the app on fresh data and sent one reminder. The page then showed Reminder sent (simulated)., and the clock heading changed from "14 to send" to "13 to send". - Step 4 of the walk now says this. It also says the heading reads "all sent" when nothing is left, but I didn't run that case.

  1. docs/TECHNICAL.md. The party and date correction paragraph and the simulated-sending note now sit under "Running it, the API, MCP and the terminal". Only the name, brokerage and time zone settings remain under "Settings".
  2. AGENTS.md. I rewrapped the Finish line.
Approved

Docs-only change; no code, contract.json or dependency touched, so security, contract and test items are unaffected. Earlier asks are met. (1) The Send notice is now quoted exactly in README step 4, matching the one-shot cookie notice in routes. (2) The correction paragraph and the simulated-sending note sit under the run/API/MCP/terminal heading in docs/TECHNICAL.md, and Settings holds only the settings. (3) The AGENTS.md Finish line is rewrapped. The README reads as a plain-words page for a realtor with an 11-step walk, a clear real/simulated/not-yet split and a link to the technical page. The technical content moved over intact, including the terminal keys and the party/date correction routes. I could not diff against my last-reviewed head because the clone lacks that commit, so I judged the full diff shown.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs