@pitcher/cli-scripts 2.14.0 → 2.16.0

package/README.md

@@ -12,7 +12,7 @@ p command --help
 
 ## MCP server
 
-Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 114 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 121 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
 
 ```bash
 p mcp
@@ -55,7 +55,7 @@ yarn mcpb:pack        # → pitcher.mcpb (validated + packed)
 
 Install by double-clicking `pitcher.mcpb` (or Settings → Extensions → Install Extension). Claude Desktop prompts for the API key (stored in the OS keychain) and organization; both are editable afterward, so switching orgs needs no reinstall.
 
-The bundle reuses the same server as `p mcp` but registers a **content-tool subset (111)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
+The bundle reuses the same server as `p mcp` but registers a **content-tool subset (118)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
 
 This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
 
@@ -394,6 +394,8 @@ p analytics viewers --instance-id 01... --canvas-id 01CANVASID... --viewer-type
 p analytics sessions --instance-id 01... --canvas-id 01CANVASID... --user rep@example.com --api-key myapikey
 ```
 
+MCP: all ten verbs are exposed as read-only `pitcher_analytics_*` tools, alongside a `pitcher://analytics/catalog` resource (which verb answers which question — returns, time model, key tier) and four query prompts — `top_content`, `content_engagement_summary`, `who_viewed_canvas`, `adoption_snapshot`.
+
 ## To run the `users` command:
 
 Read users in the org (read-only). Org scope comes from the API key via the proxy `x-org-id` header — there is no `--org-id` flag.

package/dist/src/commands/files.d.ts

