@odla-ai/cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -2,8 +2,16 @@
 import {
   AGENT_HARNESSES,
   CAPABILITIES,
+  GOOGLE_CALENDAR_READ_SCOPE,
   SYSTEM_AI_PURPOSES,
   adminAi,
+  calendarBookingPageUrl,
+  calendarCalendars,
+  calendarConnect,
+  calendarDisconnect,
+  calendarResync,
+  calendarServiceConfig,
+  calendarStatus,
   connectGitHubSecuritySource,
   disconnectGitHubSecuritySource,
   doctor,
@@ -30,12 +38,20 @@ import {
   secretsSetClerkKey,
   smoke,
   startHostedSecurityJob
-} from "./chunk-MJYQ7YDH.js";
+} from "./chunk-WDKBW4BE.js";
 export {
   AGENT_HARNESSES,
   CAPABILITIES,
+  GOOGLE_CALENDAR_READ_SCOPE,
   SYSTEM_AI_PURPOSES,
   adminAi,
+  calendarBookingPageUrl,
+  calendarCalendars,
+  calendarConnect,
+  calendarDisconnect,
+  calendarResync,
+  calendarServiceConfig,
+  calendarStatus,
   connectGitHubSecuritySource,
   disconnectGitHubSecuritySource,
   doctor,

package/llms.txt

@@ -1,6 +1,6 @@
 # @odla-ai/cli — LLM context
 
-> Agent-operable CLI for odla provisioning, System AI administration, commit-pinned GitHub security jobs, Worker secrets, and smoke checks.
+> Agent-operable CLI for odla provisioning, calendar consent and sync lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.
 
 > ⚠️ **Early access — pre-1.0.** Agents work from bounded runbooks; humans
 > approve credentials, production changes, releases, and merges. APIs and exact
@@ -10,7 +10,7 @@
 Project-neutral provisioning CLI for odla apps. It creates and validates an
 `odla.config.mjs`, then uses that config to register an app, enable services,
 push odla-db schema/rules, configure per-app BYOK AI, configure Clerk auth, record
-deployment links, provision o11y ingest credentials, and transfer local or
+deployment links, connect read-only Google Calendar mirrors, provision o11y ingest credentials, and transfer local or
 deployed Worker secrets without printing them. It also gives platform admins a
 scoped System AI control surface and gives app owners a provider-key-free
 hosted security command.
@@ -31,8 +31,8 @@ For a project you keep working in, install it as a dev dependency so the
 shorter `npx odla-ai` form works and the version is pinned by your lockfile:
 
 ```bash
-npm view @odla-ai/cli@0.9.0 version
-npm i -D --save-exact @odla-ai/cli@0.9.0
+npm view @odla-ai/cli@0.10.0 version
+npm i -D --save-exact @odla-ai/cli@0.10.0
 ```
 
 ## Prerequisites
@@ -55,6 +55,11 @@ npm i -D --save-exact @odla-ai/cli@0.9.0
 npx odla-ai setup
 npx odla-ai init --app-id my-app --name "My App"
 npx odla-ai doctor
+npx odla-ai calendar status --env dev
+npx odla-ai calendar calendars --env dev
+npx odla-ai calendar connect --env dev
+npx odla-ai calendar resync --env dev
+npx odla-ai calendar disconnect --env dev --yes
 npx odla-ai capabilities --json
 # install SDKs, write the Worker, and create wrangler.jsonc before secret push
 npx odla-ai provision --dry-run
@@ -105,14 +110,18 @@ shown-once credential.
    non-interactive shell, or `--no-open` to suppress it. Browser launch is
    best-effort; the printed URL and code always remain the fallback.
 2. Creates the platform app if needed.
-3. Enables configured services in every configured environment.
+3. Enables configured services in every configured environment. Calendar
+   intent is normalized per env and fixed to Google read-only access.
 4. Mints or reuses each env's configured service credentials: an odla-db app
    key for `db` and an ingest token for `o11y`.
 5. Pushes the configured schema and rules.
 6. Configures platform AI and stores provider keys in the tenant vault when the
    configured key env var is set.
-7. Writes `.odla/credentials.local.json` with mode `0600`.
-8. With `--write-dev-vars`, writes the local Worker values to `.dev.vars`; with
+7. With calendar enabled, starts a separate state-bound Google consent attempt
+   when needed and follows it through initial sync. The human completes OAuth;
+   codes and tokens never enter the CLI, repository, chat, or app.
+8. Writes `.odla/credentials.local.json` with mode `0600`.
+9. With `--write-dev-vars`, writes the local Worker values to `.dev.vars`; with
    `--push-secrets`, transfers the configured service secrets to the matching
    deployed Worker environment over Wrangler stdin.
 
@@ -135,6 +144,39 @@ odla-db schema with the tenant key, compares expected schema entities, and runs
 a count aggregate against the first entity. It fails early with a clear message
 when provisioning has not written `.odla/credentials.local.json`.
 
+### Read-only Google Calendar
+
+Calendar is a platform-custodied connector, not a Google credential stored by
+the application. Enable both `db` and `calendar`, configure calendar ids and an
+optional public Appointment Schedule `bookingPageUrl` per environment, then run
+normal provision. The first run has two human checkpoints: the odla device code
+establishes app-owner authority, then Google grants read-only Calendar scopes.
+
+`calendar status --json` returns the safe connection/sync projection.
+`calendar calendars --json` lists ids visible after consent; update checked-in
+config and re-provision. A resulting `needs_sync` state reuses the installed
+provider credential and resyncs without another OAuth attempt; an existing
+authorization or initial sync is awaited rather than duplicated. `calendar
+resync` requests an immediate sync, while
+`calendar disconnect --yes` stops watches and deletes this app/environment
+connection's encrypted platform token and cursors without purging retained
+mirror rows, which therefore become stale. It does not revoke the shared
+user-to-Google-OAuth-project grant, because that could invalidate other odla
+connections for the same user. A future explicitly global revoke command would
+need cross-connection accounting and warning. Production resync requires the
+CLI's explicit `--yes` checkpoint, and disconnect always requires it. None of
+these commands accepts a Google code, client secret, access token, or refresh
+token.
+
+The application uses its existing server-side `ODLA_ENDPOINT`, `ODLA_TENANT`,
+and `ODLA_API_KEY`; calendar adds no app Worker secret. Never expose the app key
+to a browser. Provider write actions are outside this read-only slice.
+
+These commands operate the current read/embed reconciliation slice. The CLI has
+no native slot-picker or create/reschedule/cancel command, and exposes no
+rolling-window/age-out, quota-backoff, retention/purge, or provider-derived
+mutation-id control. Public health remains aggregate rather than per calendar.
+
 The bundled build/migration skills add a passive pre-ship gate with
 `@odla-ai/security`: after the exact-version availability check, run
 `npm i -D --save-exact @odla-ai/security@0.2.2`, then
@@ -342,7 +384,7 @@ export default {
   dbEndpoint: process.env.ODLA_ENDPOINT ?? process.env.ODLA_DB_ENDPOINT ?? "https://db.odla.ai",
   app: { id: "my-app", name: "My App" },
   envs: ["dev"], // add "prod" deliberately; provisioning it requires --yes
-  services: ["db", "ai", "o11y"],
+  services: ["db", "ai", "o11y", "calendar"],
   db: {
     schema: "./src/odla/schema.mjs",
     rules: "./src/odla/rules.mjs",
@@ -353,6 +395,20 @@ export default {
     provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
     keyEnv: "ANTHROPIC_API_KEY",
   },
+  calendar: {
+    google: {
+      calendars: { dev: ["primary"] },
+      bookingPageUrl: {
+        dev: "https://calendar.google.com/calendar/appointments/schedules/…",
+      },
+      match: {
+        summaryPrefix: "Intro", // optional
+        organizerSelf: true,
+        requireAttendees: true,
+      },
+      attendeePolicy: "full", // or "hashed"
+    },
+  },
   auth: {
     // Publishable key (public). Created + pulled by the Clerk CLI (`npx clerk`);
     // See the installed odla-migrate phase 3. Inline `pk_…` or "$ENV_VAR".
@@ -375,7 +431,7 @@ If schema is present and rules are omitted, `defaultRules: "deny"` generates
 deny-all rules for every schema entity. That is the safe default for Workers
 that mediate reads and writes with an app key.
 
-## API reference (generated from dist/index.d.ts, v0.9.0)
+## API reference (generated from dist/index.d.ts, v0.10.0)
 
 ```ts
 import { SecurityReport, PlatformSecurityRun } from '@odla-ai/security';
@@ -471,79 +527,78 @@ declare function adminAi(options: AdminAiOptions): Promise<void>;
 /** Stable, machine-readable division of work between the CLI, coding agent,
  * human operator, and Studio. Printed by `odla-ai capabilities --json`. */
 declare const CAPABILITIES: {
-    readonly cli: readonly ["register the app and enable configured services per environment", "issue, persist, and explicitly rotate configured service credentials", "write local Worker values and push deployed Worker secrets through Wrangler stdin", "store tenant-vault secrets (including the Clerk webhook secret and reserved Clerk secret key) write-only from stdin or an env var", "push db schema/rules and configure platform AI, auth, and deployment links", "validate config offline and smoke-test a provisioned db environment", "run app-attributed hosted security discovery and independent validation without provider keys", "connect/revoke source-read-only GitHub sources and drive commit-pinned hosted security jobs without PATs or provider keys", "let admins manage system AI policy and credentials, inspect attributed usage, and read immutable admin changes through separate short-lived capability-only approvals"];
-    readonly agent: readonly ["install and import the selected odla SDKs", "wrap the Worker with withObservability and choose useful telemetry", "make application-specific schema, rules, auth, UI, and migration decisions"];
-    readonly human: readonly ["approve the odla device code and one-off third-party logins", "consent to production changes with --yes", "request destructive credential rotation explicitly", "review application semantics, security findings, releases, and merges", "approve redacted-source disclosure before hosted security reasoning", "approve GitHub App repository access separately from redacted-snippet disclosure"];
-    readonly studio: readonly ["view telemetry and environment state", "perform manual credential recovery when the CLI's local shown-once copy is unavailable", "configure system AI purposes and view app/environment/run-attributed usage", "connect/revoke GitHub security sources and inspect ref-to-SHA jobs, routes, retention, coverage, and normalized reports"];
+    readonly cli: readonly ["register the app and enable configured services per environment", "issue, persist, and explicitly rotate configured service credentials", "write local Worker values and push deployed Worker secrets through Wrangler stdin", "store tenant-vault secrets (including the Clerk webhook secret and reserved Clerk secret key) write-only from stdin or an env var", "push db schema/rules and configure platform AI, auth, and deployment links", "apply read-only Google calendar mirror and public booking-page config, then drive state-bound consent, status, discovery, resync, and disconnect flows", "validate config offline and smoke-test a provisioned db environment", "run app-attributed hosted security discovery and independent validation without provider keys", "connect/revoke source-read-only GitHub sources and drive commit-pinned hosted security jobs without PATs or provider keys", "let admins manage system AI policy and credentials, inspect attributed usage, and read immutable admin changes through separate short-lived capability-only approvals"];
+    readonly agent: readonly ["install and import the selected odla SDKs", "wrap the Worker with withObservability and choose useful telemetry", "make application-specific schema, rules, auth, UI, and migration decisions", "wire @odla-ai/calendar into trusted Worker code and keep the app admin key out of browsers"];
+    readonly human: readonly ["approve the odla device code and one-off third-party logins", "review mirrored calendar/attendee disclosure and complete the server-issued Google consent flow", "consent to production changes with --yes", "request destructive credential rotation explicitly", "review application semantics, security findings, releases, and merges", "approve redacted-source disclosure before hosted security reasoning", "approve GitHub App repository access separately from redacted-snippet disclosure"];
+    readonly studio: readonly ["view telemetry and environment state", "review calendar connection, granted read scope, selected calendars, and sync health without exposing provider tokens", "perform manual credential recovery when the CLI's local shown-once copy is unavailable", "configure system AI purposes and view app/environment/run-attributed usage", "connect/revoke GitHub security sources and inspect ref-to-SHA jobs, routes, retention, coverage, and normalized reports"];
 };
 type Output = Pick<typeof console, "log">;
 /** Print the stable responsibility boundary for humans or agent tooling. */
 declare function printCapabilities(json?: boolean, out?: Output): void;
 
-interface DoctorOptions {
-    configPath: string;
-    stdout?: Pick<typeof console, "log" | "error">;
+declare const CALENDAR_STATES: readonly ["not_connected", "authorizing", "needs_sync", "initial_sync", "healthy", "degraded", "disconnected", "failed"];
+type CalendarConnectionState = (typeof CALENDAR_STATES)[number];
+/** Owner-visible, secret-free calendar connection and sync health. */
+interface CalendarStatus {
+    env: string;
+    enabled: boolean;
+    /** True when the platform has provider credentials for this connection. */
+    connected: boolean;
+    provider: "google" | null;
+    status: CalendarConnectionState;
+    access?: "read";
+    calendars: string[];
+    attendeePolicy?: "full" | "hashed";
+    /** True once a booking projection may have established the DB privacy policy. */
+    attendeePolicyLocked?: boolean;
+    bookingPageUrl?: string | null;
+    grantedScopes: string[];
+    attemptId?: string;
+    lastSuccessfulSyncAt?: number;
+    lastFullSyncAt?: number;
+    watchExpiresAt?: number;
+    bookingCount?: number;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/** One Google calendar the connected identity may select for mirroring. */
+interface AvailableGoogleCalendar {
+    id: string;
+    summary?: string;
+    primary?: boolean;
+    selected?: boolean;
+    accessRole?: "freeBusyReader" | "reader" | "writer" | "owner";
 }
-/**
- * Validate and summarize an odla project config entirely offline — no network
- * calls and no file writes. Loads `configPath`, builds the provision plan, and
- * resolves the schema and rules (synthesizing deny-all rules from the schema
- * when `db.rules` is omitted and `db.defaultRules` isn't `false`), then prints a
- * summary line for the app, envs, services, schema entity count, rules namespace
- * count, and AI provider.
- *
- * It then collects warnings for the mistakes provision can't fix silently: a
- * schema with no entities, a rules namespace with no matching entity, the `ai`
- * service enabled without an `ai.provider`, `auth.clerk` entries that reference
- * an unset env var (`$FOO`), an `ai.keyEnv` that isn't set (provider key upload
- * will be skipped), and — when `o11y` is enabled — any env whose local
- * credentials lack an ingest token. It also folds in the shared rule linter,
- * git-tracked secret-shaped files, and wrangler config warnings. Prints `ok`
- * when clean, otherwise the warning list. Purely advisory: never throws on
- * warnings and never mutates anything.
- *
- * @param options.configPath Path to the `odla.config.mjs` to inspect.
- * @param options.stdout Optional console-like sink (defaults to `console`).
- */
-declare function doctor(options: DoctorOptions): Promise<void>;
 
-interface InitOptions {
-    rootDir?: string;
-    configPath?: string;
-    appId: string;
-    name: string;
-    envs?: string[];
-    services?: string[];
-    aiProvider?: string;
-    force?: boolean;
+interface CalendarLifecycleOptions {
+    configPath: string;
+    env?: string;
+    token?: string;
+    open?: boolean;
+    interactive?: boolean;
+    yes?: boolean;
+    json?: boolean;
+    fetch?: typeof fetch;
     stdout?: Pick<typeof console, "log" | "error">;
+    openConsentUrl?: (url: string) => Promise<void>;
+    wait?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    pollTimeoutMs?: number;
+    now?: () => number;
+    signal?: AbortSignal;
 }
-/**
- * Scaffold a new odla project into `rootDir` (default: cwd). Writes an
- * `odla.config.mjs` (default name, overridable via `configPath`) plus starter
- * `src/odla/schema.mjs` (a single `notes` entity) and `src/odla/rules.mjs`
- * (deny-all), and creates the `src/odla` and `.odla` directories. Also runs
- * `ensureGitignore` so the local token/credentials paths are ignored.
- *
- * Fully local and synchronous — no network calls. The config file is only
- * written when it doesn't already exist unless `force` is set (otherwise it
- * throws); the schema/rules files are written only when missing (never
- * overwritten, even with `force`). `appId` must match `^[a-z0-9][a-z0-9-]*$` or
- * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`,
- * `aiProvider` → `"anthropic"` (which also picks the `keyEnv`, e.g.
- * `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`/`GOOGLE_API_KEY`).
- *
- * @param options.appId Slug for the app (lowercase alphanumerics and hyphens).
- * @param options.name Human-readable app name embedded in the config.
- * @param options.rootDir Project root (defaults to `process.cwd()`).
- * @param options.configPath Config filename relative to root (default `odla.config.mjs`).
- * @param options.envs Environment names (default `["dev"]`; production is an explicit opt-in).
- * @param options.services Enabled services (default `["db","ai"]`).
- * @param options.aiProvider AI provider slug (default `"anthropic"`).
- * @param options.force Overwrite an existing config file instead of throwing.
- * @param options.stdout Optional console-like sink (defaults to `console`).
- */
-declare function initProject(options: InitOptions): void;
+/** Read the owner-visible Google connection and mirror health for one env. */
+declare function calendarStatus(options: CalendarLifecycleOptions): Promise<CalendarStatus>;
+/** List calendars visible to the connected Google identity for config authoring. */
+declare function calendarCalendars(options: CalendarLifecycleOptions): Promise<AvailableGoogleCalendar[]>;
+/** Apply the public booking page setting, then complete Google consent + initial sync. */
+declare function calendarConnect(options: CalendarLifecycleOptions): Promise<CalendarStatus>;
+/** Ask the hosted connector for an immediate incremental/full recovery sync. */
+declare function calendarResync(options: CalendarLifecycleOptions): Promise<CalendarStatus>;
+/** Stop watches and delete this connection's encrypted platform token/cursors
+ * without purging the mirror or revoking the shared Google project grant. */
+declare function calendarDisconnect(options: CalendarLifecycleOptions): Promise<CalendarStatus>;
 
 interface RunResult {
     code: number;
@@ -568,6 +623,41 @@ interface ClerkAuthConfig {
     audience?: string;
     mode?: "client" | "full";
 }
+/** Read-only event selection applied by the hosted Google calendar connector. */
+interface GoogleCalendarMatchConfig {
+    /** Mirror only events whose summary begins with this value. */
+    summaryPrefix?: string;
+    /** Require the connected identity to organize the event. Defaults to true. */
+    organizerSelf?: boolean;
+    /** Require at least one attendee. Defaults to true. */
+    requireAttendees?: boolean;
+}
+/** Google Calendar intent. OAuth credentials never belong in this config. */
+interface GoogleCalendarConfig {
+    /** One through ten provider calendar ids to mirror in each odla environment. */
+    calendars: Record<OdlaEnvName, string[]>;
+    /** Public Google Appointment Schedule URL for static embed/link mode. */
+    bookingPageUrl?: Record<OdlaEnvName, string | null>;
+    match?: GoogleCalendarMatchConfig;
+    /** Store normalized attendee addresses, or only SHA-256 match keys. */
+    attendeePolicy?: "full" | "hashed";
+}
+interface CalendarConfig {
+    google: GoogleCalendarConfig;
+}
+/** Canonical, environment-specific config sent to the calendar controller. */
+interface CalendarServiceConfig extends Record<string, unknown> {
+    provider: "google";
+    access: "read";
+    /** Deduplicated provider ids; the hosted connector accepts at most ten. */
+    calendars: string[];
+    match: {
+        organizerSelf: boolean;
+        requireAttendees: boolean;
+        summaryPrefix?: string;
+    };
+    attendeePolicy: "full" | "hashed";
+}
 /** Authored `odla.config.mjs` contract consumed by doctor and provision. */
 interface OdlaProjectConfig {
     platformUrl?: string;
@@ -596,6 +686,7 @@ interface OdlaProjectConfig {
         /** Vault secret name. Defaults to @odla-ai/ai's provider default. */
         secretName?: string;
     };
+    calendar?: CalendarConfig;
     o11y?: {
         /** This service's name in the collector. Defaults to the app id. */
         service?: string;
@@ -660,6 +751,10 @@ interface ProvisionOptions {
     interactive?: boolean;
     /** Test/embedding override for opening the approval URL. Defaults to the OS browser opener. */
     openApprovalUrl?: (url: string) => Promise<void>;
+    /** Test/embedding override for calendar connection polling. */
+    calendarPollWait?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    /** Maximum calendar consent + initial-sync wait. Defaults to ten minutes. */
+    calendarPollTimeoutMs?: number;
     /** Explicit consent for a non-dry-run plan containing `prod` or `production`. */
     yes?: boolean;
     fetch?: typeof fetch;
@@ -683,10 +778,86 @@ interface ProvisionPlan {
 interface SmokeOptions {
     configPath: string;
     env?: string;
+    /** Developer-token override used only for owner-visible calendar health. */
+    token?: string;
+    open?: boolean;
+    interactive?: boolean;
+    openApprovalUrl?: (url: string) => Promise<void>;
     fetch?: typeof fetch;
     stdout?: Pick<typeof console, "log" | "error">;
 }
 
+declare const GOOGLE_CALENDAR_READ_SCOPE = "https://www.googleapis.com/auth/calendar.events.readonly";
+/** Resolve the checked-in calendar block into one controller-safe env payload. */
+declare function calendarServiceConfig(cfg: LoadedProjectConfig, env: string): CalendarServiceConfig;
+/** Public Appointment Schedule URL to apply separately from connector config. */
+declare function calendarBookingPageUrl(cfg: LoadedProjectConfig, env: string): string | null | undefined;
+
+interface DoctorOptions {
+    configPath: string;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+/**
+ * Validate and summarize an odla project config entirely offline — no network
+ * calls and no file writes. Loads `configPath`, builds the provision plan, and
+ * resolves the schema and rules (synthesizing deny-all rules from the schema
+ * when `db.rules` is omitted and `db.defaultRules` isn't `false`), then prints a
+ * summary line for the app, envs, services, schema entity count, rules namespace
+ * count, and AI provider.
+ *
+ * It then collects warnings for the mistakes provision can't fix silently: a
+ * schema with no entities, a rules namespace with no matching entity, the `ai`
+ * service enabled without an `ai.provider`, `auth.clerk` entries that reference
+ * an unset env var (`$FOO`), an `ai.keyEnv` that isn't set (provider key upload
+ * will be skipped), and — when `o11y` is enabled — any env whose local
+ * credentials lack an ingest token. It also folds in the shared rule linter,
+ * git-tracked secret-shaped files, and wrangler config warnings. Prints `ok`
+ * when clean, otherwise the warning list. Purely advisory: never throws on
+ * warnings and never mutates anything.
+ *
+ * @param options.configPath Path to the `odla.config.mjs` to inspect.
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
+declare function doctor(options: DoctorOptions): Promise<void>;
+
+interface InitOptions {
+    rootDir?: string;
+    configPath?: string;
+    appId: string;
+    name: string;
+    envs?: string[];
+    services?: string[];
+    aiProvider?: string;
+    force?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+/**
+ * Scaffold a new odla project into `rootDir` (default: cwd). Writes an
+ * `odla.config.mjs` (default name, overridable via `configPath`) plus starter
+ * `src/odla/schema.mjs` (a single `notes` entity) and `src/odla/rules.mjs`
+ * (deny-all), and creates the `src/odla` and `.odla` directories. Also runs
+ * `ensureGitignore` so the local token/credentials paths are ignored.
+ *
+ * Fully local and synchronous — no network calls. The config file is only
+ * written when it doesn't already exist unless `force` is set (otherwise it
+ * throws); the schema/rules files are written only when missing (never
+ * overwritten, even with `force`). `appId` must match `^[a-z0-9][a-z0-9-]*$` or
+ * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`,
+ * `aiProvider` → `"anthropic"` (which also picks the `keyEnv`, e.g.
+ * `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`/`GOOGLE_API_KEY`).
+ *
+ * @param options.appId Slug for the app (lowercase alphanumerics and hyphens).
+ * @param options.name Human-readable app name embedded in the config.
+ * @param options.rootDir Project root (defaults to `process.cwd()`).
+ * @param options.configPath Config filename relative to root (default `odla.config.mjs`).
+ * @param options.envs Environment names (default `["dev"]`; production is an explicit opt-in).
+ * @param options.services Enabled services (default `["db","ai"]`).
+ * @param options.aiProvider AI provider slug (default `"anthropic"`).
+ * @param options.force Overwrite an existing config file instead of throwing.
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
+declare function initProject(options: InitOptions): void;
+
 /**
  * Provision an app end-to-end from its config — the primary deploy path, and
  * (apart from key rotation) idempotent, so re-running is safe. Obtains a
@@ -1046,5 +1217,5 @@ declare function installSkill(options?: SkillInstallOptions): SkillInstallResult
  */
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-export { AGENT_HARNESSES, type AdminAiOptions, type AgentHarness, type AgentHarnessSelector, CAPABILITIES, type CliDependencies, type ConnectGitHubSecuritySourceOptions, type DisconnectGitHubSecuritySourceOptions, type FollowHostedSecurityJobOptions, type GetHostedSecurityIntentOptions, type GetHostedSecurityJobOptions, type HarnessInstallResult, type HostedSecurityProfile, type HostedSecurityResult, type HostedSecurityTokenRequest, type ListGitHubSecuritySourcesOptions, type ListHostedSecurityJobsOptions, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type RunHostedSecurityOptions, SYSTEM_AI_PURPOSES, type ScopedPlatformTokenOptions, type SecretsPushOptions, type SecretsSetOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, type StartHostedSecurityJobOptions, type SystemAiPurpose, adminAi, connectGitHubSecuritySource, disconnectGitHubSecuritySource, doctor, followHostedSecurityJob, getHostedSecurityIntent, getHostedSecurityJob, getHostedSecurityPlan, getHostedSecurityReport, getScopedPlatformToken, inferGitHubRepository, initProject, installSkill, isTerminalHostedSecurityStatus, listGitHubSecuritySources, listHostedSecurityJobs, printCapabilities, provision, redactSecrets, repositoryFromGitRemote, runCli, runHostedSecurity, secretsPush, secretsSet, secretsSetClerkKey, smoke, startHostedSecurityJob };
+export { AGENT_HARNESSES, type AdminAiOptions, type AgentHarness, type AgentHarnessSelector, type AvailableGoogleCalendar, CAPABILITIES, type CalendarConfig, type CalendarConnectionState, type CalendarLifecycleOptions, type CalendarServiceConfig, type CalendarStatus, type CliDependencies, type ConnectGitHubSecuritySourceOptions, type DisconnectGitHubSecuritySourceOptions, type FollowHostedSecurityJobOptions, GOOGLE_CALENDAR_READ_SCOPE, type GetHostedSecurityIntentOptions, type GetHostedSecurityJobOptions, type GoogleCalendarConfig, type GoogleCalendarMatchConfig, type HarnessInstallResult, type HostedSecurityProfile, type HostedSecurityResult, type HostedSecurityTokenRequest, type ListGitHubSecuritySourcesOptions, type ListHostedSecurityJobsOptions, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type RunHostedSecurityOptions, SYSTEM_AI_PURPOSES, type ScopedPlatformTokenOptions, type SecretsPushOptions, type SecretsSetOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, type StartHostedSecurityJobOptions, type SystemAiPurpose, adminAi, calendarBookingPageUrl, calendarCalendars, calendarConnect, calendarDisconnect, calendarResync, calendarServiceConfig, calendarStatus, connectGitHubSecuritySource, disconnectGitHubSecuritySource, doctor, followHostedSecurityJob, getHostedSecurityIntent, getHostedSecurityJob, getHostedSecurityPlan, getHostedSecurityReport, getScopedPlatformToken, inferGitHubRepository, initProject, installSkill, isTerminalHostedSecurityStatus, listGitHubSecuritySources, listHostedSecurityJobs, printCapabilities, provision, redactSecrets, repositoryFromGitRemote, runCli, runHostedSecurity, secretsPush, secretsSet, secretsSetClerkKey, smoke, startHostedSecurityJob };
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.9.0",
-  "description": "Agent-operable CLI for odla provisioning, System AI administration, commit-pinned GitHub security jobs, Worker secrets, and smoke checks.",
+  "version": "0.10.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",
   "repository": {
@@ -60,7 +60,7 @@
   },
   "dependencies": {
     "@odla-ai/ai": "^0.3.3",
-    "@odla-ai/apps": "^0.7.1",
+    "@odla-ai/apps": "^0.8.0",
     "@odla-ai/db": "^0.6.2",
     "@odla-ai/security": "^0.2.2"
   },

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.
 
@@ -48,6 +48,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
 
@@ -67,7 +70,9 @@ guessing which platform/credential steps need manual work. Then:
    prints; the human approves it at https://odla.ai/studio. 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 +93,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
@@ -43,6 +50,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 +75,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