@pitcher/cli-scripts 3.1.0 → 3.2.0

package/dist/src/core/dsr-visits.js

@@ -0,0 +1,191 @@
+/**
+ * One DSR viewer's event timeline (`/analytics/canvas-details/sessions`) → visits, and per visit the
+ * sections, files and pages viewed with their time (PIT-9589). The visit rule is the Sharing
+ * Analytics app's (`packages/apps/canvas-analytics/src/lib/reconstructSessions.ts`): a visit opens
+ * on an `Entered` of the canvas itself and is keyed by its `event_pair_id`; its engaged time is the
+ * sum of its focus segments (canvas Entered → Exited). Change them together.
+ *
+ * Item time: the sum of the item's `Exited` durations (`forhowlong`, seconds) in the visit. An
+ * `Entered` with no `Exited` (the unload beacon was dropped, PIT-5833) or an `Exited` reporting 0 is
+ * estimated from the gap to the next event of the visit, as the app's timeline does, and flagged
+ * `estimated`.
+ */
+const ITEM_TYPES = { Section: 'section', File: 'file', Page: 'page' };
+// The page index is the LAST path segment, `<fileId>/page/<n>` or the older `<fileId>/<n>`, 0-based.
+const PAGE_INDEX_SUFFIX = /\/(?:page\/)?(\d+)$/;
+const ms = (ts) => new Date(ts).getTime();
+const seconds = (from, to) => Math.max(0, Math.round((ms(to) - ms(from)) / 1000));
+function sortPriority(e, anchorId) {
+    const isAnchor = e.entity_id === anchorId;
+    if (!isAnchor && e.action === 'Exited')
+        return 1;
+    if (isAnchor && e.action === 'Exited')
+        return 2;
+    if (isAnchor && e.action === 'Entered')
+        return 3;
+    if (!isAnchor && e.action === 'Entered')
+        return 4;
+    return 5;
+}
+/** `reconstructSessions`' grouping: events from an anchor `Entered` until the next one, by pair key. */
+export function groupVisits(events, anchorId) {
+    const sorted = [...events].sort((a, b) => a.timestamp.localeCompare(b.timestamp) || sortPriority(a, anchorId) - sortPriority(b, anchorId));
+    const groups = new Map();
+    let key = null;
+    let legacy = 0;
+    for (const e of sorted) {
+        if (e.entity_id === anchorId && e.action === 'Entered') {
+            key = e.event_pair_id ? `pair:${e.event_pair_id}` : `legacy:${++legacy}`;
+        }
+        if (!key)
+            continue;
+        const g = groups.get(key);
+        if (g)
+            g.push(e);
+        else
+            groups.set(key, [e]);
+    }
+    return Array.from(groups.values()).filter((g) => g.length > 0);
+}
+/** `computeEngagementDuration`: the wall-clock of each canvas focus segment, summed. */
+export function engagedSeconds(events, anchorId) {
+    let total = 0;
+    let start = null;
+    let last = null;
+    const flush = (end) => {
+        if (start && end)
+            total += seconds(start, end);
+        start = null;
+        last = null;
+    };
+    for (const e of events) {
+        if (e.entity_id === anchorId) {
+            if (e.action === 'Entered') {
+                flush(last);
+                start = e.timestamp;
+                last = e.timestamp;
+            }
+            else if (e.action === 'Exited') {
+                flush(e.timestamp);
+            }
+        }
+        else if (start) {
+            last = e.timestamp;
+        }
+    }
+    flush(last);
+    return total;
+}
+function itemsOf(events, anchorId) {
+    const items = new Map();
+    const open = new Map(); // entity → indexes of unmatched Entered
+    const item = (e) => {
+        const type = ITEM_TYPES[e.original_event_name];
+        if (!type || e.entity_id === anchorId)
+            return null;
+        let it = items.get(e.entity_id);
+        if (!it) {
+            const pageIdx = type === 'page' ? PAGE_INDEX_SUFFIX.exec(e.entity_id) : null;
+            it = {
+                type,
+                id: e.entity_id,
+                name: e.entity_name || e.entity_type || e.entity_id,
+                ...(pageIdx ? { page_number: Number(pageIdx[1]) + 1 } : {}),
+                views: 0,
+                seconds: 0,
+                estimated: false,
+            };
+            items.set(e.entity_id, it);
+        }
+        return it;
+    };
+    const gapToNext = (i) => (i + 1 < events.length ? seconds(events[i].timestamp, events[i + 1].timestamp) : 0);
+    events.forEach((e, i) => {
+        const it = item(e);
+        if (!it)
+            return;
+        if (e.action === 'Entered') {
+            it.views += 1;
+            open.set(e.entity_id, [...(open.get(e.entity_id) ?? []), i]);
+        }
+        else if (e.action === 'Exited') {
+            const pending = open.get(e.entity_id) ?? [];
+            const enteredAt = pending.shift();
+            open.set(e.entity_id, pending);
+            if (enteredAt === undefined)
+                it.views = Math.max(it.views, 1); // an Exited-only view (adblock): still a view
+            const reported = typeof e.duration === 'number' && e.duration > 0 ? e.duration : 0;
+            if (reported > 0) {
+                it.seconds += reported;
+            }
+            else if (enteredAt !== undefined) {
+                it.seconds += seconds(events[enteredAt].timestamp, e.timestamp);
+                it.estimated = true;
+            }
+        }
+    });
+    // Entered with no Exited in the visit: the gap to the next event.
+    for (const [id, pending] of open) {
+        const it = items.get(id);
+        for (const i of pending) {
+            it.seconds += gapToNext(i);
+            it.estimated = true;
+        }
+    }
+    return Array.from(items.values());
+}
+export function summarizeVisits(events, canvasId) {
+    return groupVisits(events, canvasId).map((g, i) => ({
+        visit: i + 1,
+        started_at: g[0].timestamp,
+        ended_at: g[g.length - 1].timestamp,
+        engaged_seconds: engagedSeconds(g, canvasId),
+        items: itemsOf(g, canvasId),
+    }));
+}
+/** RFC 4180 cell; a leading = + - @ is prefixed with ' so a spreadsheet never runs it as a formula. */
+export function csvCell(v) {
+    let s = v == null ? '' : String(v);
+    if (/^[=+\-@\t\r]/.test(s))
+        s = `'${s}`;
+    return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+export const VISITS_CSV_HEADER = [
+    'viewer',
+    'visit',
+    'visit_started_at',
+    'visit_engaged_seconds',
+    'item_type',
+    'item_name',
+    'page_number',
+    'item_id',
+    'views',
+    'seconds',
+    'estimated',
+];
+export function visitsToCsv(viewers) {
+    const lines = [VISITS_CSV_HEADER.join(',')];
+    for (const { viewer, visits } of viewers) {
+        for (const v of visits) {
+            const items = v.items.length ? v.items : [null];
+            for (const it of items) {
+                lines.push([
+                    viewer,
+                    v.visit,
+                    v.started_at,
+                    v.engaged_seconds,
+                    it?.type ?? '',
+                    it?.name ?? '',
+                    it?.page_number ?? '',
+                    it?.id ?? '',
+                    it?.views ?? '',
+                    it?.seconds ?? '',
+                    it ? String(it.estimated) : '',
+                ]
+                    .map(csvCell)
+                    .join(','));
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/src/core/pitcherAuth.d.ts

@@ -28,8 +28,6 @@ export declare function orgSubdomain(domain: string): string;
  * in step when a tenant is added.
  */
 export declare const AUTH0_NATIVE_CLIENT_IDS: Readonly<Record<string, string>>;
-/** The hosted MCP connector's access for an org (`pitcher_organization.settings.mcp.access`, PIT-9768). */
-export type McpAccess = 'off' | 'read_only' | 'full';
 export interface OrgConfig {
     /** The Auth0 CUSTOM domain (`auth0.test-eu.pitcher.com`) — the key into the client-id maps. */
     auth0Domain: string;
@@ -38,11 +36,6 @@ export interface OrgConfig {
     organization: string | null;
     /** `'test' | 'production'`. OPTIONAL upstream: treat unknown as production. */
     environment?: string;
-    /**
-     * undefined = UNKNOWN: next-core's org lookup failed, or that region's next-core predates the field. Never
-     * read it as "off" and never as "on" — the hosted server retries or refuses (`mcp-server` `src/oauth/access.ts`).
-     */
-    mcpAccess?: McpAccess;
 }
 export interface Auth0Tokens {
     access_token: string;

package/dist/src/core/pitcherAuth.js

@@ -38,7 +38,6 @@ export const AUTH0_NATIVE_CLIENT_IDS = {
     'auth0.test-us.pitcher.com': 'sd6biLE9qGBwUfSzl2uRC1p5JdhKY06N',
     'auth0.us.pitcher.com': 'k6BgMI2Oy26RnyucUsWiL81JOeaufECm',
 };
-const MCP_ACCESS = new Set(['off', 'read_only', 'full']);
 export function createUpstreamError(kind, message) {
     return Object.assign(new Error(message), { isUpstreamError: true, kind });
 }
@@ -98,8 +97,6 @@ export async function fetchOrgConfig(domain, opts = {}) {
         audience: a.audience,
         organization: typeof a.organization === 'string' && a.organization ? a.organization : null,
         environment: typeof json.environment === 'string' ? json.environment : undefined,
-        // A value outside the three is a newer next-core than this code: refuse it like "off", not like unknown.
-        mcpAccess: typeof json.mcp?.access === 'string' ? (MCP_ACCESS.has(json.mcp.access) ? json.mcp.access : 'off') : undefined,
     };
 }
 async function postJson(url, body, opts) {

package/dist/src/core/roleplay-stats.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The AI Roleplay manager-app's per-rep rules, ported 1:1 so the MCP team tool and the manager
+ * app give the same answer on the same data (PIT-9200). Sources, in ng-production-apps
+ * `pitcher-coach/manager-app/src/`: `lib/session-score.ts` (reading a score), `lib/stats.ts`
+ * (best, mean, trend), `lib/status.ts` (`deriveStatus`) and `hooks/useManagerData.ts`
+ * (`getAssignmentSessions`, `getRepStats`). Change them together.
+ *
+ * The one rule every aggregate here obeys: a session is unscored iff `overallScore` is not a
+ * finite number. An unscored session is never read as 0.
+ */
+export interface RoleplaySessionLike {
+    userId?: string;
+    scenarioId?: string;
+    timestamp?: string;
+    overallScore?: number | null;
+    durationMs?: number | null;
+    evaluation?: {
+        category_scores?: Array<{
+            id?: string;
+            skillId?: string;
+            title?: string;
+            score?: number;
+        }>;
+    } | null;
+}
+export interface RoleplayAssignmentLike {
+    scenarioId: string;
+    type: 'mandatory' | 'optional' | string;
+    passingScore: number;
+    dueDate: string | null;
+    createdAt: string;
+    resolvedUserIds: string[];
+}
+export type RepStatus = 'passed' | 'in_progress' | 'not_started' | 'overdue' | 'needs_coaching';
+/** The session's score, or null when it has none (`toFiniteOrNull`). */
+export declare function sessionScore(session: RoleplaySessionLike): number | null;
+/** Mean of the finite values, rounded, or null when none are finite (`meanOfFinite`). */
+export declare function meanOfFinite(values: readonly (number | null | undefined)[]): number | null;
+/** Largest finite value, or null (`maxOfFinite`). */
+export declare function maxOfFinite(values: readonly (number | null | undefined)[]): number | null;
+/** Earliest-to-latest window delta over the scored entries only (`scoreTrend`). */
+export declare function scoreTrend(scores: readonly (number | null | undefined)[], windowFor: (scoredCount: number) => number): number | null;
+export declare const avgScore: (sessions: RoleplaySessionLike[]) => number | null;
+export declare const bestScore: (sessions: RoleplaySessionLike[]) => number | null;
+export declare const scoredCount: (sessions: RoleplaySessionLike[]) => number;
+/** Up to 3 sessions per end, capped at half the scored series (`calcTrend`). */
+export declare function calcTrend(sessions: RoleplaySessionLike[]): number | null;
+/**
+ * `deriveStatus`: the raw best score is compared with `passingScore` as stored (legacy
+ * evaluations may grade on a 5-point scale; the manager app does not normalise either).
+ */
+export declare function deriveStatus(sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date): RepStatus;
+/** `getAssignmentSessions`: same scenario, a rep of the assignment, on or after it was created. */
+export declare function assignmentSessions<T extends RoleplaySessionLike>(sessions: T[], assignment: RoleplayAssignmentLike): T[];
+export interface RepStats {
+    user_id: string;
+    sessions: number;
+    scored_sessions: number;
+    best_score: number | null;
+    avg_score: number | null;
+    trend: number | null;
+    status: RepStatus;
+    last_session_at: string | null;
+    total_duration_ms: number;
+}
+/** `getRepStats` for one rep of one assignment, without the raw sessions. */
+export declare function repStats(userId: string, sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date): RepStats;
+export interface SkillAverage {
+    skill_id: string;
+    title: string;
+    avg_score: number | null;
+    scored_sessions: number;
+}
+/**
+ * Per-skill means over the sessions' `evaluation.category_scores`, keyed by `skillId` (the
+ * Skills Registry id). A legacy category without one falls back to its own `id`, which is stable
+ * within one scenario; an entry with neither, or with no finite score, is skipped.
+ */
+export declare function skillAverages(sessions: RoleplaySessionLike[]): SkillAverage[];

package/dist/src/core/roleplay-stats.js

@@ -0,0 +1,114 @@
+/**
+ * The AI Roleplay manager-app's per-rep rules, ported 1:1 so the MCP team tool and the manager
+ * app give the same answer on the same data (PIT-9200). Sources, in ng-production-apps
+ * `pitcher-coach/manager-app/src/`: `lib/session-score.ts` (reading a score), `lib/stats.ts`
+ * (best, mean, trend), `lib/status.ts` (`deriveStatus`) and `hooks/useManagerData.ts`
+ * (`getAssignmentSessions`, `getRepStats`). Change them together.
+ *
+ * The one rule every aggregate here obeys: a session is unscored iff `overallScore` is not a
+ * finite number. An unscored session is never read as 0.
+ */
+/** The session's score, or null when it has none (`toFiniteOrNull`). */
+export function sessionScore(session) {
+    const v = session.overallScore;
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/** Mean of the finite values, rounded, or null when none are finite (`meanOfFinite`). */
+export function meanOfFinite(values) {
+    const finite = values.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    if (finite.length === 0)
+        return null;
+    return Math.round(finite.reduce((a, b) => a + b, 0) / finite.length);
+}
+/** Largest finite value, or null (`maxOfFinite`). */
+export function maxOfFinite(values) {
+    const finite = values.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    return finite.length === 0 ? null : Math.max(...finite);
+}
+/** Earliest-to-latest window delta over the scored entries only (`scoreTrend`). */
+export function scoreTrend(scores, windowFor) {
+    const finite = scores.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    if (finite.length < 2)
+        return null;
+    const n = Math.min(windowFor(finite.length), finite.length);
+    if (n < 1)
+        return null;
+    const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+    return Math.round(mean(finite.slice(-n)) - mean(finite.slice(0, n)));
+}
+const byTimestamp = (a, b) => new Date(a.timestamp ?? 0).getTime() - new Date(b.timestamp ?? 0).getTime();
+export const avgScore = (sessions) => meanOfFinite(sessions.map(sessionScore));
+export const bestScore = (sessions) => maxOfFinite(sessions.map(sessionScore));
+export const scoredCount = (sessions) => sessions.filter((s) => sessionScore(s) !== null).length;
+/** Up to 3 sessions per end, capped at half the scored series (`calcTrend`). */
+export function calcTrend(sessions) {
+    const sorted = [...sessions].sort(byTimestamp);
+    return scoreTrend(sorted.map(sessionScore), (count) => Math.min(3, Math.floor(count / 2)));
+}
+/**
+ * `deriveStatus`: the raw best score is compared with `passingScore` as stored (legacy
+ * evaluations may grade on a 5-point scale; the manager app does not normalise either).
+ */
+export function deriveStatus(sessions, assignment, now = new Date()) {
+    const isOverdue = assignment.type === 'mandatory' && !!assignment.dueDate && new Date(assignment.dueDate) < now;
+    if (sessions.length === 0)
+        return isOverdue ? 'overdue' : 'not_started';
+    const best = bestScore(sessions);
+    if (best != null && best >= assignment.passingScore)
+        return 'passed';
+    if (isOverdue)
+        return 'overdue';
+    const trend = calcTrend(sessions);
+    if (scoredCount(sessions) >= 3 && trend != null && trend <= 0)
+        return 'needs_coaching';
+    return 'in_progress';
+}
+/** `getAssignmentSessions`: same scenario, a rep of the assignment, on or after it was created. */
+export function assignmentSessions(sessions, assignment) {
+    const createdAt = new Date(assignment.createdAt).getTime();
+    return sessions.filter((s) => s.scenarioId === assignment.scenarioId &&
+        typeof s.userId === 'string' &&
+        assignment.resolvedUserIds.includes(s.userId) &&
+        new Date(s.timestamp ?? 0).getTime() >= createdAt);
+}
+/** `getRepStats` for one rep of one assignment, without the raw sessions. */
+export function repStats(userId, sessions, assignment, now = new Date()) {
+    const own = sessions.filter((s) => s.userId === userId).sort(byTimestamp);
+    return {
+        user_id: userId,
+        sessions: own.length,
+        scored_sessions: scoredCount(own),
+        best_score: bestScore(own),
+        avg_score: avgScore(own),
+        trend: calcTrend(own),
+        status: deriveStatus(own, assignment, now),
+        last_session_at: own.length > 0 ? (own[own.length - 1].timestamp ?? null) : null,
+        total_duration_ms: own.reduce((sum, s) => sum + (s.durationMs ?? 0), 0),
+    };
+}
+/**
+ * Per-skill means over the sessions' `evaluation.category_scores`, keyed by `skillId` (the
+ * Skills Registry id). A legacy category without one falls back to its own `id`, which is stable
+ * within one scenario; an entry with neither, or with no finite score, is skipped.
+ */
+export function skillAverages(sessions) {
+    const bySkill = new Map();
+    for (const s of sessions) {
+        if (sessionScore(s) === null)
+            continue;
+        for (const c of s.evaluation?.category_scores ?? []) {
+            const key = c.skillId || c.id;
+            if (!key || typeof c.score !== 'number' || !Number.isFinite(c.score))
+                continue;
+            const entry = bySkill.get(key) ?? { title: c.title ?? key, scores: [] };
+            entry.scores.push(c.score);
+            bySkill.set(key, entry);
+        }
+    }
+    return Array.from(bySkill.entries()).map(([skill_id, { title, scores }]) => ({
+        skill_id,
+        title,
+        avg_score: meanOfFinite(scores),
+        scored_sessions: scores.length,
+    }));
+}

package/dist/src/mcp/hosted.js

@@ -50,7 +50,7 @@ const HOSTED_DESCRIPTIONS = {
     pitcher_files_update: 'Update a file by ID (name, folder, access, tags, metadata). sourceUrl replaces/overwrites the file binary; metadata is deep-merged.',
     pitcher_announcements_create: 'Create a wa-announcements appsDB record (title/body, optional media, CTA link, scheduling, group targeting). Requires title and body. Additive.',
     pitcher_dsr_create: 'Create a Digital Sales Room (a canvas share link) and get a clickable link back. Source is a canvas (canvasId) OR files (shareboxFileIds) - exactly one. Optional email/domain gating and a bound landing-page template. Returns the share: id, url (the full link), short_url, and a nested canvas object - there is no full_url field. This endpoint is a GET-OR-CREATE: sharing an already-shared canvas returns the existing link and only updates the fields you pass, so use pitcher_dsr_update to change or remove a value on an existing share. A failed landing bind does not fail the call: it returns the link with a warning - and binding a landing page needs instanceId, without which the bind is skipped with that warning. tags are a ShareBox-only field (they name the canvas the server builds from shareboxFileIds), so non-empty tags together with canvasId are REJECTED rather than silently dropped by the server.',
-    pitcher_metadata_template_upsert: "Upsert an instance's metadata-field schema. Merges the incoming sections by section 'label' — a section whose label matches an existing one is replaced, other sections are preserved. Cannot remove a section or field. Requires an instance- or org-admin role.",
+    pitcher_metadata_template_upsert: "Upsert an instance's metadata-field schema. Merges the incoming sections by section 'label' — a section whose label matches an existing one is REPLACED WHOLE (fields left out of it are removed), other sections are preserved. Cannot remove a whole section. To add a field, send the section with all its existing fields plus the new one. Requires an instance- or org-admin role.",
 };
 // Field descriptions that name a stripped key, rewritten for hosted (`tool name → field → text`).
 const HOSTED_FIELD_DESCRIPTIONS = {

package/dist/src/mcp/index.d.ts

@@ -1,4 +1,4 @@
-export { buildServer, type McpRunContext, type BuildServerOptions } from './server.js';
+export { buildServer, PITCHER_ICON, type McpRunContext, type BuildServerOptions } from './server.js';
 export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, } from './hosted.js';
 export { allTools } from './registry.js';
 export { allPrompts } from './prompts/registry.js';

package/dist/src/mcp/index.js

@@ -1,5 +1,5 @@
 // Public entry `@pitcher/cli-scripts/mcp` — what the hosted MCP server (web/packages/mcp-server) consumes.
-export { buildServer } from './server.js';
+export { buildServer, PITCHER_ICON } from './server.js';
 export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, } from './hosted.js';
 export { allTools } from './registry.js';
 export { allPrompts } from './prompts/registry.js';

package/dist/src/mcp/registry.js

@@ -15,6 +15,7 @@ import { metadataTemplateTools } from './tools/metadataTemplate.js';
 import { ldTools } from './tools/ld.js';
 import { orgTools } from './tools/org.js';
 import { publishAppTools } from './tools/publishApp.js';
+import { roleplayTools } from './tools/roleplay.js';
 import { rolesTools } from './tools/roles.js';
 import { searchTools } from './tools/search.js';
 import { sharedLinksTools } from './tools/sharedLinks.js';
@@ -39,6 +40,7 @@ export const allTools = [
     ...rolesTools,
     ...orgTools,
     ...analyticsTools,
+    ...roleplayTools,
     ...membershipsTools,
     ...groupsTools,
     ...metadataTemplateTools,

package/dist/src/mcp/renderPolicy.d.ts

@@ -1 +1 @@
-export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics questions (the pitcher_analytics_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";
+export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";

package/dist/src/mcp/renderPolicy.js

@@ -3,7 +3,7 @@
 // question gets a right-sized reply (a sentence, a table, one chart, or — rarely — a dashboard)
 // instead of a rigid full dashboard on every question. This constant is the single source of truth;
 // the Docs Portal spec (Product/Specs/2026-07-24-analytics-answer-rendering-policy.md) mirrors it.
-export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics questions (the pitcher_analytics_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
+export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
 
 Rendering tiers (evaluate top-down, stop at the first match):
 - A single fact / yes-no / "who/what/how many is the single X" (e.g. "which canvas did I view?", "how many viewers?") -> 1-2 sentences with the number inline. No table, no chart.
@@ -19,5 +19,6 @@ Guardrails (every tier):
 4. If results are capped/truncated, state the cap ("top 15 of 118").
 5. Never show a "vs prior period" delta unless the data actually contains prior-period numbers.
 6. Cite the source verb ("via analytics popularity").
+7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.
 
 Do not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.`;

package/dist/src/mcp/resources/analyticsCatalog.d.ts

@@ -1,3 +1,3 @@
 import type { ResourceDescriptor } from './types.js';
-export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nTen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.)\n- **Date-range, server default window:** viewers, sessions \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
+export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nFourteen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions, viewer_visits\n- **instance editor, instance admin or org admin:** file_users, file_pages, canvas_users\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.) Also file_users, file_pages, canvas_users.\n- **Date-range, server default window:** viewers, sessions, viewer_visits \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n| `file_users` | Who opened ONE file: opens, seconds, days active per user | date-range | editor | \"Who opened the pricing PDF, and for how long?\" |\n| `file_pages` | Time per page of ONE file (one user with a single `userEmails`) | date-range | editor | \"Which pages of this file do reps spend time on?\" |\n| `canvas_users` | Per user and canvas: visits, seconds; with `canvasId`, seconds per page (section) | date-range | editor | \"Which reps presented this deck, and which slides?\" |\n| `viewer_visits` | Per DSR viewer and visit: sections, files and pages with seconds; `format: csv` to export | date-range | member | \"Export who looked at which pages of this DSR\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n`viewer_visits` does both steps for up to 25 viewers at once and returns per-visit, per-page time; use it for\n\"which pages did each viewer look at\", and `format: \"csv\"` when the user wants a file.\n\n## Per-user usage\n\"Which files did this user open\" is `files` with `userEmails`; \"who opened this file\" is `file_users`; time per page\nof a file is `file_pages`; reps' canvas usage is `canvas_users` (internal users only \u2014 external DSR viewers are\n`viewers` / `viewer_visits`).\n\n## AI Roleplay\nRoleplay results are separate tools (`pitcher_roleplay_*`): kpis, sessions and rep_summary for instance or org admins,\nteam (assignment completion; admins see every assignment, coaching managers their own), session_get and\nscenarios_list. A session with no score is unscored, never 0.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
 export declare const analyticsCatalogResource: ResourceDescriptor;

package/dist/src/mcp/resources/analyticsCatalog.js

@@ -1,25 +1,26 @@
 // A model-facing catalog of the analytics verbs exposed as pitcher_analytics_* tools. It exists so a
 // host can read ONE resource to learn which verb answers which question, the time model each uses, and
-// the key tier each needs — instead of guessing from 10 tool descriptions. Distilled from the analytics
+// the key tier each needs — instead of guessing from 14 tool descriptions. Distilled from the analytics
 // runner contracts in src/commands/analytics.ts (the authoritative source); keep in sync on route/gate
 // changes. Definitions mirror the platform analytics vocabulary.
 export const ANALYTICS_CATALOG = `# Pitcher analytics catalog
 
-Ten read-only verbs, each an MCP tool named \`pitcher_analytics_<verb>\`. Pick the verb that matches the
+Fourteen read-only verbs, each an MCP tool named \`pitcher_analytics_<verb>\`. Pick the verb that matches the
 question, then call its tool. All are read-only; org scope + auth come from the server's API key (never a
 tool input) — you only pass \`instanceId\` (and, where noted, \`canvasId\`/\`userEmail\`).
 
 ## Key tiers
 - **org-admin key required:** org, popularity, users, files, canvases
 - **instance-admin or org-admin:** instance
-- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions
+- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions, viewer_visits
+- **instance editor, instance admin or org admin:** file_users, file_pages, canvas_users
 
 ## Time model
 - **Rollup (no window):** org, instance — lifetime/current totals.
 - **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, \`users\` with
   \`stats: true\`, files, canvases — omit dates to get the last 30 days. (\`users\` without \`stats\` is a
-  full roster with no window.)
-- **Date-range, server default window:** viewers, sessions — omit dates and the service picks the window.
+  full roster with no window.) Also file_users, file_pages, canvas_users.
+- **Date-range, server default window:** viewers, sessions, viewer_visits — omit dates and the service picks the window.
 
 ## Verbs
 
@@ -35,6 +36,10 @@ tool input) — you only pass \`instanceId\` (and, where noted, \`canvasId\`/\`u
 | \`canvases\` | Per-section canvas engagement list | date-range | org-admin | "How are my canvas sections performing?" |
 | \`viewers\` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | "Who viewed this DSR, and how much?" |
 | \`sessions\` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | "What did this viewer do inside the DSR?" |
+| \`file_users\` | Who opened ONE file: opens, seconds, days active per user | date-range | editor | "Who opened the pricing PDF, and for how long?" |
+| \`file_pages\` | Time per page of ONE file (one user with a single \`userEmails\`) | date-range | editor | "Which pages of this file do reps spend time on?" |
+| \`canvas_users\` | Per user and canvas: visits, seconds; with \`canvasId\`, seconds per page (section) | date-range | editor | "Which reps presented this deck, and which slides?" |
+| \`viewer_visits\` | Per DSR viewer and visit: sections, files and pages with seconds; \`format: csv\` to export | date-range | member | "Export who looked at which pages of this DSR" |
 
 ## Shaping
 Row-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:
@@ -50,6 +55,19 @@ A session is one \`Entered\` of the queried id itself (a canvas or a section), p
 \`session_count\` is counted the same way as the overview's \`total_sessions\`. \`canvases\` lists sections, and their
 ids are valid \`canvasId\` inputs for \`viewers\` and \`sessions\`.
 
+\`viewer_visits\` does both steps for up to 25 viewers at once and returns per-visit, per-page time; use it for
+"which pages did each viewer look at", and \`format: "csv"\` when the user wants a file.
+
+## Per-user usage
+"Which files did this user open" is \`files\` with \`userEmails\`; "who opened this file" is \`file_users\`; time per page
+of a file is \`file_pages\`; reps' canvas usage is \`canvas_users\` (internal users only — external DSR viewers are
+\`viewers\` / \`viewer_visits\`).
+
+## AI Roleplay
+Roleplay results are separate tools (\`pitcher_roleplay_*\`): kpis, sessions and rep_summary for instance or org admins,
+team (assignment completion; admins see every assignment, coaching managers their own), session_get and
+scenarios_list. A session with no score is unscored, never 0.
+
 ## Notes
 - \`popularity\` maps to the canvases view-analysis endpoint (there is no separate popularity route).
 - Results can include user identities/emails — treat as customer data and handle per policy.

package/dist/src/mcp/server.d.ts

@@ -3,6 +3,7 @@ import type { Credential } from '../core/credential.js';
 import type { ToolDescriptor } from './tools/types.js';
 import type { PromptDescriptor } from './prompts/types.js';
 import type { ResourceDescriptor } from './resources/types.js';
+export declare const PITCHER_ICON = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiB3aWR0aD0iNTEyIiBoZWlnaHQ9IjUxMiI+PHJlY3Qgd2lkdGg9IjUxMiIgaGVpZ2h0PSI1MTIiIHJ4PSIxMTYiIGZpbGw9IiMyOTMzNUMiLz48Y2lyY2xlIGN4PSIzNzIiIGN5PSIxNTAiIHI9IjMwIiBmaWxsPSIjQ0MwMDAwIi8+PHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTE1MCAxMTZoOTZhOTIgOTIgMCAwIDEgMCAxODRoLTUwdjk2aC00NnoiLz48cGF0aCBmaWxsPSIjMjkzMzVDIiBkPSJNMTk2IDE2MHY5Nmg1MGE0OCA0OCAwIDAgMCAwLTk2eiIvPjwvc3ZnPg==";
 /**
  * The per-server request context: who every tool call runs as, and against which origin.
  * Captured at build time — local stdio `p mcp` builds one from the `p login` session; the hosted server

package/dist/src/mcp/server.js

@@ -18,10 +18,10 @@ const version = (() => {
         return '0.0.0';
     }
 })();
-// Connector branding shown by MCP hosts (Claude Desktop, Cursor). Self-contained
-// data URI so it needs no network/asset resolution: a navy (#29335C) tile with a
+// Connector branding shown by MCP hosts (Claude Desktop, Cursor) and on the hosted server's own pages.
+// Self-contained data URI so it needs no network/asset resolution: a navy (#29335C) tile with a
 // white "P" and the Pitcher-red (#CC0000) accent from the wordmark.
-const icon = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiB3aWR0aD0iNTEyIiBoZWlnaHQ9IjUxMiI+PHJlY3Qgd2lkdGg9IjUxMiIgaGVpZ2h0PSI1MTIiIHJ4PSIxMTYiIGZpbGw9IiMyOTMzNUMiLz48Y2lyY2xlIGN4PSIzNzIiIGN5PSIxNTAiIHI9IjMwIiBmaWxsPSIjQ0MwMDAwIi8+PHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTE1MCAxMTZoOTZhOTIgOTIgMCAwIDEgMCAxODRoLTUwdjk2aC00NnoiLz48cGF0aCBmaWxsPSIjMjkzMzVDIiBkPSJNMTk2IDE2MHY5Nmg1MGE0OCA0OCAwIDAgMCAwLTk2eiIvPjwvc3ZnPg==';
+export const PITCHER_ICON = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiB3aWR0aD0iNTEyIiBoZWlnaHQ9IjUxMiI+PHJlY3Qgd2lkdGg9IjUxMiIgaGVpZ2h0PSI1MTIiIHJ4PSIxMTYiIGZpbGw9IiMyOTMzNUMiLz48Y2lyY2xlIGN4PSIzNzIiIGN5PSIxNTAiIHI9IjMwIiBmaWxsPSIjQ0MwMDAwIi8+PHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTE1MCAxMTZoOTZhOTIgOTIgMCAwIDEgMCAxODRoLTUwdjk2aC00NnoiLz48cGF0aCBmaWxsPSIjMjkzMzVDIiBkPSJNMTk2IDE2MHY5Nmg1MGE0OCA0OCAwIDAgMCAwLTk2eiIvPjwvc3ZnPg==';
 // Compact, sanitized error string (no raw stack) — shared by the prompt/resource callbacks.
 function errorText(e) {
     if (isCliError(e))
@@ -35,7 +35,7 @@ export function buildServer(ctx, tools = allTools, prompts = allPrompts, resourc
         title: 'Pitcher',
         description: 'Search, manage, and share Pitcher content, canvases, files, DSRs, and instances.',
         websiteUrl: 'https://www.pitcher.com',
-        icons: [{ src: icon, mimeType: 'image/svg+xml', sizes: ['any'] }],
+        icons: [{ src: PITCHER_ICON, mimeType: 'image/svg+xml', sizes: ['any'] }],
     }, 
     // Surfaced to the host model via InitializeResult.instructions — the analytics answer-rendering
     // policy so a natural-language question gets a right-sized reply (sentence / table / chart /