@odla-ai/cli 0.33.0 → 0.34.1

package/skills/odla-migrate/references/phase-3-auth.md

@@ -39,7 +39,7 @@ key; it never forwards or accepts another site's Clerk JWT.
    - `npx clerk link` (or `--app <id>`), then `npx clerk env pull` — pull
      the dev `pk_test_…` into `.env.local`. Take only the publishable key.
 2. Add the key to `odla.config.mjs`: `auth: { clerk: { dev: "<pk_test_…>" } }`
-   (inline is fine — it's public), then `npx @odla-ai/cli provision`
+   (inline is fine — it's public), then `npx --yes @odla-ai/cli@latest provision`
    (idempotent) — calls setAuth for the dev env; the issuer is derived
    from the key. **provision OVERWRITES any stale key** on public-config.
    The worker fetches auth config from public-config at runtime, so a key
@@ -146,7 +146,7 @@ works. Before writing any markup:
 
 - [ ] Unauthenticated curl to the gated route → 401
 - [ ] Signed-in browser session reaches the gated route
-- [ ] `npx @odla-ai/cli smoke --env dev` still passes
+- [ ] `npx --yes @odla-ai/cli@latest smoke --env dev` still passes
 - [ ] Every added UI element matches the site's existing look (fonts,
       palette, logo, spacing) — human-confirmed, not self-asserted
 - [ ] Post-login redirect lands on a real URL (mind trailing-slash /

package/skills/odla-migrate/references/phase-3b-user-sync.md

@@ -41,14 +41,14 @@ Enable it here.
 2. **Store the secret in the tenant vault** as `clerk_webhook_secret`, write-only.
    If any command can print the `whsec_` (Clerk CLI, Svix API), pipe it without
    it ever being displayed:
-   `<command that prints whsec_…> | npx @odla-ai/cli secrets set clerk_webhook_secret --env dev --stdin`.
+   `<command that prints whsec_…> | npx --yes @odla-ai/cli@latest secrets set clerk_webhook_secret --env dev --stdin`.
    Otherwise a human pastes it into Studio's secret UI (`odla.ai/studio` → the
    app → the env → secrets) — same write-only slot. The server decrypts it only
    to verify inbound events (svix HMAC over `id.timestamp.body`).
 3. **(Optional) `sk_…`** — the webhook payload already carries email/name/image,
    so the basic mirror needs only `whsec_`. Add the Clerk backend key only if
    you later need to resolve data the webhook doesn't send (invites, member
-   lookups): `npx @odla-ai/cli secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY`
+   lookups): `npx --yes @odla-ai/cli@latest secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY`
    stores it in the reserved `$clerk_secret` slot, write-only.
 
 ## Verify

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

@@ -15,11 +15,11 @@ own terminal so you never see the value.
    via this session):
 
        export <PROVIDER>_API_KEY=...    # their key
-       npx @odla-ai/cli provision
+       npx --yes @odla-ai/cli@latest provision
 
    provision stores the key in the tenant vault and sets provider/model
    in the registry. Their shell forgets it when closed; wrangler and git
-   never see it. If they use `! npx @odla-ai/cli provision` in-session, the
+   never see it. If they use `! npx --yes @odla-ai/cli@latest provision` in-session, the
    export must still happen in a terminal you don't read.
 3. `npm i @odla-ai/ai`. In the worker, use `initFromPlatform` — it reads
    provider/model from public-config (cached ~60s) and resolves the key
@@ -32,7 +32,7 @@ own terminal so you never see the value.
 
 ## Verification checklist
 
-- [ ] `npx @odla-ai/cli smoke --env dev` passes
+- [ ] `npx --yes @odla-ai/cli@latest smoke --env dev` passes
 - [ ] The AI route returns a model response on the deployed dev worker
 - [ ] `wrangler.jsonc` `vars` contain NO provider key; `git grep` for the
       key's prefix finds nothing

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

@@ -17,8 +17,8 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    add `links: { prod: "https://<domain>" }` (the CNAME domain captured in
    Phase 0). If using AI, the human re-runs the Phase 4 export + provision
    so the PROD tenant's vault gets the key.
