@primeuicom/mcp 0.1.30 → 1.1.0

package/dist/service.js

@@ -85,7 +85,9 @@ function formatHelpText(metadata = packageMetadata) {
     "  PRIMEUI_PROJECT_ROOT  Override project root used to resolve .primeui/project.json.",
     "",
     "Project config:",
-    "  .primeui/project.json must include projectId, apiKey, and targetProjectPath."
+    "  .primeui/project.json must include projectId and apiKey.",
+    "  targetProjectPath is required for file-oriented import/export flows.",
+    "  targetProjectPath is optional for the additional atomic external API tools."
   ].join("\n");
 }
 function formatInvalidHealthPathError(projectRoot, metadata = packageMetadata) {
@@ -227,8 +229,17 @@ function buildProjectRootHint() {
 var primeUiProjectConfigSchema = z2.object({
   projectId: z2.string().trim().min(1),
   apiKey: z2.string().trim().min(1),
-  targetProjectPath: z2.string().trim().regex(/^\.\/.*$/)
+  targetProjectPath: z2.string().trim().regex(/^\.\/.*$/).optional()
 }).passthrough();
+var primeUiProjectConfigWithTargetPathSchema = primeUiProjectConfigSchema.superRefine((value, ctx) => {
+  if (!value.targetProjectPath) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["targetProjectPath"],
+      message: "Required"
+    });
+  }
+});
 async function fileExists(filePath) {
   try {
     const fileStats = await stat(filePath);
@@ -263,7 +274,10 @@ async function findPrimeUiProjectConfigPath(startPath) {
   }
   return void 0;
 }
-async function readPrimeUiProjectConfig(projectConfigPath) {
+async function readPrimeUiProjectConfig(projectConfigPath, options = {
+  requireTargetProjectPath: true
+}) {
+  const requireTargetProjectPath = options.requireTargetProjectPath !== false;
   let projectConfigRaw;
   try {
     projectConfigRaw = await readFile(projectConfigPath, "utf-8");
@@ -290,7 +304,7 @@ async function readPrimeUiProjectConfig(projectConfigPath) {
       hint: buildProjectRootHint()
     });
   }
-  const parsedConfig = primeUiProjectConfigSchema.safeParse(projectConfigJson);
+  const parsedConfig = (requireTargetProjectPath ? primeUiProjectConfigWithTargetPathSchema : primeUiProjectConfigSchema).safeParse(projectConfigJson);
   if (!parsedConfig.success) {
     const details = parsedConfig.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
     throw new PrimeUiProjectConfigError({
@@ -320,10 +334,13 @@ function withConfigSourceDetails(error, context) {
     }
   });
 }
-async function loadResolvedPrimeUiProjectConfig(context) {
+async function loadResolvedPrimeUiProjectConfig(context, options) {
   try {
     const projectConfig = await readPrimeUiProjectConfig(
-      context.projectConfigPath
+      context.projectConfigPath,
+      {
+        requireTargetProjectPath: options.requireTargetProjectPath
+      }
     );
     return {
       projectRoot: context.projectRoot,
@@ -349,7 +366,9 @@ function toUniqueResolvedDirs(directories) {
 function buildPrimeUiProjectSearchRoots(options) {
   return toUniqueResolvedDirs([...options.fallbackCwds ?? [], options.cwd]);
 }
-async function resolvePrimeUiProjectConfig(options) {
+async function resolvePrimeUiProjectConfig(options, configOptions = {
+  requireTargetProjectPath: true
+}) {
   const toolProjectRoot = options.projectRootFromTool?.trim();
   if (toolProjectRoot) {
     const resolvedToolRoot = path3.resolve(toolProjectRoot);
@@ -370,11 +389,14 @@ async function resolvePrimeUiProjectConfig(options) {
         hint: buildProjectRootHint()
       });
     }
-    return loadResolvedPrimeUiProjectConfig({
-      source: "tool",
-      projectRoot: resolvedToolRoot,
-      projectConfigPath: toolProjectConfigPath
-    });
+    return loadResolvedPrimeUiProjectConfig(
+      {
+        source: "tool",
+        projectRoot: resolvedToolRoot,
+        projectConfigPath: toolProjectConfigPath
+      },
+      configOptions
+    );
   }
   const stickyProjectRoot = options.projectRootFromSticky?.trim();
   if (stickyProjectRoot) {
@@ -384,11 +406,14 @@ async function resolvePrimeUiProjectConfig(options) {
       PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH
     );
     if (await fileExists(stickyProjectConfigPath)) {
-      return loadResolvedPrimeUiProjectConfig({
-        source: "sticky",
-        projectRoot: resolvedStickyRoot,
-        projectConfigPath: stickyProjectConfigPath
-      });
+      return loadResolvedPrimeUiProjectConfig(
+        {
+          source: "sticky",
+          projectRoot: resolvedStickyRoot,
+          projectConfigPath: stickyProjectConfigPath
+        },
+        configOptions
+      );
     }
   }
   const envProjectRoot = options.projectRootFromEnv?.trim();
@@ -412,11 +437,14 @@ async function resolvePrimeUiProjectConfig(options) {
         hint: buildProjectRootHint()
       });
     }
-    return loadResolvedPrimeUiProjectConfig({
-      source: "env",
-      projectRoot: resolvedEnvRoot,
-      projectConfigPath: envProjectConfigPath
-    });
+    return loadResolvedPrimeUiProjectConfig(
+      {
+        source: "env",
+        projectRoot: resolvedEnvRoot,
+        projectConfigPath: envProjectConfigPath
+      },
+      configOptions
+    );
   }
   const searchRoots = buildPrimeUiProjectSearchRoots({
     cwd: options.cwd,
@@ -445,11 +473,14 @@ async function resolvePrimeUiProjectConfig(options) {
     });
   }
   const projectRoot = path3.dirname(path3.dirname(projectConfigPath));
-  return loadResolvedPrimeUiProjectConfig({
-    source: "search",
-    projectRoot,
-    projectConfigPath
-  });
+  return loadResolvedPrimeUiProjectConfig(
+    {
+      source: "search",
+      projectRoot,
+      projectConfigPath
+    },
+    configOptions
+  );
 }
 function resolvePrimeUiApiKeyDetails(options) {
   const envApiKey = options.apiKeyFromEnv?.trim();
@@ -465,6 +496,16 @@ function resolvePrimeUiApiKeyDetails(options) {
   };
 }
 function resolvePrimeUiTargetProjectRoot(projectRoot, projectConfig) {
+  if (!projectConfig.targetProjectPath) {
+    throw new PrimeUiProjectConfigError({
+      code: "PROJECT_CONFIG_INVALID_FORMAT",
+      message: `[primeui-mcp] invalid ${PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH} format: targetProjectPath: Required`,
+      details: {
+        projectRoot
+      },
+      hint: buildProjectRootHint()
+    });
+  }
   return path3.resolve(projectRoot, projectConfig.targetProjectPath);
 }
 async function resolvePrimeUiApiKey(options) {
@@ -562,6 +603,57 @@ var primeUiProjectPageDetailsSchema = z3.object({
   }).nullable(),
   components: z3.array(primeUiProjectPageComponentSchema).nullable()
 });
+var primeUiProjectDescriptionSchema = z3.object({
+  projectDescription: z3.string()
+});
+var primeUiPageGenerationTypeSchema = z3.enum([
+  "landing",
+  "pricing",
+  "blogIndex",
+  "blogPost",
+  "contact-us",
+  "docs",
+  "legal"
+]);
+var primeUiProjectApiWireframeStatusSchema = z3.enum(["pending", "generating", "ready", "error"]);
+var primeUiProjectApiVariantSummarySchema = z3.object({
+  id: z3.string(),
+  name: z3.string(),
+  isActive: z3.boolean(),
+  isGenerating: z3.boolean()
+});
+var primeUiProjectApiPageResourceSchema = z3.object({
+  id: z3.string(),
+  title: z3.string(),
+  slug: z3.string(),
+  pageType: primeUiPageGenerationTypeSchema,
+  isReadyToExport: z3.boolean(),
+  wireframeStatus: primeUiProjectApiWireframeStatusSchema,
+  variants: z3.array(primeUiProjectApiVariantSummarySchema)
+});
+var primeUiProjectApiPagesResponseSchema = z3.object({
+  pages: z3.array(primeUiProjectApiPageResourceSchema)
+});
+var primeUiProjectApiVariantsResponseSchema = z3.object({
+  variants: z3.array(primeUiProjectApiVariantSummarySchema)
+});
+var primeUiProjectApiVariantResourceSchema = z3.object({
+  id: z3.string(),
+  name: z3.string(),
+  isActive: z3.boolean(),
+  isGenerating: z3.boolean(),
+  components: z3.array(primeUiProjectPageComponentSchema)
+});
+var primeUiProjectApiVariantSummaryResponseSchema = z3.object({
+  variant: primeUiProjectApiVariantSummarySchema
+});
+var primeUiProjectApiVariantResponseSchema = z3.object({
+  variant: primeUiProjectApiVariantResourceSchema
+});
+var primeUiIssueReportSubmitResponseSchema = z3.object({
+  accepted: z3.literal(true),
+  ticketId: z3.string()
+});
 var primeUiExportsResponseSchema = z3.object({
   exports: z3.array(
     z3.object({
@@ -721,6 +813,75 @@ var ApiProjectDataProvider = class {
   async getProjectInfo() {
     return this.requestJson("project", primeUiProjectInfoSchema);
   }
+  async getProjectDescription() {
+    return this.requestJson(
+      "project/description",
+      primeUiProjectDescriptionSchema
+    );
+  }
+  async upsertProjectDescription(projectDescription) {
+    return this.requestJson(
+      "project/description",
+      primeUiProjectDescriptionSchema,
+      this.buildJsonRequestInit({
+        projectDescription
+      })
+    );
+  }
+  async listProjectPages() {
+    return this.requestJson(
+      "project/pages",
+      primeUiProjectApiPagesResponseSchema
+    );
+  }
+  async getProjectPage(pageId) {
+    return this.requestJson(
+      `project/pages/${encodeURIComponent(pageId)}`,
+      primeUiProjectApiPagesResponseSchema
+    );
+  }
+  async createProjectPage(input) {
+    return this.requestJson(
+      "project/pages",
+      primeUiProjectApiPagesResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
+  async listProjectPageVariants(pageId) {
+    return this.requestJson(
+      `project/pages/${encodeURIComponent(pageId)}/variants`,
+      primeUiProjectApiVariantsResponseSchema
+    );
+  }
+  async getProjectPageVariant(pageId, variantId) {
+    return this.requestJson(
+      `project/pages/${encodeURIComponent(pageId)}/variants/${encodeURIComponent(variantId)}`,
+      primeUiProjectApiVariantResponseSchema
+    );
+  }
+  async createProjectPageVariant(pageId, input) {
+    return this.requestJson(
+      `project/pages/${encodeURIComponent(pageId)}/variants`,
+      primeUiProjectApiVariantSummaryResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
+  async setProjectPageActiveVariant(pageId, variantId) {
+    return this.requestJson(
+      `project/pages/${encodeURIComponent(pageId)}/active-variant`,
+      primeUiProjectApiPagesResponseSchema,
+      this.buildJsonRequestInit({
+        variantId
+      })
+    );
+  }
+  async submitIssueReport(input) {
+    return this.requestJson(
+      "issue-reports",
+      primeUiIssueReportSubmitResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
   async getProjectPageBySlug(slug) {
     const encodedSlug = encodeURIComponent(slug);
     return this.requestJson(
@@ -790,6 +951,15 @@ var ApiProjectDataProvider = class {
   buildUrl(endpoint) {
     return buildPrimeUiApiUrl(this.apiRoot, endpoint);
   }
+  buildJsonRequestInit(payload) {
+    return {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    };
+  }
   async requestJson(endpoint, schema, requestInit = {}) {
     const apiKey = this.requireApiKey();
     const method = requestInit.method ?? "GET";
@@ -1083,9 +1253,19 @@ async function findNestedPrimeUiCandidates(rootPath) {
 }
 
 // src/health/report.ts
-function renderValue(value, fallback = "missing") {
+function renderValue(value, fallback = "not set") {
   return value?.trim() ? value : fallback;
 }
+function renderPresenceState(value) {
+  switch (value) {
+    case "set":
+      return "set";
+    case "missing":
+      return "not set";
+    case "unknown":
+      return "unknown";
+  }
+}
 function renderProjectRootComparison(comparison) {
   switch (comparison) {
     case "same":
@@ -1144,7 +1324,7 @@ function formatHealthReport(report) {
       `health input path: ${renderValue(report.runtimeContext.inputProjectRoot)}`,
       `PRIMEUI_PROJECT_ROOT: ${renderValue(report.runtimeContext.envProjectRoot)}`,
       `PRIMEUI_API_BASE_URL: ${renderValue(report.runtimeContext.envApiBaseUrl)}`,
-      `PRIMEUI_API_KEY: ${report.runtimeContext.envApiKeySet ? "set" : "missing"}`
+      `PRIMEUI_API_KEY: ${report.runtimeContext.envApiKeySet ? "set" : "not set"}`
     ]),
     "",
     formatSection("Source Resolution", [
@@ -1154,8 +1334,8 @@ function formatHealthReport(report) {
         report.sourceResolution.projectRoot.comparison
       )}`,
       `effective project root source: ${report.sourceResolution.projectRoot.effectiveSource}`,
-      `env API key: ${report.sourceResolution.apiKey.envState}`,
-      `config API key: ${report.sourceResolution.apiKey.configState}`,
+      `env API key: ${renderPresenceState(report.sourceResolution.apiKey.envState)}`,
+      `config API key: ${renderPresenceState(report.sourceResolution.apiKey.configState)}`,
       `API key comparison: ${renderApiKeyComparison(
         report.sourceResolution.apiKey.comparison
       )}`,
@@ -1545,12 +1725,12 @@ async function runHealthCheck(options) {
 }
 
 // src/services/project-sync-service.ts
-import path10 from "path";
-import { readFile as readFile4 } from "fs/promises";
+import path13 from "path";
+import { readFile as readFile7 } from "fs/promises";
 
 // src/services/page-copy-service.ts
-import { readFile as readFile3, readdir as readdir2, stat as stat5, writeFile as writeFile2 } from "fs/promises";
-import path9 from "path";
+import { readFile as readFile4, stat as stat6, writeFile as writeFile2 } from "fs/promises";
+import path10 from "path";
 
 // src/lib/import-graph.ts
 import { readFile as readFile2, stat as stat4 } from "fs/promises";
@@ -1830,20 +2010,14 @@ function buildUnifiedDiff(input) {
 ... [diff truncated]`;
 }
 
-// src/services/page-copy-service.ts
+// src/services/copy-service-shared.ts
+import { readFile as readFile3, readdir as readdir2, stat as stat5 } from "fs/promises";
+import path9 from "path";
 var DEPENDENCY_SECTIONS = [
   "dependencies",
   "devDependencies",
   "peerDependencies"
 ];
-function normalizeSlug(slug) {
-  const trimmed = slug.trim();
-  if (!trimmed || trimmed === "/") {
-    return "/";
-  }
-  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  return withLeadingSlash.replace(/\/+$/, "") || "/";
-}
 function toPosixPath(value) {
   return value.split(path9.sep).join("/");
 }
@@ -1883,11 +2057,12 @@ function parseManifest(value) {
 }
 async function resolveManifestCandidateFiles(input) {
   const result = /* @__PURE__ */ new Set();
+  const requireExisting = input.requireExisting ?? true;
   for (const rawPath of input.files) {
     const trimmed = rawPath.trim();
     if (!trimmed) {
       throw new Error(
-        `Export manifest for page "${input.pageSlug}" contains an empty file path.`
+        `Export manifest for ${input.manifestOwnerLabel} contains an empty file path.`
       );
     }
     const normalizedRelative = toPosixPath(trimmed).replace(/^\.\/+/, "");
@@ -1895,14 +2070,16 @@ async function resolveManifestCandidateFiles(input) {
     const relative = path9.relative(input.exportPath, absolutePath);
     if (relative.startsWith("..") || path9.isAbsolute(relative)) {
       throw new Error(
-        `Export manifest for page "${input.pageSlug}" contains path outside export root: ${trimmed}`
+        `Export manifest for ${input.manifestOwnerLabel} contains path outside export root: ${trimmed}`
       );
     }
-    const stats = await stat5(absolutePath).catch(() => null);
-    if (!stats?.isFile()) {
-      throw new Error(
-        `Export manifest file is missing for page "${input.pageSlug}": ${normalizedRelative}`
-      );
+    if (requireExisting) {
+      const stats = await stat5(absolutePath).catch(() => null);
+      if (!stats?.isFile()) {
+        throw new Error(
+          `Export manifest file is missing for ${input.manifestOwnerLabel}: ${normalizedRelative}`
+        );
+      }
     }
     result.add(absolutePath);
   }
@@ -1977,6 +2154,86 @@ function sortDependencySections(packageJson) {
     packageJson[section] = sorted;
   }
 }
+async function resolveDependencyRequirements(input) {
+  const exportPackageJson = await readJsonFile(
+    input.exportPackageJsonPath
+  );
+  const userPackageJson = await readJsonFile(
+    input.userPackageJsonPath
+  );
+  const missedDependencies = [];
+  const dependenciesVersionConflicts = [];
+  for (const packageName of new Set(input.requiredPackageNames)) {
+    const exportDependency = getDependencyVersion(
+      exportPackageJson,
+      packageName
+    );
+    if (!exportDependency) {
+      continue;
+    }
+    const userDependency = getDependencyVersion(userPackageJson, packageName);
+    if (!userDependency) {
+      missedDependencies.push({
+        packageName,
+        version: exportDependency.version,
+        section: exportDependency.section
+      });
+      continue;
+    }
+    if (userDependency.version !== exportDependency.version) {
+      dependenciesVersionConflicts.push({
+        packageName,
+        section: exportDependency.section,
+        exportVersion: exportDependency.version,
+        userVersion: userDependency.version
+      });
+    }
+  }
+  return {
+    missedDependencies: missedDependencies.sort(
+      (a, b) => a.packageName.localeCompare(b.packageName)
+    ),
+    dependenciesVersionConflicts: dependenciesVersionConflicts.sort(
+      (a, b) => a.packageName.localeCompare(b.packageName)
+    )
+  };
+}
+
+// src/services/runtime-guidance.ts
+var EXPORT_MANIFEST_DESCRIPTION = "Local sidecar export manifest. This is the authoritative file-level contract for the selected transfer item. Files listed per page or exportable are functionality-critical dependencies for that item.";
+var REFERENCE_EXPORT_DESCRIPTION = "Downloaded export project. Use this as the golden example for working behavior, file relationships, and integration details when the local result diverges or implementation is unclear.";
+var CONFLICT_REPORT_DESCRIPTION = "Local diff report for files that were not copied because target files already differ. These conflicts represent required imported functionality and must be reviewed before the transfer is complete.";
+function buildExportManifestArtifact(manifestPath) {
+  return {
+    kind: "export_manifest",
+    path: manifestPath,
+    description: EXPORT_MANIFEST_DESCRIPTION
+  };
+}
+function buildReferenceExportArtifact(exportPath) {
+  return {
+    kind: "reference_export",
+    path: exportPath,
+    description: REFERENCE_EXPORT_DESCRIPTION
+  };
+}
+function buildConflictReportArtifact(reportPath) {
+  return {
+    kind: "conflict_report",
+    path: reportPath,
+    description: CONFLICT_REPORT_DESCRIPTION
+  };
+}
+
+// src/services/page-copy-service.ts
+function normalizeSlug(slug) {
+  const trimmed = slug.trim();
+  if (!trimmed || trimmed === "/") {
+    return "/";
+  }
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/";
+}
 function resolveTargetFilePath(input) {
   const {
     sourceFilePath,
@@ -1990,26 +2247,46 @@ function resolveTargetFilePath(input) {
   if (sourceFilePath === sourcePagePath) {
     return targetPagePath;
   }
-  const componentsPrefix = `${sourceComponentsPath}${path9.sep}`;
+  const componentsPrefix = `${sourceComponentsPath}${path10.sep}`;
   if (sourceFilePath === sourceComponentsPath || sourceFilePath.startsWith(componentsPrefix)) {
-    const relativeToComponents = path9.relative(
+    const relativeToComponents = path10.relative(
       sourceComponentsPath,
       sourceFilePath
     );
-    return path9.join(targetComponentsPath, relativeToComponents);
+    return path10.join(targetComponentsPath, relativeToComponents);
   }
-  const relativeToExport = path9.relative(exportRoot, sourceFilePath);
-  if (relativeToExport.startsWith("..") || path9.isAbsolute(relativeToExport)) {
+  const relativeToExport = path10.relative(exportRoot, sourceFilePath);
+  if (relativeToExport.startsWith("..") || path10.isAbsolute(relativeToExport)) {
     throw new Error(`Source file is outside export root: ${sourceFilePath}`);
   }
-  return path9.join(projectRoot, relativeToExport);
+  return path10.join(projectRoot, relativeToExport);
+}
+function buildPageCopyGuidance(input) {
+  const artifacts = [
+    buildExportManifestArtifact(input.manifestPath),
+    buildReferenceExportArtifact(input.exportPath)
+  ];
+  if (input.hasFileConflicts) {
+    artifacts.push(buildConflictReportArtifact(input.reportPath));
+  }
+  const installDependenciesPrefix = input.addedDependencies.length > 0 ? "Install any newly added dependencies first. " : "";
+  let requiredActions = "Follow repository instructions for verification first. If repository rules are absent, inspect package.json scripts and run the most relevant minimal checks. Compare against the reference_export artifact only if behavior or integration looks wrong.";
+  if (input.status === "needs_review" && input.hasFileConflicts) {
+    requiredActions = "Review every file listed in the conflict_report artifact. Those conflicting files are an inseparable part of the imported page functionality and must be resolved deliberately before the transfer is complete. After resolving them, run repository-required verification and re-check after any local adaptation or refactor.";
+  } else if (input.status === "needs_review") {
+    requiredActions = "Resolve dependency version conflicts or other review blockers first, then run repository-required verification. If repository rules are absent, inspect package.json scripts and run the most relevant minimal checks. Use the reference_export artifact only when behavior diverges or local adaptation is unclear.";
+  }
+  return {
+    artifacts,
+    requiredActions: `${installDependenciesPrefix}${requiredActions}`
+  };
 }
 async function copyPageFromExport(input) {
   const normalizedOriginSlug = normalizeSlug(input.originPageSlug);
   const { exportId, exportPath } = await resolveSingleExportDirectory(
     input.exportsRoot
   );
-  const manifestPath = path9.join(
+  const manifestPath = path10.join(
     input.exportsRoot,
     `${exportId}.manifest.json`
   );
@@ -2032,13 +2309,13 @@ async function copyPageFromExport(input) {
       `Page not found in manifest for slug: ${normalizedOriginSlug}`
     );
   }
-  const sourcePagePath = path9.join(exportPath, page.pagePath);
-  const sourceComponentsPath = path9.join(exportPath, page.componentsPath);
-  const sourcePageStats = await stat5(sourcePagePath).catch(() => null);
+  const sourcePagePath = path10.join(exportPath, page.pagePath);
+  const sourceComponentsPath = path10.join(exportPath, page.componentsPath);
+  const sourcePageStats = await stat6(sourcePagePath).catch(() => null);
   if (!sourcePageStats?.isFile()) {
     throw new Error(`Source page file not found: ${sourcePagePath}`);
   }
-  const sourceComponentsStats = await stat5(sourceComponentsPath).catch(
+  const sourceComponentsStats = await stat6(sourceComponentsPath).catch(
     () => null
   );
   if (!sourceComponentsStats?.isDirectory()) {
@@ -2046,8 +2323,8 @@ async function copyPageFromExport(input) {
       `Source components folder not found: ${sourceComponentsPath}`
     );
   }
-  const targetPagePath = path9.join(input.projectRoot, page.pagePath);
-  const targetComponentsPath = path9.join(
+  const targetPagePath = path10.join(input.projectRoot, page.pagePath);
+  const targetComponentsPath = path10.join(
     input.projectRoot,
     page.componentsPath
   );
@@ -2055,7 +2332,7 @@ async function copyPageFromExport(input) {
   ensureSafeTargetPath(input.projectRoot, targetComponentsPath);
   const candidateFiles = await resolveManifestCandidateFiles({
     exportPath,
-    pageSlug: normalizedOriginSlug,
+    manifestOwnerLabel: `page "${normalizedOriginSlug}"`,
     files: page.manifest.files
   });
   const dependencyGraph = await buildImportGraph({
@@ -2078,18 +2355,18 @@ async function copyPageFromExport(input) {
       projectRoot: input.projectRoot
     });
     ensureSafeTargetPath(input.projectRoot, targetFilePath);
-    const sourceBuffer = await readFile3(sourceFilePath);
+    const sourceBuffer = await readFile4(sourceFilePath);
     const plannedSourceBuffer = sourceBuffer;
     let targetBuffer = null;
     try {
-      targetBuffer = await readFile3(targetFilePath);
+      targetBuffer = await readFile4(targetFilePath);
     } catch {
       targetBuffer = null;
     }
     const sourceRelative = toProjectRelative(exportPath, sourceFilePath);
     const targetRelative = toProjectRelative(input.projectRoot, targetFilePath);
     if (!targetBuffer) {
-      await ensureDir(path9.dirname(targetFilePath));
+      await ensureDir(path10.dirname(targetFilePath));
       await writeFile2(targetFilePath, plannedSourceBuffer);
       newFiles.push(targetRelative);
       continue;
@@ -2112,8 +2389,8 @@ async function copyPageFromExport(input) {
       isBinary
     });
   }
-  const exportPackageJsonPath = path9.join(exportPath, "package.json");
-  const userPackageJsonPath = path9.join(input.projectRoot, "package.json");
+  const exportPackageJsonPath = path10.join(exportPath, "package.json");
+  const userPackageJsonPath = path10.join(input.projectRoot, "package.json");
   if (!await fileExists2(exportPackageJsonPath)) {
     throw new Error(`Export package.json not found: ${exportPackageJsonPath}`);
   }
@@ -2182,7 +2459,7 @@ async function copyPageFromExport(input) {
     });
   }
   const copyId = createCopyId();
-  const reportPath = path9.join(
+  const reportPath = path10.join(
     input.exportsRoot,
     `${exportId}.copy-report-${copyId}.json`
   );
@@ -2220,6 +2497,14 @@ async function copyPageFromExport(input) {
       "Missing dependencies were added to package.json but are NOT installed yet. Run dependency installation manually with the package manager used by the target project."
     );
   }
+  const guidance = buildPageCopyGuidance({
+    status,
+    exportPath,
+    manifestPath,
+    reportPath,
+    hasFileConflicts,
+    addedDependencies: sortedAddedDependencies
+  });
   return {
     status,
     message: messageParts.join(" "),
@@ -2241,7 +2526,8 @@ async function copyPageFromExport(input) {
       conflictFiles: conflictFiles.length,
       addedDependencies: addedDependencies.length,
       dependenciesVersionConflicts: dependenciesVersionConflicts.length
-    }
+    },
+    guidance
   };
 }
 
@@ -2335,198 +2621,1215 @@ function buildInspectPageReport(input) {
   };
 }
 
-// src/services/project-sync-service.ts
-function buildManifestPath(exportsRoot, exportId) {
-  return path10.join(exportsRoot, `${exportId}.manifest.json`);
+// src/services/exportable-copy-service.ts
+import { readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
+import path11 from "path";
+var PACKAGE_JSON_RELATIVE_PATH = "package.json";
+var SUPPLEMENTARY_DEPENDENCY_PACKAGES = {
+  cookieBanner: ["@types/js-cookie"]
+};
+function normalizeExportableKey(value) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error("exportableKey must not be empty.");
+  }
+  return trimmed;
 }
-var ProjectSyncService = class {
-  provider;
-  projectRoot;
-  targetProjectRoot;
-  primeUiRoot;
-  tempRoot;
-  exportsRoot;
-  constructor(options) {
-    this.projectRoot = options.projectRoot;
-    this.targetProjectRoot = options.targetProjectRoot;
-    this.provider = options.provider;
-    this.primeUiRoot = path10.join(this.projectRoot, ".primeui");
-    this.tempRoot = path10.join(this.primeUiRoot, "temp");
-    this.exportsRoot = path10.join(this.tempRoot, "exports");
+function createNotAvailableResult(input) {
+  const skippedFiles = input.skippedFiles ?? [];
+  const availabilityHint = input.availabilityHint ?? (input.isReadyToExport ? "Open the PrimeUI project and regenerate the export after the shared exportable produces files successfully." : "Enable or configure this shared exportable in PrimeUI project settings first, then create and download a fresh export.");
+  return {
+    status: "not_available",
+    message: `Shared exportable "${input.exportableKey}" is not available for copy. ${availabilityHint} Details: ${input.manifestMessage}`,
+    reportPath: null,
+    exportId: input.exportId,
+    exportPath: input.exportPath,
+    exportableKey: input.exportableKey,
+    isReadyToExport: input.isReadyToExport,
+    manifestSuccess: input.manifestSuccess,
+    manifestMessage: input.manifestMessage,
+    manifestFiles: input.manifestFiles,
+    newFiles: [],
+    identicalFiles: [],
+    conflictFiles: [],
+    skippedFiles,
+    missedDependencies: [],
+    dependenciesVersionConflicts: [],
+    summary: {
+      totalManifestFiles: input.manifestFiles.length,
+      totalCandidateFiles: 0,
+      copiedFiles: 0,
+      identicalFiles: 0,
+      conflictFiles: 0,
+      skippedFiles: skippedFiles.length,
+      missedDependencies: 0,
+      dependenciesVersionConflicts: 0
+    }
+  };
+}
+function resolveSupplementaryDependencyPackages(exportableKey) {
+  return SUPPLEMENTARY_DEPENDENCY_PACKAGES[exportableKey] ?? [];
+}
+async function copyExportableFromExport(input) {
+  const normalizedExportableKey = normalizeExportableKey(input.exportableKey);
+  const { exportId, exportPath } = await resolveSingleExportDirectory(
+    input.exportsRoot
+  );
+  const manifestPath = path11.join(
+    input.exportsRoot,
+    `${exportId}.manifest.json`
+  );
+  if (!await fileExists2(manifestPath)) {
+    throw new Error(
+      `Export manifest is missing at ${manifestPath}. Run create_export and download_export to regenerate it.`
+    );
   }
-  async getProjectInfo(_context) {
-    await this.ensureTempLayout();
-    return this.provider.getProjectInfo();
+  const manifest = parseManifest(await readJsonFile(manifestPath));
+  if (manifest.export.id !== exportId) {
+    throw new Error(
+      `Manifest export id mismatch: expected ${exportId}, got ${manifest.export.id}. Re-run create_export and download_export.`
+    );
   }
-  async listExports(_context) {
-    await this.ensureTempLayout();
-    return this.provider.listExports();
+  const exportable = manifest.export.exportables.find(
+    (item) => item.key === normalizedExportableKey
+  );
+  if (!exportable) {
+    throw new Error(
+      `Shared exportable not found in manifest for key: ${normalizedExportableKey}`
+    );
   }
-  async createExport(_context) {
-    await this.ensureTempLayout();
-    const result = await this.provider.createExport();
-    const manifestPath = buildManifestPath(this.exportsRoot, result.export.id);
-    await writeUtf8(manifestPath, `${JSON.stringify(result, null, 2)}
-`);
-    return result;
+  const manifestFiles = exportable.manifest.files.map(
+    (filePath) => toPosixPath(filePath).replace(/^\.\/+/, "")
+  );
+  if (!exportable.isReadyToExport || !exportable.manifest.success || manifestFiles.length === 0) {
+    return createNotAvailableResult({
+      exportId,
+      exportPath,
+      exportableKey: normalizedExportableKey,
+      isReadyToExport: exportable.isReadyToExport,
+      manifestSuccess: exportable.manifest.success,
+      manifestMessage: exportable.manifest.message,
+      manifestFiles
+    });
   }
-  async downloadExportById(id, _context) {
-    await this.ensureTempLayout();
-    const exportsList = await this.provider.listExports();
-    const selected = exportsList.find((item) => item.id === id);
-    if (!selected) {
-      throw new Error(`Export not found: ${id}`);
-    }
-    const targetZipPath = path10.join(this.exportsRoot, `${id}.zip`);
-    const targetProjectPath = path10.join(this.exportsRoot, id);
-    const manifestPath = buildManifestPath(this.exportsRoot, id);
-    let manifest;
-    try {
-      manifest = parsePrimeUiExportManifest(
-        JSON.parse(await readFile4(manifestPath, "utf-8"))
-      );
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      throw new Error(
-        `Export manifest is required for download id "${id}". Run create_export for this export before downloading. Details: ${reason}`
-      );
-    }
-    if (manifest.export.id !== id) {
-      throw new Error(
-        `Export manifest mismatch for id "${id}". Run create_export and retry download.`
-      );
+  const skippedFiles = [];
+  const copyManagedManifestFiles = manifestFiles.filter((relativePath) => {
+    if (relativePath !== PACKAGE_JSON_RELATIVE_PATH) {
+      return true;
     }
-    await ensureDir(this.exportsRoot);
-    await this.provider.downloadExportArchive(id, targetZipPath);
-    await resetDir(targetProjectPath);
-    await extractZip(targetZipPath, targetProjectPath);
-    return {
-      exportId: id,
-      projectPath: targetProjectPath,
-      manifestPath
-    };
+    skippedFiles.push({
+      targetPath: relativePath,
+      reason: "package_json_managed_as_dependencies"
+    });
+    return false;
+  });
+  if (copyManagedManifestFiles.length === 0) {
+    return createNotAvailableResult({
+      exportId,
+      exportPath,
+      exportableKey: normalizedExportableKey,
+      isReadyToExport: exportable.isReadyToExport,
+      manifestSuccess: exportable.manifest.success,
+      manifestMessage: exportable.manifest.message,
+      manifestFiles,
+      skippedFiles,
+      availabilityHint: "No copyable files remain after filtering non-copyable manifest entries such as package.json. Adjust the PrimeUI exportable configuration and create a fresh export before retrying."
+    });
   }
-  async inspectPage(slug, _context) {
-    await this.ensureTempLayout();
-    const pageDetails = await this.provider.getProjectPageBySlug(slug);
-    const reportPayload = buildInspectPageReport(pageDetails);
-    return {
-      ...pageDetails,
-      report: reportPayload.report,
-      reportRows: reportPayload.reportRows
-    };
+  const candidateFiles = await resolveManifestCandidateFiles({
+    exportPath,
+    manifestOwnerLabel: `exportable "${normalizedExportableKey}"`,
+    files: copyManagedManifestFiles
+  });
+  const dependencyGraph = await buildImportGraph({
+    projectRoot: exportPath,
+    entryFiles: candidateFiles,
+    followInternalImports: false
+  });
+  const newFiles = [];
+  const identicalFiles = [];
+  const conflictFiles = [];
+  const conflictReportEntries = [];
+  for (const sourceFilePath of candidateFiles) {
+    const relativeToExport = path11.relative(exportPath, sourceFilePath);
+    if (relativeToExport.startsWith("..") || path11.isAbsolute(relativeToExport)) {
+      throw new Error(`Source file is outside export root: ${sourceFilePath}`);
+    }
+    const targetFilePath = path11.join(input.projectRoot, relativeToExport);
+    ensureSafeTargetPath(input.projectRoot, targetFilePath);
+    const sourceBuffer = await readFile5(sourceFilePath);
+    let targetBuffer = null;
+    try {
+      targetBuffer = await readFile5(targetFilePath);
+    } catch {
+      targetBuffer = null;
+    }
+    const sourceRelative = toProjectRelative(exportPath, sourceFilePath);
+    const targetRelative = toProjectRelative(input.projectRoot, targetFilePath);
+    if (!targetBuffer) {
+      await ensureDir(path11.dirname(targetFilePath));
+      await writeFile3(targetFilePath, sourceBuffer);
+      newFiles.push(targetRelative);
+      continue;
+    }
+    if (sourceBuffer.equals(targetBuffer)) {
+      identicalFiles.push(targetRelative);
+      continue;
+    }
+    const isBinary = isBinaryBuffer(sourceBuffer) || isBinaryBuffer(targetBuffer);
+    const diff = isBinary ? "Binary files differ." : buildUnifiedDiff({
+      oldText: targetBuffer.toString("utf-8"),
+      newText: sourceBuffer.toString("utf-8"),
+      oldLabel: `user/${targetRelative}`,
+      newLabel: `export/${sourceRelative}`
+    });
+    conflictReportEntries.push({
+      sourcePath: sourceRelative,
+      targetPath: targetRelative,
+      diff,
+      isBinary
+    });
   }
-  async copyPage(originPageSlug, _context) {
-    await this.ensureTempLayout();
-    return copyPageFromExport({
-      projectRoot: this.targetProjectRoot,
-      exportsRoot: this.exportsRoot,
-      originPageSlug
+  const exportPackageJsonPath = path11.join(
+    exportPath,
+    PACKAGE_JSON_RELATIVE_PATH
+  );
+  const userPackageJsonPath = path11.join(
+    input.projectRoot,
+    PACKAGE_JSON_RELATIVE_PATH
+  );
+  if (!await fileExists2(exportPackageJsonPath)) {
+    throw new Error(`Export package.json not found: ${exportPackageJsonPath}`);
+  }
+  if (!await fileExists2(userPackageJsonPath)) {
+    throw new Error(`User package.json not found: ${userPackageJsonPath}`);
+  }
+  const requiredPackageNames = [
+    ...dependencyGraph.externalPackages,
+    ...resolveSupplementaryDependencyPackages(normalizedExportableKey)
+  ];
+  const { missedDependencies, dependenciesVersionConflicts } = await resolveDependencyRequirements({
+    exportPackageJsonPath,
+    userPackageJsonPath,
+    requiredPackageNames
+  });
+  const sortedConflictReportEntries = conflictReportEntries.sort(
+    (a, b) => a.targetPath.localeCompare(b.targetPath)
+  );
+  for (const entry of sortedConflictReportEntries) {
+    conflictFiles.push({
+      targetPath: entry.targetPath,
+      isBinary: entry.isBinary
     });
   }
-  async clearTemp(_context) {
-    await resetDir(this.tempRoot);
-    await ensureDir(this.exportsRoot);
+  const copyId = createCopyId();
+  const reportPath = path11.join(
+    input.exportsRoot,
+    `${exportId}.copy-exportable-report-${copyId}.json`
+  );
+  const report = {
+    reportPath,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    exportId,
+    exportableKey: normalizedExportableKey,
+    conflicts: sortedConflictReportEntries
+  };
+  await writeFile3(reportPath, `${JSON.stringify(report, null, 2)}
+`, "utf-8");
+  const hasFileConflicts = conflictFiles.length > 0;
+  const hasDependencyVersionConflicts = dependenciesVersionConflicts.length > 0;
+  const needsReview = hasFileConflicts || hasDependencyVersionConflicts;
+  const status = needsReview ? "needs_review" : "completed";
+  const messageParts = [];
+  if (hasFileConflicts) {
+    messageParts.push(
+      `Conflicts detected while copying shared exportable "${normalizedExportableKey}". Manual resolution is required before integration is complete. Review ${reportPath} for full diffs and resolve conflicts in the context of the target project behavior.`
+    );
+  } else if (hasDependencyVersionConflicts) {
+    messageParts.push(
+      `Dependency version conflicts detected for shared exportable "${normalizedExportableKey}". Manual resolution is required before integration is complete. Review ${reportPath} and dependenciesVersionConflicts in this response.`
+    );
+  } else {
+    messageParts.push(
+      `Shared exportable "${normalizedExportableKey}" copied with no file conflicts or dependency version conflicts. Review ${reportPath} for full local details if needed.`
+    );
   }
-  async ensureTempLayout() {
-    await ensureDir(this.primeUiRoot);
-    await ensureDir(this.tempRoot);
-    await ensureDir(this.exportsRoot);
+  if (missedDependencies.length > 0) {
+    messageParts.push(
+      "missedDependencies lists required packages that are a substantial and inseparable part of this exportable's functionality. They were not added or installed automatically and must be handled explicitly by the agent or user."
+    );
   }
-};
-
-// src/runtime.ts
-function defaultCreateProvider(options) {
-  return new ApiProjectDataProvider(options);
+  if (skippedFiles.length > 0) {
+    messageParts.push(
+      "package.json is never copied automatically for shared exportables. Dependency follow-up must come from missedDependencies and dependenciesVersionConflicts."
+    );
+  }
+  return {
+    status,
+    message: messageParts.join(" "),
+    reportPath,
+    exportId,
+    exportPath,
+    exportableKey: normalizedExportableKey,
+    isReadyToExport: exportable.isReadyToExport,
+    manifestSuccess: exportable.manifest.success,
+    manifestMessage: exportable.manifest.message,
+    manifestFiles,
+    newFiles,
+    identicalFiles,
+    conflictFiles,
+    skippedFiles,
+    missedDependencies,
+    dependenciesVersionConflicts,
+    summary: {
+      totalManifestFiles: manifestFiles.length,
+      totalCandidateFiles: candidateFiles.length,
+      copiedFiles: newFiles.length,
+      identicalFiles: identicalFiles.length,
+      conflictFiles: conflictFiles.length,
+      skippedFiles: skippedFiles.length,
+      missedDependencies: missedDependencies.length,
+      dependenciesVersionConflicts: dependenciesVersionConflicts.length
+    }
+  };
 }
-var LazyProjectSyncSource = class {
-  env;
-  getCwd;
-  createProvider;
-  stickyProjectRoot;
-  constructor(options = {}) {
-    this.env = options.env ?? process.env;
-    this.getCwd = options.getCwd ?? (() => process.cwd());
-    this.createProvider = options.createProvider ?? defaultCreateProvider;
+
+// src/services/component-copy-service.ts
+import { readFile as readFile6, stat as stat7, writeFile as writeFile4 } from "fs/promises";
+import path12 from "path";
+function normalizeSlug2(slug) {
+  const trimmed = slug.trim();
+  if (!trimmed || trimmed === "/") {
+    return "/";
   }
-  async withService(context, operation) {
-    const service = await this.createProjectSyncService(context);
-    return operation(service);
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/";
+}
+function normalizeRequiredValue(value, label) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`${label} must not be empty.`);
   }
-  async withMutationService(context, operation) {
-    const service = await this.createProjectSyncService(context);
-    return operation(service);
+  return trimmed;
+}
+function resolveTargetFilePath2(input) {
+  const {
+    sourceFilePath,
+    sourcePagePath,
+    sourceComponentsPath,
+    targetPagePath,
+    targetComponentsPath,
+    exportRoot,
+    projectRoot
+  } = input;
+  if (sourceFilePath === sourcePagePath) {
+    return targetPagePath;
   }
-  async createProjectSyncService(context) {
-    const resolvedProjectConfig = await resolvePrimeUiProjectConfig({
-      cwd: this.getCwd(),
-      projectRootFromTool: context?.projectRoot,
-      projectRootFromSticky: this.stickyProjectRoot,
-      projectRootFromEnv: this.env.PRIMEUI_PROJECT_ROOT
-    });
-    const projectRoot = resolvedProjectConfig.projectRoot;
-    const targetProjectRoot = resolvePrimeUiTargetProjectRoot(
-      projectRoot,
-      resolvedProjectConfig.projectConfig
+  const componentsPrefix = `${sourceComponentsPath}${path12.sep}`;
+  if (sourceFilePath === sourceComponentsPath || sourceFilePath.startsWith(componentsPrefix)) {
+    const relativeToComponents = path12.relative(
+      sourceComponentsPath,
+      sourceFilePath
     );
-    const apiKey = await resolvePrimeUiApiKey({
-      projectConfig: resolvedProjectConfig.projectConfig,
-      apiKeyFromEnv: this.env.PRIMEUI_API_KEY
-    });
-    this.stickyProjectRoot = projectRoot;
-    const provider = this.createProvider({
-      apiKey,
-      baseUrl: this.env.PRIMEUI_API_BASE_URL
-    });
-    return new ProjectSyncService({
-      projectRoot,
-      targetProjectRoot,
-      provider
-    });
+    return path12.join(targetComponentsPath, relativeToComponents);
   }
-  async getProjectInfo(context) {
-    return this.withService(
-      context,
-      (service) => service.getProjectInfo(context)
+  const relativeToExport = path12.relative(exportRoot, sourceFilePath);
+  if (relativeToExport.startsWith("..") || path12.isAbsolute(relativeToExport)) {
+    throw new Error(`Source file is outside export root: ${sourceFilePath}`);
+  }
+  return path12.join(projectRoot, relativeToExport);
+}
+function buildContentKey(componentId, occurrenceIndex) {
+  return occurrenceIndex === 1 ? componentId : `${componentId}-${occurrenceIndex}`;
+}
+function resolveSelectedBlock(input) {
+  const { components } = input.pageDetails;
+  if (components === null) {
+    throw new Error(
+      `Components are unavailable for page "${input.pageDetails.page.slug}" because no active variant is set.`
     );
   }
-  async listExports(context) {
-    return this.withService(context, (service) => service.listExports(context));
+  let occurrenceIndex = 0;
+  for (const component of components) {
+    if (component.componentId !== input.componentId) {
+      continue;
+    }
+    occurrenceIndex += 1;
+    if (component.blockId !== input.blockId) {
+      continue;
+    }
+    return {
+      blockId: component.blockId,
+      componentId: component.componentId,
+      slot: component.slot,
+      props: component.props,
+      occurrenceIndex,
+      contentKey: buildContentKey(component.componentId, occurrenceIndex)
+    };
   }
-  async createExport(context) {
-    return this.withService(
-      context,
-      (service) => service.createExport(context)
-    );
+  throw new Error(
+    `Block not found for page "${input.pageDetails.page.slug}" using blockId "${input.blockId}" and componentId "${input.componentId}". Run inspect_page and confirm the selected block instance.`
+  );
+}
+async function createConflictReportEntry(input) {
+  const sourceBuffer = await readFile6(input.sourceFilePath);
+  let targetBuffer = null;
+  try {
+    targetBuffer = await readFile6(input.targetFilePath);
+  } catch {
+    targetBuffer = null;
   }
-  async downloadExportById(id, context) {
-    return this.withService(
-      context,
-      (service) => service.downloadExportById(id, context)
-    );
+  if (!targetBuffer || sourceBuffer.equals(targetBuffer)) {
+    return null;
   }
-  async inspectPage(slug, context) {
-    return this.withService(
-      context,
-      (service) => service.inspectPage(slug, context)
-    );
+  const sourceRelative = toProjectRelative(
+    input.exportPath,
+    input.sourceFilePath
+  );
+  const targetRelative = toProjectRelative(
+    input.projectRoot,
+    input.targetFilePath
+  );
+  const isBinary = isBinaryBuffer(sourceBuffer) || isBinaryBuffer(targetBuffer);
+  return {
+    sourcePath: sourceRelative,
+    targetPath: targetRelative,
+    diff: isBinary ? "Binary files differ." : buildUnifiedDiff({
+      oldText: targetBuffer.toString("utf-8"),
+      newText: sourceBuffer.toString("utf-8"),
+      oldLabel: `user/${targetRelative}`,
+      newLabel: `export/${sourceRelative}`
+    }),
+    isBinary
+  };
+}
+async function applyDependencyRequirements(input) {
+  const exportPackageJsonPath = path12.join(input.exportPath, "package.json");
+  const userPackageJsonPath = path12.join(input.projectRoot, "package.json");
+  if (!await fileExists2(exportPackageJsonPath)) {
+    throw new Error(`Export package.json not found: ${exportPackageJsonPath}`);
   }
-  async copyPage(originPageSlug, context) {
-    return this.withMutationService(
-      context,
-      (service) => service.copyPage(originPageSlug, context)
-    );
+  if (!await fileExists2(userPackageJsonPath)) {
+    throw new Error(`User package.json not found: ${userPackageJsonPath}`);
   }
-  async clearTemp(context) {
-    return this.withMutationService(
-      context,
-      (service) => service.clearTemp(context)
+  const exportPackageJson = await readJsonFile(
+    exportPackageJsonPath
+  );
+  const userPackageJson = await readJsonFile(userPackageJsonPath);
+  const addedDependencies = [];
+  const dependenciesVersionConflicts = [];
+  for (const packageName of new Set(input.requiredPackageNames)) {
+    const exportDependency = getDependencyVersion(
+      exportPackageJson,
+      packageName
     );
-  }
-};
-
-// src/server.ts
+    if (!exportDependency) {
+      continue;
+    }
+    const userDependency = getDependencyVersion(userPackageJson, packageName);
+    if (!userDependency) {
+      const sectionData = getOrCreateDependencySection(
+        userPackageJson,
+        exportDependency.section
+      );
+      sectionData[packageName] = exportDependency.version;
+      addedDependencies.push({
+        packageName,
+        version: exportDependency.version,
+        section: exportDependency.section
+      });
+      continue;
+    }
+    if (userDependency.version !== exportDependency.version) {
+      dependenciesVersionConflicts.push({
+        packageName,
+        section: exportDependency.section,
+        exportVersion: exportDependency.version,
+        userVersion: userDependency.version
+      });
+    }
+  }
+  if (addedDependencies.length > 0) {
+    sortDependencySections(userPackageJson);
+    await writeFile4(
+      userPackageJsonPath,
+      `${JSON.stringify(userPackageJson, null, 2)}
+`,
+      "utf-8"
+    );
+  }
+  return {
+    addedDependencies: addedDependencies.sort(
+      (a, b) => a.packageName.localeCompare(b.packageName)
+    ),
+    dependenciesVersionConflicts: dependenciesVersionConflicts.sort(
+      (a, b) => a.packageName.localeCompare(b.packageName)
+    )
+  };
+}
+function buildGuidance(input) {
+  const requiredActions = [
+    `Use selectedBlock.props as the exact prop payload for block "${input.selectedBlock.blockId}" and contentKey "${input.selectedBlock.contentKey}".`,
+    `Review manualInsertionTargets and wire the selected component instance into: ${input.manualInsertionTargets.join(", ")}.`,
+    input.potentialDependencyFiles.length > 0 ? "Review potentialDependencyFiles first if the imported component is incomplete, because they are the most likely supporting files." : "If the imported component is incomplete, compare the page file against the downloaded export before touching unrelated files.",
+    input.primaryComponentResolved ? "If behavior is incorrect, compare the local files against the downloaded reference export using exportPath." : "Resolve the canonical component file manually from the downloaded reference export before continuing integration."
+  ];
+  if (input.addedDependencies.length > 0) {
+    requiredActions.push(
+      "Install the newly added dependencies before running the copied component locally."
+    );
+  }
+  if (input.dependenciesVersionConflicts.length > 0) {
+    requiredActions.push(
+      "Resolve the reported dependency version conflicts before treating the transfer as complete."
+    );
+  }
+  if (input.missingManifestFiles.length > 0) {
+    requiredActions.push(
+      "Restore the missing export files referenced by the manifest before treating the transfer as complete."
+    );
+  }
+  const notes = [
+    "copy_component copies only the canonical component file when it can resolve that file reliably.",
+    "potentialDependencyFiles and potentialConflictFiles are hints, not mandatory full-page merge instructions."
+  ];
+  if (input.potentialConflictFiles.length > 0) {
+    notes.push(
+      "potentialConflictFiles mark related files that already differ locally and may matter only if behavior diverges after integration."
+    );
+  }
+  return {
+    requiredActions,
+    notes
+  };
+}
+async function copyComponentFromExport(input) {
+  const normalizedOriginSlug = normalizeSlug2(input.originPageSlug);
+  const normalizedBlockId = normalizeRequiredValue(input.blockId, "blockId");
+  const normalizedComponentId = normalizeRequiredValue(
+    input.componentId,
+    "componentId"
+  );
+  const { exportId, exportPath } = await resolveSingleExportDirectory(
+    input.exportsRoot
+  );
+  const manifestPath = path12.join(
+    input.exportsRoot,
+    `${exportId}.manifest.json`
+  );
+  if (!await fileExists2(manifestPath)) {
+    throw new Error(
+      `Export manifest is missing at ${manifestPath}. Run create_export and download_export to regenerate it.`
+    );
+  }
+  const manifest = parseManifest(await readJsonFile(manifestPath));
+  if (manifest.export.id !== exportId) {
+    throw new Error(
+      `Manifest export id mismatch: expected ${exportId}, got ${manifest.export.id}. Re-run create_export and download_export.`
+    );
+  }
+  const page = manifest.pages.find(
+    (item) => normalizeSlug2(item.slug) === normalizedOriginSlug
+  );
+  if (!page) {
+    throw new Error(
+      `Page not found in manifest for slug: ${normalizedOriginSlug}`
+    );
+  }
+  const candidateFiles = await resolveManifestCandidateFiles({
+    exportPath,
+    manifestOwnerLabel: `page "${normalizedOriginSlug}"`,
+    files: page.manifest.files,
+    requireExisting: false
+  });
+  const selectedBlock = resolveSelectedBlock({
+    pageDetails: input.pageDetails,
+    blockId: normalizedBlockId,
+    componentId: normalizedComponentId
+  });
+  const sourcePagePath = path12.join(exportPath, page.pagePath);
+  const sourceComponentsPath = path12.join(exportPath, page.componentsPath);
+  const targetPagePath = path12.join(input.projectRoot, page.pagePath);
+  const targetComponentsPath = path12.join(
+    input.projectRoot,
+    page.componentsPath
+  );
+  ensureSafeTargetPath(input.projectRoot, targetPagePath);
+  ensureSafeTargetPath(input.projectRoot, targetComponentsPath);
+  const manualInsertionTargets = [
+    toProjectRelative(input.projectRoot, targetPagePath)
+  ];
+  const primarySourceCandidates = [
+    toPosixPath(path12.join(page.componentsPath, `${normalizedComponentId}.tsx`)),
+    toPosixPath(
+      path12.join(page.componentsPath, normalizedComponentId, "index.tsx")
+    )
+  ];
+  const primaryCandidateTargetPaths = /* @__PURE__ */ new Set();
+  let primaryComponentFile = null;
+  let resolvedPrimarySourcePath = null;
+  for (const sourceRelativePath of primarySourceCandidates) {
+    const sourceCandidatePath = path12.join(exportPath, sourceRelativePath);
+    const targetCandidatePath = resolveTargetFilePath2({
+      sourceFilePath: sourceCandidatePath,
+      sourcePagePath,
+      sourceComponentsPath,
+      targetPagePath,
+      targetComponentsPath,
+      exportRoot: exportPath,
+      projectRoot: input.projectRoot
+    });
+    ensureSafeTargetPath(input.projectRoot, targetCandidatePath);
+    primaryCandidateTargetPaths.add(
+      toProjectRelative(input.projectRoot, targetCandidatePath)
+    );
+    const stats = await stat7(sourceCandidatePath).catch(() => null);
+    if (!stats?.isFile()) {
+      continue;
+    }
+    if (!resolvedPrimarySourcePath) {
+      resolvedPrimarySourcePath = sourceCandidatePath;
+      primaryComponentFile = toProjectRelative(
+        input.projectRoot,
+        targetCandidatePath
+      );
+    }
+  }
+  const newFiles = [];
+  const identicalFiles = [];
+  const conflictFiles = [];
+  const actualConflicts = [];
+  const missingManifestFiles = /* @__PURE__ */ new Set();
+  if (resolvedPrimarySourcePath && primaryComponentFile) {
+    const targetPrimaryPath = path12.join(
+      input.projectRoot,
+      primaryComponentFile
+    );
+    ensureSafeTargetPath(input.projectRoot, targetPrimaryPath);
+    const sourceBuffer = await readFile6(resolvedPrimarySourcePath);
+    let targetBuffer = null;
+    try {
+      targetBuffer = await readFile6(targetPrimaryPath);
+    } catch {
+      targetBuffer = null;
+    }
+    if (!targetBuffer) {
+      await ensureDir(path12.dirname(targetPrimaryPath));
+      await writeFile4(targetPrimaryPath, sourceBuffer);
+      newFiles.push(primaryComponentFile);
+    } else if (sourceBuffer.equals(targetBuffer)) {
+      identicalFiles.push(primaryComponentFile);
+    } else {
+      const entry = await createConflictReportEntry({
+        sourceFilePath: resolvedPrimarySourcePath,
+        targetFilePath: targetPrimaryPath,
+        exportPath,
+        projectRoot: input.projectRoot
+      });
+      if (entry) {
+        actualConflicts.push(entry);
+      }
+    }
+  }
+  const dependencyGraph = resolvedPrimarySourcePath ? await buildImportGraph({
+    projectRoot: exportPath,
+    entryFiles: [resolvedPrimarySourcePath]
+  }) : { externalPackages: [] };
+  const { addedDependencies, dependenciesVersionConflicts } = resolvedPrimarySourcePath ? await applyDependencyRequirements({
+    exportPath,
+    projectRoot: input.projectRoot,
+    requiredPackageNames: dependencyGraph.externalPackages
+  }) : {
+    addedDependencies: [],
+    dependenciesVersionConflicts: []
+  };
+  const potentialDependencyTargets = /* @__PURE__ */ new Set();
+  const potentialConflictEntries = /* @__PURE__ */ new Map();
+  for (const sourceFilePath of candidateFiles) {
+    const targetFilePath = resolveTargetFilePath2({
+      sourceFilePath,
+      sourcePagePath,
+      sourceComponentsPath,
+      targetPagePath,
+      targetComponentsPath,
+      exportRoot: exportPath,
+      projectRoot: input.projectRoot
+    });
+    ensureSafeTargetPath(input.projectRoot, targetFilePath);
+    const targetRelative = toProjectRelative(input.projectRoot, targetFilePath);
+    const sourceRelative = toProjectRelative(exportPath, sourceFilePath);
+    const sourceExists = await fileExists2(sourceFilePath);
+    if (!sourceExists) {
+      missingManifestFiles.add(sourceRelative);
+      continue;
+    }
+    if (manualInsertionTargets.includes(targetRelative) || primaryCandidateTargetPaths.has(targetRelative)) {
+      continue;
+    }
+    potentialDependencyTargets.add(targetRelative);
+    const targetExists = await fileExists2(targetFilePath);
+    if (!targetExists) {
+      continue;
+    }
+    const entry = await createConflictReportEntry({
+      sourceFilePath,
+      targetFilePath,
+      exportPath,
+      projectRoot: input.projectRoot
+    });
+    if (entry) {
+      potentialConflictEntries.set(targetRelative, entry);
+    }
+  }
+  const sortedActualConflicts = actualConflicts.sort(
+    (a, b) => a.targetPath.localeCompare(b.targetPath)
+  );
+  for (const entry of sortedActualConflicts) {
+    conflictFiles.push({
+      targetPath: entry.targetPath,
+      isBinary: entry.isBinary
+    });
+  }
+  const sortedPotentialConflictEntries = [
+    ...potentialConflictEntries.values()
+  ].sort((a, b) => a.targetPath.localeCompare(b.targetPath));
+  const potentialDependencyFiles = [...potentialDependencyTargets].sort(
+    (a, b) => a.localeCompare(b)
+  );
+  const potentialConflictFiles = sortedPotentialConflictEntries.map(
+    (entry) => entry.targetPath
+  );
+  const copyId = createCopyId();
+  const reportPath = path12.join(
+    input.exportsRoot,
+    `${exportId}.copy-component-report-${copyId}.json`
+  );
+  const report = {
+    reportPath,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    exportId,
+    originPageSlug: normalizedOriginSlug,
+    blockId: normalizedBlockId,
+    componentId: normalizedComponentId,
+    primaryComponentCandidates: primarySourceCandidates,
+    primaryComponentFile,
+    manualInsertionTargets,
+    potentialDependencyFiles,
+    actualConflicts: sortedActualConflicts,
+    potentialConflicts: sortedPotentialConflictEntries,
+    selectedBlock
+  };
+  await writeFile4(reportPath, `${JSON.stringify(report, null, 2)}
+`, "utf-8");
+  const needsReview = !primaryComponentFile || conflictFiles.length > 0 || dependenciesVersionConflicts.length > 0 || missingManifestFiles.size > 0;
+  const missingManifestFileList = [...missingManifestFiles].sort(
+    (a, b) => a.localeCompare(b)
+  );
+  const guidance = buildGuidance({
+    selectedBlock,
+    manualInsertionTargets,
+    potentialDependencyFiles,
+    potentialConflictFiles,
+    primaryComponentResolved: Boolean(primaryComponentFile),
+    addedDependencies,
+    dependenciesVersionConflicts,
+    missingManifestFiles: missingManifestFileList
+  });
+  const messageParts = [];
+  if (!primaryComponentFile) {
+    messageParts.push(
+      `Primary component file could not be resolved for block "${normalizedBlockId}" (${normalizedComponentId}). Review ${reportPath}, inspect the downloaded export at ${exportPath}, and resolve the component file manually before continuing.`
+    );
+  } else if (conflictFiles.length > 0) {
+    messageParts.push(
+      `Primary component file conflicts with an existing local file. Review ${reportPath} for the exact diff before completing block-level transfer.`
+    );
+  } else if (newFiles.length > 0) {
+    messageParts.push(
+      `Primary component file copied successfully with no direct conflicts. Review ${reportPath} for local details if needed.`
+    );
+  } else {
+    messageParts.push(
+      `Primary component file already exists and is byte-identical. Review ${reportPath} for local details if needed.`
+    );
+  }
+  if (missingManifestFileList.length > 0) {
+    messageParts.push(
+      `Referenced export files are missing: ${missingManifestFileList.join(", ")}. Review ${reportPath} and restore the missing files before treating this transfer as complete.`
+    );
+  }
+  if (addedDependencies.length > 0) {
+    messageParts.push(
+      "Missing dependencies were added to package.json but are NOT installed yet. Run dependency installation manually with the package manager used by the target project."
+    );
+  }
+  if (dependenciesVersionConflicts.length > 0) {
+    messageParts.push(
+      `Dependency version conflicts detected. Manual resolution is required before continuing block-level integration. Review ${reportPath} for full local details.`
+    );
+  }
+  messageParts.push(
+    `Use selectedBlock.props with contentKey "${selectedBlock.contentKey}" for the chosen block instance.`
+  );
+  messageParts.push(
+    `manualInsertionTargets identifies where this component usually needs to be wired: ${manualInsertionTargets.join(", ")}.`
+  );
+  if (potentialDependencyFiles.length > 0) {
+    messageParts.push(
+      "potentialDependencyFiles are prioritized hints, not mandatory full-page merge instructions. Review them first if the imported component behavior is incomplete."
+    );
+  }
+  if (potentialConflictFiles.length > 0) {
+    messageParts.push(
+      "potentialConflictFiles already differ locally. Compare them against the downloaded export only if the imported component behavior diverges."
+    );
+  }
+  return {
+    status: needsReview ? "needs_review" : "completed",
+    message: messageParts.join(" "),
+    reportPath,
+    exportId,
+    exportPath,
+    manifestPath,
+    originPageSlug: normalizedOriginSlug,
+    blockId: normalizedBlockId,
+    componentId: normalizedComponentId,
+    selectedBlock,
+    primaryComponentFile,
+    manualInsertionTargets,
+    newFiles,
+    identicalFiles,
+    conflictFiles,
+    potentialDependencyFiles,
+    potentialConflictFiles,
+    addedDependencies,
+    dependenciesVersionConflicts,
+    guidance
+  };
+}
+
+// src/services/project-sync-service.ts
+function buildManifestPath(exportsRoot, exportId) {
+  return path13.join(exportsRoot, `${exportId}.manifest.json`);
+}
+function normalizeSlug3(slug) {
+  const trimmed = slug.trim();
+  if (!trimmed || trimmed === "/") {
+    return "/";
+  }
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/";
+}
+var ProjectSyncService = class {
+  provider;
+  projectRoot;
+  targetProjectRoot;
+  primeUiRoot;
+  tempRoot;
+  exportsRoot;
+  pageDetailsBySlug;
+  constructor(options) {
+    this.projectRoot = options.projectRoot;
+    this.targetProjectRoot = options.targetProjectRoot;
+    this.provider = options.provider;
+    this.pageDetailsBySlug = options.pageDetailsBySlug ?? /* @__PURE__ */ new Map();
+    this.primeUiRoot = path13.join(this.projectRoot, ".primeui");
+    this.tempRoot = path13.join(this.primeUiRoot, "temp");
+    this.exportsRoot = path13.join(this.tempRoot, "exports");
+  }
+  async getProjectInfo(_context) {
+    await this.ensureTempLayout();
+    return this.provider.getProjectInfo();
+  }
+  async getProjectDescription(_context) {
+    return this.provider.getProjectDescription();
+  }
+  async upsertProjectDescription(projectDescription, _context) {
+    return this.provider.upsertProjectDescription(projectDescription);
+  }
+  async listProjectPages(_context) {
+    return this.provider.listProjectPages();
+  }
+  async getProjectPage(pageId, _context) {
+    return this.provider.getProjectPage(pageId);
+  }
+  async createProjectPage(input, _context) {
+    return this.provider.createProjectPage(input);
+  }
+  async listProjectPageVariants(pageId, _context) {
+    return this.provider.listProjectPageVariants(pageId);
+  }
+  async getProjectPageVariant(pageId, variantId, _context) {
+    return this.provider.getProjectPageVariant(pageId, variantId);
+  }
+  async createProjectPageVariant(pageId, input, _context) {
+    return this.provider.createProjectPageVariant(pageId, input);
+  }
+  async setProjectPageActiveVariant(pageId, variantId, _context) {
+    return this.provider.setProjectPageActiveVariant(pageId, variantId);
+  }
+  async submitIssueReport(input, _context) {
+    return this.provider.submitIssueReport(input);
+  }
+  async listExports(_context) {
+    await this.ensureTempLayout();
+    return this.provider.listExports();
+  }
+  async createExport(_context) {
+    await this.ensureTempLayout();
+    const result = await this.provider.createExport();
+    const manifestPath = buildManifestPath(this.exportsRoot, result.export.id);
+    await writeUtf8(manifestPath, `${JSON.stringify(result, null, 2)}
+`);
+    return {
+      ...result,
+      guidance: {
+        artifacts: [buildExportManifestArtifact(manifestPath)],
+        requiredActions: `Call download_export with id "${result.export.id}" next before attempting any file transfer.`
+      }
+    };
+  }
+  async downloadExportById(id, _context) {
+    await this.ensureTempLayout();
+    const exportsList = await this.provider.listExports();
+    const selected = exportsList.find((item) => item.id === id);
+    if (!selected) {
+      throw new Error(`Export not found: ${id}`);
+    }
+    const targetZipPath = path13.join(this.exportsRoot, `${id}.zip`);
+    const targetProjectPath = path13.join(this.exportsRoot, id);
+    const manifestPath = buildManifestPath(this.exportsRoot, id);
+    let manifest;
+    try {
+      manifest = parsePrimeUiExportManifest(
+        JSON.parse(await readFile7(manifestPath, "utf-8"))
+      );
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Export manifest is required for download id "${id}". Run create_export for this export before downloading. Details: ${reason}`
+      );
+    }
+    if (manifest.export.id !== id) {
+      throw new Error(
+        `Export manifest mismatch for id "${id}". Run create_export and retry download.`
+      );
+    }
+    await ensureDir(this.exportsRoot);
+    await this.provider.downloadExportArchive(id, targetZipPath);
+    await resetDir(targetProjectPath);
+    await extractZip(targetZipPath, targetProjectPath);
+    return {
+      exportId: id,
+      projectPath: targetProjectPath,
+      manifestPath,
+      guidance: {
+        artifacts: [
+          buildReferenceExportArtifact(targetProjectPath),
+          buildExportManifestArtifact(manifestPath)
+        ],
+        requiredActions: "Use the export_manifest artifact as the source of truth for which files belong to the selected page, component, or exportable. Use the reference_export artifact as the golden example only when behavior diverges or integration is unclear. Then choose copy_page for full pages, copy_component for one selected block instance, or copy_exportable for shared exportables based on user intent."
+      }
+    };
+  }
+  async inspectPage(slug, _context) {
+    await this.ensureTempLayout();
+    const pageDetails = await this.provider.getProjectPageBySlug(slug);
+    const reportPayload = buildInspectPageReport(pageDetails);
+    this.pageDetailsBySlug.set(normalizeSlug3(slug), pageDetails);
+    return {
+      ...pageDetails,
+      report: reportPayload.report,
+      reportRows: reportPayload.reportRows
+    };
+  }
+  async copyPage(originPageSlug, _context) {
+    await this.ensureTempLayout();
+    return copyPageFromExport({
+      projectRoot: this.targetProjectRoot,
+      exportsRoot: this.exportsRoot,
+      originPageSlug
+    });
+  }
+  async copyComponent(originPageSlug, blockId, componentId, _context) {
+    await this.ensureTempLayout();
+    const normalizedOriginSlug = normalizeSlug3(originPageSlug);
+    const cachedPageDetails = this.pageDetailsBySlug.get(normalizedOriginSlug);
+    const pageDetails = cachedPageDetails ?? await this.provider.getProjectPageBySlug(originPageSlug);
+    if (!cachedPageDetails) {
+      this.pageDetailsBySlug.set(normalizedOriginSlug, pageDetails);
+    }
+    return copyComponentFromExport({
+      projectRoot: this.targetProjectRoot,
+      exportsRoot: this.exportsRoot,
+      originPageSlug,
+      blockId,
+      componentId,
+      pageDetails
+    });
+  }
+  async copyExportable(exportableKey, _context) {
+    await this.ensureTempLayout();
+    return copyExportableFromExport({
+      projectRoot: this.targetProjectRoot,
+      exportsRoot: this.exportsRoot,
+      exportableKey
+    });
+  }
+  async clearTemp(_context) {
+    await resetDir(this.tempRoot);
+    await ensureDir(this.exportsRoot);
+    this.pageDetailsBySlug.clear();
+  }
+  async ensureTempLayout() {
+    await ensureDir(this.primeUiRoot);
+    await ensureDir(this.tempRoot);
+    await ensureDir(this.exportsRoot);
+  }
+};
+
+// src/runtime.ts
+function defaultCreateProvider(options) {
+  return new ApiProjectDataProvider(options);
+}
+function normalizeSlug4(slug) {
+  const trimmed = slug.trim();
+  if (!trimmed || trimmed === "/") {
+    return "/";
+  }
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/";
+}
+var LazyProjectSyncSource = class {
+  env;
+  getCwd;
+  createProvider;
+  stickyProjectRoot;
+  pageDetailsBySlug = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.env = options.env ?? process.env;
+    this.getCwd = options.getCwd ?? (() => process.cwd());
+    this.createProvider = options.createProvider ?? defaultCreateProvider;
+  }
+  async withService(context, operation, options) {
+    const service = await this.createProjectSyncService(context, options);
+    return operation(service);
+  }
+  async withMutationService(context, operation, options) {
+    const service = await this.createProjectSyncService(context, options);
+    return operation(service);
+  }
+  async createProjectSyncService(context, options) {
+    const requireTargetProjectRoot = options?.requireTargetProjectRoot ?? true;
+    const resolvedProjectConfig = await resolvePrimeUiProjectConfig(
+      {
+        cwd: this.getCwd(),
+        projectRootFromTool: context?.projectRoot,
+        projectRootFromSticky: this.stickyProjectRoot,
+        projectRootFromEnv: this.env.PRIMEUI_PROJECT_ROOT
+      },
+      {
+        requireTargetProjectPath: requireTargetProjectRoot
+      }
+    );
+    const projectRoot = resolvedProjectConfig.projectRoot;
+    const targetProjectRoot = requireTargetProjectRoot ? resolvePrimeUiTargetProjectRoot(
+      projectRoot,
+      resolvedProjectConfig.projectConfig
+    ) : projectRoot;
+    const apiKey = await resolvePrimeUiApiKey({
+      projectConfig: resolvedProjectConfig.projectConfig,
+      apiKeyFromEnv: this.env.PRIMEUI_API_KEY
+    });
+    this.stickyProjectRoot = projectRoot;
+    const provider = this.createProvider({
+      apiKey,
+      baseUrl: this.env.PRIMEUI_API_BASE_URL
+    });
+    return new ProjectSyncService({
+      projectRoot,
+      targetProjectRoot,
+      provider,
+      pageDetailsBySlug: this.pageDetailsBySlug
+    });
+  }
+  async getProjectInfo(context) {
+    return this.withService(
+      context,
+      (service) => service.getProjectInfo(context)
+    );
+  }
+  async getProjectDescription(context) {
+    return this.withService(
+      context,
+      (service) => service.getProjectDescription(context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async upsertProjectDescription(projectDescription, context) {
+    return this.withMutationService(
+      context,
+      async (service) => {
+        const result = await service.upsertProjectDescription(
+          projectDescription,
+          context
+        );
+        this.pageDetailsBySlug.clear();
+        return result;
+      },
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async listProjectPages(context) {
+    return this.withService(
+      context,
+      (service) => service.listProjectPages(context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async getProjectPage(pageId, context) {
+    return this.withService(
+      context,
+      (service) => service.getProjectPage(pageId, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async createProjectPage(input, context) {
+    return this.withMutationService(
+      context,
+      async (service) => {
+        const result = await service.createProjectPage(input, context);
+        this.pageDetailsBySlug.clear();
+        return result;
+      },
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async listProjectPageVariants(pageId, context) {
+    return this.withService(
+      context,
+      (service) => service.listProjectPageVariants(pageId, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async getProjectPageVariant(pageId, variantId, context) {
+    return this.withService(
+      context,
+      (service) => service.getProjectPageVariant(pageId, variantId, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async createProjectPageVariant(pageId, input, context) {
+    return this.withMutationService(
+      context,
+      async (service) => {
+        const result = await service.createProjectPageVariant(
+          pageId,
+          input,
+          context
+        );
+        this.pageDetailsBySlug.clear();
+        return result;
+      },
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async setProjectPageActiveVariant(pageId, variantId, context) {
+    return this.withMutationService(
+      context,
+      async (service) => {
+        const result = await service.setProjectPageActiveVariant(
+          pageId,
+          variantId,
+          context
+        );
+        this.pageDetailsBySlug.clear();
+        return result;
+      },
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async submitIssueReport(input, context) {
+    return this.withMutationService(
+      context,
+      (service) => service.submitIssueReport(input, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async listExports(context) {
+    return this.withService(context, (service) => service.listExports(context));
+  }
+  async createExport(context) {
+    return this.withService(
+      context,
+      (service) => service.createExport(context)
+    );
+  }
+  async downloadExportById(id, context) {
+    return this.withService(
+      context,
+      (service) => service.downloadExportById(id, context)
+    );
+  }
+  async inspectPage(slug, context) {
+    const result = await this.withService(
+      context,
+      (service) => service.inspectPage(slug, context)
+    );
+    this.pageDetailsBySlug.set(normalizeSlug4(slug), result);
+    return result;
+  }
+  async copyPage(originPageSlug, context) {
+    return this.withMutationService(
+      context,
+      (service) => service.copyPage(originPageSlug, context)
+    );
+  }
+  async copyComponent(originPageSlug, blockId, componentId, context) {
+    return this.withMutationService(
+      context,
+      (service) => service.copyComponent(originPageSlug, blockId, componentId, context)
+    );
+  }
+  async copyExportable(exportableKey, context) {
+    return this.withMutationService(
+      context,
+      (service) => service.copyExportable(exportableKey, context)
+    );
+  }
+  async clearTemp(context) {
+    const result = await this.withMutationService(
+      context,
+      (service) => service.clearTemp(context)
+    );
+    this.pageDetailsBySlug.clear();
+    return result;
+  }
+};
+
+// src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ZodError } from "zod/v3";
 
 // src/instructions.ts
 import { z as z4 } from "zod/v3";
@@ -2632,6 +3935,45 @@ var conflictFileSchema = z4.object({
   targetPath: z4.string().describe("Relative conflict target path inside user project root."),
   isBinary: z4.boolean().describe("True if conflict comparison was treated as binary data.")
 });
+var skippedCopyFileSchema = z4.object({
+  targetPath: z4.string().describe(
+    "Relative target path intentionally not copied into user project root."
+  ),
+  reason: z4.enum(["package_json_managed_as_dependencies"]).describe(
+    "Machine-readable reason for skipping this file. package_json_managed_as_dependencies means package.json was handled as dependency guidance instead of direct file copy."
+  )
+});
+var runtimeGuidanceArtifactSchema = z4.object({
+  kind: z4.enum(["export_manifest", "reference_export", "conflict_report"]).describe(
+    "Artifact kind. export_manifest is the local sidecar manifest and authoritative file-level contract. reference_export is the downloaded export project used as the golden example when behavior diverges or integration is unclear. conflict_report is the saved local diff report for conflicting files that represent required imported functionality."
+  ),
+  path: z4.string().describe("Absolute local path to the generated or referenced artifact."),
+  description: z4.string().describe("Why this artifact matters for the current tool result.")
+});
+var runtimeGuidanceSchema = z4.object({
+  artifacts: z4.array(runtimeGuidanceArtifactSchema).describe(
+    "Concrete local artifacts produced or referenced by the tool result. Review these before continuing the import flow."
+  ),
+  requiredActions: z4.string().describe(
+    "Mandatory next-step instruction derived from the actual tool result. Follow this text before continuing the flow."
+  )
+});
+var copyComponentSelectedBlockSchema = z4.object({
+  blockId: z4.string().describe("Selected block instance identifier."),
+  componentId: z4.string().describe("Canonical component file identity from block.key."),
+  slot: z4.string().nullable().describe("Optional slot value for the selected block instance."),
+  props: z4.record(z4.unknown()).nullable().describe("Exact props payload for the selected block instance."),
+  occurrenceIndex: z4.number().describe(
+    "1-based position of this block among components with the same componentId."
+  ),
+  contentKey: z4.string().describe(
+    "Content binding key for this selected instance. First instance uses componentId, later duplicates append -2, -3, and so on."
+  )
+});
+var copyComponentGuidanceSchema = z4.object({
+  requiredActions: z4.array(z4.string()).describe("Concrete next actions for finishing component transfer."),
+  notes: z4.array(z4.string()).describe("Important semantics and caveats for this transfer result.")
+});
 var pageDetailsSchema = pageSchema.extend({
   pageInstruction: z4.string().nullable().describe(
     "Current instruction text for the active page variant. Null when no active variant is set."
@@ -2677,164 +4019,768 @@ var TRIGGER_PHRASES = [
 var WORKFLOW_SUMMARY = `
 WORKFLOW ORDER (always follow this sequence):
 1. clear_temp -> cleanup stale temp files from previous runs before starting new import flow
-2. get_project_info -> discover PrimeUI pages
+2. get_project_info -> discover PrimeUI pages and shared exportables
 3. Reconcile PrimeUI pages with local project pages/routes/paths, then confirm target pages with user
 4. inspect_page -> inspect selected page components and produce a structured comparison table
 5. create_export -> generate export snapshot and local manifest with page file lists + shared exportables
 6. download_export -> download to temp directory
-7. copy_page -> copy one page safely (repeat for each selected page)
-8. Reconcile integration points and resolve reported conflicts, if any
+7. copy_page, copy_component, or copy_exportable -> transfer one selected page, one selected block-level component, or one selected shared exportable safely
+8. Reconcile integration points, dependency follow-up, and reported conflicts
 `.trim();
 var initialInstructions = `
 PrimeUI MCP enables importing pages from PrimeUI Studio into your local project.
 
-TRIGGER EXAMPLES (semantic intent, not exact phrase matching): ${TRIGGER_PHRASES}
+TRIGGER EXAMPLES (semantic intent, not exact phrase matching): ${TRIGGER_PHRASES}
+
+${WORKFLOW_SUMMARY}
+
+ADDITIONAL CAPABILITIES:
+- PrimeUI MCP also exposes atomic external API tools for project description, project pages, page variants, active-variant selection, and issue reports.
+- These atomic tools are OPTIONAL additional capabilities for extended scenarios.
+- They are NOT part of the primary import/export workflow above.
+- Do not replace get_project_info/create_export/download_export/copy_* with the additional API tools when the user wants the standard page import/export flow.
+
+CRITICAL RULES FOR PAGE IMPORT:
+- Import is PAGE-BY-PAGE only. Never import the entire project at once.
+- Always call clear_temp at the very beginning of a new import flow to avoid stale export state.
+- After get_project_info, always compare PrimeUI pages against the user's existing local project pages before proposing imports.
+- Reconciliation report MUST include: page presence match, slug/pagePath/componentsPath path match, and proposed action per page.
+- Decision matrix:
+  - PrimeUI + local page exists -> candidate for update/review.
+  - PrimeUI exists, local missing -> import candidate.
+  - Local exists, PrimeUI missing -> custom local page, no action unless user asks.
+  - Both exist but path mismatch -> ambiguous, export + compare before deciding.
+- For targeted component-level analysis on a specific page, call inspect_page before export/copy.
+- After inspect_page returns report table, supplement that table with local project page state:
+  mark what already exists, what is missing, and what differs.
+- Before creating export, ask user which pages to add/update (specific pages or all missing pages) and keep that choice in thread context.
+- create_export response includes:
+  - page-level manifest files per page ('pages[].manifest.files'),
+  - shared exportables list ('export.exportables').
+  Mention both to user after create_export, because this is the source of truth for copy decisions.
+- The downloaded export in .primeui/temp/ contains a full standalone Next.js project.
+  Do NOT copy it wholesale.
+- After download_export, choose the copy tool based on what the user wants to transfer:
+  - copy_page for page manifests,
+  - copy_component for one selected block-level component instance,
+  - copy_exportable for shared exportables.
+- Always call copy_page, copy_component, or copy_exportable instead of manual file copy.
+- copy_page performs safe copy only:
+  - new files are copied,
+  - identical files are reported,
+  - conflicting files are NEVER overwritten and are returned with diff.
+- copy_page reads and validates files only from 'pages[].manifest.files' in local sidecar manifest.
+- copy_page may add only missing dependencies to user's package.json.
+  It never upgrades existing dependency versions and never runs dependency installation.
+- copy_component uses inspect_page block data plus downloaded export artifacts.
+  It copies only the canonical component file that can be resolved reliably for the selected componentId.
+- copy_component returns exact selected block props, occurrenceIndex, and contentKey for the chosen blockId.
+- copy_component treats manualInsertionTargets, potentialDependencyFiles, and potentialConflictFiles as review hints, not as mandatory full-page merge instructions.
+- copy_exportable reads and validates files only from 'export.exportables[].manifest.files' in local sidecar manifest.
+- copy_exportable returns status 'not_available' when the shared exportable is disabled, not configured, or currently has no copyable export files.
+- copy_exportable never copies package.json automatically.
+  Dependency follow-up is returned via 'missedDependencies' and 'dependenciesVersionConflicts' and must be handled explicitly by the agent or user.
+- After page copy operations, inspect integration points (navigation configs, link menus, route registries, page indexes).
+- If integration pattern is obvious, apply it and explicitly mark it in the report with "\u26A0 integration update".
+- If integration pattern is unclear, ask the user before editing integration files.
+`.trim();
+var toolGetProjectInfo = {
+  title: "PrimeUI Project Info",
+  description: `ENTRY POINT for all PrimeUI import operations. Always start here. Returns project metadata plus a lightweight inventory of pages and shared exportables you can reason about before export.
+
+WHEN TO USE: Call this FIRST when user wants to import, add, sync, pull, or transfer a page from PrimeUI. Intent examples (semantic intent, not exact phrase matching): ${TRIGGER_PHRASES}.
+
+AFTER CALLING:
+- Scan the user's local project to discover existing pages/routes and related page component folders.
+- Build a reconciliation report between PrimeUI and local project with action labels:
+  - Page exists in both PrimeUI and local project.
+  - Page exists in PrimeUI but not in local project -> import candidate.
+  - Page exists in local project but not in PrimeUI -> custom local page, no action by default.
+  - Page exists in both but slug/pagePath/componentsPath mapping does not match -> ambiguous, requires export-based comparison before decision.
+- If user already requested specific pages, first verify those pages exist in PrimeUI and are isReadyToExport: true.
+- If user already requested specific shared exportables, verify those exportables exist in the lightweight exportables inventory and note their readiness before create_export.
+- If any requested page is not found or not ready, report this immediately and ask for replacement page choices.
+- Ask the user which pages or shared exportables to add or update now and keep this decision in thread context.
+- Import works one page or one shared exportable at a time. Multiple transfers are allowed, but each item is handled explicitly.
+- Only after user decision is clear, proceed to create_export.
+
+${WORKFLOW_SUMMARY}`,
+  inputSchema: optionalProjectRootInputObjectSchema,
+  outputSchema: z4.object({
+    projectId: z4.string().describe(
+      "PrimeUI project identifier associated with the API key and current import session context."
+    ),
+    projectName: z4.string().describe(
+      "Human-readable PrimeUI project name for confirmations in chat."
+    ),
+    metadata: z4.record(z4.unknown()).describe(
+      "Additional project metadata from PrimeUI. May include project-description and other context fields."
+    ),
+    exportables: z4.array(projectExportableSchema).describe(
+      "Lightweight inventory of shared exportables (for example logo, cookie banner, announcement banner, theme, image assets). Use description + isReadyToExport to plan imports before create_export."
+    ),
+    pages: z4.array(pageSchema).describe(
+      "All pages visible for this project context. Filter by user request and isReadyToExport before creating export."
+    )
+  }),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolInspectPage = {
+  title: "PrimeUI Inspect Page",
+  description: `Targeted inspection tool for one PrimeUI page. Returns page details, active variant (if present), raw components payload, and a formatted report table.
+
+WHEN TO USE:
+- Call this after get_project_info when user wants component-level analysis for a specific page.
+- Use this before export/copy when user asks to compare or selectively update page sections.
+
+AFTER CALLING:
+- Use report + reportRows to present the component table:
+  Number (1-based), ComponentGroup (ComponentId), Title/Description, blockId.
+- Then supplement this table with the CURRENT local project page state:
+  what already exists, what is missing, and what differs.
+- Do not assume componentId is unique. Use blockId as the primary component instance identifier.
+
+If page has no active variant, components is null (not empty array), and report explains why.
+
+${WORKFLOW_SUMMARY}`,
+  inputSchema: {
+    projectRoot: projectRootInputSchema,
+    pageSlug: z4.string().describe(
+      "PrimeUI page slug to inspect, for example '/', '/pricing', '/docs/getting-started'."
+    )
+  },
+  outputSchema: z4.object({
+    page: pageDetailsSchema.describe(
+      "Single PrimeUI page details resolved by slug with pageInstruction."
+    ),
+    variant: pageVariantSchema,
+    components: z4.array(pageComponentSchema).nullable().describe(
+      "Raw component instances from active variant. Null when page has no active variant."
+    ),
+    report: z4.string().describe(
+      "Formatted report table generated by MCP from component payload (includes extracted title/description summary)."
+    ),
+    reportRows: z4.array(inspectPageReportRowSchema).describe(
+      "Structured report rows with 1-based numbering and extracted title/description fields."
+    )
+  }),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolListExports = {
+  title: "PrimeUI Export List",
+  description: `Auxiliary tool to list previously created exports with their IDs, statuses, and creation dates. This is NOT the starting point for page import - start with get_project_info instead.
+
+WHEN TO USE: This is an OPTIONAL helper tool, NOT part of the main import flow. Use it only when:
+- Something went wrong with an export and you need to check its status.
+- The user explicitly references a previous export by date or context.
+- You need to verify whether an export initiated via PrimeUI Studio UI has completed.
 
-${WORKFLOW_SUMMARY}
+Note: exports can be created both through create_export AND by the user directly in PrimeUI Studio UI. This tool shows all of them.
 
-CRITICAL RULES FOR PAGE IMPORT:
-- Import is PAGE-BY-PAGE only. Never import the entire project at once.
-- Always call clear_temp at the very beginning of a new import flow to avoid stale export state.
-- After get_project_info, always compare PrimeUI pages against the user's existing local project pages before proposing imports.
-- Reconciliation report MUST include: page presence match, slug/pagePath/componentsPath path match, and proposed action per page.
-- Decision matrix:
-  - PrimeUI + local page exists -> candidate for update/review.
-  - PrimeUI exists, local missing -> import candidate.
-  - Local exists, PrimeUI missing -> custom local page, no action unless user asks.
-  - Both exist but path mismatch -> ambiguous, export + compare before deciding.
-- For targeted component-level analysis on a specific page, call inspect_page before export/copy.
-- After inspect_page returns report table, supplement that table with local project page state:
-  mark what already exists, what is missing, and what differs.
-- Before creating export, ask user which pages to add/update (specific pages or all missing pages) and keep that choice in thread context.
-- create_export response includes:
-  - page-level manifest files per page ('pages[].manifest.files'),
-  - shared exportables list ('export.exportables').
-  Mention both to user after create_export, because this is the source of truth for copy decisions.
-- The downloaded export in .primeui/temp/ contains a full standalone Next.js project.
-  Do NOT copy it wholesale.
-- Always call copy_page for each confirmed page instead of manual file copy.
-- copy_page performs safe copy only:
-  - new files are copied,
-  - identical files are reported,
-  - conflicting files are NEVER overwritten and are returned with diff.
-- copy_page reads and validates files only from 'pages[].manifest.files' in local sidecar manifest.
-- copy_page may add only missing dependencies to user's package.json.
-  It never upgrades existing dependency versions and never runs dependency installation.
-- After page copy operations, inspect integration points (navigation configs, link menus, route registries, page indexes).
-- If integration pattern is obvious, apply it and explicitly mark it in the report with "\u26A0 integration update".
-- If integration pattern is unclear, ask the user before editing integration files.
-`.trim();
-var toolGetProjectInfo = {
-  title: "PrimeUI Project Info",
-  description: `ENTRY POINT for all PrimeUI import operations. Always start here. Returns project metadata plus a lightweight inventory of pages and shared exportables you can reason about before export.
+Do NOT use this tool as a substitute for create_export. Always create a fresh export unless the user explicitly asks to use a previous one.
 
-WHEN TO USE: Call this FIRST when user wants to import, add, sync, pull, or transfer a page from PrimeUI. Intent examples (semantic intent, not exact phrase matching): ${TRIGGER_PHRASES}.
+${WORKFLOW_SUMMARY}`,
+  inputSchema: optionalProjectRootInputObjectSchema,
+  outputSchema: z4.object({
+    exports: z4.array(exportItemSchema).describe(
+      "Available exports sorted by API policy. Use item.id to download a specific prior export if user asks."
+    )
+  }),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolCreateExport = {
+  title: "PrimeUI Create Export",
+  description: `Create a new export snapshot from the current PrimeUI project state and wait for completion. Returns strict export manifest payload from API, including page-level file manifests and shared exportables.
+
+WHEN TO USE: Call this AFTER the user has confirmed which pages they want to import via get_project_info. This tool is REQUIRED before download_export, unless the user explicitly and directly asked to download a specific previous export.
 
 AFTER CALLING:
-- Scan the user's local project to discover existing pages/routes and related page component folders.
-- Build a reconciliation report between PrimeUI and local project with action labels:
-  - Page exists in both PrimeUI and local project.
-  - Page exists in PrimeUI but not in local project -> import candidate.
-  - Page exists in local project but not in PrimeUI -> custom local page, no action by default.
-  - Page exists in both but slug/pagePath/componentsPath mapping does not match -> ambiguous, requires export-based comparison before decision.
-- If user already requested specific pages, first verify those pages exist in PrimeUI and are isReadyToExport: true.
-- If any requested page is not found or not ready, report this immediately and ask for replacement page choices.
-- Ask the user which pages to add or update now (specific page list or all missing pages) and keep this decision in thread context.
-- Import works per page. Multiple pages are allowed, but each page transfer is handled explicitly.
-- Only after user decision is clear, proceed to create_export.
+- Verify that all user-selected pages are present in the export result AND have isReadyToExport: true.
+- Verify that any user-selected shared exportables are present in export.exportables.
+- If path mismatch pages were flagged during project-info reconciliation, ensure they are included for deeper comparison after download.
+- If any required page is missing or not ready, report and pause for user decision before proceeding.
+- Mention that pages can later be transferred via copy_page or copy_component, and shared exportables can be transferred separately via copy_exportable.
+- Local sidecar manifest is saved to .primeui/temp/exports/[exportId].manifest.json from this API payload.
+- Use the returned export ID to call download_export.
+- If guidance is present in the result, read guidance.artifacts and follow guidance.requiredActions before continuing.
 
 ${WORKFLOW_SUMMARY}`,
   inputSchema: optionalProjectRootInputObjectSchema,
   outputSchema: z4.object({
-    projectId: z4.string().describe(
-      "PrimeUI project identifier associated with the API key and current import session context."
+    export: z4.object({
+      id: z4.string().describe(
+        "Freshly created export identifier. Use this as download_export input.id."
+      ),
+      status: exportStatusSchema,
+      createdAt: z4.string().describe("Export creation timestamp in ISO-8601 UTC format."),
+      expiresAt: z4.string().nullable().describe(
+        "Export expiration timestamp in ISO-8601 UTC format, or null when export has no explicit expiration."
+      ),
+      summary: exportSummarySchema.describe(
+        "Export run summary with total/successful/failed counters."
+      ),
+      exportables: z4.array(exportableSchema).describe(
+        "Shared exportable manifest. These entries are independent from page-level manifests."
+      )
+    }).describe("Created export summary."),
+    pages: z4.array(exportPageSchema).describe(
+      "Strict page payload associated with this export, including per-page manifest files list."
+    ),
+    guidance: runtimeGuidanceSchema.optional().describe(
+      "Mandatory runtime guidance for local artifacts created during export. Present only on successful tool results."
+    )
+  }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  }
+};
+var toolDownloadExport = {
+  title: "PrimeUI Download Export",
+  description: `Download a completed export into .primeui/temp/exports/[exportId]. Downloads and extracts the full export as a standalone Next.js project into the temp directory. This does NOT modify the user's project - files land only in .primeui/temp/.
+
+Do NOT call this as the first step. Requires export ID from create_export. Start with get_project_info instead.
+
+WHEN TO USE: Call this AFTER create_export has returned a completed export. Requires export ID from create_export so MCP can use the matching local sidecar manifest.
+
+NOTE:
+- Download of an export ID without local sidecar manifest will fail.
+- For previous exports, create a fresh export first when possible.
+
+AFTER DOWNLOAD:
+- Use manifestPath from this response as the contract for page slug/path mapping and manifest file lists in copy operations.
+- For each selected page, call copy_page with:
+  - originPageSlug (required).
+- For each selected block-level component instance, call copy_component with:
+  - originPageSlug (required),
+  - blockId (required),
+  - componentId (required).
+- For each selected shared exportable, call copy_exportable with:
+  - exportableKey (required).
+- Treat conflicts as normal and expected. If copy_page returns needs_review, stop follow-up integration and resolve manually first.
+- If copy_component returns needs_review, stop and resolve the primary-file or direct-conflict issue before continuing block-level integration.
+- If copy_exportable returns not_available, stop and tell the user the shared exportable must be enabled or configured in PrimeUI first.
+- Do not force cleanup at flow end; keep downloaded export files available for validation and follow-up checks.
+- If guidance is present in the result, read guidance.artifacts and follow guidance.requiredActions before choosing the next copy tool.
+
+  ${WORKFLOW_SUMMARY}`,
+  inputSchema: {
+    projectRoot: projectRootInputSchema,
+    id: z4.string().describe(
+      "Export identifier to download. Prefer export.id from create_export; use list_exports only on explicit user request."
+    )
+  },
+  outputSchema: z4.object({
+    exportId: z4.string().describe(
+      "Downloaded export identifier. Should match the requested input.id for traceability."
+    ),
+    projectPath: z4.string().describe(
+      "Absolute local path to extracted export root in .primeui/temp/exports/[exportId]. Read files from here only."
+    ),
+    manifestPath: z4.string().describe(
+      "Absolute path to sidecar export manifest file (.primeui/temp/exports/[exportId].manifest.json) saved by create_export and required by copy_page and copy_component."
+    ),
+    guidance: runtimeGuidanceSchema.optional().describe(
+      "Mandatory runtime guidance for the downloaded export and manifest artifacts. Present only on successful tool results."
+    )
+  }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolCopyPage = {
+  title: "PrimeUI Copy Page",
+  description: `Safely copy one page from downloaded export into the user's local project. Works only with local files in .primeui/temp/exports and does NOT call PrimeUI API.
+
+WHEN TO USE:
+- Call this AFTER download_export.
+- Call once per selected page.
+
+BEHAVIOR:
+- Reads export sidecar manifest to resolve originPageSlug -> pagePath/componentsPath.
+- Copies and validates files strictly from pages[].manifest.files for the selected page.
+- Never overwrites existing conflicting files.
+- Writes full conflict diffs to a local report file in .primeui/temp/exports/[exportId].copy-report-[copyId].json.
+- Reports:
+  a) copied new files (relative target paths),
+  b) identical existing files (relative target paths),
+  c) conflicting files as lightweight metadata (relative target paths + binary flag, no inline diff),
+  d) missing dependencies added to package.json,
+  e) dependency version conflicts (report-only, no auto upgrade).
+- Adds only missing dependencies to package.json (dependencies/devDependencies/peerDependencies).
+- Never updates existing dependency versions and never runs install commands.
+- If status is needs_review, page import is NOT complete and manual review is required before continuing. This can be caused by file conflicts or dependency version conflicts.
+- If guidance is present in the result, read guidance.artifacts and follow guidance.requiredActions before continuing integration.
+
+${WORKFLOW_SUMMARY}`,
+  inputSchema: {
+    projectRoot: projectRootInputSchema,
+    originPageSlug: z4.string().describe(
+      "Source page slug from PrimeUI project pages list, for example '/', '/pricing', '/docs'."
+    )
+  },
+  outputSchema: z4.object({
+    status: z4.enum(["completed", "needs_review"]).describe(
+      "Decision state for next step. needs_review means manual review is required before follow-up integration because of file conflicts or dependency version conflicts."
+    ),
+    message: z4.string().describe(
+      "Decision-oriented summary that includes resolved reportPath and manual follow-up instructions when needed."
+    ),
+    reportPath: z4.string().describe(
+      "Absolute path to saved local report with full conflict diffs and details."
+    ),
+    exportId: z4.string().describe("Resolved local export identifier used for copy operation."),
+    exportPath: z4.string().describe("Absolute path to local extracted export project root."),
+    originPageSlug: z4.string().describe("Normalized source page slug requested for copy."),
+    sourcePagePath: z4.string().describe("Source page path relative to export root."),
+    sourceComponentsPath: z4.string().describe("Source components directory relative to export root."),
+    newFiles: z4.array(z4.string()).describe(
+      "Relative target paths for new files copied into user project."
+    ),
+    identicalFiles: z4.array(z4.string()).describe("Relative target paths for existing byte-identical files."),
+    conflictFiles: z4.array(conflictFileSchema).describe(
+      "Files that already exist and differ from export version. Never overwritten."
+    ),
+    addedDependencies: z4.array(dependencyToAddSchema).describe(
+      "Dependencies that were missing and have been added to user's package.json."
+    ),
+    dependenciesVersionConflicts: z4.array(dependencyVersionConflictSchema).describe(
+      "Dependencies with version mismatch between export and user project. Report only."
+    ),
+    summary: z4.object({
+      totalCandidateFiles: z4.number().describe(
+        "Total number of candidate files considered for page copy from pages[].manifest.files."
+      ),
+      copiedFiles: z4.number().describe("Number of files copied as new."),
+      identicalFiles: z4.number().describe("Number of files detected as identical."),
+      conflictFiles: z4.number().describe("Number of conflicting files not copied."),
+      addedDependencies: z4.number().describe("Count of dependencies added to package.json."),
+      dependenciesVersionConflicts: z4.number().describe("Count of dependency version mismatches reported.")
+    }),
+    guidance: runtimeGuidanceSchema.optional().describe(
+      "Mandatory runtime guidance for export artifacts and next steps after this page copy result. Present only on successful tool results."
+    )
+  }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  }
+};
+var toolCopyComponent = {
+  title: "PrimeUI Copy Component",
+  description: `Safely copy one block-level component from downloaded export into the user's local project. Works only with local files in .primeui/temp/exports and uses inspect_page semantics for block selection.
+
+WHEN TO USE:
+- Call this AFTER download_export.
+- Call this when the user wants one selected block instance, not a full page transfer.
+- Pass both blockId and componentId so the tool can bind exact props for the selected instance while still resolving the canonical component file identity.
+
+BEHAVIOR:
+- Reads export sidecar manifest to resolve originPageSlug -> pagePath/componentsPath.
+- Matches the selected block from inspect_page-compatible page details using blockId + componentId.
+- Computes selectedBlock.occurrenceIndex and selectedBlock.contentKey for duplicate component types on the same page.
+- Reuses the most recent inspect_page snapshot for selected block metadata when available instead of re-fetching live page details at copy time.
+- Resolves the primary component file from downloaded export using:
+  - [componentsPath]/[componentId].tsx
+  - [componentsPath]/[componentId]/index.tsx
+- Copies only the reliably resolved primary component file.
+- Scans the selected component tree for external package imports, adds missing dependencies to package.json, and reports version conflicts.
+- Never overwrites an existing conflicting primary component file.
+- Writes full direct and potential conflict details to a local report file in .primeui/temp/exports/[exportId].copy-component-report-[copyId].json.
+- Reports:
+  a) selectedBlock with exact props for the chosen instance,
+  b) primaryComponentFile when resolved,
+  c) copied new or identical primary files,
+  d) conflictFiles only for files actually attempted during copy,
+  e) addedDependencies / dependenciesVersionConflicts for dependency follow-up,
+  f) manualInsertionTargets for likely integration points,
+  g) potentialDependencyFiles / potentialConflictFiles as prioritized hints for manual review.
+- If status is needs_review, stop and resolve the reported primary-file, missing-manifest-file, or dependency-version issue before treating the component transfer as complete.
+
+${WORKFLOW_SUMMARY}`,
+  inputSchema: {
+    projectRoot: projectRootInputSchema,
+    originPageSlug: z4.string().describe(
+      "Source page slug from PrimeUI project pages list, for example '/', '/pricing', '/docs'."
+    ),
+    blockId: z4.string().describe(
+      "Selected block instance identifier from inspect_page output. Required when the same componentId appears multiple times on one page."
+    ),
+    componentId: z4.string().describe(
+      "Selected component identity from inspect_page output (block.key). This defines the canonical component file identity."
+    )
+  },
+  outputSchema: z4.object({
+    status: z4.enum(["completed", "needs_review"]).describe(
+      "Decision state for next step. needs_review means the primary component file could not be resolved safely or directly copied without conflict."
     ),
-    projectName: z4.string().describe(
-      "Human-readable PrimeUI project name for confirmations in chat."
+    message: z4.string().describe(
+      "Decision-oriented summary with reportPath and the next manual actions for completing component transfer."
     ),
-    metadata: z4.record(z4.unknown()).describe(
-      "Additional project metadata from PrimeUI. May include project-description and other context fields."
+    reportPath: z4.string().describe(
+      "Absolute path to saved local report with direct conflicts, potential conflicts, and selected block metadata."
     ),
-    exportables: z4.array(projectExportableSchema).describe(
-      "Lightweight inventory of shared exportables (for example logo, cookie banner, announcement banner, theme, image assets). Use description + isReadyToExport to plan imports before create_export."
+    exportId: z4.string().describe("Resolved local export identifier used for component copy."),
+    exportPath: z4.string().describe("Absolute path to local extracted export project root."),
+    manifestPath: z4.string().describe(
+      "Absolute path to the local sidecar export manifest used during component copy."
     ),
-    pages: z4.array(pageSchema).describe(
-      "All pages visible for this project context. Filter by user request and isReadyToExport before creating export."
+    originPageSlug: z4.string().describe("Normalized source page slug requested for copy."),
+    blockId: z4.string().describe("Normalized selected block instance identifier."),
+    componentId: z4.string().describe("Normalized component file identity requested for copy."),
+    selectedBlock: copyComponentSelectedBlockSchema.describe(
+      "Resolved selected block instance with exact props and duplicate-instance metadata."
+    ),
+    primaryComponentFile: z4.string().nullable().describe(
+      "Relative target path for the canonical component file when resolved, otherwise null."
+    ),
+    manualInsertionTargets: z4.array(z4.string()).describe(
+      "Relative target paths that usually need manual wiring for this component instance, typically the page file."
+    ),
+    newFiles: z4.array(z4.string()).describe(
+      "Relative target paths for new files copied into user project. For copy_component this usually contains only the primary component file."
+    ),
+    identicalFiles: z4.array(z4.string()).describe(
+      "Relative target paths for existing byte-identical copied files."
+    ),
+    conflictFiles: z4.array(conflictFileSchema).describe(
+      "Files that were actually attempted during copy and already exist with different content. Never overwritten."
+    ),
+    addedDependencies: z4.array(dependencyToAddSchema).describe(
+      "Dependencies that were missing and have been added to user's package.json."
+    ),
+    dependenciesVersionConflicts: z4.array(dependencyVersionConflictSchema).describe(
+      "Dependencies with version mismatch between export and user project. Report only."
+    ),
+    potentialDependencyFiles: z4.array(z4.string()).describe(
+      "Prioritized hint files related to the selected page manifest. Review them first if the copied component is incomplete."
+    ),
+    potentialConflictFiles: z4.array(z4.string()).describe(
+      "Potential dependency files that already differ locally. These are hints only and are not treated as direct copy conflicts."
+    ),
+    guidance: copyComponentGuidanceSchema.describe(
+      "Structured follow-up guidance for completing block-level transfer with the selected props and related files."
     )
   }),
   annotations: {
-    readOnlyHint: true,
+    readOnlyHint: false,
     destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true
+    idempotentHint: false,
+    openWorldHint: false
   }
 };
-var toolInspectPage = {
-  title: "PrimeUI Inspect Page",
-  description: `Targeted inspection tool for one PrimeUI page. Returns page details, active variant (if present), raw components payload, and a formatted report table.
+var toolCopyExportable = {
+  title: "PrimeUI Copy Exportable",
+  description: `Safely copy one shared exportable from downloaded export into the user's local project. Works only with local files in .primeui/temp/exports and does NOT call PrimeUI API.
 
 WHEN TO USE:
-- Call this after get_project_info when user wants component-level analysis for a specific page.
-- Use this before export/copy when user asks to compare or selectively update page sections.
-
-AFTER CALLING:
-- Use report + reportRows to present the component table:
-  Number (1-based), ComponentGroup (ComponentId), Title/Description, blockId.
-- Then supplement this table with the CURRENT local project page state:
-  what already exists, what is missing, and what differs.
-- Do not assume componentId is unique. Use blockId as the primary component instance identifier.
+- Call this AFTER download_export.
+- Call once per selected shared exportable.
 
-If page has no active variant, components is null (not empty array), and report explains why.
+BEHAVIOR:
+- Reads export sidecar manifest to resolve exportableKey -> export.exportables[] entry.
+- Copies and validates files strictly from export.exportables[].manifest.files for the selected shared exportable.
+- Never copies package.json automatically. package.json is treated as dependency guidance only.
+- Returns status not_available when the shared exportable is disabled, not configured, or currently has no copyable export files.
+- Never overwrites existing conflicting files.
+- Writes full conflict diffs to a local report file in .primeui/temp/exports/[exportId].copy-exportable-report-[copyId].json.
+- Reports:
+  a) copied new files (relative target paths),
+  b) identical existing files (relative target paths),
+  c) conflicting files as lightweight metadata (relative target paths + binary flag, no inline diff),
+  d) skipped files such as package.json,
+  e) missedDependencies that must be handled explicitly,
+  f) dependency version conflicts (report-only, no auto upgrade).
+- missedDependencies are a substantial and inseparable part of the shared exportable functionality. They are never added or installed automatically.
+- If status is needs_review, shared exportable transfer is NOT complete and manual review is required before continuing.
 
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {
     projectRoot: projectRootInputSchema,
-    pageSlug: z4.string().describe(
-      "PrimeUI page slug to inspect, for example '/', '/pricing', '/docs/getting-started'."
+    exportableKey: z4.string().describe(
+      "Shared exportable key from PrimeUI export payload, for example 'logo', 'theme', 'cookieBanner', 'announcementBanner', or 'imageAssets'."
     )
   },
   outputSchema: z4.object({
-    page: pageDetailsSchema.describe(
-      "Single PrimeUI page details resolved by slug with pageInstruction."
+    status: z4.enum(["completed", "needs_review", "not_available"]).describe(
+      "Decision state for next step. not_available means the shared exportable must be enabled or configured in PrimeUI first. needs_review means file conflicts or dependency version conflicts require manual resolution."
     ),
-    variant: pageVariantSchema,
-    components: z4.array(pageComponentSchema).nullable().describe(
-      "Raw component instances from active variant. Null when page has no active variant."
+    message: z4.string().describe(
+      "Decision-oriented summary with resolved reportPath and mandatory follow-up guidance for availability, conflicts, or dependency handling."
     ),
-    report: z4.string().describe(
-      "Formatted report table generated by MCP from component payload (includes extracted title/description summary)."
+    reportPath: z4.string().nullable().describe(
+      "Absolute path to saved local report with full conflict diffs and details, or null when the exportable is not available for copy."
     ),
-    reportRows: z4.array(inspectPageReportRowSchema).describe(
-      "Structured report rows with 1-based numbering and extracted title/description fields."
-    )
+    exportId: z4.string().describe("Resolved local export identifier used for copy operation."),
+    exportPath: z4.string().describe("Absolute path to local extracted export project root."),
+    exportableKey: z4.string().describe("Normalized shared exportable key requested for copy."),
+    isReadyToExport: z4.boolean().describe(
+      "Readiness flag from export manifest for the selected shared exportable."
+    ),
+    manifestSuccess: z4.boolean().describe(
+      "Success flag from export manifest for the selected shared exportable."
+    ),
+    manifestMessage: z4.string().describe(
+      "Manifest message from export payload for the selected shared exportable."
+    ),
+    manifestFiles: z4.array(z4.string()).describe(
+      "Authoritative list of manifest files for this shared exportable before any copy-time filtering."
+    ),
+    newFiles: z4.array(z4.string()).describe(
+      "Relative target paths for new files copied into user project."
+    ),
+    identicalFiles: z4.array(z4.string()).describe("Relative target paths for existing byte-identical files."),
+    conflictFiles: z4.array(conflictFileSchema).describe(
+      "Files that already exist and differ from export version. Never overwritten."
+    ),
+    skippedFiles: z4.array(skippedCopyFileSchema).describe(
+      "Manifest files intentionally not copied, for example package.json which is handled via dependency guidance."
+    ),
+    missedDependencies: z4.array(dependencyToAddSchema).describe(
+      "Required packages missing in user's package.json. These are never added or installed automatically."
+    ),
+    dependenciesVersionConflicts: z4.array(dependencyVersionConflictSchema).describe(
+      "Dependencies with version mismatch between export and user project. Report only."
+    ),
+    summary: z4.object({
+      totalManifestFiles: z4.number().describe(
+        "Total number of manifest files listed for this shared exportable before copy-time filtering."
+      ),
+      totalCandidateFiles: z4.number().describe(
+        "Total number of candidate files considered for direct copy after filtering skipped files such as package.json."
+      ),
+      copiedFiles: z4.number().describe("Number of files copied as new."),
+      identicalFiles: z4.number().describe("Number of files detected as identical."),
+      conflictFiles: z4.number().describe("Number of conflicting files not copied."),
+      skippedFiles: z4.number().describe("Number of manifest files intentionally skipped."),
+      missedDependencies: z4.number().describe("Count of missing dependency packages reported."),
+      dependenciesVersionConflicts: z4.number().describe("Count of dependency version mismatches reported.")
+    })
   }),
   annotations: {
-    readOnlyHint: true,
+    readOnlyHint: false,
     destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true
+    idempotentHint: false,
+    openWorldHint: false
   }
 };
-var toolListExports = {
-  title: "PrimeUI Export List",
-  description: `Auxiliary tool to list previously created exports with their IDs, statuses, and creation dates. This is NOT the starting point for page import - start with get_project_info instead.
+var toolClearTemp = {
+  title: "PrimeUI Clear Temp",
+  description: `Delete all files in .primeui/temp/ and recreate empty temp structure.
 
-WHEN TO USE: This is an OPTIONAL helper tool, NOT part of the main import flow. Use it only when:
-- Something went wrong with an export and you need to check its status.
-- The user explicitly references a previous export by date or context.
-- You need to verify whether an export initiated via PrimeUI Studio UI has completed.
+Call this at the START of a new import flow, before get_project_info/create_export, to reset stale temp state from previous runs.
 
-Note: exports can be created both through create_export AND by the user directly in PrimeUI Studio UI. This tool shows all of them.
+WHEN TO USE: Call once at the beginning of each new import flow. Do not call this between page imports in the same flow.
 
-Do NOT use this tool as a substitute for create_export. Always create a fresh export unless the user explicitly asks to use a previous one.
+Safe to call multiple times. Only affects .primeui/temp/ directory - never touches the user's project files.
 
 ${WORKFLOW_SUMMARY}`,
   inputSchema: optionalProjectRootInputObjectSchema,
   outputSchema: z4.object({
-    exports: z4.array(exportItemSchema).describe(
-      "Available exports sorted by API policy. Use item.id to download a specific prior export if user asks."
+    success: z4.boolean().describe(
+      "True when temp cleanup completed and baseline temp structure was recreated."
     )
   }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+};
+var projectDescriptionOutputSchema = z4.object({
+  projectDescription: z4.string().describe(
+    "Current shared project description string. Empty string means the description is not set."
+  )
+});
+var projectApiWireframeStatusSchema = z4.enum(["pending", "generating", "ready", "error"]).describe(
+  "Shared page readiness status from the external API. ready means export-selected content exists; generating means background AI work is still running."
+);
+var projectApiVariantSummarySchema = z4.object({
+  id: z4.string().describe("Stable variant identifier within the scoped PrimeUI project."),
+  name: z4.string().describe("Human-readable variant name."),
+  isActive: z4.boolean().describe(
+    "True when this variant is currently selected as the page active variant for export."
+  ),
+  isGenerating: z4.boolean().describe(
+    "True when background AI generation is still running for this variant."
+  )
+});
+var pageGenerationTypeSchema = z4.enum([
+  "landing",
+  "pricing",
+  "blogIndex",
+  "blogPost",
+  "contact-us",
+  "docs",
+  "legal"
+]).describe(
+  "Supported PrimeUI page type. Must match the external API page type enum."
+);
+var projectApiPageResourceSchema = z4.object({
+  id: z4.string().describe("Stable PrimeUI page identifier."),
+  title: z4.string().describe("Human-readable page title."),
+  slug: z4.string().describe("PrimeUI route slug for the page, for example '/', '/pricing'."),
+  pageType: pageGenerationTypeSchema,
+  isReadyToExport: z4.boolean().describe(
+    "True when the page currently has an export-selected active variant."
+  ),
+  wireframeStatus: projectApiWireframeStatusSchema,
+  variants: z4.array(projectApiVariantSummarySchema).describe("Lightweight variant summaries attached to the page resource.")
+});
+var projectApiPagesOutputSchema = z4.object({
+  pages: z4.array(projectApiPageResourceSchema).describe(
+    "Project pages payload returned by the external API. GET list may include many entries; create/get/set-active responses usually return one entry."
+  )
+});
+var projectApiVariantsOutputSchema = z4.object({
+  variants: z4.array(projectApiVariantSummarySchema).describe("Variant summaries for one selected page.")
+});
+var projectApiVariantSummaryResultSchema = z4.object({
+  variant: projectApiVariantSummarySchema.describe(
+    "Variant summary returned immediately after creation."
+  )
+});
+var projectApiVariantOutputSchema = z4.object({
+  variant: z4.object({
+    id: z4.string().describe("Stable variant identifier within the selected page."),
+    name: z4.string().describe("Human-readable variant name."),
+    isActive: z4.boolean().describe("True when this variant is currently active for export."),
+    isGenerating: z4.boolean().describe(
+      "True while background AI generation for this variant is still running."
+    ),
+    components: z4.array(pageComponentSchema).describe("Resolved component payload for the selected variant.")
+  })
+});
+var issueReportSubmitOutputSchema = z4.object({
+  accepted: z4.literal(true).describe("Always true when the issue report was accepted by the API."),
+  ticketId: z4.string().describe("Generated issue report identifier returned by the API.")
+});
+var createContentModeSchema = z4.enum(["ai", "empty", "components"]).describe(
+  "Content creation mode. empty creates an empty resource, components uses ordered componentIds, ai queues generation from prompt."
+);
+var createPageOrVariantSchema = (shape) => z4.object(shape).superRefine((value, ctx) => {
+  const contentMode = value.contentMode;
+  const componentIds = value.componentIds;
+  const prompt = value.prompt;
+  if (contentMode === "ai") {
+    if (Array.isArray(componentIds) && componentIds.length > 0) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: "componentIds are not allowed in ai mode.",
+        path: ["componentIds"]
+      });
+    }
+    return;
+  }
+  if (contentMode === "empty") {
+    if (Array.isArray(componentIds) && componentIds.length > 0) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: "componentIds are not allowed in empty mode.",
+        path: ["componentIds"]
+      });
+    }
+    if (typeof prompt === "string" && prompt.trim()) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: "prompt is not allowed in empty mode.",
+        path: ["prompt"]
+      });
+    }
+    return;
+  }
+  if (!Array.isArray(componentIds) || componentIds.length === 0) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "componentIds are required in components mode.",
+      path: ["componentIds"]
+    });
+  }
+  if (typeof prompt === "string" && prompt.trim()) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "prompt is not allowed in components mode.",
+      path: ["prompt"]
+    });
+  }
+});
+var projectDescriptionUpsertInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  projectDescription: z4.string().describe(
+    "Project description to store. Empty or whitespace-only input clears the saved description."
+  )
+});
+var projectPageCreateBaseInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  slug: z4.string().describe("Route slug for the new page, for example '/pricing'."),
+  title: z4.string().describe("Human-readable page title."),
+  pageType: pageGenerationTypeSchema,
+  contentMode: createContentModeSchema,
+  componentIds: z4.array(z4.string()).optional().describe(
+    "Ordered component IDs for components mode. Omit for empty or ai mode."
+  ),
+  prompt: z4.string().optional().describe("Optional AI prompt used only in ai mode.")
+});
+var projectPageCreateValidationSchema = createPageOrVariantSchema(
+  projectPageCreateBaseInputSchema.shape
+);
+var projectPageVariantCreateBaseInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  pageId: z4.string().describe("Target page identifier for the new variant."),
+  name: z4.string().optional().describe(
+    "Optional explicit variant name. When omitted, Studio assigns one."
+  ),
+  contentMode: createContentModeSchema,
+  componentIds: z4.array(z4.string()).optional().describe(
+    "Ordered component IDs for components mode. Omit for empty or ai mode."
+  ),
+  prompt: z4.string().optional().describe("Optional AI prompt used only in ai mode.")
+});
+var projectPageVariantCreateValidationSchema = createPageOrVariantSchema(projectPageVariantCreateBaseInputSchema.shape);
+var projectIssueReportSubmitInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  reportText: z4.string().describe("Issue report text to submit for the scoped project."),
+  tags: z4.array(z4.string()).optional().describe(
+    "Optional issue report tags. Empty values are trimmed and dropped by the API."
+  )
+});
+var toolProjectDescriptionGet = {
+  title: "PrimeUI Project Description Get",
+  description: `Atomic external API helper. Returns the current shared project description for the scoped PrimeUI project.
+
+WHEN TO USE:
+- Use this when the caller needs only the project description text.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- Do not treat this as part of the page download or export flow.
+
+AFTER CALLING:
+- Use the returned projectDescription directly.
+- Empty string means the project currently has no saved description.`,
+  inputSchema: optionalProjectRootInputObjectSchema,
+  outputSchema: projectDescriptionOutputSchema,
   annotations: {
     readOnlyHint: true,
     destructiveHint: false,
@@ -2842,196 +4788,198 @@ ${WORKFLOW_SUMMARY}`,
     openWorldHint: true
   }
 };
-var toolCreateExport = {
-  title: "PrimeUI Create Export",
-  description: `Create a new export snapshot from the current PrimeUI project state and wait for completion. Returns strict export manifest payload from API, including page-level file manifests and shared exportables.
+var toolProjectDescriptionUpsert = {
+  title: "PrimeUI Project Description Upsert",
+  description: `Atomic external API helper. Creates, updates, or clears the shared project description for the scoped PrimeUI project.
 
-WHEN TO USE: Call this AFTER the user has confirmed which pages they want to import via get_project_info. This tool is REQUIRED before download_export, unless the user explicitly and directly asked to download a specific previous export.
+WHEN TO USE:
+- Use this only when the caller explicitly wants to change the shared project description.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- Whitespace-only input is valid and clears the saved description.
 
 AFTER CALLING:
-- Verify that all user-selected pages are present in the export result AND have isReadyToExport: true.
-- If path mismatch pages were flagged during project-info reconciliation, ensure they are included for deeper comparison after download.
-- If any required page is missing or not ready, report and pause for user decision before proceeding.
-- Mention that shared exportables are available in export.exportables and can be transferred separately if needed.
-- Local sidecar manifest is saved to .primeui/temp/exports/[exportId].manifest.json from this API payload.
-- Use the returned export ID to call download_export.
+- Treat the returned projectDescription as the source of truth after persistence.`,
+  inputSchema: projectDescriptionUpsertInputSchema,
+  outputSchema: projectDescriptionOutputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  }
+};
+var toolProjectPagesList = {
+  title: "PrimeUI Project Pages List",
+  description: `Atomic external API helper. Returns the current page inventory with page-level readiness and lightweight variant summaries.
 
-${WORKFLOW_SUMMARY}`,
+WHEN TO USE:
+- Use this when the caller needs page inventory from the external API itself.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- Do not replace get_project_info with this tool when the goal is the standard import/export flow; get_project_info remains the primary entry point there.
+
+AFTER CALLING:
+- Use the returned page resources as-is.
+- If the caller needs one specific page by ID, use project_page_get.`,
   inputSchema: optionalProjectRootInputObjectSchema,
-  outputSchema: z4.object({
-    export: z4.object({
-      id: z4.string().describe(
-        "Freshly created export identifier. Use this as download_export input.id."
-      ),
-      status: exportStatusSchema,
-      createdAt: z4.string().describe("Export creation timestamp in ISO-8601 UTC format."),
-      expiresAt: z4.string().nullable().describe(
-        "Export expiration timestamp in ISO-8601 UTC format, or null when export has no explicit expiration."
-      ),
-      summary: exportSummarySchema.describe(
-        "Export run summary with total/successful/failed counters."
-      ),
-      exportables: z4.array(exportableSchema).describe(
-        "Shared exportable manifest. These entries are independent from page-level manifests."
-      )
-    }).describe("Created export summary."),
-    pages: z4.array(exportPageSchema).describe(
-      "Strict page payload associated with this export, including per-page manifest files list."
-    )
-  }),
+  outputSchema: projectApiPagesOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolProjectPageGet = {
+  title: "PrimeUI Project Page Get",
+  description: `Atomic external API helper. Returns one page by pageId using the same shape as project_pages_list.
+
+WHEN TO USE:
+- Use this when the caller already knows the target pageId.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+
+AFTER CALLING:
+- The response stays endpoint-aligned and returns a pages array envelope from the external API.`,
+  inputSchema: {
+    projectRoot: projectRootInputSchema,
+    pageId: z4.string().describe("PrimeUI page identifier to fetch from the external API.")
+  },
+  outputSchema: projectApiPagesOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolProjectPageCreate = {
+  title: "PrimeUI Project Page Create",
+  description: `Atomic external API helper. Creates a new page and its initial variant.
+
+WHEN TO USE:
+- Use this only when the caller explicitly wants to create a page through the external API.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- Do not encode follow-up chains here. Creating more variants later is a possible next step, not a requirement.
+
+AFTER CALLING:
+- The returned pages payload reflects the immediate API result for the created page.
+- If contentMode is ai, the initial variant may still be generating.`,
+  inputSchema: projectPageCreateBaseInputSchema,
+  outputSchema: projectApiPagesOutputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  }
+};
+var toolProjectPageVariantsList = {
+  title: "PrimeUI Project Page Variants List",
+  description: `Atomic external API helper. Returns lightweight variant summaries for one page.
+
+WHEN TO USE:
+- Use this when the caller needs the variant inventory for an existing pageId.
+- This is an ADDITIONAL capability outside the primary import/export workflow.`,
+  inputSchema: {
+    projectRoot: projectRootInputSchema,
+    pageId: z4.string().describe("PrimeUI page identifier whose variants should be listed.")
+  },
+  outputSchema: projectApiVariantsOutputSchema,
   annotations: {
-    readOnlyHint: false,
+    readOnlyHint: true,
     destructiveHint: false,
-    idempotentHint: false,
+    idempotentHint: true,
     openWorldHint: true
   }
 };
-var toolDownloadExport = {
-  title: "PrimeUI Download Export",
-  description: `Download a completed export into .primeui/temp/exports/[exportId]. Downloads and extracts the full export as a standalone Next.js project into the temp directory. This does NOT modify the user's project - files land only in .primeui/temp/.
-
-Do NOT call this as the first step. Requires export ID from create_export. Start with get_project_info instead.
-
-WHEN TO USE: Call this AFTER create_export has returned a completed export. Requires export ID from create_export so MCP can use the matching local sidecar manifest.
-
-NOTE:
-- Download of an export ID without local sidecar manifest will fail.
-- For previous exports, create a fresh export first when possible.
-
-AFTER DOWNLOAD:
-- Use manifestPath from this response as the contract for page slug/path mapping and manifest file lists in copy operations.
-- For each selected page, call copy_page with:
-  - originPageSlug (required).
-- Treat conflicts as normal and expected. If copy_page returns needs_review, stop follow-up integration and resolve manually first.
-- Do not force cleanup at flow end; keep downloaded export files available for validation and follow-up checks.
+var toolProjectPageVariantGet = {
+  title: "PrimeUI Project Page Variant Get",
+  description: `Atomic external API helper. Returns one variant with its component payload.
 
-  ${WORKFLOW_SUMMARY}`,
+WHEN TO USE:
+- Use this when the caller already knows both pageId and variantId.
+- This is an ADDITIONAL capability outside the primary import/export workflow.`,
   inputSchema: {
     projectRoot: projectRootInputSchema,
-    id: z4.string().describe(
-      "Export identifier to download. Prefer export.id from create_export; use list_exports only on explicit user request."
-    )
+    pageId: z4.string().describe("PrimeUI page identifier that owns the variant."),
+    variantId: z4.string().describe("PrimeUI variant identifier to fetch.")
   },
-  outputSchema: z4.object({
-    exportId: z4.string().describe(
-      "Downloaded export identifier. Should match the requested input.id for traceability."
-    ),
-    projectPath: z4.string().describe(
-      "Absolute local path to extracted export root in .primeui/temp/exports/[exportId]. Read files from here only."
-    ),
-    manifestPath: z4.string().describe(
-      "Absolute path to sidecar export manifest file (.primeui/temp/exports/[exportId].manifest.json) saved by create_export and required by copy_page."
-    )
-  }),
+  outputSchema: projectApiVariantOutputSchema,
   annotations: {
-    readOnlyHint: false,
+    readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
     openWorldHint: true
   }
 };
-var toolCopyPage = {
-  title: "PrimeUI Copy Page",
-  description: `Safely copy one page from downloaded export into the user's local project. Works only with local files in .primeui/temp/exports and does NOT call PrimeUI API.
+var toolProjectPageVariantCreate = {
+  title: "PrimeUI Project Page Variant Create",
+  description: `Atomic external API helper. Creates one new variant for an existing page.
 
 WHEN TO USE:
-- Call this AFTER download_export.
-- Call once per selected page.
+- Use this only when the caller explicitly wants a new variant on an existing page.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- The new variant is created independently. Becoming active is a separate decision handled by project_page_active_variant_set.
 
-BEHAVIOR:
-- Reads export sidecar manifest to resolve originPageSlug -> pagePath/componentsPath.
-- Copies and validates files strictly from pages[].manifest.files for the selected page.
-- Never overwrites existing conflicting files.
-- Writes full conflict diffs to a local report file in .primeui/temp/exports/[exportId].copy-report-[copyId].json.
-- Reports:
-  a) copied new files (relative target paths),
-  b) identical existing files (relative target paths),
-  c) conflicting files as lightweight metadata (relative target paths + binary flag, no inline diff),
-  d) missing dependencies added to package.json,
-  e) dependency version conflicts (report-only, no auto upgrade).
-- Adds only missing dependencies to package.json (dependencies/devDependencies/peerDependencies).
-- Never updates existing dependency versions and never runs install commands.
-- If status is needs_review, page import is NOT complete and manual review is required before continuing. This can be caused by file conflicts or dependency version conflicts.
+AFTER CALLING:
+- Treat the returned variant payload as the immediate API result.
+- The create endpoint returns a lightweight variant summary only, not the full component payload.
+- If contentMode is ai, the variant may still be generating.`,
+  inputSchema: projectPageVariantCreateBaseInputSchema,
+  outputSchema: projectApiVariantSummaryResultSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  }
+};
+var toolProjectPageActiveVariantSet = {
+  title: "PrimeUI Project Page Active Variant Set",
+  description: `Atomic external API helper. Sets the export-selected active variant for one page.
 
-${WORKFLOW_SUMMARY}`,
+WHEN TO USE:
+- Use this only when the caller explicitly wants to switch the active variant.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- This tool performs exactly one operation: set the active variant. It does not create variants and does not export anything.`,
   inputSchema: {
     projectRoot: projectRootInputSchema,
-    originPageSlug: z4.string().describe(
-      "Source page slug from PrimeUI project pages list, for example '/', '/pricing', '/docs'."
-    )
+    pageId: z4.string().describe("PrimeUI page identifier whose active variant should change."),
+    variantId: z4.string().describe("Variant identifier that should become active for export.")
   },
-  outputSchema: z4.object({
-    status: z4.enum(["completed", "needs_review"]).describe(
-      "Decision state for next step. needs_review means manual review is required before follow-up integration because of file conflicts or dependency version conflicts."
-    ),
-    message: z4.string().describe(
-      "Decision-oriented summary that includes resolved reportPath and manual follow-up instructions when needed."
-    ),
-    reportPath: z4.string().describe(
-      "Absolute path to saved local report with full conflict diffs and details."
-    ),
-    exportId: z4.string().describe("Resolved local export identifier used for copy operation."),
-    exportPath: z4.string().describe("Absolute path to local extracted export project root."),
-    originPageSlug: z4.string().describe("Normalized source page slug requested for copy."),
-    sourcePagePath: z4.string().describe("Source page path relative to export root."),
-    sourceComponentsPath: z4.string().describe("Source components directory relative to export root."),
-    newFiles: z4.array(z4.string()).describe("Relative target paths for new files copied into user project."),
-    identicalFiles: z4.array(z4.string()).describe("Relative target paths for existing byte-identical files."),
-    conflictFiles: z4.array(conflictFileSchema).describe(
-      "Files that already exist and differ from export version. Never overwritten."
-    ),
-    addedDependencies: z4.array(dependencyToAddSchema).describe(
-      "Dependencies that were missing and have been added to user's package.json."
-    ),
-    dependenciesVersionConflicts: z4.array(dependencyVersionConflictSchema).describe(
-      "Dependencies with version mismatch between export and user project. Report only."
-    ),
-    summary: z4.object({
-      totalCandidateFiles: z4.number().describe(
-        "Total number of candidate files considered for page copy from pages[].manifest.files."
-      ),
-      copiedFiles: z4.number().describe("Number of files copied as new."),
-      identicalFiles: z4.number().describe("Number of files detected as identical."),
-      conflictFiles: z4.number().describe("Number of conflicting files not copied."),
-      addedDependencies: z4.number().describe("Count of dependencies added to package.json."),
-      dependenciesVersionConflicts: z4.number().describe("Count of dependency version mismatches reported.")
-    })
-  }),
+  outputSchema: projectApiPagesOutputSchema,
   annotations: {
     readOnlyHint: false,
     destructiveHint: false,
     idempotentHint: false,
-    openWorldHint: false
+    openWorldHint: true
   }
 };
-var toolClearTemp = {
-  title: "PrimeUI Clear Temp",
-  description: `Delete all files in .primeui/temp/ and recreate empty temp structure.
-
-Call this at the START of a new import flow, before get_project_info/create_export, to reset stale temp state from previous runs.
-
-WHEN TO USE: Call once at the beginning of each new import flow. Do not call this between page imports in the same flow.
+var toolProjectIssueReportSubmit = {
+  title: "PrimeUI Project Issue Report Submit",
+  description: `Atomic external API helper. Submits an issue report for the scoped PrimeUI project.
 
-Safe to call multiple times. Only affects .primeui/temp/ directory - never touches the user's project files.
+WHEN TO USE:
+- Use this when the caller wants to send a focused issue report through the external API.
+- This is an ADDITIONAL capability outside the primary import/export workflow.
+- This tool is independent from export, page, and variant flows.
 
-${WORKFLOW_SUMMARY}`,
-  inputSchema: optionalProjectRootInputObjectSchema,
-  outputSchema: z4.object({
-    success: z4.boolean().describe(
-      "True when temp cleanup completed and baseline temp structure was recreated."
-    )
-  }),
+AFTER CALLING:
+- Use ticketId for user-facing confirmation or follow-up references.`,
+  inputSchema: projectIssueReportSubmitInputSchema,
+  outputSchema: issueReportSubmitOutputSchema,
   annotations: {
     readOnlyHint: false,
     destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: false
+    idempotentHint: false,
+    openWorldHint: true
   }
 };
 
 // src/server.ts
 var ZERO_ARG_PROJECT_ROOT_TOOLS = /* @__PURE__ */ new Set([
   "get_project_info",
+  "project_description_get",
+  "project_pages_list",
   "list_exports",
   "create_export",
   "clear_temp"
@@ -3070,6 +5018,18 @@ Hint: ${error.hint}` : `primeui mcp error [${error.code}]: ${error.message}`;
       content: [{ type: "text", text }]
     };
   }
+  if (error instanceof ZodError) {
+    const details = error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `primeui mcp error [INVALID_INPUT]: ${details}`
+        }
+      ]
+    };
+  }
   const message = error instanceof Error ? error.message : String(error);
   return {
     isError: true,
@@ -3111,6 +5071,150 @@ function createPrimeUiMcpServer(source) {
       }
     }
   );
+  server.registerTool(
+    "project_description_get",
+    toolProjectDescriptionGet,
+    async (args) => {
+      const { projectRoot } = args ?? {};
+      try {
+        const result = await source.getProjectDescription({
+          projectRoot
+        });
+        return okResult("project_description_get", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_description_upsert",
+    toolProjectDescriptionUpsert,
+    async ({ projectDescription, projectRoot }) => {
+      try {
+        const result = await source.upsertProjectDescription(projectDescription, {
+          projectRoot
+        });
+        return okResult("project_description_upsert", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_pages_list",
+    toolProjectPagesList,
+    async (args) => {
+      const { projectRoot } = args ?? {};
+      try {
+        const result = await source.listProjectPages({
+          projectRoot
+        });
+        return okResult("project_pages_list", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_page_get",
+    toolProjectPageGet,
+    async ({ pageId, projectRoot }) => {
+      try {
+        const result = await source.getProjectPage(pageId, { projectRoot });
+        return okResult("project_page_get", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_page_create",
+    toolProjectPageCreate,
+    async (args) => {
+      try {
+        const { projectRoot, ...input } = projectPageCreateValidationSchema.parse(args);
+        const result = await source.createProjectPage(input, { projectRoot });
+        return okResult("project_page_create", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_page_variants_list",
+    toolProjectPageVariantsList,
+    async ({ pageId, projectRoot }) => {
+      try {
+        const result = await source.listProjectPageVariants(pageId, {
+          projectRoot
+        });
+        return okResult("project_page_variants_list", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_page_variant_get",
+    toolProjectPageVariantGet,
+    async ({ pageId, variantId, projectRoot }) => {
+      try {
+        const result = await source.getProjectPageVariant(pageId, variantId, {
+          projectRoot
+        });
+        return okResult("project_page_variant_get", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_page_variant_create",
+    toolProjectPageVariantCreate,
+    async (args) => {
+      try {
+        const { pageId, projectRoot, ...input } = projectPageVariantCreateValidationSchema.parse(args);
+        const result = await source.createProjectPageVariant(pageId, input, {
+          projectRoot
+        });
+        return okResult("project_page_variant_create", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_page_active_variant_set",
+    toolProjectPageActiveVariantSet,
+    async ({ pageId, variantId, projectRoot }) => {
+      try {
+        const result = await source.setProjectPageActiveVariant(pageId, variantId, {
+          projectRoot
+        });
+        return okResult("project_page_active_variant_set", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "project_issue_report_submit",
+    toolProjectIssueReportSubmit,
+    async ({ reportText, tags, projectRoot }) => {
+      try {
+        const result = await source.submitIssueReport(
+          {
+            reportText,
+            tags
+          },
+          { projectRoot }
+        );
+        return okResult("project_issue_report_submit", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
   server.registerTool(
     "inspect_page",
     toolInspectPage,
@@ -3187,16 +5291,54 @@ function createPrimeUiMcpServer(source) {
   server.registerTool(
     "copy_page",
     toolCopyPage,
+    async ({ originPageSlug, projectRoot }) => {
+      try {
+        const result = await source.copyPage(
+          originPageSlug,
+          { projectRoot }
+        );
+        return okResult("copy_page", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "copy_component",
+    toolCopyComponent,
     async ({
       originPageSlug,
+      blockId,
+      componentId,
       projectRoot
     }) => {
       try {
-        const result = await source.copyPage(
+        const result = await source.copyComponent(
           originPageSlug,
-          { projectRoot }
+          blockId,
+          componentId,
+          {
+            projectRoot
+          }
         );
-        return okResult("copy_page", result);
+        return okResult("copy_component", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "copy_exportable",
+    toolCopyExportable,
+    async ({ exportableKey, projectRoot }) => {
+      try {
+        const result = await source.copyExportable(
+          exportableKey,
+          {
+            projectRoot
+          }
+        );
+        return okResult("copy_exportable", result);
       } catch (error) {
         return errorResult(error);
       }