@odla-ai/cli 0.33.0 → 0.34.1

package/skills/odla/SKILL.md

@@ -49,7 +49,9 @@ State which path you're taking and what you'll build in one line; get a nod.
    registry matches the exact string. An address that is not a registered
    account does NOT error: it mints an indistinguishable decoy, so the CLI
    prints a normal approval URL that can never be approved by anyone. Ask the
-   human, or reuse the address already in `.odla/handshake.local.json`.
+   human, or reuse the same-audience account identity already recorded with a
+   collected developer token. Current clients never persist pending device
+   codes in `.odla/handshake.local.json`.
 2. **Sandbox before live.** Every app has two databases on production odla.ai:
    a sandbox (env `dev`, tenant `<appId>--dev`) and a live one (env `prod`,
    tenant `<appId>`). "prod" names the app's live DATABASE, never a different
@@ -69,6 +71,26 @@ State which path you're taking and what you'll build in one line; get a nod.
    platform/Google consent URL returned by odla; booking runs server-side
    through the SDK with the app's existing key, never from a browser.
 
+## Agent handshake protocol
+
+Use the current published CLI and suppress browser auto-launch. Start the exact
+authorization as one foreground tool process:
+
+```bash
+npx --yes @odla-ai/cli@latest auth login --app <appId> --email <odla-account> --no-open --wait 600
+```
+
+When the CLI prints its one `/studio?code=` URL, immediately give the human a
+clickable link, repeat the code they must verify, and say that opening the page
+is not enough: they must click **Approve**. Keep the same CLI process alive and
+wait on that process for completion. The CLI owns protocol polling. Never call
+the OS `open` command, use browser control, curl a handshake endpoint, create a
+shell polling/wait loop, detach the process, or start a substitute handshake.
+The device code exists only in the running CLI. If it exits 75, the old request
+cannot be collected; start one fresh foreground invocation and surface only its
+new URL. Apply the same `--no-open --wait 600` flags when another command, such
+as first provision, must request a different reviewed capability.
+
 ## Tooling sources
 
 - **odla**: this skill plus the installed `@odla-ai/*` packages are the
@@ -93,28 +115,26 @@ State which path you're taking and what you'll build in one line; get a nod.
 
 ## The flow
 
-You reached this skill because the human ran `npx @odla-ai/cli setup`. Then:
+You reached this skill because the human ran `npx --yes @odla-ai/cli@latest setup`. Then:
 
-First run `npx @odla-ai/cli capabilities --json`; use that contract instead of
+First run `npx --yes @odla-ai/cli@latest capabilities --json`; use that contract instead of
 guessing which platform/credential steps need manual work. Then:
 
-1. **init** — `npx @odla-ai/cli init --app-id <id> --name "<Name>"` scaffolds
+1. **init** — `npx --yes @odla-ai/cli@latest init --app-id <id> --name "<Name>"` scaffolds
    `odla.config.mjs`, `src/odla/schema.mjs`, `src/odla/rules.mjs` (deny-all).
 2. **build the Worker shell** — install the SDKs, write the app, and create its
    Wrangler config (`references/sdks.md`). With o11y, add `nodejs_compat` and
    `withObservability`. The CLI will refuse secret delivery until the Wrangler
    target exists.
 3. **provision** ⏸ —
-   `npx @odla-ai/cli provision --email <existing-odla-account>
-   --write-dev-vars --push-secrets`. A device code prints; that same account
+   `npx --yes @odla-ai/cli@latest provision --email <existing-odla-account>
+   --write-dev-vars --push-secrets --no-open --wait 600`. 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. The CLI prints exactly one `/studio?code=`
-   URL and attempts to open it in every real environment. **If you have browser
-   control, open that exact URL now.** If you do not, give it to the human
-   verbatim; never wait silently or start a substitute handshake. Outside an
-   interactive terminal the wait is capped (90s default,
-   `--wait <seconds>`); exit code 75 means still pending. The device code is
-   not cached: rerunning always opens a fresh code for human review. It creates the app,
+   Opening the link alone is inert. Follow the agent handshake protocol above:
+   surface the exact link and code, keep this process alive, and let the CLI
+   wait. The device code is not cached; if the process exits, a rerun creates a
+   fresh code for human review. After approval it creates the app,
    consuming a one-time exact-id reservation when the approved app is new,
    enables services, issues or reuses configured credentials (db key + o11y
    ingest token when enabled), composes declared integration schema/rules and
