@odla-ai/cli 0.10.0 → 0.10.1

package/dist/index.d.cts

@@ -30,6 +30,8 @@ type ScopedPlatformScope = "platform:ai:policy:read" | "platform:ai:policy:write
 interface ScopedPlatformTokenOptions {
     platform: string;
     scope: ScopedPlatformScope;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     open?: boolean;
     fetch?: typeof fetch;
     stdout?: Pick<typeof console, "log">;
@@ -59,6 +61,8 @@ interface AdminAiOptions {
     maxCallsPerRun?: number;
     platform?: string;
     token?: string;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     json?: boolean;
     open?: boolean;
     fetch?: typeof fetch;
@@ -91,16 +95,17 @@ 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", "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 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"];
+    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"];
 };
 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. */
 type CalendarConnectionState = (typeof CALENDAR_STATES)[number];
 /** Owner-visible, secret-free calendar connection and sync health. */
 interface CalendarStatus {
@@ -136,10 +141,15 @@ interface AvailableGoogleCalendar {
     accessRole?: "freeBusyReader" | "reader" | "writer" | "owner";
 }
 
+/** 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. */
 interface CalendarLifecycleOptions {
-    configPath: string;
-    env?: string;
-    token?: string;
+    /** Path to the checked-in odla project config. */ configPath: string;
+    /** Configured environment; defaults to dev when present. */ env?: string;
+    /** Existing developer-token override. */ token?: string;
+    /** Existing odla account email used only for a fresh handshake. */ email?: string;
     open?: boolean;
     interactive?: boolean;
     yes?: boolean;
@@ -206,6 +216,8 @@ interface GoogleCalendarConfig {
     /** 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. */
 interface CalendarConfig {
     google: GoogleCalendarConfig;
 }
@@ -309,6 +321,8 @@ interface ProvisionOptions {
     writeCredentials?: boolean;
     writeDevVars?: string | boolean;
     token?: string;
+    /** Existing odla account email used only when a fresh device handshake is required. */
+    email?: string;
     /** true forces browser launch, false disables it, undefined auto-opens only for interactive terminals. */
     open?: boolean;
     /** Test/embedding override for terminal interactivity. Defaults to stdin/stdout TTY detection. */
@@ -344,6 +358,8 @@ interface SmokeOptions {
     env?: string;
     /** Developer-token override used only for owner-visible calendar health. */
     token?: string;
+    /** Existing odla account email used only when a fresh device handshake is required. */
+    email?: string;
     open?: boolean;
     interactive?: boolean;
     openApprovalUrl?: (url: string) => Promise<void>;
@@ -351,6 +367,7 @@ 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";
 /** Resolve the checked-in calendar block into one controller-safe env payload. */
 declare function calendarServiceConfig(cfg: LoadedProjectConfig, env: string): CalendarServiceConfig;
@@ -434,14 +451,17 @@ declare function initProject(options: InitOptions): void;
  * (mode 0600, gitignored) and, when requested, `.dev.vars`.
  *
  * The developer token comes from (in order) `options.token`, `$ODLA_DEV_TOKEN`,
- * the cached `.odla` token, or a fresh device handshake — which prints a user
- * code + approval URL and, in interactive terminals, auto-opens the browser
+ * the cached `.odla` token, or a fresh email-bound device handshake — which
+ * prints a user code for the same signed-in account to review and, in
+ * interactive terminals, auto-opens the browser
  * (`open: true`/`false` forces/suppresses it). Network error bodies pass through
  * `redactSecrets` before display.
  *
  * @param options.dryRun Print the resolved plan and return before any network call/write.
  * @param options.rotateKeys Rotate db keys and o11y tokens.
  * @param options.rotateO11yToken Rotate only the o11y token.
+ * @param options.email Existing odla account email for a fresh handshake;
+ * this is an identity hint, never a password or session credential.
  * @param options.pushSecrets Preflight Wrangler, then push each env's configured
  *   Worker secrets immediately after credential provisioning.
  * @param options.writeDevVars `true`/a path writes `.dev.vars`; `writeCredentials: false` skips the creds file.
@@ -499,6 +519,8 @@ interface SecretsSetOptions {
     yes?: boolean;
     /** Developer token override; defaults to $ODLA_DEV_TOKEN, the cached token, or a device handshake. */
     token?: string;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     open?: boolean;
     interactive?: boolean;
     openApprovalUrl?: (url: string) => Promise<void>;

package/dist/index.d.ts

@@ -30,6 +30,8 @@ type ScopedPlatformScope = "platform:ai:policy:read" | "platform:ai:policy:write
 interface ScopedPlatformTokenOptions {
     platform: string;
     scope: ScopedPlatformScope;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     open?: boolean;
     fetch?: typeof fetch;
     stdout?: Pick<typeof console, "log">;
@@ -59,6 +61,8 @@ interface AdminAiOptions {
     maxCallsPerRun?: number;
     platform?: string;
     token?: string;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     json?: boolean;
     open?: boolean;
     fetch?: typeof fetch;
@@ -91,16 +95,17 @@ 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", "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 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"];
+    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"];
 };
 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. */
 type CalendarConnectionState = (typeof CALENDAR_STATES)[number];
 /** Owner-visible, secret-free calendar connection and sync health. */
 interface CalendarStatus {
@@ -136,10 +141,15 @@ interface AvailableGoogleCalendar {
     accessRole?: "freeBusyReader" | "reader" | "writer" | "owner";
 }
 
+/** 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. */
 interface CalendarLifecycleOptions {
-    configPath: string;
-    env?: string;
-    token?: string;
+    /** Path to the checked-in odla project config. */ configPath: string;
+    /** Configured environment; defaults to dev when present. */ env?: string;
+    /** Existing developer-token override. */ token?: string;
+    /** Existing odla account email used only for a fresh handshake. */ email?: string;
     open?: boolean;
     interactive?: boolean;
     yes?: boolean;
@@ -206,6 +216,8 @@ interface GoogleCalendarConfig {
     /** 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. */
 interface CalendarConfig {
     google: GoogleCalendarConfig;
 }
@@ -309,6 +321,8 @@ interface ProvisionOptions {
     writeCredentials?: boolean;
     writeDevVars?: string | boolean;
     token?: string;
+    /** Existing odla account email used only when a fresh device handshake is required. */
+    email?: string;
     /** true forces browser launch, false disables it, undefined auto-opens only for interactive terminals. */
     open?: boolean;
     /** Test/embedding override for terminal interactivity. Defaults to stdin/stdout TTY detection. */
@@ -344,6 +358,8 @@ interface SmokeOptions {
     env?: string;
     /** Developer-token override used only for owner-visible calendar health. */
     token?: string;
+    /** Existing odla account email used only when a fresh device handshake is required. */
+    email?: string;
     open?: boolean;
     interactive?: boolean;
     openApprovalUrl?: (url: string) => Promise<void>;
@@ -351,6 +367,7 @@ 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";
 /** Resolve the checked-in calendar block into one controller-safe env payload. */
 declare function calendarServiceConfig(cfg: LoadedProjectConfig, env: string): CalendarServiceConfig;
@@ -434,14 +451,17 @@ declare function initProject(options: InitOptions): void;
  * (mode 0600, gitignored) and, when requested, `.dev.vars`.
  *
  * The developer token comes from (in order) `options.token`, `$ODLA_DEV_TOKEN`,
- * the cached `.odla` token, or a fresh device handshake — which prints a user
- * code + approval URL and, in interactive terminals, auto-opens the browser
+ * the cached `.odla` token, or a fresh email-bound device handshake — which
+ * prints a user code for the same signed-in account to review and, in
+ * interactive terminals, auto-opens the browser
  * (`open: true`/`false` forces/suppresses it). Network error bodies pass through
  * `redactSecrets` before display.
  *
  * @param options.dryRun Print the resolved plan and return before any network call/write.
  * @param options.rotateKeys Rotate db keys and o11y tokens.
  * @param options.rotateO11yToken Rotate only the o11y token.
+ * @param options.email Existing odla account email for a fresh handshake;
+ * this is an identity hint, never a password or session credential.
  * @param options.pushSecrets Preflight Wrangler, then push each env's configured
  *   Worker secrets immediately after credential provisioning.
  * @param options.writeDevVars `true`/a path writes `.dev.vars`; `writeCredentials: false` skips the creds file.
@@ -499,6 +519,8 @@ interface SecretsSetOptions {
     yes?: boolean;
     /** Developer token override; defaults to $ODLA_DEV_TOKEN, the cached token, or a device handshake. */
     token?: string;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     open?: boolean;
     interactive?: boolean;
     openApprovalUrl?: (url: string) => Promise<void>;

package/dist/index.js

@@ -38,7 +38,7 @@ import {
   secretsSetClerkKey,
   smoke,
   startHostedSecurityJob
-} from "./chunk-WDKBW4BE.js";
+} from "./chunk-MWVKOIGR.js";
 export {
   AGENT_HARNESSES,
   CAPABILITIES,

package/llms.txt

@@ -31,13 +31,17 @@ 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.10.0 version
-npm i -D --save-exact @odla-ai/cli@0.10.0
+npm view @odla-ai/cli@0.10.1 version
+npm i -D --save-exact @odla-ai/cli@0.10.1
 ```
 
 ## Prerequisites
 
 - Node.js 20 or newer (`node --version`).
+- An existing odla account that has signed in at least once. For any command
+  that may need a fresh device grant, pass `--email <account>` or set
+  `ODLA_USER_EMAIL`. This value identifies who may review the request; it is not
+  a password or session credential, and an agent must never ask for either.
 - odla apps usually deploy as Cloudflare Workers. If you have never used
   Cloudflare:
   1. Create a free account at <https://dash.cloudflare.com/sign-up>.
@@ -63,7 +67,7 @@ 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
-npx odla-ai provision --write-dev-vars --push-secrets
+npx odla-ai provision --email owner@example.com --write-dev-vars --push-secrets
 npx odla-ai smoke --env dev
 npx odla-ai secrets push --env dev
 npx odla-ai secrets set clerk_webhook_secret --env dev --stdin
@@ -75,7 +79,7 @@ npx @odla-ai/cli security sources --env dev
 npx @odla-ai/cli security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
 npx @odla-ai/cli security status <job-id>
 npx @odla-ai/cli security report <job-id>
-npx odla-ai admin ai show
+npx odla-ai admin ai show --email owner@example.com
 npx odla-ai admin ai models
 npx odla-ai admin ai set security --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
 npx odla-ai admin ai credentials
@@ -103,8 +107,11 @@ When using `--push-secrets`, create the Worker and its Wrangler config first.
 The CLI checks that config and `wrangler whoami` before it issues or rotates a
 shown-once credential.
 
-1. Gets an `odla_dev_...` token by device handshake, or reuses
-   `ODLA_DEV_TOKEN` / `.odla/dev-token.json`.
+1. Gets an `odla_dev_...` token by email-bound device handshake, or reuses
+   `ODLA_DEV_TOKEN` / `.odla/dev-token.json`. A fresh handshake requires
+   `--email <account>` or `ODLA_USER_EMAIL`; the matching existing account must
+   sign in, review the exact code, and approve it. Opening the URL alone does
+   not claim the request.
    In an interactive terminal it opens the approval page in your browser when
    the code is displayed. Pass `--open` to force browser launch from a
    non-interactive shell, or `--no-open` to suppress it. Browser launch is
@@ -138,6 +145,26 @@ The CLI preflights Wrangler first and persists the replacement before pushing;
 if that final push still fails, follow the printed `secrets push --env ...`
 retry. Do not run the rotation flag again.
 
+### Device-grant security and recovery
+
+The account email sent during a fresh handshake is a non-secret identity hint,
+not proof of identity. Unknown or never-signed-in accounts never produce a
+claimable Studio request, and the public start/poll shape intentionally does not
+reveal whether an account exists. The signed-in matching user must explicitly
+review the exact code before it becomes pending, and only one claimed pending
+or approved-but-uncollected request can be active for that user.
+
+Developer grants are tracked by id, owner, label, scopes, creation/expiry,
+last use, and revocation state. The plaintext token is delivered once to the
+polling client and is never available from the inventory. Every signed-in user
+can inspect and revoke their own grants under **Your agent credentials** in
+Studio; platform admins additionally see the global token inventory and
+metadata-only attempt evidence. Future requests with a revoked token fail.
+Deleting
+`.odla/dev-token.json` or `.odla/admin-token.local.json` removes the local copy
+but does not revoke a token already copied elsewhere, so use Studio revocation
+when compromise or accidental approval is possible.
+
 `smoke` verifies a provisioned environment from local credentials. It fetches
 the platform public config, checks the configured AI provider, fetches the live
 odla-db schema with the tenant key, compares expected schema entities, and runs
@@ -431,7 +458,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.10.0)
+## API reference (generated from dist/index.d.ts, v0.10.1)
 
 ```ts
 import { SecurityReport, PlatformSecurityRun } from '@odla-ai/security';
@@ -466,6 +493,8 @@ type ScopedPlatformScope = "platform:ai:policy:read" | "platform:ai:policy:write
 interface ScopedPlatformTokenOptions {
     platform: string;
     scope: ScopedPlatformScope;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     open?: boolean;
     fetch?: typeof fetch;
     stdout?: Pick<typeof console, "log">;
@@ -495,6 +524,8 @@ interface AdminAiOptions {
     maxCallsPerRun?: number;
     platform?: string;
     token?: string;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     json?: boolean;
     open?: boolean;
     fetch?: typeof fetch;
@@ -527,16 +558,17 @@ 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", "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 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"];
+    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"];
 };
 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. */
 type CalendarConnectionState = (typeof CALENDAR_STATES)[number];
 /** Owner-visible, secret-free calendar connection and sync health. */
 interface CalendarStatus {
@@ -572,10 +604,15 @@ interface AvailableGoogleCalendar {
     accessRole?: "freeBusyReader" | "reader" | "writer" | "owner";
 }
 
+/** 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. */
 interface CalendarLifecycleOptions {
-    configPath: string;
-    env?: string;
-    token?: string;
+    /** Path to the checked-in odla project config. */ configPath: string;
+    /** Configured environment; defaults to dev when present. */ env?: string;
+    /** Existing developer-token override. */ token?: string;
+    /** Existing odla account email used only for a fresh handshake. */ email?: string;
     open?: boolean;
     interactive?: boolean;
     yes?: boolean;
@@ -642,6 +679,8 @@ interface GoogleCalendarConfig {
     /** 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. */
 interface CalendarConfig {
     google: GoogleCalendarConfig;
 }
@@ -745,6 +784,8 @@ interface ProvisionOptions {
     writeCredentials?: boolean;
     writeDevVars?: string | boolean;
     token?: string;
+    /** Existing odla account email used only when a fresh device handshake is required. */
+    email?: string;
     /** true forces browser launch, false disables it, undefined auto-opens only for interactive terminals. */
     open?: boolean;
     /** Test/embedding override for terminal interactivity. Defaults to stdin/stdout TTY detection. */
@@ -780,6 +821,8 @@ interface SmokeOptions {
     env?: string;
     /** Developer-token override used only for owner-visible calendar health. */
     token?: string;
+    /** Existing odla account email used only when a fresh device handshake is required. */
+    email?: string;
     open?: boolean;
     interactive?: boolean;
     openApprovalUrl?: (url: string) => Promise<void>;
@@ -787,6 +830,7 @@ 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";
 /** Resolve the checked-in calendar block into one controller-safe env payload. */
 declare function calendarServiceConfig(cfg: LoadedProjectConfig, env: string): CalendarServiceConfig;
@@ -870,14 +914,17 @@ declare function initProject(options: InitOptions): void;
  * (mode 0600, gitignored) and, when requested, `.dev.vars`.
  *
  * The developer token comes from (in order) `options.token`, `$ODLA_DEV_TOKEN`,
- * the cached `.odla` token, or a fresh device handshake — which prints a user
- * code + approval URL and, in interactive terminals, auto-opens the browser
+ * the cached `.odla` token, or a fresh email-bound device handshake — which
+ * prints a user code for the same signed-in account to review and, in
+ * interactive terminals, auto-opens the browser
  * (`open: true`/`false` forces/suppresses it). Network error bodies pass through
  * `redactSecrets` before display.
  *
  * @param options.dryRun Print the resolved plan and return before any network call/write.
  * @param options.rotateKeys Rotate db keys and o11y tokens.
  * @param options.rotateO11yToken Rotate only the o11y token.
+ * @param options.email Existing odla account email for a fresh handshake;
+ * this is an identity hint, never a password or session credential.
  * @param options.pushSecrets Preflight Wrangler, then push each env's configured
  *   Worker secrets immediately after credential provisioning.
  * @param options.writeDevVars `true`/a path writes `.dev.vars`; `writeCredentials: false` skips the creds file.
@@ -935,6 +982,8 @@ interface SecretsSetOptions {
     yes?: boolean;
     /** Developer token override; defaults to $ODLA_DEV_TOKEN, the cached token, or a device handshake. */
     token?: string;
+    /** Existing odla account email used only when a fresh handshake is required. */
+    email?: string;
     open?: boolean;
     interactive?: boolean;
     openApprovalUrl?: (url: string) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "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",
@@ -61,7 +61,7 @@
   "dependencies": {
     "@odla-ai/ai": "^0.3.3",
     "@odla-ai/apps": "^0.8.0",
-    "@odla-ai/db": "^0.6.2",
+    "@odla-ai/db": "^0.6.3",
     "@odla-ai/security": "^0.2.2"
   },
   "devDependencies": {

package/skills/odla/SKILL.md

@@ -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
@@ -66,8 +69,10 @@ 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. With calendar enabled it

package/skills/odla/references/build.md

@@ -37,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.

package/skills/odla-migrate/SKILL.md

@@ -38,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.

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.10.0 version` to succeed, then run
-   `npm i -D --save-exact @odla-ai/cli@0.10.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/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