@@ -1,51 +1,9 @@
-Reads your external meetings, researches companies and participants, and provides prep materials.
-
-<database inline="true" data-source-url="{{meetings-next-view}}">Next meeting</database>
-
-Switch to **Today** to see the day's meetings on a calendar, with the current or next one highlighted. Click a meeting to see its company and attendee cards.
-
-<database inline="true" data-source-url="{{meetings-upcoming}}">Upcoming meetings</database>
-
-<database inline="true" data-source-url="{{sync-runs-recent}}">Workflow runs</database>
-
-Add a new row to sync your calendar now.
-
----
-
-## How it works
-
-Perfect Meetings helps you prepare for meetings with people outside your
-company. It brings your Google Calendar meetings into Notion and writes a
-brief about the companies, attendees, recent Gmail conversations, and likely
-meeting objective.
-
-Open a meeting to review its **Meeting prep** and take notes under **Notes**.
-Refreshing the prep leaves your notes untouched. Tick **Regenerate prep** to
-request a fresh brief or retry a failed one. Each person's **Confidence** shows how
-sure the researcher is of their name and role. Low means it matched only part
-of the name, such as a first name at the right company; their card shows
-"(low confidence)", and a later brief may correct them. Set it to High once
-you have checked a person to keep their name and role.
-
-Each brief also updates a **Profile** at the top of each attendee's page in
-**People**: their role and responsibilities, meetings with them in the last 90
-days, and a summary of recent meetings and email. Write your own notes under
-**Notes** on that page; refreshes leave them untouched. The researcher also
-fills in their **LinkedIn**, **X**, **Instagram**, and **Personal site** when
-it finds them, and the meeting card links to them. It only looks for profiles
-that are empty, so correct a wrong one by replacing it.
-
-Meetings update when calendar events change, with an hourly catch-up, and
-every catch-up is logged in **Workflow runs**. Briefs are prepared for new
-meetings and refreshed when attendees change. Today's briefs also refresh each
-morning at 7:45 am in the app's configured time zone. To refresh today's
-briefs now, manually run **Morning prep**, leaving the date empty. Meetings
-with only coworkers do not appear by default.
+<database inline="true" data-source-url="{{meetings-next-view}}">Today</database>
 
 <details>
-<summary>App data</summary>
-	<mention-page url="{{people-db}}">People</mention-page> — Look up outside attendees, their roles, and their profiles.
-	<mention-page url="{{companies-db}}">Companies</mention-page> — Browse company summaries and websites.
-	<mention-page url="{{meetings-db}}">Meetings</mention-page> — Switch to **Calendar** or **All meetings** to browse dates and past notes.
-	<mention-page url="{{sync-runs-db}}">Workflow runs</mention-page> — Every calendar catch-up, with its status and any error.
+<summary>Debug Data</summary>
+	<mention-page url="{{sync-runs-db}}">Workflow runs</mention-page> — Run history of background tasks
+	<mention-page url="{{meetings-db}}">Meetings</mention-page> — Calendar events synced with Notion
+	<mention-page url="{{companies-db}}">Companies</mention-page> — Companies you meet with
+	<mention-page url="{{people-db}}">People</mention-page> — People you meet with
 </details>
@@ -9,31 +9,132 @@ Notion pages with a short research brief.
 
 ## What it creates
 
