@odla-ai/cli 0.9.0 → 0.10.1

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,
-  and observability on Cloudflare, provisioned by @odla-ai/cli. Use when the user
+  read-only Google Calendar mirrors, 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, and OpenTelemetry **observability**, all provisioned by the
+**Clerk** auth, read-only **Google Calendar** mirrors, and OpenTelemetry **observability**, all provisioned by the
 `@odla-ai/cli`. The human approves a couple of browser-only checkpoints; you do
 everything else.
 
@@ -37,6 +37,9 @@ State which path you're taking and what you'll build in one line; get a nod.
    `.odla/credentials.local.json`, or `.odla/dev-token.json` — use `ls -l` to
    confirm they exist (and are `0600`). The only value a human ever pastes is a
    Clerk **publishable** key (`pk_…`) — public by design.
+   A fresh odla device request also needs the existing account email via
+   `--email` or `ODLA_USER_EMAIL`; email is a non-secret identifier. Never ask
+   for an odla password, Clerk token, or browser session.
 2. **Dev before prod.** Keep `envs: ["dev"]` and verify the tenant
    (`<appId>--dev`) before any write or deploy. Add `prod` only at the explicit
    production checkpoint. The first prod
@@ -48,6 +51,9 @@ State which path you're taking and what you'll build in one line; get a nod.
 4. Never `git add -A` without reading `git status` first. Never run
    `provision --rotate-keys` or `provision --rotate-o11y-token` unless the human
    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.
 
 ## The flow
 
@@ -63,11 +69,15 @@ guessing which platform/credential steps need manual work. Then:
    `withObservability`. The CLI will refuse secret delivery until the Wrangler
    target exists.
 3. **provision** ⏸ —
-   `npx @odla-ai/cli provision --write-dev-vars --push-secrets`. A device code
-   prints; the human approves it at https://odla.ai/studio. It creates the app,
+   `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,
    enables services, issues or reuses configured credentials (db key + o11y
    ingest token when enabled), pushes schema + rules, writes `.dev.vars`, and
-   transfers Worker secrets through Wrangler stdin.
+   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.
 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
@@ -88,6 +98,10 @@ 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.
 
 The CLI owns deterministic platform work from `odla.config.mjs`: service
 enablement, credential issuance/storage, `.dev.vars`, and Wrangler secret

package/skills/odla/references/build.md

@@ -15,6 +15,13 @@ 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.
+
 ## 2. Build the Worker shell
 
 `npm i` only the SDKs you need and use the local `references/sdks.md` as the
@@ -30,11 +37,13 @@ service source or online documentation is not setup context.
 ## 3. Provision  ⏸ device-code approval
 
 ```