@@ -11,6 +11,7 @@ export declare function runFilesList(opts: CommonOpts & {
     instanceId?: string;
     tags?: string;
     idIn?: string;
+    type?: string;
     page?: number;
     pageSize?: number;
 }, deps?: FilesDeps): Promise<Envelope<{

package/dist/src/commands/files.js

@@ -5,7 +5,7 @@ import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { uploadFile } from '../core/upload.js';
 import { listPageParams, listPaginationEcho } from '../core/pagination.js';
-import { parseTags, parseJsonObject, validateAccessType, deepMerge, assertIntFlags } from '../schema/content.js';
+import { parseTags, parseJsonObject, validateAccessType, validateFileType, deepMerge, assertIntFlags } from '../schema/content.js';
 import { withAuthFlags } from './withAuth.js';
 export async function runFilesList(
 // NOTE: no folderId — the Django files list has no folder filter (listing a
@@ -15,12 +15,25 @@ opts, deps = {}) {
         if (!opts.instanceId)
             throw createCliError('VALIDATION', '--instance-id is required for files list');
         assertIntFlags(opts);
+        const type = validateFileType(opts.type);
         const client = clientFor(opts, deps);
         const params = { instance_id: opts.instanceId, ...listPageParams(opts) };
         if (opts.idIn)
             params.id__in = opts.idIn;
         if (opts.tags)
             params.tags__in = opts.tags;
+        // Installable apps are file records too (type=app). Exclude them by default so a "list files"
+        // request returns real content, not the instance's installed apps. `--type <content|asset|app>`
+        // isolates one type and always wins; `--type all` restores the unfiltered listing. An explicit
+        // --id-in lookup bypasses the default exclusion — fetching a file by id is a targeted lookup, not
+        // a browse, so it must return that record whatever its type (an explicit --type still applies).
+        // Uses type__in to match the tags__in/id__in CSV convention above (a single value is a valid filter).
+        if (type && type !== 'all') {
+            params.type__in = type;
+        }
+        else if (!type && !opts.idIn) {
+            params.type__in = 'content,asset';
+        }
         const res = await client.get('/api/v1/files/', { params });
         return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
     }
@@ -122,6 +135,7 @@ export function createFilesCommand() {
         .option('--instance-id <id>', 'Instance ID (required)')
         .option('--id-in <ids>', 'Comma-separated file IDs')
         .option('--tags <tags>', 'Comma-separated tags (filters via tags__in)')
+        .option('--type <type>', 'File type: content, asset, app, or all (default excludes installable apps)')
         .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
         .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
         .action(async (options, command) => {

package/dist/src/mcp/bundled.js

@@ -1,7 +1,7 @@
 import { allTools } from './registry.js';
 // Developer-only tools excluded from the consumer .mcpb bundle. `publish_app` is alwaysDestructive
 // (creates a live, org-visible app release); `dev_sync`/`dev_sync_revert` mutate remote S3 dev state.
-// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 114.
+// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 121.
 export const BUNDLE_EXCLUDED_TOOLS = new Set(['pitcher_publish_app', 'pitcher_dev_sync', 'pitcher_dev_sync_revert']);
 // The tool set the .mcpb bundle registers.
 export const bundledTools = allTools.filter((t) => !BUNDLE_EXCLUDED_TOOLS.has(t.name));

package/dist/src/mcp/prompts/analytics.d.ts

@@ -0,0 +1,2 @@
+import type { PromptDescriptor } from './types.js';
+export declare const analyticsPrompts: PromptDescriptor[];

package/dist/src/mcp/prompts/analytics.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { instanceLine, readSafetyNote } from './shared.js';
+// Read-only analytics query recipes. Unlike the authoring prompts, these create nothing — each just
+// routes a common question to the right pitcher_analytics_* verb(s) and asks for a concise summary.
+// They carry readSafetyNote() (confirm instance + treat identities as customer data), NOT the
+// content-creation safetyPreamble (no markup is authored, so the {{token}} anti-XSS guidance is N/A).
+export const analyticsPrompts = [
+    {
+        name: 'top_content',
+        title: 'Top-performing content',
+        description: 'Rank an instance’s most-viewed canvases (and optionally files) over a window.',
+        argsSchema: {
+            instance_id: z.string().optional().describe('Target instance ID (leave blank to resolve interactively)'),
+            period: z.string().optional().describe('Time window in words, e.g. "last 30 days", "this quarter"'),
+            limit: z.string().optional().describe('How many top items to return (default 10)'),
+        },
+        build: (args) => {
+            const period = args.period || 'the last 30 days';
+            const limit = args.limit || '10';
+            const text = [
+                readSafetyNote(),
+                '',
+                '## Task: top-performing content',
+                instanceLine(args.instance_id),
+                `Window: ${period}.`,
+                '',
+                'Steps:',
+                `1. Translate the window into ISO \`startDate\`/\`endDate\` (omit both ONLY when the window is the default last 30 days). Then call \`pitcher_analytics_popularity\` for the instance with those dates and \`limit\`=${limit} to get the most-viewed canvases, ranked.`,
+                '2. (Optional) Call `pitcher_analytics_files` with the same dates to add the most-used files.',
+                '3. Summarize the top items with their view/engagement numbers, and state the exact window used. Requires an org-admin key.',
+            ].join('\n');
+            return [{ role: 'user', content: { type: 'text', text } }];
+        },
+    },
+    {
+        name: 'content_engagement_summary',
+        title: 'Content engagement summary',
+        description: 'Summarize per-content/DSR engagement for an instance over a window.',
+        argsSchema: {
+            instance_id: z.string().optional().describe('Target instance ID (leave blank to resolve interactively)'),
+            period: z.string().optional().describe('Time window in words, e.g. "last 30 days"'),
+        },
+        build: (args) => {
+            const period = args.period || 'the last 30 days';
+            const text = [
+                readSafetyNote(),
+                '',
+                '## Task: content engagement summary',
+                instanceLine(args.instance_id),
+                `Window: ${period}.`,
+                '',
+                'Steps:',
+                '1. Translate the window into ISO `startDate`/`endDate` (omit both ONLY when the window is the default last 30 days), then call `pitcher_analytics_engagement` for the instance with those dates (raise `limit` if you need more than the top 20 rows).',
+                '2. Read the `summary` for headline metrics and the `rows` for per-item engagement; note `has_more`/`total_count` if the list is capped.',
+                '3. Report which content is engaged with most and the overall trend for the window. Works with a member key.',
+            ].join('\n');
+            return [{ role: 'user', content: { type: 'text', text } }];
+        },
+    },
+    {
+        name: 'who_viewed_canvas',
+        title: 'Who viewed a DSR canvas',
+        description: 'List the viewers of a specific DSR canvas, then drill into one viewer’s session timeline.',
+        argsSchema: {
+            instance_id: z.string().optional().describe('Target instance ID (leave blank to resolve interactively)'),
+            canvas_id: z.string().optional().describe('Canvas to inspect (leave blank to pick one interactively)'),
+        },
+        build: (args) => {
+            const text = [
+                readSafetyNote(),
+                '',
+                '## Task: who viewed a DSR canvas',
+                instanceLine(args.instance_id),
+                args.canvas_id
+                    ? `Canvas to inspect: ${args.canvas_id}.`
+                    : 'No canvas given — help the user pick one via `pitcher_canvases_list` (or `pitcher_search`).',
+                '',
+                'Steps:',
+                '1. Call `pitcher_analytics_viewers` with the `canvasId` to list viewers and their per-viewer engagement.',
+                '2. To drill into a specific viewer, call `pitcher_analytics_sessions` with the same `canvasId` plus that viewer’s ' +
+                    '`userEmail` (both come from step 1) to get their raw session event timeline.',
+                '3. Summarize who viewed, how much they engaged, and — if you drilled in — what that viewer did. Works with a member key.',
+            ].join('\n');
+            return [{ role: 'user', content: { type: 'text', text } }];
+        },
+    },
+    {
+        name: 'adoption_snapshot',
+        title: 'Adoption snapshot',
+        description: 'Combine active-user stats and KPIs into a short adoption snapshot for an instance.',
+        argsSchema: {
+            instance_id: z.string().optional().describe('Target instance ID (leave blank to resolve interactively)'),
+            period: z.string().optional().describe('Time window in words, e.g. "last 30 days"'),
+        },
+        build: (args) => {
+            const period = args.period || 'the last 30 days';
+            const text = [
+                readSafetyNote(),
+                '',
+                '## Task: adoption snapshot',
+                instanceLine(args.instance_id),
+                `Window: ${period}.`,
+                '',
+                'Steps:',
+                '1. Translate the window into ISO `startDate`/`endDate` (omit both ONLY when the window is the default last 30 days), then call `pitcher_analytics_users` with `stats`=true and those dates for active-user statistics.',
+                '2. Call `pitcher_analytics_kpi` with the same dates for headline counts (e.g. `type`=total-active-users, then total-members for the denominator).',
+                '3. Combine into a short adoption snapshot — active users, totals, and the active/total ratio for the window. Requires an org-admin key.',
+            ].join('\n');
+            return [{ role: 'user', content: { type: 'text', text } }];
+        },
+    },
+];

package/dist/src/mcp/prompts/registry.js

@@ -3,6 +3,7 @@ import { dsrLandingPrompts } from './dsrLanding.js';
 import { dsrPrompts } from './dsr.js';
 import { announcementsPrompts } from './announcements.js';
 import { ldCanvasCoursePrompts } from './ldCanvasCourse.js';
+import { analyticsPrompts } from './analytics.js';
 // Every recipe prompt the server can expose. Mirrors mcp/registry.ts (allTools).
 export const allPrompts = [
     ...emailTemplatePrompts,
@@ -10,4 +11,5 @@ export const allPrompts = [
     ...dsrPrompts,
     ...announcementsPrompts,
     ...ldCanvasCoursePrompts,
+    ...analyticsPrompts,
 ];

package/dist/src/mcp/prompts/shared.d.ts

@@ -1,3 +1,4 @@
 export declare function instanceLine(instanceId: string | undefined): string;
 export declare function safetyPreamble(): string;
+export declare function readSafetyNote(): string;
 export declare function recipePreamble(): string;

package/dist/src/mcp/prompts/shared.js

@@ -24,6 +24,17 @@ export function safetyPreamble() {
             'the generated markup.',
     ].join('\n');
 }
+// Lighter note for READ-ONLY recipes (analytics queries): they create nothing, so they don't carry
+// the content-creation prod-warning or the {{token}}/anti-XSS guidance (there is no markup to author).
+// Instead: confirm the instance is the intended one, and treat returned identities as customer data.
+export function readSafetyNote() {
+    return [
+        '## Before you query',
+        'These are **read-only** analytics tools — they create nothing and mutate nothing. Confirm you are ' +
+            'pointed at the intended instance before reporting numbers, and treat any returned user ' +
+            'identities/emails as customer data (handle per policy).',
+    ].join('\n');
+}
 // Full preamble for HTML-authoring recipes: the design principles + the safety guidance.
 // Authored once so the principles, prod-awareness, and anti-XSS guidance can't drift.
 export function recipePreamble() {

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

@@ -0,0 +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.";

package/dist/src/mcp/renderPolicy.js

@@ -0,0 +1,23 @@
+// Connector-level MCP instructions surfaced to the host model (Claude Desktop, Cursor) via
+// InitializeResult.instructions. Governs how analytics answers are RENDERED so a natural-language
+// 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.
+
+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.
+- 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.
+- "over time" / "trend" / "by week/month" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).
+- 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.
+- 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 — use it rarely, only for genuinely broad asks.
+
+Guardrails (every tier):
+1. Words first — even with a chart, lead with a one-sentence answer to the literal question.
+2. 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.
+3. If data is empty or trivially small, say so in prose — do not render an empty chart.
+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").
+
+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

@@ -0,0 +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.\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

@@ -0,0 +1,60 @@
+// 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
+// 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
+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
+
+## 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.
+
+## Verbs
+
+| Verb (tool) | Returns | Time | Key | Example question |
+|---|---|---|---|---|
+| \`org\` | Organization-wide rollup totals (Django) | rollup | org-admin | "How is the whole org doing overall?" |
+| \`instance\` | Single-instance rollup totals (Django) | rollup | instance-admin | "Totals for this one workspace?" |
+| \`kpi\` | KPI metrics for an instance (members, active users, …) | date-range | member | "How many active users last month?" |
+| \`engagement\` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | "Which content is being engaged with?" |
+| \`popularity\` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | "Top 10 most-viewed decks this quarter?" |
+| \`users\` | User roster, or active-user stats with \`stats: true\` | roster: none / stats: date-range | org-admin | "Who are my active users this month?" |
+| \`files\` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | "Which files get opened the most?" |
+| \`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?" |
+
+## Shaping
+Row-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:
+\`summary\` + \`rows\` (default 20, max 100 — raise with \`limit\`) + \`total_count\`/\`returned\`/\`has_more\`,
+and a \`truncated\` note when more rows exist. \`kpi\` and \`sessions\` return the raw payload (a KPI scalar set
+and an uncapped event timeline, respectively) — never truncated.
+
+## DSR drill-down
+For "who viewed X and what did they do": call \`viewers\` (with \`canvasId\`) to list viewers, then \`sessions\`
+(with the same \`canvasId\` + the viewer's \`userEmail\`) to see that viewer's event timeline.
+
+## 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.
+`;
+export const analyticsCatalogResource = {
+    name: 'analytics-catalog',
+    uri: 'pitcher://analytics/catalog',
+    title: 'Analytics verb catalog',
+    description: 'Which analytics verb answers which question — returns, time model, key tier, examples.',
+    mimeType: 'text/markdown',
+    read: () => ANALYTICS_CATALOG,
+};

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

@@ -1,4 +1,9 @@
 import { contentDesignResource } from './contentDesign.js';
 import { ldCanvasDesignResource } from './ldCanvasDesign.js';
+import { analyticsCatalogResource } from './analyticsCatalog.js';
 // Every resource the server can expose. Mirrors mcp/registry.ts (allTools).
-export const allResources = [contentDesignResource, ldCanvasDesignResource];
+export const allResources = [
+    contentDesignResource,
+    ldCanvasDesignResource,
+    analyticsCatalogResource,
+];

package/dist/src/mcp/server.js

@@ -6,6 +6,7 @@ import { allTools } from './registry.js';
 import { allPrompts } from './prompts/registry.js';
 import { allResources } from './resources/registry.js';
 import { envelopeToToolResult, toErrorResult } from './result.js';
+import { ANALYTICS_RENDER_POLICY } from './renderPolicy.js';
 import { isCliError } from '../core/errors.js';
 const version = (() => {
     // The .mcpb bundle inlines this at build time (esbuild define) because the bundled single
@@ -40,7 +41,11 @@ export function buildServer(env, tools = allTools, prompts = allPrompts, resourc
         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'] }],
-    });
+    }, 
+    // 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 /
+    // dashboard) instead of a rigid full dashboard every time. See renderPolicy.ts.
+    { instructions: ANALYTICS_RENDER_POLICY });
     for (const tool of tools) {
         const destructive = tool.alwaysDestructive === true || (tool.write === true && env.prod);
         server.registerTool(tool.name, {

package/dist/src/mcp/tools/analytics.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi } from '../../commands/analytics.js';
+import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi, runAnalyticsEngagement, runAnalyticsPopularity, runAnalyticsUsers, runAnalyticsFiles, runAnalyticsCanvases, runAnalyticsViewers, runAnalyticsSessions, } from '../../commands/analytics.js';
 export const analyticsTools = [
     {
         name: 'pitcher_analytics_org',
@@ -34,4 +34,141 @@ export const analyticsTools = [
         run: runAnalyticsKpi,
         readOnly: true,
     },
+    {
+        name: 'pitcher_analytics_engagement',
+        title: 'DSR/content engagement',
+        description: 'Per-DSR/content engagement rows for an instance from the clickhouse analytics service. Returns a ' +
+            'summary plus a list capped to `limit` (with total_count/has_more). Works with a member key. ' +
+            'Defaults to a 30-day window when dates are omitted.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            engagementLevel: z.string().optional().describe("Engagement level filter (default 'all')"),
+            view: z.string().optional().describe("View context (default 'dsr')"),
+            search: z.string().optional().describe('Search term'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            sortBy: z.string().optional().describe('Sort field'),
+            sortOrder: z.string().optional().describe('Sort direction (asc/desc)'),
+            hideMemberFiles: z.boolean().optional().describe('Exclude rep-uploaded files'),
+            page: z.number().int().optional().describe('Page number'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsEngagement,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_popularity',
+        title: 'Most-viewed canvases',
+        description: 'Most-viewed canvases (view-analysis) for an instance, ranked and capped to `limit`. Requires an ' +
+            'org-admin key. Defaults to a 30-day window when dates are omitted.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            sortBy: z.string().optional().describe("Sort field (default 'total_views')"),
+            sortOrder: z.string().optional().describe("Sort direction (default 'DESC')"),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            page: z.number().int().optional().describe('Page number'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsPopularity,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_users',
+        title: 'User roster / active-user stats',
+        description: 'User roster (default) or active-user statistics (`stats: true`) for an instance. Requires an ' +
+            'org-admin key. The stats branch defaults to a 30-day window when dates are omitted.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            stats: z.boolean().optional().describe('Return active-user statistics instead of the roster'),
+            startDate: z.string().optional().describe('Window start, ISO date (stats only, defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (stats only, defaults to today)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs (stats only)'),
+            page: z.number().int().optional().describe('Page number (stats only)'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsUsers,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_files',
+        title: 'File usage analytics',
+        description: 'File usage analytics for an instance (views/opens/engagement per file), summarized and capped to ' +
+            '`limit`. Requires an org-admin key. Defaults to a 30-day window when dates are omitted.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            fileType: z.string().optional().describe('Filter by file type'),
+            filter: z.string().optional().describe('Search term'),
+            sortBy: z.string().optional().describe('Sort field'),
+            sortOrder: z.string().optional().describe('Sort direction (asc/desc; normalized to ASC/DESC)'),
+            metadataFilters: z.string().optional().describe('Metadata filters (JSON string)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by'),
+            hideMemberFiles: z.boolean().optional().describe('Exclude rep-uploaded files'),
+            page: z.number().int().optional().describe('Page number'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsFiles,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_canvases',
+        title: 'Per-section canvas engagement',
+        description: 'Per-section canvas engagement list for an instance, summarized and capped to `limit`. Requires an ' +
+            'org-admin key. Defaults to a 30-day window when dates are omitted.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            page: z.number().int().optional().describe('Page number'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsCanvases,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_viewers',
+        title: 'DSR canvas viewers',
+        description: 'Who viewed a specific DSR canvas — a viewer list with per-viewer engagement, capped to `limit`. ' +
+            'Works with a member key. Requires canvasId. The server applies its own default window when dates ' +
+            'are omitted. Drill into one viewer with pitcher_analytics_sessions.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            canvasId: z.string().describe('Canvas ID (required)'),
+            viewerType: z.string().optional().describe("Viewer type filter: all, internal, external (default 'all')"),
+            sortBy: z
+                .string()
+                .optional()
+                .describe('Sort field: email, session_count, total_engagement_time, last_active, sections_viewed, files_viewed'),
+            sortOrder: z.string().optional().describe("Sort direction (asc/desc, default 'desc')"),
+            search: z.string().optional().describe('Search term'),
+            startDate: z.string().optional().describe('Window start, ISO date (server default applies if omitted)'),
+            endDate: z.string().optional().describe('Window end, ISO date (server default applies if omitted)'),
+            page: z.number().int().optional().describe('Page number'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsViewers,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_sessions',
+        title: 'DSR per-viewer session timeline',
+        description: 'Per-viewer session event timeline for a DSR canvas (drill-down for one viewer). Returns the raw, ' +
+            'uncapped event list (not summarized). Works with a member key. Requires canvasId and userEmail — ' +
+            'get both from pitcher_analytics_viewers.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            canvasId: z.string().describe('Canvas ID (required)'),
+            userEmail: z.string().describe('Viewer user email (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (server default applies if omitted)'),
+            endDate: z.string().optional().describe('Window end, ISO date (server default applies if omitted)'),
+        },
+        run: runAnalyticsSessions,
+        readOnly: true,
+    },
 ];

package/dist/src/mcp/tools/files.js

@@ -1,14 +1,21 @@
 import { z } from 'zod';
 import { runFilesList, runFilesGet, runFilesCreate, runFilesUpdate } from '../../commands/files.js';
+import { FILE_TYPES } from '../../schema/content.js';
 export const filesTools = [
     {
         name: 'pitcher_files_list',
         title: 'List files',
-        description: 'List content files in an instance. Filter by tags or specific IDs.',
+        description: 'List content files in an instance. Installed apps are stored as file records too, but are ' +
+            'EXCLUDED by default (content + assets only) so a "list files" request returns real content. ' +
+            'Pass type="app" for installed apps only, or type="all" to include everything. Filter by tags or specific IDs.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             idIn: z.string().optional().describe('Comma-separated file IDs'),
             tags: z.string().optional().describe('Comma-separated tags'),
+            type: z
+                .enum(FILE_TYPES)
+                .optional()
+                .describe('File type filter. Omit to list content + assets (installed apps excluded); "app" = apps only; "all" = everything including apps.'),
             page: z.number().int().optional(),
             pageSize: z.number().int().optional(),
         },

package/dist/src/schema/content.d.ts

@@ -1,8 +1,10 @@
+export declare const FILE_TYPES: readonly ["content", "asset", "app", "all"];
 export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
 export declare function parseJsonObject(raw: string, flagName: string): Record<string, unknown>;
 export declare function parseJsonArray(raw: string, flagName: string): unknown[];
 export declare function parseTags(raw: string): string[];
 export declare function validateAccessType(v: string | undefined): string | undefined;
+export declare function validateFileType(v: string | undefined): string | undefined;
 export declare function assertIntFlags(opts: {
     page?: number;
     pageSize?: number;

package/dist/src/schema/content.js

@@ -1,5 +1,10 @@
 import { createCliError } from '../core/errors.js';
 const ACCESS_TYPES = ['public', 'restricted', 'personal'];
+// File record types on Django's `pitcher_file.type` column, plus the `all` escape hatch.
+// Installable apps are stored as file records (type=app), so `p files list` excludes them by default;
+// `all` opts back into the unfiltered listing. See validateFileType / runFilesList.
+// Exported so the MCP `pitcher_files_list` tool sources its zod enum from the same list (no drift).
+export const FILE_TYPES = ['content', 'asset', 'app', 'all'];
 export function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -37,6 +42,14 @@ export function validateAccessType(v) {
     }
     return v;
 }
+export function validateFileType(v) {
+    if (v === undefined)
+        return undefined;
+    if (!FILE_TYPES.includes(v)) {
+        throw createCliError('VALIDATION', `--type must be one of: ${FILE_TYPES.join(', ')}`);
+    }
+    return v;
+}
 // Guards against NaN reaching the request (commander's parseInt yields NaN on
 // non-numeric input, e.g. `--page abc`).
 export function assertIntFlags(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",