-| Kind         | Name               | Purpose                                                                     |
-| ------------ | ------------------ | --------------------------------------------------------------------------- |
-| Page         | APP.md             | Home page with the next-meeting card, upcoming meetings, and usage guidance |
-| Database     | Meetings           | One row per external meeting; brief at the top of the page, notes below     |
-| Database     | People             | One row per outside attendee, keyed by email                                |
-| Database     | Companies          | One row per outside company, keyed by email domain                          |
-| Database     | Workflow runs      | One row per calendar ingest run; add a row to run a catch-up now            |
-| Custom agent | Meeting researcher | Web research plus email summary, returned as JSON                           |
-| Custom view  | Next meeting       | Company and people cards for the next meeting, plus a Today calendar view   |
+| Kind         | Name               | Purpose                                                                                           |
+| ------------ | ------------------ | ------------------------------------------------------------------------------------------------- |
+| Page         | APP.md             | Home page with the main UI block and a Debug Data toggle linking the databases                    |
+| Database     | Meetings           | One row per external meeting; brief at the top of the page, notes below                           |
+| Database     | People             | One row per outside attendee, keyed by email                                                      |
+| Database     | Companies          | One row per outside company, keyed by email domain                                                |
+| Database     | Workflow runs      | One row per calendar ingest run; add a row to run a catch-up now (linked under Debug Data)        |
+| Custom agent | Meeting researcher | Web research plus email summary, returned as JSON                                                 |
+| Custom block | main_ui            | Setup progress, then a Today view (the default) and company and people cards for the next meeting |
 
 ## Workflows
 
