@odla-ai/cli 0.17.1 → 0.19.0

package/README.md

@@ -16,6 +16,73 @@ hosted security command.
 It does not know about any specific app. App identity, environments, services,
 schema, rules, integrations, auth, AI provider, and links all come from config.
 
+## Start with the runbooks, not this file
+
+odla's operational procedures — releasing, backups, database work, security
+setup — are **rows in a database**, not documents in a package. They are edited
+the moment a step turns out to be wrong, with no release in between. So the
+answer this CLI fetches is current, and every written copy of it (including
+this README, and including your training data) is a snapshot of some earlier
+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
+```
+
+Reading works for any signed-in developer and needs no `odla.config.mjs` — the
+advice is most useful before there is a project.
+
+**Runbooks are procedure; JSDoc is API.** What a function takes, returns, and
+guarantees is documented on the export itself, ships in the installed
+`.d.ts`, and renders per package at <https://odla.ai/docs>. A runbook will tell
+you *when* to call something and never invents a signature. Most real questions
+need both halves — take the steps from the runbook and the arguments from the
+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
+```
+
+It diffs the working tree, works out which surfaces moved — a package, its
+exported API, a JSDoc block, a console area — and names the runbooks whose steps
+describe them, with the command to read each one. Changing an exported API or
+its JSDoc is exactly when a procedure quoting that API goes stale, so run it
+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"
+```
+
+Platform runbook edits need admin or the `platform:runbook:write` capability,
+which the CLI requests for you; a plain handshake token is never admin by
+design, and `odla-ai whoami` reports what this terminal actually holds.
+
+**Is the corpus itself still true?**
+
+```bash
+npx odla-ai runbook lint
+```
+
+Because a runbook is edited without a release, its text can name a command that
+only a newer CLI has — and no gate in any repository can see that, since the
+text is a row in a database rather than a file. `lint` closes that: it holds
+every `odla-ai …` command the runbooks name against this CLI's actual command
+surface, and against the minimum versions each runbook declares in `requires`.
+
+A runbook may record the versions its steps assume, as `name@version` specs read
+as minimums (`@odla-ai/cli@0.18.0`). When yours is older, `runbook get` says so
+on **stderr** — never stdout, so piping the procedure into an agent still yields
+the procedure and nothing else.
+
 ## Install
 
 No install needed — the package ships a single `odla-ai` binary, so npx can run
@@ -54,13 +121,21 @@ npm i -D --save-exact @odla-ai/cli@0.16.6
 ## 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 whoami
 npx odla-ai setup
 npx odla-ai init --app-id my-app --name "My App"
 npx odla-ai doctor
 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 resync --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
@@ -260,19 +335,18 @@ agent automation. Once connected, `calendar calendars` lists ids visible to the
 Google identity so the checked-in selection can be refined. `calendar connect`
 applies the checked-in booking-page setting and starts consent when the
 connection is absent, failed, disconnected, or degraded (so an agent can
-repair revoked credentials); a healthy connection is reused. A `needs_sync`
-connection already has provider credentials, so connect/provision resyncs it
-without requesting Google consent again; an existing authorization or initial
-sync is awaited instead of creating a duplicate attempt.
-`calendar resync` asks the hosted connector to sync immediately; `calendar
-disconnect --yes` stops watches and deletes this app/environment connection's
-encrypted platform token and cursors without purging retained mirror rows,
-which may therefore remain readable but stale. It does not revoke the shared
-user-to-Google-OAuth-project grant, because that could invalidate other odla
-connections for the same user. A future explicitly global revoke command would
-need cross-connection accounting and warning. Production resync requires
-`--yes`, as does a direct production connect. None of these commands accepts a
-Google authorization code, client secret, access token, or refresh token.
+repair revoked credentials); a healthy connection is reused. A connection that
+already holds provider credentials is reused without requesting Google consent
+again, and an in-flight authorization is awaited rather than duplicated.
+
+Nothing syncs: Google Calendar is the source of truth and odla stores no events
+and no attendees, so there is no resync to ask for. `calendar disconnect --yes`
+deletes this app/environment connection's encrypted platform token. It does not
+revoke the shared user-to-Google-OAuth-project grant, because that could
+invalidate other odla connections for the same user. A future explicitly global
+revoke command would need cross-connection accounting and warning. A direct
+production connect requires `--yes`. None of these commands accepts a Google
+authorization code, client secret, access token, or refresh token.
 
 The SDK uses the existing server-side db values (`ODLA_ENDPOINT`,
 `ODLA_TENANT`, `ODLA_API_KEY`), so calendar adds no Worker secret. Never expose