pmx-canvas 0.6.2 → 0.6.3

package/skills/pmx-canvas/SKILL.md

@@ -18,12 +18,24 @@ Humans curate agent context by pinning nodes; agents read that curation through
 
 ## Runtime prerequisites
 
-PMX Canvas 0.6.1 requires **Bun >=1.4.2**, including when installed through npm.
+PMX Canvas 0.6.3 requires **Bun >=1.4.2**, including when installed through npm.
 Check `bun --version` and ensure Bun is on the MCP host's PATH, not just your shell's;
 use an absolute executable path if needed. Install/configure only when requested.
 For pinned installation, MCP configuration, managed services, and disposable verification,
 read [Installing PMX Canvas](references/installing-pmx-canvas.md).
 
+## Reading bundled skills over MCP
+
+When the server advertises `io.modelcontextprotocol/skills`, supporting hosts can discover
+bundled skills with `skills/list` and retrieve a manifest with `skills/get`. These are MCP
+protocol methods, not canvas tools. Read `skill://pmx-canvas/SKILL.md` and relative supporting
+files (for example `skill://pmx-canvas/references/installing-pmx-canvas.md`) through
+`resources/read`, fetching only what is needed. Hosts without extension support can still read
+ordinary resources or use installed filesystem skills; `canvas://skills` remains available.
+Resource reads do not activate skills or authorize executing their scripts. The host must
+preserve MCP origin and apply integrity/approval checks. Restart MCP after upgrading the package;
+the served catalog is a startup snapshot. Local mirrors still use `skills sync` below.
+
 ## Required Operating Sequence
 
 0. **After a `pmx-canvas` upgrade, refresh this skill first.** Run
@@ -237,8 +249,18 @@ graph 760×520, mcp-app 960×600, web-artifact 960×720. A *hosted* app opened w
 `canvas_app { action: "open-mcp-app" | "diagram" }` — including the Excalidraw diagram preset — is
 the exception: request `width: 720, height: 500` for its standard landscape preset instead of
 relying on the 960×600 default for a directly created `mcp-app` node. After the app mounts, read
-the node back with `canvas_query { action: "layout" }` and use its persisted width and height for
-subsequent placement or layout; the mounted app may have changed the requested dimensions.
+only its geometry, e.g. `pmx-canvas node get <id> --fields id,type,position,size`, and use the
+persisted size for subsequent placement. With MCP tool execution that supports output projection,
+project the layout to node id/type/position/size before returning it to context; otherwise prefer
+a targeted `canvas_node { action: "get", id }`. Read the full layout only when its other state
+is needed. Mounted apps may change the requested dimensions.
+Authored iframe surfaces grow in height as content changes, up to 1400px. A growing ungrouped,
+unpinned card moves down when needed to leave a 24px gap without moving its neighbors; grouped
+cards retain their authored placement. Width stays explicit, and `strictSize` or manually resized
+cards do not auto-grow. Fitting waits while a human holds the card, including in another tab;
+automatic relocations are undoable. This is not a shrink-to-fit action or `view.fit` (which only changes zoom).
+After content settles, inspect the rendered result and arrange the intended node IDs if more
+spacing is needed; do not compensate with arbitrarily huge fixed frames.
 Since 0.4.6 the server clamps explicit creation sizes UP to per-type
 readability floors (e.g. markdown 360×180, graph/json-render/html 420×280, mcp-app 480×320) —
 a tiny probe size silently becomes the floor. `strictSize: true` is the only opt-out (a fixed
@@ -467,20 +489,21 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   iframe's per-mount nonce, so AX buttons only work inside the in-canvas node (0.4.4 Codex note).
   Do not tell a user a standalone tab's controls will steer the agent.
 - A hosted ext-app (Excalidraw) node in a **WebKit** host panel (e.g. the GitHub Copilot app's
-  embedded WKWebView) historically could render as a black tile — a host compositor paint race
-  on the nested iframe, **not** a broken node (the session is healthy, `sessionStatus` is
-  `ready`, and it renders fine in Chrome/Codex). Since 0.4.6 the canvas runs a **paint oracle +
+  embedded WKWebView) can remain blank even when its API session is healthy and `sessionStatus`
+  is `ready`. This host-specific rendering issue remains open; successful Chrome/Codex rendering
+  does not establish native-host health. Since 0.4.6 the canvas runs a **paint oracle +
   recovery ladder** under WebKit: present-at-load ext-apps mount strictly one at a time (the
   cold burst was the trigger), each frame answers a double-rAF **paint probe** after settle, and
   on silence the ladder escalates — soft-expand cycle (the automatic analogue of the proven
   enlarge+close) → serialized remount → an explicit "App surface failed to paint / Retry"
