@knowcode/doc-builder 1.9.5 → 1.9.7

package/html/vercel-first-time-setup-guide.html

@@ -98,8 +98,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-29T08:43:44.010Z",
-  "dateModified": "2025-07-29T08:43:44.010Z",
+  "datePublished": "2025-07-29T09:30:31.384Z",
+  "dateModified": "2025-07-29T09:30:31.384Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html"
@@ -132,7 +132,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.9.5">Last updated: Jul 29, 2025, 08:43 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.9.5">Last updated: Jul 29, 2025, 09:30 AM UTC</span>
                 </div>
                 
                 
@@ -182,64 +182,64 @@
                 
       <div class="nav-section" data-level="0">
         <a class="nav-title" href="/README.html"  >
-          <i class="fas fa-home"></i> Documentation
+          <i class="ph ph-house"></i> Documentation
         </a>
         <div class="nav-content" >
-        <a href="/README.html" class="nav-item" data-tooltip="@knowcode/doc-builder."><i class="fas fa-file-alt"></i> Overview</a>
-        <a href="/documentation-index.html" class="nav-item" data-tooltip="This directory contains additional documentation for the @knowcode/doc-builder project, organized by topic and purpose."><i class="fas fa-file-alt"></i> Documentation Index</a>
-        <a href="/image-modal-test.html" class="nav-item" data-tooltip="This document tests the new image modal functionality in doc-builder."><i class="fas fa-file-alt"></i> Image Modal Test</a>
-        <a href="/vercel-cli-setup-guide.html" class="nav-item" data-tooltip="This guide provides comprehensive instructions for installing the Vercel CLI across different operating systems."><i class="fas fa-file-alt"></i> Vercel Cli Setup Guide</a>
-        <a href="/vercel-first-time-setup-guide.html" class="nav-item active" data-tooltip="This guide walks you through the Vercel deployment process when using ."><i class="fas fa-file-alt"></i> Vercel First Time Setup Guide</a></div></div>
+        <a href="/README.html" class="nav-item" data-tooltip="@knowcode/doc-builder."><i class="ph ph-file-text"></i> Overview</a>
+        <a href="/documentation-index.html" class="nav-item" data-tooltip="This directory contains additional documentation for the @knowcode/doc-builder project, organized by topic and purpose."><i class="ph ph-pencil-simple" style="color: #d97706;"></i> Documentation Index</a>
+        <a href="/image-modal-test.html" class="nav-item" data-tooltip="This document tests the new image modal functionality in doc-builder."><i class="ph ph-file-text"></i> Image Modal Test</a>
+        <a href="/vercel-cli-setup-guide.html" class="nav-item" data-tooltip="This guide provides comprehensive instructions for installing the Vercel CLI across different operating systems."><i class="ph ph-check-circle" style="color: #059669;"></i> Vercel Cli Setup Guide</a>
+        <a href="/vercel-first-time-setup-guide.html" class="nav-item active" data-tooltip="This guide walks you through the Vercel deployment process when using ."><i class="ph ph-check-circle" style="color: #059669;"></i> Vercel First Time Setup Guide</a></div></div>
       <div class="nav-section" data-level="1">
         <a class="nav-title collapsible" href="#" data-target="nav-guides-1" >
-          <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Guides
+          <i class="ph ph-caret-right collapse-icon"></i><i class="ph ph-book"></i> Guides
         </a>
         <div class="nav-content collapsed" id="nav-guides-1">
