@okostream/mcp 0.16.0 → 0.18.0

package/README.md

@@ -6,9 +6,8 @@ analytics, and integrations around a video player supplied by the organizer.
 
 ## Before You Connect
 
-Webinar data and actions require an active OKO organizer account. Organizer
-an active organizer account is required before an API key can be created
-signup.
+Webinar data and actions require an active OKO organizer account. An active
+organizer account is required before an API key can be created.
 
 - Already invited: [sign in or register](https://okostream.app/auth?redirect=/app/mcp).
 - Already an organizer: create a scoped key in the
@@ -86,6 +85,27 @@ is behind, with the exact update step. Global installs update with
 now (the extension bundle is discontinued; the Desktop path returns when the
 package ships through a directory).
 
+## Publishing and lumens
+
+A new page is a draft: viewers of its public URL see "not published".
+`oko_publish_event` publishes it and, like a few other operations, spends
+**lumens**, the unit of the OKO wallet. Money is handled in one direction:
+
+- **Spending is previewed.** `oko_publish_event`, `oko_unpublish_event`,
+  `oko_start_session`, `oko_extend_session` and `oko_publish_telegram_post`
+  state the charge (or the refund) when called without `confirm`, name the
+  wallet that pays, and take nothing until the organizer confirms. The amount in
+  the preview is the amount charged; the public price list is at
+  [okostream.app/pricing](https://okostream.app/pricing) and is not copied here.
+- **`oko_wallet` reads the wallet.** It returns the lumen balance, the grants and
+  the ledger of the organizer behind the key (scope `wallet:read`, included in
+  the `operator` and `full` presets, not in `readOnly`). Keys created before that scope existed get `SCOPE_REQUIRED` and
+  need a new key. A page in a shared workspace is paid from the workspace
+  owner's wallet, which is theirs to read.
+- **Payment and terms are web-only.** Plans and lumens are bought, and terms
+  accepted, only in the OKO web cabinet, and no MCP tool collects a password,
+  card or bank details, or agreement to terms on anyone's behalf.
+
 ## When a tool refuses
 
 Refusals are explicit and never require guessing:
@@ -96,10 +116,28 @@ Refusals are explicit and never require guessing:
   or rephrasing does not help; the result carries a ready-made report for the
   OKO team.
 - `PLATFORM_REJECTED_READ` — no access to that resource, or it does not exist.
-- `CHAT_PAUSED` — the event's chat is paused and accepts no messages from anyone,
-  the owner included; it is the chat's state, not a missing permission.
+- `ENTITLEMENT_REQUIRED` / `INSUFFICIENT_TOKENS` — the plan that pays lacks the
+  feature, or the wallet that pays is short of lumens. `oko_publish_telegram_post`
+  costs 5 lumens per post, charged when Telegram confirms delivery; the plan and the
+  balance are checked before the send, and the refusal names the `postId` left
+  behind as `failed` (create a new post after fixing the cause, then delete the
+  failed one with `oko_cancel_telegram_post`).
+- `CHAT_PAUSED` — the event's chat is paused, which closes it for viewers (the
+  event owner and moderators still write into a paused chat); it is the chat's
+  state, not a missing permission.
   `CHAT_MESSAGE_REFUSED` — the chat refused a message and the cause could not be
   established; the result lists what was ruled out and what remains possible.
+- `EVENT_DATE_LOCKED` — the date of a published page moves only inside the show
+  window it bought (the result carries `windowStart`, `windowEnd` and the next
+  steps); a date outside the window, a cleared date, or any date on a page whose
+  show is over is refused. `oko_update_event` may also return `warnings` (advice,
+  never a refusal).
+- `WORKSPACE_LIMIT`, `SEATS_FULL`, `ENTITLEMENT_REQUIRED` — the plan of the
+  workspace owner does not hold another shared workspace, another member, or
+  the capability at all. A refused invitation stays valid. Plans are bought only
+  in the OKO cabinet, never through MCP.
+- `WORKSPACE_INACTIVE` — `oko_publish_event` in a shared workspace the plan no
+  longer publishes into (Pro: only the workspace its owner chose as active).
 
 **One install path.** Every supported client — Claude Code, Codex, and any
 MCP client that takes a command with arguments and env — runs the package
@@ -122,10 +160,17 @@ always works. The result's `sourceVia` says who fetched the image.
 ## Capabilities
 
 - Create, duplicate, move, restore, and delete webinars.
-- Configure video, forms, calls to action, cards, banners, and images.
+- Configure video, forms, calls to action, cards, banners, and images. On an
+  already published page, turning on a banner, CTA, cards or forms costs 10
+  lumens each for that show: the tool answers with the quote first and writes
+  only after `confirm=true`; unpublishing later does not return these top-ups.
+  The live control room is a paid option of a published page (50 lumens, Pro
+  and above) bought in the analytics screen, not through MCP.
 - Operate live audience controls, chat, moderation, and analytics sessions.
 - Read analytics, session reports, geography, engagement, and form submissions.
-- Manage workspaces, invitations, notifications, and Telegram publishing.
+- Manage workspaces, invitations, notifications, and Telegram publishing
+  (5 lumens per post, shown in the confirmation preview).
+- Read the lumen balance and ledger of your own wallet (`oko_wallet`).
 
 OKO MCP acts as the organizer represented by the selected access key. It does
 not inherit platform-owner privileges. Keys are scoped and revocable, and