@odla-ai/cli 0.11.2 → 0.13.0

package/dist/index.js

@@ -2,19 +2,19 @@
 import {
   AGENT_HARNESSES,
   CAPABILITIES,
-  GOOGLE_CALENDAR_READ_SCOPE,
+  GOOGLE_CALENDAR_EVENTS_SCOPE,
   SYSTEM_AI_PURPOSES,
   adminAi,
   calendarBookingPageUrl,
   calendarCalendars,
   calendarConnect,
   calendarDisconnect,
-  calendarResync,
   calendarServiceConfig,
   calendarStatus,
   connectGitHubSecuritySource,
   disconnectGitHubSecuritySource,
   doctor,
+  exitCodeFor,
   followHostedSecurityJob,
   getHostedSecurityIntent,
   getHostedSecurityJob,
@@ -38,23 +38,23 @@ import {
   secretsSetClerkKey,
   smoke,
   startHostedSecurityJob
-} from "./chunk-DC4MIB4X.js";
+} from "./chunk-I7XDJZB6.js";
 export {
   AGENT_HARNESSES,
   CAPABILITIES,
-  GOOGLE_CALENDAR_READ_SCOPE,
+  GOOGLE_CALENDAR_EVENTS_SCOPE,
   SYSTEM_AI_PURPOSES,
   adminAi,
   calendarBookingPageUrl,
   calendarCalendars,
   calendarConnect,
   calendarDisconnect,
-  calendarResync,
   calendarServiceConfig,
   calendarStatus,
   connectGitHubSecuritySource,
   disconnectGitHubSecuritySource,
   doctor,
+  exitCodeFor,
   followHostedSecurityJob,
   getHostedSecurityIntent,
   getHostedSecurityJob,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Agent-operable CLI for odla provisioning, calendar consent and sync lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",

package/skills/odla/SKILL.md

@@ -2,7 +2,7 @@
 name: odla
 description: >
   Build a new app on odla — a realtime database (odla-db) plus AI, Clerk auth,
-  read-only Google Calendar mirrors, and observability on Cloudflare, provisioned by @odla-ai/cli. Use when the user
+  live Google Calendar booking, and observability on Cloudflare, provisioned by @odla-ai/cli. Use when the user
   wants to create/scaffold an odla app, add odla-db/ai/auth/o11y to a repo, or
   "get started with odla". For moving an existing static or GitHub Pages site to
   odla, use the odla-migrate skill instead.
@@ -15,7 +15,7 @@ runbookOrder:
 
 You drive setup and building on **odla** — an agent-operable app platform on
 Cloudflare: a realtime graph database (**odla-db**), multi-provider **AI**,
-**Clerk** auth, read-only **Google Calendar** mirrors, and OpenTelemetry **observability**, all provisioned by the
+**Clerk** auth, live **Google Calendar** booking, and OpenTelemetry **observability**, all provisioned by the
 `@odla-ai/cli`. The human approves a couple of browser-only checkpoints; you do
 everything else.
 
@@ -53,7 +53,8 @@ State which path you're taking and what you'll build in one line; get a nod.
    explicitly asks.
 5. Google OAuth is a distinct human checkpoint. Never request, paste, print, or
    store a Google authorization code/refresh token. Open only the state-bound
-   platform/Google consent URL returned by odla; calendar actions remain unavailable in the read-only slice.
+   platform/Google consent URL returned by odla; booking runs server-side
+   through the SDK with the app's existing key, never from a browser.
 
 ## Tooling sources
 
@@ -94,12 +95,19 @@ guessing which platform/credential steps need manual work. Then:
    `npx @odla-ai/cli provision --email <existing-odla-account>
    --write-dev-vars --push-secrets`. A device code prints; that same account
    signs in, reviews the exact code, and approves it at https://odla.ai/studio.
-   Opening the link alone is inert. It creates the app,
+   Opening the link alone is inert. Relay the printed approval URL to the
+   human verbatim — the automatic browser launch is best-effort and may show
+   no tab. Outside an interactive terminal the wait is capped (90s default,
+   `--wait <seconds>`); exit code 75 means still pending: the handshake is
+   persisted, so once the human approves, re-run the same command and it
+   resumes the same code and collects the token. It creates the app,
    enables services, issues or reuses configured credentials (db key + o11y
-   ingest token when enabled), pushes schema + rules, writes `.dev.vars`, and
+   ingest token when enabled), composes declared integration schema/rules and
+   guarded seeds, writes `.dev.vars`, and
    transfers Worker secrets through Wrangler stdin. With calendar enabled it