-  affordance. The connecting overlay stays up until paint is confirmed, so a black layer is
-  never presented as ready. The recovery trail
+  affordance. Native Copilot/WebKit surfaces can still remain blank despite a successful
+  probe, including when visibility is reported as visible. The recovery trail
   (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
   `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, `recovery-exhausted`, and
-  `assume-visible-rearm` — when diagnosing, trust `paint-ok`/`paint-fail`, and never assert
-  health from `settled` alone. Exception: in a host that reports the document hidden (the
-  GitHub Copilot panel does so continuously), `paint-ok` is recorded as
+  `assume-visible-rearm`. Treat `paint-ok`/`paint-fail` as diagnostic evidence, not compositor
+  proof. Require a rendered screenshot in the affected host before declaring its surface
+  healthy; a Chromium pass does not close a native Copilot/WebKit failure. In a host that
+  reports the document hidden, `paint-ok` is recorded as
   `paint-ok (unverified: host hidden)` — the app answered the paint probe, but nothing is
   proven composited, so do not treat it as a verified paint. If a
   tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.6.1**, which requires **Bun >=1.4.2** even when
+The examples pin **PMX Canvas 0.6.3**, which requires **Bun >=1.4.2** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -17,11 +17,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.6.1
+npm install -g pmx-canvas@0.6.3
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.6.1` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.6.3` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -73,7 +73,7 @@ bun run build
 bun run src/cli/index.ts --version
 ```
 
-This uses the checked-out source, not necessarily the published 0.6.1 package. Follow
+This uses the checked-out source, not necessarily the published package. Follow
 that checkout's `package.json` Bun requirement and bundled skill. Set the same root/port
 environment above; substitute `bun run /absolute/path/to/pmx-canvas/src/cli/index.ts`
 for `pmx-canvas` in startup and verification commands. The target workspace can be
@@ -91,7 +91,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.6.1", "--mcp"],
+      "args": ["pmx-canvas@0.6.3", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",

package/src/client/canvas/auto-fit.ts

@@ -1,5 +1,6 @@
 import type { CanvasNodeState } from '../types';
 import { nodeMinSize } from '../../shared/node-sizes.js';
+import { findBlocker } from '../../shared/placement.js';
 
 export const AUTO_FIT_TITLEBAR_HEIGHT = 37;
 export const AUTO_FIT_MAX_HEIGHT = 600;
@@ -81,7 +82,25 @@ export function shouldContentFitIframeNode(node: CanvasNodeState): boolean {
  * capped at the iframe ceiling.
  */
 export function computeContentGrowHeight(node: CanvasNodeState, contentHeight: number): number | null {
-  if (!shouldContentFitIframeNode(node) || contentHeight <= 0) return null;
+  if (!shouldContentFitIframeNode(node) || !Number.isFinite(contentHeight) || contentHeight <= 0) return null;
   const want = Math.min(contentHeight + AUTO_FIT_TITLEBAR_HEIGHT + AUTO_FIT_BODY_PADDING, AUTO_FIT_MAX_HEIGHT_IFRAME);
   return want > node.size.height + 8 ? want : null;
 }
+
+/** Keep an automatically growing card clear without moving its neighbors or
+ * changing its column. Groups and screen-pinned cards retain authored placement. */
+export function contentFitPosition(
+  node: CanvasNodeState,
+  height: number,
+  allNodes: CanvasNodeState[],
+): CanvasNodeState['position'] {
+  if (height <= node.size.height || node.pinned || node.data.parentGroup) return node.position;
+  const obstacles = allNodes.filter((other) => other.id !== node.id && !other.pinned && other.type !== 'group');
+  const position = { ...node.position };
+  let blocker = findBlocker(position, node.size.width, height, obstacles, 24);
+  while (blocker) {
+    position.y = blocker.position.y + blocker.size.height + 24;
+    blocker = findBlocker(position, node.size.width, height, obstacles, 24);
+  }
+  return position;
+}

package/src/client/nodes/use-iframe-content-height.ts

@@ -1,6 +1,9 @@
-import { useEffect, useRef } from 'preact/hooks';
-import { persistLayout, resizeNode } from '../state/canvas-store';
-import { computeContentGrowHeight } from '../canvas/auto-fit';
+import { effect } from '@preact/signals';
+import { useEffect } from 'preact/hooks';
+import { nodes, updateNode } from '../state/canvas-store';
+import { grabbingNodeId, otherHumans } from '../state/human-store';
+import { pushCanvasUpdate } from '../state/intent-bridge';
+import { computeContentGrowHeight, contentFitPosition } from '../canvas/auto-fit';
 import type { CanvasNodeState } from '../types';
 
 /**
@@ -11,43 +14,60 @@ import type { CanvasNodeState } from '../types';
  * because growth is monotonic with a dead-band — cannot oscillate. This is the
  * fix for iframe nodes whose body scrollHeight the parent can't measure.
  *
- * The latest node is read through a ref so the effect stays mounted across the
- * grow (its deps are only id + token). Putting node.size in the deps would re-run
- * the effect on each grow and its cleanup would cancel the pending persist.
+ * Debounce before changing geometry, retaining the latest measurement during a
+ * human grab. Read current geometry at application time; persist only this node.
+ * Relocations are undoable, height-only adjustments do not fill the undo stack.
  */
 export function useIframeContentHeight(
   node: CanvasNodeState,
   iframeRef: { current: HTMLIFrameElement | null },
   frameToken: string,
 ): void {
-  const nodeRef = useRef(node);
-  nodeRef.current = node;
-  const persistTimer = useRef<number | null>(null);
-
   useEffect(() => {
     if (!frameToken) return undefined;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let pendingHeight: number | null = null;
+    const held = () =>
+      grabbingNodeId.value === node.id || otherHumans.value.some((human) => human.grabbingNodeId === node.id);
+    function apply() {
+      timer = null;
+      if (held() || pendingHeight === null) return;
+      const reported = pendingHeight;
+      pendingHeight = null;
+      const current = nodes.value.get(node.id);
+      if (!current) return;
+      const target = computeContentGrowHeight(current, reported);
+      if (target === null) return;
+      const position = contentFitPosition(current, target, Array.from(nodes.value.values()));
+      const moved = position.x !== current.position.x || position.y !== current.position.y;
+      const patch = {
+        size: { width: current.size.width, height: target },
+        ...(moved ? { position } : {}),
+      };
+      updateNode(current.id, patch);
+      void pushCanvasUpdate([{ id: current.id, ...patch }], { recordHistory: moved });
+    }
+    function schedule() {
+      if (timer !== null) clearTimeout(timer);
+      timer = pendingHeight !== null && !held() ? setTimeout(apply, 300) : null;
+    }
+    const dispose = effect(() => {
+      held();
+      schedule();
+    });
     function onMessage(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const d = event.data as { source?: string; type?: string; token?: string; height?: unknown } | null;
       if (!d || d.source !== 'pmx-canvas-frame' || d.type !== 'content-height' || d.token !== frameToken) return;
-      const current = nodeRef.current;
-      const reported = typeof d.height === 'number' ? d.height : 0;
-      const target = computeContentGrowHeight(current, reported);
-      if (target === null) return;
-      resizeNode(current.id, { width: current.size.width, height: target });
-      if (persistTimer.current !== null) window.clearTimeout(persistTimer.current);
-      persistTimer.current = window.setTimeout(() => {
-        persistLayout({ recordHistory: false });
-        persistTimer.current = null;
-      }, 300);
+      if (typeof d.height !== 'number' || !Number.isFinite(d.height) || d.height <= 0) return;
+      pendingHeight = d.height;
+      schedule();
     }
     window.addEventListener('message', onMessage);
     return () => {
       window.removeEventListener('message', onMessage);
-      if (persistTimer.current !== null) {
-        window.clearTimeout(persistTimer.current);
-        persistTimer.current = null;
-      }
+      dispose();
+      if (timer !== null) clearTimeout(timer);
     };
   }, [node.id, frameToken]);
 }

package/src/client/state/human-store.ts

@@ -58,7 +58,7 @@ export function applyHumanSnapshot(snapshot: Partial<HumanPresenceSnapshot> | nu
   humans.value = snapshot.humans;
 }
 
-let grabbing: string | null = null;
+export const grabbingNodeId = signal<string | null>(null);
 let lastCursor: { x: number; y: number } | null = null;
 let lastSentAt = 0;
 let pending: ReturnType<typeof setTimeout> | null = null;
@@ -74,7 +74,7 @@ function post(body: Record<string, unknown>): void {
 function flushCursor(): void {
   pending = null;
   lastSentAt = Date.now();
-  post({ cursor: lastCursor, grabbingNodeId: grabbing });
+  post({ cursor: lastCursor, grabbingNodeId: grabbingNodeId.value });
 }
 
 /** Report the pointer in world coordinates (throttled); null when it leaves the canvas. */
@@ -91,7 +91,7 @@ export function reportHumanCursor(cursor: { x: number; y: number } | null): void
 
 /** Hold / release a node (drag, rename): the edit lock agents must respect. */
 export function reportHumanGrab(nodeId: string | null): void {
-  grabbing = nodeId;
+  grabbingNodeId.value = nodeId;
   post({ cursor: lastCursor, grabbingNodeId: nodeId });
 }
 
@@ -147,8 +147,8 @@ let heartbeat: ReturnType<typeof setInterval> | null = null;
 
 /** Announce this tab and keep it alive; renews a held grab. Call once per connection. */
 export function startHumanPresence(): () => void {
-  post({ cursor: lastCursor, grabbingNodeId: grabbing });
-  heartbeat = setInterval(() => post({ grabbingNodeId: grabbing }), 3000);
+  post({ cursor: lastCursor, grabbingNodeId: grabbingNodeId.value });
+  heartbeat = setInterval(() => post({ grabbingNodeId: grabbingNodeId.value }), 3000);
   const leave = () => {
     try {
       navigator.sendBeacon?.(
@@ -170,6 +170,6 @@ export function startHumanPresence(): () => void {
 export function resetHumanPresence(): void {
   humans.value = [];
   yieldedNodes.value = new Map();
-  grabbing = null;
+  grabbingNodeId.value = null;
   lastCursor = null;
 }

package/src/json-render/catalog.ts

@@ -20,6 +20,12 @@ const buttonDefinition = shadcnComponentDefinitions.Button;
 
 export const allComponentDefinitions = {
   ...shadcnComponentDefinitions,
+  Card: {
+    ...shadcnComponentDefinitions.Card,
+    slots: ['default', 'header', 'footer'],
+    description:
+      'Card container. Use children for its body and optional header/footer slots for custom headings or actions. A header slot replaces the title and description props.',
+  },
   Badge: {
     ...badgeDefinition,
     props: badgeDefinition.props.extend({

package/src/json-render/renderer/index.tsx

@@ -69,9 +69,26 @@ function Button({ props, emit }: { props: ButtonProps; emit: (event: string) =>
   );
 }
 
+function Card({ props, children, slots, ...rest }: Parameters<typeof shadcnComponents.Card>[0]) {
+  const header = slots?.header;
+  const footer = slots?.footer;
+  return (
+    <shadcnComponents.Card {...rest} props={header ? { ...props, title: null, description: null } : props}>
+      {header && <header data-pmx-card-slot="header">{header}</header>}
+      {children}
+      {footer && (
+        <footer data-pmx-card-slot="footer" className="flex flex-wrap items-center gap-3">
+          {footer}
+        </footer>
+      )}
+    </shadcnComponents.Card>
+  );
+}
+
 const { registry } = defineRegistry(catalog as never, {
   components: {
     ...shadcnComponents,
+    Card,
     Badge,
     Button,
     ...chartComponents,

package/src/json-render/schema.ts

@@ -4,12 +4,16 @@ export const schema = defineSchema(
   (s) => ({
     spec: s.object({
       root: s.string(),
+      state: { ...s.record(s.any()), ...s.optional() },
       elements: s.record(
         s.object({
           type: s.ref('catalog.components'),
           props: s.propsOf('catalog.components'),
           children: s.array(s.string()),
           visible: s.any(),
+          repeat: { ...s.any(), ...s.optional() },
+          watch: { ...s.record(s.any()), ...s.optional() },
+          slots: { ...s.record(s.array(s.string())), ...s.optional() },
           // Event→action bindings (on.press, on.change, …). Preserved through
           // validation so spec authors can wire actions — including the ax.*
           // handlers the viewer forwards to the canvas AX bridge.

package/src/mcp/server.ts

@@ -41,6 +41,7 @@ import {
   summarizeCanvasAnnotationForContext,
 } from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
+import { registerSkillExtension } from './skills.js';
 
 let canvas: CanvasAccess | null = null;
 let resourceNotificationServer: McpServer | null = null;
@@ -212,11 +213,15 @@ function buildSummaryFromLayout(
 }
 
 export async function startMcpServer(): Promise<void> {
-  const server = new McpServer({
-    name: 'pmx-canvas',
-    version: readPackageVersion(),
-  });
+  const server = new McpServer(
+    { name: 'pmx-canvas', version: readPackageVersion() },
+    {
+      instructions:
+        'Bundled workbench guidance: skill://pmx-canvas/SKILL.md. Discover skills via skills/list when supported, or canvas://skills; read files through resources/read. Skill delivery does not grant permission to execute bundled scripts.',
+    },
+  );
   resourceNotificationServer = server;
+  registerSkillExtension(server);
 
   // ── Operation-registry tools (plan-005) ────────────────────────
   // Standalone tools are registered from the shared operation registry for

package/src/mcp/skills.ts

@@ -0,0 +1,47 @@
+import { type McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { createBundledSkillCatalog } from '../server/bundled-skills.js';
+
+/** SEP-2640 methods are protocol requests, not model-facing canvas tools. */
+export function registerSkillExtension(server: McpServer, catalog = createBundledSkillCatalog()): void {
+  // The v1 SDK accepts custom methods and transmits capabilities unchanged,
+  // but its ServerCapabilities type predates the extensions field.
+  const capabilities = { resources: {}, extensions: { 'io.modelcontextprotocol/skills': {} } };
+  server.server.registerCapabilities(capabilities);
+  server.server.setRequestHandler(
+    z.object({ method: z.literal('skills/list'), params: z.object({ cursor: z.string().optional() }).optional() }),
+    async ({ params }) => {
+      // The bounded package catalog is a single page, so no cursor is issued.
+      if (params?.cursor !== undefined) throw new McpError(ErrorCode.InvalidParams, 'Unknown skills cursor');
+      return { resultType: 'complete', skills: catalog.skills };
+    },
+  );
+  server.server.setRequestHandler(
+    z.object({ method: z.literal('skills/get'), params: z.object({ uri: z.string() }) }),
+    async ({ params }) => {
+      const skill = catalog.skills.find((entry) => entry.uri === params.uri);
+      if (!skill) throw new McpError(ErrorCode.InvalidParams, `No skill is served at ${params.uri}`);
+      return { resultType: 'complete', skill };
+    },
+  );
+  server.registerResource(
+    'skill-files',
+    new ResourceTemplate('skill://{name}/{+path}', { list: undefined }),
+    { description: 'Packaged skill files. Discover complete manifests through skills/list or skills/get.' },
+    async (uri) => {
+      // Exact catalog lookup: a URI never becomes a filesystem path.
+      const content = catalog.files.get(uri.href);
+      if (!content) throw new McpError(ErrorCode.InvalidParams, `No skill file is served at ${uri.href}`);
+      return { contents: [content] };
+    },
+  );
+  for (const skill of catalog.skills) {
+    server.registerResource(
+      skill.frontmatter.name,
+      skill.uri,
+      { mimeType: 'text/markdown', description: skill.frontmatter.description },
+      async () => ({ contents: [catalog.files.get(skill.uri)!] }),
+    );
+  }
+}

package/src/server/bundled-skills.ts

@@ -17,15 +17,29 @@
  *   - `canvas://skills/<name>`   → full markdown content
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+
+const skillFrontmatterSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    description: z.string().min(1).max(1024),
+  })
+  .passthrough();
 
 export interface BundledSkill {
   name: string;
   description: string;
   uri: string;
   filePath: string;
+  frontmatter: z.infer<typeof skillFrontmatterSchema>;
 }
 
 const MAX_DESCRIPTION_LENGTH = 400;
@@ -65,52 +79,18 @@ export function findBundledSkillsRoot(): string | null {
   return null;
 }
 
-function parseFrontmatterDescription(rawMarkdown: string): string {
-  // Normalize CRLF first: a git checkout with autocrlf (the Windows default)
-  // puts a trailing \r on every line, which `(.*)$` cannot match (JS `.` and
-  // `$` both exclude \r), silently emptying every description.
-  const markdown = rawMarkdown.replace(/\r\n/g, '\n');
-  // YAML frontmatter lives between two `---` fences at the very top.
-  if (!markdown.startsWith('---')) return '';
-  const end = markdown.indexOf('\n---', 3);
-  if (end === -1) return '';
-  const frontmatter = markdown.slice(3, end);
-  const lines = frontmatter.split('\n');
-
-  // Support both single-line `description: ...` and block-scalar `description: >` /
-  // `description: |` forms (indented continuation lines).
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? '';
-    const match = /^description:\s*(.*)$/.exec(line);
-    if (!match) continue;
-    const first = (match[1] ?? '').trim();
-    if (first && first !== '>' && first !== '|' && first !== '>-' && first !== '|-') {
-      return first.slice(0, MAX_DESCRIPTION_LENGTH);
-    }
-    // Block scalar — concatenate indented follow-on lines.
-    const parts: string[] = [];
-    for (let j = i + 1; j < lines.length; j++) {
-      const follow = lines[j] ?? '';
-      if (follow.length === 0) {
-        parts.push('');
-        continue;
-      }
-      if (!/^\s/.test(follow)) break;
-      parts.push(follow.trim());
-    }
-    return parts.join(' ').replace(/\s+/g, ' ').trim().slice(0, MAX_DESCRIPTION_LENGTH);
-  }
-  return '';
+function parseFrontmatter(markdown: string): BundledSkill['frontmatter'] {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!match) throw new Error('Bundled skill is missing YAML frontmatter');
+  return skillFrontmatterSchema.parse(Bun.YAML.parse(match[1]!));
 }
 
 /**
  * Enumerate every `<name>/SKILL.md` under the bundled skills root and return
- * a compact index. Hidden directories (dotfolders) and files that don't parse
- * are skipped silently rather than throwing — missing metadata should never
- * break the MCP server's resource listing.
+ * a compact index. Invalid packaged skills fail explicitly rather than being
+ * silently omitted from the Skills extension's integrity manifest.
  */
-export function listBundledSkills(): BundledSkill[] {
-  const root = findBundledSkillsRoot();
+export function listBundledSkills(root = findBundledSkillsRoot()): BundledSkill[] {
   if (!root) return [];
   const entries = readdirSync(root);
   const skills: BundledSkill[] = [];
@@ -118,18 +98,19 @@ export function listBundledSkills(): BundledSkill[] {
     if (entry.startsWith('.')) continue;
     const skillFile = join(root, entry, 'SKILL.md');
     if (!existsSync(skillFile)) continue;
-    try {
-      const markdown = readFileSync(skillFile, 'utf-8');
-      const description = parseFrontmatterDescription(markdown);
-      skills.push({
-        name: entry,
-        description,
-        uri: `canvas://skills/${entry}`,
-        filePath: skillFile,
-      });
-    } catch {
-      // skip unreadable files
+    if (lstatSync(join(root, entry)).isSymbolicLink() || lstatSync(skillFile).isSymbolicLink()) {
+      throw new Error(`Bundled skill contains a symbolic link: ${entry}`);
     }
+    if (!lstatSync(skillFile).isFile()) throw new Error(`Bundled skill contains a non-regular file: ${skillFile}`);
+    const frontmatter = parseFrontmatter(readFileSync(skillFile, 'utf-8'));
+    if (frontmatter.name !== entry) throw new Error(`Bundled skill name does not match directory: ${entry}`);
+    skills.push({
+      name: entry,
+      description: frontmatter.description.slice(0, MAX_DESCRIPTION_LENGTH),
+      uri: `canvas://skills/${entry}`,
+      filePath: skillFile,
+      frontmatter,
+    });
   }
   skills.sort((a, b) => a.name.localeCompare(b.name));
   return skills;
@@ -145,3 +126,61 @@ export function readBundledSkill(name: string): string | null {
     return null;
   }
 }
+
+export interface SkillEntry {
+  uri: string;
+  frontmatter: BundledSkill['frontmatter'];
+  resources: Array<{ uri: string; digest: string; size: number }>;
+}
+
+type SkillContent = { uri: string; mimeType: string } & ({ text: string } | { blob: string });
+
+/** Capture immutable package bytes once per MCP process, never read caller-supplied paths. */
+export function createBundledSkillCatalog(root = findBundledSkillsRoot()) {
+  const skills: SkillEntry[] = [];
+  const files = new Map<string, SkillContent>();
+  for (const skill of listBundledSkills(root)) {
+    const entry: SkillEntry = { uri: `skill://${skill.name}/SKILL.md`, frontmatter: skill.frontmatter, resources: [] };
+    let totalBytes = 0;
+    function walk(directory: string, prefix = ''): void {
+      for (const child of readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
+        a.name.localeCompare(b.name),
+      )) {
+        const filePath = join(directory, child.name);
+        const relativePath = prefix + encodeURIComponent(child.name);
+        if (child.isSymbolicLink()) throw new Error(`Bundled skill contains a symbolic link: ${filePath}`);
+        if (child.isDirectory()) {
+          walk(filePath, `${relativePath}/`);
+          continue;
+        }
+        if (!child.isFile()) throw new Error(`Bundled skill contains a non-regular file: ${filePath}`);
+        totalBytes += lstatSync(filePath).size;
+        if (entry.resources.length >= 512 || totalBytes > 16 * 1024 * 1024) {
+          throw new Error(`Bundled skill exceeds SEP-2640 file/byte limits: ${skill.name}`);
+        }
+        const bytes = readFileSync(filePath);
+        const uri = `skill://${skill.name}/${relativePath}`;
+        const mimeType = child.name.endsWith('.md') ? 'text/markdown' : Bun.file(filePath).type;
+        // Round-trip detection preserves invalid UTF-8 and binary assets as blobs.
+        const text = bytes.toString('utf8');
+        const content =
+          !bytes.includes(0) && Buffer.from(text).equals(bytes)
+            ? { uri, mimeType, text }
+            : { uri, mimeType, blob: bytes.toString('base64') };
+        files.set(uri, content);
+        entry.resources.push({
+          uri,
+          size: bytes.length,
+          digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
+        });
+        if (uri === entry.uri) entry.frontmatter = parseFrontmatter(text);
+      }
+    }
+    walk(dirname(skill.filePath));
+    if (entry.frontmatter.name !== skill.name)
+      throw new Error(`Bundled skill name changed during loading: ${skill.name}`);
+    entry.resources.sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+    skills.push(entry);
+  }
+  return { skills, files };
+}