@odla-ai/cli 0.10.0 → 0.10.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "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",
@@ -27,8 +27,7 @@
     "dist",
     "skills",
     "README.md",
-    "REQUIREMENTS.md",
-    "llms.txt"
+    "REQUIREMENTS.md"
   ],
   "sideEffects": false,
   "engines": {
@@ -55,14 +54,13 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
-    "gen:llms": "node ../../scripts/gen-llms.mjs",
-    "prepublishOnly": "npm run build && npm run gen:llms"
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@odla-ai/ai": "^0.3.3",
-    "@odla-ai/apps": "^0.8.0",
-    "@odla-ai/db": "^0.6.2",
-    "@odla-ai/security": "^0.2.2"
+    "@odla-ai/ai": "^0.4.0",
+    "@odla-ai/apps": "^0.8.1",
+    "@odla-ai/db": "^0.6.4",
+    "@odla-ai/security": "^0.3.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

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
@@ -119,5 +124,7 @@ code, paste a publishable key, run a command) — and wait for a nod.
 - `references/build.md` — the greenfield build, step by step, with the exact
   commands and what to verify at each one.
 - `references/sdks.md` — SDK cheat-sheet (what each does + minimal real usage).
-  Every installed SDK also ships `node_modules/@odla-ai/<pkg>/llms.txt` — read
-  it for the full, current API.
+  For the full, version-matched API, read the installed package's README and
+  exported TypeScript declarations/JSDoc (resolve entry points through its
+  `package.json` `exports`). Rendered references are also public at
+  `https://odla.ai/docs/packages/<pkg>`.

package/skills/odla/references/build.md

@@ -30,18 +30,21 @@ deployed-secret transfer. With o11y, install `@odla-ai/o11y`, add
 `"nodejs_compat"` to `compatibility_flags`, and wrap the entrypoint with
 `withObservability`.
 
-Each installed package's `node_modules/@odla-ai/<pkg>/llms.txt` is the full API
-contract. The npm artifacts contain everything required for this flow; private
-service source or online documentation is not setup context.
+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.
 
 ## 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.
@@ -85,12 +88,12 @@ code. Browser code uses db subscriptions under explicit rules or pure
 Install the passive harness and scan before any production secret or deploy:
 
 Before installing the exact release, first verify
-`npm view @odla-ai/security@0.2.2 version`. An exact-version `E404` means the
+`npm view @odla-ai/security@0.3.1 version`. An exact-version `E404` means the
 release is unavailable and blocks this preflight; it is not a clean scan and
 does not prove the package name is absent.
 
 ```
-npm i -D --save-exact @odla-ai/security@0.2.2
+npm i -D --save-exact @odla-ai/security@0.3.1
 npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
 ```
 

package/skills/odla/references/sdks.md

@@ -1,8 +1,9 @@
 # odla SDK cheat-sheet
 
-Install only what the app needs. Every package ships an `llms.txt` in
-`node_modules/@odla-ai/<pkg>/` with the full, current API — read it. Minimal
-real usage below.
+Install only what the app needs. Prefer the installed package's README and
+exported TypeScript declarations/JSDoc over training memory; resolve public
+entry points through its `package.json` `exports`. Rendered references are also
+available at `https://odla.ai/docs/packages/<pkg>`. Minimal real usage follows.
 
 ## @odla-ai/db — realtime graph database
 
@@ -99,12 +100,12 @@ Run the passive CLI in local/CI development; do not import it into the running
 Worker:
 
 Before installing the exact release, require
-`npm view @odla-ai/security@0.2.2 version` to succeed before installing it. An
+`npm view @odla-ai/security@0.3.1 version` to succeed before installing it. An
 exact-version `E404` means the release is unavailable, not that the preflight
 passed, and does not prove the package name is absent.
 
 ```
-npm i -D --save-exact @odla-ai/security@0.2.2
+npm i -D --save-exact @odla-ai/security@0.3.1
 npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
 ```
 

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.
@@ -118,5 +121,6 @@ On any failure, read references/troubleshooting.md before improvising.
 This installed skill and its `references/` directory are the complete migration
 runbook; do not fetch a website or private source repository to reconstruct it.
 Read only the current phase file as directed above. After `npm install`, prefer