-   then prints a second, server-issued Google URL; the human grants read-only consent
-   and the CLI follows initial sync.
+   then prints a second, server-issued Google URL; the human grants booking
+   consent in a browser and the connection is immediately live — nothing
+   syncs.
 4. **run** — `npx wrangler dev` (auto-loads `.dev.vars`); verify locally.
 5. **security** — run the passive `@odla-ai/security` odla profile; inspect
    every lead and keep critical candidate gating enabled. If the human approves
@@ -120,14 +128,16 @@ guessing which platform/credential steps need manual work. Then:
 
 `npx @odla-ai/cli doctor` is an offline config check anytime;
 `npx @odla-ai/cli smoke --env dev` verifies a live deployment.
-Use `calendar status --json` for safe connection/sync state and `calendar
-calendars --json` to discover ids after consent; update checked-in config and
-re-provision. Resync production only with `--yes`; disconnect always requires
-`--yes` and leaves retained rows potentially stale.
+Use `calendar status --json` for safe connection state (`bookable`, booking
+and availability calendars) and `calendar calendars --json` to discover ids
+after consent; update checked-in config and re-provision. Disconnect always
+requires `--yes` and removes only this connection's sealed grant — Google
+keeps every booked event.
 
 The CLI owns deterministic platform work from `odla.config.mjs`: service
-enablement, credential issuance/storage, `.dev.vars`, and Wrangler secret
-transfer. You own source changes — install `@odla-ai/o11y`, add
+enablement, integration schema/rules/seeds, credential issuance/storage,
+`.dev.vars`, and Wrangler secret transfer. You own source changes — install
+runtime capability packages, mount their routes, supply authorization, add
 `withObservability`, create the Wrangler config, and choose application-specific
 signals. The human owns device approval, production consent, and explicit
 destructive rotation. If an

package/skills/odla/references/build.md

@@ -15,12 +15,18 @@ deny-all rules from the schema. To turn on auth/observability, add `"o11y"` to
 `services` and an `auth.clerk` block in `odla.config.mjs` (init leaves it
 commented).
 
-For a Google booking mirror, include both `"db"` and `"calendar"`. Configure
-`calendar.google.calendars` for every env (start with `"primary"`), optional
-match filters, and `attendeePolicy: "full" | "hashed"`. This release is
-read-only; do not add OAuth credentials or action scopes to config.
-For static Appointment Schedule parity, add the public per-env
-`bookingPageUrl`; it is link/embed configuration, never a credential.
+For an npm app capability such as `@odla-ai/crm`, import its data-only
+descriptor into `odla.config.mjs` and add it under `integrations`; do not add
+the capability id to `services`. Provision collision-checks and merges its
+schema/rules, creates guarded seeds only when absent, and leaves runtime package
+installation and route mounting to the source step.
+
+For Google Calendar booking, include both `"db"` and `"calendar"`. Configure
+`calendar.google.availabilityCalendars` for every env (start with
+`"primary"`; 1–10 per env) and optionally `bookingCalendar` (defaults to the
+first availability calendar). Do not add OAuth credentials to config — the
+Google grant is platform-side. A legacy per-env `bookingPageUrl` link may be
+kept as a fallback; it is public configuration, never a credential.
 
 ## 2. Build the Worker shell
 
