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

mason/deal-clock:mason/15-a-realtor-reads-the-readme-in-one-go-wha → main 3 commits fork 3 threads · 3 unresolved

  • Merged. mason/15-a-realtor-reads-the-readme-in-one-go-wha was merged into main as eec530a.

Review

Sign in to review this change.
3 files changed +268 −221
AGENTS.md +10 −1
@@ -6,6 +6,14 @@ preview at its own address, deployed from your branch as you push.
66
77 ## The rules
88
9 - Two readers, two pages. `README.md` is for the agent (the realtor) in
10 plain words: what the app does, a walk through the sample deals, what is
11 real and what is simulated. Everything technical lives in
12 `docs/TECHNICAL.md`: running it, the API, MCP, the terminal, the file
13 table, the door, the audit trail, roles. Put a new technical fact there;
14 change the README only when what an agent sees changes, and check the walk
15 against the running app.
16
917 - Work on the branch you were given. You cannot move the default branch;
1018 a person merges your pull once it is reviewed.
1119 - Keep state under `FORGE_APP_DATA`. Never write elsewhere at runtime.
@@ -140,4 +148,5 @@ To add a concept:
140148 - Finish: the app boots, `/healthz` answers `{ ok, version, uptime }`
141149 (the forge polls it; keep it cheap and apart from the page), `/`
142150 answers, `bun test` is green, the README says how to use it and what is
143 real versus simulated, `forge.json` says how to run it.
151 real versus simulated (and `docs/TECHNICAL.md` how to run it), `forge.json`
outdated

Line is far past the file's wrap width; rewrap.

152 says how to run it.
README.md +74 −220
@@ -1,231 +1,85 @@
11 # deal-clock
22
3 Every deadline of every deal on one timeline, so nothing slips.
3 Every deadline of every deal on one timeline, so nothing slips. It shows an
4 agent each date in a contract, who owes what, and the reminder to send each
5 party before it comes due.
46
5 ## For the agent
7 The technical part (running it, the API, MCP, the terminal, the files, roles)
8 is in [docs/TECHNICAL.md](docs/TECHNICAL.md).
69
7 **The clock** is the first screen. Each deal is a lane; time runs left to
8 right, and today is the dark line down the middle. Every date in a contract
9 is a marker on its lane:
10 ## Try it on the sample deals
1011
11 - **red** — overdue
12 - **amber** — due within three days
13 - **teal** — coming up
14 - **grey** — done
12 Four sample deals are already in, so the first screen is never empty. Sign in
13 first (see below). You land on **the clock**: each deal is a lane, time runs
14 left to right, and today is the dark line down the middle. Every date in a
15 contract is a marker on its lane: red is overdue, amber is due within three
16 days, teal is coming up, grey is done. The samples stay current: each time
17 the app starts, the ones nobody has touched move forward together by the days
18 since they were last set, so the screen always looks like today.
1519
16 Tap a marker to see who owes what, the reminder drafts for each party,
17 and two buttons: **Mark done**, and **Move this date** (it asks why, and
18 keeps the reason). Moving one date moves nothing else.
20 1. **Look at the clock.** You see four lanes: 77 Harbor View Dr, Unit 4B
21 (the inspection date has passed, so its marker is red), 1418 Alder Lane
22 (closing in a few days, with the earlier dates grey), 9 Orchard Row (the
23 appraisal was moved), and 2210 Juniper Court (just signed, everything
24 still ahead).
25 2. **Open a marker.** Tap the red inspection marker on Harbor View. A sheet
26 opens with the date, who owes it (the buyer), what is owed, and the reminders
27 for each party, grouped as three days before and the morning of. It also
28 has two buttons: Mark done, and Move this date.
29 3. **Read and edit a reminder.** In the sheet, tap a party's reminder. You

Verify against the preview: the page shows no 'simulated' confirmation that I can find. Describe what the realtor really sees after Send, and the real 'N to send' wording ('2 to send' / 'all sent').

