k9o 1.2.0 → 1.4.0

data/README.md

@@ -1,8 +1,7 @@
 # k9o
 
-The Kilimanjaro platform SDK for Ruby.
-
-Kilimanjaro is an AI-native platform on a Governed Database. Its products are Keep (AI Security and Governance), Pulse (Data Intelligence), Gate (Customer Identity and Access Management) and Kibo (Keys and Secrets Management).
+Client for Kilimanjaro. Read and write your data, store files, manage policies and migrations,
+deploy and invoke agents or functions, and publish to and subscribe to streams and realtime events.
 
 ## Contents
 
@@ -11,8 +10,15 @@ Kilimanjaro is an AI-native platform on a Governed Database. Its products are Ke
 - [Quick start](#quick-start)
 - [Authentication and project context](#authentication-and-project-context)
 - [Running queries](#running-queries)
+- [Query with SQL](#query-with-sql)
+- [Search](#search)
+- [Streams](#streams)
+- [Approvals](#approvals)
+- [Approval policies](#approval-policies)
+- [Schema collections](#schema-collections)
 - [Handling errors](#handling-errors)
 - [Appendix](#appendix)
+  - [About Kilimanjaro](#about-kilimanjaro)
 - [License](#license)
 
 ## Links
@@ -25,13 +31,13 @@ Kilimanjaro is an AI-native platform on a Governed Database. Its products are Ke
 ## Install
 
 ```bash
-gem install k9o
+gem install k9o -v 1.4.0
 ```
 
 Or add it to your `Gemfile`:
 
 ```ruby
-gem "k9o"
+gem "k9o", "1.4.0"
 ```
 
 Requires Ruby 3.2 or newer. See [requirements](#requirements) for details.
@@ -57,11 +63,11 @@ k9o = K9o.create_client(
 ```ruby
 new_task = { "title" => "Write the README", "done" => false }
 created = k9o.from("tasks").insert(new_task)
-puts "created: #{created.data['title']}"
+puts "Output: #{created.data['title']}"
 ```
 
 ```text
-created: Write the README
+Output: Write the README
 ```
 
 ### List tasks
@@ -69,12 +75,12 @@ created: Write the README
 ```ruby
 response = k9o.from("tasks").select.eq("done", false).limit(10).execute
 response.data.each do |task|
-  puts "#{task['title']} #{task['done']}"
+  puts "Output: #{task['title']} #{task['done']}"
 end
 ```
 
 ```text
-Write the README false
+Output: Write the README false
 ```
 
 ### Update and delete a task
@@ -97,27 +103,28 @@ The client needs a key and, for project calls, an org and project.
 | Option | What it does |
 |---|---|
 | `api_key:` | Bearer token sent with every request. |
-| `org_slug:` | Organization. On the default host the SDK uses `https://<org_slug>.api.k9o.io`. |
+| `org_slug:` | Organization. The SDK builds `https://<org_slug>.<host>` from the platform host. |
 | `project_slug:` | Project. Required by every project-scoped namespace. |
 
 See [client options](#client-options) for every option.
 
 ### Choose a host
 
-Pick one of two forms.
+The API host always comes from the base URL. Pick one of two forms.
 
-- Default platform host: pass the org slug, project slug and key.
-- Custom or self-hosted host: pass `base_url`, project slug and key, and no org slug.
+- Default public host: pass the org slug, project slug and key.
+- Any other platform, internal or air-gapped host: pass its `base_url` as well.
 
 ```ruby
 k9o = K9o.create_client(
-  base_url: "https://k9o.internal.example.com",
+  base_url: "https://api.corp.internal",
+  org_slug: "acme",
   project_slug: "task-app",
   api_key: ENV.fetch("K9O_API_KEY")
 )
 ```
 
-The base URL rules are listed under [regional hosts](#regional-hosts).
+This client talks to `https://acme.api.corp.internal`. See [regional hosts](#regional-hosts) for the rules.
 
 ## Running queries
 
@@ -136,13 +143,193 @@ A sub-object the server did not send is `nil`, so use `&.` when it may be absent
 ```ruby
 request_id = response.meta.context.request_id
 total = response.meta.cursor.total_count
-puts "#{request_id} #{total}"
+puts "Output: #{request_id} #{total}"
+```
+
+```text
+Output: req_01H... 1
+```
+
+## Query with SQL
+
+`k9o.query(sql, params)` runs one read-only SQL statement and returns the rows in `data`.
+It is read-only (a write is refused with `K9O_RAW_SQL_READ_ONLY`; change data through `from`), takes one statement per call,
+applies row-level security, accepts at most 100000 characters of SQL and 1000 parameters, and needs the project editor role.
+A reference to `dataset.<name>` reads an analytics dataset.
+
+Pass an array to bind `$1`, `$2`, and so on, or a hash to bind `:name` placeholders. Values are bound by the database and can be a string, number, boolean or `nil`; serialise anything else (for example as JSON text) first.
+
+```ruby
+rows = k9o.query("SELECT data->>'title' AS title FROM posts WHERE data->>'status' = :status", status: "published")
+puts "Output: #{rows.data.first['title']}"
+
+same = k9o.query("SELECT count(*) AS n FROM posts WHERE data->>'status' = $1", ["published"])
+puts "Output: #{same.data.first['n']}"
 ```
 
 ```text
-req_01H... 1
+Output: Hello
+Output: 12
+```
+
+A `:name` with no key in the hash raises `K9o::KError` with code `K9O_INVALID_FIELD_VALUE` before any request is sent.
+
+## Search
+
+`k9o.search(collection, column:, q:)` runs a full-text search over one text column, best matches first.
+`language:` defaults to `english`; `type:` is `plain` (default), `phrase` or `websearch`. `limit:` and `cursor:` page the result.
+
+```ruby
+found = k9o.search("articles", column: "body", q: "climate resilience", limit: 5)
+puts "Output: #{found.data.length} #{found.data.first['title']}"
+```
+
+```text
+Output: 5 Adapting to heat
+```
+
+The same search is available on a query as `text_search(column, query, language: "english", type: "plain")`.
+`vector_search(column, embedding, metric: "cosine", limit: nil)` finds the closest rows to an embedding, closest first;
+`metric:` is `cosine`, `euclidean` or `dot`, and `limit:` is 1 to 1000.
+
+```ruby
+vector = k9o.ai.embed(input: "heat waves").data["embeddings"].first
+near = k9o.from("articles").select.vector_search("embedding", vector, limit: 3).execute
+puts "Output: #{near.data.length}"
+```
+
+```text
+Output: 3
+```
+
+## Streams
+
+Publish events to a stream and tail them live. Publishing needs the project admin role; subscribing and replaying need admin or auditor.
+`subscribe` reconnects from the last sequence when the server closes the connection, so no event is repeated or skipped.
+
+```ruby
+stream = k9o.streams.create("Orders feed", 1_073_741_824)
+slug = stream.data["slug"]
+puts "Output: #{slug}"
+k9o.streams.publish(slug, { "order" => 1001 }, subject: "eu.new")
+
+k9o.streams.subscribe(slug).each do |event|
+  puts "Output: #{event["sequence"]} #{event["data"]["order"]}"
+  break
+end
+```
+
+```text
+Output: orders-feed
+Output: 1 1001
+```
+
+`replay` reads a bounded range of past events.
+Failures raise `K9o::KError`: `K9O_STREAM_UNAVAILABLE` while streams are not available, and `K9O_STREAM_INVALID` for a bad subject.
+
+## Approvals
+
+Writes that need approval wait in a queue for a second person. `k9o.approvals` reads that queue and decides its changes.
+Project admins and auditors see every change; other members see only the ones they proposed.
+
+```ruby
+queue = k9o.approvals.list(status: "pending_approval", limit: 20)
+change = queue.data.first
+
+puts "Output: #{change["id"]} #{change["operation"]} #{change["collection"]}"
+
+decided = k9o.approvals.approve(change["id"], reason: "checked the amount")
+
+puts "Output: #{decided.data["status"]}"
+```
+
+```text
+Output: apr_01j9x3 update orders
+Output: redeemed
+```
+
+- A change is `pending_approval`, `approved`, `rejected`, `expired` or `redeemed` (applied). An `expired` change can still read `pending_approval` until someone decides it.
+- `approve` can answer 200 with `status` still `pending_approval`. That means your approval is recorded and more approvers are needed; the change is not applied yet.
+- `reject(id, reason:)` needs a non-empty `reason`; the SDK checks it before sending.
+- `list` is not paginated: it returns the newest `limit` changes (1 to 200, default 50). `get(id)` reads one.
+- Deciding needs the queue-admin role (project admin or auditor).
+
+Decide many at once with `bulk`. `criteria` is a predicate over each pending change (see [Approval policies](#approval-policies)):
+
+```ruby
+run = k9o.approvals.bulk(
+  action: "reject",
+  criteria: { "eq" => ["change.table", "orders"] },
+  reason: "stale"
+)
+
+puts "Output: #{run.data["affectedCount"]} #{run.data["affectedIds"].join(",")}"
+```
+
+```text
+Output: 2 apr_01j9x3,apr_01j9x4
+```
+
+- A row that fails (a conflict, an apply error) is skipped silently and left out of `affectedIds`. Compare `affectedIds` with the set you intended.
+- `reject` needs a `reason`; `criteria` must be a predicate hash. `attestationId` identifies the batch, even when nothing matched.
+- It considers the newest 10000 pending changes. Bulk approve is not guaranteed to apply every matched row.
+
+## Approval policies
+
+A policy decides what happens to writes on one collection that match a predicate: `queue` them for approval, or `auto_approve` them.
+For a write the first matching policy, oldest first, decides. Policies are evaluated for writes sent with the `requireApproval=true` query parameter.
+
+```ruby
+policy = k9o.approval_policies.create(
+  collection: "orders",
+  operation: "update",
+  action: "queue",
+  predicate: { "gt" => ["change.row.amount", 1000] }
+)
+
+puts "Output: #{policy.data["id"]} #{policy.data["action"]}"
+
+removed = k9o.approval_policies.delete(policy.data["id"])
+
+puts "Output: #{removed.data["id"]}"
 ```
 
+```text
+Output: apo_01j9x5 queue
+Output: apo_01j9x5
+```
+
+- `operation` is `insert`, `update` or `delete`; `action` is `auto_approve` or `queue`.
+- `collection` matches `^[a-zA-Z_][a-zA-Z0-9_]{0,62}$` and `predicate` is a non-null hash. The SDK checks both before sending.
+- A predicate has one operator key: `and`, `or`, `not`, `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `in_cidr`, `not_in_cidr` or `contains`.
+  `and` and `or` take an array of predicates, `not` takes one, and a comparison takes `[left, right]`.
+- Operands start with `maker.` or `change.` (for example `change.row.amount`, `change.table`, `change.operation`, `maker.id`).
+- `list` returns all policies. Identical policies are not de-duplicated. Creating and deleting need project admin or author.
+
+## Schema collections
+
+`k9o.schema.collections.list` lists the project's collections by name, with their size and last migration.
+
+```ruby
+page = k9o.schema.collections.list(limit: 2)
+
+page.data.each do |collection|
+  puts "Output: #{collection["name"]} #{collection["rowCount"]} rows, #{collection["columnCount"]} columns"
+end
+puts "Output: next #{page.meta.cursor.next}"
+```
+
+```text
+Output: orders 120 rows, 8 columns
+Output: tasks 14 rows, 4 columns
+Output: next dGFza3M
+```
+
+- Pass `meta.cursor.next` as `cursor` for the next page; it is `nil` on the last page. `limit` is 1 to 200 (default 50).
+- A row is `name`, `rowCount`, `rowCountIsExact`, `columnCount`, `indexCount`, `lastMigrationSlug` and `lastMigrationAppliedAt`.
+- `rowCount` is a live count that skips soft-deleted rows and ignores row-level security. Without an `org_id` claim on the token, `meta.warnings` says so.
+- Project admins, auditors, editors, members and viewers can read it.
+
 ## Handling errors
 
 Failures raise `K9o::KError`, a subclass of `StandardError`. Branch on `code`.
@@ -151,14 +338,14 @@ Failures raise `K9o::KError`, a subclass of `StandardError`. Branch on `code`.
 begin
   k9o.from("missing").select.execute
 rescue K9o::KError => error
-  puts "#{error.code} #{error.status} #{error.request_id}"
-  puts error.message
+  puts "Output: #{error.code} #{error.status} #{error.request_id}"
+  puts "Output: #{error.message}"
 end
 ```
 
 ```text
-K9O_NOT_FOUND 404 req_01H...
-Collection not found
+Output: K9O_NOT_FOUND 404 req_01H...
+Output: Collection not found
 ```
 
 - See [error attributes](#error-attributes) for every field.
@@ -179,9 +366,9 @@ Collection not found
 | Option | What it does |
 |---|---|
 | `api_key:` | Bearer token sent with every request. |
-| `org_slug:` | Organization. On the default host the SDK uses `https://<org_slug>.api.k9o.io`. |
+| `org_slug:` | Organization. Prefixed to a platform host (`api.<apex>`) to form the org host. |
 | `project_slug:` | Project. Required by every project-scoped namespace. |
-| `base_url:` | Scheme and host only. Defaults to `https://api.k9o.io`. |
+| `base_url:` | Scheme and host only. Defaults to the public host `https://api.k9o.io`. |
 | `default_headers:` | Extra headers added to every request. |
 | `http_client:` | A `Net::HTTP`-compatible object used instead of the default connection. |
 
@@ -228,6 +415,8 @@ Chain filters before `execute`. Values are matched against one column.
 | `limit(n)` | Maximum rows to return. |
 | `cursor(token)` | Continue from `meta.cursor.next`. |
 | `count(mode)` | Row count mode: `none`, `exact` or `estimated`. |
+| `text_search(column, query, language: "english", type: "plain")` | Full-text search over one column. |
+| `vector_search(column, embedding, metric: "cosine", limit: nil)` | Nearest rows to an embedding, closest first. |
 
 #### Projects
 
@@ -236,9 +425,18 @@ Chain filters before `execute`. Values are matched against one column.
 | Method | What it does |
 |---|---|
 | `k9o.projects.list` | List projects you can access. |
-| `k9o.projects.create` | Create a project from `slug` and `name`. |
+| `k9o.projects.create` | Create a project from `display_name:` (optional `slug:`, `region:`, `custody_mode:`, more). |
 | `k9o.projects.get` | Read a project by slug. |
-| `k9o.projects.update` | Change a project's `name`. |
+| `k9o.projects.update` | Change a project by slug: `display_name:`, `slug:` (rename), `description:`, `region:`, more. |
+
+```ruby
+project = k9o.projects.create(display_name: "Task app", slug: "task-app")
+puts "Output: #{project.data["slug"]}"
+```
+
+```text
+Output: task-app
+```
 
 #### Gate (end-user sign-in)
 
@@ -248,20 +446,18 @@ Chain filters before `execute`. Values are matched against one column.
 |---|---|
 | `k9o.gate.sign_up` | Create an end user from email and password. |
 | `k9o.gate.sign_in` | Sign in with email and password. |
-| `k9o.gate.sign_out` | Revoke the session's refresh token. |
+| `k9o.gate.sign_out` | Revoke a session. Requires `refresh_token:`. |
 | `k9o.gate.whoami` | Return the signed-in identity. |
 | `k9o.gate.refresh_token` | Exchange a refresh token for a new access token. |
-| `k9o.gate.verify_session` | Check that the current session is valid. |
-| `k9o.gate.hosted` | Return the hosted sign-in `signInUrl` and `rpId`. |
 
 ```ruby
 session = k9o.gate.sign_in(email: "ada@example.com", password: "correct-horse")
 user = session.data["user"]
-puts user["email"]
+puts "Output: #{user["email"]}"
 ```
 
 ```text
-ada@example.com
+Output: ada@example.com
 ```
 
 #### Storage
@@ -303,11 +499,32 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 
 | Method | What it does |
 |---|---|
-| `k9o.functions.deploy` | Deploy a function from `name`, `runtime` and `code`. |
-| `k9o.functions.list` | List functions. |
+| `k9o.functions.upload_artifact` | Upload the build (`bytes`, `kind` of `"wasm"` or `"tar"`). Returns `artifactKey`. |
+| `k9o.functions.deploy` | Deploy from `name:`, `runtime:`, `tier:`, `artifact_key:`, `version:`, optional `description:`. |
+| `k9o.functions.list` | List functions. Options: `status:`, `limit:`, `cursor:`. |
 | `k9o.functions.get` | Read one function by name. |
 | `k9o.functions.delete` | Remove a function. |
-| `k9o.functions.invoke` | Run a function with a payload. |
+| `k9o.functions.invoke` | Run a function. The `payload` argument is sent as `{payload}`. |
+
+`tier:` is `"sandbox"` (an OCI image archive, `"tar"`, up to 256 MiB). The `gateway` tier is for functions owned by platform operators and is not available to most projects. Sandbox functions run in a [Firelock](https://github.com/firelock-sandbox/firelock) microVM sandbox.
+
+```ruby
+artifact = k9o.functions.upload_artifact(File.binread("hello.tar"), "tar")
+
+k9o.functions.deploy(
+  name: "hello",
+  runtime: "bun",
+  tier: "sandbox",
+  artifact_key: artifact.data["artifactKey"],
+  version: "1.0.0"
+)
+result = k9o.functions.invoke("hello", { "name" => "Ada" })
+puts "Output: #{result.data["greeting"]}"
+```
+
+```text
+Output: Hello, Ada
+```
 
 #### Migrations
 
@@ -331,11 +548,11 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | Method | What it does |
 |---|---|
 | `k9o.policies.current` | Read the published bundle. |
-| `k9o.policies.list` | List bundles. |
-| `k9o.policies.create` | Create a bundle from `name` and `rules`. |
-| `k9o.policies.validate` | Check rules without saving. |
+| `k9o.policies.list` | List bundles. Only option: `status:`. |
+| `k9o.policies.create` | Create a bundle from a `policy:` document (optional `rules:`, `editor_mode:`). |
+| `k9o.policies.validate` | Check a `policy:` document (and optional `rules:`) without saving. |
 | `k9o.policies.get` | Read one bundle. |
-| `k9o.policies.update` | Change a bundle. |
+| `k9o.policies.update` | Replace a bundle's `policy:` (optional `rules:`, `editor_mode:`). |
 | `k9o.policies.delete` | Remove a bundle. |
 | `k9o.policies.publish` | Make a bundle current. |
 
@@ -345,7 +562,9 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 
 | Method | What it does |
 |---|---|
-| `k9o.audit.query` | Search events by time range, type and more. |
+| `k9o.audit.query` | Filter by `event_type:`, `actor_id:`, `after:`, `before:`, `limit:`, `cursor:`. |
+
+`after:` and `before:` are ISO 8601 timestamps.
 
 #### AI embeddings
 
@@ -354,6 +573,21 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | Method | What it does |
 |---|---|
 | `k9o.ai.embed(input:, model: nil)` | Embed one string or a list of strings. |
+| `k9o.ai.generate(prompt, model: nil, max_tokens: nil, temperature: nil, usage_type: nil)` | Generate text from a prompt. |
+
+##### Generate text
+
+`model` is optional: without it the org's default model is used. Models from outside providers answer 501 until built.
+The result `data` is the same as `compute.llms.invoke`.
+
+```ruby
+result = k9o.ai.generate("Say hi in three words", max_tokens: 20)
+puts "Output: #{result.data['content']}"
+```
+
+```text
+Output: Hi there, friend!
+```
 
 #### Language models
 
@@ -364,7 +598,18 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | `k9o.compute.llms.list` | List available models. |
 | `k9o.compute.llms.read` | Read one model. |
 | `k9o.compute.llms.invoke` | Send a prompt and get the reply. |
-| `k9o.compute.llms.invoke_stream` | Stream the reply token by token (returns an `Enumerator`). |
+| `k9o.compute.llms.invoke_stream` | Stream the reply chunk by chunk (returns an `Enumerator`). |
+
+Pass settings in `params:` (`max_tokens`, `temperature`, `usage_type`). The result `data` has `content` and `usage`.
+
+```ruby
+reply = k9o.compute.llms.invoke("llama-3-8b", prompt: "Say hi", params: { max_tokens: 20 })
+puts "Output: #{reply.data['content']} #{reply.data['usage']['totalTokens']}"
+```
+
+```text
+Output: Hi there! 14
+```
 
 #### Realtime
 
@@ -372,12 +617,52 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 
 | Method | What it does |
 |---|---|
-| `k9o.realtime.subscribe` | Stream live events (returns an `Enumerator`). |
-| `k9o.realtime.replay` | Read past events from a sequence number. |
-| `k9o.realtime.subscribe_poll` | Poll for events from a sequence number. |
+| `k9o.realtime.subscribe` | Stream live events over SSE (returns an `Enumerator`). |
 
 `K9o::Realtime::Topic` builds topic names, for example `Topic.collection("tasks")`.
 
+#### Streams
+
+`k9o.streams` publishes to and subscribes to the project's user streams. It needs `project_slug`.
+
+| Method | What it does |
+|---|---|
+| `k9o.streams.create(display_name, max_bytes, retention_seconds: nil)` | Create a stream. The slug comes from the name. |
+| `k9o.streams.list` | List the project's streams. |
+| `k9o.streams.get(slug)` | Read one stream. |
+| `k9o.streams.delete(slug)` | Retire a stream. |
+| `k9o.streams.publish(slug, data, subject: nil)` | Append an event. `subject` is a dot-separated routing suffix. |
+| `k9o.streams.replay(slug, from_sequence: nil, until_sequence: nil, limit: nil)` | Read past events: `events`, `nextCursor`, `hasMore`. |
+| `k9o.streams.subscribe(slug, from_sequence: nil)` | Tail live events over SSE (an `Enumerator`). Reconnects from the last sequence. |
+
+#### Approvals
+
+`k9o.approvals` reads and decides the queue of changes waiting for approval. It needs `project_slug`.
+
+| Method | What it does |
+|---|---|
+| `k9o.approvals.list(status: nil, limit: nil)` | Newest pending changes first. Not paginated; `limit` is 1 to 200. |
+| `k9o.approvals.get(id)` | Read one change. |
+| `k9o.approvals.approve(id, reason: nil)` | Approve. `status` can stay `pending_approval` while more approvers are needed. |
+| `k9o.approvals.reject(id, reason:)` | Reject. `reason` is required. |
+| `k9o.approvals.bulk(action:, criteria:, reason: nil)` | Approve or reject every change matching a predicate. `reason` is required to reject. Failed rows are skipped. |
+
+#### Approval policies
+
+`k9o.approval_policies` holds the rules that decide which writes are queued. It needs `project_slug`.
+
+| Method | What it does |
+|---|---|
+| `k9o.approval_policies.list` | All policies, oldest first. |
+| `k9o.approval_policies.create(collection:, operation:, action:, predicate:)` | Create a policy. `action` is `auto_approve` or `queue`. |
+| `k9o.approval_policies.delete(id)` | Delete a policy. |
+
+#### Schema
+
+| Method | What it does |
+|---|---|
+| `k9o.schema.collections.list(limit: nil, cursor: nil)` | List the project's collections by name, with `meta.cursor.next` paging. |
+
 #### Studio
 
 `k9o.studio` manages workflows and dashboards.
@@ -391,7 +676,7 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | `k9o.studio.workflows.read` | Read one workflow. |
 | `k9o.studio.workflows.update` | Change a workflow. |
 | `k9o.studio.workflows.delete` | Delete a workflow. |
-| `k9o.studio.workflows.trigger` | Start a run. |
+| `k9o.studio.workflows.trigger` | Start a run, with an optional context hash. |
 | `k9o.studio.workflows.runs.list` | List a workflow's runs. |
 | `k9o.studio.workflows.runs.read` | Read one run. |
 | `k9o.studio.workflows.runs.cancel` | Cancel a run. |
@@ -415,19 +700,13 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | Method | What it does |
 |---|---|
 | `k9o.me.profile.get` | Read the profile. |
-| `k9o.me.profile.update` | Change the display name. |
+| `k9o.me.profile.update` | Change `display_name:`, `locale:` or `timezone:` (only those given). |
 | `k9o.me.sessions.list` | List active sessions. |
 | `k9o.me.sessions.revoke` | End one session. |
 | `k9o.me.sessions.revoke_all` | End all sessions. |
 | `k9o.me.api_tokens.list` | List API tokens. |
-| `k9o.me.api_tokens.create` | Create an API token. |
+| `k9o.me.api_tokens.create` | Create a token from `label:` and `scope_manifest:` (optional `ttl_seconds:`). |
 | `k9o.me.api_tokens.delete` | Delete an API token. |
-| `k9o.me.notifications.list` | List notifications. |
-| `k9o.me.notifications.mark_read` | Mark one as read. |
-| `k9o.me.notifications.mark_all_read` | Mark all as read. |
-| `k9o.me.audit_log.query` | Search your own audit events. |
-| `k9o.me.data_export.request` | Request a data export. |
-| `k9o.me.data_export.status` | Check an export job. |
 
 #### Organization
 
@@ -447,30 +726,26 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | Method | What it does |
 |---|---|
 | `k9o.org.get` | Read the active organization. |
-| `k9o.org.members.list` | List members. |
+| `k9o.org.members.list` | List members. Options: `user_id:`, `role:`, `acceptance_status:`, `status:`, `state:`. |
 | `k9o.org.members.invite` | Invite a member by email and role. |
-| `k9o.org.members.get` | Read one member. |
 | `k9o.org.members.remove` | Remove a member. |
-| `k9o.org.groups.list` | List groups. |
-| `k9o.org.groups.create` | Create a group. |
+| `k9o.org.groups.list` | List groups, optionally for one `user_id:`. |
 | `k9o.org.groups.get` | Read one group. |
-| `k9o.org.groups.delete` | Delete a group. |
-| `k9o.org.audit_log.query` | Search organization audit events. |
+| `k9o.org.audit_log.query` | Search organization audit events by `type:` and `limit:`. |
 | `k9o.org.gate.roles.list` | List role grants. |
-| `k9o.org.gate.roles.grant` | Grant a role to a user. |
+| `k9o.org.gate.roles.grant` | Grant a role to a user (`user_id:`, `role:`, optional `decision_reason:`). |
 | `k9o.org.gate.roles.get` | Read one grant. |
 | `k9o.org.gate.roles.revoke` | Revoke a grant. |
 | `k9o.org.gate.idp_providers.list` | List identity providers. |
-| `k9o.org.gate.idp_providers.create` | Add an identity provider. |
+| `k9o.org.gate.idp_providers.create` | Add a provider: `idp_provider:`, `display_name:`, `client_id:`, `client_secret_ref:`, `tier_gating:`. |
 | `k9o.org.gate.idp_providers.get` | Read one provider. |
 | `k9o.org.gate.idp_providers.configure` | Change a provider. |
 | `k9o.org.gate.idp_providers.delete` | Remove a provider. |
-| `k9o.org.smtp.get` | Read the mail server settings. |
-| `k9o.org.smtp.set` | Save the mail server settings. |
-| `k9o.org.smtp.test` | Send a test email. |
+| `k9o.org.smtp.set` | Save the mail server: `host:`, `port:`, `username:`, `password_ref:`, `from_address:`. |
+| `k9o.org.smtp.test` | Send a test email to `to:`, with an optional `subject:`. |
 | `k9o.org.smtp.unset` | Remove the mail server settings. |
 | `k9o.org.default_llm.get` | Read the default model. |
-| `k9o.org.default_llm.set` | Set the default model. |
+| `k9o.org.default_llm.set` | Set the default model from a model id. |
 
 #### Vault secrets
 
@@ -479,7 +754,7 @@ signed = avatars.create_signed_url("ada.png", expires_in: 300)
 | Method | What it does |
 |---|---|
 | `k9o.kibo.vault.secrets.list` | List secrets by prefix. |
-| `k9o.kibo.vault.secrets.get` | Read a secret's details. |
+| `k9o.kibo.vault.secrets.get` | Read a secret by name (`region:` is required). |
 | `k9o.kibo.vault.secrets.create` | Store a new secret. |
 | `k9o.kibo.vault.secrets.reveal_challenge` | Get a one-time challenge for revealing. |
 | `k9o.kibo.vault.secrets.reveal` | Reveal the value using the challenge. |
@@ -534,10 +809,12 @@ The server may send codes not listed here, so keep a fallback branch.
 
 ### Regional hosts
 
-- Organization hosts such as `https://acme.api.k9o.io` are region-free.
-- The SDK sends one credential-free `HEAD` request to learn the region.
-- Later requests go to the regional host.
-- Any other base URL is used exactly as given.
+- A platform host is `api.<apex>` or `api-staging.<apex>`, on any apex.
+- With `org_slug`, the SDK builds the org host `<org_slug>.<host>`.
+- A region-free org host gets one credential-free `HEAD` request to learn its region.
+- Later requests go to the regional host, which must share the org, family and apex.
+- Any other base URL (internal, air-gapped, localhost) is used exactly as given.
+- `https://api.k9o.io` is only the default when `base_url:` is omitted.
 
 ### Related packages
 
@@ -546,6 +823,20 @@ The server may send codes not listed here, so keep a fallback branch.
 | `@k9o/core` | TypeScript SDK |
 | `@k9o/cli` | Command-line tool |
 
+### About Kilimanjaro
+
+Kilimanjaro is a modular developer platform for building secure enterprise applications.
+You define AI agents, functions and data pipelines on the platform.
+The SDKs let you deploy and invoke them, read and write your data, publish to and subscribe to streams,
+sign users in, and encrypt with keys you hold.
+
+It provides four building blocks:
+
+- **Keep**: AI security and governance. Guardrails and policy for the agents you run.
+- **Pulse**: data intelligence and real-time stream processing. Streams, analytics and live feeds.
+- **Gate**: customer identity and access management. Sign-in and sessions, and automatic data scoping so a signed-in user reaches only their own data.
+- **Kibo**: cryptographic keys and secrets management. Client-side encryption with keys you hold, and a secrets vault.
+
 ## License
 
 Apache-2.0 © Formelo Inc. See `LICENSE` and `NOTICE`.