@@ -50,19 +56,22 @@ Prints a short device code and a link. ⏸ That same account opens the link, sig
 in, explicitly reviews the exact code, and approves it — loading the URL alone
 does not claim access, and no secret passes through the chat. Provision then:
 creates the app, enables its services, issues or reuses the db key (and the
-o11y ingest token when o11y is enabled), pushes schema + rules, writes
+o11y ingest token when o11y is enabled), pushes the composed app + integration
+schema/rules, creates missing guarded seeds, writes
 `.dev.vars`, and transfers configured Worker secrets through Wrangler stdin.
 Local credential files are `0600` and gitignored. Verify with
-`npx @odla-ai/cli doctor` — it prints the app, envs, services, and flags
+`npx @odla-ai/cli doctor` — it prints the app, envs, services, integrations, and flags
 anything unset. `--push-secrets` preflights the Wrangler config and login before
 issuing or rotating a shown-once credential.
 
 Calendar adds a second ⏸ checkpoint after the odla device approval: provision
-prints/opens a state-bound Google URL issued by the platform and waits while the human grants
-`calendar.events.readonly` and the hosted connector performs initial sync. The
-CLI never receives the Google callback code or tokens. Once connected, run
+prints/opens a state-bound Google URL issued by the platform and waits while
+the human grants the booking scopes in a browser. The CLI never receives the
+Google callback code or tokens, and nothing syncs afterward — Google stays
+the single source of truth. Once connected, run
 `npx @odla-ai/cli calendar calendars --env dev --json`, refine the checked-in
-calendar ids if needed, re-provision, and verify `calendar status --json`.
+calendar ids if needed, re-provision, and verify `calendar status --env dev`
+reports `bookable: yes`.
 
 The CLI stops at the source boundary: it verifies but does not invent your
 application semantics. Do not use Studio to mint a routine o11y token. Manual
@@ -82,10 +91,11 @@ means the namespace has no rule yet — add one in `src/odla/rules.mjs`
 (deliberately; e.g. `{ notes: { view: "auth.signedIn", create: "auth.signedIn" } }`),
 re-provision to push it, and retry.
 
-Calendar uses the same `ODLA_ENDPOINT`, `ODLA_TENANT`, and server-only
-`ODLA_API_KEY`; it adds no Worker secret. Keep `initCalendar` in trusted Worker
-code. Browser code uses db subscriptions under explicit rules or pure
-`@odla-ai/calendar/client` helpers, never the admin key.
+Calendar rides the server-only `ODLA_API_KEY`; it adds no Worker secret. Keep
+`initCalendar` in trusted Worker code and expose the app's own slots/booking
+endpoints to the browser — never call the platform calendar routes from
+browser code. Browsers may import only the pure `@odla-ai/calendar/client`
+helpers (`computeBookableSlots`, formatters), never the admin key.
 
 ## 5. Security preflight
 

package/skills/odla/references/sdks.md

@@ -32,34 +32,46 @@ Worker/admin side: `init({ appId: tenantId, adminToken: env.ODLA_API_KEY, endpoi
 The publishable key is public; `provision` stores it (`setAuth`). Rules evaluate
 the signed-in user's JWT as `auth` — e.g. `auth.signedIn`, `auth.email`.
 
-## @odla-ai/calendar — read-only Google booking mirror
+## @odla-ai/calendar — live Google Calendar booking
 
 Calendar requires `services: ["db", "calendar"]` plus a `calendar.google`
-block. Normal provision opens a second, state-bound Google checkpoint issued by the platform for the
-human to grant `calendar.events.readonly`; Google tokens stay in the hosted
-connector and never become app/CLI secrets.
+block (`availabilityCalendars` per env, optional `bookingCalendar`). Normal
+provision opens a second, state-bound Google checkpoint issued by the
+platform; the human grants the booking scopes in a browser. Google tokens
+stay platform-side and never become app/CLI secrets. Google Calendar is the
+single source of truth — odla stores no calendar or attendee data, and
+nothing syncs.
 
 ```ts
 // Trusted Worker only — the admin key must never enter browser code.
