Calendar & Onboarding — Handoff

What the calendar integration is today, how a connection actually works, what the onboarding wizard does now, and where the next phase is headed. Written for the agent picking this up, by the one who built the last stretch.

2026-09-16 · Google + Microsoft calendars, all three rungs · onboarding wizard in one straight line · last two PRs merging

Where it stands

Calendars work on both vendors at every level, and onboarding runs in one straight line. A company's shared calendar, a building's calendar, and a leasing agent's own calendar can each be Microsoft or Google. Clara books tours on any of them. The one thing we do not have is Gmail: Clara cannot read or send a company's Google mail.

Rung	What it is	Where you see it	Microsoft	Google
Company	One shared calendar (and, on Microsoft, the shared leasing mailbox) for the whole company. The default shape for a new customer.	Onboarding · Channels step (company shape) · Organization Settings card	mailbox + calendar	calendar only
Building	A calendar (and mailbox) per property, for companies run per-building team.	Onboarding · Channels step (per-building shape) · Property Settings	live	live
Person	A leasing agent's own calendar. Tours go in a person's day, not a building's.	Onboarding · Your calendar step · first sign-in screen · Profile → My calendar	live	live

How a connection works

Every rung on every vendor is the same four-step shape. Learn it once.

Authorize routemints a signed state, writes a "started" ledger row→ Vendor consentMicrosoft or Google, account chooser forced on the person lane→ One callback per vendortells the three rungs apart by the state's shape→ Channel vaultone row per node + kind, provider on the row