-`node_modules/@odla-ai/*/llms.txt` over training memory for package APIs — the
-installed artifact is the version this project actually uses.
+each installed package's README and exported TypeScript declarations/JSDoc over
+training memory; resolve entry points through its `package.json` `exports`.
+Those artifacts describe the version this project actually uses.

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.2 version` to succeed, then run
+   `npm i -D --save-exact @odla-ai/cli@0.10.2` 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** —
@@ -21,7 +22,7 @@ in the browser in interactive terminals).
    public-config show where the app runs. (`links.prod` is set the same way at
    Phase 5, from the prod deploy's printed URL.)
 3. STOP before touching schema: read "Porting relational code" in
-   `node_modules/@odla-ai/db/llms.txt`. The traps are silent: entity ids
+   `node_modules/@odla-ai/db/README.md`. The traps are silent: entity ids
    are not attrs (mirror an id attr), there is no NULL (omit on write,
    re-project on read), lists need explicit `order`, uniques are
    single-attr (derive composite keys), ON CONFLICT maps to `mutationId`
@@ -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
@@ -47,8 +49,9 @@ in the browser in interactive terminals).
 10. Add `/api/*` routes before the assets fall-through, using
     `init({ appId: env.ODLA_TENANT, adminToken: env.ODLA_API_KEY,
     endpoint: env.ODLA_ENDPOINT })` from `@odla-ai/db`. Read the installed
-    package's `node_modules/@odla-ai/db/llms.txt` for query, transaction, and
-    error contracts.
+    package's README and exported TypeScript declarations/JSDoc for query,
+    transaction, and error contracts. The rendered reference is at
+    `https://odla.ai/docs/packages/db` when online.
 11. `wrangler dev` + curl each route; then `npm run deploy:app:dev` and
     curl the workers.dev URL.
 

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

@@ -9,8 +9,8 @@ server-issued Google consent page. They never paste an OAuth code or token.
 
 1. Inventory the old behavior. Distinguish a public appointment-page link from
    actual event create/reschedule/cancel APIs. Do not promise more than exists.
-2. Require `npm view @odla-ai/calendar@0.1.0 version` to succeed, then install
-   `npm i --save-exact @odla-ai/calendar@0.1.0` as a runtime dependency. An
+2. Require `npm view @odla-ai/calendar@0.1.1 version` to succeed, then install
+   `npm i --save-exact @odla-ai/calendar@0.1.1` as a runtime dependency. An
    exact-version `E404` blocks this phase; do not substitute a git checkout or
    another version. Add `"calendar"` beside
    `"db"` in services and configure:

package/skills/odla-migrate/references/phase-4-ai.md

@@ -24,9 +24,10 @@ own terminal so you never see the value.
 3. `npm i @odla-ai/ai`. In the worker, use `initFromPlatform` — it reads
    provider/model from public-config (cached ~60s) and resolves the key
    from the vault at call time using only the app's db key. Provider and
-   model are switchable in Studio with no redeploy. Read
-   `node_modules/@odla-ai/ai/llms.txt` and the public platform manual for the
-   complete vault + public-config contract.
+   model are switchable in Studio with no redeploy. Read the installed
+   `node_modules/@odla-ai/ai/README.md` and exported TypeScript
+   declarations/JSDoc for the version-matched API; the rendered reference at
+   `https://odla.ai/docs/packages/ai` covers the public platform composition.
 4. Add one `/api/*` route that round-trips the model; deploy dev.
 
 ## Verification checklist

package/skills/odla-migrate/references/phase-5-cutover.md

@@ -24,10 +24,10 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    `secrets push --env prod --yes` only to retry the transfer (see
    references/secrets-map.md).
 3. Build, then run the passive pre-cutover security gate:
-   first require `npm view @odla-ai/security@0.2.2 version` to succeed. An
+   first require `npm view @odla-ai/security@0.3.1 version` to succeed. An
    exact-version `E404` means the release is unavailable and blocks cutover;
    it is not a clean scan and does not prove the package name is absent. Run
-   `npm i -D --save-exact @odla-ai/security@0.2.2` followed by
+   `npm i -D --save-exact @odla-ai/security@0.3.1` followed by
    `npx odla-security scan . --profile odla --out .odla/security/pre-cutover --fail-on high --fail-on-candidates critical`.
    Review `REPORT.md`; a candidate is a lead, not confirmation, and a baseline
    requires a concrete reason, owner, and expiry.

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
@@ -78,6 +80,6 @@ the printed `secrets push --env ...` retry and do not rotate again.
 ## Something not covered here
 
 Check, in order: `npx @odla-ai/cli doctor` output; this skill's current phase
-and troubleshooting references; then the relevant installed
-`node_modules/@odla-ai/*/llms.txt`. Do not improvise around a safety rule to
-unblock yourself — surface the blocker to the human instead.
+and troubleshooting references; then the relevant installed package README and
+exported TypeScript declarations/JSDoc. Do not improvise around a safety rule
+to unblock yourself — surface the blocker to the human instead.

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