-        <a href="/guides/authentication-default-change.html" class="nav-item" data-tooltip="Starting from version 1.7.4, @knowcode/doc-builder now defaults to no authentication for all documentation sites."><i class="fas fa-file-alt"></i> Authentication Default Change</a>
-        <a href="/guides/authentication-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase - a secure, scalable authentication platform."><i class="fas fa-file-alt"></i> Authentication Guide</a>
-        <a href="/guides/claude-workflow-guide.html" class="nav-item" data-tooltip="This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a>
-        <a href="/guides/documentation-standards.html" class="nav-item" data-tooltip="This document defines the documentation standards and conventions for the @knowcode/doc-builder project."><i class="fas fa-file-alt"></i> Documentation Standards</a>
-        <a href="/guides/html-embedding-guide.html" class="nav-item" data-tooltip="Starting from version 1.9.2, doc-builder treats HTML files ( and ) as attachments that are automatically copied to your output directory during the..."><i class="fas fa-file-alt"></i> Html Embedding Guide</a>
-        <a href="/guides/image-modal-guide.html" class="nav-item" data-tooltip="When users click on any image in your generated documentation, it opens in a professional modal overlay with: Full-screen viewing experience Smooth..."><i class="fas fa-file-alt"></i> Image Modal Guide</a>
-        <a href="/guides/phosphor-icons-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder automatically converts Unicode emojis in your markdown files to beautiful Phosphor icons in the generated HTML."><i class="fas fa-file-alt"></i> Phosphor Icons Guide</a>
-        <a href="/guides/private-directory-authentication.html" class="nav-item" data-tooltip="The @knowcode/doc-builder provides flexible authentication options to protect your documentation."><i class="fas fa-file-alt"></i> Private Directory Authentication</a>
-        <a href="/guides/private-directory-authentication-troubleshooting.html" class="nav-item" data-tooltip="Private Directory Authentication Troubleshooting."><i class="fas fa-file-alt"></i> Private Directory Authentication Troubleshooting</a>
-        <a href="/guides/public-site-deployment.html" class="nav-item" data-tooltip="The @knowcode/doc-builder now supports deploying public documentation sites without authentication."><i class="fas fa-file-alt"></i> Public Site Deployment</a>
-        <a href="/guides/search-engine-verification-guide.html" class="nav-item" data-tooltip="Search engine verification provides access to powerful webmaster tools:."><i class="fas fa-file-alt"></i> Search Engine Verification Guide</a>
-        <a href="/guides/seo-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features to help your documentation rank better in search results and..."><i class="fas fa-file-alt"></i> Seo Guide</a>
-        <a href="/guides/seo-optimization-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features that automatically optimize your documentation for search..."><i class="fas fa-file-alt"></i> Seo Optimization Guide</a>
-        <a href="/guides/troubleshooting-guide.html" class="nav-item" data-tooltip="This guide helps you resolve common issues when using @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Troubleshooting Guide</a>
-        <a href="/guides/windows-setup-guide.html" class="nav-item" data-tooltip="This guide helps Windows users set up the complete AI-powered documentation workflow using Claude Code, @knowcode/doc-builder, and Vercel."><i class="fas fa-file-alt"></i> Windows Setup Guide</a></div></div>
+        <a href="/guides/authentication-default-change.html" class="nav-item" data-tooltip="Starting from version 1.7.4, @knowcode/doc-builder now defaults to no authentication for all documentation sites."><i class="ph ph-file-text"></i> Authentication Default Change</a>
+        <a href="/guides/authentication-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase - a secure, scalable authentication platform."><i class="ph ph-check-circle" style="color: #059669;"></i> Authentication Guide</a>
+        <a href="/guides/claude-workflow-guide.html" class="nav-item" data-tooltip="This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it..."><i class="ph ph-pencil-simple" style="color: #d97706;"></i> Claude Workflow Guide</a>
+        <a href="/guides/documentation-standards.html" class="nav-item" data-tooltip="This document defines the documentation standards and conventions for the @knowcode/doc-builder project."><i class="ph ph-pencil-simple" style="color: #d97706;"></i> Documentation Standards</a>
+        <a href="/guides/html-embedding-guide.html" class="nav-item" data-tooltip="Starting from version 1.9.2, doc-builder treats HTML files ( and ) as attachments that are automatically copied to your output directory during the..."><i class="ph ph-check-circle" style="color: #059669;"></i> Html Embedding Guide</a>
+        <a href="/guides/image-modal-guide.html" class="nav-item" data-tooltip="When users click on any image in your generated documentation, it opens in a professional modal overlay with: Full-screen viewing experience Smooth..."><i class="ph ph-check-circle" style="color: #059669;"></i> Image Modal Guide</a>
+        <a href="/guides/phosphor-icons-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder automatically converts Unicode emojis in your markdown files to beautiful Phosphor icons in the generated HTML."><i class="ph ph-pencil-simple" style="color: #d97706;"></i> Phosphor Icons Guide</a>
+        <a href="/guides/private-directory-authentication.html" class="nav-item" data-tooltip="The @knowcode/doc-builder provides flexible authentication options to protect your documentation."><i class="ph ph-check-circle" style="color: #059669;"></i> Private Directory Authentication</a>
+        <a href="/guides/private-directory-authentication-troubleshooting.html" class="nav-item" data-tooltip="Private Directory Authentication Troubleshooting."><i class="ph ph-check-circle" style="color: #059669;"></i> Private Directory Authentication Troubleshooting</a>
+        <a href="/guides/public-site-deployment.html" class="nav-item" data-tooltip="The @knowcode/doc-builder now supports deploying public documentation sites without authentication."><i class="ph ph-check-circle" style="color: #059669;"></i> Public Site Deployment</a>
+        <a href="/guides/search-engine-verification-guide.html" class="nav-item" data-tooltip="Search engine verification provides access to powerful webmaster tools:."><i class="ph ph-check-circle" style="color: #059669;"></i> Search Engine Verification Guide</a>
+        <a href="/guides/seo-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features to help your documentation rank better in search results and..."><i class="ph ph-check-circle" style="color: #059669;"></i> Seo Guide</a>
+        <a href="/guides/seo-optimization-guide.html" class="nav-item" data-tooltip="Comprehensive guide to optimizing documentation for search engines. Learn SEO best practices, use built-in features, and improve your rankings."><i class="ph ph-check-circle" style="color: #059669;"></i> Seo Optimization Guide</a>
+        <a href="/guides/troubleshooting-guide.html" class="nav-item" data-tooltip="This guide helps you resolve common issues when using @knowcode/doc-builder."><i class="ph ph-check-circle" style="color: #059669;"></i> Troubleshooting Guide</a>
+        <a href="/guides/windows-setup-guide.html" class="nav-item" data-tooltip="This guide helps Windows users set up the complete AI-powered documentation workflow using Claude Code, @knowcode/doc-builder, and Vercel."><i class="ph ph-check-circle" style="color: #059669;"></i> Windows Setup Guide</a></div></div>
       <div class="nav-section private-nav" data-level="1">
         <a class="nav-title collapsible" href="#" data-target="nav-private-1" >
