@mediadatafusion/pi-workflow-suite 0.0.11 → 0.0.12

package/extensions/workflow-web-tools.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { execSync } from "node:child_process";
 import { Type } from "typebox";
 
 type RuntimeToolInfo = {
@@ -32,9 +33,44 @@ export interface WorkflowWebFetchDetails {
   fetchedAt: string;
 }
 
+export interface WorkflowBrowserAction {
+  action: "click" | "type" | "wait" | "waitForSelector" | "select" | "evaluate" | "screenshot" | "reload" | "readText" | "readAttr";
+  selector?: string;
+  value?: string;
+  timeout?: number;
+  label?: string;
+}
+
+export interface WorkflowBrowserActionResult {
+  label?: string;
+  action: string;
+  ok: boolean;
+  error?: string;
+  text?: string;
+  attrValue?: string | null;
+  result?: unknown;
+  found?: boolean;
+}
+
+export interface WorkflowBrowserCheckDetails {
+  url: string;
+  title: string;
+  consoleMessages: string[];
+  pageErrors: string[];
+  elementCounts: Record<string, number>;
+  localStorageValues: Record<string, string | null>;
+  screenshotPath?: string;
+  loadTimeMs: number;
+  error?: string;
+  actionResults?: WorkflowBrowserActionResult[];
+}
+
 const WORKFLOW_WEB_SEARCH_TOOL = "workflow_web_search";
 const WORKFLOW_WEB_FETCH_TOOL = "workflow_web_fetch";
-const WORKFLOW_WEB_TOOLS = [WORKFLOW_WEB_SEARCH_TOOL, WORKFLOW_WEB_FETCH_TOOL];
+const WORKFLOW_BROWSER_CHECK_TOOL = "workflow_browser_check";
+const WORKFLOW_STOP_SERVER_TOOL = "workflow_stop_server";
+const WORKFLOW_WEB_TOOLS = [WORKFLOW_WEB_SEARCH_TOOL, WORKFLOW_WEB_FETCH_TOOL, WORKFLOW_BROWSER_CHECK_TOOL, WORKFLOW_STOP_SERVER_TOOL];
+const workflowWebErrorMessage = (error: unknown): string => error instanceof Error ? error.message : String(error ?? "");
 const SEARCH_TIMEOUT_MS = 12_000;
 const FETCH_TIMEOUT_MS = 12_000;
 const MAX_SEARCH_RESULTS = 10;
@@ -73,6 +109,24 @@ const WorkflowWebFetchParams = Type.Object({
   maxChars: Type.Optional(Type.Number({ description: "Maximum extracted text characters to return, 1000-18000. Default 12000.", minimum: 1000, maximum: 18000 })),
 });
 
+const WorkflowBrowserCheckParams = Type.Object({
+  url: Type.String({ description: "Full URL to check in a headless browser, e.g. http://localhost:8017." }),
+  selectors: Type.Optional(Type.Array(Type.String(), { description: "CSS selectors to count matching elements." })),
+  localStorageKeys: Type.Optional(Type.Array(Type.String(), { description: "localStorage keys to retrieve values for." })),
+  screenshot: Type.Optional(Type.Boolean({ description: "Take a full-page screenshot saved to /tmp/validator_screenshot.png." })),
+  actions: Type.Optional(Type.Array(Type.Object({
+    action: Type.String({ description: "Interaction type: click, type, wait, waitForSelector, select, evaluate, screenshot, reload, readText, readAttr." }),
+    selector: Type.Optional(Type.String({ description: "CSS selector for the target element (required for click, type, waitForSelector, readText, readAttr)." })),
+    value: Type.Optional(Type.String({ description: "Text to type (type action), JS expression (evaluate action), or attribute name (readAttr action)." })),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in ms. Default 5000." })),
+    label: Type.Optional(Type.String({ description: "Human-readable label for this step in results." })),
+  }), { description: "Sequential browser interaction steps to perform after page load." })),
+});
+
+const WorkflowStopServerParams = Type.Object({
+  port: Type.Number({ description: "Port number to kill any process listening on (1-65535).", minimum: 1, maximum: 65535 }),
+});
+
 function normalizeToolName(name: string): string {
   return name.trim().toLowerCase();
 }
@@ -270,6 +324,211 @@ export async function workflowWebFetch(rawUrl: string, maxChars = 12_000): Promi
   }
 }
 