@@ -125,13 +145,13 @@ guessing which platform/credential steps need manual work. Then:
    syncs.
 4. **run** — `npx wrangler dev` (auto-loads `.dev.vars`); verify locally.
    When an agent mention appears stuck, inspect the durable delivery ledger
-   with `npx odla-ai agent jobs --env <env> --json`. Requeue only an exact
-   dead-letter id with `npx odla-ai agent retry <job-id> --env <env> --json`;
+   with `npx --yes @odla-ai/cli@latest agent jobs --env <env> --json`. Requeue only an exact
+   dead-letter id with `npx --yes @odla-ai/cli@latest agent retry <job-id> --env <env> --json`;
    pending/running/succeeded jobs are intentionally not replayable.
 5. **security** — run the passive `@odla-ai/security` odla profile; inspect
    every lead and keep critical candidate gating enabled. If the human approves
    redacted source disclosure, follow with
-   `npx @odla-ai/cli security run . --env dev --ack-redacted-source` for
+   `npx --yes @odla-ai/cli@latest security run . --env dev --ack-redacted-source` for
    app-attributed discovery + independent validation. Never request provider
    keys; the platform selects the routes and returns bounded role grants. For
    repeatable server-side review, run `security github connect --env dev`
@@ -141,8 +161,8 @@ guessing which platform/credential steps need manual work. Then:
    --ack-redacted-source`.
    The source job follows, reports, and gates by default. Never request a PAT or
    treat GitHub read approval as redacted-snippet disclosure consent.
-6. **ship** ⏸ — run `npx @odla-ai/cli provision --live --dry-run`, show the
-   human, then `npx @odla-ai/cli provision --live --yes --push-secrets` and
+6. **ship** ⏸ — run `npx --yes @odla-ai/cli@latest provision --live --dry-run`, show the
+   human, then `npx --yes @odla-ai/cli@latest provision --live --yes --push-secrets` and
    `npx wrangler deploy`. Add `prod` to `envs` only when future ordinary
    provision runs should target both environments.
 
@@ -154,13 +174,13 @@ on the app. It is platform-side: there is nothing PM-specific to install or
 provision. Start a session by reading it, and keep it current while you build:
 
 ```cmd
-npx @odla-ai/cli pm next --app <appId>
+npx --yes @odla-ai/cli@latest pm next --app <appId>
 ```
 
 For a durable supervisor loop, establish and persist an exact-project PM cursor:
 
 ```cmd
-npx @odla-ai/cli pm watch --app <appId> --entity task --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --entity task --jsonl
 ```
 
 A Ready event is a wake-up signal, not permission: reload the task and linked
@@ -198,11 +218,11 @@ procedures — releasing, backups, database and code-runtime operations — are
 in odla and change without a CLI release. Read one at the moment you follow it:
 
 ```cmd
-npx @odla-ai/cli runbook list
+npx --yes @odla-ai/cli@latest runbook list
 ```
 
 ```cmd
-npx @odla-ai/cli runbook get release
+npx --yes @odla-ai/cli@latest runbook get release
 ```
 
 `runbook get` prints raw markdown, so pipe it or read it directly. Do not follow a
@@ -214,11 +234,11 @@ cited answer; `search` returns the **sections** behind it, each with its source
 and the command to pull the rest:
 
 ```cmd
-npx @odla-ai/cli runbook ask "how do I roll back a bad publish?"
+npx --yes @odla-ai/cli@latest runbook ask "how do I roll back a bad publish?"
 ```
 
 ```cmd
-npx @odla-ai/cli runbook search "roll back a bad publish"
+npx --yes @odla-ai/cli@latest runbook search "roll back a bad publish"
 ```
 
 Cite what you quote — `release#rolling-back-a-bad-publish (v3)` — so the reader
