@odla-ai/cli 0.33.0 → 0.34.1

package/README.md

@@ -30,10 +30,10 @@ day.
 Ask before you search the web or work from memory:
 
 ```bash
-npx @odla-ai/cli runbook ask "how do I roll back a bad publish?"   # written, cited answer
-npx @odla-ai/cli runbook search "restore a tenant"                 # the passages behind it
-npx @odla-ai/cli runbook get release                               # the whole procedure
-npx @odla-ai/cli runbook list                                      # what exists
+npx --yes @odla-ai/cli@latest runbook ask "how do I roll back a bad publish?"   # written, cited answer
+npx --yes @odla-ai/cli@latest runbook search "restore a tenant"                 # the passages behind it
+npx --yes @odla-ai/cli@latest runbook get release                               # the whole procedure
+npx --yes @odla-ai/cli@latest runbook list                                      # what exists
 ```
 
 Reading works for any signed-in developer and needs no `odla.config.mjs` — the
@@ -45,9 +45,9 @@ Before an agent reads PM, Discussions, o11y, runbooks, or identity from a fresh
 workspace, it can explain the selected context without authenticating:
 
 ```bash
-npx @odla-ai/cli context show --platform https://odla.ai --app <appId> --env prod --json
-npx @odla-ai/cli context save production --platform https://odla.ai --app <appId> --env prod
-npx @odla-ai/cli context show --context production --json
+npx --yes @odla-ai/cli@latest context show --platform https://odla.ai --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest context save production --platform https://odla.ai --app <appId> --env prod
+npx --yes @odla-ai/cli@latest context show --context production --json
 ```
 
 For each value, an explicit flag wins over the matching
@@ -81,13 +81,13 @@ project. The installed `references/agent-identity.md` runbook gives the full
 cross-worktree recovery procedure.
 
 ```bash
-ODLA_DEV_TOKEN=... npx @odla-ai/cli pm handoff --app <appId>
-ODLA_DEV_TOKEN=... npx @odla-ai/cli discuss list --app <appId> --json
-ODLA_DEV_TOKEN=... npx @odla-ai/cli o11y status --app <appId> --env prod --json
-ODLA_DEV_TOKEN=... npx @odla-ai/cli whoami --json
-npx @odla-ai/cli platform status --context production --json
-npx @odla-ai/cli pm handoff --context production --json
-npx @odla-ai/cli runbook new deploy --context production --title Deploy --file deploy.md
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest pm handoff --app <appId>
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest discuss list --app <appId> --json
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest o11y status --app <appId> --env prod --json
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest whoami --json
+npx --yes @odla-ai/cli@latest platform status --context production --json
+npx --yes @odla-ai/cli@latest pm handoff --context production --json
+npx --yes @odla-ai/cli@latest runbook new deploy --context production --title Deploy --file deploy.md
 ```
 
 Runbooks tell an agent how to operate; PM tells every agent what this project is
@@ -96,15 +96,15 @@ app is registered, start each session with the read-only aligned-work intake,
 then read open bugs and recent decisions:
 
 ```bash
-npx odla-ai pm project list --app <productId>
-npx odla-ai pm project add --app <productId> --name "My project"
-npx odla-ai pm project use <projectId>
-npx odla-ai pm next --app <appId> --project <projectId>
-npx odla-ai pm handoff --app <appId>
-npx odla-ai pm watch --app <appId> --entity task --jsonl
-npx odla-ai pm bug list --app <appId> --status open
-npx odla-ai pm goal list --app <appId> --status open
-npx odla-ai pm decision list --app <appId> --limit 20
+npx --yes @odla-ai/cli@latest pm project list --app <productId>
+npx --yes @odla-ai/cli@latest pm project add --app <productId> --name "My project"
+npx --yes @odla-ai/cli@latest pm project use <projectId>
+npx --yes @odla-ai/cli@latest pm next --app <appId> --project <projectId>
+npx --yes @odla-ai/cli@latest pm handoff --app <appId>
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --entity task --jsonl
+npx --yes @odla-ai/cli@latest pm bug list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm goal list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm decision list --app <appId> --limit 20
 ```
 
 `pm handoff` is the authoritative unresolved-state view: unmet goals, every