-- `calendarIngest`: calendar event created, updated, or cancelled, plus an
-  hourly backfill. Upserts Meetings by event ID, People by email, and
-  Companies by domain. On first run it adds the two-way relations
-  (Attendees, Companies, Company), which the SDK cannot declare yet. Each run
-  is logged in Workflow runs as Pending, then Success or Failed; adding a row there
-  runs a catch-up. A run that crashes or times out stays Pending, because the
-  SDK has no hook for that yet.
-- `meetingPrep`: a Meetings row is created, its attendees change, or
-  **Regenerate prep** is ticked. Searches Gmail (last 90 days, 10 threads per
-  attendee), calls the researcher agent, and rewrites the **Meeting prep**
-  section. Anything under **Notes** is left alone.
-- `morningPrep`: every day at 07:45 in `TIME_ZONE`, it refreshes the prep for
-  that day's meetings.
+Each workflow keeps its key (used by `ntn workers exec`); the name is what
+Notion shows.
+
+- **Sync calendar** (`calendarIngest`): runs hourly, when a row is added to
+  Workflow runs, or by hand. It has no calendar event triggers, so changes
+  show up within the hour. Each run scans 1 day back and 7 days ahead and
+  upserts Meetings by event ID, People by email, and Companies by domain. A
+  cancelled or declined event marks its meeting Cancelled, and so does an
+  event that a complete scan no longer returns (deleted). On first run it
+  adds the two-way relations (Attendees, Companies, Company), which the SDK
+  cannot declare yet. Each run
+  is logged in Workflow runs as Pending, then Success or Failed; adding a row
+  there, or pressing **Sync calendar** in the block, runs a catch-up. A run
+  that crashes or times out stays Pending, because the SDK has no hook for
+  that yet. Its manual trigger takes no input and is always a catch-up.
+- **Research companies and people** (`meetingPrep`): a Meetings row is
+  created, its attendees change, or **Regenerate prep** is ticked. Searches
+  Gmail (last 90 days, 10 threads per attendee), calls the researcher agent,
+  and rewrites the **Meeting prep** section. Anything under **Notes** is left
+  alone. Its manual trigger takes no input and works through the research
+  backlog (see below).
+- **Refresh today's research** (`morningPrep`): every day at 07:45 in
+  `TIME_ZONE`, it refreshes the prep for that day's meetings. Its manual
+  trigger takes no input and refreshes today.
+
+### Research backlog
+
+Research runs per meeting: one session covers a meeting's brief, its
+attendees, and their companies. A manual **Research companies and people** run
+therefore picks meetings that together cover everyone not yet researched
+(`src/workflows/lib/backlog.ts`). Among meetings that are not cancelled and
+started in the last 30 days:
+
+- **First**, meetings that include a person or company research has never
+  reached, and that no earlier pick already covers. Research stamps
+  **Researched at** on every attendee and company when a session returns,
+  even if it found nothing, so each record is researched once. (Records
+  researched before that property existed count through Role, Confidence, or
+  Summary.) A failed session stamps nothing, so its records stay in the
+  backlog.
+- **Then**, upcoming meetings whose prep never finished: Prep status empty,
+  Queued, or Failed.
+
+Skipped: meetings without outside attendees; meetings Researching now, unless
+nothing has changed for 20 minutes, when they count as stuck and are retried;
+and Failed meetings whose last attempt was less than 6 hours ago
+(`FAILED_RETRY_MS`). That cooldown keeps a persistent failure from taking a
+slot on every run. Within each group, upcoming meetings go first, soonest
+first, then past meetings, most recent first. Each run preps at most 10
+meetings (`BACKLOG_MAX_MEETINGS`) and logs how many are left; run it again
+to continue.
+
+## Block states
+
+The block works out what to show from Workflow runs and Meetings; it stores
+no state of its own (`blocks/main_ui/state.ts`):
+
+| State       | When                                                         | Shows                                                                           |
+| ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Never run   | Workflow runs is empty                                       | A **Sync calendar** button                                                      |
+| Waiting     | The newest run (by Started) has no Status                    | "Waiting for flow to start"                                                     |
+| Syncing     | The newest run is Pending                                    | "Reading latest calendar events"                                                |
+| Researching | The newest run succeeded and meetings are Queued/Researching | "Researching companies and people (k of n meetings ready)"                      |
+| Failed      | The newest run failed                                        | The run's Error and a **Retry sync** button                                     |
+| Ready       | The App is populated, or nothing above applies               | The Today (default) and Next meeting views, or an empty state with **Sync now** |
+
+Once the App is populated it always shows Ready, never a setup, loading, or
+error state again. Populated means any of these, each of which only grows:
+
+- a meeting has Prep status Ready or Failed, or **Prep updated** set;
+- a sync succeeded and there are no outside meetings at all, which shows an
+  empty state explaining that meetings sync hourly and coworker-only
+  meetings are hidden; or
+- two of the 10 most recent syncs have succeeded.
+
+The block also latches populated for the session. Queries report loaded
+only after their first real result, and keep their last rows while a
+changed query (such as the hourly date cutoff) reloads, so nothing flashes.
+After that, a query error is a small notice above the last good data.
+
+In "k of n", taken from the upcoming-meetings query, n counts the meetings
+research will cover: not cancelled, with outside attendees, and not yet
+ended or being researched now (prep skips meetings that have ended). k
+counts those whose Prep status is Ready or Failed, so a failure does not
+stall the count. A meeting Queued or Researching with no change (Prep
+updated or last edit) for 20 minutes counts as stuck: it leaves n, the
+status line suggests Regenerate prep, and the button comes back. A manual
+**Research companies and people** run also retries it.
+
+The button adds a Workflow runs row (Trigger "Run now", Started now), which
+starts **Sync calendar** like a row added by hand. It is disabled while a run
+is waiting, syncing, or researching, and after a click until a new run row
+appears or a minute passes. A run that has waited or stayed Pending for more
+than 20 minutes (timed from Started, or the row's creation when Started is
+empty) is treated as stuck, and the button comes back.
+
+The block reads four live queries (`blocks/main_ui/derive.ts`): Meetings
+from local midnight 3 days ago onward (up to 200, not cancelled), the 10
+newest Workflow runs, People, and Companies. The next meeting, Today,
+progress, and populated signals are all derived from those rows. The SDK
+re-sends every subscription's query whenever the host reports a change to
+its data source, with no debounce, so research writes multiply requests per
+subscription; keep the count low. The Meetings window changes once a day,
+so the query is not replaced between renders. When a query fails before any
+rows have loaded, the block shows the error with **Retry**, not an empty
+state.
+
+Every empty state in the ready UI (no outside meetings yet, nothing today,
+nothing upcoming) has a quiet **Sync now** button. It creates the same
+Workflow runs row with the same double-click guard. While a sync is in
+flight it is disabled and shows the same stage as the setup panel (waiting
+for the flow, reading calendar events, then researching k of n meetings),
+then clears and re-enables when done, or re-enables with a short note if a
+stage looks stuck. The block stays on the ready UI throughout.
 
 "External" means an attendee's email domain is not your account's domain or
 one of its coworker domains. Consumer mailboxes such as gmail.com get a People
