@genart-dev/mcp-server 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -268,9 +268,40 @@ var EditorState = class extends import_events.EventEmitter {
       canvasHeight: def.canvas.height,
       rendererId: def.renderer.type
     };
+    const sketch = {
+      getSymbols() {
+        return loaded.definition.symbols ?? {};
+      },
+      setSymbols(symbols) {
+        loaded.definition = { ...loaded.definition, symbols };
+      },
+      getComponents() {
+        return loaded.definition.components ?? {};
+      },
+      setComponents(components) {
+        loaded.definition = { ...loaded.definition, components };
+      },
+      getThirdParty() {
+        const def2 = loaded.definition;
+        return def2["thirdParty"] ?? [];
+      },
+      setThirdParty(notices) {
+        loaded.definition["thirdParty"] = notices;
+      },
+      getRenderer() {
+        return loaded.definition.renderer.type;
+      },
+      getGenartVersion() {
+        return loaded.definition.genart;
+      },
+      setGenartVersion(version) {
+        loaded.definition = { ...loaded.definition, genart: version };
+      }
+    };
     return {
       layers: layerStack,
       sketchState,
+      sketch,
       canvasWidth: def.canvas.width,
       canvasHeight: def.canvas.height,
       async resolveAsset(_assetId) {
@@ -306,11 +337,25 @@ var EditorState = class extends import_events.EventEmitter {
 // src/server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_zod2 = require("zod");
-var import_core12 = require("@genart-dev/core");
+var import_core15 = require("@genart-dev/core");
 var import_plugin_typography = __toESM(require("@genart-dev/plugin-typography"), 1);
 var import_plugin_filters = __toESM(require("@genart-dev/plugin-filters"), 1);
 var import_plugin_shapes = __toESM(require("@genart-dev/plugin-shapes"), 1);
 var import_plugin_layout_guides = __toESM(require("@genart-dev/plugin-layout-guides"), 1);
+var import_plugin_painting = __toESM(require("@genart-dev/plugin-painting"), 1);
+var import_plugin_textures = __toESM(require("@genart-dev/plugin-textures"), 1);
+var import_plugin_animation = __toESM(require("@genart-dev/plugin-animation"), 1);
+var import_plugin_color_adjust = __toESM(require("@genart-dev/plugin-color-adjust"), 1);
+var import_plugin_compositing = __toESM(require("@genart-dev/plugin-compositing"), 1);
+var import_plugin_construction = __toESM(require("@genart-dev/plugin-construction"), 1);
+var import_plugin_distribution = __toESM(require("@genart-dev/plugin-distribution"), 1);
+var import_plugin_figure = __toESM(require("@genart-dev/plugin-figure"), 1);
+var import_plugin_layout_composition = __toESM(require("@genart-dev/plugin-layout-composition"), 1);
+var import_plugin_perspective = __toESM(require("@genart-dev/plugin-perspective"), 1);
+var import_plugin_poses = __toESM(require("@genart-dev/plugin-poses"), 1);
+var import_plugin_styles = __toESM(require("@genart-dev/plugin-styles"), 1);
+var import_plugin_symbols = __toESM(require("@genart-dev/plugin-symbols"), 1);
+var import_plugin_trace = __toESM(require("@genart-dev/plugin-trace"), 1);
 
 // src/tools/workspace.ts
 var import_promises3 = require("fs/promises");
@@ -739,8 +784,8 @@ async function createSketch(state, input) {
   }
   let algorithm = input.algorithm;
   if (!algorithm) {
-    const registry4 = (0, import_core3.createDefaultRegistry)();
-    const adapter = registry4.resolve(rendererType);
+    const registry5 = (0, import_core3.createDefaultRegistry)();
+    const adapter = registry5.resolve(rendererType);
     algorithm = adapter.getAlgorithmTemplate();
   }
   let resolvedComponents;
@@ -965,8 +1010,8 @@ async function updateAlgorithm(state, input) {
   const shouldValidate = input.validate !== false;
   let validationPassed = true;
   if (shouldValidate) {
-    const registry4 = (0, import_core3.createDefaultRegistry)();
-    const adapter = registry4.resolve(def.renderer.type);
+    const registry5 = (0, import_core3.createDefaultRegistry)();
+    const adapter = registry5.resolve(def.renderer.type);
     const result = adapter.validate(input.algorithm);
     if (!result.valid) {
       throw new Error(
@@ -1089,6 +1134,12 @@ async function forkSketch(state, input) {
   const seed = generateNewSeed ? Math.floor(Math.random() * 1e5) : sourceDef.state.seed;
   const title = input.title ?? `${sourceDef.title} (fork)`;
   const ts = now2();
+  const sourceGeneration = sourceDef.lineage?.generation ?? 1;
+  const lineage = {
+    parentId: input.sourceId,
+    parentTitle: sourceDef.title,
+    generation: sourceGeneration + 1
+  };
   const forkedDef = {
     genart: "1.1",
     id: input.newId,
@@ -1101,6 +1152,8 @@ async function forkSketch(state, input) {
     colors,
     state: buildState(parameters, colors, seed),
     algorithm,
+    ...sourceDef.compositionLevel ? { compositionLevel: sourceDef.compositionLevel } : {},
+    lineage,
     ...philosophy ? { philosophy } : {},
     ...sourceDef.themes ? { themes: [...sourceDef.themes] } : {},
     ...sourceDef.skills ? { skills: [...sourceDef.skills] } : {},
@@ -2062,6 +2115,13 @@ ${s.philosophy}`);
     params[p.key] = p.default;
   }
   const colorPalette = colors.map((c) => c.default);
+  const maxGeneration = Math.max(
+    ...sources.map((s) => s.lineage?.generation ?? 1)
+  );
+  const lineage = {
+    blendSources: input.sourceIds,
+    generation: maxGeneration + 1
+  };
   const timestamp = now5();
   const newDef = {
     genart: "1.1",
@@ -2070,6 +2130,7 @@ ${s.philosophy}`);
     created: timestamp,
     modified: timestamp,
     ...skills.length > 0 ? { skills } : {},
+    lineage,
     renderer: { type: renderer, version: sources[0].renderer.version },
     canvas: { width: canvasWidth, height: canvasHeight },
     ...philosophy ? { philosophy } : {},
@@ -2296,14 +2357,25 @@ async function getGuidelines(input) {
     color: "color",
     colours: "color",
     layout: "composition",
-    palette: "color"
+    palette: "color",
+    painting: "painting",
+    watercolor: "painting",
+    ink: "illustration",
+    illustration: "illustration",
+    "mixed-media": "illustration",
+    "mixed media": "illustration",
+    process: "process",
+    layering: "process",
+    "mark-making": "process",
+    refinement: "process",
+    constraints: "process"
   };
   const category = categoryMap[topic];
   if (!category) {
     return {
       success: false,
       topic,
-      error: `No guidelines found for topic: '${topic}'. Available topics: composition, color, parameters, animation, performance`,
+      error: `No guidelines found for topic: '${topic}'. Available topics: composition, color, painting, illustration, process, parameters, animation, performance`,
       guidelines: null,
       relatedSkills: []
     };
@@ -2330,6 +2402,138 @@ ${guidelines}`,
     }))
   };
 }
+var CONTEXT_KEYWORDS = {
+  // Composition keywords
+  layout: ["golden-ratio", "rule-of-thirds", "visual-weight", "gestalt-grouping"],
+  balance: ["visual-weight", "golden-ratio", "rule-of-thirds"],
+  grid: ["rule-of-thirds", "gestalt-grouping", "rhythm-movement"],
+  flow: ["rhythm-movement", "gestalt-grouping"],
+  movement: ["rhythm-movement", "mark-making"],
+  rhythm: ["rhythm-movement", "mark-making"],
+  focal: ["rule-of-thirds", "visual-weight", "figure-ground"],
+  negative: ["figure-ground", "visual-weight"],
+  space: ["figure-ground", "visual-weight", "atmospheric-depth"],
+  // Color keywords
+  palette: ["color-harmony", "palette-generation", "color-mixing-strategy"],
+  color: ["color-harmony", "color-temperature", "itten-contrasts", "color-mixing-strategy"],
+  warm: ["color-temperature", "atmospheric-depth"],
+  cool: ["color-temperature", "atmospheric-depth"],
+  contrast: ["simultaneous-contrast", "itten-contrasts", "value-structure"],
+  value: ["value-structure", "itten-contrasts", "layering-strategy"],
+  gray: ["color-mixing-strategy", "value-structure"],
+  // Painting keywords
+  watercolor: ["watercolor-techniques", "layering-strategy", "material-behavior"],
+  ink: ["ink-illustration", "mark-making", "material-behavior"],
+  oil: ["painting-foundations", "layering-strategy", "material-behavior"],
+  charcoal: ["material-behavior", "mark-making"],
+  brush: ["mark-making", "material-behavior"],
+  layer: ["layering-strategy", "mixed-media-workflow", "iterative-refinement"],
+  texture: ["material-behavior", "mark-making"],
+  // Process keywords
+  study: ["thumbnail-studies", "creative-constraints", "iterative-refinement"],
+  thumbnail: ["thumbnail-studies", "creative-constraints"],
+  refine: ["iterative-refinement", "layering-strategy"],
+  iterate: ["iterative-refinement", "thumbnail-studies"],
+  depth: ["atmospheric-depth", "color-temperature", "value-structure"],
+  atmosphere: ["atmospheric-depth", "color-temperature"],
+  perspective: ["atmospheric-depth"],
+  constraint: ["creative-constraints"],
+  limit: ["creative-constraints", "color-mixing-strategy"],
+  hatch: ["mark-making", "ink-illustration"],
+  stipple: ["mark-making"],
+  gestural: ["mark-making", "iterative-refinement"],
+  mix: ["color-mixing-strategy", "mixed-media-workflow"],
+  glaze: ["layering-strategy", "material-behavior"]
+};
+async function suggestSkills(state, input) {
+  const allSkills = registry.list();
+  const scored = /* @__PURE__ */ new Map();
+  for (const skill of allSkills) {
+    scored.set(skill.id, { score: 0, reasons: [] });
+  }
+  if (input.sketchId) {
+    const loaded = state.getSketch(input.sketchId);
+    if (loaded) {
+      const sketch = loaded.definition;
+      const usedSkills = new Set(sketch.skills ?? []);
+      for (const skill of allSkills) {
+        if (!usedSkills.has(skill.id)) {
+          const entry = scored.get(skill.id);
+          entry.score += 1;
+          entry.reasons.push("not yet used in this sketch");
+        }
+      }
+      const level = sketch.compositionLevel;
+      if (level) {
+        const levelSkills = {
+          study: ["thumbnail-studies", "creative-constraints", "iterative-refinement"],
+          sketch: ["iterative-refinement", "mark-making", "layering-strategy", "color-mixing-strategy"],
+          developed: ["layering-strategy", "material-behavior", "atmospheric-depth", "color-mixing-strategy"],
+          exhibition: ["layering-strategy", "material-behavior", "atmospheric-depth", "iterative-refinement", "mark-making"]
+        };
+        for (const id of levelSkills[level] ?? []) {
+          const entry = scored.get(id);
+          if (entry) {
+            entry.score += 3;
+            entry.reasons.push(`recommended for ${level}-level work`);
+          }
+        }
+      }
+      if (sketch.layers && sketch.layers.length > 0) {
+        const layerTypes = sketch.layers.map((l) => l.type);
+        if (layerTypes.some((t) => t.startsWith("painting:"))) {
+          for (const id of ["layering-strategy", "material-behavior", "iterative-refinement"]) {
+            const entry = scored.get(id);
+            if (entry) {
+              entry.score += 2;
+              entry.reasons.push("sketch uses painting layers");
+            }
+          }
+        }
+      }
+    }
+  }
+  if (input.context) {
+    const words = input.context.toLowerCase().split(/\W+/);
+    for (const word of words) {
+      const matched = CONTEXT_KEYWORDS[word];
+      if (matched) {
+        for (const skillId of matched) {
+          const entry = scored.get(skillId);
+          if (entry) {
+            entry.score += 2;
+            if (!entry.reasons.includes(`matches context keyword "${word}"`)) {
+              entry.reasons.push(`matches context keyword "${word}"`);
+            }
+          }
+        }
+      }
+    }
+  }
+  if (!input.sketchId && !input.context) {
+    for (const skill of allSkills) {
+      if (skill.category === "process") {
+        const entry = scored.get(skill.id);
+        entry.score += 2;
+        entry.reasons.push("process knowledge is broadly applicable");
+      }
+    }
+  }
+  const ranked = allSkills.map((skill) => ({
+    id: skill.id,
+    name: skill.name,
+    category: skill.category,
+    complexity: skill.complexity,
+    description: skill.description,
+    relevanceScore: scored.get(skill.id).score,
+    rationale: scored.get(skill.id).reasons
+  })).filter((s) => s.relevanceScore > 0).sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, 5);
+  return {
+    success: true,
+    suggestions: ranked,
+    total: ranked.length
+  };
+}
 
 // src/tools/components.ts
 var import_promises7 = require("fs/promises");
@@ -2583,7 +2787,7 @@ async function captureHtml(options) {
   try {
     await page.setViewport({ width, height, deviceScaleFactor: 1 });
     await page.setContent(html, { waitUntil: "domcontentloaded", timeout: 3e4 });
-    await new Promise((resolve3) => setTimeout(resolve3, waitMs));
+    await new Promise((resolve5) => setTimeout(resolve5, waitMs));
     const buffer = await page.screenshot({
       type: imageType,
       clip: { x: 0, y: 0, width, height },
@@ -2603,7 +2807,7 @@ async function captureHtmlMulti(options) {
   try {
     await page.setViewport({ width, height, deviceScaleFactor: 1 });
     await page.setContent(html, { waitUntil: "domcontentloaded", timeout: 3e4 });
-    await new Promise((resolve3) => setTimeout(resolve3, waitMs));
+    await new Promise((resolve5) => setTimeout(resolve5, waitMs));
     const pngBuffer = await page.screenshot({
       type: "png",
       clip: { x: 0, y: 0, width, height }
@@ -2613,7 +2817,7 @@ async function captureHtmlMulti(options) {
     const inlineWidth = Math.round(width * scale);
     const inlineHeight = Math.round(height * scale);
     await page.setViewport({ width: inlineWidth, height: inlineHeight, deviceScaleFactor: 1 });
-    await new Promise((resolve3) => setTimeout(resolve3, 100));
+    await new Promise((resolve5) => setTimeout(resolve5, 100));
     const jpegBuffer = await page.screenshot({
       type: "jpeg",
       quality: jpegQuality,
@@ -2774,205 +2978,1264 @@ async function captureBatch(state, input) {
   };
 }
 
-// src/tools/export.ts
-var import_fs = require("fs");
-var import_promises9 = require("fs/promises");
-var import_path9 = require("path");
-var import_archiver = __toESM(require("archiver"), 1);
+// src/tools/critique.ts
 var import_core10 = require("@genart-dev/core");
-var registry3 = (0, import_core10.createDefaultRegistry)();
-async function validateOutputPath(outputPath) {
-  const parentDir = (0, import_path9.dirname)(outputPath);
-  try {
-    const s = await (0, import_promises9.stat)(parentDir);
-    if (!s.isDirectory()) {
-      throw new Error(`Parent directory does not exist: ${parentDir}`);
-    }
-  } catch (e) {
-    if (e instanceof Error && e.message.startsWith("Parent directory")) throw e;
-    throw new Error(`Parent directory does not exist: ${parentDir}`);
-  }
-  try {
-    await (0, import_promises9.stat)(outputPath);
-    throw new Error(
-      `File already exists at ${outputPath}. Delete it first or use a different path.`
-    );
-  } catch (e) {
-    if (e instanceof Error && e.message.startsWith("File already exists")) throw e;
+var registry3 = (0, import_core10.createDefaultSkillRegistry)();
+var ALL_ASPECTS = [
+  "composition",
+  "color",
+  "rhythm",
+  "unity",
+  "expression"
+];
+var SEVERITY = {
+  study: {
+    level: "study",
+    description: "Fast, exploratory \u2014 value the energy of discovery over polish",
+    focus: "Is the core idea visible? Does the sketch capture a single insight?",
+    tolerance: "High tolerance for roughness, imbalance, and incomplete resolution. Studies should feel alive, not finished."
+  },
+  sketch: {
+    level: "sketch",
+    description: "Intentional but rough \u2014 the idea should read clearly",
+    focus: "Do composition and color serve the concept? Are parameters well-chosen?",
+    tolerance: "Moderate tolerance. Unresolved edges and raw marks are fine, but the structure should be deliberate."
+  },
+  developed: {
+    level: "developed",
+    description: "Refined \u2014 every major decision should be justified",
+    focus: "Do all elements work together? Is there a clear visual hierarchy? Does the palette feel cohesive?",
+    tolerance: "Low tolerance for accidental imbalance. Rough areas should be intentional, not neglected."
+  },
+  exhibition: {
+    level: "exhibition",
+    description: "Polished \u2014 every element earns its place",
+    focus: "Could you defend every choice? Does the piece hold up under sustained viewing? Is the concept fully realized?",
+    tolerance: "Minimal tolerance. Each mark, color, and spatial relationship should feel inevitable."
   }
+};
+function buildCompositionFramework() {
+  return {
+    aspect: "composition",
+    questions: [
+      "Where does the eye land first? Is that the intended focal point?",
+      "Is there a clear visual hierarchy (primary, secondary, tertiary)?",
+      "How does the composition use the edges and corners of the canvas?",
+      "Is negative space working actively or is it leftover?",
+      "Does the arrangement feel balanced or intentionally unbalanced?"
+    ],
+    principles: [
+      "Visual weight distribution \u2014 dense, dark, saturated, or detailed areas carry more weight",
+      "Entry points and eye paths \u2014 the viewer needs a way in and a journey through the piece",
+      "Edge tension \u2014 elements near canvas edges create tension; use this deliberately",
+      "Rule of thirds / golden ratio \u2014 useful starting points, not rigid rules",
+      "Figure-ground clarity \u2014 the relationship between positive and negative space"
+    ],
+    pitfalls: [
+      "Centering everything \u2014 creates static compositions unless intentionally symmetrical",
+      "Filling the canvas uniformly \u2014 denies the viewer rest areas and focal emphasis",
+      "Tangent lines \u2014 elements barely touching edges or each other create visual discomfort",
+      "Competing focal points \u2014 multiple areas of equal emphasis confuse the eye",
+      "Ignoring the canvas aspect ratio \u2014 composition should respond to the format"
+    ]
+  };
 }
-function algorithmExtension(rendererType) {
-  return rendererType === "glsl" ? ".glsl" : ".js";
-}
-function applyOverrides2(sketch, overrides) {
-  if (overrides.seed === void 0 && overrides.params === void 0) {
-    return sketch;
-  }
-  const newState = {
-    seed: overrides.seed ?? sketch.state.seed,
-    params: overrides.params ? { ...sketch.state.params, ...overrides.params } : sketch.state.params,
-    colorPalette: sketch.state.colorPalette
+function buildColorFramework() {
+  return {
+    aspect: "color",
+    questions: [
+      "Does the palette feel intentional or arbitrary?",
+      "Is there a dominant color temperature (warm/cool) or a deliberate tension between them?",
+      "How many distinct hues are active? Is that number serving the concept?",
+      "Are value contrasts (light/dark) creating readable structure?",
+      "Do any colors feel out of place \u2014 or is dissonance intentional?"
+    ],
+    principles: [
+      "Color harmony \u2014 analogous, complementary, triadic, or split-complementary relationships",
+      "Value structure \u2014 squint at the piece; the composition should read in grayscale",
+      "Temperature as depth \u2014 warm advances, cool recedes (atmospheric perspective)",
+      "Saturation as emphasis \u2014 high saturation draws the eye; use it sparingly for focus",
+      "Color proportion \u2014 unequal amounts create interest (e.g., 60-30-10 ratio)"
+    ],
+    pitfalls: [
+      "Too many fully saturated colors competing for attention",
+      "No value range \u2014 all mid-tones flatten the piece",
+      "Random color assignment \u2014 palette should derive from concept, not just randomness",
+      "Ignoring simultaneous contrast \u2014 adjacent colors alter each other's appearance",
+      "Uniform opacity everywhere \u2014 varying transparency adds depth and atmosphere"
+    ]
   };
-  return { ...sketch, state: newState };
 }
-async function exportSketch(state, input) {
-  state.requireWorkspace();
-  const loaded = state.requireSketch(input.sketchId);
-  const sketch = applyOverrides2(loaded.definition, {
-    seed: input.seed,
-    params: input.params
-  });
-  await validateOutputPath(input.outputPath);
-  const adapter = registry3.resolve(sketch.renderer.type);
-  if (!adapter) {
-    throw new Error(
-      `Unsupported renderer type: '${sketch.renderer.type}'`
-    );
-  }
-  switch (input.format) {
-    case "html":
-      return await exportHtml(sketch, input.outputPath);
-    case "png":
-      return await exportPng(sketch, input);
-    case "svg":
-      return await exportSvg(sketch, input);
-    case "algorithm":
-      return await exportAlgorithm(sketch, input.outputPath);
-    case "zip":
-      return await exportZip(sketch, input);
-    default:
-      throw new Error(`Unsupported export format: '${input.format}'`);
-  }
+function buildRhythmFramework() {
+  return {
+    aspect: "rhythm",
+    questions: [
+      "Is there a repeating visual motif or interval?",
+      "Does the rhythm accelerate, decelerate, or remain steady?",
+      "Are there moments of syncopation \u2014 unexpected breaks in the pattern?",
+      "Does the rhythm contribute to or fight against the composition?",
+      "Is there scale variation \u2014 does the motif appear at multiple sizes?"
+    ],
+    principles: [
+      "Regular rhythm creates calm and order; irregular rhythm creates energy",
+      "Progressive rhythm (gradual change) creates movement and depth",
+      "Alternating rhythm adds complexity without chaos",
+      "Rhythm at multiple scales (fractal repetition) creates richness",
+      "Silence (empty intervals) is as important as sound (marked intervals)"
+    ],
+    pitfalls: [
+      "Perfectly regular grids without variation feel mechanical, not generative",
+      "Random distribution reads as noise, not rhythm",
+      "Single-scale repetition feels monotonous \u2014 vary size, spacing, or density",
+      "Rhythm that ignores the composition's focal structure",
+      "Over-complexity \u2014 too many overlapping rhythms create visual noise"
+    ]
+  };
 }
-async function exportHtml(sketch, outputPath) {
-  const adapter = registry3.resolve(sketch.renderer.type);
-  const html = adapter.generateStandaloneHTML(sketch);
-  const content = Buffer.from(html, "utf-8");
-  await (0, import_promises9.writeFile)(outputPath, content);
+function buildUnityFramework() {
   return {
-    success: true,
-    sketchId: sketch.id,
-    format: "html",
-    outputPath,
-    fileSize: content.byteLength,
-    renderer: sketch.renderer.type
+    aspect: "unity",
+    questions: [
+      "Does the piece feel like one cohesive work or disconnected parts?",
+      "Is there a unifying visual language (consistent mark quality, shape vocabulary)?",
+      "Do the parameters work together or do some feel bolted on?",
+      "Would removing any element weaken the whole?",
+      "Does the algorithm express a single clear idea?"
+    ],
+    principles: [
+      "Unity through repetition \u2014 shared elements tie the composition together",
+      "Unity through proximity \u2014 grouped elements feel related",
+      "Unity through continuation \u2014 aligned elements create visual connections",
+      "Variety within unity \u2014 enough variation to hold interest, enough consistency to cohere",
+      "Conceptual unity \u2014 all visual decisions serve the stated philosophy"
+    ],
+    pitfalls: [
+      "Feature accumulation \u2014 adding elements that don't serve the core concept",
+      "Inconsistent mark quality \u2014 mixing precise geometry with organic marks without intention",
+      "Disconnected color and form \u2014 palette that doesn't relate to the spatial structure",
+      "Parameter sprawl \u2014 too many controls that don't interact meaningfully",
+      "Style mixing without integration \u2014 combining techniques that don't speak to each other"
+    ]
   };
 }
-async function exportPng(sketch, input) {
-  const adapter = registry3.resolve(sketch.renderer.type);
-  const html = adapter.generateStandaloneHTML(sketch);
-  const width = input.width ?? sketch.canvas.width;
-  const height = input.height ?? sketch.canvas.height;
-  const result = await captureHtml({ html, width, height });
-  await (0, import_promises9.writeFile)(input.outputPath, result.bytes);
+function buildExpressionFramework() {
   return {
-    success: true,
-    sketchId: sketch.id,
-    format: "png",
-    outputPath: input.outputPath,
-    fileSize: result.bytes.byteLength,
-    renderer: sketch.renderer.type
+    aspect: "expression",
+    questions: [
+      "What mood or feeling does this piece evoke?",
+      "Is the generative process visible in the output? Should it be?",
+      "Does the algorithm's logic contribute to the emotional quality?",
+      "Is there a sense of the unexpected \u2014 does the piece surprise even its creator?",
+      "Does the philosophy statement match the visual experience?"
+    ],
+    principles: [
+      "Generative art is a conversation between intention and emergence",
+      "The algorithm is a medium \u2014 its constraints and affordances shape expression",
+      "Controlled randomness creates life; pure randomness creates noise",
+      "The seed is a collaborator \u2014 different seeds should produce meaningfully different moods",
+      "Process and result are both the artwork \u2014 the code embodies artistic decisions"
+    ],
+    pitfalls: [
+      "Over-control \u2014 leaving no room for generative surprise",
+      "Under-control \u2014 no discernible artistic intention behind the randomness",
+      "Technique as end \u2014 impressive code that produces emotionally flat output",
+      "Derivative work \u2014 reproducing established generative art tropes without adding perspective",
+      "Mismatched intent \u2014 the philosophy says one thing but the visual says another"
+    ]
   };
 }
-async function exportSvg(sketch, input) {
-  const width = input.width ?? sketch.canvas.width;
-  const height = input.height ?? sketch.canvas.height;
-  if (sketch.renderer.type === "svg") {
-    const content2 = Buffer.from(sketch.algorithm, "utf-8");
-    await (0, import_promises9.writeFile)(input.outputPath, content2);
-    return {
-      success: true,
-      sketchId: sketch.id,
-      format: "svg",
-      outputPath: input.outputPath,
-      fileSize: content2.byteLength,
-      renderer: sketch.renderer.type,
-      notice: null
-    };
+var ASPECT_BUILDERS = {
+  composition: buildCompositionFramework,
+  color: buildColorFramework,
+  rhythm: buildRhythmFramework,
+  unity: buildUnityFramework,
+  expression: buildExpressionFramework
+};
+async function critiqueSketch(state, input) {
+  state.requireWorkspace();
+  let sketchId;
+  if (input.sketchId) {
+    sketchId = input.sketchId;
+  } else if (state.selection.size > 0) {
+    sketchId = [...state.selection][0];
+  } else {
+    throw new Error("No sketch specified and nothing selected");
   }
-  const adapter = registry3.resolve(sketch.renderer.type);
-  const html = adapter.generateStandaloneHTML(sketch);
-  const result = await captureHtml({ html, width, height });
-  const b64 = Buffer.from(result.bytes).toString("base64");
-  const svg = `<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
-     width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
-  <image width="${width}" height="${height}"
-         href="data:image/png;base64,${b64}"/>
-</svg>`;
-  const content = Buffer.from(svg, "utf-8");
-  await (0, import_promises9.writeFile)(input.outputPath, content);
-  return {
+  const loaded = state.requireSketch(sketchId);
+  const sketch = loaded.definition;
+  const capture = await captureScreenshot(state, {
+    target: "sketch",
+    sketchId,
+    previewSize: input.previewSize ?? 400
+  });
+  const aspects = input.aspects ?? [...ALL_ASPECTS];
+  const frameworks = aspects.map((a) => ASPECT_BUILDERS[a]());
+  const level = sketch.compositionLevel ?? "sketch";
+  const severity = SEVERITY[level] ?? SEVERITY["sketch"];
+  const relevantSkills = gatherRelevantSkills(aspects);
+  const metadata = {
     success: true,
-    sketchId: sketch.id,
-    format: "svg",
-    outputPath: input.outputPath,
-    fileSize: content.byteLength,
-    renderer: sketch.renderer.type,
-    notice: "Non-SVG renderer \u2014 rasterized PNG embedded in SVG container"
+    sketchId,
+    title: sketch.title,
+    compositionLevel: level,
+    philosophy: sketch.philosophy ?? null,
+    severity: {
+      level: severity.level,
+      description: severity.description,
+      focus: severity.focus,
+      tolerance: severity.tolerance
+    },
+    frameworks,
+    relevantSkills,
+    instructions: [
+      "Use the image above and the frameworks below to perform a structured self-critique.",
+      `Calibrate your critique to the ${severity.level} level: ${severity.description}`,
+      "For each aspect, answer the questions, check the principles, and watch for the pitfalls.",
+      "Be honest but constructive \u2014 identify what works as well as what could improve.",
+      "End with 2-3 specific, actionable improvements ranked by impact."
+    ]
   };
-}
-async function exportAlgorithm(sketch, outputPath) {
-  const content = Buffer.from(sketch.algorithm, "utf-8");
-  await (0, import_promises9.writeFile)(outputPath, content);
   return {
-    success: true,
-    sketchId: sketch.id,
-    format: "algorithm",
-    outputPath,
-    fileSize: content.byteLength,
-    renderer: sketch.renderer.type
+    metadata,
+    previewJpegBase64: capture.previewJpegBase64
   };
 }
-async function exportZip(sketch, input) {
-  const adapter = registry3.resolve(sketch.renderer.type);
-  const width = input.width ?? sketch.canvas.width;
-  const height = input.height ?? sketch.canvas.height;
-  const html = adapter.generateStandaloneHTML(sketch);
-  const genartJson = (0, import_core10.serializeGenart)(sketch);
-  const algorithm = sketch.algorithm;
-  const algExt = algorithmExtension(sketch.renderer.type);
-  const captureResult = await captureHtml({ html, width, height });
-  const output = (0, import_fs.createWriteStream)(input.outputPath);
-  const archive = (0, import_archiver.default)("zip", { zlib: { level: 9 } });
-  const finished = new Promise((resolve3, reject) => {
-    output.on("close", resolve3);
-    archive.on("error", reject);
+async function compareSketches(state, input) {
+  state.requireWorkspace();
+  const ids = input.sketchIds;
+  if (ids.length < 2) {
+    throw new Error("compare_sketches requires at least 2 sketch IDs");
+  }
+  if (ids.length > 4) {
+    throw new Error("compare_sketches supports a maximum of 4 sketches");
+  }
+  const sketchInfos = ids.map((id) => {
+    const loaded = state.requireSketch(id);
+    return {
+      id,
+      title: loaded.definition.title,
+      compositionLevel: loaded.definition.compositionLevel ?? "sketch",
+      philosophy: loaded.definition.philosophy ?? null,
+      renderer: loaded.definition.renderer.type,
+      seed: loaded.definition.state.seed
+    };
   });
-  archive.pipe(output);
-  archive.append(html, { name: `${sketch.id}.html` });
-  archive.append(Buffer.from(captureResult.bytes), { name: `${sketch.id}.png` });
-  archive.append(algorithm, { name: `${sketch.id}${algExt}` });
-  archive.append(genartJson, { name: `${sketch.id}.genart` });
-  await archive.finalize();
-  await finished;
-  const s = await (0, import_promises9.stat)(input.outputPath);
-  return {
+  const batchResult = await captureBatch(state, {
+    sketchIds: ids,
+    previewSize: input.previewSize ?? 300
+  });
+  const previews = batchResult.items.map((item) => ({
+    sketchId: item.metadata["sketchId"],
+    inlineJpegBase64: item.inlineJpegBase64
+  }));
+  const aspects = input.aspects ?? [...ALL_ASPECTS];
+  const frameworks = aspects.map((a) => ASPECT_BUILDERS[a]());
+  const comparisonQuestions = aspects.map((aspect) => ({
+    aspect,
+    questions: buildComparisonQuestions(aspect, sketchInfos.length)
+  }));
+  const metadata = {
     success: true,
-    sketchId: sketch.id,
-    format: "zip",
-    outputPath: input.outputPath,
-    fileSize: s.size,
-    renderer: sketch.renderer.type,
-    contents: [
-      `${sketch.id}.html`,
-      `${sketch.id}.png`,
-      `${sketch.id}${algExt}`,
-      `${sketch.id}.genart`
+    sketches: sketchInfos,
+    aspects,
+    frameworks,
+    comparisonQuestions,
+    instructions: [
+      `Compare the ${ids.length} sketches shown above across the specified aspects.`,
+      "For each aspect, use the framework questions and comparison questions to analyze differences.",
+      "Identify which sketch handles each aspect most effectively and why.",
+      "Note where sketches complement each other \u2014 techniques from one could improve another.",
+      "End with a ranking per aspect and overall, with specific observations justifying each placement."
+    ]
+  };
+  return { metadata, previews };
+}
+function buildComparisonQuestions(aspect, count) {
+  const base = {
+    composition: [
+      "Which sketch has the strongest focal point?",
+      "How do the compositions differ in their use of space?",
+      "Which creates the most effective visual hierarchy?"
+    ],
+    color: [
+      "Which palette feels most intentional?",
+      "How do the value ranges compare \u2014 which has the strongest lights and darks?",
+      "Which color temperature creates the most effective mood?"
+    ],
+    rhythm: [
+      "Which sketch has the most engaging visual rhythm?",
+      "How do the rhythmic structures differ \u2014 regular vs progressive vs irregular?",
+      "Which achieves the best balance of repetition and variation?"
+    ],
+    unity: [
+      "Which sketch feels most cohesive as a single work?",
+      "Where does unity break down in each \u2014 what elements feel disconnected?",
+      "Which has the tightest relationship between concept and execution?"
+    ],
+    expression: [
+      "Which sketch evokes the strongest emotional response?",
+      "How does each sketch's generative process contribute to its expression?",
+      "Which most successfully balances intention with emergence?"
     ]
   };
+  const questions = [...base[aspect]];
+  if (count > 2) {
+    questions.push(
+      `Could elements from different sketches be combined to create something stronger?`
+    );
+  }
+  return questions;
+}
+function gatherRelevantSkills(aspects) {
+  const aspectToCategory = {
+    composition: ["composition"],
+    color: ["color"],
+    rhythm: ["composition"],
+    unity: ["composition", "color"],
+    expression: ["process"]
+  };
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const aspect of aspects) {
+    const categories = aspectToCategory[aspect];
+    for (const cat of categories) {
+      const skills = registry3.list(cat);
+      for (const skill of skills) {
+        if (!seen.has(skill.id)) {
+          seen.add(skill.id);
+          result.push({ id: skill.id, name: skill.name, relevantTo: aspect });
+        }
+      }
+    }
+  }
+  return result;
 }
 
-// src/tools/design.ts
-function requireSketchId(state, args) {
-  return args.sketchId ?? state.requireSelectedSketchId();
+// src/tools/series.ts
+var import_promises9 = require("fs/promises");
+var import_path9 = require("path");
+var import_core11 = require("@genart-dev/core");
+function now6() {
+  return (/* @__PURE__ */ new Date()).toISOString();
 }
-var BLEND_MODES = [
-  "normal",
-  "multiply",
-  "screen",
-  "overlay",
-  "darken",
+var KEBAB_RE2 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function validateKebabId2(id) {
+  if (!KEBAB_RE2.test(id)) {
+    throw new Error(
+      "ID must be kebab-case: lowercase letters, numbers, hyphens"
+    );
+  }
+}
+var VALID_STAGES = [
+  "studies",
+  "drafts",
+  "refinements",
+  "finals"
+];
+var STAGE_TO_LEVEL = {
+  studies: "study",
+  drafts: "sketch",
+  refinements: "developed",
+  finals: "exhibition"
+};
+var LEVEL_SCALE = {
+  study: 1,
+  sketch: 1,
+  developed: 1.5,
+  exhibition: 2
+};
+async function createSeries(state, input) {
+  const ws = state.requireWorkspace();
+  const id = input.label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  if (!id) {
+    throw new Error("Could not derive a valid ID from the label");
+  }
+  if (ws.series?.some((s) => s.id === id)) {
+    throw new Error(`Series with ID '${id}' already exists in workspace`);
+  }
+  const stages = input.stages ?? [...VALID_STAGES];
+  for (const stage of stages) {
+    if (!VALID_STAGES.includes(stage)) {
+      throw new Error(
+        `Invalid stage: '${stage}'. Valid stages: ${VALID_STAGES.join(", ")}`
+      );
+    }
+  }
+  const sketchFiles = input.sketchFiles ?? [];
+  for (const file of sketchFiles) {
+    const found = ws.sketches.some((s) => s.file === file);
+    if (!found) {
+      throw new Error(
+        `Sketch file '${file}' not found in workspace`
+      );
+    }
+  }
+  const series = {
+    id,
+    label: input.label,
+    narrative: input.narrative,
+    intent: input.intent,
+    ...input.progression ? { progression: input.progression } : {},
+    stages,
+    sketchFiles
+  };
+  state.workspace = {
+    ...ws,
+    modified: now6(),
+    series: [...ws.series ?? [], series]
+  };
+  const workspaceJson = (0, import_core11.serializeWorkspace)(state.workspace);
+  if (!state.remoteMode) {
+    await (0, import_promises9.writeFile)(state.workspacePath, workspaceJson, "utf-8");
+  }
+  state.emitMutation("workspace:updated", { seriesAdded: id });
+  return {
+    success: true,
+    series: {
+      id,
+      label: input.label,
+      narrative: input.narrative,
+      intent: input.intent,
+      stages,
+      sketchCount: sketchFiles.length
+    },
+    workspaceContent: workspaceJson
+  };
+}
+async function developConcept(_state, input) {
+  const medium = input.medium ?? "p5";
+  return {
+    success: true,
+    conceptPlan: {
+      concept: input.concept,
+      medium,
+      mood: {
+        instruction: "Define the emotional quality this concept should evoke.",
+        prompts: [
+          "What feeling should the viewer experience?",
+          "Is this contemplative, energetic, unsettling, serene?",
+          "What time of day, season, or environment does this concept suggest?"
+        ]
+      },
+      palette: {
+        instruction: "Design a color strategy that serves the mood.",
+        prompts: [
+          "What color temperature dominates (warm/cool)?",
+          "How many distinct hues are needed?",
+          "Should saturation be high (bold, graphic) or low (subtle, atmospheric)?",
+          "What value range (light-to-dark contrast) supports the concept?"
+        ]
+      },
+      composition: {
+        instruction: "Plan the spatial structure.",
+        prompts: [
+          "Where should the viewer's eye land first?",
+          "Is the composition centered, asymmetric, or edge-driven?",
+          "How does negative space contribute to the concept?",
+          "What rhythm (regular, progressive, chaotic) serves the idea?"
+        ]
+      },
+      skills: {
+        instruction: "Identify design skills to load for this concept.",
+        prompts: [
+          "Which composition skill applies (rule-of-thirds, golden-ratio, gestalt)?",
+          "Which color skill applies (color-harmony, color-temperature, simultaneous-contrast)?",
+          "Are there process skills needed (layering-strategy, iterative-refinement, thumbnail-studies)?",
+          "Consider using `suggest_skills` with the concept as context."
+        ]
+      },
+      seriesStructure: {
+        instruction: "Plan the body of work.",
+        prompts: [
+          "How many studies should explore the core idea (3-6 recommended)?",
+          "What aspect varies between studies (color, density, rhythm, scale)?",
+          "Which studies should be developed further into drafts?",
+          "What progression tells the most compelling story?"
+        ],
+        recommendedStages: ["studies", "drafts", "refinements", "finals"]
+      }
+    },
+    nextSteps: [
+      "1. Use `create_series` with a label, narrative, and intent derived from this plan.",
+      "2. Create 3-6 study-level sketches using `create_sketch` with compositionLevel: 'study'.",
+      "3. Use `critique_sketch` on each study to evaluate against the concept.",
+      "4. Use `promote_sketch` to advance the best studies to drafts.",
+      "5. Iterate: critique \u2192 refine \u2192 promote through stages.",
+      "6. Use `series_summary` to capture the full progression."
+    ]
+  };
+}
+async function seriesSummary(state, input) {
+  const ws = state.requireWorkspace();
+  const series = ws.series?.find((s) => s.id === input.seriesId);
+  if (!series) {
+    throw new Error(`Series '${input.seriesId}' not found in workspace`);
+  }
+  const sketchInfos = [];
+  const loadedIds = [];
+  for (const file of series.sketchFiles) {
+    let found = false;
+    for (const [id, loaded] of state.sketches) {
+      if ((0, import_path9.basename)(loaded.path) === file) {
+        const def = loaded.definition;
+        sketchInfos.push({
+          id,
+          title: def.title,
+          file,
+          compositionLevel: def.compositionLevel ?? "sketch",
+          lineage: def.lineage ?? null,
+          renderer: def.renderer.type,
+          canvas: `${def.canvas.width}x${def.canvas.height}`,
+          seed: def.state.seed,
+          parameterCount: def.parameters.length,
+          colorCount: def.colors.length,
+          philosophy: def.philosophy ?? null
+        });
+        loadedIds.push(id);
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      sketchInfos.push({ file, status: "not loaded" });
+    }
+  }
+  let previews;
+  if (input.captureScreenshots !== false && loadedIds.length > 0) {
+    const batchResult = await captureBatch(state, {
+      sketchIds: loadedIds,
+      previewSize: input.previewSize ?? 300
+    });
+    previews = batchResult.items.map((item) => ({
+      sketchId: item.metadata["sketchId"],
+      inlineJpegBase64: item.inlineJpegBase64
+    }));
+  }
+  const metadata = {
+    success: true,
+    series: {
+      id: series.id,
+      label: series.label,
+      narrative: series.narrative,
+      intent: series.intent,
+      progression: series.progression ?? null,
+      stages: series.stages ?? null
+    },
+    sketches: sketchInfos,
+    summary: {
+      totalSketches: series.sketchFiles.length,
+      loadedSketches: loadedIds.length,
+      compositionLevels: countBy(
+        sketchInfos.filter((s) => s["compositionLevel"]).map((s) => s["compositionLevel"])
+      )
+    },
+    instructions: [
+      "Review the series progression from studies through finals.",
+      "Evaluate whether the narrative and intent are reflected in the body of work.",
+      "Consider: does each sketch build on its predecessors? Is there a clear evolution?",
+      "Identify the strongest and weakest pieces. What makes them succeed or fail?",
+      "Document insights and decisions in the series narrative."
+    ]
+  };
+  return { metadata, previews };
+}
+async function promoteSketch(state, input) {
+  const ws = state.requireWorkspace();
+  const source = state.requireSketch(input.sketchId);
+  const sourceDef = source.definition;
+  if (!VALID_STAGES.includes(input.toStage)) {
+    throw new Error(
+      `Invalid stage: '${input.toStage}'. Valid stages: ${VALID_STAGES.join(", ")}`
+    );
+  }
+  const targetLevel = STAGE_TO_LEVEL[input.toStage];
+  const scale = LEVEL_SCALE[targetLevel];
+  const newId = input.newId ?? `${input.sketchId}-${input.toStage.replace(/s$/, "")}`;
+  validateKebabId2(newId);
+  if (state.getSketch(newId)) {
+    throw new Error(`Sketch with ID '${newId}' already exists`);
+  }
+  const newWidth = Math.round(sourceDef.canvas.width * scale);
+  const newHeight = Math.round(sourceDef.canvas.height * scale);
+  const sourceGeneration = sourceDef.lineage?.generation ?? 1;
+  const title = input.title ?? `${sourceDef.title} (${input.toStage.replace(/s$/, "")})`;
+  const ts = now6();
+  const promotedDef = {
+    genart: "1.1",
+    id: newId,
+    title,
+    created: ts,
+    modified: ts,
+    renderer: sourceDef.renderer,
+    canvas: { width: newWidth, height: newHeight },
+    parameters: [...sourceDef.parameters],
+    colors: [...sourceDef.colors],
+    state: {
+      seed: sourceDef.state.seed,
+      params: { ...sourceDef.state.params },
+      colorPalette: [...sourceDef.state.colorPalette]
+    },
+    algorithm: sourceDef.algorithm,
+    compositionLevel: targetLevel,
+    lineage: {
+      parentId: input.sketchId,
+      parentTitle: sourceDef.title,
+      generation: sourceGeneration + 1
+    },
+    ...sourceDef.philosophy ? { philosophy: sourceDef.philosophy } : {},
+    ...sourceDef.themes ? { themes: [...sourceDef.themes] } : {},
+    ...sourceDef.skills ? { skills: [...sourceDef.skills] } : {},
+    ...sourceDef.components ? { components: sourceDef.components } : {},
+    ...sourceDef.symbols ? { symbols: sourceDef.symbols } : {},
+    ...input.agent ? { agent: input.agent } : {},
+    ...input.model ? { model: input.model } : {}
+  };
+  const sourceDir = (0, import_path9.dirname)(source.path);
+  const newPath = (0, import_path9.resolve)(sourceDir, `${newId}.genart`);
+  const json = (0, import_core11.serializeGenart)(promotedDef);
+  if (!state.remoteMode) {
+    await (0, import_promises9.writeFile)(newPath, json, "utf-8");
+  }
+  state.sketches.set(newId, { definition: promotedDef, path: newPath });
+  const sourceRef = ws.sketches.find(
+    (s) => s.file === (0, import_path9.basename)(source.path)
+  );
+  const position = sourceRef ? { x: sourceRef.position.x, y: sourceRef.position.y + sourceDef.canvas.height + 200 } : { x: 0, y: 0 };
+  const file = (0, import_path9.basename)(newPath);
+  state.workspace = {
+    ...ws,
+    modified: ts,
+    sketches: [...ws.sketches, { file, position }]
+  };
+  if (input.seriesId) {
+    const seriesIndex = state.workspace.series?.findIndex(
+      (s) => s.id === input.seriesId
+    );
+    if (seriesIndex !== void 0 && seriesIndex >= 0 && state.workspace.series) {
+      const series = state.workspace.series[seriesIndex];
+      const updatedSeries = {
+        ...series,
+        sketchFiles: [...series.sketchFiles, file]
+      };
+      state.workspace = {
+        ...state.workspace,
+        series: state.workspace.series.map(
+          (s, i) => i === seriesIndex ? updatedSeries : s
+        )
+      };
+    }
+  }
+  const workspaceJson = (0, import_core11.serializeWorkspace)(state.workspace);
+  if (!state.remoteMode) {
+    await (0, import_promises9.writeFile)(state.workspacePath, workspaceJson, "utf-8");
+  }
+  state.emitMutation("sketch:created", { id: newId, path: newPath });
+  state.emitMutation("workspace:updated", { added: file });
+  return {
+    success: true,
+    sourceId: input.sketchId,
+    promotedSketch: {
+      id: newId,
+      title,
+      path: newPath,
+      compositionLevel: targetLevel,
+      stage: input.toStage,
+      canvas: { width: newWidth, height: newHeight },
+      position,
+      lineage: promotedDef.lineage
+    },
+    ...scale > 1 ? {
+      canvasUpscaled: `Canvas scaled ${scale}x: ${sourceDef.canvas.width}x${sourceDef.canvas.height} \u2192 ${newWidth}x${newHeight}`
+    } : {},
+    fileContent: json,
+    workspaceContent: workspaceJson
+  };
+}
+function countBy(items) {
+  const counts = {};
+  for (const item of items) {
+    counts[item] = (counts[item] ?? 0) + 1;
+  }
+  return counts;
+}
+
+// src/tools/reference.ts
+var import_promises10 = require("fs/promises");
+var import_path10 = require("path");
+var import_core12 = require("@genart-dev/core");
+var import_promises11 = require("fs/promises");
+function now7() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+var KEBAB_RE3 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function validateKebabId3(id) {
+  if (!KEBAB_RE3.test(id)) {
+    throw new Error(
+      "ID must be kebab-case: lowercase letters, numbers, hyphens"
+    );
+  }
+}
+var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".tiff",
+  ".svg"
+]);
+function isImageFile(path) {
+  return IMAGE_EXTENSIONS.has((0, import_path10.extname)(path).toLowerCase());
+}
+var VALID_REFERENCE_TYPES = [
+  "image",
+  "artwork",
+  "photograph",
+  "texture",
+  "palette"
+];
+async function addReference(state, input) {
+  const ws = state.requireWorkspace();
+  if (!isImageFile(input.image)) {
+    throw new Error(
+      `Not a recognized image file: ${input.image}. Supported: ${[...IMAGE_EXTENSIONS].join(", ")}`
+    );
+  }
+  const id = input.id ?? (0, import_path10.basename)(input.image, (0, import_path10.extname)(input.image)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  if (!id) {
+    throw new Error("Could not derive a valid ID from the image filename");
+  }
+  validateKebabId3(id);
+  const refType = input.type ?? "image";
+  if (!VALID_REFERENCE_TYPES.includes(refType)) {
+    throw new Error(
+      `Invalid reference type: '${refType}'. Valid types: ${VALID_REFERENCE_TYPES.join(", ")}`
+    );
+  }
+  const workspaceDir = (0, import_path10.dirname)(state.workspacePath);
+  const refsDir = (0, import_path10.resolve)(workspaceDir, "references");
+  await (0, import_promises10.mkdir)(refsDir, { recursive: true });
+  const ext = (0, import_path10.extname)(input.image);
+  const destFilename = `${id}${ext}`;
+  const destPath = (0, import_path10.resolve)(refsDir, destFilename);
+  const relativePath = `references/${destFilename}`;
+  if (!state.remoteMode) {
+    await (0, import_promises10.copyFile)((0, import_path10.resolve)(input.image), destPath);
+  }
+  const ref = {
+    id,
+    type: refType,
+    path: relativePath,
+    ...input.source ? { source: input.source } : {}
+  };
+  let attachedTo;
+  let workspaceJson;
+  let sketchJson;
+  if (input.sketchId) {
+    const loaded = state.requireSketch(input.sketchId);
+    const existingRefs = loaded.definition.references ?? [];
+    if (existingRefs.some((r) => r.id === id)) {
+      throw new Error(
+        `Reference with ID '${id}' already exists on sketch '${input.sketchId}'`
+      );
+    }
+    const updatedDef = {
+      ...loaded.definition,
+      modified: now7(),
+      references: [...existingRefs, ref]
+    };
+    state.sketches.set(input.sketchId, {
+      definition: updatedDef,
+      path: loaded.path
+    });
+    sketchJson = (0, import_core12.serializeGenart)(updatedDef);
+    if (!state.remoteMode) {
+      await (0, import_promises11.writeFile)(loaded.path, sketchJson, "utf-8");
+    }
+    attachedTo = `sketch:${input.sketchId}`;
+    state.emitMutation("sketch:updated", { id: input.sketchId });
+  } else if (input.seriesId) {
+    const seriesIndex = ws.series?.findIndex((s) => s.id === input.seriesId);
+    if (seriesIndex === void 0 || seriesIndex < 0 || !ws.series) {
+      throw new Error(`Series '${input.seriesId}' not found in workspace`);
+    }
+    const series = ws.series[seriesIndex];
+    const existingRefs = series.references ?? [];
+    if (existingRefs.some((r) => r.id === id)) {
+      throw new Error(
+        `Reference with ID '${id}' already exists on series '${input.seriesId}'`
+      );
+    }
+    const updatedSeries = {
+      ...series,
+      references: [...existingRefs, ref]
+    };
+    state.workspace = {
+      ...ws,
+      modified: now7(),
+      series: ws.series.map(
+        (s, i) => i === seriesIndex ? updatedSeries : s
+      )
+    };
+    workspaceJson = (0, import_core12.serializeWorkspace)(state.workspace);
+    if (!state.remoteMode) {
+      await (0, import_promises11.writeFile)(state.workspacePath, workspaceJson, "utf-8");
+    }
+    attachedTo = `series:${input.seriesId}`;
+    state.emitMutation("workspace:updated", { referenceAdded: id });
+  } else {
+    throw new Error("Either seriesId or sketchId must be specified");
+  }
+  return {
+    success: true,
+    reference: {
+      id,
+      type: refType,
+      path: relativePath,
+      source: input.source ?? null
+    },
+    attachedTo,
+    ...sketchJson ? { fileContent: sketchJson } : {},
+    ...workspaceJson ? { workspaceContent: workspaceJson } : {}
+  };
+}
+async function analyzeReference(state, input) {
+  state.requireWorkspace();
+  const { ref, location } = findReference(state, input.referenceId, input.seriesId, input.sketchId);
+  const workspaceDir = (0, import_path10.dirname)(state.workspacePath);
+  const imagePath = (0, import_path10.resolve)(workspaceDir, ref.path);
+  let previewJpegBase64;
+  try {
+    const imageBuffer = await (0, import_promises10.readFile)(imagePath);
+    const ext = (0, import_path10.extname)(ref.path).toLowerCase();
+    const mimeMap = {
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".webp": "image/webp",
+      ".svg": "image/svg+xml"
+    };
+    previewJpegBase64 = imageBuffer.toString("base64");
+  } catch {
+  }
+  const metadata = {
+    success: true,
+    referenceId: ref.id,
+    type: ref.type,
+    path: ref.path,
+    source: ref.source ?? null,
+    location,
+    existingAnalysis: ref.analysis ?? null,
+    analysisFramework: {
+      composition: {
+        instruction: "Analyze the compositional structure of this reference.",
+        prompts: [
+          "What is the primary compositional structure (centered, asymmetric, diagonal, radial)?",
+          "Where does the eye land first? What creates the focal point?",
+          "How is negative space used \u2014 actively or passively?",
+          "What is the relationship between foreground, middle ground, and background?",
+          "How do the edges and corners of the frame interact with the subject?"
+        ]
+      },
+      palette: {
+        instruction: "Identify the color strategy.",
+        prompts: [
+          "What are the dominant colors (3-5 hex values)?",
+          "What color temperature dominates \u2014 warm, cool, or neutral?",
+          "What is the value range \u2014 high contrast or compressed?",
+          "Is the palette analogous, complementary, triadic, or something else?",
+          "How does saturation vary across the composition?"
+        ]
+      },
+      rhythm: {
+        instruction: "Identify rhythmic and pattern qualities.",
+        prompts: [
+          "Is there a repeating motif or interval?",
+          "Is the rhythm regular, progressive, alternating, or irregular?",
+          "At how many scales does pattern appear (fractal quality)?",
+          "How do density variations create movement?",
+          "Where are the moments of rest vs. activity?"
+        ]
+      },
+      mood: {
+        instruction: "Identify the emotional and atmospheric qualities.",
+        prompts: [
+          "What is the overall mood \u2014 contemplative, energetic, serene, unsettling?",
+          "How do color, light, and space contribute to that mood?",
+          "Is there a sense of time \u2014 moment, duration, timelessness?",
+          "What emotional response does the work invite?"
+        ]
+      },
+      technique: {
+        instruction: "Identify technical and material qualities worth studying.",
+        prompts: [
+          "What medium or technique is used?",
+          "How is mark-making contributing to expression?",
+          "Are there layering or transparency effects?",
+          "What level of control vs. chance is visible?",
+          "What technical approach could be translated to generative art?"
+        ]
+      }
+    },
+    instructions: [
+      "Study the reference image carefully using the framework above.",
+      "For each category, answer the prompts and synthesize your observations.",
+      "After analysis, use update_reference_analysis to save the structured analysis.",
+      "The analysis should inform how you create study sketches inspired by this reference.",
+      "Focus on qualities that can be translated to generative art \u2014 don't try to replicate literally."
+    ]
+  };
+  return { metadata, previewJpegBase64 };
+}
+async function updateReferenceAnalysis(state, input) {
+  const ws = state.requireWorkspace();
+  const { ref, location } = findReference(
+    state,
+    input.referenceId,
+    input.seriesId,
+    input.sketchId
+  );
+  const updatedRef = {
+    ...ref,
+    analysis: input.analysis
+  };
+  let workspaceJson;
+  let sketchJson;
+  if (location.startsWith("sketch:")) {
+    const sketchId = location.replace("sketch:", "");
+    const loaded = state.requireSketch(sketchId);
+    const updatedDef = {
+      ...loaded.definition,
+      modified: now7(),
+      references: (loaded.definition.references ?? []).map(
+        (r) => r.id === input.referenceId ? updatedRef : r
+      )
+    };
+    state.sketches.set(sketchId, {
+      definition: updatedDef,
+      path: loaded.path
+    });
+    sketchJson = (0, import_core12.serializeGenart)(updatedDef);
+    if (!state.remoteMode) {
+      await (0, import_promises11.writeFile)(loaded.path, sketchJson, "utf-8");
+    }
+    state.emitMutation("sketch:updated", { id: sketchId });
+  } else {
+    const seriesId = location.replace("series:", "");
+    const seriesIndex = ws.series.findIndex((s) => s.id === seriesId);
+    const series = ws.series[seriesIndex];
+    const updatedSeries = {
+      ...series,
+      references: (series.references ?? []).map(
+        (r) => r.id === input.referenceId ? updatedRef : r
+      )
+    };
+    state.workspace = {
+      ...ws,
+      modified: now7(),
+      series: ws.series.map(
+        (s, i) => i === seriesIndex ? updatedSeries : s
+      )
+    };
+    workspaceJson = (0, import_core12.serializeWorkspace)(state.workspace);
+    if (!state.remoteMode) {
+      await (0, import_promises11.writeFile)(state.workspacePath, workspaceJson, "utf-8");
+    }
+    state.emitMutation("workspace:updated", { referenceAnalyzed: input.referenceId });
+  }
+  return {
+    success: true,
+    referenceId: input.referenceId,
+    location,
+    analysis: input.analysis,
+    ...sketchJson ? { fileContent: sketchJson } : {},
+    ...workspaceJson ? { workspaceContent: workspaceJson } : {}
+  };
+}
+async function extractPalette(state, input) {
+  state.requireWorkspace();
+  const { ref, location } = findReference(
+    state,
+    input.referenceId,
+    input.seriesId,
+    input.sketchId
+  );
+  const count = input.count ?? 6;
+  const workspaceDir = (0, import_path10.dirname)(state.workspacePath);
+  const imagePath = (0, import_path10.resolve)(workspaceDir, ref.path);
+  let previewJpegBase64;
+  try {
+    const imageBuffer = await (0, import_promises10.readFile)(imagePath);
+    previewJpegBase64 = imageBuffer.toString("base64");
+  } catch {
+  }
+  const metadata = {
+    success: true,
+    referenceId: ref.id,
+    type: ref.type,
+    path: ref.path,
+    location,
+    requestedColors: count,
+    existingPalette: ref.analysis?.palette ?? null,
+    instructions: [
+      `Extract ${count} dominant colors from the reference image as hex values.`,
+      "Order them from most dominant to least dominant.",
+      "Include both saturated and neutral colors if present in the image.",
+      "Consider the role of each color \u2014 is it a background, accent, or primary element?",
+      "After extraction, use update_reference_analysis to save the palette.",
+      "You can also apply the extracted palette to a sketch using set_colors or create a new theme."
+    ],
+    extractionGuidelines: {
+      dominance: "Prioritize colors by the area they occupy, not just their saturation.",
+      variety: "Include the full value range (lights, midtones, darks) if present.",
+      harmony: `Look for ${count <= 4 ? "core harmony" : "extended palette including transitional colors"}.`,
+      neutrals: "Don't ignore grays, blacks, and whites \u2014 they often define the character of a palette."
+    }
+  };
+  return { metadata, previewJpegBase64 };
+}
+function findReference(state, referenceId, seriesId, sketchId) {
+  if (sketchId) {
+    const loaded = state.requireSketch(sketchId);
+    const ref = (loaded.definition.references ?? []).find(
+      (r) => r.id === referenceId
+    );
+    if (ref) return { ref, location: `sketch:${sketchId}` };
+    throw new Error(
+      `Reference '${referenceId}' not found on sketch '${sketchId}'`
+    );
+  }
+  if (seriesId) {
+    const ws2 = state.requireWorkspace();
+    const series = ws2.series?.find((s) => s.id === seriesId);
+    if (!series) {
+      throw new Error(`Series '${seriesId}' not found in workspace`);
+    }
+    const ref = (series.references ?? []).find((r) => r.id === referenceId);
+    if (ref) return { ref, location: `series:${seriesId}` };
+    throw new Error(
+      `Reference '${referenceId}' not found on series '${seriesId}'`
+    );
+  }
+  const ws = state.requireWorkspace();
+  if (ws.series) {
+    for (const series of ws.series) {
+      const ref = (series.references ?? []).find((r) => r.id === referenceId);
+      if (ref) return { ref, location: `series:${series.id}` };
+    }
+  }
+  for (const [id, loaded] of state.sketches) {
+    const ref = (loaded.definition.references ?? []).find(
+      (r) => r.id === referenceId
+    );
+    if (ref) return { ref, location: `sketch:${id}` };
+  }
+  throw new Error(
+    `Reference '${referenceId}' not found in any series or sketch`
+  );
+}
+
+// src/tools/export.ts
+var import_fs = require("fs");
+var import_promises12 = require("fs/promises");
+var import_path11 = require("path");
+var import_archiver = __toESM(require("archiver"), 1);
+var import_core13 = require("@genart-dev/core");
+var registry4 = (0, import_core13.createDefaultRegistry)();
+async function validateOutputPath(outputPath) {
+  const parentDir = (0, import_path11.dirname)(outputPath);
+  try {
+    const s = await (0, import_promises12.stat)(parentDir);
+    if (!s.isDirectory()) {
+      throw new Error(`Parent directory does not exist: ${parentDir}`);
+    }
+  } catch (e) {
+    if (e instanceof Error && e.message.startsWith("Parent directory")) throw e;
+    throw new Error(`Parent directory does not exist: ${parentDir}`);
+  }
+  try {
+    await (0, import_promises12.stat)(outputPath);
+    throw new Error(
+      `File already exists at ${outputPath}. Delete it first or use a different path.`
+    );
+  } catch (e) {
+    if (e instanceof Error && e.message.startsWith("File already exists")) throw e;
+  }
+}
+function algorithmExtension(rendererType) {
+  return rendererType === "glsl" ? ".glsl" : ".js";
+}
+function applyOverrides2(sketch, overrides) {
+  if (overrides.seed === void 0 && overrides.params === void 0) {
+    return sketch;
+  }
+  const newState = {
+    seed: overrides.seed ?? sketch.state.seed,
+    params: overrides.params ? { ...sketch.state.params, ...overrides.params } : sketch.state.params,
+    colorPalette: sketch.state.colorPalette
+  };
+  return { ...sketch, state: newState };
+}
+async function exportSketch(state, input) {
+  state.requireWorkspace();
+  const loaded = state.requireSketch(input.sketchId);
+  const sketch = applyOverrides2(loaded.definition, {
+    seed: input.seed,
+    params: input.params
+  });
+  await validateOutputPath(input.outputPath);
+  const adapter = registry4.resolve(sketch.renderer.type);
+  if (!adapter) {
+    throw new Error(
+      `Unsupported renderer type: '${sketch.renderer.type}'`
+    );
+  }
+  switch (input.format) {
+    case "html":
+      return await exportHtml(sketch, input.outputPath);
+    case "png":
+      return await exportPng(sketch, input);
+    case "svg":
+      return await exportSvg(sketch, input);
+    case "algorithm":
+      return await exportAlgorithm(sketch, input.outputPath);
+    case "zip":
+      return await exportZip(sketch, input);
+    default:
+      throw new Error(`Unsupported export format: '${input.format}'`);
+  }
+}
+async function exportHtml(sketch, outputPath) {
+  const adapter = registry4.resolve(sketch.renderer.type);
+  const html = adapter.generateStandaloneHTML(sketch);
+  const content = Buffer.from(html, "utf-8");
+  await (0, import_promises12.writeFile)(outputPath, content);
+  return {
+    success: true,
+    sketchId: sketch.id,
+    format: "html",
+    outputPath,
+    fileSize: content.byteLength,
+    renderer: sketch.renderer.type
+  };
+}
+async function exportPng(sketch, input) {
+  const adapter = registry4.resolve(sketch.renderer.type);
+  const html = adapter.generateStandaloneHTML(sketch);
+  const width = input.width ?? sketch.canvas.width;
+  const height = input.height ?? sketch.canvas.height;
+  const result = await captureHtml({ html, width, height });
+  await (0, import_promises12.writeFile)(input.outputPath, result.bytes);
+  return {
+    success: true,
+    sketchId: sketch.id,
+    format: "png",
+    outputPath: input.outputPath,
+    fileSize: result.bytes.byteLength,
+    renderer: sketch.renderer.type
+  };
+}
+async function exportSvg(sketch, input) {
+  const width = input.width ?? sketch.canvas.width;
+  const height = input.height ?? sketch.canvas.height;
+  if (sketch.renderer.type === "svg") {
+    const content2 = Buffer.from(sketch.algorithm, "utf-8");
+    await (0, import_promises12.writeFile)(input.outputPath, content2);
+    return {
+      success: true,
+      sketchId: sketch.id,
+      format: "svg",
+      outputPath: input.outputPath,
+      fileSize: content2.byteLength,
+      renderer: sketch.renderer.type,
+      notice: null
+    };
+  }
+  const adapter = registry4.resolve(sketch.renderer.type);
+  const html = adapter.generateStandaloneHTML(sketch);
+  const result = await captureHtml({ html, width, height });
+  const b64 = Buffer.from(result.bytes).toString("base64");
+  const svg = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
+     width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  <image width="${width}" height="${height}"
+         href="data:image/png;base64,${b64}"/>
+</svg>`;
+  const content = Buffer.from(svg, "utf-8");
+  await (0, import_promises12.writeFile)(input.outputPath, content);
+  return {
+    success: true,
+    sketchId: sketch.id,
+    format: "svg",
+    outputPath: input.outputPath,
+    fileSize: content.byteLength,
+    renderer: sketch.renderer.type,
+    notice: "Non-SVG renderer \u2014 rasterized PNG embedded in SVG container"
+  };
+}
+async function exportAlgorithm(sketch, outputPath) {
+  const content = Buffer.from(sketch.algorithm, "utf-8");
+  await (0, import_promises12.writeFile)(outputPath, content);
+  return {
+    success: true,
+    sketchId: sketch.id,
+    format: "algorithm",
+    outputPath,
+    fileSize: content.byteLength,
+    renderer: sketch.renderer.type
+  };
+}
+async function exportZip(sketch, input) {
+  const adapter = registry4.resolve(sketch.renderer.type);
+  const width = input.width ?? sketch.canvas.width;
+  const height = input.height ?? sketch.canvas.height;
+  const html = adapter.generateStandaloneHTML(sketch);
+  const genartJson = (0, import_core13.serializeGenart)(sketch);
+  const algorithm = sketch.algorithm;
+  const algExt = algorithmExtension(sketch.renderer.type);
+  const captureResult = await captureHtml({ html, width, height });
+  const output = (0, import_fs.createWriteStream)(input.outputPath);
+  const archive = (0, import_archiver.default)("zip", { zlib: { level: 9 } });
+  const finished = new Promise((resolve5, reject) => {
+    output.on("close", resolve5);
+    archive.on("error", reject);
+  });
+  archive.pipe(output);
+  archive.append(html, { name: `${sketch.id}.html` });
+  archive.append(Buffer.from(captureResult.bytes), { name: `${sketch.id}.png` });
+  archive.append(algorithm, { name: `${sketch.id}${algExt}` });
+  archive.append(genartJson, { name: `${sketch.id}.genart` });
+  await archive.finalize();
+  await finished;
+  const s = await (0, import_promises12.stat)(input.outputPath);
+  return {
+    success: true,
+    sketchId: sketch.id,
+    format: "zip",
+    outputPath: input.outputPath,
+    fileSize: s.size,
+    renderer: sketch.renderer.type,
+    contents: [
+      `${sketch.id}.html`,
+      `${sketch.id}.png`,
+      `${sketch.id}${algExt}`,
+      `${sketch.id}.genart`
+    ]
+  };
+}
+
+// src/tools/design.ts
+function requireSketchId(state, args) {
+  return args.sketchId ?? state.requireSelectedSketchId();
+}
+var BLEND_MODES = [
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "darken",
   "lighten",
   "color-dodge",
   "color-burn",
@@ -2992,8 +4255,8 @@ async function designAddLayer(state, args) {
   const sketchId = requireSketchId(state, args);
   const loaded = state.requireSketch(sketchId);
   const stack = state.getLayerStack(sketchId);
-  const registry4 = state.pluginRegistry;
-  const layerTypeDef = registry4?.resolveLayerType(args.type);
+  const registry5 = state.pluginRegistry;
+  const layerTypeDef = registry5?.resolveLayerType(args.type);
   if (!layerTypeDef) {
     throw new Error(
       `Unknown layer type: '${args.type}'. Use design_list_layers types from registered plugins.`
@@ -3100,10 +4363,7 @@ async function designUpdateLayer(state, args) {
     stack.updateProperties(args.layerId, updates);
   }
   if (args.name !== void 0) {
-    const current = stack.get(args.layerId);
-    stack.updateProperties(args.layerId, { ...current.properties });
-    const mutableLayer = stack.get(args.layerId);
-    mutableLayer.name = args.name;
+    stack.updateMeta(args.layerId, { name: args.name });
   }
   await state.saveSketch(sketchId);
   return { updated: true, layerId: args.layerId, sketchId };
@@ -3201,9 +4461,7 @@ async function designToggleVisibility(state, args) {
     throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
   }
   const newVisible = args.visible ?? !layer.visible;
-  const mutableLayer = layer;
-  mutableLayer.visible = newVisible;
-  stack.updateProperties(args.layerId, { ...layer.properties });
+  stack.updateMeta(args.layerId, { visible: newVisible });
   await state.saveSketch(sketchId);
   return {
     layerId: args.layerId,
@@ -3219,9 +4477,7 @@ async function designLockLayer(state, args) {
     throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
   }
   const newLocked = args.locked ?? !layer.locked;
-  const mutableLayer = layer;
-  mutableLayer.locked = newLocked;
-  stack.updateProperties(args.layerId, { ...layer.properties });
+  stack.updateMeta(args.layerId, { locked: newLocked });
   await state.saveSketch(sketchId);
   return {
     layerId: args.layerId,
@@ -3242,8 +4498,8 @@ async function designCaptureComposite(state, args) {
 }
 
 // src/tools/design-plugins.ts
-function registerPluginMcpTools(server, registry4, state) {
-  for (const tool of registry4.getMcpTools()) {
+function registerPluginMcpTools(server, registry5, state) {
+  for (const tool of registry5.getMcpTools()) {
     const inputSchema = tool.definition.inputSchema;
     server.tool(
       tool.name,
@@ -3288,7 +4544,7 @@ function registerPluginMcpTools(server, registry4, state) {
 }
 
 // src/resources/index.ts
-var import_core11 = require("@genart-dev/core");
+var import_core14 = require("@genart-dev/core");
 function registerResources(server, state) {
   registerSkillsResource(server);
   registerCanvasPresetsResource(server);
@@ -3296,7 +4552,7 @@ function registerResources(server, state) {
   registerRenderersResource(server);
 }
 function registerSkillsResource(server) {
-  const skillRegistry = (0, import_core11.createDefaultSkillRegistry)();
+  const skillRegistry = (0, import_core14.createDefaultSkillRegistry)();
   server.resource(
     "skills",
     "genart://skills",
@@ -3347,7 +4603,7 @@ function registerCanvasPresetsResource(server) {
           mimeType: "application/json",
           text: JSON.stringify(
             {
-              presets: import_core11.CANVAS_PRESETS.map((p) => ({
+              presets: import_core14.CANVAS_PRESETS.map((p) => ({
                 id: p.id,
                 label: p.label,
                 category: p.category,
@@ -3404,7 +4660,7 @@ function registerGalleryResource(server, state) {
   );
 }
 function registerRenderersResource(server) {
-  const registry4 = (0, import_core11.createDefaultRegistry)();
+  const registry5 = (0, import_core14.createDefaultRegistry)();
   server.resource(
     "renderers",
     "genart://renderers",
@@ -3413,9 +4669,9 @@ function registerRenderersResource(server) {
       mimeType: "application/json"
     },
     async () => {
-      const types = registry4.list();
+      const types = registry5.list();
       const renderers = types.map((type) => {
-        const adapter = registry4.resolve(type);
+        const adapter = registry5.resolve(type);
         return {
           type: adapter.type,
           displayName: adapter.displayName,
@@ -3427,7 +4683,7 @@ function registerRenderersResource(server) {
           }))
         };
       });
-      const defaultAdapter = registry4.getDefault();
+      const defaultAdapter = registry5.getDefault();
       return {
         contents: [
           {
@@ -3454,6 +4710,9 @@ function registerPrompts(server, state) {
   registerCreateGenerativeArt(server);
   registerExploreVariations(server, state);
   registerApplyDesignTheory(server, state);
+  registerCritiqueAndIterate(server, state);
+  registerDevelopArtisticConcept(server, state);
+  registerStudyReference(server, state);
 }
 function registerCreateGenerativeArt(server) {
   server.prompt(
@@ -3734,21 +4993,200 @@ function registerApplyDesignTheory(server, state) {
             content: {
               type: "text",
               text: [
-                `Apply design theory to improve a generative art sketch.`,
+                `Apply design theory to improve a generative art sketch.`,
+                ``,
+                sketchContext,
+                ``,
+                theoryGuides[args.theory],
+                ``,
+                `## Workflow`,
+                `1. Use \`get_selection\` or \`open_sketch\` to examine the current sketch`,
+                `2. Analyze how the theory applies to the existing algorithm`,
+                `3. Use \`fork_sketch\` to create a theory-applied variant`,
+                `4. Modify the fork's algorithm and parameters using the theory principles above`,
+                `5. Use \`capture_screenshot\` to compare before and after`,
+                `6. Update the philosophy field to document the design rationale`,
+                ``,
+                `**Attribution:** Always pass your \`agent\` name and \`model\` identifier when calling tools that create or modify sketches.`
+              ].join("\n")
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+function registerCritiqueAndIterate(server, state) {
+  server.prompt(
+    "critique-and-iterate",
+    "Capture a sketch, self-critique it, identify improvements, fork, apply changes, compare, and document the iteration",
+    {
+      sketchId: import_zod.z.string().describe("ID of the sketch to critique and iterate on"),
+      aspects: import_zod.z.string().optional().describe("Comma-separated aspects to focus on (composition, color, rhythm, unity, expression). Default: all"),
+      iterations: import_zod.z.string().optional().describe("Number of improvement iterations (default: 1)")
+    },
+    async (args) => {
+      const sketch = state.getSketch(args.sketchId);
+      const iterations = args.iterations ? parseInt(args.iterations, 10) : 1;
+      const aspectList = args.aspects ? args.aspects.split(",").map((a) => a.trim()) : ["composition", "color", "rhythm", "unity", "expression"];
+      let sketchContext = "";
+      if (sketch) {
+        const def = sketch.definition;
+        sketchContext = [
+          `## Current Sketch: "${def.title}"`,
+          `- **ID:** ${def.id}`,
+          `- **Renderer:** ${def.renderer.type}`,
+          `- **Canvas:** ${def.canvas.width}\xD7${def.canvas.height}`,
+          `- **Composition Level:** ${def.compositionLevel ?? "sketch"}`,
+          def.philosophy ? `- **Philosophy:** ${def.philosophy}` : `- **Philosophy:** not set`,
+          `- **Parameters:** ${def.parameters?.length ?? 0} defined`,
+          `- **Colors:** ${def.colors?.length ?? 0} defined`
+        ].join("\n");
+      } else {
+        sketchContext = `## Sketch: ${args.sketchId}
+*(Not currently loaded \u2014 use open_sketch first)*`;
+      }
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Perform a structured critique-and-iterate cycle on a generative art sketch.`,
                 ``,
                 sketchContext,
                 ``,
-                theoryGuides[args.theory],
+                `## Focus Aspects`,
+                aspectList.map((a) => `- ${a}`).join("\n"),
                 ``,
-                `## Workflow`,
-                `1. Use \`get_selection\` or \`open_sketch\` to examine the current sketch`,
-                `2. Analyze how the theory applies to the existing algorithm`,
-                `3. Use \`fork_sketch\` to create a theory-applied variant`,
-                `4. Modify the fork's algorithm and parameters using the theory principles above`,
-                `5. Use \`capture_screenshot\` to compare before and after`,
-                `6. Update the philosophy field to document the design rationale`,
+                `## Iterations: ${iterations}`,
                 ``,
-                `**Attribution:** Always pass your \`agent\` name and \`model\` identifier when calling tools that create or modify sketches.`
+                `## Process`,
+                ``,
+                `For each iteration:`,
+                ``,
+                `### Step 1: Capture & Critique`,
+                `1. Use \`critique_sketch\` with sketchId="${args.sketchId}" and aspects=[${aspectList.map((a) => `"${a}"`).join(", ")}]`,
+                `2. Study the returned screenshot carefully`,
+                `3. Answer each framework question honestly \u2014 what works and what doesn't`,
+                `4. Note the severity calibration for this composition level`,
+                ``,
+                `### Step 2: Identify Improvements`,
+                `Based on the critique, identify 2-3 specific, actionable improvements:`,
+                `- Rank them by expected visual impact`,
+                `- Be precise: "shift the focal cluster from center to upper-left third" not "improve composition"`,
+                `- Consider which improvements can be achieved via parameter changes vs algorithm changes`,
+                ``,
+                `### Step 3: Fork & Apply`,
+                `1. Use \`fork_sketch\` to create a new version (preserve the original for comparison)`,
+                `2. Apply the identified improvements:`,
+                `   - Use \`set_parameters\` or \`set_colors\` for parameter-level changes`,
+                `   - Use \`update_algorithm\` for algorithmic changes`,
+                `3. Use \`capture_screenshot\` to verify each change visually`,
+                ``,
+                `### Step 4: Compare`,
+                `1. Use \`compare_sketches\` with the original and improved sketch IDs`,
+                `2. Evaluate: did each intended improvement actually improve the piece?`,
+                `3. Note any unintended consequences \u2014 improvements in one aspect sometimes degrade another`,
+                ``,
+                `### Step 5: Document`,
+                `After all iterations:`,
+                `1. Update the improved sketch's philosophy field to document what changed and why`,
+                `2. Summarize the iteration journey: what was tried, what worked, what was learned`,
+                `3. If the original was better in some aspects, note what to preserve in future iterations`,
+                ``,
+                `## Guidelines`,
+                `- Be your own harshest (but fairest) critic \u2014 the goal is genuine improvement`,
+                `- Small, focused changes are better than sweeping rewrites`,
+                `- If a change doesn't work, revert it before trying the next improvement`,
+                `- The final piece should feel like a natural evolution, not a different sketch`,
+                `- Always pass your \`agent\` name and \`model\` identifier when calling tools that create or modify sketches`
+              ].join("\n")
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+function registerDevelopArtisticConcept(server, _state) {
+  server.prompt(
+    "develop-artistic-concept",
+    "Develop an artistic concept through a full studio workflow: concept planning, studies, development, critique, iteration, and documentation",
+    {
+      concept: import_zod.z.string().describe("The artistic concept or theme to explore"),
+      medium: import_zod.z.enum(["p5", "three", "glsl", "canvas2d", "svg"]).optional().describe("Preferred renderer/medium (default: p5)"),
+      depth: import_zod.z.enum(["quick", "standard", "deep"]).optional().describe("How deeply to explore: quick (3 studies), standard (6 studies), deep (9+ studies). Default: standard")
+    },
+    async (args) => {
+      const medium = args.medium ?? "p5";
+      const depth = args.depth ?? "standard";
+      const studyCount = depth === "quick" ? 3 : depth === "deep" ? 9 : 6;
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Develop the following artistic concept through a full studio workflow.`,
+                ``,
+                `## Concept`,
+                `${args.concept}`,
+                ``,
+                `## Medium: ${medium}`,
+                `## Depth: ${depth} (${studyCount} studies)`,
+                ``,
+                `## Phase 1: Conceptual Planning`,
+                `1. Use \`develop_concept\` with your concept and medium to get a structured plan`,
+                `2. Define: mood, color strategy, compositional approach, and relevant skills`,
+                `3. Create a series with \`create_series\` \u2014 write a narrative and intent statement`,
+                ``,
+                `## Phase 2: Thumbnail Studies`,
+                `1. Create ${studyCount} quick study-level sketches with \`create_sketch\` (compositionLevel: "study")`,
+                `2. Each study should explore a different aspect of the concept:`,
+                `   - Vary composition (centered vs asymmetric vs edge-driven)`,
+                `   - Vary color (warm vs cool, saturated vs muted)`,
+                `   - Vary rhythm (regular vs progressive vs chaotic)`,
+                `   - Vary density (sparse vs dense vs gradient)`,
+                `3. Use small canvases (600x600 or similar) \u2014 studies are fast explorations`,
+                `4. Use \`capture_batch\` to see all studies at once`,
+                ``,
+                `## Phase 3: Selection & Critique`,
+                `1. Use \`series_summary\` to see the full set of studies with screenshots`,
+                `2. Use \`critique_sketch\` on the 2-3 most promising studies`,
+                `3. Identify which studies best capture the concept's intent`,
+                `4. Note what works in each \u2014 composition choices, color relationships, rhythmic qualities`,
+                ``,
+                `## Phase 4: Development`,
+                `1. Use \`promote_sketch\` to advance the best 1-2 studies to "drafts" stage`,
+                `2. Refine the promoted sketches:`,
+                `   - Add more parameters for fine control`,
+                `   - Develop the color palette with more nuance`,
+                `   - Strengthen compositional structure`,
+                `   - Load relevant skills with \`load_skill\` for guidance`,
+                `3. Use \`critique_sketch\` after each round of changes`,
+                ``,
+                `## Phase 5: Critique & Iteration`,
+                `1. Use \`compare_sketches\` to evaluate drafts against each other`,
+                `2. For the strongest draft, use the critique-and-iterate workflow:`,
+                `   - Critique \u2192 identify improvements \u2192 fork \u2192 apply \u2192 compare`,
+                `3. Promote the best iteration to "refinements" stage`,
+                `4. Continue refining until the piece feels resolved`,
+                ``,
+                `## Phase 6: Final & Documentation`,
+                `1. Promote the best refinement to "finals" stage (canvas will upscale)`,
+                `2. Update the philosophy field with the full artistic statement`,
+                `3. Use \`series_summary\` to capture the complete progression`,
+                `4. Document: what was the concept? How did it evolve? What was discovered?`,
+                ``,
+                `## Guidelines`,
+                `- Each phase should feel like a natural progression, not a checklist`,
+                `- Trust the studies \u2014 let unexpected results redirect the exploration`,
+                `- The final piece should feel inevitable, like it couldn't have been any other way`,
+                `- Always pass your \`agent\` name and \`model\` identifier when calling tools`,
+                `- Use \`auto_arrange\` periodically to keep the workspace organized`
               ].join("\n")
             }
           }
@@ -3757,6 +5195,83 @@ function registerApplyDesignTheory(server, state) {
     }
   );
 }
+function registerStudyReference(server, _state) {
+  server.prompt(
+    "study-reference",
+    "Study a reference image: analyze it, identify key qualities, create a generative study sketch inspired by it, and document learnings",
+    {
+      referenceId: import_zod.z.string().describe("ID of the reference to study"),
+      seriesId: import_zod.z.string().optional().describe("Series the reference belongs to (also where the study sketch will be added)"),
+      sketchId: import_zod.z.string().optional().describe("Sketch the reference belongs to"),
+      medium: import_zod.z.enum(["p5", "three", "glsl", "canvas2d", "svg"]).optional().describe("Renderer for the study sketch (default: p5)"),
+      focus: import_zod.z.string().optional().describe("Specific quality to focus on: composition, palette, rhythm, mood, technique, or a custom focus")
+    },
+    async (args) => {
+      const medium = args.medium ?? "p5";
+      const focus = args.focus ?? "all key qualities";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Study a reference image and create a generative art sketch inspired by it.`,
+                ``,
+                `## Reference: ${args.referenceId}`,
+                args.seriesId ? `## Series: ${args.seriesId}` : "",
+                `## Medium: ${medium}`,
+                `## Focus: ${focus}`,
+                ``,
+                `## Phase 1: Analyze the Reference`,
+                `1. Use \`analyze_reference\` with referenceId="${args.referenceId}"${args.seriesId ? ` seriesId="${args.seriesId}"` : ""}${args.sketchId ? ` sketchId="${args.sketchId}"` : ""} to get the analysis framework and image`,
+                `2. Study the image carefully using the framework prompts`,
+                `3. Answer each category: composition, palette, rhythm, mood, technique`,
+                `4. Use \`update_reference_analysis\` to save your structured analysis`,
+                ``,
+                `## Phase 2: Extract Key Qualities`,
+                `From your analysis, identify 2-4 key qualities that are most interesting for generative art:`,
+                `- These could be: a specific compositional structure, a color relationship, a rhythmic pattern, a mood quality`,
+                `- Focus on qualities that can be *translated* into code, not literally replicated`,
+                `- Consider what makes this reference compelling \u2014 what would be lost if you removed each quality?`,
+                ``,
+                `## Phase 3: Extract Palette`,
+                `1. Use \`extract_palette\` to study the reference's color strategy`,
+                `2. Extract 5-8 hex colors that capture the essential palette`,
+                `3. Save the palette in the reference analysis`,
+                ``,
+                `## Phase 4: Create Study Sketch`,
+                `1. Use \`create_sketch\` with compositionLevel: "study" to create a quick exploration`,
+                `2. Translate the key qualities into generative parameters and algorithm choices:`,
+                `   - Composition \u2192 element placement, density distribution, negative space`,
+                `   - Palette \u2192 color definitions, themes derived from the reference palette`,
+                `   - Rhythm \u2192 repetition patterns, interval variations, scale relationships`,
+                `   - Mood \u2192 overall tone, animation speed, mark quality`,
+                `   - Technique \u2192 rendering approach, layering, transparency`,
+                `3. Add the reference to the sketch with \`add_reference\``,
+                `4. Document in the philosophy field how the reference influenced the study`,
+                `5. Use \`capture_screenshot\` to verify the result`,
+                ``,
+                `## Phase 5: Compare & Document`,
+                `1. Use \`analyze_reference\` again to see the reference alongside your study`,
+                `2. Evaluate: which qualities translated well? Which were lost or transformed?`,
+                `3. Note what you learned \u2014 what worked, what surprised you, what to try next`,
+                `4. Update the study sketch's philosophy with these insights`,
+                ``,
+                `## Guidelines`,
+                `- The goal is *inspiration*, not replication \u2014 a study should be recognizably generative`,
+                `- A good study captures the *spirit* of the reference while being authentically algorithmic`,
+                `- Use small canvases (600x600) \u2014 studies are explorations, not finished pieces`,
+                `- If the reference suggests multiple interesting directions, create multiple studies`,
+                `- Always pass your \`agent\` name and \`model\` identifier when calling tools`
+              ].filter(Boolean).join("\n")
+            }
+          }
+        ]
+      };
+    }
+  );
+}
 
 // src/server.ts
 function jsonResult(data) {
@@ -3771,22 +5286,36 @@ function toolError(message) {
   };
 }
 async function initializePluginRegistry() {
-  const registry4 = (0, import_core12.createPluginRegistry)({
+  const registry5 = (0, import_core15.createPluginRegistry)({
     surface: "mcp",
     supportsInteractiveTools: false,
     supportsRendering: false
   });
-  await registry4.register(import_plugin_typography.default);
-  await registry4.register(import_plugin_filters.default);
-  await registry4.register(import_plugin_shapes.default);
-  await registry4.register(import_plugin_layout_guides.default);
-  return registry4;
+  await registry5.register(import_plugin_typography.default);
+  await registry5.register(import_plugin_filters.default);
+  await registry5.register(import_plugin_shapes.default);
+  await registry5.register(import_plugin_layout_guides.default);
+  await registry5.register(import_plugin_painting.default);
+  await registry5.register(import_plugin_textures.default);
+  await registry5.register(import_plugin_animation.default);
+  await registry5.register(import_plugin_color_adjust.default);
+  await registry5.register(import_plugin_compositing.default);
+  await registry5.register(import_plugin_construction.default);
+  await registry5.register(import_plugin_distribution.default);
+  await registry5.register(import_plugin_figure.default);
+  await registry5.register(import_plugin_layout_composition.default);
+  await registry5.register(import_plugin_perspective.default);
+  await registry5.register(import_plugin_poses.default);
+  await registry5.register(import_plugin_styles.default);
+  await registry5.register(import_plugin_symbols.default);
+  await registry5.register(import_plugin_trace.default);
+  return registry5;
 }
 function createServer(state) {
   const server = new import_mcp.McpServer(
     {
       name: "@genart/mcp-server",
-      version: "0.3.0"
+      version: "0.4.0"
     },
     {
       capabilities: {
@@ -3796,9 +5325,9 @@ function createServer(state) {
       }
     }
   );
-  const registryReady = initializePluginRegistry().then((registry4) => {
-    state.pluginRegistry = registry4;
-    registerPluginMcpTools(server, registry4, state);
+  const registryReady = initializePluginRegistry().then((registry5) => {
+    state.pluginRegistry = registry5;
+    registerPluginMcpTools(server, registry5, state);
   });
   server._pluginsReady = registryReady;
   registerWorkspaceTools(server, state);
@@ -3813,6 +5342,9 @@ function createServer(state) {
   registerKnowledgeTools(server, state);
   registerDesignTools(server, state);
   registerCaptureTools(server, state);
+  registerCritiqueTools(server, state);
+  registerSeriesTools(server, state);
+  registerReferenceTools(server, state);
   registerExportTools(server, state);
   registerResources(server, state);
   registerPrompts(server, state);
@@ -4577,6 +6109,276 @@ function registerCaptureTools(server, state) {
     }
   );
 }
+function registerCritiqueTools(server, state) {
+  server.tool(
+    "critique_sketch",
+    "Capture a sketch screenshot and return a structured self-critique framework (questions, principles, pitfalls) per aspect. Severity calibrates to compositionLevel.",
+    {
+      sketchId: import_zod2.z.string().optional().describe("Sketch to critique (default: selected sketch)"),
+      aspects: import_zod2.z.array(import_zod2.z.enum(["composition", "color", "rhythm", "unity", "expression"])).optional().describe("Aspects to critique (default: all five)"),
+      previewSize: import_zod2.z.number().optional().describe("Max dimension for inline preview JPEG (default: 400)")
+    },
+    async (args) => {
+      try {
+        const result = await critiqueSketch(state, args);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.metadata, null, 2) },
+            { type: "image", data: result.previewJpegBase64, mimeType: "image/jpeg" }
+          ]
+        };
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "compare_sketches",
+    "Side-by-side capture of 2-4 sketches with a structured comparison framework across specified aspects.",
+    {
+      sketchIds: import_zod2.z.array(import_zod2.z.string()).describe("IDs of 2-4 sketches to compare"),
+      aspects: import_zod2.z.array(import_zod2.z.enum(["composition", "color", "rhythm", "unity", "expression"])).optional().describe("Aspects to compare (default: all five)"),
+      previewSize: import_zod2.z.number().optional().describe("Max dimension for inline preview JPEGs (default: 300)")
+    },
+    async (args) => {
+      try {
+        const result = await compareSketches(state, args);
+        const content = [
+          { type: "text", text: JSON.stringify(result.metadata, null, 2) }
+        ];
+        for (const preview of result.previews) {
+          content.push({
+            type: "text",
+            text: `--- Sketch: ${preview.sketchId} ---`
+          });
+          content.push({
+            type: "image",
+            data: preview.inlineJpegBase64,
+            mimeType: "image/jpeg"
+          });
+        }
+        return { content };
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+}
+function registerSeriesTools(server, state) {
+  server.tool(
+    "create_series",
+    "Create a new curated series of sketches with narrative, intent, and studio workflow stages",
+    {
+      label: import_zod2.z.string().describe("Display label for the series"),
+      narrative: import_zod2.z.string().describe("Prose narrative describing the artistic exploration"),
+      intent: import_zod2.z.string().describe("Short statement of artistic intent"),
+      progression: import_zod2.z.string().optional().describe(
+        "Series progression type (e.g. 'linear', 'branching', 'iterative')"
+      ),
+      stages: import_zod2.z.array(import_zod2.z.enum(["studies", "drafts", "refinements", "finals"])).optional().describe(
+        "Ordered stages in the studio workflow (default: all four)"
+      ),
+      sketchFiles: import_zod2.z.array(import_zod2.z.string()).optional().describe("File names of existing sketches to include")
+    },
+    async (args) => {
+      try {
+        const result = await createSeries(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "develop_concept",
+    "Generate a structured concept development plan with mood, palette, composition, skills, and series structure recommendations",
+    {
+      concept: import_zod2.z.string().describe("The artistic concept or theme to develop"),
+      medium: import_zod2.z.enum(["p5", "three", "glsl", "canvas2d", "svg"]).optional().describe("Preferred renderer/medium (default: p5)")
+    },
+    async (args) => {
+      try {
+        const result = await developConcept(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "series_summary",
+    "Capture all sketches in a series with narrative context for holistic evaluation",
+    {
+      seriesId: import_zod2.z.string().describe("ID of the series to summarize"),
+      captureScreenshots: import_zod2.z.boolean().optional().describe("Capture screenshots of each sketch (default: true)"),
+      previewSize: import_zod2.z.number().optional().describe("Preview image size in pixels (default: 300)")
+    },
+    async (args) => {
+      try {
+        const result = await seriesSummary(state, args);
+        const content = [
+          { type: "text", text: JSON.stringify(result.metadata, null, 2) }
+        ];
+        if (result.previews) {
+          for (const preview of result.previews) {
+            content.push({
+              type: "image",
+              data: preview.inlineJpegBase64,
+              mimeType: "image/jpeg"
+            });
+          }
+        }
+        return { content };
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "promote_sketch",
+    "Promote a sketch to the next studio workflow stage \u2014 fork, upscale canvas, update compositionLevel, and add to series",
+    {
+      sketchId: import_zod2.z.string().describe("ID of the sketch to promote"),
+      toStage: import_zod2.z.enum(["studies", "drafts", "refinements", "finals"]).describe("Target stage to promote to"),
+      seriesId: import_zod2.z.string().optional().describe("Series to add the promoted sketch to"),
+      newId: import_zod2.z.string().optional().describe(
+        "URL-safe kebab-case ID for the promoted sketch (default: auto-generated)"
+      ),
+      title: import_zod2.z.string().optional().describe("Title for the promoted sketch (default: auto-generated)"),
+      agent: import_zod2.z.string().optional().describe("CLI agent name"),
+      model: import_zod2.z.string().optional().describe("AI model identifier")
+    },
+    async (args) => {
+      try {
+        const result = await promoteSketch(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+}
+function registerReferenceTools(server, state) {
+  server.tool(
+    "add_reference",
+    "Import an image as a reference for inspiration. Copies the image to the workspace references/ directory and attaches it to a series or sketch.",
+    {
+      image: import_zod2.z.string().describe("Path to the reference image file"),
+      type: import_zod2.z.enum(["image", "artwork", "photograph", "texture", "palette"]).optional().describe("Reference type (default: image)"),
+      source: import_zod2.z.string().optional().describe("Source attribution (artist, URL, collection)"),
+      seriesId: import_zod2.z.string().optional().describe("Series to attach the reference to"),
+      sketchId: import_zod2.z.string().optional().describe("Sketch to attach the reference to"),
+      id: import_zod2.z.string().optional().describe("Custom reference ID (default: derived from filename)")
+    },
+    async (args) => {
+      try {
+        const result = await addReference(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "analyze_reference",
+    "Return a structured analysis framework for a reference image, with the image for visual inspection. The agent fills in the analysis using the framework prompts.",
+    {
+      referenceId: import_zod2.z.string().describe("ID of the reference to analyze"),
+      seriesId: import_zod2.z.string().optional().describe("Series the reference belongs to (speeds up lookup)"),
+      sketchId: import_zod2.z.string().optional().describe("Sketch the reference belongs to (speeds up lookup)"),
+      previewSize: import_zod2.z.number().optional().describe("Max dimension for preview image (default: native)")
+    },
+    async (args) => {
+      try {
+        const result = await analyzeReference(state, args);
+        const content = [
+          { type: "text", text: JSON.stringify(result.metadata, null, 2) }
+        ];
+        if (result.previewJpegBase64) {
+          const ext = (result.metadata["path"] ?? ".png").split(".").pop() ?? "png";
+          const mimeMap = {
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            webp: "image/webp",
+            svg: "image/svg+xml"
+          };
+          content.push({
+            type: "image",
+            data: result.previewJpegBase64,
+            mimeType: mimeMap[ext] ?? "image/png"
+          });
+        }
+        return { content };
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "update_reference_analysis",
+    "Save a structured analysis (composition, palette, rhythm, mood, technique) back to a reference after studying it with analyze_reference.",
+    {
+      referenceId: import_zod2.z.string().describe("ID of the reference to update"),
+      seriesId: import_zod2.z.string().optional().describe("Series the reference belongs to"),
+      sketchId: import_zod2.z.string().optional().describe("Sketch the reference belongs to"),
+      analysis: import_zod2.z.object({
+        composition: import_zod2.z.string().optional().describe("Compositional structure observations"),
+        palette: import_zod2.z.array(import_zod2.z.string()).optional().describe("Dominant colors as hex values"),
+        rhythm: import_zod2.z.string().optional().describe("Visual rhythm and pattern observations"),
+        mood: import_zod2.z.string().optional().describe("Mood and emotional qualities"),
+        technique: import_zod2.z.string().optional().describe("Technique and medium observations"),
+        keyQualities: import_zod2.z.array(import_zod2.z.string()).optional().describe("Key qualities worth studying")
+      }).describe("Structured analysis to save")
+    },
+    async (args) => {
+      try {
+        const result = await updateReferenceAnalysis(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "extract_palette",
+    "Return a reference image for color palette extraction, with guidelines for identifying dominant colors. The agent extracts hex colors visually.",
+    {
+      referenceId: import_zod2.z.string().describe("ID of the reference to extract palette from"),
+      seriesId: import_zod2.z.string().optional().describe("Series the reference belongs to"),
+      sketchId: import_zod2.z.string().optional().describe("Sketch the reference belongs to"),
+      count: import_zod2.z.number().optional().describe("Number of colors to extract (default: 6)")
+    },
+    async (args) => {
+      try {
+        const result = await extractPalette(state, args);
+        const content = [
+          { type: "text", text: JSON.stringify(result.metadata, null, 2) }
+        ];
+        if (result.previewJpegBase64) {
+          const ext = (result.metadata["path"] ?? ".png").split(".").pop() ?? "png";
+          const mimeMap = {
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            webp: "image/webp",
+            svg: "image/svg+xml"
+          };
+          content.push({
+            type: "image",
+            data: result.previewJpegBase64,
+            mimeType: mimeMap[ext] ?? "image/png"
+          });
+        }
+        return { content };
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+}
 function registerExportTools(server, state) {
   server.tool(
     "export_sketch",
@@ -4841,7 +6643,7 @@ function registerDesignTools(server, state) {
     }
   );
 }
-function registerKnowledgeTools(server, _state) {
+function registerKnowledgeTools(server, state) {
   server.tool(
     "list_skills",
     "List all available design knowledge skills (Phase 5)",
@@ -4877,7 +6679,7 @@ function registerKnowledgeTools(server, _state) {
     "get_guidelines",
     "Return design guidelines and best practices for a topic (Phase 5)",
     {
-      topic: import_zod2.z.enum(["composition", "color", "parameters", "animation", "performance"]).describe("Guideline topic"),
+      topic: import_zod2.z.enum(["composition", "color", "process", "painting", "illustration", "parameters", "animation", "performance"]).describe("Guideline topic"),
       renderer: import_zod2.z.enum(["p5", "three", "glsl", "canvas2d", "svg"]).optional().describe("Renderer-specific guidance")
     },
     async (args) => {
@@ -4889,6 +6691,22 @@ function registerKnowledgeTools(server, _state) {
       }
     }
   );
+  server.tool(
+    "suggest_skills",
+    "Recommend relevant design skills based on sketch context and/or free-text description",
+    {
+      sketchId: import_zod2.z.string().optional().describe("ID of a loaded sketch to analyze for skill recommendations"),
+      context: import_zod2.z.string().optional().describe("Free-text description of what you're working on (e.g., 'atmospheric landscape with watercolor')")
+    },
+    async (args) => {
+      try {
+        const result = await suggestSkills(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
 }
 
 // src/index.ts