@@ -237,7 +257,7 @@ installed version in front of you, and the runbook is not claiming to describe i
 ### After you change something, ask what you invalidated
 
 ```cmd
-npx @odla-ai/cli runbook impact
+npx --yes @odla-ai/cli@latest runbook impact
 ```
 
 It diffs your working tree against `origin/main` (`--base <ref>` for anything
@@ -255,7 +275,7 @@ in the same piece of work.
 The other direction — are the runbooks themselves still true?
 
 ```cmd
-npx @odla-ai/cli runbook lint
+npx --yes @odla-ai/cli@latest runbook lint
 ```
 
 Every `odla-ai …` command the runbooks name is held against this CLI's real
@@ -268,21 +288,31 @@ reader on an older CLI gets an "unknown action" error instead of an explanation.
 
 Found a wrong step? Fix an app runbook directly. For a platform runbook,
 `runbook edit` requests an admin-approved capability — a plain handshake token is
-never admin, and `npx @odla-ai/cli whoami` tells you what you hold.
+never admin, and `npx --yes @odla-ai/cli@latest whoami` tells you what you hold.
 
-⏸ That request prints the same canonical approval block. **Use browser control
-to open its URL immediately; if unavailable, give it to the human verbatim.**
-You cannot approve it yourself — the grant is issued to you, not by you — and
-the command blocks until a signed-in admin approves it. Never wait silently or
-start a substitute handshake because the automatic opener produced no tab.
+⏸ That request prints the same canonical approval block. Follow the agent
+handshake protocol: run with `--no-open --wait 600`, immediately surface its
+clickable URL and code to the human, and preserve that foreground process. You
+cannot approve it yourself — the grant is issued to you, not by you — and the
+command blocks until a signed-in admin approves it.
 If approval is not available, comment on the runbook instead so an admin can fix
 it later.
 
-`npx @odla-ai/cli doctor` is an offline config check anytime;
-`npx @odla-ai/cli smoke --env dev` verifies a live deployment from local
+`npx --yes @odla-ai/cli@latest doctor` is an offline config check anytime;
+`npx --yes @odla-ai/cli@latest smoke --env dev` verifies a live deployment from local
 service credentials. After `provision --push-secrets`, use
-`npx @odla-ai/cli smoke --env dev --runtime`; it verifies the Worker and
+`npx --yes @odla-ai/cli@latest smoke --env dev --runtime`; it verifies the Worker and
 anonymous integration routes without retrieving its db/o11y secrets.
+When `o11y.monitoring` is configured, apply its repository-owned Kitesurf or
+existing-o11y performance indicators, cadence, SLOs, and email schedule with `monitor plan` followed by
+`monitor apply` (`--yes` for prod). For unattended diagnosis, prefer
+`monitor status --json`, `monitor incidents --runs --json`, and
+`monitor report --period weekly --json`. Treat `bad` as application evidence;
+`monitor_error` and `missed` mean the monitoring system is uncertain and must
+not be reported as app downtime or success; this includes no request data and
+stale canaries. The returned documents deliberately exclude page content. Use
+`monitor run <probe-id> --json` for a bounded manual Kitesurf check;
+manual outcomes never enter the scheduled SLO denominator.
 Use `calendar status --json` for safe connection state (`bookable`, booking
 and availability calendars) and `calendar calendars --json` to discover ids
 after consent; update checked-in config and re-provision. Disconnect always

package/skills/odla/references/agent-identity.md

@@ -18,8 +18,8 @@ checkout that first obtained the credential.
 ## 1. Save non-secret context outside the checkout
 
 ```cmd
-npx @odla-ai/cli context save delivery --platform https://odla.ai --app <appId> --env prod
-npx @odla-ai/cli context show --context delivery --json
+npx --yes @odla-ai/cli@latest context save delivery --platform https://odla.ai --app <appId> --env prod
+npx --yes @odla-ai/cli@latest context show --context delivery --json
 ```
 
 The context stores only platform/app/environment metadata. Its private token
@@ -34,7 +34,7 @@ exists, the CLI starts the normal email-bound device handshake and prints the
 exact Studio approval URL.
 
 ```cmd
-npx @odla-ai/cli whoami --context delivery --email <account-email> --json
+npx --yes @odla-ai/cli@latest whoami --context delivery --email <account-email> --json
 ```
 
 In Studio, review the exact code, requested handle, projects, and capabilities.
@@ -47,8 +47,8 @@ project in every checkout and worktree.
 After approval and collection, verify the selected identity and context:
 
 ```cmd
-npx @odla-ai/cli whoami --context delivery --json
-npx @odla-ai/cli pm next --context delivery --json
+npx --yes @odla-ai/cli@latest whoami --context delivery --json
+npx --yes @odla-ai/cli@latest pm next --context delivery --json
 ```
 
 If the agent request omits the handle, Registry deliberately creates a new

package/skills/odla/references/build.md

@@ -5,7 +5,7 @@ Exact commands, verified against `@odla-ai/cli`. ⏸ marks a human step.
 ## 1. Scaffold
 
 ```
-npx @odla-ai/cli init --app-id my-app --name "My App"
+npx --yes @odla-ai/cli@latest init --app-id my-app --name "My App"
 ```
 
 Writes `odla.config.mjs`, `src/odla/schema.mjs`, `src/odla/rules.mjs`, and adds
@@ -48,7 +48,7 @@ vendor docs, never memorized steps.
 ## 3. Provision  ⏸ device-code approval
 
 ```
-npx @odla-ai/cli provision --email <existing-odla-account> --write-dev-vars --push-secrets
+npx --yes @odla-ai/cli@latest provision --email <existing-odla-account> --write-dev-vars --push-secrets --no-open --wait 600
 ```
 
 The email is an account identifier, never a password or session credential.
@@ -61,7 +61,7 @@ o11y ingest token when o11y is enabled), pushes the composed app + integration
 schema/rules, creates missing guarded seeds, writes
 `.dev.vars`, and transfers configured Worker secrets through Wrangler stdin.
 Local credential files are `0600` and gitignored. Verify with
