@odla-ai/cli 0.17.0 → 0.18.0

package/README.md

@@ -16,6 +16,56 @@ 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.
+
 ## Install
 
 No install needed — the package ships a single `odla-ai` binary, so npx can run
@@ -54,6 +104,14 @@ 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 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