@okostream/mcp 0.2.0 → 0.4.0

package/README.md

@@ -54,10 +54,17 @@ Every tool returns JSON text plus MCP `structuredContent`. List-like tools use b
 
 - `limit` defaults to 20-50 depending on the tool.
 - Cursor tools return both `hasMore`/`nextCursor` and `has_more`/`next_cursor`.
-- `oko_list_my_events`, `oko_get_analytics`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`, `oko_list_workspace_access`, `oko_list_workspace_invites`, and `oko_list_telegram_posts` support pagination.
+- `oko_list_my_events`, `oko_get_analytics`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`, `oko_list_notifications`, `oko_list_workspace_access`, `oko_list_workspace_invites`, and `oko_list_telegram_posts` support pagination.
 - `oko_get_analytics` omits heavy `timeline`, baseline/final snapshots, and NMO participant rows by default. Request `includeTimeline`, `includeSnapshots`, or `includeNmoRows` only when needed.
+- `oko_get_session_report` returns a compact structured session report plus markdown suitable for a human handoff.
 - Oversized responses are truncated with `truncated: true` and a `truncationMessage`.
 
+The server also exposes MCP-native onboarding:
+
+- `instructions` on initialize with the supported webinar creation flow and product invariants.
+- Resources: `oko://guide/create-webinar`, `oko://guide/platform`, `oko://guide/security`, `oko://schema/event`, `oko://capabilities`.
+- Prompts: `create_webinar_from_brief`, `audit_event_setup`, `prepare_session_report`.
+
 This package is published as source-available runtime distribution for OKO customers. `license: UNLICENSED` means all rights reserved unless a separate agreement says otherwise.
 
 ## Local Development
@@ -92,14 +99,16 @@ All tools are prefixed with `oko_` for safe discovery next to other MCP servers.
 Core discovery/read tools:
 
 - `oko_whoami`, `oko_list_workspaces`, `oko_list_my_events`, `oko_get_event`
-- `oko_get_live_state`, `oko_get_analytics`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`
+- `oko_validate_event_setup`
+- `oko_update_profile`, `oko_list_notifications`, `oko_mark_notifications_read`
+- `oko_get_live_state`, `oko_get_analytics`, `oko_get_session_report`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`, `oko_delete_lead`
 
 Event/setup/media tools:
 
 - `oko_create_webinar`, `oko_update_event`, `oko_delete_event`
 - `oko_duplicate_event`, `oko_move_event`
 - `oko_configure_blocks`, `oko_configure_cards`
-- `oko_upload_image`, `oko_delete_image`
+- `oko_upload_image`, `oko_upload_card_images_batch`, `oko_wait_for_image_variants`, `oko_delete_image`
 
 Live/session/chat/NMO tools:
 
@@ -124,11 +133,15 @@ Dangerous or external side-effect tools require `confirm: true`.
 2. `oko_list_my_events` should return only events visible to that UID.
 3. `oko_create_webinar` should create a test webinar and RTDB owner/workspace mirror.
 4. `oko_configure_cards` should create/update `blocks.cards.items` and preserve card image fields by stable card id.
-5. `oko_upload_image` should accept a local path or HTTPS image URL, upload `master.webp`, and let OKO generate variants.
-6. `oko_start_session` -> `oko_fix_orphan_session` -> `oko_delete_session` should leave no active session pointers on a disposable test event.
-7. `oko_duplicate_event`, workspace tools, and `oko_move_event` should preserve Firestore access rules and RTDB owner/workspace mirrors.
-8. `oko_import_nmo_participants` should call CF24 and return per-row results; clean up test participants after import.
-9. `oko_get_analytics` should read an existing event with analytics sessions.
+5. `oko_upload_card_images_batch` should upload multiple card images, then return ready `imageVariants`.
+6. `oko_validate_event_setup` should catch missing images/forms/buttons/video/NMO/Telegram/variants on a deliberately broken event.
+7. `oko_start_session` -> `oko_fix_orphan_session` -> `oko_delete_session` should leave no active session pointers on a disposable test event.
+8. `oko_duplicate_event`, workspace tools, and `oko_move_event` should preserve Firestore access rules and RTDB owner/workspace mirrors.
+9. `oko_import_nmo_participants` should call CF24 and return per-row results; clean up test participants after import.
+10. `oko_get_session_report` should return markdown and structured session data for a completed session.
+11. `oko_list_notifications` -> `oko_mark_notifications_read` should read and clear an own disposable notification.
+12. `oko_get_analytics` should read an existing event with analytics sessions.
+13. MCP protocol smoke should report 59 tools, 5 resources, 3 prompts, and non-empty initialize instructions.
 
 CLI help:
 