-const calendar = initCalendar({
-  appId: env.ODLA_TENANT,
+const cal = initCalendar({
+  appId: env.ODLA_APP_ID,       // registry app id
+  env: env.ODLA_ENV,
   adminToken: env.ODLA_API_KEY,
-  endpoint: env.ODLA_ENDPOINT,
+  endpoint: env.ODLA_PLATFORM ?? "https://odla.ai",
 });
-const next = await calendar.bookings.next("member@example.com");
+const fb = await cal.availability.freeBusy({ timeMin, timeMax });
+const slots = computeBookableSlots(fb.busy, { from: timeMin, to: timeMax,
+  timezone, slotMinutes: 30 });
+const { booking } = await cal.actions.create(
+  { summary, startAt, endAt, attendees: [email], timezone, meet: true },
+  { idempotencyKey: `booking:${recordId}` }, // retry-safe; Google emails the invite
+);
 ```
 
-Browser code may query `$bookings` with `@odla-ai/db/client` only under an
-explicit view rule, and may import pure formatting helpers from
-`@odla-ai/calendar/client`. Do not import `initCalendar` or expose
-`ODLA_API_KEY` in a browser. Provider actions are not part of the read-only
-slice; a `calendar_not_connected`/501 action response is not a reason to widen
-credentials or request a Google token.
+Store the returned `eventId`/`meetUrl` on the app's own record;
+`actions.reschedule(eventId, …)` and `actions.cancel(eventId)` use it. A
+taken slot rejects with non-retryable `calendar_slot_unavailable` — refetch
+slots, don't retry. Browser code never calls `initCalendar` or the platform
+calendar routes; it hits the app's own endpoints and may import pure helpers
+(`computeBookableSlots`, formatters) from `@odla-ai/calendar/client`.
+`SlotPicker` from `@odla-ai/ui` renders the slot output directly.
 
 After consent, use `odla-ai calendar calendars --env dev --json` to discover
-selectable ids, edit the checked-in list, and optionally set a public per-env
-`bookingPageUrl` for Appointment Schedule embed/link mode. Re-provision, then verify with
-`calendar status --json` and `smoke`.
+selectable ids and edit the checked-in list. Re-provision, then verify
+`calendar status --env dev` reports `bookable: yes` and `smoke` passes. A
+pre-pivot read-only grant reports `degraded`/`calendar_reconsent_required`;
+re-run `calendar connect`.
 
 ## @odla-ai/ai — inference (Claude / GPT / Gemini)
 
@@ -71,6 +83,31 @@ await ai.chat({ messages }); // provider/model + key resolved from the platform
 No API key in your code or env — it lives in the tenant vault; `provision`
 stores it when the configured `ai.keyEnv` is set at provision time.
 
+## @odla-ai/crm — records, pipelines, follow-ups, and contactability
+
+Define the CRM once in an app module, mount `createCrmRoutes` in trusted Worker
+code behind the app's admin authorization, and render the optional admin kit
+from `@odla-ai/crm/ui`. Declare `createCrmIntegration(crm, options)` under
+`odla.config.mjs` `integrations`—never under `services`.
+
+```ts
+import { createCrmIntegration } from "@odla-ai/crm";
+import { crm } from "./src/crm.js";
+
+export default {
+  app: { id: "my-app", name: "My App" },
+  services: ["db"],
+  integrations: [createCrmIntegration(crm, { basePath: "/api/crm" })],
+  links: { dev: "https://dev.example.com" },
+};
+```
+
+Provision merges the CRM schema/rules and creates `crm_config` only when
+absent. Doctor checks the composed contract offline; smoke calls the records
+route anonymously and requires `401`. The CLI does not edit the Worker or
+invent `authorize`. Billing is an optional injected `BillingProvider`; reuse
+app-owned payment code when present rather than assuming another package.
+
 ## @odla-ai/o11y — observability (Cloudflare Workers)
 
 ```ts

package/skills/odla-migrate/SKILL.md

@@ -2,7 +2,7 @@
 name: odla-migrate
 description: >
   Migrate a static site (e.g. GitHub Pages) to odla on Cloudflare in safe
-  phases, then add a database, optional read-only calendar mirror, Clerk login, and AI. Use when the user wants to
+  phases, then add a database, optional Google Calendar booking, Clerk login, and AI. Use when the user wants to
   move a static or GitHub Pages site to Cloudflare/odla, or to add a backend,
   database, login/auth, or AI features to a static site via odla.
 runbookOrder:
@@ -49,10 +49,12 @@ installed skill at `../odla/SKILL.md` instead.
    approved o11y rotation with `--push-secrets` so the Worker is updated in the
    same run. If the final Wrangler transfer fails, use the CLI's printed
    non-rotating `secrets push` retry; never rotate again just to retry delivery.
-7. Existing calendar embeds are public links, not proof of a booking. Preserve
-   them via `bookingPageUrl`; never claim reconciliation until the read-only
-   mirror is connected and the app correlates `$bookings` deliberately. Google
-   OAuth tokens never enter the repo, CLI, or chat.
+7. Calendar booking is server-side only. `initCalendar` and the platform's
+   calendar routes authenticate with the app's full `ODLA_API_KEY` — never
+   call them from a browser; the browser talks to the app's own Worker
+   endpoints. An old public embed link is not a booking flow; preserve it via
+   `bookingPageUrl` only until the native flow is verified. Google OAuth
+   tokens never enter the repo, CLI, or chat.
 
 ## Phase state machine
 
@@ -108,7 +110,7 @@ Read the current phase's file when you enter it — not before:
 - references/phase-0-preflight.md
 - references/phase-1-static.md
 - references/phase-2-db.md
-- references/phase-2b-calendar.md (optional: preserve an embed and add authoritative read-only reconciliation)
+- references/phase-2b-calendar.md (optional: live Google Calendar booking — slots, create/reschedule/cancel through the app's own Worker)
 - references/phase-3-auth.md
 - references/phase-3b-user-sync.md (optional: mirror Clerk users into $users)
 - references/phase-4-ai.md

package/skills/odla-migrate/references/phase-2-db.md

@@ -11,8 +11,8 @@ opens the review page in interactive terminals; loading it alone is inert.
 
 ## Steps
 
-1. Require `npm view @odla-ai/cli@0.10.2 version` to succeed, then run
-   `npm i -D --save-exact @odla-ai/cli@0.10.2` and `npm i @odla-ai/db`.
+1. Require `npm view @odla-ai/cli@0.13.0 version` to succeed, then run
+   `npm i -D --save-exact @odla-ai/cli@0.13.0` and `npm i @odla-ai/db`.
 2. `npx @odla-ai/cli init --app-id <id> --name "<Name>" --env dev --services db`
    Review `odla.config.mjs`. Keep `envs: ["dev"]` — prod is Phase 5. Set
    `links.dev` to the URL the Phase 1 `wrangler deploy` **actually printed** —

package/skills/odla-migrate/references/phase-2b-calendar.md

@@ -1,42 +1,130 @@
-# Phase 2b — Google Calendar (optional, read-only)
-
-Use this phase only when the existing site has a Google Appointment Schedule
-link/embed or locally reported meeting state. Keep the old booking experience
-working while adding an authoritative read-only mirror.
-
-Human obligations: review attendee-data retention and complete the second,
-server-issued Google consent page. They never paste an OAuth code or token.
-
-1. Inventory the old behavior. Distinguish a public appointment-page link from
-   actual event create/reschedule/cancel APIs. Do not promise more than exists.
-2. Require `npm view @odla-ai/calendar@0.1.1 version` to succeed, then install
-   `npm i --save-exact @odla-ai/calendar@0.1.1` as a runtime dependency. An
-   exact-version `E404` blocks this phase; do not substitute a git checkout or
-   another version. Add `"calendar"` beside
-   `"db"` in services and configure:
-   - `calendar.google.calendars.dev` (start with `"primary"`);
-   - optional summary/organizer/attendee match filters;
-   - deliberate `attendeePolicy: "full" | "hashed"`;
-   - the old public Appointment Schedule URL as `bookingPageUrl.dev` when
-     preserving the embed/link. It is public configuration, not a secret.
-3. Run `doctor`, then `provision --dry-run`. Show the human the calendars,
-   attendee policy, public booking page, and read-only scope.
-4. Run normal dev provision. After odla device approval, pause again while the
-   human grants Google `calendar.events.readonly`; the CLI follows initial sync.
-5. Run `calendar calendars --env dev --json`, refine the checked-in ids, and
-   re-provision. Verify `calendar status --env dev --json` and `smoke --env dev`.
-6. Put `initCalendar` only in trusted Worker code. Browser code may keep using
-   the public `bookingPageUrl`, query `$bookings` through explicit db rules, or
-   import pure helpers from `@odla-ai/calendar/client`. Never expose
-   `ODLA_API_KEY`.
-7. Replace self-reported meeting state only after an explicit, tested
-   application-to-booking correlation exists. A matching attendee email may be
-   sufficient for some apps; do not silently regress later workflow statuses.
-
-This slice cannot create, reschedule, or cancel Google events. A static picker
-continues to be Google's sealed UI; odla supplies configuration, mirror reads,
-and reconciliation.
-
-Gate: the old embed/link still works, status is healthy, the selected calendars
-match config, `$bookings` smoke succeeds, no Google credential exists in local
-files, and `MIGRATION.md` records the disclosure/correlation decision.
+# Phase 2b — Google Calendar booking (optional)
+
+Use this phase when the site should offer real scheduling: visitors pick a
+bookable slot and the app creates a live Google Calendar event — with a Meet
+link and an invitation email that Google itself sends. Google Calendar is the
+single source of truth; odla stores no calendar or attendee data. There is no
+sync, no mirror, and no `$bookings` namespace.
+
+Human obligations: complete the server-issued Google consent page in a
+browser (they never paste an OAuth code or token), and receive the test
+invitation email during verification.
+
+Boundary that shapes every step: `initCalendar` and the platform's calendar
+routes are **server-side only** — they authenticate with the app's full
+`ODLA_API_KEY`. Never call them from a browser; the browser talks only to
+this app's own Worker endpoints and may import pure helpers from
+`@odla-ai/calendar/client`.
+
+1. Require `npm view @odla-ai/calendar@0.2.0 version` to succeed, then
+   install `npm i --save-exact @odla-ai/calendar@0.2.0` as a runtime
+   dependency. An exact-version `E404` blocks this phase; do not substitute a
+   git checkout or another version.
+2. Add `"calendar"` beside `"db"` in services and author the config block —
+   booking rides the existing db key, so calendar adds no new secret:
+
+   ```js
+   calendar: {
+     google: {
+       availabilityCalendars: { dev: ["primary"] }, // 1–10 per env
+       bookingCalendar: { dev: "primary" },         // optional; defaults to first availability calendar
+       bookingPageUrl: { dev: null },               // optional legacy fallback link
+     },
+   },
+   ```
+
+3. Run `doctor`, then `provision --dry-run`; show the human the calendars and
+   the booking scopes. Run normal dev provision. Consent runs last: the CLI
+   prints/opens a state-bound Google URL and the human grants access in a
+   browser. If the platform connector reports a readiness 503
+   (`calendar_*_not_configured`), provision still completes and prints a
+   `calendar connect --env dev` resume hint — that gap is platform-operator
+   work, not yours. Then `calendar calendars --env dev --json` to refine
+   checked-in ids, and verify `calendar status --env dev` shows
+   `bookable: yes` (a pre-pivot read-only grant shows `degraded` /
+   `calendar_reconsent_required`; re-run `calendar connect`).
+4. Build the **slots endpoint** in the app's Worker — capability-gated like
+   every other route (a booking endpoint that ignores Phase 3 auth decisions
+   is a regression):
+
+   ```ts
+   import { initCalendar, computeBookableSlots } from "@odla-ai/calendar";
+
+   // GET /api/booking/slots
+   const cal = initCalendar({
+     appId: env.ODLA_APP_ID,
+     env: env.ODLA_ENV,
+     adminToken: env.ODLA_API_KEY,
+     endpoint: env.ODLA_PLATFORM ?? "https://odla.ai",
+   });
+   const fb = await cal.availability.freeBusy({
+     timeMin: Date.now(),
+     timeMax: Date.now() + 14 * 86_400_000,
+   });
+   const slots = computeBookableSlots(fb.busy, {
+     from: fb.timeMin,
+     to: fb.timeMax,
+     timezone: BOOKING_TIMEZONE,          // app-owned config, not user input
+     slotMinutes: 30,
+     businessHours: { days: [1, 2, 3, 4, 5], startHour: 9, endHour: 17 },
+     minNoticeMs: 24 * 3_600_000,
+   });
+   return Response.json({ slots, timezone: BOOKING_TIMEZONE });
+   ```
+
+   Business hours, slot length, notice, and buffers are this app's product
+   decisions — keep them in app config, and reject slot requests wider than
+   the window you offer.
+5. Build the **create endpoint** (`POST /api/booking`). Validate that the
+   requested slot is one this app offers (recompute from the same config),
+   then create — the platform re-validates availability under its booking
+   lease, so a stale slot cannot double-book:
+
+   ```ts
+   const { booking, duplicate } = await cal.actions.create(
+     {
+       summary: `Intro call — ${name}`,
+       startAt, endAt,
+       attendees: [email],
+       timezone: BOOKING_TIMEZONE,
+       meet: true,               // Meet link on the event and in the invite
+       // notify defaults true → Google emails the invitation
+     },
+     { idempotencyKey: `booking:${applicationId}` }, // your own stable record id
+   );
+   ```
+
+   Store the returned `booking.eventId` and `booking.meetUrl` on the app's
+   own record (its odla-db row) — that record is the app's only persistence;
+   attendee data lives in Google. On `calendar_slot_unavailable` (409,
+   non-retryable) return a "slot taken" response; the client refetches
+   `/api/booking/slots` and re-picks. On retryable
+   `calendar_booking_in_progress`, retry once after a short delay.
+6. Reschedule/cancel go through the stored id:
+   `cal.actions.reschedule(eventId, { startAt, endAt })` and
+   `cal.actions.cancel(eventId)` (idempotent) — expose them as app endpoints
+   gated to the record's owner. Attendees can also act through Google's own
+   invitation flows; treat Google as authoritative.
+7. Frontend. Two supported shapes:
+   - **`@odla-ai/ui` SlotPicker** — renders the slots response directly
+     (`{ slots, timezone, onSelect }`). On a non-framework static site use a
+     Preact island: a small entry that mounts `<SlotPicker>` into a div,
+     bundled with esbuild as an IIFE with `react`/`react-dom` aliased to
+     `preact/compat`, committed as a static asset next to the site's other
+     assets.
+   - **Plain fetch + buttons** — `fetch("/api/booking/slots")`, render times
+     with `formatBookingRange` from `@odla-ai/calendar/client`, POST the
+     chosen slot.
+   Either way the browser only ever talks to this app's Worker.
+8. If the old site had a Google Appointment Schedule embed/link, keep it
+   working via `bookingPageUrl` until the native flow is verified, then
+   retire it deliberately.
+
+Gate (live dev round-trip, all of it): a booking made through the site's own
+UI creates the event on the booking calendar with a Meet link; the Google
+invitation email arrives in the test attendee's inbox; a repeat POST with the
+same idempotency key returns `duplicate: true` (no second event); a taken
+slot returns 409 and the UI refetches slots; reschedule and cancel work via
+the stored `eventId`; zero attendee data is persisted anywhere except the
+app's own tenant record; no Google credential exists in local files; and
+`MIGRATION.md` records the booking-flow decision.

package/skills/odla-migrate/references/secrets-map.md

@@ -15,6 +15,9 @@
 | `o11y_…` (o11y ingest token) | wrangler secret `ODLA_O11Y_TOKEN` + `.odla/credentials.local.json` (0600) + `.dev.vars` | only if the app enables o11y; provision issues/reuses it and moves it alongside the db key; never a var, never chat |
 | `ODLA_ENDPOINT` / `ODLA_TENANT` / `ODLA_PLATFORM` / `ODLA_APP_ID` / `ODLA_ENV` | wrangler `vars` | not secrets; keep them set in every env block |
 | `ODLA_O11Y_ENDPOINT` / `ODLA_O11Y_SERVICE` | `.dev.vars` from provision or optional wrangler `vars` overrides | not secrets; public ingest defaults to `https://o11y.odla.ai` and `ODLA_APP_ID` when the token is present |
+| `GOOGLE_CALENDAR_CLIENT_ID` / `GOOGLE_CALENDAR_CLIENT_SECRET` / `CALENDAR_TOKEN_MASTER_KEY` | platform-operator Worker secrets on `odla-apps` | never part of a customer migration; never in chat, the repo, or the app's wrangler config — a readiness 503 (`calendar_*_not_configured`) means the operator sets these, not you |
+| Google calendar grant (OAuth tokens) | platform-side, sealed after human browser consent | the human clicks the server-issued consent URL; no code or token is ever pasted, and the CLI/app/repo never hold one |
+| calendar booking auth (app side) | none — rides the existing `ODLA_API_KEY` | enabling calendar adds NO new app secret; `initCalendar` uses the app's server db key, server-side only, never in a browser |
 
 System AI provider credentials are platform-owned and never enter a customer
 migration. `odla-ai security run` receives only app/run-bound role grants; do

package/skills/odla-migrate/references/troubleshooting.md

@@ -29,11 +29,22 @@ prints what it verified against.
 
 Cause: the `odla_dev_…` token expired (~24h) or the handshake was never
 approved.
-Fix: re-run `npx @odla-ai/cli provision` — it starts a fresh handshake; the
-matching existing account must be supplied with `--email` or
-`ODLA_USER_EMAIL`, then signs in, reviews, and approves the exact code at the
-printed URL. Never ask for a password or session token. Use `--no-open` in
-non-interactive shells if the browser launch misbehaves.
+Fix: re-run `npx @odla-ai/cli provision` — it resumes a still-pending
+handshake if one exists, else starts a fresh one; the matching existing
+account must be supplied with `--email` or `ODLA_USER_EMAIL`, then signs in,
+reviews, and approves the exact code at the printed URL. Never ask for a
+password or session token.
+
+## Handshake exits with code 75 / "handshake still pending"
+
+Cause: nobody approved within the wait cap (90s outside an interactive
+terminal; `--wait <seconds>` overrides). This is normal in agent shells and
+loses nothing — the handshake is persisted in `.odla/handshake.local.json`.
+Fix: relay the printed approval URL to the human **verbatim** (browser
+launch is best-effort — a sandboxed shell can report success with no tab
+appearing), wait for them to approve, then re-run the same command; it
+resumes the same code and collects the token. Do not loop unattended
+retries; each handshake lives ~10 minutes.
 
 ## `smoke` fails: missing credentials