-`npx @odla-ai/cli doctor` — it prints the app, envs, services, integrations, and flags
+`npx --yes @odla-ai/cli@latest doctor` — it prints the app, envs, services, integrations, and flags
 anything unset. `--push-secrets` preflights the Wrangler config and login before
 issuing or rotating a shown-once credential.
 
@@ -76,9 +76,10 @@ mutations remain direct-human operations.
 
 If provision reports that the selected agent credential has no live
 `app.manage` grant, retries cannot add authority. Run
-`npx @odla-ai/cli provision --request-grant --email <existing-odla-account>
---write-dev-vars --push-secrets`. This deliberately ignores `ODLA_DEV_TOKEN`
-and the local token cache, prints/opens a fresh exact-project review URL, and
+`npx --yes @odla-ai/cli@latest provision --request-grant --email <existing-odla-account>
+--write-dev-vars --push-secrets --no-open --wait 600`. This deliberately
+ignores `ODLA_DEV_TOKEN` and the local token cache, prints a fresh exact-project
+review URL, and
 continues with the approved replacement credential. Remove an explicit
 `--token`; a supplied credential cannot approve authority for itself.
 
@@ -87,7 +88,7 @@ prints/opens a state-bound Google URL issued by the platform and waits while
 the human grants the booking scopes in a browser. The CLI never receives the
 Google callback code or tokens, and nothing syncs afterward — Google stays
 the single source of truth. Once connected, run
-`npx @odla-ai/cli calendar calendars --env dev --json`, refine the checked-in
+`npx --yes @odla-ai/cli@latest calendar calendars --env dev --json`, refine the checked-in
 calendar ids if needed, re-provision, and verify `calendar status --env dev`
 reports `bookable: yes`.
 
@@ -95,7 +96,7 @@ The CLI stops at the source boundary: it verifies but does not invent your
 application semantics. Do not use Studio to mint a routine o11y token. Manual
 Studio rotation is recovery-only;
 normal replacement is
-`npx @odla-ai/cli provision --rotate-o11y-token --push-secrets` after explicit
+`npx --yes @odla-ai/cli@latest provision --rotate-o11y-token --push-secrets` after explicit
 human approval.
 
 ## 4. Run locally