-          <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Private
+          <i class="ph ph-caret-right collapse-icon"></i><i class="ph ph-lock"></i> Private
         </a>
         <div class="nav-content collapsed" id="nav-private-1">
-        <a href="/private/cache-control-anti-pattern.html" class="nav-item" data-tooltip="Cache Control Anti-Pattern: Why Aggressive Cache-Busting is Bad for Documentation Sites."><i class="fas fa-file-alt"></i> Cache Control Anti Pattern</a>
-        <a href="/private/next-steps-walkthrough.html" class="nav-item" data-tooltip="Now that we&#039;ve implemented Supabase authentication, let&#039;s walk through testing the implementation and preparing for deployment."><i class="fas fa-file-alt"></i> Next Steps Walkthrough</a>
-        <a href="/private/supabase-auth-implementation-completed.html" class="nav-item" data-tooltip="This document records the successful implementation of Supabase authentication in @knowcode/doc-builder v1.7.5+."><i class="fas fa-file-alt"></i> Supabase Auth Implementation Completed</a>
-        <a href="/private/supabase-auth-implementation-plan.html" class="nav-item" data-tooltip="Supabase Auth Implementation Plan for @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Supabase Auth Implementation Plan</a>
-        <a href="/private/supabase-auth-integration-plan.html" class="nav-item" data-tooltip="Supabase Authentication Integration Plan for @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Supabase Auth Integration Plan</a>
-        <a href="/private/supabase-auth-setup-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase."><i class="fas fa-file-alt"></i> Supabase Auth Setup Guide</a>
-        <a href="/private/test-private-doc.html" class="nav-item" data-tooltip="Test Private Document."><i class="fas fa-file-alt"></i> Test Private Doc</a>
-        <a href="/private/user-management-tooling.html" class="nav-item" data-tooltip="The user management system is a set of tools designed to manage user access to Supabase-authenticated documentation sites built with."><i class="fas fa-file-alt"></i> User Management Tooling</a></div></div>
+        <a href="/private/cache-control-anti-pattern.html" class="nav-item" data-tooltip="Cache Control Anti-Pattern: Why Aggressive Cache-Busting is Bad for Documentation Sites."><i class="ph ph-check-circle" style="color: #059669;"></i> Cache Control Anti Pattern</a>
+        <a href="/private/next-steps-walkthrough.html" class="nav-item" data-tooltip="Now that we&#039;ve implemented Supabase authentication, let&#039;s walk through testing the implementation and preparing for deployment."><i class="ph ph-check-circle" style="color: #059669;"></i> Next Steps Walkthrough</a>
+        <a href="/private/supabase-auth-implementation-completed.html" class="nav-item" data-tooltip="This document records the successful implementation of Supabase authentication in @knowcode/doc-builder v1.7.5+."><i class="ph ph-check-circle" style="color: #059669;"></i> Supabase Auth Implementation Completed</a>
+        <a href="/private/supabase-auth-implementation-plan.html" class="nav-item" data-tooltip="Supabase Auth Implementation Plan for @knowcode/doc-builder."><i class="ph ph-check-circle" style="color: #059669;"></i> Supabase Auth Implementation Plan</a>
+        <a href="/private/supabase-auth-integration-plan.html" class="nav-item" data-tooltip="Supabase Authentication Integration Plan for @knowcode/doc-builder."><i class="ph ph-check-circle" style="color: #059669;"></i> Supabase Auth Integration Plan</a>
+        <a href="/private/supabase-auth-setup-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase."><i class="ph ph-check-circle" style="color: #059669;"></i> Supabase Auth Setup Guide</a>
+        <a href="/private/test-private-doc.html" class="nav-item" data-tooltip="Test Private Document."><i class="ph ph-file-text"></i> Test Private Doc</a>
+        <a href="/private/user-management-tooling.html" class="nav-item" data-tooltip="The user management system is a set of tools designed to manage user access to Supabase-authenticated documentation sites built with."><i class="ph ph-check-circle" style="color: #059669;"></i> User Management Tooling</a></div></div>
       <div class="nav-section private-nav" data-level="2">
         <a class="nav-title collapsible" href="/private/launch/README.html" data-target="nav-private-launch-2" >