+export async function workflowBrowserCheck(
+  url: string,
+  selectors?: string[],
+  localStorageKeys?: string[],
+  screenshot?: boolean,
+  actions?: WorkflowBrowserAction[],
+): Promise<WorkflowBrowserCheckDetails> {
+  const startTime = Date.now();
+  const cleanUrl = url.trim();
+  if (!cleanUrl) throw new Error("URL is required.");
+  let puppeteer: typeof import("puppeteer");
+  try {
+    puppeteer = (await import("puppeteer")).default as typeof import("puppeteer");
+  } catch {
+    return {
+      url: cleanUrl, title: "", consoleMessages: [], pageErrors: [],
+      elementCounts: {}, localStorageValues: {}, loadTimeMs: Date.now() - startTime,
+      error: "Puppeteer is not available in this environment.",
+    };
+  }
+  const browser = await puppeteer.launch({ headless: "shell", args: ["--no-sandbox"] });
+  try {
+    const page = await browser.newPage();
+    const consoleMessages: string[] = [];
+    const pageErrors: string[] = [];
+    page.on("console", (msg) => consoleMessages.push(`${msg.type()}: ${msg.text()}`));
+    page.on("pageerror", (err) => pageErrors.push(workflowWebErrorMessage(err)));
+    await page.goto(cleanUrl, { waitUntil: "networkidle2", timeout: 15000 });
+    const title = await page.title();
+    const elementCounts: Record<string, number> = {};
+    if (selectors && selectors.length > 0) {
+      for (const sel of selectors) {
+        try {
+          elementCounts[sel] = await page.$$eval(sel, (els) => els.length);
+        } catch {
+          elementCounts[sel] = 0;
+        }
+      }
+    }
+    const localStorageValues: Record<string, string | null> = {};
+    if (localStorageKeys && localStorageKeys.length > 0) {
+      for (const key of localStorageKeys) {
+        try {
+          localStorageValues[key] = await page.evaluate((k) => localStorage.getItem(k), key);
+        } catch {
+          localStorageValues[key] = null;
+        }
+      }
+    }
+    let screenshotPath: string | undefined;
+    if (screenshot) {
+      screenshotPath = "/tmp/validator_screenshot.png";
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+    }
+    const actionResults: WorkflowBrowserActionResult[] = [];
+    if (actions && actions.length > 0) {
+      for (const act of actions) {
+        const result: WorkflowBrowserActionResult = { label: act.label, action: act.action, ok: false };
+        const timeout = act.timeout ?? 5000;
+        try {
+          switch (act.action) {
+            case "click":
+              if (!act.selector) throw new Error("selector required for click");
+              await page.waitForSelector(act.selector, { timeout });
+              await page.click(act.selector);
+              result.ok = true;
+              break;
+            case "type":
+              if (!act.selector) throw new Error("selector required for type");
+              if (act.value === undefined) throw new Error("value required for type");
+              await page.waitForSelector(act.selector, { timeout });
+              await page.type(act.selector, act.value, { delay: 20 });
+              result.ok = true;
+              break;
+            case "wait":
+              await new Promise((r) => setTimeout(r, timeout));
+              result.ok = true;
+              break;
+            case "waitForSelector":
+              if (!act.selector) throw new Error("selector required for waitForSelector");
+              await page.waitForSelector(act.selector, { timeout });
+              result.found = true;
+              result.ok = true;
+              break;
+            case "select":
+              if (!act.selector) throw new Error("selector required for select");
+              if (act.value === undefined) throw new Error("value required for select");
+              await page.waitForSelector(act.selector, { timeout });
+              await page.select(act.selector, act.value);
+              result.ok = true;
+              break;
+            case "evaluate":
+              if (act.value === undefined) throw new Error("value (JS expression) required for evaluate");
+              result.result = await page.evaluate(act.value);
+              result.ok = true;
+              break;
+            case "screenshot": {
+              const stepPath = `/tmp/validator_step_${actionResults.length}.png`;
+              await page.screenshot({ path: stepPath, fullPage: true });
+              result.result = stepPath;
+              result.ok = true;
+              break;
+            }
+            case "reload":
+              await page.reload({ waitUntil: "networkidle2", timeout });
+              result.ok = true;
+              break;
+            case "readText":
+              if (!act.selector) throw new Error("selector required for readText");
+              await page.waitForSelector(act.selector, { timeout });
+              result.text = await page.$eval(act.selector, (el) => (el as HTMLElement).innerText?.trim() ?? el.textContent?.trim() ?? "");
+              result.ok = true;
+              break;
+            case "readAttr":
+              if (!act.selector) throw new Error("selector required for readAttr");
+              if (!act.value) throw new Error("value (attribute name) required for readAttr");
+              await page.waitForSelector(act.selector, { timeout });
+              result.attrValue = await page.$eval(act.selector, (el, attr) => el.getAttribute(attr as string), act.value);
+              result.ok = true;
+              break;
+            default:
+              result.error = `Unknown action type: ${act.action}`;
+          }
+        } catch (err) {
+          result.error = err instanceof Error ? err.message : String(err);
+        }
+        actionResults.push(result);
+      }
+    }
+    return {
+      url: cleanUrl, title, consoleMessages, pageErrors,
+      elementCounts, localStorageValues, screenshotPath,
+      loadTimeMs: Date.now() - startTime,
+      ...(actionResults.length > 0 ? { actionResults } : {}),
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+
+// ── Cross-platform port-kill utility ──────────────────────────
+
+function killOnPortUnix(port: number): boolean {
+  // Primary: lsof — works on macOS (built-in) and most Linux systems
+  try {
+    const out = execSync("lsof -ti :" + port + " 2>/dev/null", { timeout: 3000, encoding: "utf8" });
+    const pids = out.trim().split("\n").map(Number).filter(pid => pid > 0);
+    if (pids.length > 0) {
+      for (const pid of pids) {
+        try { process.kill(pid, "SIGTERM"); } catch { /* already dead */ }
+      }
+      return true;
+    }
+  } catch { /* lsof unavailable or port free */ }
+  // Fallback 1: fuser — Linux psmisc
+  try {
+    execSync("fuser -k " + port + "/tcp 2>/dev/null || true", { timeout: 3000 });
+    return true;
+  } catch { /* fuser unavailable */ }
+  // Fallback 2: ss — Linux iproute2 (always available, even in minimal containers)
+  try {
+    const out = execSync("ss -tlnp 'sport = :" + port + "' 2>/dev/null", { timeout: 3000, encoding: "utf8" });
+    const match = out.match(/pid=(\d+)/);
+    if (match) {
+      try { process.kill(parseInt(match[1], 10), "SIGTERM"); } catch { /* already dead */ }
+      return true;
+    }
+  } catch { /* ss unavailable */ }
+  return false;
+}
+
+function killOnPortWindows(port: number): boolean {
+  try {
+    const out = execSync("netstat -ano | findstr :" + port, { timeout: 3000, encoding: "utf8", shell: "cmd.exe" });
+    const lines = out.split("\n");
+    let killed = false;
+    for (const line of lines) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 5 && parts[1] && parts[1].endsWith(":" + port)) {
+        const pid = parseInt(parts[parts.length - 1], 10);
+        if (pid > 0) {
+          try {
+            execSync("taskkill /PID " + pid + " /F", { timeout: 3000, shell: "cmd.exe" });
+            killed = true;
+          } catch { /* taskkill failed */ }
+        }
+      }
+    }
+    return killed;
+  } catch { return false; }
+}
+
+function killProcessOnPort(port: number): boolean {
+  try {
+    if (process.platform === "win32") {
+      return killOnPortWindows(port);
+    } else {
+      return killOnPortUnix(port);
+    }
+  } catch {
+    return false;
+  }
+}
+
 export function refreshRuntimeWebTools(pi: ExtensionAPI): string[] {
   const tools = pi.getAllTools() as RuntimeToolInfo[];
   discoveredRuntimeWebTools = Array.from(new Set(
@@ -351,6 +610,107 @@ export function registerWorkflowWebTools(pi: ExtensionAPI): void {
       }
     },
   } as ToolDefinition<typeof WorkflowWebFetchParams, WorkflowWebFetchDetails>);
+
+  pi.registerTool({
+    name: WORKFLOW_BROWSER_CHECK_TOOL,
+    label: "Workflow Browser Check",
+    description: "Launch a headless browser to verify a web app. Supports passive checks (console errors, DOM elements, localStorage) and interactive actions (click, type, wait, read text, read attributes, screenshots, page reload). Use for browser-level validation evidence when dev server or static HTTP server is running.",
+    promptSnippet: "Launch headless browser for passive checks and interactive actions at a URL",
+    promptGuidelines: [
+      "Use workflow_browser_check to gather browser-level validation evidence. For passive checks, pass selectors and localStorageKeys. For interactive testing, pass an actions array with click, type, waitForSelector, readText, readAttr, screenshot, reload, evaluate, wait, or select steps.",
+      "Start a dev server or python3 http.server first, then pass the URL to workflow_browser_check.",
+      "After browser checks complete, stop the server with workflow_stop_server({ port: PORT }) — do not rely on platform-specific shell commands.",
+      "Actions execute sequentially after page load. Each action returns ok/error and type-specific results (text, attrValue, result, found). Failed actions do not abort remaining actions.",
+      "Use readText to extract visible text from elements. Use readAttr to read attribute values like 'value', 'class', 'disabled'. Use evaluate for arbitrary JS like document.title or localStorage.getItem('key').",
+      "Set screenshot: true for initial page, or use a screenshot action step after interactions.",
+    ],
+    parameters: WorkflowBrowserCheckParams,
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal): Promise<AgentToolResult<WorkflowBrowserCheckDetails>> {
+      if (signal?.aborted) throw new Error("Browser check aborted.");
+      try {
+        const p = params as { url?: unknown; selectors?: unknown; localStorageKeys?: unknown; screenshot?: unknown; actions?: unknown };
+        const rawActions = Array.isArray(p.actions) ? p.actions : undefined;
+        const parsedActions: WorkflowBrowserAction[] | undefined = rawActions?.map((a: unknown) => {
+          const item = a as Record<string, unknown>;
+          return {
+            action: String(item.action ?? ""),
+            selector: typeof item.selector === "string" ? item.selector : undefined,
+            value: typeof item.value === "string" ? item.value : undefined,
+            timeout: typeof item.timeout === "number" ? item.timeout : undefined,
+            label: typeof item.label === "string" ? item.label : undefined,
+          } as WorkflowBrowserAction;
+        });
+        const details = await workflowBrowserCheck(
+          String(p.url ?? ""),
+          Array.isArray(p.selectors) ? p.selectors.map(String) : undefined,
+          Array.isArray(p.localStorageKeys) ? p.localStorageKeys.map(String) : undefined,
+          Boolean(p.screenshot),
+          parsedActions,
+        );
+        const lines: string[] = [
+          `URL: ${details.url}`,
+          `Title: ${details.title || "(none)"}`,
+          `Load time: ${details.loadTimeMs}ms`,
+        ];
+        if (details.error) {
+          lines.push(`Error: ${details.error}`);
+        } else {
+          lines.push(`Console messages: ${details.consoleMessages.length}`);
+          for (const msg of details.consoleMessages.slice(0, 20)) lines.push(`  ${msg}`);
+          if (details.consoleMessages.length > 20) lines.push(`  ... and ${details.consoleMessages.length - 20} more`);
+          lines.push(`Page errors: ${details.pageErrors.length}`);
+          for (const err of details.pageErrors) lines.push(`  ${err}`);
+          if (details.elementCounts && Object.keys(details.elementCounts).length > 0) {
+            lines.push("Element counts:");
+            for (const [sel, count] of Object.entries(details.elementCounts)) lines.push(`  ${sel}: ${count}`);
+          }
+          if (details.localStorageValues && Object.keys(details.localStorageValues).length > 0) {
+            lines.push("localStorage:");
+            for (const [key, val] of Object.entries(details.localStorageValues)) lines.push(`  ${key}: ${val ?? "(null)"}`);
+          }
+          if (details.screenshotPath) lines.push(`Screenshot: ${details.screenshotPath}`);
+          if (details.actionResults && details.actionResults.length > 0) {
+            lines.push(`Actions: ${details.actionResults.length} step(s)`);
+            for (const r of details.actionResults) {
+              const label = r.label ? `[${r.label}] ` : "";
+              const parts = [`  ${label}${r.action}: ${r.ok ? "OK" : "FAILED"}`];
+              if (r.error) parts.push(`| error: ${r.error}`);
+              if (r.text !== undefined) parts.push(`| text: "${r.text.slice(0, 200)}"`);
+              if (r.attrValue !== undefined) parts.push(`| attr: ${r.attrValue}`);
+              if (r.found !== undefined) parts.push(`| found: ${r.found}`);
+              if (r.result !== undefined) parts.push(`| result: ${typeof r.result === "string" ? r.result : JSON.stringify(r.result)}`);
+              lines.push(parts.join(" "));
+            }
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }], details };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Workflow browser check failed: ${message}` }], details: { url: String((params as { url?: unknown }).url ?? ""), title: "", consoleMessages: [], pageErrors: [], elementCounts: {}, localStorageValues: {}, loadTimeMs: 0, error: message } };
+      }
+    },
+  } as ToolDefinition<typeof WorkflowBrowserCheckParams, WorkflowBrowserCheckDetails>);
+
+  pi.registerTool({
+    name: WORKFLOW_STOP_SERVER_TOOL,
+    label: "Workflow Stop Server",
+    description: "Kill any process listening on the given port. Cross-platform (macOS, Windows, Linux). Use to stop dev servers, static HTTP servers, or any background process started for validation.",
+    promptSnippet: "Stop a server process on a port",
+    promptGuidelines: [
+      "Use workflow_stop_server to reliably stop dev servers or static servers after validation instead of shell commands.",
+      "Pass the port number the server is listening on (e.g., 3017 for a server started on port 3017).",
+      "This works cross-platform and does not require fuser, lsof, or other platform-specific tools installed.",
+    ],
+    parameters: WorkflowStopServerParams,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, signal): Promise<AgentToolResult<{ port: number; killed: boolean }>> {
+      if (signal?.aborted) throw new Error("Server stop aborted.");
+      const port = (params as { port: number }).port;
+      const killed = killProcessOnPort(port);
+      return { content: [{ type: "text", text: killed ? "Stopped process on port " + port + "." : "No process found on port " + port + " (already free or unable to kill)." }], details: { port, killed } };
+    },
+  } as ToolDefinition<typeof WorkflowStopServerParams, { port: number; killed: boolean }>);
 }
 
 export default function workflowWebToolsNoopExtension(): void {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediadatafusion/pi-workflow-suite",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Structured workflow orchestration suite for Pi with Standard, Plan, Mission, compaction, diagrams, web access, repo lock, and safety gates.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,6 +41,7 @@
     "agents/",
     "config/",
     "themes/",
+    "docs/assets/",
     "scripts/install-to-live.sh",
     "scripts/verify-live.sh",
     "scripts/audit-live.sh",
@@ -50,6 +51,8 @@
     "scripts/bootstrap-project.sh",
     "scripts/check-clean-release-tree.sh",
     "scripts/check-package-size.mjs",
+    "scripts/check-package-media.mjs",
+    "scripts/package-media-config.mjs",
     "scripts/prepare-package-readme.mjs",
     "scripts/build-package-export.mjs",
     "README.md",
@@ -78,8 +81,8 @@
     "themes": [
       "./themes"
     ],
-    "image": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.6/docs/assets/pi-workflow-suite-header.png",
-    "video": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.6/docs/assets/pi-workflow-suite-demo.mp4"
+    "image": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/pi-workflow-suite-header.png",
+    "video": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/pi-workflow-suite-demo.mp4"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -104,9 +107,10 @@
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "check:ts": "tsc --noEmit --noCheck",
+    "check:ts": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run check:ts && ./scripts/test-workflow-forced-subagent-regression.sh && ./scripts/test-agent-skill-boundary-regression.sh && ./scripts/test-startup-visual-mode-entry-regression.sh && ./scripts/test-settings-health-regression.sh && ./scripts/test-handoff-visibility-regression.sh && ./scripts/test-mission-milestone-handoff-regression.sh && ./scripts/test-plan-handoff-chain-regression.sh && ./scripts/test-plan-step-progress-regression.sh && ./scripts/test-standard-mode-regression.sh && ./scripts/test-final-handoff-summary-regression.sh && ./scripts/test-clarification-answer-handoff-regression.sh && ./scripts/test-validation-evidence-contract-regression.sh && ./scripts/test-mermaid-guidance-regression.sh && ./scripts/test-runtime-web-tools-regression.sh && ./scripts/test-repolock-scope-regression.sh && ./scripts/test-repo-lock-version-regression.sh && ./scripts/test-package-menu-surface.sh && npm run check:package-size && git diff --check",
+    "validate": "npm run check:ts && npm run check:package-media && npm run check:package-size && git diff --check",
+    "check:package-media": "node scripts/check-package-media.mjs",
     "check:package-size": "node scripts/check-package-size.mjs",
     "prepack": "node scripts/prepare-package-readme.mjs apply",
     "postpack": "node scripts/prepare-package-readme.mjs restore --pack",

package/scripts/audit-live.sh

@@ -28,7 +28,7 @@ while IFS= read -r rel; do
     printf 'MISSING: %s\n' "$rel"
     missing=1
   fi
-done < <(cd "$REPO_DIR" && find agents skills extensions config -type f ! -name '.DS_Store' ! -name '*.backup.*' ! -name '*.broken.*' | sort)
+done < <(cd "$REPO_DIR" && find agents skills extensions config -type f ! -name '.DS_Store' ! -name '*.bak' ! -name '*.backup.*' ! -name '*.broken.*' | sort)
 if [[ "$missing" -eq 0 ]]; then
   printf 'OK: no missing canonical managed files\n'
 fi

package/scripts/build-package-export.mjs

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { packageMediaUrl, packageMediaUrls } from './package-media-config.mjs';
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(scriptDir, '..');
@@ -39,20 +40,14 @@ function parseArgs(argv) {
   return args;
 }
 
-const mediaVersion = '0.0.6';
-
-function mediaCdn(assetPath) {
-  return `https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@${mediaVersion}/${assetPath}`;
-}
-
 function buildPackageReadme(sourceReadme, version) {
   const headerBlock = `# Pi Workflow Suite\n\n${
-    `![Pi Workflow Suite — structured workflow orchestration for Pi](${mediaCdn('docs/assets/pi-workflow-suite-header.png')})`
+    `![Pi Workflow Suite — structured workflow orchestration for Pi](${packageMediaUrls.header})`
   }\n\n${[
-    `[![Install](${mediaCdn('docs/assets/readme-link-install.svg')})](#installation)`,
-    `[![Quick Start](${mediaCdn('docs/assets/readme-link-quick-start.svg')})](#quick-start)`,
-    `[![Commands](${mediaCdn('docs/assets/readme-link-commands.svg')})](#core-commands)`,
-    `[![Settings](${mediaCdn('docs/assets/readme-link-settings.svg')})](#settings-reference)`,
+    `[![Install](${packageMediaUrls.readmeInstall})](#installation)`,
+    `[![Quick Start](${packageMediaUrls.readmeQuickStart})](#quick-start)`,
+    `[![Commands](${packageMediaUrls.readmeCommands})](#core-commands)`,
+    `[![Settings](${packageMediaUrls.readmeSettings})](#settings-reference)`,
   ].join(' ')}\n\n**Workflow Suite Version:** `;
 
   let readme = sourceReadme.replace(
@@ -60,7 +55,7 @@ function buildPackageReadme(sourceReadme, version) {
     headerBlock,
   );
 
-  const packageMediaBlock = `## Quick Demo\n\nSee Pi Workflow Suite in action: structured workflow modes, settings, runtime status, and guided execution inside Pi.\n\n[![Watch the Pi Workflow Suite quick demo](${mediaCdn('docs/assets/pi-workflow-suite-demo.gif')})](${mediaCdn('docs/assets/pi-workflow-suite-demo.mp4')})\n\n## Screenshots\n\n${[
+  const packageMediaBlock = `## Quick Demo\n\nSee Pi Workflow Suite in action: structured workflow modes, settings, runtime status, and guided execution inside Pi.\n\n[![Watch the Pi Workflow Suite quick demo](${packageMediaUrls.demoGif})](${packageMediaUrls.demoMp4})\n\n## Screenshots\n\n${[
     ['Pi Workflow Suite Mission Home with workflow graphs', 'docs/assets/screenshots/00-mission-home.png'],
     ['Pi Workflow Suite startup logo', 'docs/assets/screenshots/01-startup-Logo.png'],
     ['Workflow Suite theme settings', 'docs/assets/screenshots/02-theme-settings.png'],
@@ -68,7 +63,7 @@ function buildPackageReadme(sourceReadme, version) {
     ['Workflow Suite shared sub-agent settings', 'docs/assets/screenshots/04-SharedSubAgentsSettings.png'],
     ['Mission Mode milestone progress', 'docs/assets/screenshots/05-mission-mode.png'],
     ['Workflow Suite Mermaid diagram output', 'docs/assets/screenshots/06-diagram-mermaid.png'],
-  ].map(([alt, path]) => `![${alt}](${mediaCdn(path)})`).join('\n\n')}\n\n`;
+  ].map(([alt, path]) => `![${alt}](${packageMediaUrl(path)})`).join('\n\n')}\n\n`;
 
   readme = readme.replace(/## Quick Demo[\s\S]*?## Contents\n/, `${packageMediaBlock}## Contents\n`);
   return readme;