@@ -139,17 +140,17 @@ Optional hosted follow-up (human must explicitly approve redacted tracked-source
 disclosure under the configured providers' retention/residency terms):
 
 ```
-npx @odla-ai/cli security run . --env dev --ack-redacted-source
+npx --yes @odla-ai/cli@latest security run . --env dev --ack-redacted-source
 ```
 
 For a repeatable commit-pinned job after the human approves the read-only
 GitHub App:
 
 ```
-npx @odla-ai/cli security github connect --env dev
-npx @odla-ai/cli security plan --env dev
-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 --yes @odla-ai/cli@latest security github connect --env dev
+npx --yes @odla-ai/cli@latest security plan --env dev
+npx --yes @odla-ai/cli@latest security sources --env dev
+npx --yes @odla-ai/cli@latest security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
 ```
 
 The CLI infers the repository from a safe GitHub origin, never requests a PAT
@@ -170,7 +171,7 @@ supplied one. Surface either without looping or manufacturing a provider key.
 Initialize live after the sandbox is healthy (prod tenant = the bare `appId`), then:
 
 ```
-npx @odla-ai/cli provision --live --yes --push-secrets  # prod mutation + configured Worker secrets
+npx --yes @odla-ai/cli@latest provision --live --yes --push-secrets  # prod mutation + configured Worker secrets
 npx wrangler deploy
 ```
 
@@ -180,5 +181,5 @@ should manage sandbox and live together. If calendar is enabled, predeclare
 `calendar.google.availabilityCalendars.prod`; the live Google connection still
 has its own consent checkpoint.
 
-Verify with `npx @odla-ai/cli smoke --env prod`. Point env vars at the service
+Verify with `npx --yes @odla-ai/cli@latest smoke --env prod`. Point env vars at the service
 custom domains, never `*.workers.dev` (Workers can't fetch same-account workers.dev).

package/skills/odla/references/co-owners.md

@@ -25,7 +25,7 @@ records who co-owns an app; the db honors any co-owner when they provision.
    primary owner:
 
    ```cmd
-   npx @odla-ai/cli provision --email teammate@example.com --write-dev-vars --push-secrets
+   npx --yes @odla-ai/cli@latest provision --email teammate@example.com --write-dev-vars --push-secrets --no-open --wait 600
    ```
 
    provision verifies the existing app (it does not re-create it), mints the

package/skills/odla/references/pm-work-intake.md

@@ -16,9 +16,9 @@ for the current chat and should name the PM goal and task references.
 ## 1. Resolve context and read authoritative state
 
 ```cmd
-npx @odla-ai/cli context show --context <profile>
-npx @odla-ai/cli pm next --app <appId> --json
-npx @odla-ai/cli pm handoff --app <appId> --json
+npx --yes @odla-ai/cli@latest context show --context <profile>
+npx --yes @odla-ai/cli@latest pm next --app <appId> --json
+npx --yes @odla-ai/cli@latest pm handoff --app <appId> --json
 ```
 
 Read any existing Doing task before selecting another. For each candidate, read
@@ -53,9 +53,9 @@ Create/refine the task with one alignment source, an actionable description,
 acceptance criteria, and execution mode:
 
 ```cmd
-npx @odla-ai/cli pm task add --app <appId> --title "<work>" --goal <goal-id> --description "<bounded work>" --acceptance "<observable proof>" --execution agent
-npx @odla-ai/cli pm task get <task-id> --json
-npx @odla-ai/cli pm task ready <task-id> --expected-revision <revision>
+npx --yes @odla-ai/cli@latest pm task add --app <appId> --title "<work>" --goal <goal-id> --description "<bounded work>" --acceptance "<observable proof>" --execution agent
+npx --yes @odla-ai/cli@latest pm task get <task-id> --json
+npx --yes @odla-ai/cli@latest pm task ready <task-id> --expected-revision <revision>
 ```
 
 Use `--alignment-decision <decision-id>` instead of `--goal` only for an
@@ -72,8 +72,8 @@ silently become its executor.
 Review the latest task revision immediately before claiming:
 
 ```cmd
-npx @odla-ai/cli pm task get <task-id> --json
-npx @odla-ai/cli pm task claim <task-id> --expected-revision <revision>
+npx --yes @odla-ai/cli@latest pm task get <task-id> --json
+npx --yes @odla-ai/cli@latest pm task claim <task-id> --expected-revision <revision>
 ```
 
 Only one concurrent caller can win. On conflict, reload `pm next` and the task;
@@ -110,7 +110,7 @@ later. Reserve `pm ... ref <id>` for structured odla Discussion markup.
 If the claimant must stop:
 
 ```cmd
-npx @odla-ai/cli pm task release <task-id> --expected-revision <revision>
+npx --yes @odla-ai/cli@latest pm task release <task-id> --expected-revision <revision>
 ```
 
 Comment with the branch/worktree, last verified commit, unfinished step, and
@@ -124,9 +124,9 @@ Establish a checkpoint before waiting for PM lifecycle changes, persist every
 checkpoint record, and resume with its opaque cursor:
 
 ```cmd
-npx @odla-ai/cli pm watch --app <appId> --entity task --jsonl
-npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --state ready --self <principal-id> --jsonl
-npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --action comment.created --self <principal-id> --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --entity task --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --cursor <cursor> --entity task --state ready --self <principal-id> --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --cursor <cursor> --entity task --action comment.created --self <principal-id> --jsonl
 ```
 
 Delivery is at least once. Deduplicate by `eventId`; advance durable consumer

package/skills/odla/references/pm.md

@@ -49,23 +49,23 @@ Entity is `goal | task | decision | bug`; every command takes `--json` for
 machine-readable output.
 
 ```cmd
-npx @odla-ai/cli pm bug add --app <appId> --title "Checkout 500s on retry" --severity high --desc "…"
+npx --yes @odla-ai/cli@latest pm bug add --app <appId> --title "Checkout 500s on retry" --severity high --desc "…"
 ```
 
 ```cmd
-npx @odla-ai/cli pm bug list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm bug list --app <appId> --status open
 ```
 
 ```cmd
-npx @odla-ai/cli pm next --app <appId>
+npx --yes @odla-ai/cli@latest pm next --app <appId>
 ```
 
 ```cmd
-npx @odla-ai/cli pm task claim <id> --expected-revision <n>
+npx --yes @odla-ai/cli@latest pm task claim <id> --expected-revision <n>
 ```
 
 ```cmd
-npx @odla-ai/cli pm decision list --q "stripe"
+npx --yes @odla-ai/cli@latest pm decision list --q "stripe"
 ```
 
 - `add` needs `--app <appId>` and `--title`; it takes the entity's own fields
@@ -116,8 +116,8 @@ the request in PM but do not require them to repeat it with a Ready transition.
 write:
 
 ```cmd
-npx @odla-ai/cli context show --context <profile>
-npx @odla-ai/cli pm next --app <appId>
+npx --yes @odla-ai/cli@latest context show --context <profile>
+npx --yes @odla-ai/cli@latest pm next --app <appId>
 ```
 
 Then read `pm bug list --app <appId> --status open` and
@@ -167,13 +167,13 @@ Discussion markup uses stable typed references. Prefer it over pasting a title
 that can be renamed:
 
 ```cmd
-npx @odla-ai/cli pm task ref <task-id>
+npx --yes @odla-ai/cli@latest pm task ref <task-id>
 ```
 
 Paste the returned markup into `--markup`, alongside other references:
 
 ```cmd
-npx @odla-ai/cli discuss post --app <appId> --subject "Ready for review" --markup "Review @[Checkout retries](pm:task/<task-id>) for @[Retry safety](pm:goal/<goal-id>)."
+npx --yes @odla-ai/cli@latest discuss post --app <appId> --subject "Ready for review" --markup "Review @[Checkout retries](pm:task/<task-id>) for @[Retry safety](pm:goal/<goal-id>)."
 ```
 
 The same copied `pm:*` markup works in an item's own PM comment. It is stored as
@@ -181,8 +181,8 @@ a structured reference, rendered as a PM chip, and printed as markup again by
 the `comments` command:
 
 ```cmd
-npx @odla-ai/cli pm task comment <task-id> --body "Blocked by @[Retry safety](pm:goal/<goal-id>)."
-npx @odla-ai/cli pm task comments <task-id>
+npx --yes @odla-ai/cli@latest pm task comment <task-id> --body "Blocked by @[Retry safety](pm:goal/<goal-id>)."
+npx --yes @odla-ai/cli@latest pm task comments <task-id>
 ```
 
 Use `pm:task`, `pm:goal`, `pm:decision`, `pm:bug`, and `pm:runbook`. The message
@@ -237,9 +237,9 @@ For work that must run from several worktrees or another project, save a named,
 non-secret operator context and select it explicitly:
 
 ```cmd
-npx @odla-ai/cli context save delivery --platform https://odla.ai --app <appId>
-npx @odla-ai/cli context show --context delivery
-npx @odla-ai/cli pm next --context delivery
+npx --yes @odla-ai/cli@latest context save delivery --platform https://odla.ai --app <appId>
+npx --yes @odla-ai/cli@latest context show --context delivery
+npx --yes @odla-ai/cli@latest pm next --context delivery
 ```
 
 The selected profile uses a user-level private credential cache instead of the
@@ -258,9 +258,9 @@ Every goal/task/decision/bug create/update/delete appends an immutable event
 snapshot in the same transaction. Consume the exact-project stream with:
 
 ```cmd
-npx @odla-ai/cli pm watch --app <appId> --jsonl
-npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --state ready --self <principal-id> --jsonl
-npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --action comment.created --self <principal-id> --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --cursor <cursor> --entity task --state ready --self <principal-id> --jsonl
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --cursor <cursor> --entity task --action comment.created --self <principal-id> --jsonl
 ```
 
 The first call establishes a checkpoint and intentionally does not replay old

package/skills/odla/references/sdks.md

@@ -121,7 +121,7 @@ recordError(err, { route, code });                   // structured errors
 ```
 
 When `o11y` is in `services`, run
-`npx @odla-ai/cli provision --write-dev-vars --push-secrets`. The CLI enables
+`npx --yes @odla-ai/cli@latest provision --write-dev-vars --push-secrets`. The CLI enables
 the service, issues or reuses its token, persists it locally, writes
 `.dev.vars`, and transfers `ODLA_O11Y_TOKEN` to the Worker over Wrangler stdin.
 With a token present, the SDK defaults `ODLA_O11Y_ENDPOINT` to
@@ -151,7 +151,7 @@ npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on
 ```
 
 Deterministic rules emit leads. After explicit redacted-source approval, run
-`npx @odla-ai/cli security run . --env dev --ack-redacted-source` for hosted,
+`npx --yes @odla-ai/cli@latest security run . --env dev --ack-redacted-source` for hosted,
 app-attributed discovery and independent validation. It obtains owner auth and
 never asks for provider keys. The lower-level library flow remains available
 for custom orchestrators; active reproduction still requires an explicitly

package/skills/odla-migrate/SKILL.md

@@ -65,6 +65,24 @@ installed skill at `../odla/SKILL.md` instead.
    Read `references/project-state.md` before recording or resuming work. Never
    put credentials or secret values in PM.
 
+## Agent handshake protocol
+
+Run the current published CLI with browser auto-launch suppressed and keep the
+authorization command as one foreground tool process:
+
+```bash
+npx --yes @odla-ai/cli@latest auth login --app <appId> --email <odla-account> --no-open --wait 600
+```
+
+Immediately surface the printed `/studio?code=` URL as a clickable human action,
+repeat the code to verify, and tell the human to click **Approve**. Wait on the
+same process; the CLI owns protocol polling. Never call the OS `open` command,
+use browser control, curl a handshake endpoint, create a shell polling/wait
+loop, detach the process, or start a substitute handshake. The device code
+exists only in the running CLI. If it exits 75, its old URL cannot be collected;
+start one fresh foreground invocation and surface only the new URL. Use the same
+`--no-open --wait 600` flags when provision itself needs a reviewed capability.
+
 ## Phase state machine
 
 Phases run strictly in order; each has a verification gate:
@@ -75,7 +93,7 @@ Phases run strictly in order; each has a verification gate:
 PM is the durable state: goals define the migration gates, board tasks show the
 active phase, decisions preserve product and architecture choices, bugs capture
 defects, and comments carry evidence. In a fresh session, query PM first as
-specified in `references/project-state.md`; `npx @odla-ai/cli doctor` then
+specified in `references/project-state.md`; `npx --yes @odla-ai/cli@latest doctor` then
 confirms the checked-in config state.
 
 ## Auth model (one line)
@@ -100,14 +118,14 @@ so this is a natural first step.
 
 ## Verification tools
 
-- `npx @odla-ai/cli capabilities --json` — authoritative automation boundary;
+- `npx --yes @odla-ai/cli@latest capabilities --json` — authoritative automation boundary;
   run once when orienting so source edits and human checkpoints are not confused
   with CLI-owned platform/credential work.
-- `npx @odla-ai/cli doctor` — offline config/schema/rules validation; run
+- `npx --yes @odla-ai/cli@latest doctor` — offline config/schema/rules validation; run
   after any config edit.
-- `npx @odla-ai/cli provision --dry-run` — the plan, zero network/file I/O;
+- `npx --yes @odla-ai/cli@latest provision --dry-run` — the plan, zero network/file I/O;
   show it to the human before the first real provision.
-- `npx @odla-ai/cli smoke --env dev` — live, read-only: public-config, live
+- `npx --yes @odla-ai/cli@latest smoke --env dev` — live, read-only: public-config, live
   schema diff, a count aggregate. Run after every provision.
 - `wrangler dev` + curl — exercise routes locally before deploying.
 - Contract probes — compare old and new method/auth/request/response schemas,

package/skills/odla-migrate/references/phase-2-chapter.md

@@ -50,7 +50,7 @@ hand-author only the namespaces it does not.
    `/admin/#people/person/record-id/profile`; keep legacy query/path links only
    as inbound compatibility URLs.
 6. **Override rather than inherit wherever local behavior was a decision.**
-7. `npx @odla-ai/cli doctor` → `provision --dry-run` (show the human) → provision.
+7. `npx --yes @odla-ai/cli@latest doctor` → `provision --dry-run` (show the human) → provision.
 
 ### Existing admin workspace gate
 

package/skills/odla-migrate/references/phase-2-db.md

@@ -7,9 +7,10 @@ schema + deny-all rules, the db key in the dev worker, and first
 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
-attempts to open the one canonical review URL in every real CLI environment.
-Agents with browser control open that exact URL immediately; loading it alone
-is inert until the signed-in human approves.
+waits for the one canonical review URL. Agents run it with
+`--no-open --wait 600`, immediately surface that URL and code as a clickable
+human checkpoint, and preserve the same foreground CLI process. Loading the
+URL alone is inert until the signed-in human clicks **Approve**.
 
 ## Steps
 
@@ -18,7 +19,7 @@ is inert until the signed-in human approves.
    declarations while ODLA is under active development, commit the lockfile,
    and record the resolved graph from
    `npm ls @odla-ai/cli @odla-ai/db` in PM.
-2. `npx @odla-ai/cli init --app-id <id> --name "<Name>" --env dev --services db`
+2. `npx --yes @odla-ai/cli@latest 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** —
    copy it from that output and `curl` it (200) before pasting. NEVER predict or
@@ -45,15 +46,15 @@ is inert until the signed-in human approves.
    generated deny-all `src/odla/rules.mjs`: the worker mediates all
    access with its app key (which bypasses rules); browsers get nothing
    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 --email <existing-odla-account>
-   --write-dev-vars --push-secrets` — handshake,
+5. `npx --yes @odla-ai/cli@latest doctor` until clean.
+6. `npx --yes @odla-ai/cli@latest provision --dry-run` — show the plan to the human.
+7. `npx --yes @odla-ai/cli@latest provision --email <existing-odla-account>
+   --write-dev-vars --push-secrets --no-open --wait 600` — 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
    init — confirm with `git status`. Use
-   `npx @odla-ai/cli secrets push --env dev` only to retry the secret-transfer
+   `npx --yes @odla-ai/cli@latest secrets push --env dev` only to retry the secret-transfer
    portion (details and manual fallback: references/secrets-map.md).
 8. The app now exists. Before further implementation, follow
    `project-state.md`: create the migration goals/tasks/decisions in PM,
@@ -75,7 +76,7 @@ is inert until the signed-in human approves.
 
 ## Verification checklist
 
-- [ ] `npx @odla-ai/cli smoke --env dev` passes (public-config, schema, aggregate)
+- [ ] `npx --yes @odla-ai/cli@latest smoke --env dev` passes (public-config, schema, aggregate)
 - [ ] Routes work locally and on the deployed dev worker
 - [ ] `links.dev` set — public-config carries the URL and Studio shows it
 - [ ] `git status` shows no credential files staged