Fix import paths and remove organ metaphors

- Update all `from storage.` imports to `from dss.storage.` - Update `from config import config` to use `dss.settings` - Update `from auth.` imports to `from dss.auth.` - Update health check to use `dss.mcp.handler` - Fix SmartMerger import (merger.py not smart_merger.py) - Fix TranslationDictionary import path - Fix test assertion for networkx edges/links - Remove organ/body metaphors from: - API server health check - CLI status command and help text - Admin UI logger and error handler 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-10 13:05:00 -03:00
parent 41fba59bf7
commit faa19beef3
22 changed files with 251 additions and 295 deletions
--- a/admin-ui/js/core/error-handler.js
+++ b/admin-ui/js/core/error-handler.js
@@ -1,147 +1,139 @@
 /**
- * DSS Error Handler - Immune System Antibodies
+ * DSS Error Handler
 *
- * The DSS Component's immune system uses these antibodies to detect and report threats.
- * Converts technical errors into human-friendly, actionable treatment plans.
+ * Converts technical errors into user-friendly, actionable messages.
 * Integrates with the messaging system for structured error reporting.
 *
- * Biological Framework: These error messages use component metaphors to make
- * issues intuitive. See docs/DSS_ORGANISM_GUIDE.md for the full framework.
- *
 * @module error-handler
 */

 import { notifyError, ErrorCode } from './messaging.js';

 /**
- * Error message templates with component metaphors
- *
- * These messages use biological language from the DSS Component Framework.
- * Each error is framed as a symptom the immune system detected, with
- * a diagnosis and treatment plan.
+ * Error message templates with user-friendly descriptions
 */
 const errorMessages = {
-  // Figma API Errors - Sensory System Issues
+  // Figma API Errors
  figma_403: {
-    title: '🛡️ IMMUNE ALERT: Sensory Input Blocked',
-    message: 'The DSS sensory organs cannot perceive the Figma file. Your access credentials lack permission.',
+    title: 'Access Denied',
+    message: 'Cannot access the Figma file. Your access credentials lack permission.',
    actions: [
-      'Verify your Figma authentication token in Settings (nervous system communication)',
-      'Confirm you have access to this file in Figma (sensory perception)',
-      'Check if the file still exists (component awareness)',
+      'Verify your Figma authentication token in Settings',
+      'Confirm you have access to this file in Figma',
+      'Check if the file still exists',
    ],
    code: ErrorCode.FIGMA_API_ERROR,
  },
  figma_404: {
-    title: '🛡️ IMMUNE ALERT: Sensory Target Lost',
-    message: 'The Figma file the DSS sensory organs were trying to perceive doesn\'t exist or is inaccessible.',
+    title: 'File Not Found',
+    message: 'The Figma file doesn\'t exist or is inaccessible.',
    actions: [
-      'Double-check your Figma file key in Settings (sensory focus)',
+      'Double-check your Figma file key in Settings',
      'Verify the file hasn\'t been deleted in Figma',
-      'Confirm you have access to the file in Figma (sensory perception)',
+      'Confirm you have access to the file in Figma',
    ],
    code: ErrorCode.FIGMA_API_ERROR,
  },
  figma_401: {
-    title: '🔌 NERVOUS SYSTEM ALERT: Authentication Expired',
-    message: 'The DSS nervous system\'s authentication with Figma has failed. Your sensory input token is invalid or expired.',
+    title: 'Authentication Failed',
+    message: 'Figma authentication failed. Your access token is invalid or expired.',
    actions: [
-      'Refresh your Figma authentication token in Settings (nervous system repair)',
-      'Get a fresh token from figma.com/settings (Account → Personal Access Tokens)',
+      'Refresh your Figma authentication token in Settings',
+      'Get a fresh token from figma.com/settings (Account -> Personal Access Tokens)',
      'Ensure you copied the full token without truncation',
    ],
    code: ErrorCode.FIGMA_CONNECTION_FAILED,
  },
  figma_429: {
-    title: '⚡ METABOLISM ALERT: Sensory Overload',
-    message: 'The DSS is sensing too quickly. Figma\'s rate limits have been triggered.',
+    title: 'Rate Limit Exceeded',
+    message: 'Too many requests. Figma\'s rate limits have been triggered.',
    actions: [
-      'Let the component rest for 1-2 minutes before sensing again',
-      'Reduce how frequently the sensory system extracts data',
+      'Wait 1-2 minutes before trying again',
+      'Reduce how frequently you extract data',
    ],
    code: ErrorCode.FIGMA_API_ERROR,
  },
  figma_500: {
-    title: '🔌 EXTERNAL SYSTEM ALERT: Figma Component Stressed',
-    message: 'Figma\'s servers are experiencing stress. This is external to DSS.',
+    title: 'Figma Server Error',
+    message: 'Figma\'s servers are experiencing issues. This is external to DSS.',
    actions: [
-      'Wait while the external component recovers',
-      'Check Figma health: status.figma.com',
+      'Wait and try again later',
+      'Check Figma status: status.figma.com',
    ],
    code: ErrorCode.FIGMA_API_ERROR,
  },
  figma_demo: {
-    title: '🛡️ IMMUNE ALERT: Invalid Sensory Configuration',
-    message: 'The sensory organs are configured to look at "demo" which doesn\'t exist in Figma.',
+    title: 'Invalid Configuration',
+    message: 'The Figma file key is configured to "demo" which doesn\'t exist in Figma.',
    actions: [
-      'Update Settings with your real Figma file key (configure sensory input)',
+      'Update Settings with your real Figma file key',
      'Find your file key in the Figma URL: figma.com/file/[FILE_KEY]/...',
      'Use the Figma file selector in Settings',
    ],
    code: ErrorCode.FIGMA_INVALID_KEY,
  },

-  // API Connection Errors - Nervous System / Heart Issues
+  // API Connection Errors
  api_network: {
-    title: '❤️ CRITICAL: Heart Not Responding',
-    message: 'The DSS nervous system cannot reach the heart (server). The component is not responding.',
+    title: 'Server Not Responding',
+    message: 'Cannot connect to the DSS server.',
    actions: [
-      'Verify the heart is beating: curl http://localhost:3456/health',
-      'Restart the heart: cd tools/api && python3 -m uvicorn server:app --port 3456',
-      'Check your network connection to the component',
+      'Verify the server is running: curl http://localhost:3456/health',
+      'Restart the server: ./scripts/dss start',
+      'Check your network connection',
    ],
    code: ErrorCode.SYSTEM_NETWORK,
  },
  api_timeout: {
-    title: '⚡ METABOLISM ALERT: Component Overloaded',
-    message: 'The DSS component took too long to respond. The heart may be stressed or metabolism sluggish.',
+    title: 'Request Timeout',
+    message: 'The server took too long to respond.',
    actions: [
-      'Let the component rest and try again shortly',
-      'Check the heart\'s logs for signs of stress: tail -f /tmp/dss-demo.log',
-      'Reduce metabolic load (try processing smaller batches)',
+      'Try again in a few moments',
+      'Check the server logs: ./scripts/dss logs',
+      'Try processing smaller batches',
    ],
    code: ErrorCode.API_TIMEOUT,
  },
  api_500: {
-    title: '🧠 BRAIN ALERT: Critical Processing Error',
-    message: 'The DSS brain encountered a fatal error while processing your request.',
+    title: 'Server Error',
+    message: 'The server encountered an error while processing your request.',
    actions: [
-      'Examine the brain\'s thoughts in the logs: tail -f /tmp/dss-demo.log',
-      'Retry the operation to see if it recovers',
-      'Report the issue if the component keeps failing',
+      'Check the server logs: ./scripts/dss logs',
+      'Retry the operation',
+      'Report the issue if it persists',
    ],
    code: ErrorCode.API_SERVER_ERROR,
  },

-  // Validation Errors - Immune System / Genetics
+  // Validation Errors
  validation_missing_field: {
-    title: '🛡️ IMMUNE ALERT: DNA Incomplete',
-    message: 'The genetic code (configuration) is missing essential information. The component cannot proceed.',
+    title: 'Missing Required Field',
+    message: 'The configuration is missing required information.',
    actions: [
-      'Fill in all fields marked as required (complete the genetic code)',
+      'Fill in all fields marked as required',
      'Ensure each input field contains valid information',
    ],
    code: ErrorCode.VALIDATION_MISSING_FIELD,
  },
  validation_invalid_format: {
-    title: '🛡️ IMMUNE ALERT: Genetic Mutation Detected',
-    message: 'One or more genetic sequences (configuration values) have an invalid format.',
+    title: 'Invalid Format',
+    message: 'One or more configuration values have an invalid format.',
    actions: [
-      'Verify URLs start with http:// or https:// (correct genetic sequence)',
-      'Check email addresses follow standard format (valid genetic code)',
-      'Ensure file keys contain only letters, numbers, and hyphens (genetic pattern match)',
+      'Verify URLs start with http:// or https://',
+      'Check email addresses follow standard format',
+      'Ensure file keys contain only letters, numbers, and hyphens',
    ],
    code: ErrorCode.VALIDATION_INVALID_FORMAT,
  },

  // Generic fallback
  unknown: {
-    title: '🧬 ORGANISM ALERT: Unexplained Symptom',
-    message: 'The DSS component experienced an unexpected problem. The root cause is unclear.',
+    title: 'Unexpected Error',
+    message: 'An unexpected problem occurred.',
    actions: [
-      'Try the operation again (component may self-heal)',
-      'Refresh if the issue persists (restart vitals)',
-      'Check browser console for clues about the component\'s condition',
+      'Try the operation again',
+      'Refresh the page if the issue persists',
+      'Check browser console for details',
    ],
    code: ErrorCode.SYSTEM_UNEXPECTED,
  },
@@ -253,7 +245,7 @@ export function handleError(error, context = {}) {
  });

  // Log full details to console for debugging
