@goodandready/dsh-image-gen 0.11.39 → 0.11.40

package/lib/capabilities.js

@@ -0,0 +1,433 @@
+/**
+ * Capability Registry and Model Selector (#434)
+ * Provides comprehensive capability mapping, strict pre-flight validation,
+ * cost estimation, and recommendation for task-specific models and providers.
+ */
+
+export const CAPABILITY_REGISTRY = [
+  // Fal.ai models
+  {
+    provider: 'fal',
+    modelId: 'fal-ai/flux/dev',
+    displayName: 'FLUX.1 [dev]',
+    capabilities: ['txt2img', 'img2img', 'inpaint', 'high_res', 'text_rendering'],
+    maxResolution: 2048,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4', '21:9'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: true,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.025,
+    pricingSource: 'fal.ai/pricing (2026-09)',
+    verifiedDate: '2026-09-15',
+    tier: 'pro',
+  },
+  {
+    provider: 'fal',
+    modelId: 'fal-ai/flux/schnell',
+    displayName: 'FLUX.1 [schnell]',
+    capabilities: ['txt2img', 'text_rendering'],
+    maxResolution: 1024,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.003,
+    pricingSource: 'fal.ai/pricing (2026-09)',
+    verifiedDate: '2026-09-15',
+    tier: 'economy',
+  },
+  {
+    provider: 'fal',
+    modelId: 'fal-ai/flux-general/image-to-image',
+    displayName: 'FLUX.1 Image-to-Image',
+    capabilities: ['img2img', 'reference'],
+    maxResolution: 1536,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: true,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.03,
+    pricingSource: 'fal.ai/pricing (2026-09)',
+    verifiedDate: '2026-09-15',
+    tier: 'pro',
+  },
+  {
+    provider: 'fal',
+    modelId: 'fal-ai/recraft-v3',
+    displayName: 'Recraft v3',
+    capabilities: ['txt2img', 'vector', 'text_rendering', 'high_res'],
+    maxResolution: 2048,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.04,
+    pricingSource: 'fal.ai/pricing (2026-09)',
+    verifiedDate: '2026-09-15',
+    tier: 'pro',
+  },
+
+  // Google Gemini Imagen models
+  {
+    provider: 'gemini',
+    modelId: 'imagen-3.0-generate-002',
+    displayName: 'Google Imagen 3.0',
+    capabilities: ['txt2img', 'text_rendering', 'high_res'],
+    maxResolution: 2048,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.03,
+    pricingSource: 'ai.google.dev (2026-09)',
+    verifiedDate: '2026-09-01',
+    tier: 'pro',
+  },
+  {
+    provider: 'gemini',
+    modelId: 'imagen-3.0-capability-001',
+    displayName: 'Google Imagen 3.0 Editing',
+    capabilities: ['txt2img', 'img2img', 'inpaint', 'outpaint'],
+    maxResolution: 1536,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: true,
+      referenceConditioning: true,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.035,
+    pricingSource: 'ai.google.dev (2026-09)',
+    verifiedDate: '2026-09-01',
+    tier: 'pro',
+  },
+
+  // Replicate models
+  {
+    provider: 'replicate',
+    modelId: 'black-forest-labs/flux-1.1-pro',
+    displayName: 'Replicate FLUX 1.1 Pro',
+    capabilities: ['txt2img', 'text_rendering', 'high_res'],
+    maxResolution: 2048,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4', '21:9'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.04,
+    pricingSource: 'replicate.com/pricing',
+    verifiedDate: '2026-09-10',
+    tier: 'pro',
+  },
+  {
+    provider: 'replicate',
+    modelId: 'stability-ai/sdxl',
+    displayName: 'Replicate SDXL',
+    capabilities: ['txt2img', 'img2img', 'inpaint'],
+    maxResolution: 1024,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+    features: {
+      textRendering: false,
+      facePreservation: false,
+      maskInpainting: true,
+      referenceConditioning: true,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.018,
+    pricingSource: 'replicate.com/pricing',
+    verifiedDate: '2026-09-10',
+    tier: 'economy',
+  },
+
+  // Local (ComfyUI / Stable Diffusion / A1111)
+  {
+    provider: 'local',
+    modelId: 'sdxl_base',
+    displayName: 'Local ComfyUI SDXL Base',
+    capabilities: ['txt2img', 'img2img', 'inpaint', 'high_res', 'face_preservation', 'controlnet'],
+    maxResolution: 2048,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4', '21:9'],
+    features: {
+      textRendering: false,
+      facePreservation: true,
+      maskInpainting: true,
+      referenceConditioning: true,
+      controlnet: true,
+    },
+    estimatedCostUSD: 0.0,
+    pricingSource: 'local-hardware (0 USD)',
+    verifiedDate: '2026-10-01',
+    tier: 'free',
+  },
+  {
+    provider: 'local',
+    modelId: 'flux_local',
+    displayName: 'Local ComfyUI FLUX',
+    capabilities: ['txt2img', 'img2img', 'text_rendering', 'high_res'],
+    maxResolution: 2048,
+    supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4', '21:9'],
+    features: {
+      textRendering: true,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.0,
+    pricingSource: 'local-hardware (0 USD)',
+    verifiedDate: '2026-10-01',
+    tier: 'free',
+  },
+
+  // Seedream backend
+  {
+    provider: 'seedream',
+    modelId: 'seedream-v2',
+    displayName: 'Seedream v2',
+    capabilities: ['txt2img', 'img2img'],
+    maxResolution: 1024,
+    supportedAspectRatios: ['1:1', '16:9', '9:16'],
+    features: {
+      textRendering: false,
+      facePreservation: false,
+      maskInpainting: false,
+      referenceConditioning: false,
+      controlnet: false,
+    },
+    estimatedCostUSD: 0.015,
+    pricingSource: 'seedream API',
+    verifiedDate: '2026-08-20',
+    tier: 'economy',
+  },
+]
+
+/**
+ * Returns the entire capability registry with metadata.
+ */
+export function getCapabilityRegistry() {
+  return [...CAPABILITY_REGISTRY]
+}
+
+/**
+ * Filter models based on required operations and features.
+ * Unknown capabilities are strictly treated as unsupported.
+ */
+export function filterModelsByCapabilities(requirements = {}, options = {}) {
+  const {
+    operations = [],
+    textRendering = false,
+    facePreservation = false,
+    maskInpainting = false,
+    referenceConditioning = false,
+    controlnet = false,
+    minResolution = 0,
+    aspectRatio = null,
+  } = requirements
+
+  const maxCost = requirements.maxCost ?? requirements.maxCostUSD ?? Infinity
+
+  const configuredProviders = Array.isArray(options.configuredProviders)
+    ? options.configuredProviders
+    : (Array.isArray(requirements.configuredProviders) ? requirements.configuredProviders : null)
+
+  return CAPABILITY_REGISTRY.map((model) => {
+    const missing = []
+
+    if (configuredProviders && !configuredProviders.includes(model.provider)) {
+      missing.push(`provider_unconfigured:${model.provider}`)
+    }
+
+    for (const op of operations) {
+      if (!model.capabilities.includes(op)) {
+        missing.push(`operation:${op}`)
+      }
+    }
+
+    if (textRendering && !model.features.textRendering) {
+      missing.push('feature:textRendering')
+    }
+    if (facePreservation && !model.features.facePreservation) {
+      missing.push('feature:facePreservation')
+    }
+    if (maskInpainting && !model.features.maskInpainting) {
+      missing.push('feature:maskInpainting')
+    }
+    if (referenceConditioning && !model.features.referenceConditioning) {
+      missing.push('feature:referenceConditioning')
+    }
+    if (controlnet && !model.features.controlnet) {
+      missing.push('feature:controlnet')
+    }
+
+    if (minResolution > 0 && model.maxResolution < minResolution) {
+      missing.push(`resolution:${model.maxResolution}<${minResolution}`)
+    }
+
+    if (aspectRatio && !model.supportedAspectRatios.includes(aspectRatio)) {
+      missing.push(`aspectRatio:${aspectRatio}`)
+    }
+
+    if (model.estimatedCostUSD > maxCost) {
+      missing.push(`cost:${model.estimatedCostUSD}>${maxCost}`)
+    }
+
+    return {
+      ...model,
+      compatible: missing.length === 0,
+      missingCapabilities: missing,
+    }
+  })
+}
+
+/**
+ * Evaluates requirements and recommends the best model.
+ */
+export function recommendModelForTask(requirements = {}, options = {}) {
+  const evaluated = filterModelsByCapabilities(requirements, options)
+  const compatible = evaluated.filter((m) => m.compatible)
+
+  if (compatible.length === 0) {
+    const partial = [...evaluated].sort((a, b) => a.missingCapabilities.length - b.missingCapabilities.length)
+    return {
+      ok: false,
+      recommended: null,
+      message: 'No model in registry completely satisfies all specified task requirements.',
+      alternatives: partial.slice(0, 3).map((m) => ({
+        provider: m.provider,
+        modelId: m.modelId,
+        displayName: m.displayName,
+        missing: m.missingCapabilities,
+        estimatedCostUSD: m.estimatedCostUSD,
+      })),
+    }
+  }
+
+  // Rank compatible models:
+  // 1. Configured providers preferred
+  // 2. Cost-effectiveness
+  // 3. Higher max resolution
+  compatible.sort((a, b) => {
+    if (a.estimatedCostUSD !== b.estimatedCostUSD) {
+      return a.estimatedCostUSD - b.estimatedCostUSD
+    }
+    return b.maxResolution - a.maxResolution
+  })
+
+  const best = compatible[0]
+  const reasons = []
+  if (best.estimatedCostUSD === 0) reasons.push('Zero API cost (local backend)')
+  else reasons.push(`Estimated cost: $${best.estimatedCostUSD.toFixed(3)}`)
+  if (best.features.textRendering && requirements.textRendering) reasons.push('Native high-precision text rendering')
+  if (best.features.facePreservation && requirements.facePreservation) reasons.push('Facial identity retention supported')
+  if (best.features.maskInpainting && requirements.maskInpainting) reasons.push('Pixel-accurate mask inpainting supported')
+
+  return {
+    ok: true,
+    recommended: best,
+    recommendationReason: reasons.join('; '),
+    allCompatibleCount: compatible.length,
+    alternatives: compatible.slice(1, 4).map((m) => ({
+      provider: m.provider,
+      modelId: m.modelId,
+      displayName: m.displayName,
+      estimatedCostUSD: m.estimatedCostUSD,
+    })),
+  }
+}
+
+/**
+ * Pre-flight validation before provider dispatch (#434).
+ * Rejects unsupported capabilities BEFORE submitting to provider to avoid wasting credits or losing inputs.
+ */
+export function validateModelCapability(provider, modelId, requestedFeatures = {}) {
+  const model = CAPABILITY_REGISTRY.find(
+    (m) => m.provider === provider && (m.modelId === modelId || !modelId)
+  )
+
+  if (!model) {
+    // Unknown model/provider: return strict unknown warning
+    return {
+      valid: false,
+      status: 'unknown_model',
+      reason: `Provider "${provider}" with model "${modelId || 'default'}" is not documented in capability registry.`,
+    }
+  }
+
+  const {
+    operation,
+    requiresMask,
+    requiresReference,
+    requiresFacePreservation,
+    requiresTextRender,
+  } = requestedFeatures
+
+  if (operation && !model.capabilities.includes(operation)) {
+    return {
+      valid: false,
+      status: 'unsupported_operation',
+      reason: `Operation "${operation}" is not supported by model "${model.displayName}" (${model.provider}).`,
+    }
+  }
+
+  if (requiresMask && !model.features.maskInpainting) {
+    return {
+      valid: false,
+      status: 'unsupported_feature',
+      reason: `Mask inpainting is requested but not supported by "${model.displayName}". Discarding mask would corrupt generation.`,
+    }
+  }
+
+  if (requiresReference && !model.features.referenceConditioning && !model.capabilities.includes('img2img')) {
+    return {
+      valid: false,
+      status: 'unsupported_feature',
+      reason: `Reference image conditioning is requested but not supported by "${model.displayName}".`,
+    }
+  }
+
+  if (requiresFacePreservation && !model.features.facePreservation) {
+    return {
+      valid: false,
+      status: 'unsupported_feature',
+      reason: `Face preservation identity transfer is requested but not supported by "${model.displayName}".`,
+    }
+  }
+
+  if (requiresTextRender && !model.features.textRendering) {
+    return {
+      valid: false,
+      status: 'unsupported_feature',
+      reason: `High-fidelity text rendering is required but "${model.displayName}" lacks native text layout capabilities.`,
+    }
+  }
+
+  return {
+    valid: true,
+    status: 'supported',
+    model,
+  }
+}

package/lib/client.js

@@ -360,6 +360,7 @@ window.__ModuleLoader__.load({
       { field: 'toolsetProcessing', spec: booleanField('toolsetProcessing'), kind: 'select', options: ['true', 'false'], labelKey: 'f.toolsetProcessing', hintKey: 'f.toolsetProcessingHint', tab: 'general' },
       { field: 'toolsetFrontend', spec: booleanField('toolsetFrontend'), kind: 'select', options: ['true', 'false'], labelKey: 'f.toolsetFrontend', hintKey: 'f.toolsetFrontendHint', tab: 'general' },
       { field: 'toolsetCreative', spec: booleanField('toolsetCreative'), kind: 'select', options: ['true', 'false'], labelKey: 'f.toolsetCreative', hintKey: 'f.toolsetCreativeHint', tab: 'general' },
+      { field: 'activeProjectProfile', spec: selectField('activeProjectProfile', ['', 'cyberpunk_neon', 'minimal_nordic', 'corporate_editorial']), kind: 'select', options: ['', 'cyberpunk_neon', 'minimal_nordic', 'corporate_editorial'], labelKey: 'f.activeProjectProfile', hintKey: 'f.activeProjectProfileHint', tab: 'general' },
 
       // Provider: FAL
       { field: 'model', spec: textField('model'), kind: 'text', labelKey: 'f.model', hintKey: 'f.modelHint', placeholderKey: 'p.model', when: ['fal'], tab: 'provider' },
@@ -2878,6 +2879,8 @@ window.__ModuleLoader__.load({
       'vault.title': 'Asset Browser & Vault',
       'f.comfyTemplate': 'ComfyUI Workflow Template',
       'f.comfyTemplateHint': 'Pre-vetted workflow template (e.g. SDXL txt2img, img2img, InstantID face transfer, RealESRGAN upscaler).',
+      'f.activeProjectProfile': 'Active Project Profile',
+      'f.activeProjectProfileHint': 'Select a saved visual profile (palette, style, format) to consistently apply across generations (#435).',
     }
     const zh = {
       'card.actionRemoveBg': '移除背景',
@@ -3187,6 +3190,8 @@ window.__ModuleLoader__.load({
       'vault.title': '图像素材库与浏览器',
       'f.comfyTemplate': 'ComfyUI 工作流模板',
       'f.comfyTemplateHint': '经过验证的预设工作流模板（例如 SDXL 文生图、图生图、InstantID 人脸迁移、RealESRGAN 放大器）。',
+      'f.activeProjectProfile': '活动项目视觉配置',
+      'f.activeProjectProfileHint': '选择已保存的项目视觉配置（调色板、风格、格式），跨多次生成统一应用 (#435)。',
     }
     // Dual compatibility with DSH 0.1.5-rc.3 (settingsScope) and 0.1.6+ (configForms) (#291, #295)
     const inject = ['slots', 'locale', 'sessions']

package/lib/config-schema.js

@@ -220,6 +220,11 @@ export const Config = z.object({
     .description('Vetted ComfyUI workflow template identifier (e.g. "txt2img_sdxl", "img2img_sdxl", "face_instantid", "upscale_esrgan").')
     .default('')
     .volatile(),
+  activeProjectProfile: z
+    .string()
+    .description('Active project visual profile for continuous multi-image styling (#435). One of: "", "cyberpunk_neon", "minimal_nordic", "corporate_editorial".')
+    .default('')
+    .volatile(),
   comfyWorkflowJson: z
     .string()
     .description('Custom ComfyUI API workflow JSON template with {{prompt}}, {{seed}}, etc. placeholders.')

package/lib/index.js

@@ -50,6 +50,8 @@ import { clearAllAnchors } from './anchor-helpers.js'
 import { clearSpendReservations } from './cost-meter.js'
 import { getAllRecipes, getRecipe } from './recipes.js'
 import { getComfyTemplates, getComfyTemplate, createComfyDependencyValidator } from './comfy-catalog.js'
+import { getCapabilityRegistry, filterModelsByCapabilities, recommendModelForTask } from './capabilities.js'
+import { getAllProjectProfiles, saveCustomProfile, deleteCustomProfile } from './project-profiles.js'
 import { resetLoopGuard, getLoopGuardState } from './loop-guard.js'
 import { Config, plainConfig, volatileConfig, publicConfig, ensureConfig } from './config-schema.js'
 import { resolveSource } from './resolve-source.js'
@@ -465,6 +467,49 @@ export function apply(ctx, rawConfig) {
     },
   }), 'dsh-image-gen: comfy templates route')
 
+  // Capabilities route (#434)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/capabilities',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') {
+        res.writeHead(405, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'GET only' }))
+        return
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ ok: true, registry: getCapabilityRegistry() }))
+    },
+  }), 'dsh-image-gen: capabilities route')
+
+  // Project profiles route (#435)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/profiles',
+    handler: async (req, res) => {
+      if (req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: true, profiles: getAllProjectProfiles() }))
+        return
+      }
+      if (req.method === 'POST') {
+        try {
+          const body = await readBoundedRequestBody(req, 1024 * 1024)
+          const data = JSON.parse(body.toString('utf8'))
+          const saved = saveCustomProfile(data)
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: true, profile: saved }))
+        } catch (err) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: err.message }))
+        }
+        return
+      }
+      res.writeHead(405, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'GET or POST only' }))
+    },
+  }), 'dsh-image-gen: project profiles route')
+
   // Live events route (#379)
   registerLiveProgressRoutes(ctx)
 

package/lib/project-profiles.js

@@ -0,0 +1,234 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+/**
+ * Visual Project & Series Profiles (#435)
+ * Manages persistent project visual profiles with explicit scope,
+ * parameter cascade (defaults -> profile -> request), and immutable history tagging.
+ */
+
+export const BUILTIN_PROJECT_PROFILES = [
+  {
+    id: 'cyberpunk_neon',
+    name: 'Cyberpunk Neon',
+    version: '1.0.0',
+    description: 'High contrast neon lighting and dark futuristic styling.',
+    palette: ['#00f0ff', '#ff003c', '#ffe600', '#0a0a12'],
+    stylePrompt: 'cyberpunk aesthetic, volumetric atmospheric lighting, raytracing, sharp neon accents, highly detailed 8k',
+    negativePrompt: 'washed out, vintage, pastel, desaturated, noisy',
+    format: { size: '1024x1024', aspect: '1:1', format: 'webp' },
+    rules: {
+      background: 'dark cityscapes or moody interior',
+      typography: 'clean monospace or futuristic geometric',
+    },
+    allowedModels: ['fal-ai/flux/dev', 'sdxl_base'],
+    builtin: true,
+  },
+  {
+    id: 'minimal_nordic',
+    name: 'Scandinavian Minimalist',
+    version: '1.0.0',
+    description: 'Warm daylight, matte textures, and understated earthy tones.',
+    palette: ['#f4f1de', '#e07a5f', '#3d405b', '#81b29a'],
+    stylePrompt: 'scandinavian minimalism, clean composition, soft natural daylight, matte surfaces, earthy organic elegance',
+    negativePrompt: 'cluttered, neon, heavy shadows, oversaturated, glossy plastic',
+    format: { size: '1024x1024', aspect: '1:1', format: 'png' },
+    rules: {
+      background: 'plain textured warm neutral',
+      typography: 'light grotesque sans',
+    },
+    allowedModels: ['fal-ai/flux/dev', 'imagen-3.0-generate-002'],
+    builtin: true,
+  },
+  {
+    id: 'corporate_editorial',
+    name: 'Corporate Editorial',
+    version: '1.0.0',
+    description: 'High-end business magazine photography with crisp studio lighting.',
+    palette: ['#0f172a', '#3b82f6', '#64748b', '#f8fafc'],
+    stylePrompt: 'high-end corporate magazine editorial, crisp balanced studio lighting, premium commercial photography',
+    negativePrompt: 'anime, cartoon, oversaturated, exaggerated distortions, amateur',
+    format: { size: '1024x1024', aspect: '16:9', format: 'webp' },
+    rules: {
+      background: 'architectural soft blur or pristine studio',
+      typography: 'editorial serif / humanistic sans',
+    },
+    allowedModels: ['fal-ai/flux/dev', 'black-forest-labs/flux-1.1-pro'],
+    builtin: true,
+  },
+]
+
+export function getProfilesStoragePath(customPath) {
+  if (customPath) return customPath
+  if (process.env.DSH_PROJECT_PROFILES_PATH) return process.env.DSH_PROJECT_PROFILES_PATH
+  const home = os.homedir() || '/tmp'
+  return path.join(home, '.dsh', 'dsh-image-gen', 'project-profiles.json')
+}
+
+export function loadCustomProfiles(storagePath) {
+  const filePath = getProfilesStoragePath(storagePath)
+  try {
+    if (!fs.existsSync(filePath)) return []
+    const content = fs.readFileSync(filePath, 'utf8')
+    const parsed = JSON.parse(content)
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    return []
+  }
+}
+
+export function saveCustomProfile(profile, storagePath) {
+  if (!profile || typeof profile !== 'object') {
+    throw new Error('Invalid project profile: object required')
+  }
+  if (!profile.id || typeof profile.id !== 'string') {
+    throw new Error('Project profile requires a string "id"')
+  }
+  if (!profile.name || typeof profile.name !== 'string') {
+    throw new Error('Project profile requires a string "name"')
+  }
+
+  const filePath = getProfilesStoragePath(storagePath)
+  const dir = path.dirname(filePath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  const existing = loadCustomProfiles(storagePath)
+  const index = existing.findIndex((p) => p.id === profile.id)
+  const prepared = {
+    ...profile,
+    version: profile.version || '1.0.0',
+    builtin: false,
+    updatedAt: new Date().toISOString(),
+  }
+
+  if (index >= 0) {
+    existing[index] = prepared
+  } else {
+    existing.push(prepared)
+  }
+
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2), 'utf8')
+  return prepared
+}
+
+export function deleteCustomProfile(id, storagePath) {
+  const filePath = getProfilesStoragePath(storagePath)
+  const existing = loadCustomProfiles(storagePath)
+  const filtered = existing.filter((p) => p.id !== id)
+  if (filtered.length === existing.length) {
+    return false
+  }
+  fs.writeFileSync(filePath, JSON.stringify(filtered, null, 2), 'utf8')
+  return true
+}
+
+export function getAllProjectProfiles(storagePath) {
+  const custom = loadCustomProfiles(storagePath)
+  const customIds = new Set(custom.map((c) => c.id))
+  const builtins = BUILTIN_PROJECT_PROFILES.filter((b) => !customIds.has(b.id))
+  return [...builtins, ...custom]
+}
+
+export function getProjectProfileById(id, storagePath) {
+  if (!id) return null
+  const all = getAllProjectProfiles(storagePath)
+  return all.find((p) => p.id === id) || null
+}
+
+/**
+ * Parameter resolution cascade (#435):
+ * Priority: Request parameters > Project Profile > System Defaults.
+ * Returns effective params, provenance mapping, and immutable profile tag for history.
+ */
+export function resolveEffectiveParams(requestParams = {}, profileId = null, storagePath = null) {
+  const profile = profileId ? getProjectProfileById(profileId, storagePath) : null
+  const provenance = {}
+  const effective = {}
+
+  // 1. Defaults
+  const defaults = {
+    size: '1024x1024',
+    format: 'webp',
+    negativePrompt: '',
+    steps: 25,
+    cfg: 7,
+  }
+
+  for (const [key, val] of Object.entries(defaults)) {
+    effective[key] = val
+    provenance[key] = 'default'
+  }
+
+  // 2. Profile layer
+  if (profile) {
+    if (profile.format?.size) {
+      effective.size = profile.format.size
+      provenance.size = 'profile'
+    }
+    if (profile.format?.format) {
+      effective.format = profile.format.format
+      provenance.format = 'profile'
+    }
+    if (profile.negativePrompt) {
+      effective.negativePrompt = profile.negativePrompt
+      provenance.negativePrompt = 'profile'
+    }
+    if (profile.stylePrompt) {
+      effective.stylePrompt = profile.stylePrompt
+      provenance.stylePrompt = 'profile'
+    }
+    if (Array.isArray(profile.palette) && profile.palette.length > 0) {
+      effective.palette = [...profile.palette]
+      provenance.palette = 'profile'
+    }
+    if (profile.rules) {
+      effective.rules = { ...profile.rules }
+      provenance.rules = 'profile'
+    }
+  }
+
+  // 3. Request layer (highest precedence)
+  for (const [key, val] of Object.entries(requestParams)) {
+    if (val !== undefined && val !== null) {
+      if (key === 'prompt') {
+        // Synthesize prompt with profile style if available
+        if (effective.stylePrompt) {
+          effective.prompt = `${val}, ${effective.stylePrompt}`
+          provenance.prompt = 'request+profile'
+        } else {
+          effective.prompt = val
+          provenance.prompt = 'request'
+        }
+      } else if (key === 'negativePrompt') {
+        if (effective.negativePrompt && val) {
+          effective.negativePrompt = `${effective.negativePrompt}, ${val}`
+          provenance.negativePrompt = 'request+profile'
+        } else {
+          effective.negativePrompt = val || effective.negativePrompt
+          provenance.negativePrompt = 'request'
+        }
+      } else {
+        effective[key] = val
+        provenance[key] = 'request'
+      }
+    }
+  }
+
+  // Immutable applied profile metadata snapshot for history
+  const appliedProfile = profile
+    ? {
+        id: profile.id,
+        name: profile.name,
+        version: profile.version || '1.0.0',
+      }
+    : null
+
+  return {
+    effectiveParams: effective,
+    provenance,
+    appliedProfile,
+  }
+}

package/lib/register-tools.js

@@ -20,6 +20,8 @@ import { registerCharacterSheetTools } from './tools/character-sheet.js'
 import { registerVisionOcrTools } from './tools/vision-ocr.js'
 import { registerDiagramTools } from './tools/diagram.js'
 import { registerRecipeTools } from './tools/recipes.js'
+import { registerCapabilityTools } from './tools/capabilities.js'
+import { registerProjectProfileTools } from './tools/project-profiles.js'
 import {
   createLiveProgressSession,
   publishLiveProgress,
@@ -149,6 +151,12 @@ export function registerAllTools(ctx, deps) {
     if (Boolean(sets.recipes)) {
       registerRecipeTools(targetCtx, { ...deps, toolDispatcher })
     }
+    if (Boolean(sets.capabilities)) {
+      registerCapabilityTools(targetCtx, deps)
+    }
+    if (Boolean(sets.profiles)) {
+      registerProjectProfileTools(targetCtx, deps)
+    }
   }
 
   function dispose() {

package/lib/tools/capabilities.js

@@ -0,0 +1,139 @@
+import {
+  getCapabilityRegistry,
+  recommendModelForTask,
+  validateModelCapability,
+} from '../capabilities.js'
+
+/**
+ * Registers capability-based model selection tools (#434).
+ */
+export function registerCapabilityTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'select_image_model',
+    description: 'Recommends the best provider and model based on required task capabilities (text rendering, inpainting, face preservation, cost limits).',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        operations: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Required operations, e.g. ["txt2img", "inpaint", "img2img"].',
+        },
+        textRendering: {
+          type: 'boolean',
+          description: 'Whether native high-precision text rendering is required.',
+        },
+        facePreservation: {
+          type: 'boolean',
+          description: 'Whether facial identity likeness preservation is required.',
+        },
+        maskInpainting: {
+          type: 'boolean',
+          description: 'Whether pixel-accurate inpainting mask support is required.',
+        },
+        referenceConditioning: {
+          type: 'boolean',
+          description: 'Whether reference image guidance is required.',
+        },
+        controlnet: {
+          type: 'boolean',
+          description: 'Whether structural ControlNet guidance is required.',
+        },
+        minResolution: {
+          type: 'number',
+          description: 'Minimum resolution in pixels (e.g. 1024 or 2048).',
+        },
+        maxCostUSD: {
+          type: 'number',
+          description: 'Maximum estimated cost in USD per generation.',
+        },
+      },
+    },
+    output: {
+      render(args, value) {
+        if (!value?.ok) {
+          return [{ type: 'text', text: `Capability selection: ${value?.message || 'No matching model found.'}` }]
+        }
+        const rec = value.recommended
+        return [
+          {
+            type: 'text',
+            text: `Recommended Model: ${rec.displayName} (${rec.provider}/${rec.modelId})\nReason: ${value.recommendationReason}\nEstimated Cost: $${rec.estimatedCostUSD} (Source: ${rec.pricingSource})`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const requirements = {
+        operations: args.operations || [],
+        textRendering: Boolean(args.textRendering),
+        facePreservation: Boolean(args.facePreservation),
+        maskInpainting: Boolean(args.maskInpainting),
+        referenceConditioning: Boolean(args.referenceConditioning),
+        controlnet: Boolean(args.controlnet),
+        minResolution: args.minResolution || 0,
+        maxCost: args.maxCostUSD || Infinity,
+      }
+
+      // Check configured provider list from deps or runtime
+      const configuredProviders = deps.cfg?.provider ? [deps.cfg.provider] : null
+      return recommendModelForTask(requirements, { configuredProviders })
+    },
+  })
+
+  ctx.tools.register({
+    name: 'validate_model_features',
+    description: 'Pre-flight check if a model or provider supports specific generation features before running the task.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        provider: {
+          type: 'string',
+          description: 'Provider name (fal, gemini, replicate, local, seedream).',
+        },
+        modelId: {
+          type: 'string',
+          description: 'Specific model identifier.',
+        },
+        operation: {
+          type: 'string',
+          description: 'Requested operation (txt2img, img2img, inpaint).',
+        },
+        requiresMask: {
+          type: 'boolean',
+          description: 'Whether operation requires inpainting mask.',
+        },
+        requiresReference: {
+          type: 'boolean',
+          description: 'Whether operation requires reference image.',
+        },
+        requiresFacePreservation: {
+          type: 'boolean',
+          description: 'Whether operation requires face preservation.',
+        },
+        requiresTextRender: {
+          type: 'boolean',
+          description: 'Whether operation requires text rendering.',
+        },
+      },
+      required: ['provider'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: value.valid
+              ? `Validation PASSED for ${args.provider}: ${value.model?.displayName}`
+              : `Validation FAILED (${value.status}): ${value.reason}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      return validateModelCapability(args.provider, args.modelId, args)
+    },
+  })
+}

package/lib/tools/project-profiles.js

@@ -0,0 +1,139 @@
+import {
+  getAllProjectProfiles,
+  getProjectProfileById,
+  saveCustomProfile,
+  deleteCustomProfile,
+  resolveEffectiveParams,
+} from '../project-profiles.js'
+
+/**
+ * Registers project visual profile management tools (#435).
+ */
+export function registerProjectProfileTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'manage_project_profiles',
+    description: 'Manages visual project and series profiles (list, get, save, delete) for consistent styling across generation sets.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'get', 'save', 'delete'],
+          description: 'Action to perform: list all profiles, get by id, save (create/update), or delete.',
+        },
+        id: {
+          type: 'string',
+          description: 'Profile ID for get or delete actions.',
+        },
+        profile: {
+          type: 'object',
+          additionalProperties: true,
+          description: 'Profile specification object for save action (id, name, palette, stylePrompt, negativePrompt, format, rules).',
+        },
+      },
+      required: ['action'],
+    },
+    output: {
+      render(args, value) {
+        if (args.action === 'list') {
+          const list = Array.isArray(value) ? value : []
+          return [
+            {
+              type: 'text',
+              text: `Project Profiles (${list.length}):\n` +
+                list.map((p) => `- [${p.id}] ${p.name} (v${p.version || '1.0.0'}) ${p.builtin ? '(builtin)' : '(custom)'}`).join('\n'),
+            },
+          ]
+        }
+        if (args.action === 'get') {
+          return [
+            {
+              type: 'text',
+              text: value ? `Profile [${value.id}] ${value.name}:\nStyle: "${value.stylePrompt || ''}"\nPalette: ${(value.palette || []).join(', ')}` : 'Profile not found.',
+            },
+          ]
+        }
+        if (args.action === 'save') {
+          return [{ type: 'text', text: `Saved profile [${value?.id}] ${value?.name} successfully.` }]
+        }
+        if (args.action === 'delete') {
+          return [{ type: 'text', text: value ? `Deleted profile ${args.id}.` : `Profile ${args.id} not found or cannot be deleted.` }]
+        }
+        return [{ type: 'text', text: JSON.stringify(value) }]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.profilesPath || null
+      if (args.action === 'list') {
+        return getAllProjectProfiles(storagePath)
+      }
+      if (args.action === 'get') {
+        return getProjectProfileById(args.id, storagePath)
+      }
+      if (args.action === 'save') {
+        return saveCustomProfile(args.profile, storagePath)
+      }
+      if (args.action === 'delete') {
+        return deleteCustomProfile(args.id, storagePath)
+      }
+      throw new Error(`Unknown action: ${args.action}`)
+    },
+  })
+
+  ctx.tools.register({
+    name: 'resolve_project_profile_params',
+    description: 'Calculates effective generation parameters by cascading request overrides over a project visual profile and system defaults.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        profileId: {
+          type: 'string',
+          description: 'Identifier of the project visual profile.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'Specific image request prompt.',
+        },
+        negativePrompt: {
+          type: 'string',
+          description: 'Specific negative prompt overrides.',
+        },
+        size: {
+          type: 'string',
+          description: 'Specific dimensions (e.g. 1024x1024 or 1280x720).',
+        },
+        format: {
+          type: 'string',
+          description: 'Output format (webp, png, jpeg).',
+        },
+      },
+      required: ['profileId'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: `Effective Parameters for Profile [${value?.appliedProfile?.name || args.profileId}]:\n` +
+              `Prompt: "${value?.effectiveParams?.prompt || ''}"\n` +
+              `Negative: "${value?.effectiveParams?.negativePrompt || ''}"\n` +
+              `Dimensions: ${value?.effectiveParams?.size} (${value?.effectiveParams?.format})\n` +
+              `Provenance: ${JSON.stringify(value?.provenance || {})}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.profilesPath || null
+      const requestParams = {
+        prompt: args.prompt,
+        negativePrompt: args.negativePrompt,
+        size: args.size,
+        format: args.format,
+      }
+      return resolveEffectiveParams(requestParams, args.profileId, storagePath)
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-image-gen",
-  "version": "0.11.39",
+  "version": "0.11.40",
   "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers — the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
   "keywords": [
     "deepseek-harness",