-2. `npx @odla-ai/cli provision --dry-run`, show the human, then
-   `npx @odla-ai/cli provision --yes --push-secrets` — provisions the prod
+2. `npx --yes @odla-ai/cli@latest provision --dry-run`, show the human, then
+   `npx --yes @odla-ai/cli@latest provision --yes --push-secrets` — provisions the prod
    tenant (`<appId>`) and transfers its configured db/o11y secrets through
    Wrangler stdin. `--yes` is the explicit production consent; use standalone
    `secrets push --env prod --yes` only to retry the transfer (see
@@ -32,7 +32,7 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    Review `REPORT.md`; a candidate is a lead, not confirmation, and a baseline
    requires a concrete reason, owner, and expiry.
    If the human explicitly approves redacted tracked-source disclosure, follow
-   with `npx @odla-ai/cli security run . --env prod --ack-redacted-source`.
+   with `npx --yes @odla-ai/cli@latest security run . --env prod --ack-redacted-source`.
    The platform owns provider credentials and attributes the bounded,
    independent-model run to this app; never request provider keys locally.
    For a repeatable commit-pinned review, the human can first approve
@@ -46,7 +46,7 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    request/response contracts on the prod workers.dev URL. Equal payload values
    with different keys, nesting, types, units, or omission behavior are not
    parity.
-5. `npx @odla-ai/cli smoke --env prod`.
+5. `npx --yes @odla-ai/cli@latest smoke --env prod`.
 6. Human: add the domain to Cloudflare, then attach it to the prod
    worker (Workers & Pages → the worker → Domains & Routes). Supply
    them the exact hostname values to enter.
@@ -81,7 +81,7 @@ production on the *existing* app. Then:
 
 ## Verification checklist
 
-- [ ] `npx @odla-ai/cli smoke --env prod` passes
+- [ ] `npx --yes @odla-ai/cli@latest smoke --env prod` passes
 - [ ] Passive `odla-security` pre-cutover report reviewed; critical lead gate passes
 - [ ] Public domain serves from the worker (check the `x-odla-worker`
       header) on every parity path

package/skills/odla-migrate/references/project-state.md

@@ -51,10 +51,10 @@ Resolve `appId` from `odla.config.mjs`; do not guess it from a repository name,
 deployment, old branch, or conversation.
 
 ```cmd
-npx @odla-ai/cli pm next --app <appId>
-npx @odla-ai/cli pm bug list --app <appId> --status open
-npx @odla-ai/cli pm decision list --app <appId> --limit 20
-npx @odla-ai/cli pm goal list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm next --app <appId>
+npx --yes @odla-ai/cli@latest pm bug list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm decision list --app <appId> --limit 20
+npx --yes @odla-ai/cli@latest pm goal list --app <appId> --status open
 ```
 
 Read the linked goal and the active task's comments before editing. Confirm

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

@@ -30,8 +30,8 @@ authorizes one exact Cloudflare target; Registry stages additive DB/o11y
 credentials, the CLI holds plaintext only in memory, and one Wrangler bulk
 stdin call installs `ODLA_API_KEY` plus `ODLA_O11Y_TOKEN`:
 
-    npx @odla-ai/cli provision --push-secrets
-    npx @odla-ai/cli provision --live --yes --push-secrets  # Phase 5; prod only
+    npx --yes @odla-ai/cli@latest provision --push-secrets
+    npx --yes @odla-ai/cli@latest provision --live --yes --push-secrets  # Phase 5; prod only
 
 Each developer and Worker may have a different credential for the same sandbox
 tenant. Revocation is targeted and never rotates siblings. Use
@@ -39,8 +39,8 @@ tenant. Revocation is targeted and never rotates siblings. Use
 one deployed runtime. Use the narrower command below only to transfer an
 already-saved local-development credential:
 
-    npx @odla-ai/cli secrets push --env dev
-    npx @odla-ai/cli secrets push --env prod --yes
+    npx --yes @odla-ai/cli@latest secrets push --env dev
+    npx --yes @odla-ai/cli@latest secrets push --env prod --yes
 
 There is intentionally no production manual-copy fallback. If the CLI is
 unavailable, repair the CLI or Registry session path rather than exporting a
@@ -52,8 +52,8 @@ production key into shell history or chat.
 reading the value only from stdin or a named env var — never argv — so a
 producer command pipes straight into the vault:
 
-    <command that prints the value> | npx @odla-ai/cli secrets set clerk_webhook_secret --env dev --stdin
-    npx @odla-ai/cli secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
+    <command that prints the value> | npx --yes @odla-ai/cli@latest secrets set clerk_webhook_secret --env dev --stdin
+    npx --yes @odla-ai/cli@latest secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
 
 The value cannot be read back by the CLI, Studio, or the developer token —
 only by that tenant's app API key (reserved `$` secrets not even then). Studio

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

@@ -22,30 +22,30 @@ Cause: tenant confusion — the code ran against `<appId>` (prod) instead
 of `<appId>--dev`, or vice versa. Typical trigger: `wrangler deploy`
 without `--env dev`, or `wrangler dev` picking up top-level vars.
 Fix: check `ODLA_TENANT`/`ODLA_ENV` in the relevant `wrangler.jsonc`
-env block and which deploy command ran. `npx @odla-ai/cli smoke --env dev`
+env block and which deploy command ran. `npx --yes @odla-ai/cli@latest smoke --env dev`
 prints what it verified against.
 
 ## Provision fails with an auth/token error
 
 Cause: the `odla_dev_…` token expired (~24h) or the handshake was never
 approved.
-Fix: re-run `npx @odla-ai/cli provision` — it resumes a still-pending
-handshake if one exists, else starts a fresh one; the 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.
+Fix: start one fresh foreground provision with the matching existing account
+supplied by `--email` or `ODLA_USER_EMAIL`, plus `--no-open --wait 600`.
+Immediately surface the printed URL and code to that human and preserve the CLI
+process while they review and approve it. Never ask for a password or session
+token.
 
 ## Handshake exits with code 75 / "handshake still pending"
 
-Cause: nobody approved within the wait cap (90s outside an interactive
-terminal; `--wait <seconds>` overrides). This is normal in agent shells and
-loses nothing — the handshake is persisted in `.odla/handshake.local.json`.
-Fix: use browser control to open the one printed `/studio?code=` URL now. If
-browser control is unavailable, give that URL to the human **verbatim**. The
-CLI attempts its OS opener in every real environment, but that request can
-still produce no visible tab. Wait for approval, then re-run the same command; it
-resumes the same code and collects the token. Do not loop unattended
-retries; each handshake lives ~10 minutes.
+Cause: nobody approved before the CLI process's wait cap. The opaque device code
+lived only in that process and is not persisted, so an exited process cannot
+collect a later approval of its old URL.
+Fix: tell the human the old code is no longer usable. Start one fresh foreground
+command with `--no-open --wait 600`, immediately surface its new clickable URL
+and code, and keep that exact CLI process running. Wait only on the tool's
+existing process session; the CLI owns protocol polling. Do not use `open`,
+browser control, `curl`, a shell wait/poll loop, detached execution, or
+unattended retries.
 
 ## The approval URL says no request matches, or is never approvable
 
@@ -65,22 +65,22 @@ prints a URL, polls, and times out.
 Fix: confirm the address with the human and re-run. **Never derive it from
 `git config user.email`, `gh`, or a commit author** — that is the usual source
 of this, because a git identity is routinely a different address from the odla
-account. If `.odla/handshake.local.json` exists, the address it records is
-known-good; reuse that. Repeated failures with the same address mean it is not
-registered — the human must add it to their account (or use the registered
-one), and no amount of retrying will help.
+account. A legacy `.odla/handshake.local.json` is discarded by current clients
+and must not be treated as resumable state. Repeated failures with the same
+address mean it is not registered — the human must add it to their account (or
+use the registered one), and no amount of retrying will help.
 
 ## `smoke` fails: missing credentials
 
 Cause: `.odla/credentials.local.json` absent, for a different app id,
 or lacking a db key for the requested env.
-Fix: run `npx @odla-ai/cli provision` for the configured envs first; confirm
+Fix: run `npx --yes @odla-ai/cli@latest provision` for the configured envs first; confirm
 `envs` in odla.config.mjs includes the env you're smoking.
 
 ## `smoke` fails: schema mismatch
 
 Cause: local `src/odla/schema.mjs` changed since the last push.
-Fix: re-run `npx @odla-ai/cli provision` (schema re-push is the migration
+Fix: re-run `npx --yes @odla-ai/cli@latest provision` (schema re-push is the migration
 mechanism; additive changes are safe on live tenants), then re-run
 smoke.
 
@@ -88,7 +88,7 @@ smoke.
 
 Cause: an older CLI expected one o11y token per tenant. Current o11y credentials
 are additive, so another developer or Worker's token is not an obstacle.
-Fix: run `npx @odla-ai/cli provision --push-secrets` (add `--yes` when production
+Fix: run `npx --yes @odla-ai/cli@latest provision --push-secrets` (add `--yes` when production
 is in the plan). The approved handshake stages a new target-bound token and DB
 key, installs them without a local plaintext cache, and leaves every sibling
 credential intact. Use destructive rotation only for an actual compromise.
@@ -127,7 +127,7 @@ Wrangler bulk operation automatically revokes its staged set.
 
 ## Something not covered here
 
-Check, in order: `npx @odla-ai/cli doctor` output; this skill's current phase
+Check, in order: `npx --yes @odla-ai/cli@latest doctor` output; this skill's current phase
 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

@@ -22,8 +22,8 @@ do those requests share."
 Start with the stable aggregate envelope before composing individual routes:
 
 ```cmd
-npx @odla-ai/cli context show --app <appId> --env prod --json
-npx @odla-ai/cli o11y status --app <appId> --env prod --minutes 60 --json
+npx --yes @odla-ai/cli@latest context show --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest o11y status --app <appId> --env prod --minutes 60 --json
 ```
 
 Both commands work outside a project checkout. `context show` reports where
@@ -123,7 +123,7 @@ bug against the app, with the cohort in the description and the trace id in a
 comment:
 
 ```cmd
-npx @odla-ai/cli pm bug add --app <appId> --title "POST /pay 503s under retry" --severity high --desc "…"
+npx --yes @odla-ai/cli@latest pm bug add --app <appId> --title "POST /pay 503s under retry" --severity high --desc "…"
 ```
 
 Severity follows the blast radius, not your confidence. The conventions and the