package/dist/guides.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+export const OKO_MCP_INSTRUCTIONS = [
+    "You are controlling OKO Stream as an organizer through MCP tools.",
+    "Start every new workspace session with oko_whoami, then respect the returned scopes.",
+    "OKO events have no draft/live/ended status. Start/End controls manage analytics sessions only, never video streaming.",
+    "For webinar creation, prefer this flow: oko_create_webinar, oko_configure_blocks, oko_configure_cards, image uploads, oko_validate_event_setup, then return public/setup/analytics links.",
+    "For card images, create stable card ids first, then use oko_upload_card_images_batch or oko_upload_image plus oko_wait_for_image_variants.",
+    "Before destructive actions, show the exact target and require an explicit user confirmation; then pass confirm=true.",
+    "Use oko_validate_event_setup before telling the organizer that a webinar is ready.",
+    "Do not bypass OKO APIs or Firebase rules; this server is the supported organizer surface.",
+].join("\n");
+const GUIDE_RESOURCES = [
+    {
+        name: "oko_mcp_create_webinar",
+        uri: "oko://guide/create-webinar",
+        title: "Create an OKO Webinar",
+        description: "Recommended call order for creating and validating a webinar.",
+        text: [
+            "# Create an OKO Webinar",
+            "",
+            "1. Call `oko_whoami` and inspect scopes.",
+            "2. If the workspace is unclear, call `oko_list_workspaces`.",
+            "3. Call `oko_create_webinar` with title/date/workspace and video URL when known.",
+            "4. Call `oko_configure_blocks` for video, forms, CTA, banner, Telegram, and NMO settings.",
+            "5. Call `oko_configure_cards` with stable card ids before uploading card images.",
+            "6. Upload images with `oko_upload_card_images_batch` or `oko_upload_image`, then wait for variants.",
+            "7. Call `oko_validate_event_setup` and fix blocking findings.",
+            "8. Return public, setup, analytics, registration, and login links that apply to the event.",
+            "",
+            "Important: OKO has no event status. Do not invent draft/live/ended lifecycle states.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_mcp_platform",
+        uri: "oko://guide/platform",
+        title: "OKO Platform Invariants",
+        description: "Core OKO product rules that MCP clients must respect.",
+        text: [
+            "# OKO Platform Invariants",
+            "",
+            "- OKO events have no `draft`, `live`, or `ended` status field.",
+            "- Public event pages render whenever the event exists and normal access rules allow it.",
+            "- Start and End controls manage analytics sessions only; they never start or stop the video stream.",
+            "- Setup writes Firestore event structure. Live analytics and controls use RTDB mirrors and session nodes.",
+            "- Chat lives in the separate chat RTDB. Moderator actions require chat scopes and normal event access.",
+            "- NMO participant import is handled by the scoped Cloud Function `importNmoParticipants`.",
+            "- Image variants are asynchronous. A master upload is not fully ready until `imageVariants` are present.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_mcp_security",
+        uri: "oko://guide/security",
+        title: "OKO MCP Security Model",
+        description: "API-key, scopes, confirmation, and Firebase rules boundaries.",
+        text: [
+            "# OKO MCP Security Model",
+            "",
+            "The MCP server acts as the organizer user represented by `OKO_API_KEY`. It is not a platform-admin backdoor.",
+            "",
+            "Security layers:",
+            "- API keys are stored hashed in Firestore and the full secret is shown only once in the OKO UI.",
+            "- `exchangeApiKey` mints short-lived Firebase custom tokens with legacy `scopes` and rules-readable `mcpScopes`.",
+            "- MCP tools check scopes before executing.",
+            "- Firestore, RTDB, chat RTDB, and Storage rules also check `mcpScopes` for direct Firebase SDK misuse.",
+            "- Destructive or external side-effect tools require explicit `confirm:true`.",
+            "- Wrong API-key exchanges are counted per keyId; after 10 failures the keyId is locked for 15 minutes.",
+            "",
+            "- `events:read`: list and read event documents.",
+            "- `events:write`: create, duplicate, move, and update event metadata.",
+            "- `events:delete`: delete event records.",
+            "- `setup:write`: configure blocks, forms, cards, and images.",
+            "- `analytics:read`: read live state, sessions, reports, chat history.",
+            "- `analytics:write` + `live:control`: start/end/fix/delete analytics sessions.",
+            "- `live:control`: live block visibility and viewer refresh.",
+            "- `chat:write`: send organizer chat messages.",
+            "- `chat:moderate`: delete, mute, ban, unmute, unban, and chat settings.",
+            "- `telegram:write`: claim/list channels and create/cancel/publish Telegram posts.",
+            "- `workspace:read` / `workspace:write`: workspace, members, invites, notifications.",
+            "- `nmo:write`: NMO participants and checkpoints.",
+            "- `leads:read`: read form submissions; lead deletion also requires `setup:write`.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_event_schema",
+        uri: "oko://schema/event",
+        title: "OKO Event Schema Notes",
+        description: "Compact schema notes for fields most often edited by MCP clients.",
+        text: [
+            "# OKO Event Schema Notes",
+            "",
+            "Common event fields:",
+            "- `title`: user-visible webinar title.",
+            "- `meta.eventDate`: scheduled date.",
+            "- `video.originalUrl` / `video.embedUrl`: raw and normalized video URLs.",
+            "- `forms[]`: lead forms with `id`, `type`, `title`, `fields[]`, consent copy, and submit/success text.",
+            "- `blocks.primaryCta`: CTA copy, `buttonUrl` or `formId`, and visibility.",
+            "- `blocks.promoBanner`: banner copy, link/form binding, image refs, variants, and visibility.",
+            "- `blocks.cards.items[]`: stable `id`, copy, optional `buttonUrl` or `formId`, image refs, and `imageVariants`.",
+            "- `telegram.channelIds`: claimed Telegram channels for notifications.",
+            "- `nmoMode`, `nmoCriteria`, `participantUids`: NMO mode and participant gates.",
+            "- `workspaceId`, `accessibleBy`, `editors`: access mirrors required by rules and dashboard queries.",
+            "",
+            "Do not remove unknown fields when updating nested config. Use dedicated MCP tools instead of whole-document rewrites.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_mcp_capabilities",
+        uri: "oko://capabilities",
+        title: "OKO MCP Capabilities",
+        description: "High-level workflows available through OKO MCP.",
+        text: [
+            "# OKO MCP Capabilities",
+            "",
+            "## Webinar setup",
+            "- Create, duplicate, move, update, validate, and delete webinars.",
+            "- Configure forms, CTA, banner, cards, video placeholder, Telegram, and NMO settings.",
+            "- Upload images from local paths, data URLs, or HTTPS URLs and wait for variants.",
+            "",
+            "## Live analytics",
+            "- Read live state, start/end analytics sessions, refresh viewers, and change block visibility.",
+            "- Read compact analytics, session reports, leads, chat history, and NMO participation data.",
+            "- Fix or delete orphan sessions only after explicit confirmation.",
+            "",
+            "## Collaboration and comms",
+            "- Manage workspaces, members, invites, notifications, and Telegram post lifecycle.",
+            "- Send organizer chat messages and moderate chat users when scoped.",
+            "- Import/remove NMO participants through scoped Cloud Functions.",
+        ].join("\n"),
+    },
+];
+function promptMessage(text) {
+    return {
+        messages: [{
+                role: "user",
+                content: { type: "text", text },
+            }],
+    };
+}
+export function registerGuides(server) {
+    for (const resource of GUIDE_RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: "text/markdown",
+        }, async (uri) => ({
+            contents: [{
+                    uri: uri.toString(),
+                    mimeType: "text/markdown",
+                    text: resource.text,
+                }],
+        }));
+    }
+    server.registerPrompt("create_webinar_from_brief", {
+        title: "Create Webinar From Brief",
+        description: "Plan and execute a complete OKO webinar setup from an organizer brief.",
+        argsSchema: {
+            brief: z.string().min(1).describe("Organizer brief with topic, date, audience, blocks, images, and integrations."),
+            workspaceId: z.string().optional().describe("Optional OKO workspace id."),
+        },
+    }, async ({ brief, workspaceId }) => promptMessage([
+        "Create an OKO webinar from this brief using MCP tools.",
+        "",
+        "Required flow:",
+        "1. Call oko_whoami and verify scopes.",
+        "2. Create the webinar in the requested workspace if provided.",
+        "3. Configure metadata, blocks, forms, Telegram, NMO, and cards as needed.",
+        "4. Upload images only after target slots/cards exist; wait for image variants.",
+        "5. Run oko_validate_event_setup and fix actionable errors.",
+        "6. Return public, setup, analytics, registration/login links as applicable.",
+        "",
+        workspaceId ? `Workspace id: ${workspaceId}` : "Workspace id: not specified; choose the personal workspace unless the user clarifies.",
+        "",
+        "Brief:",
+        brief,
+    ].join("\n")));
+    server.registerPrompt("audit_event_setup", {
+        title: "Audit Event Setup",
+        description: "Audit an OKO event for readiness and produce a fix plan.",
+        argsSchema: {
+            eventId: z.string().min(1).describe("OKO event id to audit."),
+            focus: z.string().optional().describe("Optional focus area, for example NMO, Telegram, forms, cards, live."),
+        },
+    }, async ({ eventId, focus }) => promptMessage([
+        `Audit OKO event ${eventId}.`,
+        "",
+        "Required flow:",
+        "1. Call oko_whoami and verify scopes.",
+        "2. Call oko_get_event and oko_validate_event_setup.",
+        "3. If relevant, inspect live state, Telegram posts, participants, leads, and image variant readiness.",
+        "4. Separate errors that block launch from warnings and polish suggestions.",
+        "5. Propose exact MCP tool calls needed to fix issues; execute only if the organizer asked for implementation.",
+        "",
+        focus ? `Focus: ${focus}` : "Focus: full setup readiness.",
+    ].join("\n")));
+    server.registerPrompt("prepare_session_report", {
+        title: "Prepare Session Report",
+        description: "Prepare an organizer-friendly report from OKO analytics session data.",
+        argsSchema: {
+            eventId: z.string().min(1).describe("OKO event id."),
+            sessionId: z.string().optional().describe("Optional analytics session id; omit to choose from sessions list."),
+            audience: z.string().optional().describe("Optional report audience, for example internal, client, NMO."),
+        },
+    }, async ({ eventId, sessionId, audience }) => promptMessage([
+        `Prepare a session report for OKO event ${eventId}.`,
+        "",
+        "Required flow:",
+        "1. Call oko_whoami and verify analytics:read.",
+        sessionId ? `2. Use session id ${sessionId}.` : "2. Call oko_get_analytics and choose the relevant ended session id from returned sessions.",
+        "3. Call oko_get_session_report.",
+        "4. Summarize attendance, engagement, chat, CTA/cards, geo, and NMO if present.",
+        "5. Call out data caveats separately from conclusions.",
+        "",
+        audience ? `Audience: ${audience}` : "Audience: organizer/internal.",
+    ].join("\n")));
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { OKO_MCP_INSTRUCTIONS, registerGuides } from "./guides.js";
 import { registerTools } from "./tools.js";
 if (process.argv.includes("--help")) {
     process.stdout.write([
@@ -22,8 +23,11 @@ if (process.argv.includes("--help")) {
 }
 const server = new McpServer({
     name: "oko-mcp-server",
-    version: "0.2.0",
+    version: "0.4.0",
+}, {
+    instructions: OKO_MCP_INSTRUCTIONS,
 });
+registerGuides(server);
 registerTools(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools.js

@@ -6,7 +6,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 import { z } from "zod";
-import { addDoc, arrayRemove, collection, deleteDoc, deleteField, documentId, doc, getDoc, getDocs, limit, orderBy, query, serverTimestamp, setDoc, startAfter, Timestamp, updateDoc, where, } from "firebase/firestore";
+import { addDoc, arrayRemove, collection, deleteDoc, deleteField, documentId, doc, getDoc, getDocs, limit, orderBy, query, runTransaction as runFirestoreTransaction, serverTimestamp, setDoc, startAfter, Timestamp, updateDoc, where, } from "firebase/firestore";
 import { get, endBefore, limitToLast, orderByKey, push, query as dbQuery, ref, remove, runTransaction, serverTimestamp as rtdbServerTimestamp, set, update, } from "firebase/database";
 import { httpsCallable } from "firebase/functions";
 import { deleteObject, getDownloadURL, ref as storageRef, uploadBytes, } from "firebase/storage";
@@ -144,6 +144,35 @@ const deleteImageOutputSchema = z.object({
     storageDeletesAttempted: z.number().int().nonnegative(),
     storageDeleteWarnings: z.array(z.string()),
 }).passthrough();
+const imageVariantsOutputSchema = z.object({
+    eventId: z.string(),
+    kind: z.enum(IMAGE_KINDS),
+    cardId: z.string().nullable(),
+    imageId: z.string().nullable(),
+    imageUrl: z.string().url().nullable(),
+    imageMasterUrl: z.string().url().nullable(),
+    imageVariants: unknownRecordSchema.nullable(),
+    ready: z.boolean(),
+    reason: z.string().nullable(),
+    elapsedMs: z.number().int().nonnegative(),
+}).passthrough();
+const cardImagesBatchOutputSchema = z.object({
+    eventId: z.string(),
+    uploads: z.array(unknownRecordSchema),
+    variants: z.array(unknownRecordSchema),
+    ready: z.boolean(),
+    warnings: z.array(z.string()),
+}).passthrough();
+const setupValidationOutputSchema = z.object({
+    eventId: z.string(),
+    ok: z.boolean(),
+    score: z.number().int().min(0).max(100),
+    errors: z.array(unknownRecordSchema),
+    warnings: z.array(unknownRecordSchema),
+    suggestions: z.array(unknownRecordSchema),
+    nextActions: z.array(z.string()),
+    links: unknownRecordSchema,
+}).passthrough();
 const workspaceAccessOutputSchema = z.object({
     workspaceId: z.string(),
     workspace: unknownRecordSchema,
@@ -163,6 +192,32 @@ const nmoImportOutputSchema = z.object({
     summary: unknownRecordSchema,
     results: z.array(unknownRecordSchema),
 }).passthrough();
+const sessionReportOutputSchema = z.object({
+    eventId: z.string(),
+    sessionId: z.string(),
+    reportUrl: z.string().url(),
+    markdown: z.string(),
+    session: unknownRecordSchema,
+}).passthrough();
+const profileOutputSchema = z.object({
+    uid: z.string(),
+    profile: unknownRecordSchema,
+    updated: z.array(z.string()),
+}).passthrough();
+const deleteLeadOutputSchema = z.object({
+    eventId: z.string(),
+    leadId: z.string(),
+    deleted: z.boolean(),
+}).passthrough();
+const notificationsOutputSchema = z.object({
+    notifications: z.array(unknownRecordSchema),
+    unreadCountOnPage: z.number().int().nonnegative(),
+    ...cursorMetaSchema,
+}).passthrough();
+const notificationsMarkOutputSchema = z.object({
+    markedRead: z.number().int().nonnegative(),
+    notificationIds: z.array(z.string()),
+}).passthrough();
 const formFieldSchema = z.object({
     id: z.string().min(1).optional(),
     label: z.string().max(120),
@@ -209,6 +264,11 @@ const telegramChannelSchema = z.object({
     title: z.string().max(200).optional(),
     username: z.string().max(120).nullable().optional(),
 }).strict();
+const profileDisplayNameSchema = z.string().max(40).nullable();
+const timezoneSchema = z.string()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9_+./-]+$/, "Use an IANA timezone such as Europe/Moscow or UTC.");
 const cardsConfigOutputSchema = z.object({
     eventId: z.string(),
     updated: z.array(z.string()),
@@ -480,6 +540,7 @@ function readImageRef(eventData, kind, cardId) {
             imageId: storagePathFromDownloadUrl(safeString(banner.imageMasterUrl))?.split("/").at(-2) ?? null,
             imageUrl: safeString(banner.imageUrl) || null,
             imageMasterUrl: safeString(banner.imageMasterUrl) || null,
+            imageVariants: readImageVariants(banner.imageVariants),
         };
     }
     if (kind === "videoPlaceholder") {
@@ -489,6 +550,7 @@ function readImageRef(eventData, kind, cardId) {
             imageId: storagePathFromDownloadUrl(safeString(placeholder.imageMasterUrl))?.split("/").at(-2) ?? null,
             imageUrl: safeString(placeholder.imageUrl) || null,
             imageMasterUrl: safeString(placeholder.imageMasterUrl) || null,
+            imageVariants: readImageVariants(placeholder.imageVariants),
         };
     }
     if (!cardId)
@@ -502,6 +564,7 @@ function readImageRef(eventData, kind, cardId) {
         imageId: cardId,
         imageUrl: safeString(item.imageUrl) || null,
         imageMasterUrl: safeString(item.imageMasterUrl) || null,
+        imageVariants: readImageVariants(item.imageVariants),
     };
 }
 function cardItemsWithImage(eventData, cardId, patch) {
@@ -662,6 +725,141 @@ async function uploadMasterImage(path, image) {
     });
     return getDownloadURL(ref);
 }
+async function updateCardImageInTransaction(eventId, cardId, patch) {
+    const eventRef = doc(firestore, "events", eventId);
+    await runFirestoreTransaction(firestore, async (transaction) => {
+        const snap = await transaction.get(eventRef);
+        if (!snap.exists())
+            throw new Error("Event not found.");
+        const data = snap.data();
+        transaction.update(eventRef, {
+            "blocks.cards.items": cardItemsWithImage(data, cardId, patch),
+        });
+    });
+}
+function imageVariantReason(ref) {
+    if (!ref.imageMasterUrl && !ref.imageUrl)
+        return "image_missing";
+    if (!ref.imageMasterUrl)
+        return "master_missing";
+    if (!ref.imageVariants)
+        return "variants_pending";
+    if (!ref.imageUrl)
+        return "image_url_pending";
+    return null;
+}
+function imageVariantStatus(eventId, eventData, kind, cardId, elapsedMs) {
+    const ref = readImageRef(eventData, kind, cardId ?? undefined);
+    const reason = imageVariantReason(ref);
+    return {
+        eventId,
+        kind,
+        cardId,
+        imageId: ref.imageId,
+        imageUrl: ref.imageUrl,
+        imageMasterUrl: ref.imageMasterUrl,
+        imageVariants: ref.imageVariants,
+        ready: reason === null,
+        reason,
+        elapsedMs,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForImageVariantTargets(uid, eventId, targets, timeoutSec) {
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutSec * 1000;
+    let latest = targets.map((target) => ({
+        eventId,
+        kind: target.kind,
+        cardId: target.cardId,
+        imageId: target.cardId,
+        imageUrl: null,
+        imageMasterUrl: null,
+        imageVariants: null,
+        ready: false,
+        reason: "not_checked",
+        elapsedMs: 0,
+    }));
+    while (true) {
+        const elapsedMs = Date.now() - startedAt;
+        const event = await readEvent(eventId, uid, "read");
+        latest = targets.map((target) => imageVariantStatus(eventId, event, target.kind, target.cardId, elapsedMs));
+        if (latest.every((item) => item.ready) || Date.now() >= deadline)
+            return latest;
+        await sleep(Math.min(2000, Math.max(250, deadline - Date.now())));
+    }
+}
+async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
+    if (kind === "card" && !cardId)
+        throw new Error("cardId is required when kind is card.");
+    if (kind !== "card" && cardId)
+        throw new Error("cardId is only valid when kind is card.");
+    const event = await readEvent(eventId, uid, "edit");
+    const previous = readImageRef(event, kind, cardId);
+    const sourceBuffer = await readImageSource(source);
+    const masterBuffer = await compressToMasterWebp(sourceBuffer);
+    const imageId = kind === "card" ? cardId : randomUUID();
+    const masterPath = imageStoragePath(eventId, uid, kind, imageId);
+    const previousMasterPath = storagePathFromDownloadUrl(previous.imageMasterUrl);
+    const deleteWarnings = [];
+    let deletesAttempted = 0;
+    if (kind === "card" && previousMasterPath === masterPath) {
+        const variantPaths = variantPathsFromMasterPath(masterPath);
+        deletesAttempted += variantPaths.length;
+        deleteWarnings.push(...await deleteStoragePaths(variantPaths));
+    }
+    let masterUrl = null;
+    try {
+        masterUrl = await uploadMasterImage(masterPath, masterBuffer);
+        if (kind === "promoBanner") {
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.promoBanner.imageMasterUrl": masterUrl,
+                "blocks.promoBanner.imageUrl": masterUrl,
+                "blocks.promoBanner.imageVariants": null,
+            });
+        }
+        else if (kind === "videoPlaceholder") {
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.video.placeholder.imageMasterUrl": masterUrl,
+                "blocks.video.placeholder.imageUrl": masterUrl,
+                "blocks.video.placeholder.imageVariants": null,
+            });
+        }
+        else {
+            await updateCardImageInTransaction(eventId, cardId, {
+                imageUrl: masterUrl,
+                imageMasterUrl: masterUrl,
+                imageVariants: null,
+            });
+        }
+    }
+    catch (err) {
+        if (masterUrl) {
+            await deleteStoragePaths([masterPath, ...variantPathsFromMasterPath(masterPath)]).catch(() => []);
+        }
+        throw err;
+    }
+    if (kind !== "card" || (previousMasterPath && previousMasterPath !== masterPath) || (!previous.imageMasterUrl && previous.imageUrl)) {
+        const cleanup = await deleteStorageUrls(previous.imageMasterUrl, previous.imageUrl);
+        deletesAttempted += cleanup.attempted;
+        deleteWarnings.push(...cleanup.warnings);
+    }
+    return {
+        eventId,
+        kind,
+        imageId,
+        storagePath: masterPath,
+        masterUrl,
+        variantsPending: true,
+        sourceBytes: sourceBuffer.byteLength,
+        masterBytes: masterBuffer.byteLength,
+        note: "Image master uploaded. CF generateImageVariants should publish thumb/card/hero variants and update imageUrl/imageVariants in about 10-30 seconds.",
+        storageDeletesAttempted: deletesAttempted,
+        storageDeleteWarnings: deleteWarnings,
+    };
+}
 async function authed(scopes) {
     return ensureAuth(scopes);
 }
@@ -685,6 +883,9 @@ function setupUrl(eventId) {
 function analyticsUrl(eventId) {
     return `https://okostream.app/analytics/${eventId}`;
 }
+function sessionReportUrl(eventId, sessionId) {
+    return `${analyticsUrl(eventId)}/report/${sessionId}`;
+}
 function nmoRegisterUrl(eventId) {
     return `${eventUrl(eventId)}/register`;
 }
@@ -729,6 +930,145 @@ async function readEvent(eventId, uid, mode = "read") {
         assertEventReadable(data, uid);
     return data;
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function validateEventSetup(eventId, event) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    const add = (target, code, path, message) => {
+        target.push({ code, path, message });
+    };
+    const blocks = asRecord(event.blocks);
+    const forms = Array.isArray(event.forms) ? event.forms.filter((item) => item && typeof item === "object") : [];
+    const formIds = eventFormIds(event);
+    const title = safeString(event.title).trim();
+    if (!title)
+        add(errors, "title_missing", "title", "Event title is required.");
+    const video = asRecord(event.video);
+    if (!safeString(video.embedUrl).trim()) {
+        add(warnings, "video_missing", "video.embedUrl", "No normalized video URL is configured.");
+    }
+    const meta = asRecord(event.meta);
+    const eventDateMs = toMillis(meta.eventDate);
+    if (eventDateMs == null) {
+        add(suggestions, "date_missing", "meta.eventDate", "Add the webinar date/time if it is known.");
+    }
+    else if (eventDateMs < Date.now() - 60 * 60 * 1000) {
+        add(warnings, "date_in_past", "meta.eventDate", "Configured webinar date appears to be in the past.");
+    }
+    const duplicateFormIds = new Set();
+    const seenFormIds = new Set();
+    forms.forEach((form, index) => {
+        const id = safeString(form.id).trim();
+        if (!id)
+            add(errors, "form_id_missing", `forms[${index}].id`, "Every form must have a stable id.");
+        else if (seenFormIds.has(id))
+            duplicateFormIds.add(id);
+        else
+            seenFormIds.add(id);
+        const fields = Array.isArray(form.fields) ? form.fields : [];
+        if (fields.length === 0)
+            add(warnings, "form_fields_missing", `forms[${index}].fields`, "Lead form has no fields.");
+    });
+    for (const id of duplicateFormIds)
+        add(errors, "form_id_duplicate", "forms", `Duplicate form id: ${id}.`);
+    const checkFormBinding = (path, formId) => {
+        const id = safeString(formId).trim();
+        if (id && !formIds.has(id))
+            add(errors, "form_binding_missing", path, `Referenced formId "${id}" does not exist in event.forms.`);
+    };
+    const promo = asRecord(blocks.promoBanner);
+    if (promo.enabled === true) {
+        checkFormBinding("blocks.promoBanner.formId", promo.formId);
+        if (!safeString(promo.link).trim() && !safeString(promo.formId).trim()) {
+            add(suggestions, "promo_target_missing", "blocks.promoBanner", "Enabled promo banner has no link or form binding.");
+        }
+        if (!safeString(promo.imageUrl).trim()) {
+            add(warnings, "promo_image_missing", "blocks.promoBanner.imageUrl", "Enabled promo banner has no image.");
+        }
+        else if (safeString(promo.imageMasterUrl).trim() && !readImageVariants(promo.imageVariants)) {
+            add(warnings, "promo_variants_pending", "blocks.promoBanner.imageVariants", "Promo banner image variants are not ready yet.");
+        }
+    }
+    const cta = asRecord(blocks.primaryCta);
+    if (cta.enabled === true) {
+        checkFormBinding("blocks.primaryCta.formId", cta.formId);
+        if (!safeString(cta.title).trim() && !safeString(cta.text).trim()) {
+            add(suggestions, "cta_copy_missing", "blocks.primaryCta", "Enabled CTA has no title or text.");
+        }
+        if (!safeString(cta.buttonLabel).trim()) {
+            add(warnings, "cta_button_missing", "blocks.primaryCta.buttonLabel", "Enabled CTA has no button label.");
+        }
+        if (safeString(cta.buttonLabel).trim() && !safeString(cta.buttonUrl).trim() && !safeString(cta.formId).trim()) {
+            add(warnings, "cta_target_missing", "blocks.primaryCta", "CTA button has no URL or form binding.");
+        }
+    }
+    const videoPlaceholder = asRecord(asRecord(blocks.video).placeholder);
+    if (videoPlaceholder.enabled === true && videoPlaceholder.mode === "image") {
+        if (!safeString(videoPlaceholder.imageUrl).trim()) {
+            add(warnings, "placeholder_image_missing", "blocks.video.placeholder.imageUrl", "Image placeholder mode is enabled but no image is configured.");
+        }
+        else if (safeString(videoPlaceholder.imageMasterUrl).trim() && !readImageVariants(videoPlaceholder.imageVariants)) {
+            add(warnings, "placeholder_variants_pending", "blocks.video.placeholder.imageVariants", "Video placeholder image variants are not ready yet.");
+        }
+    }
+    const cards = readCardsConfig(event);
+    if (cards.enabled) {
+        if (cards.items.length === 0)
+            add(warnings, "cards_empty", "blocks.cards.items", "Cards block is enabled but has no cards.");
+        const cardIds = new Set();
+        cards.items.forEach((card, index) => {
+            const path = `blocks.cards.items[${index}]`;
+            if (cardIds.has(card.id))
+                add(errors, "card_id_duplicate", `${path}.id`, `Duplicate card id: ${card.id}.`);
+            cardIds.add(card.id);
+            if (!card.title && !card.text)
+                add(suggestions, "card_copy_missing", path, "Card has no title or text.");
+            if (card.buttonLabel && !card.buttonUrl && !card.formId)
+                add(warnings, "card_target_missing", path, "Card button has no URL or form binding.");
+            if (card.formId && !formIds.has(card.formId))
+                add(errors, "card_form_missing", `${path}.formId`, `Referenced formId "${card.formId}" does not exist.`);
+            if (card.imageMasterUrl && !card.imageVariants)
+                add(warnings, "card_variants_pending", `${path}.imageVariants`, "Card image variants are not ready yet.");
+        });
+    }
+    const telegram = asRecord(event.telegram);
+    const telegramChannels = Array.isArray(telegram.channelIds) ? telegram.channelIds : [];
+    if (telegram.enabled === true && telegramChannels.length === 0 && typeof telegram.channelId !== "number") {
+        add(warnings, "telegram_channel_missing", "telegram.channelIds", "Telegram is enabled but no channel is configured.");
+    }
+    if (event.nmoMode === true) {
+        const criteria = asRecord(event.nmoCriteria);
+        const watch = typeof criteria.minWatchTimeRatio === "number" ? criteria.minWatchTimeRatio : 0.8;
+        const checkpoints = typeof criteria.minCheckpointRatio === "number" ? criteria.minCheckpointRatio : 0.8;
+        if (watch < 0 || watch > 1 || checkpoints < 0 || checkpoints > 1) {
+            add(errors, "nmo_criteria_invalid", "nmoCriteria", "NMO criteria ratios must be between 0 and 1.");
+        }
+        const participantUids = Array.isArray(event.participantUids) ? event.participantUids : [];
+        if (participantUids.length === 0) {
+            add(warnings, "nmo_participants_missing", "participantUids", "NMO mode is enabled but no participants are registered yet.");
+        }
+    }
+    const nextActions = [
+        ...errors.map((item) => `Fix error: ${item.message}`),
+        ...warnings.slice(0, 5).map((item) => `Review warning: ${item.message}`),
+    ];
+    if (nextActions.length === 0)
+        nextActions.push("No blocking setup issues found.");
+    const penalty = errors.length * 25 + warnings.length * 8 + suggestions.length * 2;
+    return {
+        eventId,
+        ok: errors.length === 0,
+        score: Math.max(0, Math.min(100, 100 - penalty)),
+        errors,
+        warnings,
+        suggestions,
+        nextActions,
+        links: eventLinks(eventId, event),
+    };
+}
 function canEditEventWithPermissions(perms) {
     return perms.editSetup === true || perms.controlLive === true || perms.startSession === true;
 }
@@ -1200,6 +1540,70 @@ function compactAnalyticsSession(raw, options) {
     }
     return session;
 }
+function numberMetric(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function formatSeconds(value) {
+    const seconds = numberMetric(value);
+    if (seconds == null)
+        return "n/a";
+    const total = Math.max(0, Math.round(seconds));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${String(m).padStart(2, "0")}m ${String(s).padStart(2, "0")}s`;
+    return `${m}m ${String(s).padStart(2, "0")}s`;
+}
+function formatDateTime(value) {
+    const millis = toMillis(value);
+    if (millis == null)
+        return "n/a";
+    return new Date(millis).toISOString();
+}
+function markdownMetric(label, value, suffix = "") {
+    const metric = value === null || value === undefined || value === "" ? "n/a" : String(value);
+    return `- ${label}: ${metric}${suffix}`;
+}
+function sessionReportMarkdown({ eventId, event, sessionId, session, }) {
+    const lines = [
+        `# OKO session report`,
+        "",
+        `Event: ${safeString(event.title, eventId)}`,
+        `Event URL: ${eventUrl(eventId)}`,
+        `Report URL: ${sessionReportUrl(eventId, sessionId)}`,
+        `Session: ${sessionId}`,
+        "",
+        "## Timing",
+        markdownMetric("Started", formatDateTime(session.startedAt)),
+        markdownMetric("Ended", formatDateTime(session.endedAt)),
+        markdownMetric("Duration", formatSeconds(session.durationSec)),
+        "",
+        "## Audience",
+        markdownMetric("Peak viewers", session.peakViewers),
+        markdownMetric("Unique visitors", session.uniqueVisitors),
+        markdownMetric("Views", session.viewCount),
+        markdownMetric("Average watch time", formatSeconds(session.avgTimeSec)),
+        markdownMetric("Median watch time", formatSeconds(session.medianTimeSec)),
+        "",
+        "## Engagement",
+        markdownMetric("Chat messages", session.chatMessages),
+        markdownMetric("Banner impressions", session.bannerImpressions),
+        markdownMetric("Banner clicks", session.bannerClicks),
+        markdownMetric("Banner CTR", session.bannerCtr, session.bannerCtr == null ? "" : "%"),
+        markdownMetric("CTA clicks", session.ctaClicks),
+        markdownMetric("Cards clicks", session.cardsClicks),
+    ];
+    const nmo = session.nmoEvaluation;
+    if (nmo && typeof nmo === "object" && !Array.isArray(nmo)) {
+        const summary = nmo.summary;
+        if (summary && typeof summary === "object" && !Array.isArray(summary)) {
+            const s = summary;
+            lines.push("", "## NMO", markdownMetric("Passed", s.passed), markdownMetric("Failed", s.failed), markdownMetric("No-show", s.noShow), markdownMetric("Total", s.total));
+        }
+    }
+    return lines.join("\n");
+}
 export function registerTools(server) {
     server.registerTool("oko_whoami", {
         title: "Who am I",
@@ -1217,6 +1621,39 @@ export function registerTools(server) {
         const auth = await authed([]);
         return textResult({ uid: auth.uid, scopes: currentScopes() });
     });
+    server.registerTool("oko_update_profile", {
+        title: "Update profile",
+        description: toolDescription({
+            summary: "Update the authenticated organizer profile fields used by OKO UI.",
+            args: [
+                "displayName: optional display name, max 40 chars; null clears it.",
+                "timezone: optional IANA timezone such as Europe/Moscow or UTC.",
+            ],
+            returns: "uid, updated field names, and the resulting profile snapshot.",
+            examples: ["Use when the organizer asks to change their visible OKO name or timezone."],
+            notes: ["This edits only the current organizer's own userProfiles document and does not require extra workspace/event scopes."],
+        }),
+        inputSchema: {
+            displayName: profileDisplayNameSchema.optional().describe("Display name, max 40 chars. Null clears it."),
+            timezone: timezoneSchema.optional().describe("IANA timezone, for example Europe/Moscow or UTC."),
+        },
+        outputSchema: profileOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ displayName, timezone }) => {
+        const { uid } = await authed([]);
+        const patch = { updatedAt: serverTimestamp() };
+        if (displayName !== undefined)
+            patch.displayName = displayName?.trim() || null;
+        if (timezone !== undefined)
+            patch.timezone = timezone.trim();
+        const updated = Object.keys(patch).filter((key) => key !== "updatedAt");
+        if (updated.length === 0)
+            throw new Error("Provide displayName and/or timezone.");
+        const profileRef = doc(firestore, "userProfiles", uid);
+        await setDoc(profileRef, patch, { merge: true });
+        const profileSnap = await getDoc(profileRef);
+        return textResult({ uid, updated, profile: profileSnap.exists() ? serialize(profileSnap.data()) : {} });
+    });
     server.registerTool("oko_list_workspaces", {
         title: "List workspaces",
         description: toolDescription({
@@ -1487,6 +1924,26 @@ export function registerTools(server) {
         const data = await readEvent(eventId, uid, "read");
         return textResult({ id: eventId, ...serialize(data), ...eventLinks(eventId, data) });
     });
+    server.registerTool("oko_validate_event_setup", {
+        title: "Validate event setup",
+        description: toolDescription({
+            summary: "Run a read-only setup readiness lint for one OKO event.",
+            args: ["eventId: OKO event document id."],
+            returns: "ok flag, score, errors, warnings, suggestions, next actions, and useful links.",
+            examples: [
+                "Use after creating/configuring a webinar and before telling the organizer it is ready.",
+                "Use before live-session prep to catch missing video, pending image variants, invalid form bindings, or NMO participant gaps.",
+            ],
+            notes: ["This tool does not modify the event and does not start/end analytics sessions."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: setupValidationOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["events:read"]);
+        const data = await readEvent(eventId, uid, "read");
+        return textResult(validateEventSetup(eventId, data));
+    });
     server.registerTool("oko_create_webinar", {
         title: "Create webinar",
         description: toolDescription({
@@ -1813,72 +2270,89 @@ export function registerTools(server) {
         annotations: writeTool,
     }, async ({ eventId, kind, cardId, source }) => {
         const { uid } = await authed(["setup:write"]);
-        if (kind === "card" && !cardId)
-            throw new Error("cardId is required when kind is card.");
-        if (kind !== "card" && cardId)
-            throw new Error("cardId is only valid when kind is card.");
-        const event = await readEvent(eventId, uid, "edit");
-        const previous = readImageRef(event, kind, cardId);
-        const sourceBuffer = await readImageSource(source);
-        const masterBuffer = await compressToMasterWebp(sourceBuffer);
-        const imageId = kind === "card" ? cardId : randomUUID();
-        const masterPath = imageStoragePath(eventId, uid, kind, imageId);
-        const previousMasterPath = storagePathFromDownloadUrl(previous.imageMasterUrl);
-        const deleteWarnings = [];
-        let deletesAttempted = 0;
-        if (kind === "card" && previousMasterPath === masterPath) {
-            const variantPaths = variantPathsFromMasterPath(masterPath);
-            deletesAttempted += variantPaths.length;
-            deleteWarnings.push(...await deleteStoragePaths(variantPaths));
-        }
-        let masterUrl = null;
-        try {
-            masterUrl = await uploadMasterImage(masterPath, masterBuffer);
-            const patch = {};
-            if (kind === "promoBanner") {
-                patch["blocks.promoBanner.imageMasterUrl"] = masterUrl;
-                patch["blocks.promoBanner.imageUrl"] = masterUrl;
-                patch["blocks.promoBanner.imageVariants"] = null;
-            }
-            else if (kind === "videoPlaceholder") {
-                patch["blocks.video.placeholder.imageMasterUrl"] = masterUrl;
-                patch["blocks.video.placeholder.imageUrl"] = masterUrl;
-                patch["blocks.video.placeholder.imageVariants"] = null;
-            }
-            else {
-                patch["blocks.cards.items"] = cardItemsWithImage(event, cardId, {
-                    imageUrl: masterUrl,
-                    imageMasterUrl: masterUrl,
-                    imageVariants: null,
-                });
-            }
-            await updateDoc(doc(firestore, "events", eventId), patch);
-        }
-        catch (err) {
-            if (masterUrl) {
-                await deleteStoragePaths([masterPath, ...variantPathsFromMasterPath(masterPath)]).catch(() => []);
-            }
-            throw err;
-        }
-        if (kind !== "card" || (previousMasterPath && previousMasterPath !== masterPath) || (!previous.imageMasterUrl && previous.imageUrl)) {
-            const cleanup = await deleteStorageUrls(previous.imageMasterUrl, previous.imageUrl);
-            deletesAttempted += cleanup.attempted;
-            deleteWarnings.push(...cleanup.warnings);
+        return textResult(await uploadEventImageForUser(uid, eventId, kind, cardId, source));
+    });
+    server.registerTool("oko_upload_card_images_batch", {
+        title: "Upload card images batch",
+        description: toolDescription({
+            summary: "Upload images for multiple existing cards, preserving card metadata with Firestore transactions and waiting for generated variants.",
+            args: [
+                "eventId: event to edit.",
+                "images: 1-6 card image uploads. Each cardId must already exist in blocks.cards.items.",
+                "timeoutSec: max wait for all CF-generated image variants, default 60 seconds.",
+            ],
+            returns: "eventId, per-card upload details, per-card variant readiness, ready flag, and warnings.",
+            examples: [
+                "Use after oko_configure_cards has returned stable card ids.",
+                "Use for webinar cards where an agent generated several local images and needs to attach all of them.",
+            ],
+            notes: [
+                "This is a workflow tool for cards only. Use oko_upload_image for promoBanner or videoPlaceholder.",
+                "The tool does not create cards; it only attaches images to existing cards.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            images: z.array(z.object({
+                cardId: cardIdSchema.describe("Existing card id."),
+                source: imageSourceSchema.describe("Image source for this card."),
+            }).strict()).min(1).max(MAX_CARD_ITEMS).describe("Card images to upload."),
+            timeoutSec: z.number().int().min(1).max(120).default(60).describe("Maximum seconds to wait for all generated variants."),
+        },
+        outputSchema: cardImagesBatchOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId, images, timeoutSec }) => {
+        const { uid } = await authed(["setup:write"]);
+        const uploads = [];
+        for (const image of images) {
+            uploads.push(await uploadEventImageForUser(uid, eventId, "card", image.cardId, image.source));
         }
+        const variants = await waitForImageVariantTargets(uid, eventId, images.map((image) => ({ kind: "card", cardId: image.cardId })), timeoutSec);
+        const warnings = variants
+            .filter((item) => !item.ready)
+            .map((item) => `Card ${item.cardId ?? "unknown"} variants are not ready yet: ${item.reason ?? "unknown"}.`);
         return textResult({
             eventId,
-            kind,
-            imageId,
-            storagePath: masterPath,
-            masterUrl,
-            variantsPending: true,
-            sourceBytes: sourceBuffer.byteLength,
-            masterBytes: masterBuffer.byteLength,
-            note: "Image master uploaded. CF generateImageVariants should publish thumb/card/hero variants and update imageUrl/imageVariants in about 10-30 seconds.",
-            storageDeletesAttempted: deletesAttempted,
-            storageDeleteWarnings: deleteWarnings,
+            uploads,
+            variants,
+            ready: variants.every((item) => item.ready),
+            warnings,
         });
     });
+    server.registerTool("oko_wait_for_image_variants", {
+        title: "Wait for image variants",
+        description: toolDescription({
+            summary: "Poll an event image slot until Cloud Function generated thumb/card/hero variants are visible in Firestore.",
+            args: [
+                "eventId: event to inspect.",
+                "kind: promoBanner, videoPlaceholder, or card.",
+                "cardId: required when kind=card.",
+                "timeoutSec: max wait, default 60 seconds.",
+            ],
+            returns: "image URLs, imageVariants, ready flag, pending reason, and elapsed time.",
+            examples: ["Use after oko_upload_image to avoid checking the UI before image variants are ready."],
+            notes: ["Read-only. It does not trigger variant generation; it only waits for CF4's Firestore update."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            kind: z.enum(IMAGE_KINDS).describe("Target image slot."),
+            cardId: z.string().min(1).optional().describe("Required when kind=card."),
+            timeoutSec: z.number().int().min(1).max(120).default(60).describe("Maximum seconds to wait."),
+        },
+        outputSchema: imageVariantsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, kind, cardId, timeoutSec }) => {
+        const { uid } = await authed(["events:read"]);
+        if (kind === "card" && !cardId)
+            throw new Error("cardId is required when kind is card.");
+        if (kind !== "card" && cardId)
+            throw new Error("cardId is only valid when kind is card.");
+        const statuses = await waitForImageVariantTargets(uid, eventId, [{ kind, cardId: cardId ?? null }], timeoutSec);
+        const status = statuses[0];
+        if (!status)
+            throw new Error("Image variant status was not produced.");
+        return textResult(status);
+    });
     server.registerTool("oko_delete_image", {
         title: "Delete event image",
         description: toolDescription({
@@ -1911,25 +2385,27 @@ export function registerTools(server) {
         const previous = readImageRef(event, kind, cardId);
         requireConfirm(confirm, "oko_delete_image", { eventId, kind, cardId: cardId ?? null, imageId: previous.imageId });
         const cleanup = await deleteStorageUrls(previous.imageMasterUrl, previous.imageUrl);
-        const patch = {};
         if (kind === "promoBanner") {
-            patch["blocks.promoBanner.imageMasterUrl"] = deleteField();
-            patch["blocks.promoBanner.imageUrl"] = deleteField();
-            patch["blocks.promoBanner.imageVariants"] = deleteField();
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.promoBanner.imageMasterUrl": deleteField(),
+                "blocks.promoBanner.imageUrl": deleteField(),
+                "blocks.promoBanner.imageVariants": deleteField(),
+            });
         }
         else if (kind === "videoPlaceholder") {
-            patch["blocks.video.placeholder.imageMasterUrl"] = deleteField();
-            patch["blocks.video.placeholder.imageUrl"] = deleteField();
-            patch["blocks.video.placeholder.imageVariants"] = deleteField();
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.video.placeholder.imageMasterUrl": deleteField(),
+                "blocks.video.placeholder.imageUrl": deleteField(),
+                "blocks.video.placeholder.imageVariants": deleteField(),
+            });
         }
         else {
-            patch["blocks.cards.items"] = cardItemsWithImage(event, cardId, {
+            await updateCardImageInTransaction(eventId, cardId, {
                 imageUrl: null,
                 imageMasterUrl: null,
                 imageVariants: null,
             });
         }
-        await updateDoc(doc(firestore, "events", eventId), patch);
         return textResult({
             eventId,
             kind,
@@ -2505,6 +2981,65 @@ export function registerTools(server) {
         const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().startedAt) : null;
         return textResult({ sessions, ...cursorMeta(sessions.length, max, hasMore, nextCursor) }, { truncationHint: "Use limit/cursor or keep includeTimeline/includeSnapshots/includeNmoRows disabled." });
     });
+    server.registerTool("oko_get_session_report", {
+        title: "Get session report",
+        description: toolDescription({
+            summary: "Build a ready-to-share report for one analytics session, with compact structured data and markdown.",
+            args: [
+                "eventId: event to inspect.",
+                "sessionId: optional analytics session id; omitted means latest session.",
+                "includeTimeline: include recent timeline buckets; default false.",
+                "timelineLimit: max timeline buckets when includeTimeline=true.",
+                "includeSnapshots: include baseline/final snapshots; default false.",
+                "includeNmoRows: include full NMO participant rows; default false.",
+            ],
+            returns: "event/session ids, report URL, markdown summary, event summary, and compact session object.",
+            examples: ["Use after a webinar when the user asks for the finished session report without manually opening the report page."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            sessionId: z.string().min(1).optional().describe("analyticsSessions document id. Omit to use the latest session."),
+            includeTimeline: z.boolean().default(false).describe("Include recent timeline buckets."),
+            timelineLimit: z.number().int().min(1).max(500).default(ANALYTICS_TIMELINE_DEFAULT_LIMIT).describe("Max timeline buckets when includeTimeline=true."),
+            includeSnapshots: z.boolean().default(false).describe("Include baselineSnapshot and finalSnapshot."),
+            includeNmoRows: z.boolean().default(false).describe("Include full NMO participant rows when present."),
+        },
+        outputSchema: sessionReportOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, sessionId, includeTimeline, timelineLimit, includeSnapshots, includeNmoRows }) => {
+        const { uid } = await authed(["analytics:read"]);
+        const event = await readEvent(eventId, uid, "read");
+        let resolvedSessionId = sessionId;
+        let sessionData = null;
+        if (resolvedSessionId) {
+            const sessionSnap = await getDoc(doc(firestore, "events", eventId, "analyticsSessions", resolvedSessionId));
+            if (!sessionSnap.exists())
+                throw new Error("Analytics session not found.");
+            sessionData = sessionSnap.data();
+        }
+        else {
+            const snap = await getDocs(query(collection(firestore, "events", eventId, "analyticsSessions"), orderBy("startedAt", "desc"), limit(1)));
+            const first = snap.docs[0];
+            if (!first)
+                throw new Error("No analytics sessions found for this event.");
+            resolvedSessionId = first.id;
+            sessionData = first.data();
+        }
+        const session = compactAnalyticsSession({ id: resolvedSessionId, ...sessionData }, { includeTimeline, timelineLimit, includeSnapshots, includeNmoRows });
+        const markdown = sessionReportMarkdown({ eventId, event, sessionId: resolvedSessionId, session });
+        return textResult({
+            eventId,
+            sessionId: resolvedSessionId,
+            event: {
+                id: eventId,
+                title: safeString(event.title, eventId),
+                ...eventLinks(eventId, event),
+            },
+            reportUrl: sessionReportUrl(eventId, resolvedSessionId),
+            markdown,
+            session,
+        }, { truncationHint: "Keep includeTimeline/includeSnapshots/includeNmoRows disabled or lower timelineLimit." });
+    });
     server.registerTool("oko_list_recent_chat", {
         title: "List recent chat",
         description: toolDescription({
@@ -2910,6 +3445,108 @@ export function registerTools(server) {
         }
         return textResult({ leads, ...meta });
     });
+    server.registerTool("oko_delete_lead", {
+        title: "Delete form lead",
+        description: toolDescription({
+            summary: "Delete one lead/form submission from an event.",
+            args: ["eventId: event id.", "leadId: events/{eventId}/leads document id.", "confirm: must be true."],
+            returns: "eventId, leadId, deleted=true, and a small preview of the deleted lead.",
+            examples: ["Use after listing leads and confirming the exact submission to remove."],
+            notes: ["Destructive. Requires setup:write in addition to leads:read so read-only keys cannot delete leads."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            leadId: z.string().min(1).max(160).describe("Lead document id under events/{eventId}/leads."),
+            confirm: z.boolean().optional().describe("Required true for lead deletion."),
+        },
+        outputSchema: deleteLeadOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, leadId, confirm }) => {
+        const { uid } = await authed(["leads:read", "setup:write"]);
+        await readEvent(eventId, uid, "edit");
+        const leadRef = doc(firestore, "events", eventId, "leads", leadId);
+        const leadSnap = await getDoc(leadRef);
+        if (!leadSnap.exists())
+            throw new Error("Lead not found.");
+        const lead = serialize(leadSnap.data());
+        requireConfirm(confirm, "oko_delete_lead", { eventId, leadId, formId: lead.formId, source: lead.source, submittedAt: lead.submittedAt });
+        await deleteDoc(leadRef);
+        return textResult({ eventId, leadId, deleted: true, leadPreview: lead });
+    });
+    server.registerTool("oko_list_notifications", {
+        title: "List notifications",
+        description: toolDescription({
+            summary: "List in-app notifications for the authenticated organizer.",
+            args: [
+                "unreadOnly: only unread notifications, default false.",
+                "limit: max notifications, default 20, max 100.",
+                "cursor: createdAt cursor returned as nextCursor by the previous page.",
+            ],
+            returns: "notifications plus unreadCountOnPage and cursor pagination metadata.",
+            examples: ["Use when the organizer asks what changed in OKO or what notifications are waiting."],
+        }),
+        inputSchema: {
+            unreadOnly: z.boolean().default(false).describe("Return only unread notifications."),
+            limit: limitField(100, 20),
+            cursor: cursorField,
+        },
+        outputSchema: notificationsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ unreadOnly, limit: max, cursor }) => {
+        const { uid } = await authed(["workspace:read"]);
+        const fetchLimit = unreadOnly ? Math.min(max * 5 + 1, 501) : max + 1;
+        const constraints = [
+            orderBy("createdAt", "desc"),
+            limit(fetchLimit),
+        ];
+        if (cursor)
+            constraints.splice(1, 0, startAfter(parseTimestampCursor(cursor)));
+        const snap = await getDocs(query(collection(firestore, "userNotifications", uid, "items"), ...constraints));
+        const matchingDocs = unreadOnly ? snap.docs.filter((item) => item.data().read !== true) : snap.docs;
+        const { page, hasMore: hasMoreInMatches } = pickPage(matchingDocs, max);
+        const hasMore = hasMoreInMatches || snap.docs.length >= fetchLimit;
+        const cursorSource = hasMoreInMatches ? page.at(-1) : snap.docs.at(-1);
+        const notifications = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
+        const nextCursor = hasMore ? timestampCursorFrom(cursorSource?.data().createdAt) : null;
+        return textResult({
+            notifications,
+            unreadCountOnPage: notifications.filter((item) => item.read !== true).length,
+            ...cursorMeta(notifications.length, max, hasMore, nextCursor),
+        });
+    });
+    server.registerTool("oko_mark_notifications_read", {
+        title: "Mark notifications read",
+        description: toolDescription({
+            summary: "Mark own OKO in-app notifications as read.",
+            args: [
+                "notificationIds: optional explicit notification ids, max 100.",
+                "allUnread: true to mark unread notifications on the first page, max controlled by limit.",
+                "limit: when allUnread=true, max unread notifications to mark, default 100, max 200.",
+            ],
+            returns: "markedRead count and notification ids updated.",
+            examples: ["Use after oko_list_notifications when the user asks to clear the bell/unread state."],
+            notes: ["Provide either notificationIds or allUnread=true. This can update only the current organizer's own notifications."],
+        }),
+        inputSchema: {
+            notificationIds: z.array(z.string().min(1).max(160)).max(100).optional().describe("Specific notification document ids."),
+            allUnread: z.boolean().default(false).describe("Mark unread notifications as read."),
+            limit: limitField(200, 100),
+        },
+        outputSchema: notificationsMarkOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ notificationIds, allUnread, limit: max }) => {
+        const { uid } = await authed(["workspace:read"]);
+        if (Boolean(notificationIds?.length) === allUnread) {
+            throw new Error("Provide either notificationIds or allUnread=true.");
+        }
+        let ids = [...new Set(notificationIds ?? [])];
+        if (allUnread) {
+            const snap = await getDocs(query(collection(firestore, "userNotifications", uid, "items"), where("read", "==", false), limit(max)));
+            ids = snap.docs.map((item) => item.id);
+        }
+        await Promise.all(ids.map((id) => updateDoc(doc(firestore, "userNotifications", uid, "items", id), { read: true })));
+        return textResult({ markedRead: ids.length, notificationIds: ids });
+    });
     server.registerTool("oko_list_telegram_channels", {
         title: "List Telegram channels",
         description: toolDescription({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for managing OKO Stream webinars as an organizer.",
   "license": "UNLICENSED",
   "type": "module",