@odla-ai/cli 0.11.1 → 0.12.0

package/dist/index.d.cts

@@ -2,6 +2,10 @@ import { SecurityReport, PlatformSecurityRun } from '@odla-ai/security';
 import { HostedSecurityJob, GitHubConnectionStatus, GitHubSecuritySource, HostedSecurityIntentResponse, HostedSecurityPlan, HostedSecurityReport, HostedSecurityJobStatus } from '@odla-ai/security/hosted';
 export { GitHubConnectionAttempt, GitHubConnectionStatus, GitHubSecuritySource, HostedSecurityCounts, HostedSecurityCoverage, HostedSecurityIntent, HostedSecurityIntentResponse, HostedSecurityJob, HostedSecurityJobStatus, HostedSecurityPlan, HostedSecurityPlanRoute, HostedSecurityReport, HostedSecurityReportFinding, HostedSecurityRoute } from '@odla-ai/security/hosted';
 
+/** Map a CLI failure to its process exit code: 75 (EX_TEMPFAIL) marks a
+ * handshake that is still awaiting human approval — the pending state is
+ * persisted and rerunning the same command resumes it — everything else is 1. */
+declare function exitCodeFor(err: unknown): number;
 /** Injectable side-effect boundaries used to run and test the command dispatcher. */
 interface CliDependencies {
     fetch?: typeof fetch;
@@ -95,7 +99,7 @@ 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 ["start an email-bound device request without accepting a password or user session token", "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 cli: readonly ["start an email-bound device request without accepting a password or user session token", "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 Google Calendar booking config, then drive state-bound consent, status, discovery, and disconnect flows (bookings run live through the platform proxy)", "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 ["provide the existing odla account email, then sign in and explicitly review/approve the exact device code", "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", "let signed-in users inventory/revoke their own agent grants and admins audit/global-revoke them", "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"];
@@ -104,29 +108,28 @@ type Output = Pick<typeof console, "log">;
 /** Print the stable responsibility boundary for humans or agent tooling. */
 declare function printCapabilities(json?: boolean, out?: Output): void;
 
-declare const CALENDAR_STATES: readonly ["not_connected", "authorizing", "needs_sync", "initial_sync", "healthy", "degraded", "disconnected", "failed"];
-/** Connection lifecycle reported by the registry; mirrors the platform's calendar states. */
+declare const CALENDAR_STATES: readonly ["not_connected", "authorizing", "healthy", "degraded", "disconnected", "failed"];
+/** Connection lifecycle reported by the registry; mirrors the platform's
+ * calendar states. `degraded` means connected but re-consent is required. */
 type CalendarConnectionState = (typeof CALENDAR_STATES)[number];
-/** Owner-visible, secret-free calendar connection and sync health. */
+/** Owner-visible, secret-free calendar connection health. */
 interface CalendarStatus {
     env: string;
     enabled: boolean;
     /** True when the platform has provider credentials for this connection. */
     connected: boolean;
+    /** True when the grant covers booking writes; false means reconnect. */
+    writable: boolean;
     provider: "google" | null;
     status: CalendarConnectionState;
-    access?: "read";
+    access?: "book";
+    /** Calendar that receives created bookings. */
+    bookingCalendarId?: string;
+    /** Calendars consulted for FreeBusy availability. */
     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;
@@ -142,9 +145,9 @@ interface AvailableGoogleCalendar {
 }
 
 /** Shared inputs for the calendar lifecycle commands (status, connect,
- * calendars, resync, disconnect): the project config path and env, plus
- * injectable token, output, browser, clock, and polling hooks so agents and
- * tests can drive the flow deterministically. */
+ * calendars, disconnect): the project config path and env, plus injectable
+ * token, output, browser, clock, and polling hooks so agents and tests can
+ * drive the flow deterministically. */
 interface CalendarLifecycleOptions {
     /** Path to the checked-in odla project config. */ configPath: string;
     /** Configured environment; defaults to dev when present. */ env?: string;
@@ -161,16 +164,17 @@ interface CalendarLifecycleOptions {
     now?: () => number;
     signal?: AbortSignal;
 }
-/** Read the owner-visible Google connection and mirror health for one env. */
+/** Read the owner-visible Google connection and booking 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. */
+/** Apply the optional booking-page setting, then complete Google consent.
+ * A connection whose grant predates booking scopes (`degraded`) re-runs
+ * consent so the platform can create events and read FreeBusy. */
 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. */
+/** Delete this connection's encrypted platform tokens. No calendar data is
+ * stored anywhere, so there is nothing else to clean up; the shared Google
+ * project grant is not revoked. */
 declare function calendarDisconnect(options: CalendarLifecycleOptions): Promise<CalendarStatus>;
 
 interface RunResult {
@@ -196,42 +200,32 @@ 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. */
+/** Google Calendar booking intent. OAuth credentials never belong in this
+ * config, and no calendar data is mirrored — Google is the source of truth. */
 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. */
+    /** One through ten calendars consulted for availability in each env. */
+    availabilityCalendars?: Record<OdlaEnvName, string[]>;
+    /** Retired read-mirror spelling of `availabilityCalendars` (still accepted). */
+    calendars?: Record<OdlaEnvName, string[]>;
+    /** Calendar that receives created bookings per env ("primary" or a concrete
+     * id). Defaults to the first availability calendar. */
+    bookingCalendar?: Record<OdlaEnvName, string>;
+    /** Optional public fallback link (retiring; first-party booking replaces it). */
     bookingPageUrl?: Record<OdlaEnvName, string | null>;
-    match?: GoogleCalendarMatchConfig;
-    /** Store normalized attendee addresses, or only SHA-256 match keys. */
-    attendeePolicy?: "full" | "hashed";
 }
-/** The `calendar` block of `odla.config.mjs` — the Google read-mirror
- * settings; valid only alongside the db service. */
+/** The `calendar` block of `odla.config.mjs` — the Google booking settings;
+ * valid only alongside the db service (booking rides the app's db key). */
 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";
+    access: "book";
+    /** Calendar that receives created bookings. */
+    bookingCalendarId: string;
+    /** Deduplicated provider ids; the booking proxy accepts at most ten. */
+    availabilityCalendars: string[];
 }
 /** Authored `odla.config.mjs` contract consumed by doctor and provision. */
 interface OdlaProjectConfig {
@@ -325,6 +319,11 @@ interface ProvisionOptions {
     /** true forces browser launch, false disables it, undefined auto-opens whenever
      * this machine can show a browser (skipped in CI, over SSH, or with no display). */
     open?: boolean;
+    /** Cap the handshake-approval wait, in seconds. When it elapses the command
+     * exits with the pending handshake persisted; rerunning resumes it. Defaults
+     * to the handshake's own expiry on an interactive terminal and 90 seconds
+     * everywhere else (agent tool shells kill long-running commands). */
+    wait?: number;
     /** 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. */
@@ -364,8 +363,8 @@ interface SmokeOptions {
     stdout?: Pick<typeof console, "log" | "error">;
 }
 
-/** The only Google OAuth scope the platform ever requests: read-only calendar events. */
-declare const GOOGLE_CALENDAR_READ_SCOPE = "https://www.googleapis.com/auth/calendar.events.readonly";
+/** The Google OAuth scope that authorizes booking writes (events read/write). */
+declare const GOOGLE_CALENDAR_EVENTS_SCOPE = "https://www.googleapis.com/auth/calendar.events";
 /** 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. */
@@ -803,4 +802,4 @@ declare function installSkill(options?: SkillInstallOptions): SkillInstallResult
  */
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-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 };
+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_EVENTS_SCOPE, type GetHostedSecurityIntentOptions, type GetHostedSecurityJobOptions, type GoogleCalendarConfig, 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, calendarServiceConfig, calendarStatus, connectGitHubSecuritySource, disconnectGitHubSecuritySource, doctor, exitCodeFor, followHostedSecurityJob, getHostedSecurityIntent, getHostedSecurityJob, getHostedSecurityPlan, getHostedSecurityReport, getScopedPlatformToken, inferGitHubRepository, initProject, installSkill, isTerminalHostedSecurityStatus, listGitHubSecuritySources, listHostedSecurityJobs, printCapabilities, provision, redactSecrets, repositoryFromGitRemote, runCli, runHostedSecurity, secretsPush, secretsSet, secretsSetClerkKey, smoke, startHostedSecurityJob };

package/dist/index.d.ts

@@ -2,6 +2,10 @@ import { SecurityReport, PlatformSecurityRun } from '@odla-ai/security';
 import { HostedSecurityJob, GitHubConnectionStatus, GitHubSecuritySource, HostedSecurityIntentResponse, HostedSecurityPlan, HostedSecurityReport, HostedSecurityJobStatus } from '@odla-ai/security/hosted';
 export { GitHubConnectionAttempt, GitHubConnectionStatus, GitHubSecuritySource, HostedSecurityCounts, HostedSecurityCoverage, HostedSecurityIntent, HostedSecurityIntentResponse, HostedSecurityJob, HostedSecurityJobStatus, HostedSecurityPlan, HostedSecurityPlanRoute, HostedSecurityReport, HostedSecurityReportFinding, HostedSecurityRoute } from '@odla-ai/security/hosted';
 
+/** Map a CLI failure to its process exit code: 75 (EX_TEMPFAIL) marks a
+ * handshake that is still awaiting human approval — the pending state is
+ * persisted and rerunning the same command resumes it — everything else is 1. */
+declare function exitCodeFor(err: unknown): number;
 /** Injectable side-effect boundaries used to run and test the command dispatcher. */
 interface CliDependencies {
     fetch?: typeof fetch;
@@ -95,7 +99,7 @@ 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 ["start an email-bound device request without accepting a password or user session token", "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 cli: readonly ["start an email-bound device request without accepting a password or user session token", "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 Google Calendar booking config, then drive state-bound consent, status, discovery, and disconnect flows (bookings run live through the platform proxy)", "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 ["provide the existing odla account email, then sign in and explicitly review/approve the exact device code", "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", "let signed-in users inventory/revoke their own agent grants and admins audit/global-revoke them", "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"];
@@ -104,29 +108,28 @@ type Output = Pick<typeof console, "log">;
 /** Print the stable responsibility boundary for humans or agent tooling. */
 declare function printCapabilities(json?: boolean, out?: Output): void;
 
-declare const CALENDAR_STATES: readonly ["not_connected", "authorizing", "needs_sync", "initial_sync", "healthy", "degraded", "disconnected", "failed"];
-/** Connection lifecycle reported by the registry; mirrors the platform's calendar states. */
+declare const CALENDAR_STATES: readonly ["not_connected", "authorizing", "healthy", "degraded", "disconnected", "failed"];
+/** Connection lifecycle reported by the registry; mirrors the platform's
+ * calendar states. `degraded` means connected but re-consent is required. */
 type CalendarConnectionState = (typeof CALENDAR_STATES)[number];
-/** Owner-visible, secret-free calendar connection and sync health. */
+/** Owner-visible, secret-free calendar connection health. */
 interface CalendarStatus {
     env: string;
     enabled: boolean;
     /** True when the platform has provider credentials for this connection. */
     connected: boolean;
+    /** True when the grant covers booking writes; false means reconnect. */
+    writable: boolean;
     provider: "google" | null;
     status: CalendarConnectionState;
-    access?: "read";
+    access?: "book";
+    /** Calendar that receives created bookings. */
+    bookingCalendarId?: string;
+    /** Calendars consulted for FreeBusy availability. */
     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;
@@ -142,9 +145,9 @@ interface AvailableGoogleCalendar {
 }
 
 /** Shared inputs for the calendar lifecycle commands (status, connect,
- * calendars, resync, disconnect): the project config path and env, plus
- * injectable token, output, browser, clock, and polling hooks so agents and
- * tests can drive the flow deterministically. */
+ * calendars, disconnect): the project config path and env, plus injectable
+ * token, output, browser, clock, and polling hooks so agents and tests can
+ * drive the flow deterministically. */
 interface CalendarLifecycleOptions {
     /** Path to the checked-in odla project config. */ configPath: string;
     /** Configured environment; defaults to dev when present. */ env?: string;
@@ -161,16 +164,17 @@ interface CalendarLifecycleOptions {
     now?: () => number;
     signal?: AbortSignal;
 }
-/** Read the owner-visible Google connection and mirror health for one env. */
+/** Read the owner-visible Google connection and booking 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. */
+/** Apply the optional booking-page setting, then complete Google consent.
+ * A connection whose grant predates booking scopes (`degraded`) re-runs
+ * consent so the platform can create events and read FreeBusy. */
 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. */
+/** Delete this connection's encrypted platform tokens. No calendar data is
+ * stored anywhere, so there is nothing else to clean up; the shared Google
+ * project grant is not revoked. */
 declare function calendarDisconnect(options: CalendarLifecycleOptions): Promise<CalendarStatus>;
 
 interface RunResult {
@@ -196,42 +200,32 @@ 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. */
+/** Google Calendar booking intent. OAuth credentials never belong in this
+ * config, and no calendar data is mirrored — Google is the source of truth. */
 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. */
+    /** One through ten calendars consulted for availability in each env. */
+    availabilityCalendars?: Record<OdlaEnvName, string[]>;
+    /** Retired read-mirror spelling of `availabilityCalendars` (still accepted). */
+    calendars?: Record<OdlaEnvName, string[]>;
+    /** Calendar that receives created bookings per env ("primary" or a concrete
+     * id). Defaults to the first availability calendar. */
+    bookingCalendar?: Record<OdlaEnvName, string>;
+    /** Optional public fallback link (retiring; first-party booking replaces it). */
     bookingPageUrl?: Record<OdlaEnvName, string | null>;
-    match?: GoogleCalendarMatchConfig;
-    /** Store normalized attendee addresses, or only SHA-256 match keys. */
-    attendeePolicy?: "full" | "hashed";
 }
-/** The `calendar` block of `odla.config.mjs` — the Google read-mirror
- * settings; valid only alongside the db service. */
+/** The `calendar` block of `odla.config.mjs` — the Google booking settings;
+ * valid only alongside the db service (booking rides the app's db key). */
 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";
+    access: "book";
+    /** Calendar that receives created bookings. */
+    bookingCalendarId: string;
+    /** Deduplicated provider ids; the booking proxy accepts at most ten. */
+    availabilityCalendars: string[];
 }
 /** Authored `odla.config.mjs` contract consumed by doctor and provision. */
 interface OdlaProjectConfig {
@@ -325,6 +319,11 @@ interface ProvisionOptions {
     /** true forces browser launch, false disables it, undefined auto-opens whenever
      * this machine can show a browser (skipped in CI, over SSH, or with no display). */
     open?: boolean;
+    /** Cap the handshake-approval wait, in seconds. When it elapses the command
+     * exits with the pending handshake persisted; rerunning resumes it. Defaults
+     * to the handshake's own expiry on an interactive terminal and 90 seconds
+     * everywhere else (agent tool shells kill long-running commands). */
+    wait?: number;
     /** 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. */
@@ -364,8 +363,8 @@ interface SmokeOptions {
     stdout?: Pick<typeof console, "log" | "error">;
 }
 
-/** The only Google OAuth scope the platform ever requests: read-only calendar events. */
-declare const GOOGLE_CALENDAR_READ_SCOPE = "https://www.googleapis.com/auth/calendar.events.readonly";
+/** The Google OAuth scope that authorizes booking writes (events read/write). */
+declare const GOOGLE_CALENDAR_EVENTS_SCOPE = "https://www.googleapis.com/auth/calendar.events";
 /** 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. */
@@ -803,4 +802,4 @@ declare function installSkill(options?: SkillInstallOptions): SkillInstallResult
  */
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-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 };
+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_EVENTS_SCOPE, type GetHostedSecurityIntentOptions, type GetHostedSecurityJobOptions, type GoogleCalendarConfig, 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, calendarServiceConfig, calendarStatus, connectGitHubSecuritySource, disconnectGitHubSecuritySource, doctor, exitCodeFor, followHostedSecurityJob, getHostedSecurityIntent, getHostedSecurityJob, getHostedSecurityPlan, getHostedSecurityReport, getScopedPlatformToken, inferGitHubRepository, initProject, installSkill, isTerminalHostedSecurityStatus, listGitHubSecuritySources, listHostedSecurityJobs, printCapabilities, provision, redactSecrets, repositoryFromGitRemote, runCli, runHostedSecurity, secretsPush, secretsSet, secretsSetClerkKey, smoke, startHostedSecurityJob };

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-Y4HWUEFF.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.1",
+  "version": "0.12.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,30 @@ 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
+
+- **odla**: this skill plus the installed `@odla-ai/*` packages are the
+  complete, offline contract (README + exported declarations/JSDoc, rendered
+  at `https://odla.ai/docs/packages/<pkg>`). Never reconstruct odla behavior
+  from the web or training memory.
+- **Third-party tools (wrangler, Clerk) — the reverse**: their CLIs and config
+  formats evolve, so never work from memorized setup steps. When you reach a
+  wrangler or Clerk step, fetch the vendor's current agent docs and follow
+  those:
+  - Cloudflare: docs index `https://developers.cloudflare.com/llms.txt`; every
+    docs page has a markdown twin at `<page>/index.md` (wrangler config:
+    `https://developers.cloudflare.com/workers/wrangler/configuration/index.md`).
+    With the human's OK (it edits global agent config), you may also follow
+    `https://developers.cloudflare.com/agent-setup/prompt.md` to add
+    Cloudflare's own skills + MCP servers to your harness.
+  - Clerk: agent-first CLI setup `https://clerk.com/docs/cli.md`; docs index
+    `https://clerk.com/docs/llms.txt`.
+
+  Offline? Say so, continue with the vendor steps written in these references,
+  and flag that they may be stale.
 
 ## The flow
 
@@ -72,12 +95,18 @@ 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
    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
@@ -98,10 +127,11 @@ 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

package/skills/odla/references/build.md

@@ -15,25 +15,29 @@ 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 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
 
 `npm i` only the SDKs you need and use the local `references/sdks.md` as the
-integration map. Create the Worker entrypoint and `wrangler.jsonc` before any
-deployed-secret transfer. With o11y, install `@odla-ai/o11y`, add
-`"nodejs_compat"` to `compatibility_flags`, and wrap the entrypoint with
-`withObservability`.
+integration map. `npm i -D wrangler` so the project pins its own copy instead
+of relying on an implicit `npx` fetch. Create the Worker entrypoint and
+`wrangler.jsonc` before any deployed-secret transfer — take the current config
+syntax from Cloudflare's live docs (SKILL.md "Tooling sources"), not memory.
+With o11y, install `@odla-ai/o11y`, add `"nodejs_compat"` to
+`compatibility_flags`, and wrap the entrypoint with `withObservability`.
 
 Each installed package's README and exported TypeScript declarations/JSDoc are
 the version-matched API contract; resolve public entry points through its
-`package.json` `exports`. The npm artifacts contain everything required for
-this flow; private service source or online documentation is not setup context.
+`package.json` `exports`. For everything odla, the npm artifacts contain the
+whole setup context — private service source or web documentation is never
+required. Third-party tooling (wrangler, Clerk) is the reverse: use the live
+vendor docs, never memorized steps.
 
 ## 3. Provision  ⏸ device-code approval
 
@@ -54,11 +58,13 @@ 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
@@ -78,10 +84,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