-          <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Launch
+          <i class="ph ph-caret-right collapse-icon"></i><i class="ph ph-rocket-launch"></i> Launch
         </a>
         <div class="nav-content collapsed" id="nav-private-launch-2">
-        <a href="/private/launch/README.html" class="nav-item" data-tooltip="This directory contains all documentation related to the commercial launch of @knowcode/doc-builder, including go-to-market strategy, platform..."><i class="fas fa-file-alt"></i> Launch Overview</a>
-        <a href="/private/launch/auth-cleanup-summary.html" class="nav-item" data-tooltip="All references to the old client-side authentication system have been removed from @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Auth Cleanup Summary</a>
-        <a href="/private/launch/bubble-plugin-specification.html" class="nav-item" data-tooltip="This document outlines the technical specification for creating a Bubble.io plugin that integrates @knowcode/doc-builder, enabling Bubble developers..."><i class="fas fa-file-alt"></i> Bubble Plugin Specification</a>
-        <a href="/private/launch/go-to-market-strategy.html" class="nav-item" data-tooltip="Go-to-Market Strategy &amp; Product Launch Plan."><i class="fas fa-file-alt"></i> Go To Market Strategy</a>
-        <a href="/private/launch/launch-announcements.html" class="nav-item" data-tooltip="This document contains ready-to-use announcement templates for launching @knowcode/doc-builder across various platforms and channels."><i class="fas fa-file-alt"></i> Launch Announcements</a>
-        <a href="/private/launch/vercel-deployment-auth-setup.html" class="nav-item" data-tooltip="Vercel Deployment Authentication Setup Guide."><i class="fas fa-file-alt"></i> Vercel Deployment Auth Setup</a></div></div>
+        <a href="/private/launch/README.html" class="nav-item" data-tooltip="This directory contains all documentation related to the commercial launch of @knowcode/doc-builder, including go-to-market strategy, platform..."><i class="ph ph-check-circle" style="color: #059669;"></i> Launch Overview</a>
+        <a href="/private/launch/auth-cleanup-summary.html" class="nav-item" data-tooltip="All references to the old client-side authentication system have been removed from @knowcode/doc-builder."><i class="ph ph-check-circle" style="color: #059669;"></i> Auth Cleanup Summary</a>
+        <a href="/private/launch/bubble-plugin-specification.html" class="nav-item" data-tooltip="This document outlines the technical specification for creating a Bubble.io plugin that integrates @knowcode/doc-builder, enabling Bubble developers..."><i class="ph ph-x-circle" style="color: #dc2626;"></i> Bubble Plugin Specification</a>
+        <a href="/private/launch/go-to-market-strategy.html" class="nav-item" data-tooltip="Go-to-Market Strategy &amp; Product Launch Plan."><i class="ph ph-pencil-simple" style="color: #d97706;"></i> Go To Market Strategy</a>
+        <a href="/private/launch/launch-announcements.html" class="nav-item" data-tooltip="This document contains ready-to-use announcement templates for launching @knowcode/doc-builder across various platforms and channels."><i class="ph ph-check-circle" style="color: #059669;"></i> Launch Announcements</a>
+        <a href="/private/launch/vercel-deployment-auth-setup.html" class="nav-item" data-tooltip="Vercel Deployment Authentication Setup Guide."><i class="ph ph-check-circle" style="color: #059669;"></i> Vercel Deployment Auth Setup</a></div></div>
       <div class="nav-section" data-level="1">
         <a class="nav-title collapsible" href="#" data-target="nav-prompts-1" >
-          <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Prompts
+          <i class="ph ph-caret-right collapse-icon"></i><i class="ph ph-chat-circle-dots"></i> Prompts
         </a>
         <div class="nav-content collapsed" id="nav-prompts-1">
-        <a href="/prompts/markdown-document-standards.html" class="nav-item" data-tooltip="Detailed introduction to the topic..."><i class="fas fa-file-alt"></i> Markdown Document Standards</a></div></div>
+        <a href="/prompts/markdown-document-standards.html" class="nav-item" data-tooltip="Detailed introduction to the topic..."><i class="ph ph-pencil-simple" style="color: #d97706;"></i> Markdown Document Standards</a></div></div>
             </nav>
             <div class="resize-handle"></div>
         </aside>