-npx @odla-ai/cli provision --write-dev-vars --push-secrets
+npx @odla-ai/cli provision --email <existing-odla-account> --write-dev-vars --push-secrets
 ```
 
-Prints a short device code and a link. ⏸ The human opens https://odla.ai/studio, signs
-in, and approves the code — no secret passes through the chat. Provision then:
+The email is an account identifier, never a password or session credential.
+Prints a short device code and a link. ⏸ That same account opens the link, signs
+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
 `.dev.vars`, and transfers configured Worker secrets through Wrangler stdin.
@@ -43,6 +52,13 @@ Local credential files are `0600` and gitignored. Verify with
 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
+`npx @odla-ai/cli calendar calendars --env dev --json`, refine the checked-in
+calendar ids if needed, re-provision, and verify `calendar status --json`.
+
 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
 Studio rotation is recovery-only;
@@ -61,6 +77,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.
+
 ## 5. Security preflight
 
 Install the passive harness and scan before any production secret or deploy:

package/skills/odla/references/sdks.md

@@ -31,6 +31,35 @@ 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
+
+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.
+
+```ts
+// Trusted Worker only — the admin key must never enter browser code.
+const calendar = initCalendar({
+  appId: env.ODLA_TENANT,
+  adminToken: env.ODLA_API_KEY,
+  endpoint: env.ODLA_ENDPOINT,
+});
+const next = await calendar.bookings.next("member@example.com");
+```
+
+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.
+
+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`.
+
 ## @odla-ai/ai — inference (Claude / GPT / Gemini)
 
 ```ts

package/skills/odla-migrate/SKILL.md

@@ -2,13 +2,14 @@
 name: odla-migrate
 description: >
   Migrate a static site (e.g. GitHub Pages) to odla on Cloudflare in safe
-  phases, then add a database, Clerk login, and AI. Use when the user wants to
+  phases, then add a database, optional read-only calendar mirror, 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:
   - references/phase-0-preflight.md
   - references/phase-1-static.md
   - references/phase-2-db.md
+  - references/phase-2b-calendar.md
   - references/phase-3-auth.md
   - references/phase-3b-user-sync.md
   - references/phase-4-ai.md
@@ -37,6 +38,9 @@ installed skill at `../odla/SKILL.md` instead.
 3. Never print, paste, or commit a secret. Never `cat` .dev.vars,
    .odla/credentials.local.json, or .odla/dev-token.json. Read
    references/secrets-map.md BEFORE any command that touches a credential.
+   A fresh device request requires the existing odla account email via
+   `--email` or `ODLA_USER_EMAIL`; email is a non-secret identifier. Never ask
+   for an odla password, Clerk token, or browser session.
 4. Never `git add -A` without reading `git status` first.
 5. Never widen a db rule to silence a 403 — default-deny is the design.
    Any rules change is a human checkpoint.
@@ -45,12 +49,16 @@ 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.
 
 ## Phase state machine
 
 Phases run strictly in order; each has a verification gate:
 
-  P0 preflight -> P1 static-on-cloudflare -> P2 database -> P3 login
+  P0 preflight -> P1 static-on-cloudflare -> P2 database -> P2b calendar (optional) -> P3 login
   -> P4 ai (optional) -> P5 prod + DNS cutover
 
 `MIGRATION.md` at the user's repo root is the durable state: create it in
@@ -100,6 +108,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-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

@@ -4,14 +4,15 @@ Goal: the app registered on the platform, a dev odla-db tenant with
 schema + deny-all rules, the db key in the dev worker, and first
 `/api/*` routes live in dev.
 
-Human obligation: sign in at https://odla.ai/studio and approve the handshake
-code when the provision run prints it (it also opens the approval page
-in the browser in interactive terminals).
+Human obligation: provide the existing odla account email (not a password or
+session credential), sign in at https://odla.ai/studio, explicitly review the
+exact handshake code, and approve it. The provision run prints the code and
+opens the review page in interactive terminals; loading it alone is inert.
 
 ## Steps
 
-1. Require `npm view @odla-ai/cli@0.8.0 version` to succeed, then run
-   `npm i -D --save-exact @odla-ai/cli@0.8.0` and `npm i @odla-ai/db`.
+1. Require `npm view @odla-ai/cli@0.10.1 version` to succeed, then run
+   `npm i -D --save-exact @odla-ai/cli@0.10.1` 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** —
@@ -32,7 +33,8 @@ in the browser in interactive terminals).
    directly. Loosening a rule is a human checkpoint.
 5. `npx @odla-ai/cli doctor` until clean.
 6. `npx @odla-ai/cli provision --dry-run` — show the plan to the human.
-7. `npx @odla-ai/cli provision --write-dev-vars --push-secrets` — handshake,
+7. `npx @odla-ai/cli provision --email <existing-odla-account>
+   --write-dev-vars --push-secrets` — handshake,
    app registration, dev db key, schema + rules push; writes
    `.odla/credentials.local.json` (0600) and `.dev.vars`, then pipes configured
    Worker secrets to Wrangler over stdin. Both local files are gitignored by

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

@@ -0,0 +1,42 @@
+# 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.0 version` to succeed, then install
+   `npm i --save-exact @odla-ai/calendar@0.1.0` 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.

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

@@ -8,8 +8,9 @@
 | Clerk webhook secret (`whsec_…`) | tenant vault (`clerk_webhook_secret`) | only for auth mode "full"; piped with `secrets set clerk_webhook_secret --env <env> --stdin`, or entered in Studio; never wrangler, never chat |
 | Clerk secret key (`sk_test_`/`sk_live_`) | not needed for this journey | if a later feature needs user resolution/invites, pipe it with `secrets set-clerk-key --env <env>` (reserved `$clerk_secret`, write-only); never chat |
 | LLM provider key | tenant vault | env var in the HUMAN's shell for one provision run; never wrangler vars, never git, never chat |
+| `ODLA_USER_EMAIL` / `--email` | process environment or one command invocation | non-secret identifier for the existing signed-in odla account allowed to review a fresh request; never substitute a password or session token |
 | `odla_sk_…` (tenant db key) | wrangler secret `ODLA_API_KEY` + `.odla/credentials.local.json` (0600) + `.dev.vars` | present when db is enabled; move it only with the pipeline below |
-| `odla_dev_…` (developer token) | `.odla/dev-token.json` (0600) | ~24h lifetime, provision-time only; never deployed |
+| `odla_dev_…` (developer token) | `.odla/dev-token.json` (0600) | tracked/revocable, ~24h lifetime, provision-time only; never deployed; deleting this cache does not revoke a copied token |
 | scoped `odla_dev_…` (admin-approved platform capability) | `.odla/admin-token.local.json` (0600) | separate policy/credential/usage/self-audit scope, ~15m lifetime, denied on owner routes, never deployed |
 | `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 |

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

@@ -30,7 +30,9 @@ 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
-human approves the new code at the printed URL. Use `--no-open` in
+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.
 
 ## `smoke` fails: missing credentials

package/skills/odla-o11y-debug/SKILL.md

@@ -29,9 +29,13 @@ GET https://odla.ai/o11y/<appId>/<endpoint>?env=prod
 Authorization: Bearer <developer-token>
 ```
 
-Get `<developer-token>` from the device handshake (`POST https://odla.ai/handshake`
-→ approve in the Studio → `POST /handshake/poll`). `env` is `prod` (default) or
-`dev`. If a read returns `{"error":"ae_not_configured"}` (501), the app's metrics
+Get `<developer-token>` from `@odla-ai/cli` or the device handshake: start with
+`POST https://odla.ai/handshake` and
+`{"email":"<existing-odla-account>","label":"o11y debugger"}`, show the returned
+verification URL, then poll `POST /handshake/poll`. Email is a non-secret
+identifier; never ask for a password or session token. The matching account
+must sign in and explicitly review and approve the exact code. `env` is `prod`
+(default) or `dev`. If a read returns `{"error":"ae_not_configured"}` (501), the app's metrics
 reads aren't turned on yet — errors/traces still work; say so and fall back to them.
 
 ## Endpoints