package/scripts/check-clean-release-tree.sh

@@ -11,6 +11,7 @@ report() {
 }
 
 if [[ -e AGENTS.md && -n "$(git ls-files AGENTS.md)" ]]; then report 'AGENTS.md must not be present on clean release main'; fi
+if [[ -e CLAUDE.md && -n "$(git ls-files CLAUDE.md)" ]]; then report 'CLAUDE.md must not be present on clean release main'; fi
 if [[ -e .github && -n "$(git ls-files .github)" ]]; then report '.github/ must not be tracked on clean release main'; fi
 if [[ -e .factory && -n "$(git ls-files .factory)" ]]; then report '.factory/ must not be tracked on clean release main'; fi
 if [[ -e .kilo && -n "$(git ls-files .kilo)" ]]; then report '.kilo/ must not be tracked on clean release main'; fi
@@ -18,7 +19,7 @@ if [[ -e .cursor && -n "$(git ls-files .cursor)" ]]; then report '.cursor/ must
 
 while IFS= read -r path; do
   case "$path" in
-    agents/*|config/*|extensions/*|skills/*|docs/assets/*|themes/*|scripts/install-to-live.sh|scripts/verify-live.sh|scripts/audit-live.sh|scripts/quarantine-live-junk.sh|scripts/backup-live.sh|scripts/audit-settings.sh|scripts/bootstrap-project.sh|scripts/check-clean-release-tree.sh|scripts/check-package-size.mjs|scripts/prepare-package-readme.mjs|scripts/build-package-export.mjs|README.md|CHANGELOG.md|CONTRIBUTING.md|LICENSE.md|NOTICE|SECURITY.md|SUPPORT.md|TRADEMARKS.md|VERSION|package.json|package-lock.json|tsconfig.json|.gitignore)
+    agents/*|config/*|extensions/*|skills/*|docs/assets/*|themes/*|scripts/install-to-live.sh|scripts/verify-live.sh|scripts/audit-live.sh|scripts/quarantine-live-junk.sh|scripts/backup-live.sh|scripts/audit-settings.sh|scripts/bootstrap-project.sh|scripts/check-clean-release-tree.sh|scripts/check-package-size.mjs|scripts/check-package-media.mjs|scripts/package-media-config.mjs|scripts/prepare-package-readme.mjs|scripts/build-package-export.mjs|README.md|CHANGELOG.md|CONTRIBUTING.md|LICENSE.md|NOTICE|SECURITY.md|SUPPORT.md|TRADEMARKS.md|VERSION|package.json|package-lock.json|tsconfig.json|.gitignore)
       ;;
     docs/*)
       report "non-asset docs file is not allowed: $path"
@@ -26,7 +27,7 @@ while IFS= read -r path; do
     scripts/test-*|scripts/sync-from-live.sh)
       report "internal script is not allowed: $path"
       ;;
-    .github/*|AGENTS.md|.factory/*|.kilo/*|.cursor/*)
+    .github/*|AGENTS.md|CLAUDE.md|.factory/*|.kilo/*|.cursor/*)
       report "internal path is not allowed: $path"
       ;;
     *auth.json|*settings.json|*workflow-settings.json|*active.json|workflows/*|*sessions/*|*missions/*|*plans/*|*logs/*|*.env|*.env.*|*.DS_Store)

package/scripts/check-package-media.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { packageMediaBaseUrl, packageMediaUrls, packageMediaVersion } from './package-media-config.mjs';
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, '..');
+const packageJson = JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8'));
+
+const forbiddenNeedles = [
+  '@mediadatafusion/pi-workflow-suite@0.0.6/docs/assets',
+  'raw.githubusercontent.com/MediaDataFusion/pi-workflow-suite/v0.0.12/docs/assets',
+];
+
+const expectedPiManifest = {
+  extensions: ['./extensions/workflow-modes.ts', './extensions/subagent/index.ts'],
+  skills: ['./skills'],
+  prompts: ['./config/prompts', '!*.md'],
+  themes: ['./themes'],
+};
+
+const requiredPackageFiles = [
+  'extensions/',
+  'skills/',
+  'config/',
+  'themes/',
+  'scripts/check-package-media.mjs',
+  'scripts/package-media-config.mjs',
+  'scripts/prepare-package-readme.mjs',
+  'scripts/build-package-export.mjs',
+  'README.md',
+  'package-lock.json',
+];
+
+function assert(condition, message) {
+  if (!condition) {
+    console.error(`ERROR: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+function assertArrayEquals(actual, expected, label) {
+  assert(Array.isArray(actual), `package.json ${label} must be an array`);
+  if (!Array.isArray(actual)) return;
+  const sameLength = actual.length === expected.length;
+  const sameEntries = expected.every((entry, index) => actual[index] === entry);
+  assert(sameLength && sameEntries, `package.json ${label} changed from expected manifest surface`);
+}
+
+assertArrayEquals(packageJson.pi?.extensions, expectedPiManifest.extensions, 'pi.extensions');
+assertArrayEquals(packageJson.pi?.skills, expectedPiManifest.skills, 'pi.skills');
+assertArrayEquals(packageJson.pi?.prompts, expectedPiManifest.prompts, 'pi.prompts');
+assertArrayEquals(packageJson.pi?.themes, expectedPiManifest.themes, 'pi.themes');
+assert(packageJson.pi?.image === packageMediaUrls.header, 'package.json pi.image does not match package media config');
+assert(packageJson.pi?.video === packageMediaUrls.demoMp4, 'package.json pi.video does not match package media config');
+assert(packageJson.pi?.video?.endsWith('.mp4'), 'package.json pi.video must be an MP4 URL');
+assert(packageJson.pi?.image?.match(/\.(png|jpg|jpeg|webp|gif)$/), 'package.json pi.image must be an image URL');
+assert(
+  packageMediaBaseUrl ===
+    `https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@${packageMediaVersion}/docs/assets`,
+  'package media must use the established jsDelivr npm CDN media base',
+);
+
+for (const requiredFile of requiredPackageFiles) {
+  assert(packageJson.files?.includes(requiredFile), `package.json files must include ${requiredFile}`);
+}
+assert(!packageJson.files?.includes('docs/assets/'), 'package.json files must not include docs/assets/');
+
+const packageJsonText = JSON.stringify(packageJson);
+for (const needle of forbiddenNeedles) {
+  assert(!packageJsonText.includes(needle), `package.json still contains forbidden media URL ${needle}`);
+}
+
+assert(packageJsonText.includes(packageMediaBaseUrl), 'package.json does not contain the package media base URL');
+
+if (process.exitCode) process.exit(process.exitCode);
+console.log(`OK: package media points to ${packageMediaBaseUrl}`);

package/scripts/install-to-live.sh

@@ -72,6 +72,7 @@ install_dir() {
     ! -name '.DS_Store' \
     ! -name '*.log' \
     ! -name '*.tmp' \
+    ! -name '*.bak' \
     ! -name '*.backup.*' \
     ! -name '*.broken.*' \
     -print0)
@@ -79,6 +80,7 @@ install_dir() {
 
 atomic_install_file "package.json"
 atomic_install_file "package-lock.json"
+atomic_install_file "VERSION"
 install_dir "extensions"
 install_dir "agents"
 install_dir "skills"

package/scripts/package-media-config.mjs

@@ -0,0 +1,28 @@
+export const packageMediaVersion = '0.0.12';
+
+export const packageMediaBaseUrl =
+  `https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@${packageMediaVersion}/docs/assets`;
+
+export function packageMediaUrl(assetPath) {
+  const normalizedPath = assetPath.replace(/^docs\/assets\//, '').replace(/^\/+/, '');
+  return `${packageMediaBaseUrl}/${normalizedPath}`;
+}
+
+export const packageMediaUrls = {
+  header: packageMediaUrl('pi-workflow-suite-header.png'),
+  demoGif: packageMediaUrl('pi-workflow-suite-demo.gif'),
+  demoMp4: packageMediaUrl('pi-workflow-suite-demo.mp4'),
+  readmeInstall: packageMediaUrl('readme-link-install.svg'),
+  readmeQuickStart: packageMediaUrl('readme-link-quick-start.svg'),
+  readmeCommands: packageMediaUrl('readme-link-commands.svg'),
+  readmeSettings: packageMediaUrl('readme-link-settings.svg'),
+  screenshots: {
+    missionHome: packageMediaUrl('screenshots/00-mission-home.png'),
+    startupLogo: packageMediaUrl('screenshots/01-startup-Logo.png'),
+    themeSettings: packageMediaUrl('screenshots/02-theme-settings.png'),
+    globalSafetySettings: packageMediaUrl('screenshots/03-GlobalSafetySettings.png'),
+    sharedSubAgentsSettings: packageMediaUrl('screenshots/04-SharedSubAgentsSettings.png'),
+    missionMode: packageMediaUrl('screenshots/05-mission-mode.png'),
+    diagramMermaid: packageMediaUrl('screenshots/06-diagram-mermaid.png'),
+  },
+};