package/lib/config.js

@@ -1,12 +1,16 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const semver = require('semver');
 const sharedAuth = require('./shared-auth-config');
 
 /**
  * Default configuration
  */
 const defaultConfig = {
+  // Configuration version - updated when new config options are added
+  configVersion: require('../package.json').version,
+  
   // Source and output directories
   docsDir: 'docs',
   outputDir: 'html',
@@ -32,7 +36,9 @@ const defaultConfig = {
     normalizeTitle: true,      // Auto-normalize all-caps titles to title case
     showPdfDownload: true,     // Show PDF download icon in header
     menuDefaultOpen: true,     // Menu/sidebar open by default
-    attachments: true          // Copy attachments (Excel, PDF, etc.) to output
+    attachments: true,         // Copy attachments (Excel, PDF, etc.) to output
+    dynamicNavIcons: true,     // Use status-based icons in navigation
+    subtleColors: true         // Apply subtle colors to status icons
   },
   
   // Authentication - Supabase only (basic auth removed for security)
@@ -212,6 +218,112 @@ const notionInspiredPreset = {
   }
 };
 
+/**
+ * Check if config migration is needed
+ * @param {object} userConfig - Current user configuration
+ * @param {string} packageVersion - Current package version
+ * @returns {boolean} - Whether migration is needed
+ */
+function needsMigration(userConfig, packageVersion) {
+  // If no configVersion in user config, it needs migration
+  if (!userConfig.configVersion) {
+    return true;
+  }
+  
+  try {
+    // Use semver to compare versions
+    return semver.lt(userConfig.configVersion, packageVersion);
+  } catch (error) {
+    console.warn(chalk.yellow(`Warning: Invalid version format in config: ${userConfig.configVersion}`));
+    return true; // Migrate on version parse errors
+  }
+}
+
+/**
+ * Deep merge objects, preserving user customizations
+ * @param {object} target - Target object (defaults)
+ * @param {object} source - Source object (user config)
+ * @returns {object} - Merged object
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+  
+  for (const key in source) {
+    if (source.hasOwnProperty(key)) {
+      if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+        // Recursively merge objects
+        result[key] = deepMerge(target[key] || {}, source[key]);
+      } else {
+        // Use source value (user customization takes precedence)
+        result[key] = source[key];
+      }
+    }
+  }
+  
+  return result;
+}
+
+/**
+ * Migrate user configuration to current version
+ * @param {object} userConfig - Current user configuration
+ * @param {string} targetVersion - Target package version
+ * @returns {object} - Migrated configuration
+ */
+function migrateConfig(userConfig, targetVersion) {
+  console.log(chalk.blue(`🔄 Migrating config from ${userConfig.configVersion || 'unknown'} to ${targetVersion}`));
+  
+  // Start with current defaults
+  let migratedConfig = { ...defaultConfig };
+  
+  // Deep merge user customizations
+  migratedConfig = deepMerge(migratedConfig, userConfig);
+  
+  // Update the config version
+  migratedConfig.configVersion = targetVersion;
+  
+  // Log new features added
+  const newFeatures = [];
+  if (!userConfig.features?.dynamicNavIcons) {
+    newFeatures.push('Dynamic navigation icons');
+  }
+  if (!userConfig.features?.subtleColors) {
+    newFeatures.push('Subtle status colors');
+  }
+  if (!userConfig.features?.phosphorWeight) {
+    newFeatures.push('Phosphor icon weight options');
+  }
+  if (!userConfig.features?.phosphorSize) {
+    newFeatures.push('Phosphor icon sizing');
+  }
+  
+  if (newFeatures.length > 0) {
+    console.log(chalk.green(`✨ Added new features: ${newFeatures.join(', ')}`));
+  }
+  
+  return migratedConfig;
+}
+
+/**
+ * Save configuration to file
+ * @param {string} configPath - Path to config file
+ * @param {object} config - Configuration object to save
+ */
+async function saveConfig(configPath, config) {
+  // Create backup of existing config
+  if (fs.existsSync(configPath)) {
+    const backupPath = `${configPath}.backup.${Date.now()}`;
+    await fs.copy(configPath, backupPath);
+    console.log(chalk.gray(`💾 Backed up existing config to ${path.basename(backupPath)}`));
+  }
+  
+  // Format config as module.exports
+  const configContent = `module.exports = ${JSON.stringify(config, null, 2)};
+`;
+  
+  await fs.writeFile(configPath, configContent);
+  console.log(chalk.green(`✅ Updated config file: ${path.basename(configPath)}`));
+}
+
 /**
  * Load configuration
  */