30 see the words it would send, in a subject field and a message field,
31 already filled in. Change the message; the subject can run to 150
32 characters and the message to 2000.
33 4. **Send it.** Tap Send. A short notice at the top of the page reads
34 "Reminder sent (simulated)." and the reminder now shows "Sent" with
35 today's date and your edited words, not the original draft. Under the
36 clock, the heading "Reminders for today" counts what is left ("14 to send"
37 becomes "13 to send"; when nothing is left it reads "all sent").
38 5. **Move a date, with a reason.** Open the same marker again and use Move
39 this date: pick a new date and say why ("Inspector delayed"). The marker
40 jumps to the new date, and the sheet lists the move, the reason and who
41 made it. No other date moves.
42 6. **See a date that was moved.** On 9 Orchard Row, open the appraisal
43 marker. The sheet shows where it moved from and to, with the reason
44 the appraiser gave.
45 7. **Mark a date done.** On Alder Lane, open a coming date and tap Mark
46 done. The marker turns grey and its reminders stop. Reopen puts it back.
47 8. **Add a party.** Tap the address 2210 Juniper Court to open the deal's
48 page. It lists every date and every party. Under "Add a party" pick a
49 role (the title company, say), type a name and an email or phone, and
50 add it. The party appears in the list, and the dates that concern them now
51 have reminders for them.
52 Made a typo? Each party has Edit (fix the name or email; the next
53 reminder uses it) and Remove (its unsent reminders go with it).
54 9. **Add a date.** On the same page, add a date the contract added, such as
55 an HOA review: a name, a date, who owes it. It joins the deal's list and
56 the clock. A date you added has a Remove this date button in its sheet,
57 for when the contract drops it; the standard dates cannot be removed, only
58 moved or marked done.
59 10. **Open a new deal.** Back on the clock, tap New deal. Type an address,
60 buyer, seller, contract date and closing date. The standard lengths are
61 already filled in (inspection 10 days, appraisal 21, financing 30, title 14,
62 final walkthrough the day before closing) and you can change them; tick
63 Count business days to skip weekends. Tap Open deal. You land on the new
64 deal's page with every date worked out, and it has its own lane on the clock.
65 11. **Download the calendar file.** On a deal's page, tap Add to calendar.
66 You get a calendar file with every date of the deal and an alarm three days
67 before and the morning of, to open in your own calendar app.
1968
20 Under the clock, **Reminders for today** lists what should go out this
21 morning. Every open date reminds the parties it concerns — buyer, seller,
22 lender, title company, the other agent — **three days before** and **the
23 morning of**. Open a draft to edit its subject (up to 150 characters) and message (up to
24 2000) in plain fields, then tap **Send**. What was approved is kept with the
25 send: a sent reminder shows those words, not the current draft, on the page,
26 in `/api/deals/:id`, in MCP and in the terminal.
27
28 **A deal's page** (tap its address) lists every date and party. Add a date
29 the contract adds (an HOA review, a repair deadline), add the lender or the
30 title company, and **Add to calendar** downloads an `.ics` file with every
31 date and its alarms for your own calendar. Nothing is stuck once added: each
32 party has **Edit** (a mistyped name or email, which the next reminder draft
33 uses) and **Remove**; a date you added opens a sheet with **Remove this
34 date** for when the contract drops it. The standard contract dates cannot be
35 removed — move them or mark them done. Removing a party or a date drops the
36 reminders not yet sent; reminders already marked sent stay on record. Over
37 the API: `PATCH` or `DELETE /api/deals/:id/parties/:party` and `DELETE
38 /api/deals/:id/deadlines/:deadline`.
39
40 **New deal** takes the address, buyer, seller, contract date and closing
41 date, and works out the rest from the contingency lengths. The defaults —
42 inspection 10 days, appraisal 21, financing 30, title 14, final walkthrough
43 the day before closing — are editable on the form. Days are calendar days;
44 tick *Count business days* to skip weekends.
45
46 Four sample deals are already in: one with an overdue inspection, one
47 closing this week, one whose appraisal was moved, and one just signed.
48 They stay current: each time the app starts, the samples nobody has
49 touched move forward together by the days since they were last set, so the
50 first screen always looks like today. A sample you changed (marked done,
51 moved, added a date or party to, sent a reminder for) is left alone.
52
53 ### What is real, and what is not yet
69 ## What is real, and what is not yet
5470
5571 - **Real:** the dates and their math, mark done, moves with their reasons,
56 who owes what, the reminder drafts, the record of what was sent, the
57 calendar file, and `POST /tick` (below).
58 - **Simulated:** sending. *Send* records that a reminder went out; no
59 email or text message leaves the app.
60 - **Not in this prototype:** real email or SMS, e-signature, document
61 storage, and reading the dates out of a contract PDF (phase two).
72 who owes what, the reminder drafts and editing them, the record of what was
73 sent, the calendar file, and adding parties, dates and deals.
74 - **Simulated:** sending. Send records that a reminder went out and keeps the
75 words that were approved; no email or text message leaves the app.
76 - **Not in this prototype (phase two):** real email or text messages,
77 e-signature, document storage, and reading the dates out of a contract PDF.
6278
63 Deals are private: sign in (the forge's account) to see the clock or a
64 deal, and to open deals, mark dates done, move them and send reminders. A
65 visitor who is not signed in is asked to sign in, and sees nothing of any
66 deal. Only the agent who opened a deal, or an admin, can remove it.
79 ## Signing in, and who can remove a deal
6780
68 The name and brokerage in the header come from two settings
69 (Settings → App → Environment): `DEAL_CLOCK_AGENT` and
70 `DEAL_CLOCK_BROKERAGE`. Dates follow the server's time zone (`TZ`).
71
72 ## For whoever runs it
73
74 `POST /tick` answers the reminders that go out today and are not yet
75 marked sent, as JSON — call it each morning as a signed-in account (a
76 stranger gets 401; it sends nothing and changes nothing). `GET /deals/:id/ics` is a deal's calendar file. The JSON API is
77 `/api/deals`, described at `/openapi.json`; the same operations are MCP
78 tools at `POST /mcp` (`list_deals`, `get_deal`, `reminders_today`,
79 `open_deal`, `add_date`, `add_party`, `mark_done` — with `done: false` to
80 reopen a date — `move_date`, `send_reminder`). `send_reminder` takes an
81 optional `subject` and `body` to send edited words; without them the draft
82 goes as it is.
83
84 The terminal does the page's work too. It opens on every open date, soonest
85 first: `n` opens a new deal (address, buyer, seller, contract date, closing
86 date; the standard lengths do the rest), `x` marks the date under the cursor
87 done, `u` reopens it, `m` moves it (the new date, then the reason), `o` opens
88 its deal — where `a` adds a date,
89 `p` adds a party, `e` edits the party under the cursor (the cursor walks the
90 dates, then the parties), `X` removes the date or party under it after you
91 type `yes`, and `D` removes the deal likewise — and `h`
92 shows done dates. `r` lists today's reminders: enter reads a draft, `e`
93 types new words for it (a subject, then a message, where `\n` is a line
94 break and an empty answer keeps the draft's), and `s` sends what you read,
95 under the same limits as the page. `j`/`k` move, `b` goes back, `q` quits. What you change there
96 shows on every open page within a second.
97
98 No runtime dependencies: Bun, `bun:sqlite`, and the browser's own popovers
99 — the page needs no script to work.
100
101 This is an app: the forge runs it. Production follows the default branch;
102 every open pull gets a preview at its own address with its own copy of the
103 data. Everything the app keeps lives under `FORGE_APP_DATA`, which is what
104 makes "production data" and "preview data" two different things.
105
106 ```sh
107 PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts # run it here
108 bun test # what `forge.json`'s app.test runs on every push
109 FORGE_APP_DATA=./data bun run src/tty.ts # the terminal
110 FORGE_APP_DATA=./data bun run src/db.ts --check # schema version, integrity
111 bun run lint:design # no colour but the tokens'
112 bun run contract:emit # rewrite contract/openapi.json from the routes
113 ```
114
115 `app.test` in `forge.json` runs beside `app.run` in every deploy, not before
116 it: the preview comes up the moment the app answers, and says `live`, or
117 `serving · tests failed` the moment the suite disagrees.
118
119 ## The shape
120
121 One implementation, many doors. `src/actions.ts` is every operation as a
122 plain function — `(db, who, input)` in, data or a named failure out — and
123 the page, the JSON API, the MCP server and the terminal all call it and
124 decide nothing themselves. `AGENTS.md` says how to add to it.
125
126 | file | what it is |
127 | ---------------------------------- | -------------------------------------------------------------- |
128 | `src/deals.ts` | deals: open, read, move a date, mark done, parties, reminders sent |
129 | `src/dates.ts`, `src/deadlines.ts` | calendar math; the standard contract dates and who owes them |
130 | `src/reminders.ts`, `src/ics.ts` | reminder drafts and `/tick`; the calendar file |
131 | `src/sample.ts` | the four sample deals a new database starts with |
132 | `src/result.ts` | what an action answers, and the audit habit they share |
133 | `src/actions.ts` | the audit trail, read |
134 | `contract.json` | who may do what: roles, and the least role each verb needs |
135 | `src/contract.ts`, `src/can.ts` | the table, read at boot; the forge's evaluator, verbatim |
136 | `src/security.ts` | the door: rationing, same origin, the table before the body |
137 | `src/audit.ts` | every change and every refused one, as a row |
138 | `src/who.ts` | who is asking, from the forge's signed headers |
139 | `src/db.ts` | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations |
140 | `src/live.ts` | the in-process bus and `GET /events` |
141 | `src/mcp.ts` | the actions as MCP tools at `POST /mcp` |
142 | `src/routes.ts` | every path, in one table, each API route described beside it |
143 | `src/openapi.ts` | the routes as OpenAPI; committed at `contract/openapi.json` |
144 | `src/pages/` | the clock, a deal, a new deal, a date's sheet; one `layout` |
145 | `design/tokens.json`, `src/tokens.ts` | the look as data, light and dark; compiled to `/tokens.css` |
146 | `src/http.ts` | the floor: headers, body cap, files |
147 | `src/server.ts` | boot: open the database, serve |
148 | `src/tty.ts`, `src/terminal.ts` | the terminal: the pty, and the keys and screen over the same actions |
149 | `src/env.ts` | what the forge told this process |
150 | `static/app.css`, `static/live.js` | the look in the tokens' words, and the clock that stays current |
151
152 ## What every app stands on
153
154 - **The door.** Before a route sees a request, `src/security.ts` rations
155 writes (and a stranger's API calls), refuses a write from another site,
156 and turns away — before the body is read — anyone the table lets through
157 a resource's door for no row at all: 401 for a stranger, 403 for anyone
158 else. The action still decides about the real row.
159 - **The audit trail.** Every change, and every change refused, is a row:
160 who, which resource and verb, which row, when, and whether they were
161 let. Admins read it at `GET /api/audit`. A row that cannot be written
162 is a log line, never a failed request.
163 - **The API, described.** `GET /openapi.json` is `contract/openapi.json`,
164 written from the routes by `bun run contract:emit`; each operation names
165 its cell of the table (`x-contract`). `bun test` fails while it is stale.
166 It needs a signed-in user: no door of the table is open to a stranger, and
167 the description is shut to them when none is.
168 - **Up, or not.** `GET /healthz` answers `{ ok, version, uptime }`; the
169 forge waits on it before it sends anyone to a deploy.
170 - **The look.** `design/tokens.json` holds every colour, space and size,
171 light and dark; nothing else spells out a colour (`bun run lint:design`),
172 and every pair a person reads meets 4.5:1 in both themes.
173 - **The open web.** A shared link unfurls (description, Open Graph, a
174 card); `/robots.txt` keeps crawlers to the page, and out of previews
175 entirely; `/.well-known/security.txt` sends a reporter to the forge
176 that runs the app.
177
178 ## Who you are
179
180 The forge says who is asking on every request it proxies, and the app
181 verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers:
182
183 - **anon** — anyone. Sees the sign-in notice; no deal, date or party.
184 - **user** — signed in to the forge and able to see this app. Reads every
185 deal, its parties and their contacts. Opens deals,
186 marks dates done, moves them, adds dates and parties, sends reminders;
187 removes the deals they opened.
188 - **admin** — able to write this repository. Removes any deal.
189
190 "Sign in" is `/__forge/signin?to=<path>` and "Sign out" is
191 `/__forge/signout`; the forge answers both on the app's own host, and
192 `/__forge/report` too: it sends anyone, with no account, to report a
193 problem on this app's repository, if that repository is public.
194
195 ## Any interface
196
197 The same actions, the same rules, at every door. A script is the person
198 whose forge grant it carries; a bare script is anonymous.
199
200 ```sh
201 curl https://<app>/api/deals
202 curl -X POST https://<app>/tick
203 curl https://<app>/deals/1/ics
204 ```
205
206 As an MCP server, for Claude Code or Claude Desktop — the deal tools:
207
208 ```sh
209 claude mcp add --transport http deal-clock https://<app>/mcp
210 ```
211
212 ```json
213 {
214 "mcpServers": { "deal-clock": { "type": "http", "url": "https://<app>/mcp" } }
215 }
216 ```
217
218 The clock stays current over `/events`: a date someone else marks done or
219 moves — on the page, over the API, or in the terminal — changes without a
220 reload. Without JavaScript it is the same page, one
221 reload behind.
222
223 The terminal opens with the exact command in `FORGE_APP_SSH` when the app
224 runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge
225 the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on
226 a real pty over the same data, as the account at the keyboard; everything
227 it does is `src/terminal.ts`, which `src/terminal.test.ts` drives key by key.
228
229 The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or
230 `preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and
231 `FORGE_APP_IDENTITY_KEY` when it starts the app. `forge.json` says how.
81 Deals are private. Sign in with your forge account to see the clock or a
82 deal, and to open deals, mark dates done, move them, add dates and parties,
83 and send reminders. A visitor who is not signed in is asked to sign in and
84 sees nothing of any deal. Only the agent who opened a deal, or an admin, can
85 remove it, so the sample deals can be removed by an admin only.
docs/TECHNICAL.md added +184
@@ -0,0 +1,184 @@
1 # deal-clock, technical
2
3 For whoever builds, runs or connects to deal-clock. What the app is for, and
4 a walk through it, are in the [README](../README.md); this page holds
5 everything technical, and `AGENTS.md` says how to add to it.
6
7 ## Settings
8
9 The name and brokerage in the header come from two settings
10 (Settings → App → Environment): `DEAL_CLOCK_AGENT` and
11 `DEAL_CLOCK_BROKERAGE`. Dates follow the server's time zone (`TZ`).
12
13 ## Running it, the API, MCP and the terminal
14
15 Parties and dates can be corrected after they are added: a party can be
outdated

This paragraph about editing/removing parties and dates is not a setting; move it under 'Running it, the API, MCP and the terminal'. Same for the sending-is-simulated note below.

16 edited (a mistyped name or email, which the next reminder draft uses) or
17 removed, and a date you added can be removed when the contract drops it. The
18 standard contract dates cannot be removed — move them or mark them done.
19 Removing a party or a date drops the reminders not yet sent; reminders already
20 marked sent stay on record. Over the API: `PATCH` or `DELETE
21 /api/deals/:id/parties/:party` and `DELETE /api/deals/:id/deadlines/:deadline`.
22
23 Sending is simulated: *Send* records that a reminder went out and the
24 words approved with it; nothing leaves the app. The record is shown on the
25 page, in `/api/deals/:id`, in MCP and in the terminal.
26
27 `POST /tick` answers the reminders that go out today and are not yet
28 marked sent, as JSON — call it each morning as a signed-in account (a
29 stranger gets 401; it sends nothing and changes nothing). `GET /deals/:id/ics` is a deal's calendar file. The JSON API is
30 `/api/deals`, described at `/openapi.json`; the same operations are MCP
31 tools at `POST /mcp` (`list_deals`, `get_deal`, `reminders_today`,
32 `open_deal`, `add_date`, `add_party`, `mark_done` — with `done: false` to
33 reopen a date — `move_date`, `send_reminder`). `send_reminder` takes an
34 optional `subject` and `body` to send edited words; without them the draft
35 goes as it is.
36
37 The terminal does the page's work too. It opens on every open date, soonest
38 first: `n` opens a new deal (address, buyer, seller, contract date, closing
39 date; the standard lengths do the rest), `x` marks the date under the cursor
40 done, `u` reopens it, `m` moves it (the new date, then the reason), `o` opens
41 its deal — where `a` adds a date,
42 `p` adds a party, `e` edits the party under the cursor (the cursor walks the
43 dates, then the parties), `X` removes the date or party under it after you
44 type `yes`, and `D` removes the deal likewise — and `h`
45 shows done dates. `r` lists today's reminders: enter reads a draft, `e`
46 types new words for it (a subject, then a message, where `\n` is a line
47 break and an empty answer keeps the draft's), and `s` sends what you read,
48 under the same limits as the page. `j`/`k` move, `b` goes back, `q` quits. What you change there
49 shows on every open page within a second.
50
51 No runtime dependencies: Bun, `bun:sqlite`, and the browser's own popovers
52 — the page needs no script to work.
53
54 This is an app: the forge runs it. Production follows the default branch;
55 every open pull gets a preview at its own address with its own copy of the
56 data. Everything the app keeps lives under `FORGE_APP_DATA`, which is what
57 makes "production data" and "preview data" two different things.
58
59 ```sh
60 PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts # run it here
61 bun test # what `forge.json`'s app.test runs on every push
62 FORGE_APP_DATA=./data bun run src/tty.ts # the terminal
63 FORGE_APP_DATA=./data bun run src/db.ts --check # schema version, integrity
64 bun run lint:design # no colour but the tokens'
65 bun run contract:emit # rewrite contract/openapi.json from the routes
66 ```
67
68 `app.test` in `forge.json` runs beside `app.run` in every deploy, not before
69 it: the preview comes up the moment the app answers, and says `live`, or
70 `serving · tests failed` the moment the suite disagrees.
71
72 ## The shape
73
74 One implementation, many doors. `src/actions.ts` is every operation as a
75 plain function — `(db, who, input)` in, data or a named failure out — and
76 the page, the JSON API, the MCP server and the terminal all call it and
77 decide nothing themselves. `AGENTS.md` says how to add to it.
78
79 | file | what it is |
80 | ---------------------------------- | -------------------------------------------------------------- |
81 | `src/deals.ts` | deals: open, read, move a date, mark done, parties, reminders sent |
82 | `src/dates.ts`, `src/deadlines.ts` | calendar math; the standard contract dates and who owes them |
83 | `src/reminders.ts`, `src/ics.ts` | reminder drafts and `/tick`; the calendar file |
84 | `src/sample.ts` | the four sample deals a new database starts with |
85 | `src/result.ts` | what an action answers, and the audit habit they share |
86 | `src/actions.ts` | the audit trail, read |
87 | `contract.json` | who may do what: roles, and the least role each verb needs |
88 | `src/contract.ts`, `src/can.ts` | the table, read at boot; the forge's evaluator, verbatim |
89 | `src/security.ts` | the door: rationing, same origin, the table before the body |
90 | `src/audit.ts` | every change and every refused one, as a row |
91 | `src/who.ts` | who is asking, from the forge's signed headers |
92 | `src/db.ts` | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations |
93 | `src/live.ts` | the in-process bus and `GET /events` |
94 | `src/mcp.ts` | the actions as MCP tools at `POST /mcp` |
95 | `src/routes.ts` | every path, in one table, each API route described beside it |
96 | `src/openapi.ts` | the routes as OpenAPI; committed at `contract/openapi.json` |
97 | `src/pages/` | the clock, a deal, a new deal, a date's sheet; one `layout` |
98 | `design/tokens.json`, `src/tokens.ts` | the look as data, light and dark; compiled to `/tokens.css` |
99 | `src/http.ts` | the floor: headers, body cap, files |
100 | `src/server.ts` | boot: open the database, serve |
101 | `src/tty.ts`, `src/terminal.ts` | the terminal: the pty, and the keys and screen over the same actions |
102 | `src/env.ts` | what the forge told this process |
103 | `static/app.css`, `static/live.js` | the look in the tokens' words, and the clock that stays current |
104
105 ## What every app stands on
106
107 - **The door.** Before a route sees a request, `src/security.ts` rations
108 writes (and a stranger's API calls), refuses a write from another site,
109 and turns away — before the body is read — anyone the table lets through
110 a resource's door for no row at all: 401 for a stranger, 403 for anyone
111 else. The action still decides about the real row.
112 - **The audit trail.** Every change, and every change refused, is a row:
113 who, which resource and verb, which row, when, and whether they were
114 let. Admins read it at `GET /api/audit`. A row that cannot be written
115 is a log line, never a failed request.
116 - **The API, described.** `GET /openapi.json` is `contract/openapi.json`,
117 written from the routes by `bun run contract:emit`; each operation names
118 its cell of the table (`x-contract`). `bun test` fails while it is stale.
119 It needs a signed-in user: no door of the table is open to a stranger, and
120 the description is shut to them when none is.
121 - **Up, or not.** `GET /healthz` answers `{ ok, version, uptime }`; the
122 forge waits on it before it sends anyone to a deploy.
123 - **The look.** `design/tokens.json` holds every colour, space and size,
124 light and dark; nothing else spells out a colour (`bun run lint:design`),
125 and every pair a person reads meets 4.5:1 in both themes.
126 - **The open web.** A shared link unfurls (description, Open Graph, a
127 card); `/robots.txt` keeps crawlers to the page, and out of previews
128 entirely; `/.well-known/security.txt` sends a reporter to the forge
129 that runs the app.
130
131 ## Who you are
132
133 The forge says who is asking on every request it proxies, and the app
134 verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers:
135
136 - **anon** — anyone. Sees the sign-in notice; no deal, date or party.
137 - **user** — signed in to the forge and able to see this app. Reads every
138 deal, its parties and their contacts. Opens deals,
139 marks dates done, moves them, adds dates and parties, sends reminders;
140 removes the deals they opened.
141 - **admin** — able to write this repository. Removes any deal.
142
143 "Sign in" is `/__forge/signin?to=<path>` and "Sign out" is
144 `/__forge/signout`; the forge answers both on the app's own host, and
145 `/__forge/report` too: it sends anyone, with no account, to report a
146 problem on this app's repository, if that repository is public.
147
148 ## Any interface
149
150 The same actions, the same rules, at every door. A script is the person
151 whose forge grant it carries; a bare script is anonymous.
152
153 ```sh
154 curl https://<app>/api/deals
155 curl -X POST https://<app>/tick
156 curl https://<app>/deals/1/ics
157 ```
158
159 As an MCP server, for Claude Code or Claude Desktop — the deal tools:
160
161 ```sh
162 claude mcp add --transport http deal-clock https://<app>/mcp
163 ```
164
165 ```json
166 {
167 "mcpServers": { "deal-clock": { "type": "http", "url": "https://<app>/mcp" } }
168 }
169 ```
170
171 The clock stays current over `/events`: a date someone else marks done or
172 moves — on the page, over the API, or in the terminal — changes without a
173 reload. Without JavaScript it is the same page, one
174 reload behind.
175
176 The terminal opens with the exact command in `FORGE_APP_SSH` when the app
177 runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge
178 the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on
179 a real pty over the same data, as the account at the keyboard; everything
180 it does is `src/terminal.ts`, which `src/terminal.test.ts` drives key by key.
181
182 The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or
183 `preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and
184 `FORGE_APP_IDENTITY_KEY` when it starts the app. `forge.json` says how.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs