@justin_666/square-couplets-master-skills 1.0.19 → 1.1.0

package/dist/constants.js

@@ -46,7 +46,7 @@ Lighting: soft studio lighting, gentle glow on gold details, museum-quality artw
 Composition: 
 The diamond-shaped Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping).
 The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off.
-The Doufang should occupy 95% of the image area, maximizing visual impact.
+The Doufang should occupy 90 - 95% of the image area, maximizing visual impact.
 Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
 
 Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio.
@@ -54,7 +54,7 @@ Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ra
 Framing requirements:
 - The entire diamond-shaped Doufang must be fully visible inside the image.
 - No part of the artwork is cut off, cropped, out of frame, or touching the image borders.
-- Minimal margins - the Doufang should fill most of the frame ( 95% of image area).
+- Minimal margins - the Doufang should fill most of the frame ( 90 - 95% of image area).
 
 Text requirements:
 - The Chinese characters must be clear, correct, readable.
@@ -144,7 +144,7 @@ Your generated "imagePrompt" must follow this logic:
 1. **Framing**:
    - The entire diamond Doufang must be fully contained within the 1:1 frame.
    - Minimal, elegant margins - just enough to prevent edge cropping (approximately 2-5% of frame width).
-   - The Doufang should fill most of the frame ( 95% of the image area).
+   - The Doufang should fill most of the frame ( 90 - 95% of the image area).
    - No cropping, no touching edges, no cut-off.
 2. **Text Quality**:
    - Calligraphy must be clear, professional, and correctly written.
@@ -157,7 +157,7 @@ Your generated "imagePrompt" must follow this logic:
 Composition: 
 The diamond-shaped Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (just enough to prevent edge cropping, approximately 2-5% of frame width).
 The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off.
-The Doufang should occupy 95% of the image area, maximizing visual impact.
+The Doufang should occupy 90 - 95% of the image area, maximizing visual impact.
 Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
 
 Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio.
@@ -165,7 +165,7 @@ Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ra
 Framing requirements:
 - The entire diamond-shaped Doufang must be fully visible inside the image.
 - No part of the artwork is cut off, cropped, out of frame, or touching the image borders.
-- Minimal margins - the Doufang should fill most of the frame ( 95% of image area).
+- Minimal margins - the Doufang should fill most of the frame ( 90 - 95% of image area).
 
 Text requirements:
 - The Chinese characters must be clear, correct, readable.
@@ -228,7 +228,7 @@ export const getSimpleUserInputPrompt = (userKeyword) => {
 export const getImageGenerationPromptWithReference = (basePrompt) => {
     return `${basePrompt}
 
-IMPORTANT COMPOSITION NOTE: The diamond-shaped Doufang should fill 95% of the frame with minimal margins (2-5% of frame width). Avoid excessive white space or wide margins. Maximize the visual impact by making the Doufang artwork occupy most of the image area.
+IMPORTANT COMPOSITION NOTE: The diamond-shaped Doufang should fill 90 - 95% of the frame with minimal margins (2-5% of frame width). Avoid excessive white space or wide margins. Maximize the visual impact by making the Doufang artwork occupy most of the image area.
 
 Note: The reference image provided above should be used as a visual style guide. Follow the style, color palette, and artistic approach described in the prompt, which was generated based on analysis of this reference image.`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justin_666/square-couplets-master-skills",
-  "version": "1.0.19",
+  "version": "1.1.0",
   "description": "Claude Agent Skills for generating Chinese New Year Doufang (diamond-shaped couplet) artwork using Google Gemini AI",
   "type": "module",
   "main": "bin/doufang-skills.js",

package/skills/generate-doufang-image/index.js

@@ -5,105 +5,35 @@
  * Can be called directly by agents or users
  */
 
-import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
-import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
-import { execSync } from 'child_process';
-import { createRequire } from 'module';
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import {
+  getProjectRoot,
+  loadEnvironmentVariables,
+  findServicesPath,
+  getApiKey,
+  showVersion,
+  loadReferenceImage,
+  importServiceModule,
+  createProgressSpinner
+} from '../shared/utils.js';
+
+// Initialize
+const projectRoot = getProjectRoot(import.meta.url);
 
-// Resolve project root and service path
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const skillDir = resolve(__dirname);
-const projectRoot = resolve(skillDir, '../..');
-
-// Try to find services directory
-function findServicesPath() {
-  // Get npm global prefix to find globally installed packages
-  let globalPrefix = null;
-  try {
-    globalPrefix = execSync('npm config get prefix', { encoding: 'utf-8' }).trim();
-  } catch (e) {
-    // Ignore error, try other methods
-  }
-  
-  // Try to resolve package location using createRequire (works in ES modules)
-  let packageRoot = null;
-  try {
-    const require = createRequire(import.meta.url);
-    const packageJsonPath = require.resolve('@justin_666/square-couplets-master-skills/package.json');
-    packageRoot = dirname(packageJsonPath);
-  } catch (e) {
-    // Package not found via require.resolve, will try other paths
-  }
-  
-  const possiblePaths = [
-    // Global npm package - dist directory (compiled JS)
-    ...(globalPrefix ? [
-      join(globalPrefix, 'lib', 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-      join(globalPrefix, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-    ] : []),
-    // From resolved package root - dist directory
-    ...(packageRoot ? [
-      join(packageRoot, 'dist', 'services'),
-      join(packageRoot, 'services'), // fallback to source
-    ] : []),
-    // Local project root - dist directory
-    join(projectRoot, 'dist', 'services'),
-    join(projectRoot, 'services'), // fallback to source
-    // Local node_modules - dist directory
-    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-    // Current working directory - dist directory
-    join(process.cwd(), 'dist', 'services'),
-    join(process.cwd(), 'services'),
-    // Current working directory node_modules
-    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-  ];
-
-  for (const path of possiblePaths) {
-    try {
-      if (statSync(path).isDirectory()) {
-        return path;
-      }
-    } catch (e) {
-      // Path doesn't exist, try next
-    }
-  }
-  return null;
-}
-
-// Load environment variables helper
-async function loadEnvironmentVariables() {
+async function main() {
   try {
-    const dotenv = await import('dotenv');
-    const envLocalPath = join(projectRoot, '.env.local');
-    const envPath = join(projectRoot, '.env');
-    const cwdEnvLocalPath = join(process.cwd(), '.env.local');
-    const cwdEnvPath = join(process.cwd(), '.env');
-
-    if (existsSync(envLocalPath)) {
-      dotenv.config({ path: envLocalPath });
-    } else if (existsSync(envPath)) {
-      dotenv.config({ path: envPath });
-    } else if (existsSync(cwdEnvLocalPath)) {
-      dotenv.config({ path: cwdEnvLocalPath });
-    } else if (existsSync(cwdEnvPath)) {
-      dotenv.config({ path: cwdEnvPath });
-    } else {
-      dotenv.config();
+    // Check for version flag
+    if (process.argv.includes('--version') || process.argv.includes('-v')) {
+      showVersion(projectRoot);
+      process.exit(0);
     }
-  } catch (e) {
-    // dotenv not available, continue without it (will use environment variables)
-  }
-}
 
-async function main() {
-  try {
     // Load environment variables first
-    await loadEnvironmentVariables();
+    await loadEnvironmentVariables(projectRoot);
     
     // Parse command line arguments
-    const args = process.argv.slice(2);
+    const args = process.argv.slice(2).filter(arg => !arg.startsWith('-'));
     const prompt = args[0];
     const model = args[1] || 'gemini-2.5-flash-image';
     const imageSize = args[2] || '1K';
@@ -113,17 +43,19 @@ async function main() {
     if (!prompt) {
       console.error('❌ Error: Prompt is required');
       console.log('\nUsage:');
-      console.log('  node skills/generate-doufang-image/index.js <prompt> [model] [size] [reference-image] [output-path]');
+      console.log('  doufang-image <prompt> [model] [size] [reference-image] [output-path]');
       console.log('\nParameters:');
       console.log('  prompt           - Image generation prompt (required)');
       console.log('  model            - Model to use: gemini-2.5-flash-image (default) or gemini-3-pro-image-preview');
       console.log('  size             - Image size: 1K (default), 2K, or 4K (Pro model only)');
       console.log('  reference-image  - Optional reference image path');
       console.log('  output-path      - Optional output file path (default: output/doufang-{timestamp}.png)');
+      console.log('\nOptions:');
+      console.log('  -v, --version    Show version number');
       console.log('\nExample:');
-      console.log('  node skills/generate-doufang-image/index.js "A diamond-shaped Doufang..."');
-      console.log('  node skills/generate-doufang-image/index.js "..." gemini-3-pro-image-preview 2K');
-      console.log('  node skills/generate-doufang-image/index.js "..." gemini-3-pro-image-preview 2K images/ref.png output/my-doufang.png');
+      console.log('  doufang-image "A diamond-shaped Doufang..."');
+      console.log('  doufang-image "..." gemini-3-pro-image-preview 2K');
+      console.log('  doufang-image "..." gemini-3-pro-image-preview 2K images/ref.png output/my-doufang.png');
       process.exit(1);
     }
 
@@ -141,91 +73,60 @@ async function main() {
     }
 
     // Get API key
-    const apiKey = process.env.GEMINI_API_KEY || process.env.API_KEY || process.env.GOOGLE_GENAI_API_KEY;
-    
+    const apiKey = getApiKey();
     if (!apiKey) {
       console.error('❌ Error: API Key is missing');
       console.log('💡 Set GEMINI_API_KEY in .env file or environment variable');
       process.exit(1);
     }
 
-    // Try to import service function
-    const servicesPath = findServicesPath();
+    // Find and import service module
+    const servicesPath = findServicesPath(projectRoot);
     if (!servicesPath) {
       console.error('❌ Error: Cannot find services directory');
       console.log('💡 Make sure you are running from the project root or have installed the package');
+      console.log('💡 Set DEBUG_DOUFANG=1 to see detailed path checking');
       process.exit(1);
     }
 
-    // Dynamic import of service (prioritize compiled .js from dist/)
-    let serviceModule;
-    const possibleServicePaths = [
-      // 1. Compiled JS in dist/ (npm package)
-      join(dirname(servicesPath), 'dist', 'services', 'geminiService.js'),
-      // 2. Compiled JS in services/ (if built locally)
-      join(servicesPath, 'geminiService.js'),
-      // 3. Source TS (development only)
-      join(servicesPath, 'geminiService.ts'),
-    ];
-    
-    let importError = null;
-    for (const servicePath of possibleServicePaths) {
-      try {
-        if (existsSync(servicePath)) {
-          serviceModule = await import(`file://${servicePath}`);
-          break;
-        }
-      } catch (e) {
-        importError = e;
-        continue;
-      }
-    }
-    
-    if (!serviceModule) {
-      console.error('❌ Error: Cannot import service module');
-      console.error('   Tried paths:');
-      possibleServicePaths.forEach(p => console.error(`   - ${p}`));
-      if (importError) {
-        console.error('\n   Last error:', importError.message);
-      }
-      console.error('\n💡 This usually means the package was not properly built.');
-      console.error('   Please report this issue at: https://github.com/poirotw66/Square_Couplets_Master/issues');
-      process.exit(1);
-    }
+    const serviceModule = await importServiceModule(servicesPath);
     const { generateDoufangImage } = serviceModule;
 
     // Load reference image if provided
     let referenceImageDataUrl = null;
     if (referenceImagePath) {
-      const fullPath = resolve(process.cwd(), referenceImagePath);
-      if (!existsSync(fullPath)) {
-        console.error(`❌ Error: Reference image not found: ${fullPath}`);
+      try {
+        referenceImageDataUrl = loadReferenceImage(referenceImagePath);
+        console.log(`🖼️  Using reference image: ${referenceImagePath}`);
+      } catch (error) {
+        console.error(`❌ Error: ${error.message}`);
         process.exit(1);
       }
-      
-      const imageBuffer = readFileSync(fullPath);
-      const base64 = imageBuffer.toString('base64');
-      const ext = referenceImagePath.split('.').pop()?.toLowerCase();
-      const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png';
-      referenceImageDataUrl = `data:${mimeType};base64,${base64}`;
     }
 
-    // Generate image
-    console.log(`🖼️  Generating image...`);
+    // Generate image with progress spinner
+    console.log(`🎨 Generating image...`);
     console.log(`    Model: ${model}`);
     console.log(`    Size: ${imageSize}`);
-    if (referenceImagePath) {
-      console.log(`    Reference: ${referenceImagePath}`);
-    }
-    console.log('    This may take a while, please wait...\n');
+    console.log('');
     
-    const imageDataUrl = await generateDoufangImage(
-      prompt,
-      apiKey,
-      model,
-      imageSize,
-      referenceImageDataUrl
-    );
+    const spinner = createProgressSpinner('Generating image... (this may take 30-60 seconds)');
+    spinner.start();
+    
+    let imageDataUrl;
+    try {
+      imageDataUrl = await generateDoufangImage(
+        prompt,
+        apiKey,
+        model,
+        imageSize,
+        referenceImageDataUrl
+      );
+      spinner.stop('✅ Image generated successfully!');
+    } catch (error) {
+      spinner.stop('');
+      throw error;
+    }
     
     // Extract base64 data
     const base64Data = imageDataUrl.replace(/^data:image\/\w+;base64,/, '');
@@ -252,7 +153,6 @@ async function main() {
     // Save image
     writeFileSync(finalOutputPath, buffer);
     
-    console.log('✅ Image generated successfully!');
     console.log(`📁 Saved to: ${finalOutputPath}`);
     console.log(`📊 File size: ${(buffer.length / 1024 / 1024).toFixed(2)} MB`);
     
@@ -262,7 +162,18 @@ async function main() {
 
   } catch (error) {
     console.error('❌ Error:', error.message);
-    if (error.stack) {
+    if (error.details) {
+      console.error('\nDetails:');
+      if (error.details.triedPaths) {
+        console.error('  Tried paths:');
+        error.details.triedPaths.forEach(p => console.error(`    - ${p}`));
+      }
+      if (error.details.lastError) {
+        console.error(`  Last error: ${error.details.lastError}`);
+      }
+    }
+    if (process.env.DEBUG_DOUFANG && error.stack) {
+      console.error('\nStack trace:');
       console.error(error.stack);
     }
     process.exit(1);

package/skills/generate-doufang-prompt/SKILL.md

@@ -31,7 +31,7 @@ When user provides a keyword or wish phrase, generate a professional Doufang art
    - **Decorative elements**: Symbolic elements that visually represent the keyword (e.g., horse, dragon, pine tree, crane, gold ingots, clouds, mountains, sun, plum blossoms)
    - **Style**: Traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class
    - **Composition**: 
-     - Doufang fills 95% of the frame
+     - Doufang fills 90 - 95% of the frame
      - Centered with minimal elegant margins (2-5% of frame width, just enough to prevent edge cropping)
      - Fully visible inside the frame, not touching edges
    - **Quality**: Ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio
@@ -56,7 +56,7 @@ When user provides a keyword or wish phrase, generate a professional Doufang art
 ```json
 {
   "blessingPhrase": "招財進寶",
-  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '招財進寶'. Around the calligraphy: symbolic elements that visually represent wealth - gold ingots, coins, treasure chests, and prosperity symbols, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
+  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '招財進寶'. Around the calligraphy: symbolic elements that visually represent wealth - gold ingots, coins, treasure chests, and prosperity symbols, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 90 - 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
 }
 ```
 
@@ -68,7 +68,7 @@ When user provides a keyword or wish phrase, generate a professional Doufang art
 ```json
 {
   "blessingPhrase": "延年益壽",
-  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '延年益壽'. Around the calligraphy: symbolic elements that visually represent health and longevity - pine trees, cranes, peaches, and bamboo, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
+  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '延年益壽'. Around the calligraphy: symbolic elements that visually represent health and longevity - pine trees, cranes, peaches, and bamboo, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 90 - 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
 }
 ```
 
@@ -80,13 +80,13 @@ When user provides a keyword or wish phrase, generate a professional Doufang art
 ```json
 {
   "blessingPhrase": "萬馬奔騰",
-  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '萬馬奔騰'. Around the calligraphy: symbolic elements that visually represent energy and vitality - galloping horses, flowing clouds, dynamic movement, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
+  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '萬馬奔騰'. Around the calligraphy: symbolic elements that visually represent energy and vitality - galloping horses, flowing clouds, dynamic movement, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 90 - 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
 }
 ```
 
 ## Key Requirements
 
-- The Doufang should fill **95% of the frame** (not less)
+- The Doufang should fill **90 - 95% of the frame** (not less)
 - Minimal margins: **2-5% of frame width** (just enough to prevent edge cropping)
 - **No excessive white space** or wide margins
 - Traditional Chinese artistic style (ink wash, calligraphy)

package/skills/generate-doufang-prompt/index.js

@@ -5,218 +5,82 @@
  * Can be called directly by agents or users
  */
 
-import { fileURLToPath } from 'url';
-import { dirname, join, resolve } from 'path';
-import { readFileSync, existsSync, statSync } from 'fs';
-import { execSync } from 'child_process';
-import { createRequire } from 'module';
+import { resolve } from 'path';
+import {
+  getProjectRoot,
+  loadEnvironmentVariables,
+  findServicesPath,
+  getApiKey,
+  showVersion,
+  loadReferenceImage,
+  importServiceModule
+} from '../shared/utils.js';
+
+// Initialize
+const projectRoot = getProjectRoot(import.meta.url);
 
-// Load environment variables helper
-async function loadEnvironmentVariables() {
-  try {
-    const dotenv = await import('dotenv');
-    const envLocalPath = join(projectRoot, '.env.local');
-    const envPath = join(projectRoot, '.env');
-    const cwdEnvLocalPath = join(process.cwd(), '.env.local');
-    const cwdEnvPath = join(process.cwd(), '.env');
-
-    if (existsSync(envLocalPath)) {
-      dotenv.config({ path: envLocalPath });
-    } else if (existsSync(envPath)) {
-      dotenv.config({ path: envPath });
-    } else if (existsSync(cwdEnvLocalPath)) {
-      dotenv.config({ path: cwdEnvLocalPath });
-    } else if (existsSync(cwdEnvPath)) {
-      dotenv.config({ path: cwdEnvPath });
-    } else {
-      dotenv.config();
-    }
-  } catch (e) {
-    // dotenv not available, continue without it (will use environment variables)
-  }
-}
-
-// Resolve project root and service path
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const skillDir = resolve(__dirname);
-const projectRoot = resolve(skillDir, '../..');
-
-// Try to find dist directory (compiled JS) or services directory (source TS)
-function findServicesPath() {
-  // Get npm global prefix to find globally installed packages
-  let globalPrefix = null;
-  try {
-    globalPrefix = execSync('npm config get prefix', { encoding: 'utf-8' }).trim();
-  } catch (e) {
-    // Ignore error, try other methods
-  }
-  
-  // Try to resolve package location using createRequire (works in ES modules)
-  let packageRoot = null;
+async function main() {
   try {
-    const require = createRequire(import.meta.url);
-    const packageJsonPath = require.resolve('@justin_666/square-couplets-master-skills/package.json');
-    packageRoot = dirname(packageJsonPath);
-  } catch (e) {
-    // Package not found via require.resolve, will try other paths
-  }
-  
-  // Build list of possible paths
-  // IMPORTANT: We're looking for dist/services (compiled) not services/ (source)
-  const possiblePaths = [
-    // Global npm package - dist directory (compiled JS)
-    ...(globalPrefix ? [
-      join(globalPrefix, 'lib', 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-      join(globalPrefix, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-    ] : []),
-    // From resolved package root - dist directory
-    ...(packageRoot ? [
-      join(packageRoot, 'dist', 'services'),
-      join(packageRoot, 'services'), // fallback to source
-    ] : []),
-    // Local project root - dist directory
-    join(projectRoot, 'dist', 'services'),
-    join(projectRoot, 'services'), // fallback to source
-    // Local node_modules - dist directory
-    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-    // Current working directory - dist directory
-    join(process.cwd(), 'dist', 'services'),
-    join(process.cwd(), 'services'),
-    // Current working directory node_modules
-    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
-  ];
-
-  // Debug: log all paths being checked (enable with DEBUG_DOUFANG=1)
-  if (process.env.DEBUG_DOUFANG) {
-    console.log('🔍 Checking paths for services directory:');
-    console.log(`   packageRoot: ${packageRoot || 'not found'}`);
-    console.log(`   globalPrefix: ${globalPrefix || 'not found'}`);
-    console.log(`   projectRoot: ${projectRoot}`);
-    console.log(`   cwd: ${process.cwd()}`);
-    console.log('\n   Trying paths:');
-    for (const path of possiblePaths) {
-      const exists = existsSync(path);
-      console.log(`   ${exists ? '✅' : '❌'} ${path}`);
+    // Check for version flag
+    if (process.argv.includes('--version') || process.argv.includes('-v')) {
+      showVersion(projectRoot);
+      process.exit(0);
     }
-  }
-  
-  for (const path of possiblePaths) {
-    try {
-      if (statSync(path).isDirectory()) {
-        if (process.env.DEBUG_DOUFANG) {
-          console.log(`\n✅ Found services at: ${path}`);
-        }
-        return path;
-      }
-    } catch (e) {
-      // Path doesn't exist, try next
-    }
-  }
-  
-  // If not found, provide helpful error message
-  if (process.env.DEBUG_DOUFANG) {
-    console.log('\n❌ Services directory not found in any of the checked paths');
-  }
-  return null;
-}
 
-
-async function main() {
-  try {
     // Load environment variables first
-    await loadEnvironmentVariables();
+    await loadEnvironmentVariables(projectRoot);
     
     // Parse command line arguments
-    const args = process.argv.slice(2);
+    const args = process.argv.slice(2).filter(arg => !arg.startsWith('-'));
     const keyword = args[0];
     const referenceImagePath = args[1]; // Optional reference image path
     
     if (!keyword) {
       console.error('❌ Error: Keyword is required');
       console.log('\nUsage:');
-      console.log('  node skills/generate-doufang-prompt/index.js <keyword> [reference-image-path]');
+      console.log('  doufang-prompt <keyword> [reference-image-path]');
+      console.log('\nOptions:');
+      console.log('  -v, --version    Show version number');
       console.log('\nExample:');
-      console.log('  node skills/generate-doufang-prompt/index.js "財富"');
-      console.log('  node skills/generate-doufang-prompt/index.js "健康" images/reference.png');
+      console.log('  doufang-prompt "財富"');
+      console.log('  doufang-prompt "健康" images/reference.png');
       process.exit(1);
     }
 
     // Get API key
-    const apiKey = process.env.GEMINI_API_KEY || process.env.API_KEY || process.env.GOOGLE_GENAI_API_KEY;
-    
+    const apiKey = getApiKey();
     if (!apiKey) {
       console.error('❌ Error: API Key is missing');
       console.log('💡 Set GEMINI_API_KEY in .env file or environment variable');
       process.exit(1);
     }
 
-    // Try to import service function
-    const servicesPath = findServicesPath();
+    // Find and import service module
+    const servicesPath = findServicesPath(projectRoot);
     if (!servicesPath) {
       console.error('❌ Error: Cannot find services directory');
       console.log('💡 Make sure you are running from the project root or have installed the package');
+      console.log('💡 Set DEBUG_DOUFANG=1 to see detailed path checking');
       process.exit(1);
     }
 
-    // Dynamic import of service (prioritize compiled .js from dist/)
-    let serviceModule;
-    const possibleServicePaths = [
-      // 1. Compiled JS in dist/ (npm package)
-      join(dirname(servicesPath), 'dist', 'services', 'geminiService.js'),
-      // 2. Compiled JS in services/ (if built locally)
-      join(servicesPath, 'geminiService.js'),
-      // 3. Source TS (development only)
-      join(servicesPath, 'geminiService.ts'),
-    ];
-    
-    let importError = null;
-    for (const servicePath of possibleServicePaths) {
-      try {
-        if (existsSync(servicePath)) {
-          serviceModule = await import(`file://${servicePath}`);
-          break;
-        }
-      } catch (e) {
-        importError = e;
-        continue;
-      }
-    }
-    
-    if (!serviceModule) {
-      console.error('❌ Error: Cannot import service module');
-      console.error('   Tried paths:');
-      possibleServicePaths.forEach(p => console.error(`   - ${p}`));
-      if (importError) {
-        console.error('\n   Last error:', importError.message);
-      }
-      console.error('\n💡 This usually means the package was not properly built.');
-      console.error('   Please report this issue at: https://github.com/poirotw66/Square_Couplets_Master/issues');
-      process.exit(1);
-    }
+    const serviceModule = await importServiceModule(servicesPath);
     const { generateDoufangPrompt } = serviceModule;
 
     // Load reference image if provided
     let referenceImageDataUrl = null;
     if (referenceImagePath) {
-      const fullPath = resolve(process.cwd(), referenceImagePath);
-      if (!existsSync(fullPath)) {
-        console.error(`❌ Error: Reference image not found: ${fullPath}`);
+      try {
+        referenceImageDataUrl = loadReferenceImage(referenceImagePath);
+        console.log(`🖼️  Using reference image: ${referenceImagePath}`);
+      } catch (error) {
+        console.error(`❌ Error: ${error.message}`);
         process.exit(1);
       }
-      
-      const imageBuffer = readFileSync(fullPath);
-      const base64 = imageBuffer.toString('base64');
-      const ext = referenceImagePath.split('.').pop()?.toLowerCase();
-      const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png';
-      referenceImageDataUrl = `data:${mimeType};base64,${base64}`;
     }
 
     // Generate prompt
     console.log(`📝 Generating prompt for keyword: "${keyword}"`);
-    if (referenceImagePath) {
-      console.log(`🖼️  Using reference image: ${referenceImagePath}`);
-    }
     
     const result = await generateDoufangPrompt(keyword, apiKey, referenceImageDataUrl);
     
@@ -225,7 +89,18 @@ async function main() {
 
   } catch (error) {
     console.error('❌ Error:', error.message);
-    if (error.stack) {
+    if (error.details) {
+      console.error('\nDetails:');
+      if (error.details.triedPaths) {
+        console.error('  Tried paths:');
+        error.details.triedPaths.forEach(p => console.error(`    - ${p}`));
+      }
+      if (error.details.lastError) {
+        console.error(`  Last error: ${error.details.lastError}`);
+      }
+    }
+    if (process.env.DEBUG_DOUFANG && error.stack) {
+      console.error('\nStack trace:');
       console.error(error.stack);
     }
     process.exit(1);

package/skills/optimize-doufang-prompt/SKILL.md

@@ -26,11 +26,11 @@ When user reports that generated images have excessive white margins, poor compo
    
    **Replace with:**
    - ✅ "centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping)"
-   - ✅ "minimal margins - the Doufang should fill most of the frame (95% of image area)"
-   - ✅ "The Doufang should occupy 95% of the image area, maximizing visual impact"
+   - ✅ "minimal margins - the Doufang should fill most of the frame (90 - 95% of image area)"
+   - ✅ "The Doufang should occupy 90 - 95% of the image area, maximizing visual impact"
 
 3. **Add explicit composition instructions:**
-   - Add: "The Doufang should fill 95% of the frame"
+   - Add: "The Doufang should fill 90 - 95% of the frame"
    - Add: "Minimal margins (2-5% of frame width)"
    - Add: "Maximize visual impact by making the Doufang occupy most of the frame"
    - Add: "Avoid excessive white space or wide margins"
@@ -61,7 +61,7 @@ When user reports that generated images have excessive white margins, poor compo
 
 **After:**
 ```
-"...The Doufang should occupy 95% of the image area, maximizing visual impact..."
+"...The Doufang should occupy 90 - 95% of the image area, maximizing visual impact..."
 ```
 
 ### Rule 3: Composition Emphasis
@@ -72,7 +72,7 @@ When user reports that generated images have excessive white margins, poor compo
 
 **After:**
 ```
-"...minimal margins - the Doufang should fill most of the frame (95% of image area)..."
+"...minimal margins - the Doufang should fill most of the frame (90 - 95% of image area)..."
 ```
 
 ## Examples
@@ -86,7 +86,7 @@ A diamond-shaped Chinese New Year Doufang centered in a 1:1 frame with wide whit
 
 **Optimized Prompt:**
 ```
-A diamond-shaped Chinese New Year Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The Doufang should occupy 95% of the image area, maximizing visual impact. The artwork is a masterpiece of traditional ink-wash fusion...
+A diamond-shaped Chinese New Year Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The Doufang should occupy 90 - 95% of the image area, maximizing visual impact. The artwork is a masterpiece of traditional ink-wash fusion...
 ```
 
 ### Example 2: Improving Composition Instructions
@@ -98,7 +98,7 @@ Composition: The diamond-shaped Doufang is fully visible and centered, with gene
 
 **Optimized Prompt:**
 ```
-Composition: The diamond-shaped Doufang fills 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. The Doufang should occupy most of the image area, maximizing visual impact. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
+Composition: The diamond-shaped Doufang fills 90 - 95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. The Doufang should occupy most of the image area, maximizing visual impact. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
 ```
 
 ### Example 3: Complete Prompt Optimization
@@ -115,7 +115,7 @@ Framing requirements:
 ```
 Framing requirements:
 - The entire diamond-shaped Doufang must be fully visible inside the image.
-- Minimal margins - the Doufang should fill most of the frame (95% of image area).
+- Minimal margins - the Doufang should fill most of the frame (90 - 95% of image area).
 - No cropping, no touching edges, no cut-off.
 - Maximize visual impact by making the Doufang occupy most of the frame.
 ```
@@ -123,7 +123,7 @@ Framing requirements:
 ## Key Optimization Principles
 
 1. **Never use "wide" or "generous" margins** - Always specify minimal margins (2-5%)
-2. **Always specify frame fill percentage** - 95% of image area
+2. **Always specify frame fill percentage** - 90 - 95% of image area
 3. **Emphasize visual impact** - Over safety margins
 4. **Be specific about margin size** - "2-5% of frame width"
 5. **Clarify purpose** - "just enough to prevent edge cropping"

package/skills/optimize-doufang-prompt/index.js

@@ -3,97 +3,178 @@
 /**
  * Executable script for optimize-doufang-prompt skill
  * Optimizes prompts to reduce white margins and improve composition
+ * Supports both simple rule-based and AI-powered optimization
  */
 
-import { fileURLToPath } from 'url';
-import { dirname, join, resolve } from 'path';
-import { existsSync, statSync } from 'fs';
-import { config } from 'dotenv';
+import {
+  getProjectRoot,
+  loadEnvironmentVariables,
+  getApiKey,
+  showVersion,
+  createProgressSpinner
+} from '../shared/utils.js';
 
-// Resolve project root
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const skillDir = resolve(__dirname);
-const projectRoot = resolve(skillDir, '../..');
+// Initialize
+const projectRoot = getProjectRoot(import.meta.url);
 
-// Load environment variables
-const envLocalPath = join(projectRoot, '.env.local');
-const envPath = join(projectRoot, '.env');
-
-if (existsSync(envLocalPath)) {
-  config({ path: envLocalPath });
-} else if (existsSync(envPath)) {
-  config({ path: envPath });
-} else {
-  config();
+/**
+ * Optimize prompt using AI (Gemini)
+ * Note: AI optimization is experimental and may fallback to rule-based
+ */
+async function optimizePromptWithAI(originalPrompt, apiKey) {
+  // Note: AI optimization requires proper Google Gen AI SDK integration
+  // For now, this is a placeholder that falls back to rule-based optimization
+  // Future implementation will use: GoogleGenAI API for smarter optimization
+  
+  console.log('⚠️  AI optimization is currently experimental');
+  console.log('   Falling back to rule-based optimization');
+  return optimizePromptSimple(originalPrompt);
 }
 
-async function optimizePrompt(originalPrompt) {
-  // This is a simple optimization - in a real implementation,
-  // you might want to use an LLM to optimize the prompt
-  
+/**
+ * Optimize prompt using simple rules (fallback)
+ */
+function optimizePromptSimple(originalPrompt) {
   let optimized = originalPrompt;
   
   // Replace wide margin descriptions with minimal margin
   optimized = optimized.replace(/wide\s+white\s+margins/gi, 'minimal elegant margins (2-5% of frame width)');
   optimized = optimized.replace(/wide\s+margins/gi, 'minimal margins (2-5%)');
   optimized = optimized.replace(/excessive\s+white\s+space/gi, 'minimal white space');
+  optimized = optimized.replace(/large\s+margins/gi, 'minimal margins (2-5%)');
   
-  // Ensure Doufang fills 85-95% of frame
-  if (!optimized.includes('85-95%')) {
-    optimized = optimized.replace(
-      /(Composition:.*?)(\.|$)/i,
-      (match, p1, p2) => {
-        if (!p1.includes('85-95%')) {
-          return p1 + ' The Doufang should fill 85-95% of the image area, maximizing visual impact.' + p2;
+  // Ensure Doufang fills 90-95% of frame
+  if (!optimized.includes('90-95%') && !optimized.includes('85-95%') && !optimized.includes('fills 90%')) {
+    // Try to find Composition section and enhance it
+    const hasComposition = /Composition:/i.test(optimized);
+    if (hasComposition) {
+      optimized = optimized.replace(
+        /(Composition:.*?)(\.|$)/i,
+        (match, p1, p2) => {
+          if (!p1.includes('90-95%') && !p1.includes('85-95%')) {
+            return p1 + ' The diamond-shaped Doufang fills 90-95% of the 1:1 frame, centered with minimal margins (2-5% of frame width).' + p2;
+          }
+          return match;
         }
-        return match;
-      }
-    );
+      );
+    } else {
+      // Add composition requirement at the end
+      optimized += '\n\nComposition: The diamond-shaped Doufang fills 90-95% of the 1:1 frame, centered with minimal margins (2-5% of frame width). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off.';
+    }
+  }
+  
+  // Ensure "not cropped" and "not touching edges" are mentioned
+  if (!optimized.includes('not cropped') && !optimized.includes('not touch')) {
+    optimized += ' The artwork should not be cropped or touch the frame edges.';
   }
   
   // Add explicit margin requirements if not present
-  if (!optimized.includes('2-5%')) {
-    optimized += '\n\nIMPORTANT: The diamond-shaped Doufang must fill 85-95% of the frame with minimal margins (2-5% of frame width). Avoid excessive white space or wide margins.';
+  if (!optimized.includes('2-5%') && !optimized.includes('minimal margin')) {
+    optimized += '\n\nIMPORTANT: The diamond-shaped Doufang must fill 90-95% of the frame with minimal margins (2-5% of frame width). Avoid excessive white space or wide margins.';
   }
   
-  return optimized;
+  return optimized.trim();
 }
 
 async function main() {
   try {
+    // Check for version flag
+    if (process.argv.includes('--version') || process.argv.includes('-v')) {
+      showVersion(projectRoot);
+      process.exit(0);
+    }
+
+    // Load environment variables first
+    await loadEnvironmentVariables(projectRoot);
+    
     // Parse command line arguments
     const args = process.argv.slice(2);
-    const prompt = args[0];
+    const useAI = args.includes('--ai');
+    const prompt = args.filter(arg => !arg.startsWith('--'))[0];
     
     if (!prompt) {
       console.error('❌ Error: Prompt is required');
       console.log('\nUsage:');
-      console.log('  node skills/optimize-doufang-prompt/index.js <prompt>');
-      console.log('\nOr pipe prompt:');
-      console.log('  echo "A diamond-shaped..." | node skills/optimize-doufang-prompt/index.js');
+      console.log('  doufang-optimize <prompt> [--ai]');
+      console.log('\nOptions:');
+      console.log('  --ai             Use AI to optimize prompt (requires API key)');
+      console.log('  -v, --version    Show version number');
       console.log('\nExample:');
-      console.log('  node skills/optimize-doufang-prompt/index.js "A diamond-shaped Doufang with wide white margins..."');
+      console.log('  doufang-optimize "A diamond-shaped Doufang with wide margins..."');
+      console.log('  doufang-optimize "..." --ai');
+      console.log('\nNote: Without --ai flag, uses fast rule-based optimization.');
+      console.log('      With --ai flag, uses Gemini AI for smarter optimization.');
       process.exit(1);
     }
 
-    // Optimize prompt
     console.log('✨ Optimizing prompt...\n');
-    const optimized = await optimizePrompt(prompt);
+    
+    let optimized;
+    let method = 'rule-based';
+    
+    if (useAI) {
+      const apiKey = getApiKey();
+      if (!apiKey) {
+        console.warn('⚠️  No API key found, falling back to rule-based optimization');
+        console.warn('💡 Set GEMINI_API_KEY to use AI-powered optimization\n');
+        optimized = optimizePromptSimple(prompt);
+      } else {
+        console.log('🤖 Using AI to optimize (Gemini 2.0 Flash)...');
+        const spinner = createProgressSpinner('Optimizing with AI...');
+        spinner.start();
+        
+        try {
+          optimized = await optimizePromptWithAI(prompt, apiKey);
+          spinner.stop('✅ AI optimization complete!');
+          method = 'AI-powered (Gemini 2.0 Flash)';
+        } catch (error) {
+          spinner.stop('');
+          console.warn(`⚠️  AI optimization failed: ${error.message}`);
+          console.warn('   Falling back to rule-based optimization\n');
+          optimized = optimizePromptSimple(prompt);
+        }
+      }
+    } else {
+      console.log('⚡ Using fast rule-based optimization...');
+      optimized = optimizePromptSimple(prompt);
+    }
     
     // Output optimized prompt
-    console.log('✅ Optimized prompt:');
+    console.log('\n✅ Optimized prompt:');
     console.log('─'.repeat(60));
     console.log(optimized);
     console.log('─'.repeat(60));
     
+    // Calculate improvement (simple heuristic)
+    const improvements = [];
+    if (!prompt.includes('90-95%') && optimized.includes('90-95%')) {
+      improvements.push('Added frame fill percentage');
+    }
+    if (!prompt.includes('minimal margin') && optimized.includes('minimal margin')) {
+      improvements.push('Specified minimal margins');
+    }
+    if (prompt.includes('wide margin') && !optimized.includes('wide margin')) {
+      improvements.push('Removed wide margin references');
+    }
+    
+    if (improvements.length > 0) {
+      console.log('\n📊 Improvements:');
+      improvements.forEach(imp => console.log(`   ✓ ${imp}`));
+    }
+    
     // Also output as JSON for programmatic use
     console.log('\n📋 JSON output:');
-    console.log(JSON.stringify({ optimizedPrompt: optimized }, null, 2));
+    console.log(JSON.stringify({ 
+      originalPrompt: prompt,
+      optimizedPrompt: optimized,
+      method: method,
+      improvements: improvements
+    }, null, 2));
 
   } catch (error) {
     console.error('❌ Error:', error.message);
-    if (error.stack) {
+    if (process.env.DEBUG_DOUFANG && error.stack) {
+      console.error('\nStack trace:');
       console.error(error.stack);
     }
     process.exit(1);

package/skills/shared/utils.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+/**
+ * Shared utility functions for all Doufang skills
+ * Provides common functionality to avoid code duplication
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { execSync } from 'child_process';
+import { createRequire } from 'module';
+
+/**
+ * Get project root directory
+ */
+export function getProjectRoot(importMetaUrl) {
+  const __filename = fileURLToPath(importMetaUrl);
+  const __dirname = dirname(__filename);
+  const skillDir = resolve(__dirname);
+  return resolve(skillDir, '../..');
+}
+
+/**
+ * Load environment variables from .env files
+ */
+export async function loadEnvironmentVariables(projectRoot) {
+  try {
+    const dotenv = await import('dotenv');
+    const envLocalPath = join(projectRoot, '.env.local');
+    const envPath = join(projectRoot, '.env');
+    const cwdEnvLocalPath = join(process.cwd(), '.env.local');
+    const cwdEnvPath = join(process.cwd(), '.env');
+
+    if (existsSync(envLocalPath)) {
+      dotenv.config({ path: envLocalPath });
+    } else if (existsSync(envPath)) {
+      dotenv.config({ path: envPath });
+    } else if (existsSync(cwdEnvLocalPath)) {
+      dotenv.config({ path: cwdEnvLocalPath });
+    } else if (existsSync(cwdEnvPath)) {
+      dotenv.config({ path: cwdEnvPath });
+    } else {
+      dotenv.config();
+    }
+  } catch (e) {
+    // dotenv not available, continue without it (will use environment variables)
+  }
+}
+
+/**
+ * Find services directory (supports both compiled dist/ and source services/)
+ */
+export function findServicesPath(projectRoot) {
+  // Get npm global prefix to find globally installed packages
+  let globalPrefix = null;
+  try {
+    globalPrefix = execSync('npm config get prefix', { encoding: 'utf-8' }).trim();
+  } catch (e) {
+    // Ignore error, try other methods
+  }
+  
+  // Try to resolve package location using createRequire (works in ES modules)
+  let packageRoot = null;
+  try {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve('@justin_666/square-couplets-master-skills/package.json');
+    packageRoot = dirname(packageJsonPath);
+  } catch (e) {
+    // Package not found via require.resolve, will try other paths
+  }
+  
+  // Build list of possible paths
+  // IMPORTANT: We're looking for dist/services (compiled) not services/ (source)
+  const possiblePaths = [
+    // Global npm package - dist directory (compiled JS)
+    ...(globalPrefix ? [
+      join(globalPrefix, 'lib', 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
+      join(globalPrefix, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
+    ] : []),
+    // From resolved package root - dist directory
+    ...(packageRoot ? [
+      join(packageRoot, 'dist', 'services'),
+      join(packageRoot, 'services'), // fallback to source
+    ] : []),
+    // Local project root - dist directory
+    join(projectRoot, 'dist', 'services'),
+    join(projectRoot, 'services'), // fallback to source
+    // Local node_modules - dist directory
+    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
+    // Current working directory - dist directory
+    join(process.cwd(), 'dist', 'services'),
+    join(process.cwd(), 'services'),
+    // Current working directory node_modules
+    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
+  ];
+
+  // Debug: log all paths being checked (enable with DEBUG_DOUFANG=1)
+  if (process.env.DEBUG_DOUFANG) {
+    console.log('🔍 Checking paths for services directory:');
+    console.log(`   packageRoot: ${packageRoot || 'not found'}`);
+    console.log(`   globalPrefix: ${globalPrefix || 'not found'}`);
+    console.log(`   projectRoot: ${projectRoot}`);
+    console.log(`   cwd: ${process.cwd()}`);
+    console.log('\n   Trying paths:');
+    for (const path of possiblePaths) {
+      const exists = existsSync(path);
+      console.log(`   ${exists ? '✅' : '❌'} ${path}`);
+    }
+  }
+  
+  for (const path of possiblePaths) {
+    try {
+      if (statSync(path).isDirectory()) {
+        if (process.env.DEBUG_DOUFANG) {
+          console.log(`\n✅ Found services at: ${path}`);
+        }
+        return path;
+      }
+    } catch (e) {
+      // Path doesn't exist, try next
+    }
+  }
+  
+  // If not found, provide helpful error message
+  if (process.env.DEBUG_DOUFANG) {
+    console.log('\n❌ Services directory not found in any of the checked paths');
+  }
+  return null;
+}
+
+/**
+ * Get MIME type from file extension
+ */
+export function getMimeType(filePath) {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  const mimeTypes = {
+    'jpg': 'image/jpeg',
+    'jpeg': 'image/jpeg',
+    'png': 'image/png',
+    'gif': 'image/gif',
+    'webp': 'image/webp',
+    'bmp': 'image/bmp'
+  };
+  return mimeTypes[ext] || 'image/png'; // default to png
+}
+
+/**
+ * Get API key from environment variables
+ */
+export function getApiKey() {
+  return process.env.GEMINI_API_KEY || 
+         process.env.API_KEY || 
+         process.env.GOOGLE_GENAI_API_KEY;
+}
+
+/**
+ * Show version from package.json
+ */
+export function showVersion(projectRoot) {
+  const packageJsonPath = join(projectRoot, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    console.log(`v${pkg.version}`);
+  } else {
+    console.log('version unknown');
+  }
+}
+
+/**
+ * Create a progress spinner for long-running operations
+ */
+export function createProgressSpinner(message = 'Processing...') {
+  const spinner = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinnerIndex = 0;
+  let interval = null;
+
+  return {
+    start() {
+      interval = setInterval(() => {
+        process.stdout.write(`\r${spinner[spinnerIndex]} ${message}`);
+        spinnerIndex = (spinnerIndex + 1) % spinner.length;
+      }, 80);
+    },
+    
+    stop(finalMessage = '') {
+      if (interval) {
+        clearInterval(interval);
+        interval = null;
+      }
+      if (finalMessage) {
+        process.stdout.write(`\r${finalMessage}${' '.repeat(50)}\n`);
+      } else {
+        process.stdout.write('\r' + ' '.repeat(100) + '\r');
+      }
+    }
+  };
+}
+
+/**
+ * Load reference image as data URL
+ */
+export function loadReferenceImage(referenceImagePath) {
+  const fullPath = resolve(process.cwd(), referenceImagePath);
+  if (!existsSync(fullPath)) {
+    throw new Error(`Reference image not found: ${fullPath}`);
+  }
+  
+  const imageBuffer = readFileSync(fullPath);
+  const base64 = imageBuffer.toString('base64');
+  const mimeType = getMimeType(referenceImagePath);
+  return `data:${mimeType};base64,${base64}`;
+}
+
+/**
+ * Import service module dynamically
+ */
+export async function importServiceModule(servicesPath) {
+  const possibleServicePaths = [
+    // 1. Compiled JS in dist/ (npm package)
+    join(dirname(servicesPath), 'dist', 'services', 'geminiService.js'),
+    // 2. Compiled JS in services/ (if built locally)
+    join(servicesPath, 'geminiService.js'),
+    // 3. Source TS (development only)
+    join(servicesPath, 'geminiService.ts'),
+  ];
+  
+  let importError = null;
+  for (const servicePath of possibleServicePaths) {
+    try {
+      if (existsSync(servicePath)) {
+        return await import(`file://${servicePath}`);
+      }
+    } catch (e) {
+      importError = e;
+      continue;
+    }
+  }
+  
+  // If we get here, nothing worked
+  const error = new Error('Cannot import service module');
+  error.details = {
+    triedPaths: possibleServicePaths,
+    lastError: importError?.message
+  };
+  throw error;
+}