@@ -129,8 +129,8 @@ Refine a Backlog task with `--goal` (or an accepted
 and claim the reviewed revision:
 
 ```bash
-npx odla-ai pm task ready <id> --expected-revision <n>
-npx odla-ai pm task claim <id> --expected-revision <n>
+npx --yes @odla-ai/cli@latest pm task ready <id> --expected-revision <n>
+npx --yes @odla-ai/cli@latest pm task claim <id> --expected-revision <n>
 ```
 
 Ready is stored as `todo` for API compatibility. Claims are atomic and assign
@@ -160,7 +160,7 @@ When diagnosing a deployed app, agents can request one parseable observability
 snapshot instead of scraping Studio or composing collector routes themselves:
 
 ```bash
-npx odla-ai o11y status --app <appId> --env prod --minutes 60 --json
+npx --yes @odla-ai/cli@latest o11y status --app <appId> --env prod --minutes 60 --json
 ```
 
 Schema v9 keeps application RED, an `applicationVersions` breakdown of
@@ -186,6 +186,87 @@ jobs, missing canary configuration, stale probes, and partial
 socket-reconciliation coverage remain explicit fields. Authentication progress
 is stderr-only, so stdout is a single JSON document.
 
+Repository-controlled SLO monitoring lives under `o11y.monitoring`. Objectives
+can consume Kitesurf routes or bounded observations of existing o11y error,
+latency, and protected-canary signals. A minimal route policy detects both
+short outages and sustained error-budget burn, and sends incident and digest
+email:
+
+```js
+export default {
+  services: ["o11y"],
+  links: { prod: "https://example.com" },
+  o11y: {
+    monitoring: {
+      probes: [{
+        id: "home", route: "/", envs: ["prod"], every: "5m",
+        expect: { status: 200, titleIncludes: "Example", textIncludes: ["Welcome"] },
+      }],
+      slos: [{
+        id: "availability", name: "Public availability",
+        indicator: { type: "probe-success", probes: ["home"] },
+        target: 0.999, window: "28d",
+        alerts: {
+          spike: { badChecks: 2, withinChecks: 3, recoverAfter: 2 },
+          trend: { burnRate: 1, shortWindow: "6h", longWindow: "3d", minBadChecks: 2 },
+        },
+      }],
+      notifications: {
+        prod: {
+          email: ["oncall@example.com"], timezone: "America/Costa_Rica",
+          daily: "08:00", weekly: { day: "monday", at: "08:00" },
+        },
+      },
+    },
+  },
+};
+```
+
+For a service-performance objective, omit `probes` and select an existing o11y
+metric. The comparator describes a successful observation, so this example
+requires each five-minute request p95 to be at most 500ms:
+
+```js
+slos: [{
+  id: "request-latency", name: "Request p95 at or below 500ms",
+  indicator: {
+    type: "o11y-metric", metric: "latency_p95", comparator: "lte",
+    threshold: 500, every: "5m", observationWindow: "5m",
+  },
+  target: 0.99, window: "28d",
+}]
+```
+
+`error_rate`, `latency_p95`, `synthetic_success`, and
+`synthetic_publish_to_visible` are supported. The checked-in odla-db first
+rollout is `ops/monitoring/odla-db.config.mjs`:
+
+```bash
+npx --yes @odla-ai/cli@latest monitor plan --config ops/monitoring/odla-db.config.mjs --env prod --json
+```
+
+Preview and apply the normalized policy, then inspect or exercise it through
+stable JSON:
+
+```bash
+npx --yes @odla-ai/cli@latest monitor plan --env prod --json
+npx --yes @odla-ai/cli@latest monitor apply --env prod --yes --json
+npx --yes @odla-ai/cli@latest monitor status --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest monitor run home --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest monitor incidents --app <appId> --env prod --runs --json
+npx --yes @odla-ai/cli@latest monitor report --app <appId> --env prod --period weekly --json
+```
+
+Only scheduled `good` and `bad` outcomes enter the application SLO denominator.
+Kitesurf failures, missing Analytics Engine evidence, stale canaries, query
+failures, and scheduler gaps are retained as `monitor_error`/`missed` and
+degrade monitoring health separately, so no traffic or a broken monitor cannot
+manufacture success or downtime. Probe responses retain bounded metadata only;
+page content and accessibility trees are never returned by the CLI or stored.
+Each applied desired-state revision starts a fresh SLO event series and closes
+open incidents as `config_revision_changed`; results produced by different
+thresholds, routes, assertions, or notification policy are never blended.
+
 For platform-wide operations, `platform status --json` requests only the
 short-lived, admin-approved `platform:status:read` capability and reads the
 same `odla.platform-status/v1` snapshot as Studio. It works outside a project
@@ -204,10 +285,10 @@ For repository-managed settings, compare checked-in intent with the live
 owner-visible Registry projection before provisioning:
 
 ```bash
-npx odla-ai config diff --json
-npx odla-ai config plan --json > .odla/config-plan.json
-npx odla-ai config apply --plan .odla/config-plan.json --json
-npx odla-ai operations wait <operation-id> --json
+npx --yes @odla-ai/cli@latest config diff --json
+npx --yes @odla-ai/cli@latest config plan --json > .odla/config-plan.json
+npx --yes @odla-ai/cli@latest config apply --plan .odla/config-plan.json --json
+npx --yes @odla-ai/cli@latest operations wait <operation-id> --json
 ```
 
 `diff` and `plan` are read-only and request only a short-lived,
@@ -258,8 +339,8 @@ JSDoc, and neither from memory.
 **After you change something, ask which runbooks you invalidated:**
 
 ```bash
-npx @odla-ai/cli runbook impact               # vs origin/main, uncommitted work included
-npx @odla-ai/cli runbook impact --base HEAD~1
+npx --yes @odla-ai/cli@latest runbook impact               # vs origin/main, uncommitted work included
+npx --yes @odla-ai/cli@latest runbook impact --base HEAD~1
 ```
 
 It diffs the working tree, works out which surfaces moved — a package, its
@@ -270,7 +351,7 @@ before you call the change finished. Fixing what it finds is one command and
 takes effect immediately:
 
 ```bash
-npx @odla-ai/cli runbook edit db --note "retract replaced the null write"
+npx --yes @odla-ai/cli@latest runbook edit db --note "retract replaced the null write"
 ```
 
 Platform runbook edits need admin or the `platform:runbook:write` capability,
@@ -283,7 +364,7 @@ but never grants authority.
 **Is the corpus itself still true?**
 
 ```bash
-npx odla-ai runbook lint
+npx --yes @odla-ai/cli@latest runbook lint
 ```
 
 Because a runbook is edited without a release, its text can name a command that
@@ -300,16 +381,20 @@ the procedure and nothing else.
 ## Install
 
 No install needed — the package ships a single `odla-ai` binary, so npx can run
-it directly:
+it directly. Agents and one-off setup should resolve the current published CLI
+explicitly:
 
 ```bash
-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"
 ```
 
 For a project you keep working in, install it as a dev dependency so the
-shorter `npx odla-ai` form works. ODLA is under active development: use a normal
-dependency declaration, commit the lockfile, and let `npm ci` reproduce the
-resolved graph:
+lockfile records the CLI/runtime graph used by that application. Use
+`npx --no-install odla-ai` only when deliberately testing that pinned graph;
+agent orchestration examples use `@latest` so a stale workspace or cache does
+not silently select an older CLI. ODLA is under active development: use a
+normal dependency declaration, commit the lockfile, and let `npm ci` reproduce
+the resolved graph:
 
 ```bash
 npm view @odla-ai/cli version
@@ -338,61 +423,62 @@ npm ls @odla-ai/cli
 ## Commands
 
 ```bash
-npx odla-ai runbook ask "how do I roll back a bad publish?"
-npx odla-ai runbook search "restore a tenant" --limit 5
-npx odla-ai runbook get release
-npx odla-ai runbook list
-npx odla-ai runbook impact --base origin/main
-npx odla-ai runbook lint
-npx odla-ai runbook edit db --note "what changed"
-npx odla-ai runbook comment release --body "step 4 no longer applies"
-npx odla-ai context show --app my-app --env prod --json
-npx odla-ai whoami
-npx odla-ai setup
-npx odla-ai init --app-id my-app --name "My App"
-npx odla-ai doctor
-npx odla-ai ai models --env dev # exact models this app may select; no admin grant
-npx odla-ai config diff --json
-npx odla-ai config plan --json > .odla/config-plan.json
-npx odla-ai config apply --plan .odla/config-plan.json --json
-npx odla-ai operations get <operation-id> --json
-npx odla-ai operations wait <operation-id> --timeout 60 --json
-npx odla-ai calendar status --env dev
-npx odla-ai calendar calendars --env dev
-npx odla-ai calendar connect --env dev
-npx odla-ai calendar disconnect --env dev --yes
-npx odla-ai capabilities --json
-npx odla-ai code connect --platform https://odla.ai --app-id my-app --env dev --email owner@example.com
-npx odla-ai code connect --env prod --once # bounded enrollment + heartbeat proof
+npx --yes @odla-ai/cli@latest auth login --app my-app --email owner@example.com --no-open --wait 600
+npx --yes @odla-ai/cli@latest runbook ask "how do I roll back a bad publish?"
+npx --yes @odla-ai/cli@latest runbook search "restore a tenant" --limit 5
+npx --yes @odla-ai/cli@latest runbook get release
+npx --yes @odla-ai/cli@latest runbook list
+npx --yes @odla-ai/cli@latest runbook impact --base origin/main
+npx --yes @odla-ai/cli@latest runbook lint
+npx --yes @odla-ai/cli@latest runbook edit db --note "what changed"
+npx --yes @odla-ai/cli@latest runbook comment release --body "step 4 no longer applies"
+npx --yes @odla-ai/cli@latest context show --app my-app --env prod --json
+npx --yes @odla-ai/cli@latest whoami
+npx --yes @odla-ai/cli@latest setup
+npx --yes @odla-ai/cli@latest init --app-id my-app --name "My App"
+npx --yes @odla-ai/cli@latest doctor
+npx --yes @odla-ai/cli@latest ai models --env dev # exact models this app may select; no admin grant
+npx --yes @odla-ai/cli@latest config diff --json
+npx --yes @odla-ai/cli@latest config plan --json > .odla/config-plan.json
+npx --yes @odla-ai/cli@latest config apply --plan .odla/config-plan.json --json
+npx --yes @odla-ai/cli@latest operations get <operation-id> --json
+npx --yes @odla-ai/cli@latest operations wait <operation-id> --timeout 60 --json
+npx --yes @odla-ai/cli@latest calendar status --env dev
+npx --yes @odla-ai/cli@latest calendar calendars --env dev
+npx --yes @odla-ai/cli@latest calendar connect --env dev --no-open
+npx --yes @odla-ai/cli@latest calendar disconnect --env dev --yes
+npx --yes @odla-ai/cli@latest capabilities --json
+npx --yes @odla-ai/cli@latest code connect --platform https://odla.ai --app-id my-app --env dev --email owner@example.com --no-open
+npx --yes @odla-ai/cli@latest code connect --env prod --once --no-open # bounded enrollment + heartbeat proof
 # install SDKs, write the Worker, and create wrangler.jsonc before secret push
-npx odla-ai provision --dry-run
-npx odla-ai provision --email owner@example.com --write-dev-vars --push-secrets
+npx --yes @odla-ai/cli@latest provision --dry-run
+npx --yes @odla-ai/cli@latest provision --email owner@example.com --write-dev-vars --push-secrets --no-open --wait 600
 # recovery when the selected agent credential has no live app.manage grant
-npx odla-ai provision --request-grant --email owner@example.com --write-dev-vars --push-secrets
-npx odla-ai smoke --env dev
-npx odla-ai agent jobs --env dev --state dead_letter --json
-npx odla-ai agent retry <job-id> --env dev --json
-npx odla-ai discuss watch <topic-id> --jsonl
-npx odla-ai discuss watch <topic-id> --cursor <saved-cursor> --jsonl
-npx odla-ai secrets push --env dev
-npx odla-ai secrets set clerk_webhook_secret --env dev --stdin
-npx odla-ai secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
-npx odla-ai security run . --env dev --ack-redacted-source
-npx odla-ai security github connect --env dev # infers owner/name from git origin
-npx odla-ai security plan --env dev
-npx odla-ai security sources --env dev
-npx odla-ai security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
-npx odla-ai security status <job-id>
-npx odla-ai security report <job-id>
-npx odla-ai admin ai show --context production --email owner@example.com
-npx odla-ai admin ai models --context production
-npx odla-ai admin ai set security --context production --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
-npx odla-ai admin ai credentials --context production
-npx odla-ai admin ai credential set anthropic --context production --from-env ANTHROPIC_API_KEY
-npx odla-ai admin ai usage --context production --app-id my-app --env prod --limit 50
-npx odla-ai admin ai audit --context production --limit 25
-npx odla-ai skill install
-npx odla-ai version
+npx --yes @odla-ai/cli@latest provision --request-grant --email owner@example.com --write-dev-vars --push-secrets --no-open --wait 600
+npx --yes @odla-ai/cli@latest smoke --env dev
+npx --yes @odla-ai/cli@latest agent jobs --env dev --state dead_letter --json
+npx --yes @odla-ai/cli@latest agent retry <job-id> --env dev --json
+npx --yes @odla-ai/cli@latest discuss watch <topic-id> --jsonl
+npx --yes @odla-ai/cli@latest discuss watch <topic-id> --cursor <saved-cursor> --jsonl
+npx --yes @odla-ai/cli@latest secrets push --env dev
+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
+npx --yes @odla-ai/cli@latest security run . --env dev --ack-redacted-source
+npx --yes @odla-ai/cli@latest security github connect --env dev --no-open # infers owner/name from git origin
+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
+npx --yes @odla-ai/cli@latest security status <job-id>
+npx --yes @odla-ai/cli@latest security report <job-id>
+npx --yes @odla-ai/cli@latest admin ai show --context production --email owner@example.com --no-open
+npx --yes @odla-ai/cli@latest admin ai models --context production
+npx --yes @odla-ai/cli@latest admin ai set security --context production --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
+npx --yes @odla-ai/cli@latest admin ai credentials --context production
+npx --yes @odla-ai/cli@latest admin ai credential set anthropic --context production --from-env ANTHROPIC_API_KEY
+npx --yes @odla-ai/cli@latest admin ai usage --context production --app-id my-app --env prod --limit 50
+npx --yes @odla-ai/cli@latest admin ai audit --context production --limit 25
+npx --yes @odla-ai/cli@latest skill install
+npx --yes @odla-ai/cli@latest version
 ```
 
 Before a non-dry provisioning run, the executable verifies two independent
@@ -472,8 +558,8 @@ New configs contain only the `dev` environment. After the development flow is
 healthy, initialize the existing app's live instance without editing the config:
 
 ```sh
-npx @odla-ai/cli provision --live --dry-run
-npx @odla-ai/cli provision --live --yes --push-secrets
+npx --yes @odla-ai/cli@latest provision --live --dry-run
+npx --yes @odla-ai/cli@latest provision --live --yes --push-secrets
 ```
 
 `--live` targets only `prod`, enables every configured service, provisions its
@@ -514,16 +600,22 @@ credential set.
    the exact project id does not exist yet, approval reserves that id for this
    credential instead of failing: the credential may create only that app once,
    and Registry binds its reviewed grant to the new app incarnation.
-   Every real CLI handshake prints exactly one canonical `/studio?code=…` URL
-   and attempts to open it — including from CI, SSH, display-less, scripted,
-   and agent-driven shells. Only `--no-open` suppresses the attempt. Browser
-   launch is best-effort: an agent with browser control must open that exact URL
-   immediately; otherwise it gives the URL to the human verbatim. The device
-   code stays only in the running process. Outside an interactive terminal the
-   approval wait is capped (90 seconds by default; `--wait <seconds>`
-   overrides), and a still-pending handshake exits with code 75. Rerunning
-   always requests and opens a new code; it never resumes an older request from
-   `.odla/`.
+   Every real CLI handshake prints exactly one canonical `/studio?code=…` URL.
+   Interactive humans may use the CLI's best-effort browser launch. Agents use
+   the current published CLI with `--no-open --wait 600`, immediately surface
+   that exact URL and code as a clickable human approval action, and preserve
+   the same foreground process:
+
+   ```bash
+   npx --yes @odla-ai/cli@latest auth login --app <appId> --email <odla-account> --no-open --wait 600
+   ```
+
+   The CLI owns protocol polling. An agent must not call OS `open`, use browser
+   control, curl a handshake endpoint, build a shell wait loop, detach the
+   process, or start a substitute handshake. The device code stays only in the
+   running process. If that process exits 75, the old code cannot be collected;
+   a later invocation requests a new code and never resumes an older request
+   from `.odla/`.
 2. Creates the platform app if needed. For a new id, this consumes the exact-id
    reservation approved in step 1; it is not ambient project-creation authority.
 3. Enables configured services in every configured environment. Calendar
@@ -568,8 +660,8 @@ working sibling runtime.
 Inventory and retire one successful deployment without disturbing any sibling:
 
 ```sh
-npx @odla-ai/cli credentials list --env dev
-npx @odla-ai/cli credentials revoke <receipt-id>
+npx --yes @odla-ai/cli@latest credentials list --env dev
+npx --yes @odla-ai/cli@latest credentials revoke <receipt-id>
 ```
 
 The inventory contains only receipt, target, state, and timestamp metadata.
@@ -580,7 +672,7 @@ Verify a deployment that intentionally keeps db/o11y credentials only on the
 Worker:
 
 ```sh
-npx @odla-ai/cli smoke --env dev --runtime
+npx --yes @odla-ai/cli@latest smoke --env dev --runtime
 ```
 
 Runtime smoke never reads `.odla/credentials.local.json`. It checks Registry
@@ -742,10 +834,10 @@ or SSH `origin`; pass `--repo owner/name` when it cannot. It opens GitHub's
 installation/authorization page and polls that exact odla attempt:
 
 ```bash
-npx odla-ai security github connect --env dev
-npx odla-ai security plan --env dev
-npx odla-ai security sources --env dev
-npx odla-ai 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 --no-open
+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
 ```
 
 `security plan` is the owner-readable disclosure preflight. It shows the exact
@@ -868,7 +960,7 @@ LLM-usage records. The human owns the device approval, production consent, and
 explicit destructive rotation. Studio is where people view telemetry and
 perform manual recovery, configure System AI, and inspect app/run-attributed
 platform usage; its o11y token control is not the normal setup path.
-Run `npx odla-ai capabilities` for the human-readable contract or add `--json`
+Run `npx --yes @odla-ai/cli@latest capabilities` for the human-readable contract or add `--json`
 when an agent or tool needs to branch on it without scraping prose.
 
 `setup` (and `skill install`) installs one complete offline runbook bundle at

package/REQUIREMENTS.md

@@ -60,6 +60,12 @@ Agnacl, but none should mention or special-case Agnacl.
 - Every real CLI handshake must attempt to open that canonical approval URL,
   including in CI, SSH, display-less, and agent-driven shells. `--no-open` is
   the only production suppression; failures must visibly repeat the manual action.
+- Installed agent instructions must require `--no-open --wait 600`, an explicit
+  clickable human approval checkpoint, and preservation of the same foreground
+  CLI process. They must prohibit OS `open`, browser-control opening, direct
+  handshake polling, shell wait loops, detached execution, and replacement
+  handshakes while that process is alive. Exit 75 must be described as loss of
+  the in-memory device code; a later invocation creates a fresh code.
 - Cached developer tokens must be mode `0600`, gitignored, and reused until
   expiry.
 - Minted developer tokens must have a metadata-only inventory (owner, label,