-  console.group(`🔴 ${parsed.title}`);
+  console.group(`[ERROR] ${parsed.title}`);
  console.log('Message:', parsed.message);
  if (parsed.actions) {
    console.log('Actions:', parsed.actions);
@@ -281,23 +273,23 @@ export async function tryWithErrorHandling(fn, context = {}) {
 }

 /**
- * Get user-friendly HTTP status message using component metaphors
+ * Get user-friendly HTTP status message
 * @param {number} status - HTTP status code
- * @returns {string} User-friendly message with biological context
+ * @returns {string} User-friendly message
 */
 export function getStatusMessage(status) {
  const messages = {
-    400: '🛡️ Genetic Code Invalid - the DNA sequence doesn\'t compile',
-    401: '🔐 Authentication Failed - the nervous system can\'t verify identity',
-    403: '🚫 Access Forbidden - immune system rejected this component',
-    404: '👻 Target Lost - sensory organs can\'t perceive the resource',
-    429: '⚡ Metabolism Overloaded - component sensing too quickly',
-    500: '🧠 Brain Error - critical neural processing failure',
-    502: '💀 Component Unresponsive - the heart has stopped beating',
-    503: '🏥 Component In Recovery - temporarily unable to metabolize requests',
+    400: 'Bad Request - invalid input data',
+    401: 'Authentication Failed - invalid credentials',
+    403: 'Access Forbidden - permission denied',
+    404: 'Not Found - resource doesn\'t exist',
+    429: 'Rate Limited - too many requests',
+    500: 'Server Error - internal processing failure',
+    502: 'Bad Gateway - server not responding',
+    503: 'Service Unavailable - temporarily unable to handle requests',
  };

-  return messages[status] || `🔴 Unknown Component State - HTTP ${status}`;
+  return messages[status] || `Unknown Error - HTTP ${status}`;
 }

 export default {
--- a/admin-ui/js/core/logger.js
+++ b/admin-ui/js/core/logger.js
@@ -1,35 +1,28 @@
 /**
- * DSS Logger - Component Brain Consciousness System
+ * DSS Logger - Structured Logging System
 *
- * The DSS brain uses this logger to become conscious of what's happening.
- * Log levels represent the component's level of awareness and concern.
+ * Provides structured logging with categories and levels for the DSS admin UI.
 *
- * Framework: DSS Component Framework
- * See: docs/DSS_ORGANISM_GUIDE.md#brain
- *
- * Log Categories (Organ Systems):
- *   'heart'         - ❤️ Database operations and data persistence
- *   'brain'         - 🧠 Validation, analysis, and decision making
- *   'nervous'       - 🔌 API calls, webhooks, communication
- *   'digestive'     - 🍽️ Data ingestion, parsing, transformation
- *   'circulatory'   - 🩸 Design token flow and distribution
- *   'metabolic'     - ⚡ Style-dictionary transformations
- *   'endocrine'     - 🎛️ Theme system and configuration
- *   'immune'        - 🛡️ Validation, error detection, security
- *   'sensory'       - 👁️ Asset loading, Figma perception
- *   'skin'          - 🎨 UI rendering, Storybook output
- *   'skeleton'      - 🦴 Schema and structure validation
- *
- * Provides structured logging with biological awareness levels and optional remote logging.
+ * Log Categories:
+ *   'storage'       - Database operations and data persistence
+ *   'validation'    - Validation, analysis, and decision making
+ *   'api'           - API calls, webhooks, communication
+ *   'parser'        - Data ingestion, parsing, transformation
+ *   'tokens'        - Design token flow and distribution
+ *   'transform'     - Style-dictionary transformations
+ *   'config'        - Theme system and configuration
+ *   'security'      - Validation, error detection, security
+ *   'assets'        - Asset loading, Figma integration
+ *   'ui'            - UI rendering, Storybook output
+ *   'schema'        - Schema and structure validation
 */

-// Component awareness levels - how conscious is the system?
 const LOG_LEVELS = {
-  DEBUG: 0,    // 🧠 Deep thought - brain analyzing internal processes
-  INFO: 1,     // 💭 Awareness - component knows what's happening
-  WARN: 2,     // ⚠️ Symptom - component detected something unusual
-  ERROR: 3,    // 🛡️ Immune alert - component detected a threat
-  NONE: 4      // 🌙 Sleep - component is silent
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  NONE: 4
 };

 class Logger {
@@ -76,23 +69,22 @@ class Logger {
      this.logs.shift();
    }

-    // Console output with component awareness emojis
-    const levelEmojis = {
-      DEBUG: '🧠',      // Brain thinking deeply
-      INFO: '💭',       // Component aware
-      WARN: '⚠️',       // Symptom detected
-      ERROR: '🛡️'      // Immune alert - threat detected
+    const levelIcons = {
+      DEBUG: '[D]',
+      INFO: '[I]',
+      WARN: '[W]',
+      ERROR: '[E]'
    };

    const colors = {
-      DEBUG: 'color: #666; font-style: italic',  // Gray, thoughtful
-      INFO: 'color: #2196F3; font-weight: bold',  // Blue, informative
-      WARN: 'color: #FF9800; font-weight: bold',  // Orange, warning
-      ERROR: 'color: #F44336; font-weight: bold'  // Red, critical
+      DEBUG: 'color: #666; font-style: italic',
+      INFO: 'color: #2196F3; font-weight: bold',
+      WARN: 'color: #FF9800; font-weight: bold',
+      ERROR: 'color: #F44336; font-weight: bold'
    };

-    const emoji = levelEmojis[level] || '🔘';
-    const prefix = `${emoji} [${category}]`;
+    const icon = levelIcons[level] || '[?]';
+    const prefix = `${icon} [${category}]`;
    const style = colors[level] || '';

    if (data) {
@@ -120,56 +112,49 @@ class Logger {
  }

  /**
-   * 🧠 DEBUG - Brain's deep thoughts
-   * Internal analysis and detailed consciousness
+   * DEBUG - Detailed internal information
   */
  debug(category, message, data) {
    this._log('DEBUG', category, message, data);
  }

  /**
-   * 💭 INFO - Component awareness
-   * The system knows what's happening, stays informed
+   * INFO - General information
   */
  info(category, message, data) {
    this._log('INFO', category, message, data);
  }

  /**
-   * ⚠️ WARN - Symptom detection
-   * Component detected something unusual but not critical
+   * WARN - Warning, something unusual detected
   */
  warn(category, message, data) {
    this._log('WARN', category, message, data);
  }

  /**
-   * 🛡️ ERROR - Immune alert
-   * Component detected a threat - critical consciousness
+   * ERROR - Error, something went wrong
   */
  error(category, message, data) {
    this._log('ERROR', category, message, data);
  }

  /**
-   * 📜 Get recent consciousness records
-   * Retrieve the component's recent thoughts and awareness
+   * Get recent log entries
   */
  getRecentLogs(count = 50) {
    return this.logs.slice(-count);
  }

  /**
-   * 🧠 Clear the mind
-   * Erase recent consciousness logs
+   * Clear all logs
   */
  clear() {
    this.logs = [];
  }

  /**
-   * 📤 Export consciousness
-   * Save the component's awareness to a file for analysis
+   * Export logs to file
   */
  export() {
    const dataStr = JSON.stringify(this.logs, null, 2);
@@ -185,13 +170,11 @@ class Logger {
 }

 /**
- * 🧠 ORGANISM CONSCIOUSNESS
- * Create the DSS component's brain - a singleton logger that tracks all awareness
+ * DSS Logger singleton
 */
 const logger = new Logger('DSS', 'INFO');

 // Set log level from localStorage or URL param
-// Allow tuning the component's consciousness level (awareness sensitivity)
 const urlParams = new URLSearchParams(window.location.search);
 const logLevel = urlParams.get('log') || localStorage.getItem('dss_log_level') || 'INFO';
 logger.setLevel(logLevel.toUpperCase());
--- a/apps/api/server.py
+++ b/apps/api/server.py
@@ -353,7 +353,7 @@ class TokenDriftCreate(BaseModel):

 # === Authentication ===

-from auth.atlassian_auth import get_auth
+from dss.auth.atlassian_auth import get_auth

 async def get_current_user(authorization: Optional[str] = Header(None)) -> Dict[str, Any]:
    """
@@ -421,71 +421,62 @@ async def root():
@app.get("/health")
 async def health():
    """
-    🏥 ORGANISM VITAL SIGNS CHECK
+    Health check endpoint.

-    Performs a complete health diagnostic on the DSS component.
-    Returns 200 OK with vital signs if component is healthy.
+    Performs a complete health diagnostic on the DSS server.
+    Returns 200 OK with service status.

-    Vital Signs Checked:
-    - ❤️ Heart (Database) - Is the source of truth responsive?
-    - 🧠 Brain (MCP Handler) - Is the decision-making system online?
-    - 👁️ Sensory (Figma) - Are the external perception organs configured?
+    Services Checked:
+    - Storage - Is the data directory accessible?
+    - MCP Handler - Is the MCP handler initialized?
+    - Figma - Is the Figma integration configured?
    """
    import os
    import psutil
    from pathlib import Path

-    # ❤️ Check Heart (storage) connectivity
-    db_ok = False
+    # Check storage connectivity
+    storage_ok = False
    try:
-        from storage.json_store import DATA_DIR
-        db_ok = DATA_DIR.exists()
+        from dss.storage.json_store import DATA_DIR
+        storage_ok = DATA_DIR.exists()
    except Exception as e:
        import traceback
-        error_trace = traceback.format_exc()
-        print(f"🏥 VITAL SIGN: Heart (storage) error: {type(e).__name__}: {e}", flush=True)
-        print(f"   Traceback:\n{error_trace}", flush=True)
-        pass
+        print(f"[Health] Storage check error: {type(e).__name__}: {e}", flush=True)

-    # 🧠 Check Brain (MCP handler) functionality
+    # Check MCP handler functionality
    mcp_ok = False
    try:
        import sys
        from pathlib import Path
-        # Add project root to path (two levels up from tools/api)
        project_root = Path(__file__).parent.parent.parent
        if str(project_root) not in sys.path:
            sys.path.insert(0, str(project_root))

-        from tools.dss_mcp.handler import get_mcp_handler
+        from dss.mcp.handler import get_mcp_handler
        handler = get_mcp_handler()
        mcp_ok = handler is not None
    except Exception as e:
        import traceback
-        error_trace = ''.join(traceback.format_exception(type(e), e, e.__traceback__))
-        print(f"🧠 BRAIN CHECK: MCP handler error: {type(e).__name__}: {e}", flush=True)
-        print(f"   Traceback:\n{error_trace}", flush=True)
+        print(f"[Health] MCP handler check error: {type(e).__name__}: {e}", flush=True)

-    # Get uptime (how long component has been conscious)
+    # Get uptime
    try:
        process = psutil.Process(os.getpid())
        uptime_seconds = int((datetime.now() - datetime.fromtimestamp(process.create_time())).total_seconds())
    except:
        uptime_seconds = 0

-    # Overall vitality assessment
-    status = "healthy" if (db_ok and mcp_ok) else "degraded"
+    # Overall status
+    status = "healthy" if (storage_ok and mcp_ok) else "degraded"

    return {
        "status": status,
-        "vital_signs": {
-            "overall": "🟢 All systems nominal" if status == "healthy" else "🟡 System degradation detected",
-            "consciousness_duration_seconds": uptime_seconds
-        },
+        "uptime_seconds": uptime_seconds,
        "version": "0.8.0",
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "services": {
-            "storage": "ok" if db_ok else "error",
+            "storage": "ok" if storage_ok else "error",
            "mcp": "ok" if mcp_ok else "error",
            "figma": "connected" if config.figma.is_configured else "not configured"
        }
--- a/apps/cli/src/cli.ts
+++ b/apps/cli/src/cli.ts
@@ -1,18 +1,16 @@
 #!/usr/bin/env node
 /**
- * 🧬 DSS CLI - Design System Server Organism Controller
+ * DSS CLI - Design System Server Command Line Interface
 *
- * A portable companion for UI developers - think of it as the organism's
- * command-line nervous system. Through these commands, you can:
+ * A portable companion for UI developers. Commands:
 *
- * - 🧬 Awaken a new organism (init)
- * - 💚 Check the organism's vital signs (status)
- * - 🩸 Direct the sensory organs to perceive Figma (extract)
- * - 🔄 Circulate extracted nutrients (sync)
- * - ⚙️ Adjust the organism's behavior (config)
- * - 🧠 Birth a conscious instance (start)
- *
- * Framework: DSS Organism Framework
+ * - init: Initialize DSS in a project
+ * - status: Check server status
+ * - extract: Extract tokens/components from Figma
+ * - sync: Sync tokens to codebase
+ * - config: Manage configuration
+ * - start: Start the server
+ * - stop: Stop the server
 */

 import { Command } from 'commander';
@@ -29,63 +27,63 @@ const program = new Command();

 program
  .name('dss')
-  .description('🧬 Design System Server - Organism Controller for UI Developers')
+  .description('Design System Server - CLI for UI Developers')
  .version('0.1.0');

 // Init command - setup DSS in a project
 program
  .command('init')
-  .description('🧬 ORGANISM GENESIS - Create a new design system organism in your project')
-  .option('-f, --figma-key <key>', 'Link to Figma genetic blueprint')
-  .option('-t, --figma-token <token>', 'Figma sensory organ connection token')
+  .description('Initialize DSS in your project')
+  .option('-f, --figma-key <key>', 'Figma file key')
+  .option('-t, --figma-token <token>', 'Figma access token')
  .action(initCommand);

 // Start command - start the DSS server
 program
  .command('start')
-  .description('💚 ORGANISM AWAKENING - Bring the design system organism to life')
-  .option('-p, --port <port>', 'Neural pathway port', '3456')
-  .option('-d, --dev', 'Live consciousness mode with hot-reload')
-  .option('--no-open', 'Do not open sensory interface')
+  .description('Start the DSS server')
+  .option('-p, --port <port>', 'Server port', '3456')
+  .option('-d, --dev', 'Development mode with hot-reload')
+  .option('--no-open', 'Do not open browser')
  .action(startCommand);

 // Sync command - sync tokens from Figma
 program
  .command('sync')
-  .description('🩸 NUTRIENT CIRCULATION - Distribute extracted tokens through the codebase')
-  .option('-f, --format <format>', 'Nutrient format: css, scss, json, ts', 'css')
-  .option('-o, --output <path>', 'Circulation destination')
+  .description('Sync tokens from Figma to codebase')
+  .option('-f, --format <format>', 'Output format: css, scss, json, ts', 'css')
+  .option('-o, --output <path>', 'Output directory')
  .option('--file-key <key>', 'Figma file key (overrides config)')
  .action(syncCommand);

 // Extract command - extract components or tokens
 program
  .command('extract <type>')
-  .description('👁️ SENSORY PERCEPTION - Direct organism eyes to perceive Figma designs')
-  .option('-f, --format <format>', 'Perception output format', 'json')
-  .option('-o, --output <path>', 'Memory storage location')
+  .description('Extract components or tokens from Figma')
+  .option('-f, --format <format>', 'Output format', 'json')
+  .option('-o, --output <path>', 'Output location')
  .option('--file-key <key>', 'Figma file key')
  .action(extractCommand);

 // Config command - manage configuration
 program
  .command('config')
-  .description('⚙️ ENDOCRINE ADJUSTMENT - Configure organism behavior and preferences')
-  .option('--set <key=value>', 'Set organism hormone value')
-  .option('--get <key>', 'Read organism hormone value')
-  .option('--list', 'View all hormones')
+  .description('Manage DSS configuration')
+  .option('--set <key=value>', 'Set configuration value')
+  .option('--get <key>', 'Get configuration value')
+  .option('--list', 'List all configuration')
  .action(configCommand);

 // Stop command - stop the server
 program
  .command('stop')
-  .description('😴 ORGANISM REST - Put the design system organism into sleep mode')
+  .description('Stop the DSS server')
  .action(stopCommand);

 // Status command - check DSS status
 program
  .command('status')
-  .description('🏥 VITAL SIGNS CHECK - Monitor organism health and configuration')
+  .description('Check DSS server status and configuration')
  .action(statusCommand);

 // Parse arguments
--- a/apps/cli/src/commands/status.ts
+++ b/apps/cli/src/commands/status.ts
@@ -1,8 +1,7 @@
 /**
- * 🏥 DSS Status Command - Organism Vital Signs
+ * DSS Status Command
 *
- * Check DSS design system organism's vital signs, consciousness state,
- * and sensory organ configuration.
+ * Check DSS server status and configuration.
 */

 import chalk from 'chalk';
@@ -15,48 +14,48 @@ export async function statusCommand(): Promise<void> {
  const config = getConfig();

  console.log('');
-  console.log(chalk.cyan('  🏥 ORGANISM VITAL SIGNS'));
+  console.log(chalk.cyan('  DSS Status'));
  console.log(chalk.dim('  ────────────────────────'));
  console.log('');

-  // Organism status
+  // Project status
  if (hasProjectConfig()) {
-    console.log(chalk.green('  🧬 Organism:'), chalk.dim('Born and conscious'));
-    console.log(chalk.dim(`    Home: ${cwd}`));
+    console.log(chalk.green('  Project:'), chalk.dim('Initialized'));
+    console.log(chalk.dim(`    Root: ${cwd}`));
  } else {
-    console.log(chalk.yellow('  🧬 Organism:'), chalk.dim('Not yet born'));
-    console.log(chalk.dim('    Genesis: dss init'));
+    console.log(chalk.yellow('  Project:'), chalk.dim('Not initialized'));
+    console.log(chalk.dim('    Initialize: dss init'));
  }

  console.log('');

-  // Consciousness status (server)
+  // Server status
  const running = isServerRunning(cwd);
  const pid = getServerPid(cwd);
  const port = config.port || 3456;

  if (running) {
-    console.log(chalk.green('  💚 Consciousness:'), chalk.dim(`Awake (PID: ${pid})`));
-    console.log(chalk.dim(`    Neural port: http://localhost:${port}`));
+    console.log(chalk.green('  Server:'), chalk.dim(`Running (PID: ${pid})`));
+    console.log(chalk.dim(`    URL: http://localhost:${port}`));

    // Try to get health info
    try {
      const api = getApiClient({ port });
      const health = await api.health();
-      console.log(chalk.dim(`    Awareness: ${health.figma_mode}`));
+      console.log(chalk.dim(`    Mode: ${health.figma_mode}`));
    } catch {
-      console.log(chalk.yellow('    ⚠️  Unable to read consciousness'));
+      console.log(chalk.yellow('    Unable to get health status'));
    }
  } else {
-    console.log(chalk.yellow('  💚 Consciousness:'), chalk.dim('Sleeping'));
-    console.log(chalk.dim('    Awaken: dss start'));
+    console.log(chalk.yellow('  Server:'), chalk.dim('Stopped'));
+    console.log(chalk.dim('    Start: dss start'));
  }

  console.log('');

-  // Sensory organs (Figma)
+  // Figma integration
  if (config.figmaToken) {
-    console.log(chalk.green('  👁️ Sensory Eyes:'), chalk.dim('Configured'));
+    console.log(chalk.green('  Figma:'), chalk.dim('Configured'));

    // Test connection if server is running
    if (running) {
@@ -64,21 +63,21 @@ export async function statusCommand(): Promise<void> {
        const api = getApiClient({ port });
        const test = await api.testFigmaConnection();
        if (test.success) {
-          console.log(chalk.green('    Perception:'), chalk.dim(`Clear (${test.user})`));
+          console.log(chalk.green('    Connection:'), chalk.dim(`OK (${test.user})`));
        } else {
-          console.log(chalk.red('    Perception:'), chalk.dim(test.error || 'Blinded'));
+          console.log(chalk.red('    Connection:'), chalk.dim(test.error || 'Failed'));
        }
      } catch {
-        console.log(chalk.yellow('    Perception:'), chalk.dim('Cannot test'));
+        console.log(chalk.yellow('    Connection:'), chalk.dim('Cannot test'));
      }
    }
  } else {
-    console.log(chalk.yellow('  👁️ Sensory Eyes:'), chalk.dim('Not configured'));
+    console.log(chalk.yellow('  Figma:'), chalk.dim('Not configured'));
    console.log(chalk.dim('    Configure: dss config --set figmaToken=figd_xxxxx'));
  }

  if (config.figmaFileKey) {
-    console.log(chalk.green('  📋 Genetic Blueprint:'), chalk.dim(config.figmaFileKey));
+    console.log(chalk.green('  Figma File:'), chalk.dim(config.figmaFileKey));
  } else {
    console.log(chalk.yellow('  Figma File:'), chalk.dim('Not configured'));
    console.log(chalk.dim('    Set: dss config --set figmaFileKey=abc123'));
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1,18 +1,16 @@
 #!/usr/bin/env node
 /**
- * 🧬 DSS CLI - Design System Server Organism Controller
+ * DSS CLI - Design System Server Command Line Interface
 *
- * A portable companion for UI developers - think of it as the organism's
- * command-line nervous system. Through these commands, you can:
+ * A portable companion for UI developers. Commands:
 *
- * - 🧬 Awaken a new organism (init)
- * - 💚 Check the organism's vital signs (status)
- * - 🩸 Direct the sensory organs to perceive Figma (extract)
- * - 🔄 Circulate extracted nutrients (sync)
- * - ⚙️ Adjust the organism's behavior (config)
- * - 🧠 Birth a conscious instance (start)
- *
- * Framework: DSS Organism Framework
+ * - init: Initialize DSS in a project
+ * - status: Check server status
+ * - extract: Extract tokens/components from Figma
+ * - sync: Sync tokens to codebase
+ * - config: Manage configuration
+ * - start: Start the server
+ * - stop: Stop the server
 */

 import { Command } from 'commander';
@@ -29,63 +27,63 @@ const program = new Command();

 program
  .name('dss')
-  .description('🧬 Design System Server - Organism Controller for UI Developers')
+  .description('Design System Server - CLI for UI Developers')
  .version('0.1.0');

 // Init command - setup DSS in a project
 program
  .command('init')
-  .description('🧬 ORGANISM GENESIS - Create a new design system organism in your project')
-  .option('-f, --figma-key <key>', 'Link to Figma genetic blueprint')
-  .option('-t, --figma-token <token>', 'Figma sensory organ connection token')
+  .description('Initialize DSS in your project')
+  .option('-f, --figma-key <key>', 'Figma file key')
+  .option('-t, --figma-token <token>', 'Figma access token')
  .action(initCommand);

 // Start command - start the DSS server
 program
  .command('start')
-  .description('💚 ORGANISM AWAKENING - Bring the design system organism to life')
-  .option('-p, --port <port>', 'Neural pathway port', '3456')
-  .option('-d, --dev', 'Live consciousness mode with hot-reload')
-  .option('--no-open', 'Do not open sensory interface')
+  .description('Start the DSS server')
+  .option('-p, --port <port>', 'Server port', '3456')
+  .option('-d, --dev', 'Development mode with hot-reload')
+  .option('--no-open', 'Do not open browser')
  .action(startCommand);

 // Sync command - sync tokens from Figma
 program
  .command('sync')
-  .description('🩸 NUTRIENT CIRCULATION - Distribute extracted tokens through the codebase')
-  .option('-f, --format <format>', 'Nutrient format: css, scss, json, ts', 'css')
-  .option('-o, --output <path>', 'Circulation destination')
+  .description('Sync tokens from Figma to codebase')
+  .option('-f, --format <format>', 'Output format: css, scss, json, ts', 'css')
+  .option('-o, --output <path>', 'Output directory')
  .option('--file-key <key>', 'Figma file key (overrides config)')
  .action(syncCommand);

 // Extract command - extract components or tokens
 program
  .command('extract <type>')
-  .description('👁️ SENSORY PERCEPTION - Direct organism eyes to perceive Figma designs')
-  .option('-f, --format <format>', 'Perception output format', 'json')
-  .option('-o, --output <path>', 'Memory storage location')
+  .description('Extract components or tokens from Figma')
+  .option('-f, --format <format>', 'Output format', 'json')
+  .option('-o, --output <path>', 'Output location')
  .option('--file-key <key>', 'Figma file key')
  .action(extractCommand);

 // Config command - manage configuration
 program
  .command('config')
-  .description('⚙️ ENDOCRINE ADJUSTMENT - Configure organism behavior and preferences')
-  .option('--set <key=value>', 'Set organism hormone value')
-  .option('--get <key>', 'Read organism hormone value')
-  .option('--list', 'View all hormones')
+  .description('Manage DSS configuration')
+  .option('--set <key=value>', 'Set configuration value')
+  .option('--get <key>', 'Get configuration value')
+  .option('--list', 'List all configuration')
  .action(configCommand);

 // Stop command - stop the server
 program
  .command('stop')
-  .description('😴 ORGANISM REST - Put the design system organism into sleep mode')
+  .description('Stop the DSS server')
  .action(stopCommand);

 // Status command - check DSS status
 program
  .command('status')
-  .description('🏥 VITAL SIGNS CHECK - Monitor organism health and configuration')
+  .description('Check DSS server status and configuration')
  .action(statusCommand);

 // Parse arguments
--- a/cli/src/commands/status.ts
+++ b/cli/src/commands/status.ts
@@ -1,8 +1,7 @@
 /**
- * 🏥 DSS Status Command - Organism Vital Signs
+ * DSS Status Command
 *
- * Check DSS design system organism's vital signs, consciousness state,
- * and sensory organ configuration.
+ * Check DSS server status and configuration.
 */

 import chalk from 'chalk';
@@ -15,48 +14,48 @@ export async function statusCommand(): Promise<void> {
  const config = getConfig();

  console.log('');
-  console.log(chalk.cyan('  🏥 ORGANISM VITAL SIGNS'));
+  console.log(chalk.cyan('  DSS Status'));
  console.log(chalk.dim('  ────────────────────────'));
  console.log('');

-  // Organism status
+  // Project status
  if (hasProjectConfig()) {
-    console.log(chalk.green('  🧬 Organism:'), chalk.dim('Born and conscious'));
-    console.log(chalk.dim(`    Home: ${cwd}`));
+    console.log(chalk.green('  Project:'), chalk.dim('Initialized'));
+    console.log(chalk.dim(`    Root: ${cwd}`));
  } else {
-    console.log(chalk.yellow('  🧬 Organism:'), chalk.dim('Not yet born'));
-    console.log(chalk.dim('    Genesis: dss init'));
+    console.log(chalk.yellow('  Project:'), chalk.dim('Not initialized'));
+    console.log(chalk.dim('    Initialize: dss init'));
  }

  console.log('');

-  // Consciousness status (server)
+  // Server status
  const running = isServerRunning(cwd);
  const pid = getServerPid(cwd);
  const port = config.port || 3456;

  if (running) {
-    console.log(chalk.green('  💚 Consciousness:'), chalk.dim(`Awake (PID: ${pid})`));
-    console.log(chalk.dim(`    Neural port: http://localhost:${port}`));
+    console.log(chalk.green('  Server:'), chalk.dim(`Running (PID: ${pid})`));
+    console.log(chalk.dim(`    URL: http://localhost:${port}`));

    // Try to get health info
    try {
      const api = getApiClient({ port });
      const health = await api.health();
-      console.log(chalk.dim(`    Awareness: ${health.figma_mode}`));
+      console.log(chalk.dim(`    Mode: ${health.figma_mode}`));
    } catch {
-      console.log(chalk.yellow('    ⚠️  Unable to read consciousness'));
+      console.log(chalk.yellow('    Unable to get health status'));
    }
  } else {
-    console.log(chalk.yellow('  💚 Consciousness:'), chalk.dim('Sleeping'));
-    console.log(chalk.dim('    Awaken: dss start'));
+    console.log(chalk.yellow('  Server:'), chalk.dim('Stopped'));
+    console.log(chalk.dim('    Start: dss start'));
  }

  console.log('');

-  // Sensory organs (Figma)
+  // Figma integration
  if (config.figmaToken) {
-    console.log(chalk.green('  👁️ Sensory Eyes:'), chalk.dim('Configured'));
+    console.log(chalk.green('  Figma:'), chalk.dim('Configured'));

    // Test connection if server is running
    if (running) {
@@ -64,21 +63,21 @@ export async function statusCommand(): Promise<void> {
        const api = getApiClient({ port });
        const test = await api.testFigmaConnection();
        if (test.success) {
-          console.log(chalk.green('    Perception:'), chalk.dim(`Clear (${test.user})`));
+          console.log(chalk.green('    Connection:'), chalk.dim(`OK (${test.user})`));
        } else {
-          console.log(chalk.red('    Perception:'), chalk.dim(test.error || 'Blinded'));
+          console.log(chalk.red('    Connection:'), chalk.dim(test.error || 'Failed'));
        }
      } catch {
-        console.log(chalk.yellow('    Perception:'), chalk.dim('Cannot test'));
+        console.log(chalk.yellow('    Connection:'), chalk.dim('Cannot test'));
      }
    }
  } else {
-    console.log(chalk.yellow('  👁️ Sensory Eyes:'), chalk.dim('Not configured'));
+    console.log(chalk.yellow('  Figma:'), chalk.dim('Not configured'));
    console.log(chalk.dim('    Configure: dss config --set figmaToken=figd_xxxxx'));
  }

  if (config.figmaFileKey) {
-    console.log(chalk.green('  📋 Genetic Blueprint:'), chalk.dim(config.figmaFileKey));
+    console.log(chalk.green('  Figma File:'), chalk.dim(config.figmaFileKey));
  } else {
    console.log(chalk.yellow('  Figma File:'), chalk.dim('Not configured'));
    console.log(chalk.dim('    Set: dss config --set figmaFileKey=abc123'));
--- a/dss/init.py
+++ b/dss/init.py
@@ -56,15 +56,14 @@ from dss.ingest.base import (

 # Export/Import
 from dss.export_import.service import DSSArchiveExporter, DSSArchiveImporter
-from dss.export_import.smart_merger import SmartMerger
+from dss.export_import.merger import SmartMerger

 # Storybook
 from dss.storybook.generator import StoryGenerator
 from dss.storybook.scanner import StorybookScanner

 # Translations
-from dss.translations.dictionary import TranslationDictionary
-from dss.translations.resolver import TokenResolver
+from dss.translations import TranslationDictionary, TokenResolver

 # Services
 from dss.services.project_manager import ProjectManager
--- a/dss/auth/atlassian_auth.py
+++ b/dss/auth/atlassian_auth.py
@@ -12,7 +12,7 @@ from datetime import datetime, timedelta
 from typing import Optional, Dict, Any
 from atlassian import Jira, Confluence

-from storage.json_store import read_json, write_json, SYSTEM_DIR
+from dss.storage.json_store import read_json, write_json, SYSTEM_DIR


 class AtlassianAuth:
--- a/dss/export_import/merger.py
+++ b/dss/export_import/merger.py
@@ -10,7 +10,7 @@ from .security import TimestampConflictResolver
 from ..models.project import Project
 from ..models.theme import DesignToken
 from ..models.component import Component
-from storage.json_store import Projects, Components, Tokens
+from dss.storage.json_store import Projects, Components, Tokens


 MergeStrategy = Literal["overwrite", "keep_local", "fork", "skip"]
--- a/dss/export_import/service.py
+++ b/dss/export_import/service.py
@@ -20,7 +20,7 @@ from .importer import DSSArchiveImporter, ImportAnalysis
 from .merger import SmartMerger, ConflictResolutionMode, MergeAnalysis
 from .security import DatabaseLockingStrategy, MemoryLimitManager
 from ..models.project import Project
-from storage.json_store import Projects, ActivityLog
+from dss.storage.json_store import Projects, ActivityLog


@dataclass
--- a/dss/figma/figma_tools.py
+++ b/dss/figma/figma_tools.py
@@ -19,18 +19,14 @@ Tools:
 import json
 import hashlib
 import asyncio
-import sys
 from datetime import datetime
 from typing import Optional, Dict, List, Any
 from dataclasses import dataclass, asdict
 from pathlib import Path
 import httpx

-# Add parent to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from config import config
-from storage.json_store import Cache, ActivityLog
+from dss.settings import settings
+from dss.storage.json_store import Cache, ActivityLog

@dataclass
 class DesignToken:
@@ -67,9 +63,9 @@ class FigmaClient:
    """

    def __init__(self, token: Optional[str] = None):
-        self.token = token or config.figma.token
+        self.token = token or settings.FIGMA_TOKEN
        self.base_url = "https://api.figma.com/v1"
-        self.cache_ttl = config.figma.cache_ttl
+        self.cache_ttl = settings.FIGMA_CACHE_TTL
        self._use_real_api = bool(self.token)

    def _cache_key(self, endpoint: str) -> str:
--- a/dss/mcp/audit.py
+++ b/dss/mcp/audit.py
@@ -11,7 +11,7 @@ from typing import Optional, Dict, Any
 from datetime import datetime
 from enum import Enum

-from storage.json_store import ActivityLog, append_jsonl, read_jsonl, SYSTEM_DIR  # JSON storage
+from dss.storage.json_store import ActivityLog, append_jsonl, read_jsonl, SYSTEM_DIR  # JSON storage


 class AuditEventType(Enum):
--- a/dss/mcp/context/project_context.py
+++ b/dss/mcp/context/project_context.py
@@ -17,7 +17,7 @@ from pathlib import Path
 import sys
 sys.path.insert(0, str(Path(__file__).parent.parent.parent))

-from storage.json_store import Projects, Components, Tokens
+from dss.storage.json_store import Projects, Components, Tokens
 from analyze.scanner import ProjectScanner
 from ..config import mcp_config

--- a/dss/mcp/handler.py
+++ b/dss/mcp/handler.py
@@ -22,7 +22,7 @@ from pathlib import Path
 # Note: sys.path is set up by the importing module (server.py)
 # Do NOT modify sys.path here as it causes relative import issues

-from storage.json_store import Projects, ActivityLog
+from dss.storage.json_store import Projects, ActivityLog
 from .config import mcp_config, integration_config
 from .context.project_context import get_context_manager, ProjectContext
 from .tools.project_tools import PROJECT_TOOLS, ProjectTools
--- a/dss/mcp/integrations/base.py
+++ b/dss/mcp/integrations/base.py
@@ -12,7 +12,7 @@ from datetime import datetime, timedelta
 from enum import Enum

 from ..config import mcp_config
-from storage.json_store import Cache, read_json, write_json, SYSTEM_DIR
+from dss.storage.json_store import Cache, read_json, write_json, SYSTEM_DIR


 class CircuitState(Enum):
--- a/dss/mcp/operations.py
+++ b/dss/mcp/operations.py
@@ -13,7 +13,7 @@ from datetime import datetime
 from enum import Enum

 from .config import mcp_config
-from storage.json_store import ActivityLog, read_json, write_json, DATA_DIR  # JSON storage
+from dss.storage.json_store import ActivityLog, read_json, write_json, DATA_DIR  # JSON storage


 class OperationStatus(Enum):
--- a/dss/mcp/security.py
+++ b/dss/mcp/security.py
@@ -16,7 +16,7 @@ from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
 from cryptography.hazmat.backends import default_backend

 from .config import mcp_config
-from storage.json_store import read_json, write_json, SYSTEM_DIR  # JSON storage
+from dss.storage.json_store import read_json, write_json, SYSTEM_DIR  # JSON storage


 class CredentialVault:
--- a/dss/mcp/tools/project_tools.py
+++ b/dss/mcp/tools/project_tools.py
@@ -20,7 +20,7 @@ from mcp import types
 from ..context.project_context import get_context_manager
 from ..security import CredentialVault
 from ..audit import AuditLog, AuditEventType
-from storage.json_store import Projects, Components, Tokens, ActivityLog  # JSON storage
+from dss.storage.json_store import Projects, Components, Tokens, ActivityLog  # JSON storage
 from ..handler import get_mcp_handler, MCPContext


--- a/dss/services/project_manager.py
+++ b/dss/services/project_manager.py
@@ -28,7 +28,7 @@ class ProjectManager:
        Initialize project manager.

        Args:
-            projects_db: Projects database class (from storage.database)
+            projects_db: Projects database class (from dss.storage.database)
            config_service: Optional ConfigService for config initialization
        """
        self.db = projects_db
--- a/dss/status/dashboard.py
+++ b/dss/status/dashboard.py
@@ -190,7 +190,7 @@ class StatusDashboard:

        # Database stats
        try:
-            from storage.json_store import get_stats, ActivityLog, SyncHistory, Projects, Components
+            from dss.storage.json_store import get_stats, ActivityLog, SyncHistory, Projects, Components

            stats = get_stats()
            data.projects_count = stats.get("projects", 0)
--- a/tests/test_project_analyzer.py
+++ b/tests/test_project_analyzer.py
@@ -21,7 +21,8 @@ def test_run_project_analysis(mock_react_project: Path):

    # Verify the graph structure
    assert "nodes" in data, "Graph data should contain 'nodes'."
-    assert "links" in data, "Graph data should contain 'links'."
+    # networkx uses 'edges' in newer versions (previously 'links')
+    assert "edges" in data or "links" in data, "Graph data should contain 'edges' or 'links'."

    # Get a list of node IDs (which are the relative file paths)
    node_ids = [node['id'] for node in data['nodes']]