@@ -54,43 +155,47 @@ npm test
 npm run build
 ```
 
+The custom block's key is `main_ui`: it comes from the file name
+`src/customBlocks/main_ui.ts`, and its browser source is in `blocks/main_ui/`.
+Its display name is **Perfect Meetings** and its slash command is
+`/perfect-meetings`. It opens on **Today**; a viewer's last tab is remembered
+in their browser, so new viewers start on Today.
+
 The App's name is the title of its home page. Set it on the first deploy:
 
 ```shell
-ntn apps deploy --name "Perfect Meetings App"
+ntn apps deploy --name "Perfect Meetings"
 ```
 
 ## Run on demand and debug
 
-Every workflow has a manual trigger. Run it with `ntn workers exec` and read
-the result with `ntn workers runs list` and `ntn workers runs logs <run-id>`.
-You can also run the manual trigger from the workflow in Notion. For a calendar
-catch-up, add a row to **Workflow runs**, or run **Calendar ingest** with mode
-**backfill**, leaving the other inputs empty. To refresh today's briefs, run **Morning prep** with an empty
-date. Wait for the catch-up to finish before refreshing briefs for new meetings.
+Every workflow has a manual trigger, and none takes input. Run it from the
+workflow in Notion, or with `ntn workers exec`, and read the result with
+`ntn workers runs list` and `ntn workers runs logs <run-id>`. For a calendar
+catch-up you can also press **Sync calendar** in the block or add a row to
+**Workflow runs**. Wait for the catch-up to finish before refreshing briefs
+for new meetings.
 
 ```shell
-# Ingest only your current or next meeting. includeInternal counts coworkers
-# as outside attendees for this run only, so you can test with internal meetings.
-ntn workers exec calendarIngest -d '{"mode":"next","eventStartTime":null,"eventId":null,"includeInternal":true}'
-
-# Other ingest modes: "backfill" (the hourly scan), "event" (needs
-# eventStartTime), and "cancel" (needs eventId).
-ntn workers exec calendarIngest -d '{"mode":"backfill","eventStartTime":null,"eventId":null,"includeInternal":null}'
+# Calendar catch-up: the hourly scan, on demand.
+ntn workers exec calendarIngest -d '{}'
 
-# Rewrite one meeting's brief. reason: "created", "updated", or null (force).
-ntn workers exec meetingPrep -d '{"meeting":"<Meetings page URL or ID>","reason":null}'
+# Research everyone not yet researched, up to 10 meetings per run.
+ntn workers exec meetingPrep -d '{}'
 
-# Run the morning refresh for today, or for another date (YYYY-MM-DD).
-ntn workers exec morningPrep -d '{"date":null}'
+# Refresh today's briefs.
+ntn workers exec morningPrep -d '{}'
 ```
 
+To rewrite one meeting's brief, tick **Regenerate prep** on it.
+
 The "List calendar events" step in each ingest run records a diagnostic
 summary: events per calendar, why events were skipped, and a tally of attendee
 domains. When a run finds no meetings, check it first.
 
-To treat coworkers as outside attendees on every trigger, not just one manual
-run, set `INCLUDE_INTERNAL_ATTENDEES` on your own worker:
+To treat coworkers as outside attendees, for example to test with internal
+meetings, set `INCLUDE_INTERNAL_ATTENDEES` on your own worker. It applies to
+every trigger:
 
 ```shell
 ntn workers env set INCLUDE_INTERNAL_ATTENDEES=true