Two callbacks total, one per vendor, each registered once with that vendor: /api/integrations/outlook/callback and /api/integrations/google-calendar/callback. Adding a rung never touches a vendor console.
The state says which rung. A company state and a person state are signed with the server secret and bound to the session that minted them (org-connect-state.ts, person-connect-state.ts, one shared signer in signed-oauth-state.ts). A forged, replayed or tampered link is refused before any code is exchanged and lands on one fixed page. The building lane still uses a bare state; it names a property that is re-checked against the caller's scope.
The vault is one table shape. ChannelAttachment rows keyed by node (ORG#, PERSON#) and kind (calendar, mailbox), with provider: 'microsoft' | 'google'. Connecting supersedes the live hook rather than adding a second calendar. Disconnecting ends the hook and keeps the row as audit.
Tokens refresh through the row's own vendor. fresh-channel-token.ts branches on provider; a revoked Google grant marks the row "reconnect needed" with plain copy. Clara's tour code reads a calendar's provider off the row (getOrgCalendarAccess, getPersonCalendarAccess) and never assumes Outlook.
Company Google is calendar-only by design. The connect route derives the vendor from the mailbox domain when an address is named; when none is (the onboarding button), the button's vendor wins. A Google company gets its calendar connected and its inbox stays "we'll set that up with you" until the Gmail question is answered.

Infrastructure

Piece	Where	Notes
Google sign-in	Google Cloud project propflow-login, PropFlow org, hello@ account	Better Auth. Env: `GOOGLE_LOGIN_CLIENT_ID` / `_SECRET`. Moved off a personal account on 2026-09-16.
Google integrations	Google Cloud project propflow-integrations-508806, same org	Calendar API and Gmail API enabled. Env: `GOOGLE_INTEGRATIONS_CLIENT_ID` / `_SECRET`. One registered redirect URI: the Google calendar callback above. Verified; no ID verification was required.
Legacy Google client	`GOOGLE_CLIENT_ID` / `_SECRET`	The vendor-quote poller's old project. Not part of calendars. Leave it.
Microsoft	One app registration (Fede's earlier in-house move)	Env: `MICROSOFT_CLIENT_ID` / `_SECRET`. Company connects can hit the admin-approval wall; the vault carries a `pending_admin_approval` status and a silent re-ask. Google has no such wall.
Deploy	Vercel, project propflowai	Merge to main is the production deploy. A green main run promotes; check the Production deployment's SHA before telling anyone something is live.
Gmail scopes	Google	`gmail.send` is cheap. `gmail.readonly` is a restricted scope and needs Google's CASA review, unless a customer's own Workspace admin allowlists our app, which exempts us. Nothing in code uses either today.

The onboarding wizard now

1 · AppFoliorequired, no skip→ 2 · Syncpick buildings→ 3 · Reviewwhat we imported→ 4 · Channelscompany shape OR per-building picker, in place→ 5 · Your calendarMicrosoft or Google, skippable→ 6 · Teammatesemail only, role from the standard select, one ending→ Dashboard

Back on every step. Teammates goes back to Your calendar, which goes back to Channels.
One ending on teammates. "Finish" alone when nothing is typed; "Skip for now" beside "Send invites" once an email is typed. Never Skip beside Finish.
Channels never changes URL. /onboarding/channels resolves the company's shape once and renders it in place. The old addresses (company-microsoft, company-channels) are redirects that carry the query string, so consent links minted before still land.
What "onboarded" means on disk. onboardingCompletedAt on the User row (or a completed ONBOARDING#<userId> record) is terminal: an admin who has it is never routed back in. calendarWelcomeOfferedAt is stamped when the Your-calendar step renders, so the post-wizard first-sign-in screen never asks a finished admin twice.
Company steps vs the personal tail. wizard-steps.ts tracks only the two company steps anyone can do once for everyone (AppFolio, company mailbox). Your calendar and teammates are the personal tail, reached once no company step is left. Do not add a per-person step to the company tracker; it was tried, and skipping it looped people back into the wizard forever.
Operating model decides the Channels shape. New customers default to centralized (company shape). The admin customer page has a dropdown to flip a company to per-building team.

What we don't have

No calendar slot-assignment across several agents' calendars (which person gets the tour). Scoped for next week in the standup, not started.
No email-choice screen in settings (PropFlow-provided address vs the customer's own vs PMS-only). Decided in the standup; the onboarding flow deliberately does not ask.
No self-serve reset of an onboarded admin in the UI. See "Testing and resetting" below.
Stale pricing copy and unpaid-module leakage in the app are flagged for cleanup and are not part of this work.

Where it's going (from the 2026-09-16 founders' standup)

The admin onboards first (AppFolio, company policies, the general email), then invites leasing agents, whose separate flow has one step: connect your calendar. That flow already exists (/welcome/calendar); the wizard's Your-calendar step is its twin for the admin.
Default to a PropFlow-provided leasing email (like <company>@propflow.io) so onboarding is never blocked on mail permissions. The choice between PropFlow's address, the customer's own domain, and PMS-only moves out of onboarding into settings, presented as a mockup of what the customer's email would look like rather than a "what's your email?" prompt.
Destructive integration actions stay super-admin only (PropFlow staff): disconnecting the sending mailbox or the PMS. Disconnecting a calendar is fine to expose. Later: confirmation prompts and an approval flow.
Teammates invite by email only, name derived from the address, with role descriptions so PM versus leasing agent is clear. Shipped in the form; the descriptions are not.
Settings information architecture gets consolidated into one command center grouped by module. Gera owns it. This page does not cover it.

Testing and resetting

Accounts and companies

Any @propflowai.co address is a platform admin: it skips onboarding and sees every company. To walk the wizard you need a customer identity in a test company.
A company marked "Test company" at creation can use the demo AppFolio database, so the AppFolio step can be completed without real credentials.
The screenshot tool cannot photograph the wizard: both seeded evidence identities are already onboarded. Evidence for wizard changes is a live walk in production.

Resetting an onboarded admin to walk it again

There is no button for this yet. The least-resistance path is a script run from a session, dry-run by default:

npm run reset:onboarding-walk -- --email admin@testco.example            # shows what would change
npm run reset:onboarding-walk -- --email admin@testco.example --apply --confirm-table=propflow-prod
npm run reset:onboarding-walk -- --email ... --disconnect --apply --confirm-table=propflow-prod   # also ends channel hooks + disables the AppFolio credential

Ships in #8919. Without --disconnect it clears only the completion stamps (the user row's two dates and the onboarding record), so the wizard opens on whichever steps are still outstanding. With it, the company's mailbox and calendar hooks and the admin's own calendar hook are ended and the AppFolio credential is disabled, so the walk starts from the AppFolio step. Imported properties are left alone; the import is an upsert and re-running it is safe. To wipe properties too, use reset-org-sync-for-reimport.ts, which is heavier and requires sync to be paused first.

What shipped on 2026-09-16

PR	What it did
#8841	Google sign-in moved to a company-owned Google Cloud project.
#8845	One multi-provider integration row, used everywhere a vendor is chosen.
#8878	The channel vault refreshes Google tokens through Google; company and person rungs admit a Google row.
#8883	A centralized company connects its shared Google calendar; "Calendar connected" tone in settings and onboarding.
#8884	Teammates step: email-only invites, standard role select, one ending.
#8895	The Microsoft-named onboarding step renamed vendor-neutral; old address redirects.
#8897	A leasing agent connects their own Google calendar (first sign-in screen and My calendar).
#8902	One Channels step: the company shape renders in place; both shapes continue into the wizard.
#8906	Google's account chooser on the person lane, so "connect a different account" can.
#8911	Your calendar as wizard step 5 of 6, with the offer stamped on render.
#8914	Person-calendar links signed and session-bound on both vendors.

Gotchas the next agent will hit

The company-callback tests mock org-connect-state wholesale. A new export read at import time by anything the callback imports kills them on load. That is why the shared max-age lives in the signer module.
A push disarms auto-merge. Re-arm after every push once the reviewer's verdict is clean.
Route pins. Adding or moving a page needs npm run generate:route-manifest; the wizard route list, the step counter, the middleware's private-segment list and the activity step map are all pinned by tests and all have to move together.
The symbol sweep blocks a push that leaves a comment naming a deleted export. Grep after every rename.
Mutation controls and drift fences (calendar-engine provider allowlist, and the like) must be re-pointed in the same PR that changes what they pin.
The reviewer reads the whole diff up to about 300 lines, then samples. Slice vertically; branch every part off origin/main.

Companion pages: Google Calendar, Three Rungs (the plan this executed) · Google connect flow · New customer onboarding experience.