@@ -228,7 +340,15 @@ async function loadConfig(configPath, options = {}) {
   if (fs.existsSync(customConfigPath)) {
     try {
       const customConfig = require(customConfigPath);
-      config = { ...config, ...customConfig };
+      const packageJson = require('../package.json');
+      
+      // Check if migration is needed
+      if (needsMigration(customConfig, packageJson.version)) {
+        config = migrateConfig(customConfig, packageJson.version);
+        await saveConfig(customConfigPath, config);
+      } else {
+        config = { ...config, ...customConfig };
+      }
       
       // Handle alternative config formats
       if (customConfig.site) {
@@ -356,5 +476,8 @@ module.exports = {
   defaultConfig,
   notionInspiredPreset,
   loadConfig,
-  createDefaultConfig
+  createDefaultConfig,
+  needsMigration,
+  migrateConfig,
+  saveConfig
 };

package/lib/core-builder.js

@@ -64,6 +64,113 @@ function escapeHtml(text) {
   return text.replace(/[&<>"']/g, m => map[m]);
 }
 
+// Detect document status from content and front matter
+function detectDocumentStatus(content, frontMatter = {}) {
+  // Check front matter first
+  if (frontMatter.status) {
+    return frontMatter.status.toLowerCase();
+  }
+  
+  // Check content for status indicators (case insensitive)
+  const contentLower = content.toLowerCase();
+  
+  const statusIndicators = {
+    'draft': ['🚧', 'draft', 'work in progress', 'wip', 'under construction'],
+    'complete': ['✅', 'completed', 'verified', 'ready', '✓'],
+    'warning': ['⚠️', '❗', 'warning', 'caution', 'attention'],
+    'error': ['❌', '🚨', 'error', 'failed', 'broken'],
+    'planning': ['📋', 'planning', 'todo', 'roadmap', 'brainstorm'],
+    'deprecated': ['🗑️', 'deprecated', 'obsolete', 'archived']
+  };
+  
+  for (const [status, indicators] of Object.entries(statusIndicators)) {
+    for (const indicator of indicators) {
+      if (contentLower.includes(indicator)) {
+        return status;
+      }
+    }
+  }
+  
+  // Special cases based on file name patterns
+  if (frontMatter.title || content.includes('# ')) {
+    const title = (frontMatter.title || content.match(/^#\s+(.+)$/m)?.[1] || '').toLowerCase();
+    
+    if (title.includes('readme') || title.includes('overview')) return 'readme';
+    if (title.includes('guide') || title.includes('tutorial')) return 'guide';
+    if (title.includes('troubleshoot') || title.includes('problem')) return 'troubleshoot';
+    if (title.includes('api') || title.includes('reference')) return 'reference';
+  }
+  
+  return 'default';
+}
+
+// Get icon for document status with subtle styling
+function getIconForStatus(status, isFolder = false, config = {}) {
+  if (isFolder) {
+    return '<i class="ph ph-folder"></i>';
+  }
+  
+  // Check if dynamic icons are enabled (default: true)
+  const dynamicIcons = config.features?.dynamicNavIcons !== false;
+  const subtleColors = config.features?.subtleColors !== false && dynamicIcons;
+  
+  if (!dynamicIcons) {
+    return '<i class="ph ph-file-text"></i>';
+  }
+  
+  const statusIcons = {
+    'draft': {
+      icon: 'ph ph-pencil-simple',
+      color: subtleColors ? '#d97706' : undefined  // More subtle amber
+    },
+    'complete': {
+      icon: 'ph ph-check-circle',
+      color: subtleColors ? '#059669' : undefined  // More subtle emerald
+    },
+    'warning': {
+      icon: 'ph ph-warning',
+      color: subtleColors ? '#ea580c' : undefined  // More subtle orange
+    },
+    'error': {
+      icon: 'ph ph-x-circle',
+      color: subtleColors ? '#dc2626' : undefined  // More subtle red
+    },
+    'planning': {
+      icon: 'ph ph-list-checks',
+      color: subtleColors ? '#7c3aed' : undefined  // More subtle violet
+    },
+    'deprecated': {
+      icon: 'ph ph-archive',
+      color: subtleColors ? '#6b7280' : undefined  // Subtle gray
+    },
+    'guide': {
+      icon: 'ph ph-book-open',
+      color: subtleColors ? '#2563eb' : undefined  // More subtle blue
+    },
+    'readme': {
+      icon: 'ph ph-house',
+      color: subtleColors ? '#059669' : undefined  // More subtle emerald
+    },
+    'troubleshoot': {
+      icon: 'ph ph-wrench',
+      color: subtleColors ? '#dc2626' : undefined  // More subtle red
+    },
+    'reference': {
+      icon: 'ph ph-book',
+      color: subtleColors ? '#7c3aed' : undefined  // More subtle violet
+    },
+    'default': {
+      icon: 'ph ph-file-text',
+      color: undefined
+    }
+  };
+  
+  const statusConfig = statusIcons[status] || statusIcons.default;
+  const colorStyle = statusConfig.color ? ` style="color: ${statusConfig.color};"` : '';
+  
+  return `<i class="${statusConfig.icon}"${colorStyle}></i>`;
+}
+
 // Extract summary from markdown content for tooltips
 function extractSummary(content, maxLength = 150) {
   // Remove front matter
@@ -553,31 +660,35 @@ function buildNavigationStructure(files, currentFile, config = {}) {
   // Helper function to render a section
   const renderSection = (folderName, folderData, level = 0, parentPath = '') => {
     const icons = {
-      'root': 'fas fa-home',
-      'product-roadmap': 'fas fa-road',
-      'product-requirements': 'fas fa-clipboard-list',
-      'architecture': 'fas fa-sitemap',
-      'system-analysis': 'fas fa-chart-line',
-      'system': 'fas fa-cogs',
-      'bubble': 'fas fa-circle',
-      'quickbase': 'fas fa-database',
-      'activecampaign': 'fas fa-envelope',
-      'doc-signer': 'fas fa-signature',
-      'api-deprecated': 'fas fa-archive',
-      'postman': 'fas fa-flask',
-      'mcp': 'fas fa-puzzle-piece',
-      'team': 'fas fa-users',
-      'thought-leadership': 'fas fa-lightbulb',
-      'middleware': 'fas fa-layer-group',
-      'paths': 'fas fa-route',
-      'testing': 'fas fa-vial',
-      'api': 'fas fa-plug',
-      'documentation-tool': 'fas fa-tools'
+      'root': 'ph ph-house',
+      'product-roadmap': 'ph ph-road-horizon',
+      'product-requirements': 'ph ph-list-checks',
+      'architecture': 'ph ph-tree-structure',
+      'system-analysis': 'ph ph-chart-line-up',
+      'system': 'ph ph-gear-six',
+      'bubble': 'ph ph-circle',
+      'quickbase': 'ph ph-database',
+      'activecampaign': 'ph ph-envelope',
+      'doc-signer': 'ph ph-signature',
+      'api-deprecated': 'ph ph-archive',
+      'postman': 'ph ph-flask',
+      'mcp': 'ph ph-puzzle-piece',
+      'team': 'ph ph-users',
+      'thought-leadership': 'ph ph-lightbulb',
+      'middleware': 'ph ph-stack',
+      'paths': 'ph ph-path',
+      'testing': 'ph ph-test-tube',
+      'api': 'ph ph-plug',
+      'documentation-tool': 'ph ph-wrench',
+      'guides': 'ph ph-book',
+      'private': 'ph ph-lock',
+      'launch': 'ph ph-rocket-launch',
+      'prompts': 'ph ph-chat-circle-dots'
     };
     
     const displayName = folderName === 'root' ? 'Documentation' : 
                        folderName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
-    const icon = icons[folderName] || 'fas fa-folder';
+    const icon = icons[folderName] || 'ph ph-folder';
     
     if (!folderData.files.length && !Object.keys(folderData.folders).length) {
       return '';
@@ -587,7 +698,7 @@ function buildNavigationStructure(files, currentFile, config = {}) {
     const pathParts = parentPath ? [parentPath, folderName].join('-') : folderName;
     const sectionId = `nav-${pathParts}-${level}`;
     const isCollapsible = level > 0 || folderName !== 'root';
-    const collapseIcon = isCollapsible ? '<i class="fas fa-chevron-right collapse-icon"></i>' : '';
+    const collapseIcon = isCollapsible ? '<i class="ph ph-caret-right collapse-icon"></i>' : '';
     
     // Check if this folder has a README.md file to link to
     const readmeFile = folderData.files.find(f => f.displayName === 'README');
@@ -634,9 +745,10 @@ function buildNavigationStructure(files, currentFile, config = {}) {
       
       const linkPath = '/' + file.urlPath;
       const tooltip = file.summary ? ` data-tooltip="${escapeHtml(file.summary)}"` : '';
+      const icon = getIconForStatus(file.status || 'default', false, config);
       
       html += `
-        <a href="${linkPath}" class="nav-item${isActive}"${tooltip}><i class="fas fa-file-alt"></i> ${title}</a>`;
+        <a href="${linkPath}" class="nav-item${isActive}"${tooltip}>${icon} ${title}</a>`;
     });
     
     html += `</div></div>`;
@@ -698,8 +810,9 @@ function buildNavigationStructure(files, currentFile, config = {}) {
             }
             const linkPath = '/' + file.urlPath;
             const tooltip = file.summary ? ` data-tooltip="${escapeHtml(file.summary)}"` : '';
+            const icon = getIconForStatus(file.status || 'default', false, config);
             additionalFiles += `
-        <a href="${linkPath}" class="nav-item${isActive}"${tooltip}><i class="fas fa-file-alt"></i> ${title}</a>`;
+        <a href="${linkPath}" class="nav-item${isActive}"${tooltip}>${icon} ${title}</a>`;
           });
           
           // Reconstruct with additional files inserted
@@ -769,9 +882,12 @@ async function getAllMarkdownFiles(dir, baseDir = dir) {
         .replace(/[-_]/g, ' ')
         .replace(/\b\w/g, l => l.toUpperCase());
       
-      // Read file to extract summary
-      const content = await fs.readFile(fullPath, 'utf-8');
-      const summary = extractSummary(content);
+      // Read file to extract summary and status
+      const rawContent = await fs.readFile(fullPath, 'utf-8');
+      const { data: frontMatter, content } = matter(rawContent);
+      const summary = frontMatter.description || extractSummary(content);
+      const status = detectDocumentStatus(content, frontMatter);
+      
       
       // Check if this file is in the private directory
       const isPrivate = relativePath.split(path.sep)[0] === 'private' || 
@@ -784,7 +900,10 @@ async function getAllMarkdownFiles(dir, baseDir = dir) {
         urlPath,
         displayName,
         summary,
-        isPrivate
+        isPrivate,
+        status,
+        frontMatter,
+        content
       });
     }
   }

package/lib/emoji-mapper.js

@@ -15,6 +15,7 @@ const emojiToPhosphor = {
   '⛔': '<i class="ph ph-prohibit" aria-label="prohibited"></i>',
   '🚫': '<i class="ph ph-prohibit-inset" aria-label="not allowed"></i>',
   '🚨': '<i class="ph ph-siren" aria-label="alert"></i>',
+  '🚧': '<i class="ph ph-barricade" aria-label="under construction"></i>',
   '🆘': '<i class="ph ph-first-aid" aria-label="emergency"></i>',
   
   // Development & Tech
@@ -80,6 +81,7 @@ const emojiToPhosphor = {
   '🧭': '<i class="ph ph-compass" aria-label="navigation"></i>',
   '🗺️': '<i class="ph ph-map-trifold" aria-label="map"></i>',
   '🌐': '<i class="ph ph-globe" aria-label="global"></i>',
+  '🌍': '<i class="ph ph-globe-hemisphere-west" aria-label="world"></i>',
   
   // Communication
   '📧': '<i class="ph ph-envelope" aria-label="email"></i>',
@@ -249,6 +251,20 @@ const emojiToPhosphor = {
   '📑': '<i class="ph ph-file-text" aria-label="document"></i>',
   '💀': '<i class="ph ph-skull" aria-label="skull"></i>',
   '🔤': '<i class="ph ph-textbox" aria-label="letters"></i>',
+  '🧱': '<i class="ph ph-wall" aria-label="brick"></i>',
+  '🖼️': '<i class="ph ph-image" aria-label="picture"></i>',
+  '🎂': '<i class="ph ph-cake" aria-label="birthday"></i>',
+  '↩️': '<i class="ph ph-arrow-u-left" aria-label="return"></i>',
+  '📜': '<i class="ph ph-scroll" aria-label="scroll"></i>',
+  '🕰️': '<i class="ph ph-clock" aria-label="clock"></i>',
+  '🧮': '<i class="ph ph-calculator" aria-label="calculator"></i>',
+  '🎫': '<i class="ph ph-ticket" aria-label="ticket"></i>',
+  '🌿': '<i class="ph ph-leaf" aria-label="leaf"></i>',
+  '🥊': '<i class="ph ph-boxing-glove" aria-label="boxing"></i>',
+  '🎛️': '<i class="ph ph-faders" aria-label="controls"></i>',
+  '🗣️': '<i class="ph ph-megaphone-simple" aria-label="speaking"></i>',
+  '💝': '<i class="ph ph-gift" aria-label="gift with bow"></i>',
+  '🐌': '<i class="ph ph-spiral" aria-label="snail"></i>',
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.9.5",
+  "version": "1.9.7",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {
@@ -8,9 +8,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/setup.js || true",
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "publish:npm": "./publish.sh",
-    "release": "./publish.sh"
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [
     "documentation",
@@ -39,7 +37,8 @@
     "gray-matter": "^4.0.3",
     "marked": "^15.0.12",
     "ora": "5.4.1",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "semver": "^7.7.2"
   },
   "engines": {
     "node": ">=14.0.0"