botdocs 0.4.0 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # Botdocs
 
+[![Read about the commits](https://img.shields.io/badge/commits-code%20blog-1a1a1a?style=flat-square)](https://wwel.sh/digest.html?repo=botdocs)
+
 [![npm version](https://img.shields.io/npm/v/botdocs.svg)](https://www.npmjs.com/package/botdocs)
 
 Convert markdown documentation into beautiful static sites with AI-powered semantic search — no backend required.
@@ -12,6 +14,8 @@ Convert markdown documentation into beautiful static sites with AI-powered seman
 - **Deep Links** - Search results link directly to sections
 - **No Backend** - Everything runs in the browser
 - **Fast** - Syntax highlighting with Shiki
+- **Live Preview** - `--watch` rebuilds on save and serves the site locally
+- **SEO** - Optional Open Graph/Twitter tags and `sitemap.xml` via `baseUrl`
 
 ## Installation
 
@@ -44,6 +48,9 @@ botdocs ./docs -c ./my-config.json
 
 # Combine multiple options
 botdocs ./docs -o ./public -t slate -v
+
+# Live preview: rebuild on save + local server
+botdocs ./docs --watch
 ```
 
 ### CLI Options
@@ -55,6 +62,8 @@ botdocs ./docs -o ./public -t slate -v
 | `--config <file>` | `-c` | Path to config file | `botdocs.config.json` |
 | `--theme <theme>` | `-t` | Theme to use | `classic` |
 | `--verbose` | `-v` | Enable verbose logging | `false` |
+| `--watch` | `-w` | Rebuild on changes and serve the site for live preview | `false` |
+| `--port <number>` | `-p` | Port for the preview server (with `--watch`) | `3000` |
 
 ### Available Themes
 
@@ -73,12 +82,16 @@ Create `botdocs.config.json` in your docs directory:
   "title": "My Documentation",
   "description": "Project docs",
   "theme": "classic",
+  "customCss": "custom.css",
   "attribution": true,
+  "baseUrl": "https://example.com/docs/",
   "chat": { "enabled": true },
   "build": {
     "chunkSize": 500,
     "chunkOverlap": 50,
-    "topK": 3
+    "minChunkSize": 15,
+    "topK": 3,
+    "minScore": 0.75
   }
 }
 ```
@@ -90,12 +103,16 @@ Create `botdocs.config.json` in your docs directory:
 | `title` | string | `"Documentation"` | Site title |
 | `description` | string | `"Project documentation"` | Site description |
 | `theme` | string | `"classic"` | Theme to use (classic, material, minimal, slate, modern) |
+| `customCss` | string | none | Path to a CSS file, resolved relative to the config file's directory. Appended after theme CSS in `bundle.css`, so same-specificity selectors override the theme without `!important` |
 | `attribution` | boolean | `true` | Show "Built with Botdocs" footer link |
+| `baseUrl` | string | none | Canonical URL where the site is hosted. When set, pages get `rel=canonical` and Open Graph/Twitter card tags, and a `sitemap.xml` is generated |
 | `chat.enabled` | boolean | `true` | Enable AI chatbot |
 | `chat.welcomeMessage` | string | `"Ask me anything about the docs!"` | Chatbot welcome message |
 | `build.chunkSize` | number | `500` | Text chunk size for embeddings |
 | `build.chunkOverlap` | number | `50` | Overlap between chunks |
+| `build.minChunkSize` | number | `15` | Chunks smaller than this (estimated tokens) get folded into a neighboring chunk instead of becoming a standalone, low-signal search result |
 | `build.topK` | number | `3` | Number of results to return |
+| `build.minScore` | number | `0.75` | Minimum vector similarity (0-1) a result must reach to be returned at all, regardless of `topK` — filters out weak/off-topic matches instead of always padding results. The e5 embedding model has a fairly high similarity floor even for unrelated text, so this needs to sit well above 0.5 to actually gate anything |
 
 ## Front Matter
 
@@ -113,11 +130,12 @@ description: Quick start guide
 1. **Build**: Parses markdown → generates embeddings → creates `vector-db.json`
 2. **Runtime**: User query → embed → search vector DB → return relevant chunks
 3. **No LLM**: Pure semantic search, not AI text generation
+4. **Consent**: On first use, visitors are asked before the embedding model downloads to their browser, with a disclosure of what runs locally
 
 ## Architecture
 
 - **Embedding Model**: `e5-small-v2` (384-dim vectors, 2.2x faster than all-MiniLM-L6-v2)
-- **Search**: Cosine similarity, client-side only
+- **Search**: Hybrid — vector cosine similarity fused with BM25 keyword scoring (Reciprocal Rank Fusion), gated by a minimum similarity threshold, client-side only
 - **Browser Bundle**: ~825KB (includes Transformers.js)
 - **Deployment**: Fully static, works on any host
 

package/dist/src/builder/chunker.d.ts

@@ -7,6 +7,13 @@ export interface TextChunk {
 export interface ChunkerOptions {
     maxChunkSize: number;
     chunkOverlap: number;
+    /**
+     * Chunks smaller than this (in estimated tokens) are folded into a
+     * neighboring chunk instead of being kept as standalone, low-information
+     * entries in the vector DB (e.g. a heading followed by a single short
+     * line). Set to 0 to disable merging.
+     */
+    minChunkSize: number;
 }
 /**
  * Text chunker that splits documents by headings while respecting token limits
@@ -18,6 +25,17 @@ export declare class Chunker {
      * Chunk a document into semantically meaningful pieces
      */
     chunkDocument(doc: ProcessedDocument, fileHash?: string): TextChunk[];
+    /**
+     * Fold chunks smaller than minChunkSize into a neighbor so a heading with
+     * little or no body content doesn't become its own low-signal retrieval
+     * candidate.
+     */
+    private mergeSmallChunks;
+    /**
+     * True for a line that is entirely markdown badges/images/links with no
+     * other prose (a bare link line, a shields.io badge, or a chain of both).
+     */
+    private isBoilerplateLine;
     /**
      * Create a chunk with metadata
      */

package/dist/src/builder/chunker.js

@@ -1,3 +1,6 @@
+// Matches a markdown image, a badge (image wrapped in a link), or a plain
+// link, e.g. `![alt](url)`, `[![alt](url)](url)`, `[text](url)`.
+const LINK_OR_IMAGE = /\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)|!?\[[^\]]*\]\([^)]*\)/g;
 /**
  * Text chunker that splits documents by headings while respecting token limits
  */
@@ -7,6 +10,7 @@ export class Chunker {
         this.options = {
             maxChunkSize: options.maxChunkSize || 500,
             chunkOverlap: options.chunkOverlap || 50,
+            minChunkSize: options.minChunkSize ?? 15,
         };
     }
     /**
@@ -54,6 +58,13 @@ export class Chunker {
                 currentChunk = [line];
             }
             else {
+                // Badges and bare reference links carry no retrievable prose, but
+                // their markup is character-heavy enough to dodge minChunkSize and
+                // their repeated project-name alt-text then dominates BM25 matches
+                // on any query mentioning that name. Drop them before they're ever
+                // embedded or indexed rather than filtering by size after the fact.
+                if (this.isBoilerplateLine(line))
+                    continue;
                 currentChunk.push(line);
                 // Check if chunk is getting too large
                 const tokenCount = this.estimateTokens(currentChunk.join('\n'));
@@ -71,7 +82,57 @@ export class Chunker {
         if (currentChunk.length > 0) {
             chunks.push(this.createChunk(currentChunk.join('\n'), doc, currentHeading, fileHash));
         }
-        return chunks.filter((chunk) => chunk.text.trim().length > 0);
+        const nonEmptyChunks = chunks.filter((chunk) => chunk.text.trim().length > 0);
+        return this.mergeSmallChunks(nonEmptyChunks);
+    }
+    /**
+     * Fold chunks smaller than minChunkSize into a neighbor so a heading with
+     * little or no body content doesn't become its own low-signal retrieval
+     * candidate.
+     */
+    mergeSmallChunks(chunks) {
+        const minTokens = this.options.minChunkSize;
+        if (minTokens <= 0 || chunks.length <= 1)
+            return chunks;
+        const merged = [];
+        for (const chunk of chunks) {
+            const prev = merged[merged.length - 1];
+            if (prev && this.estimateTokens(prev.text) < minTokens) {
+                // Absorb forward: the small chunk becomes the lead-in for the next
+                // section, which takes over as the chunk's heading/metadata.
+                merged[merged.length - 1] = {
+                    text: `${prev.text}\n\n${chunk.text}`,
+                    metadata: chunk.metadata,
+                };
+            }
+            else {
+                merged.push(chunk);
+            }
+        }
+        // A trailing chunk with nothing after it to absorb into gets folded
+        // backward instead, keeping the earlier (more substantial) heading.
+        if (merged.length > 1) {
+            const last = merged[merged.length - 1];
+            if (this.estimateTokens(last.text) < minTokens) {
+                const prev = merged[merged.length - 2];
+                merged[merged.length - 2] = {
+                    text: `${prev.text}\n\n${last.text}`,
+                    metadata: prev.metadata,
+                };
+                merged.pop();
+            }
+        }
+        return merged;
+    }
+    /**
+     * True for a line that is entirely markdown badges/images/links with no
+     * other prose (a bare link line, a shields.io badge, or a chain of both).
+     */
+    isBoilerplateLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return false;
+        return trimmed.replace(LINK_OR_IMAGE, '').trim().length === 0;
     }
     /**
      * Create a chunk with metadata

package/dist/src/builder/embedder.js

@@ -2,7 +2,7 @@ import { pipeline, env } from '@huggingface/transformers';
 // Disable local model loading - use Hugging Face
 env.allowLocalModels = false;
 export class Embedder {
-    model;
+    model = null;
     modelName;
     dimension;
     constructor(modelName = 'Xenova/e5-small-v2') {
@@ -24,6 +24,9 @@ export class Embedder {
         if (!this.model) {
             await this.initialize();
         }
+        if (!this.model) {
+            throw new Error('Failed to initialize embedding model');
+        }
         // Prepend "passage: " prefix for e5 models
         const prefixedText = `passage: ${text}`;
         // Generate embedding

package/dist/src/builder/index-size.d.ts

@@ -0,0 +1,3 @@
+export declare const INDEX_SIZE_WARN_BYTES: number;
+export declare function formatBytes(bytes: number): string;
+export declare function isIndexSizeWarning(bytes: number): boolean;

package/dist/src/builder/index-size.js

@@ -0,0 +1,16 @@
+export const INDEX_SIZE_WARN_BYTES = 2 * 1024 * 1024;
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let value = bytes;
+    let unit = -1;
+    do {
+        value /= 1024;
+        unit++;
+    } while (value >= 1024 && unit < units.length - 1);
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+export function isIndexSizeWarning(bytes) {
+    return bytes >= INDEX_SIZE_WARN_BYTES;
+}

package/dist/src/builder/index.js

@@ -1,11 +1,14 @@
 import { defaultConfig } from '../types/config.js';
 import { SiteGenerator } from './site-generator.js';
 import { VectorDBBuilder } from './vector-db-builder.js';
-import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, cpSync } from 'fs';
+import { formatBytes, isIndexSizeWarning } from './index-size.js';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, cpSync, statSync } from 'fs';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { INDEX_SIZE_WARN_BYTES } from './index-size.js';
+import { underSrc } from './paths.js';
 const execAsync = promisify(exec);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -58,8 +61,19 @@ export async function build(options) {
         const vectorDBBuilder = new VectorDBBuilder({
             chunkSize: config.build?.chunkSize,
             chunkOverlap: config.build?.chunkOverlap,
+            minChunkSize: config.build?.minChunkSize,
         });
         await vectorDBBuilder.build(documents, outputDir, verbose);
+        const dbPath = join(outputDir, 'vector-db.json');
+        if (existsSync(dbPath)) {
+            const { size } = statSync(dbPath);
+            console.log(`Search index: ${formatBytes(size)}`);
+            if (isIndexSizeWarning(size)) {
+                console.warn(`Warning: search index exceeds ${formatBytes(INDEX_SIZE_WARN_BYTES)} — ` +
+                    'it loads fully in the browser, so large indexes slow first paint. ' +
+                    'Consider fewer/smaller docs or raising build.minChunkSize.');
+            }
+        }
     }
     // Phase 3: Build client-side code with Vite
     console.log('Building client-side code...');
@@ -114,8 +128,7 @@ export async function build(options) {
     }
     // Phase 4: Copy styles
     console.log('Copying styles...');
-    // From dist/src/builder, go to project root, then to src/styles
-    const stylesDir = resolve(__dirname, '../../../src/styles');
+    const stylesDir = underSrc(__dirname, 'styles');
     const themesDir = join(stylesDir, 'themes');
     const outputCssDir = join(assetsDir, 'css');
     // Determine which theme to use

package/dist/src/builder/paths.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve a directory under the project's src/ tree regardless of whether
+ * this module is executing compiled (dist/src/...) or from source (src/...)
+ * via tsx.
+ */
+export declare function underSrc(moduleDir: string, name: string): string;

package/dist/src/builder/paths.js

@@ -0,0 +1,13 @@
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+/**
+ * Resolve a directory under the project's src/ tree regardless of whether
+ * this module is executing compiled (dist/src/...) or from source (src/...)
+ * via tsx.
+ */
+export function underSrc(moduleDir, name) {
+    const inSourceTree = resolve(moduleDir, '..', name);
+    if (existsSync(inSourceTree))
+        return inSourceTree;
+    return resolve(moduleDir, '..', '..', '..', 'src', name);
+}

package/dist/src/builder/site-generator.d.ts

@@ -1,5 +1,6 @@
 import { ProcessedDocument } from '../types/document.js';
 import { BotdocsConfig } from '../types/config.js';
+export declare function absoluteUrl(baseUrl: string, urlPath: string): string;
 export declare class SiteGenerator {
     private processor;
     private templateEngine;
@@ -9,6 +10,7 @@ export declare class SiteGenerator {
      * Generate the complete site
      */
     generate(inputDir: string, outputDir: string, config: BotdocsConfig): Promise<ProcessedDocument[]>;
+    private writeSitemap;
     /**
      * Build navigation structure from documents, grouping by top-level
      * folder so e.g. every doc under `path-of-python/` (its README plus

package/dist/src/builder/site-generator.js

@@ -1,13 +1,18 @@
 import { readFileSync, writeFileSync, readdirSync, mkdirSync, cpSync } from 'fs';
-import { join, dirname, resolve, basename } from 'path';
+import { join, dirname, basename } from 'path';
 import { MarkdownProcessor } from './markdown-processor.js';
 import { TemplateEngine } from './template-engine.js';
+import { underSrc } from './paths.js';
+import { rootPrefix, relativeUrl } from '../shared/site-root.js';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 function stripHtml(value) {
     return value.replace(/<[^>]*>/g, '');
 }
+export function absoluteUrl(baseUrl, urlPath) {
+    return `${baseUrl.replace(/\/+$/, '')}${urlPath.startsWith('/') ? urlPath : `/${urlPath}`}`;
+}
 export class SiteGenerator {
     processor;
     templateEngine;
@@ -46,9 +51,9 @@ export class SiteGenerator {
         // Generate navigation
         const navigation = this.buildNavigation(this.documents);
         const pageSequence = this.buildPageSequence(navigation);
-        // Load templates from source directory (not dist)
-        // From dist/src/builder, go to project root, then to src/templates
-        const templatesDir = resolve(__dirname, '../../../src/templates');
+        // Load templates from the project's src/templates, whether running
+        // compiled from dist/ or directly from src/ via tsx.
+        const templatesDir = underSrc(__dirname, 'templates');
         const layoutTemplate = readFileSync(join(templatesDir, 'layout.html'), 'utf-8');
         const docPageTemplate = readFileSync(join(templatesDir, 'doc-page.html'), 'utf-8');
         const indexTemplate = readFileSync(join(templatesDir, 'index.html'), 'utf-8');
@@ -57,8 +62,11 @@ export class SiteGenerator {
         for (let i = 0; i < this.documents.length; i++) {
             const doc = this.documents[i];
             const isIndex = doc.relativePath === 'README.md' || doc.relativePath === 'index.md';
+            const pageUrl = isIndex ? '/' : doc.url;
             // Prepare navigation data
             const adjacent = pageSequence.get(doc.url);
+            const root = rootPrefix(doc.url);
+            const relativeLink = (link) => link && { ...link, url: relativeUrl(root, link.url) };
             // Render document content
             const contentTemplate = isIndex ? indexTemplate : docPageTemplate;
             const content = this.templateEngine.renderWithLoops(contentTemplate, {
@@ -70,11 +78,11 @@ export class SiteGenerator {
                     ? this.documents.filter(d => d !== doc).map(d => ({
                         title: d.metadata.title,
                         description: d.metadata.description,
-                        url: d.url,
+                        url: relativeUrl(root, d.url),
                     }))
                     : undefined,
-                prevPage: adjacent?.prev,
-                nextPage: adjacent?.next,
+                prevPage: relativeLink(adjacent?.prev),
+                nextPage: relativeLink(adjacent?.next),
             });
             // Render full page with layout
             const html = this.templateEngine.renderWithLoops(layoutTemplate, {
@@ -87,8 +95,14 @@ export class SiteGenerator {
                 siteTitle: config.title || 'Documentation',
                 siteDescription: config.description || '',
                 content,
-                navigation: this.renderNavigation(navigation, doc.url),
+                root,
+                navigation: this.renderNavigation(navigation, root, doc.url),
                 chatEnabled: config.chat?.enabled,
+                ogUrl: config.baseUrl ? absoluteUrl(config.baseUrl, pageUrl) : undefined,
+                searchConfigJson: JSON.stringify({
+                    topK: config.build?.topK ?? 3,
+                    minScore: config.build?.minScore ?? 0.75,
+                }),
                 attribution: config.attribution !== false, // defaults to true
             });
             // Write HTML file
@@ -106,8 +120,22 @@ export class SiteGenerator {
             }
         }
         console.log(`Generated ${this.documents.length} HTML pages`);
+        if (config.baseUrl) {
+            this.writeSitemap(outputDir, config.baseUrl);
+        }
         return this.documents;
     }
+    writeSitemap(outputDir, baseUrl) {
+        const urls = this.documents
+            .map((doc) => {
+            const isRootIndex = doc.relativePath === 'README.md' || doc.relativePath === 'index.md';
+            return absoluteUrl(baseUrl, isRootIndex ? '/' : doc.url);
+        }).map((loc) => `  <url><loc>${loc}</loc></url>`)
+            .join('\n');
+        const sitemap = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
+        writeFileSync(join(outputDir, 'sitemap.xml'), sitemap, 'utf-8');
+        console.log('Generated sitemap.xml');
+    }
     /**
      * Build navigation structure from documents, grouping by top-level
      * folder so e.g. every doc under `path-of-python/` (its README plus
@@ -156,7 +184,7 @@ export class SiteGenerator {
      * other page sees the group collapsed to a single link that leads to
      * its root README.
      */
-    renderNavigation(items, currentUrl) {
+    renderNavigation(items, root, currentUrl) {
         if (items.length === 0)
             return '';
         let html = '<ul class="nav-list">';
@@ -168,9 +196,9 @@ export class SiteGenerator {
                 .filter(Boolean)
                 .join(' ');
             html += `<li${liClasses ? ` class="${liClasses}"` : ''}>`;
-            html += `<a href="${item.url}"${isActive ? ' class="active"' : ''}>${item.title}</a>`;
+            html += `<a href="${relativeUrl(root, item.url)}"${isActive ? ' class="active"' : ''}>${item.title}</a>`;
             if (isExpanded) {
-                html += this.renderNavigation(item.children, currentUrl);
+                html += this.renderNavigation(item.children, root, currentUrl);
             }
             html += '</li>';
         }

package/dist/src/builder/template-engine.d.ts

@@ -6,12 +6,12 @@ export declare class TemplateEngine {
      * Render a template with variables
      * Replaces {{variableName}} with values from data object
      */
-    render(template: string, data: Record<string, any>): string;
+    render(template: string, data: Record<string, unknown>): string;
     /**
      * Render a template with nested variables
      * Supports {{object.property}} syntax
      */
-    renderAdvanced(template: string, data: Record<string, any>): string;
+    renderAdvanced(template: string, data: Record<string, unknown>): string;
     /**
      * Get nested property from object using dot notation
      */
@@ -21,10 +21,10 @@ export declare class TemplateEngine {
      * Supports {{#if variable}}...{{/if}} syntax
      * Handles nested conditionals recursively
      */
-    renderWithConditionals(template: string, data: Record<string, any>): string;
+    renderWithConditionals(template: string, data: Record<string, unknown>): string;
     /**
      * Render template with loops
      * Supports {{#each items}}...{{/each}} syntax
      */
-    renderWithLoops(template: string, data: Record<string, any>): string;
+    renderWithLoops(template: string, data: Record<string, unknown>): string;
 }

package/dist/src/builder/template-engine.js

@@ -25,7 +25,11 @@ export class TemplateEngine {
      * Get nested property from object using dot notation
      */
     getNestedProperty(obj, path) {
-        return path.split('.').reduce((current, key) => current?.[key], obj);
+        return path
+            .split('.')
+            .reduce((current, key) => current && typeof current === 'object'
+            ? current[key]
+            : undefined, obj);
     }
     /**
      * Render template with conditional blocks

package/dist/src/builder/vector-db-builder.d.ts

@@ -3,6 +3,7 @@ import { VectorDatabase } from '../types/vector-db.js';
 export interface VectorDBBuilderOptions {
     chunkSize?: number;
     chunkOverlap?: number;
+    minChunkSize?: number;
     modelName?: string;
 }
 export declare class VectorDBBuilder {

package/dist/src/builder/vector-db-builder.js

@@ -10,6 +10,7 @@ export class VectorDBBuilder {
         this.chunker = new Chunker({
             maxChunkSize: options.chunkSize || 500,
             chunkOverlap: options.chunkOverlap || 50,
+            minChunkSize: options.minChunkSize,
         });
         this.embedder = new Embedder(options.modelName);
     }

package/dist/src/cli/index.js

@@ -1,14 +1,26 @@
 import { Command } from 'commander';
 import { build } from '../builder/index.js';
 import { defaultOptions } from './options.js';
-import { readFileSync } from 'fs';
+import { startServer } from './server.js';
+import { watchDocs } from './watcher.js';
+import { readFileSync, existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-// Read package.json for version
-// From dist/src/cli/index.js, go up 3 levels to project root
-const packageJson = JSON.parse(readFileSync(resolve(__dirname, '../../../package.json'), 'utf-8'));
+// Read package.json for version. Walks up from this file so it resolves
+// both from dist/src/cli (installed) and src/cli (tsx).
+function findPackageJson(startDir) {
+    let dir = startDir;
+    while (dir !== dirname(dir)) {
+        const candidate = resolve(dir, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        dir = dirname(dir);
+    }
+    throw new Error('package.json not found');
+}
+const packageJson = JSON.parse(readFileSync(findPackageJson(__dirname), 'utf-8'));
 const program = new Command();
 program
     .name('botdocs')
@@ -20,27 +32,58 @@ program
     .option('-c, --config <file>', 'Path to config file (botdocs.config.json)')
     .option('-t, --theme <theme>', 'Theme to use (classic, material, minimal, slate, modern); overrides config file if set')
     .option('-v, --verbose', 'Enable verbose logging')
+    .option('-w, --watch', 'Rebuild on changes and serve the site for live preview')
+    .option('-p, --port <number>', 'Port for the preview server (with --watch)', parseInt)
     .action(async (input, options) => {
-    try {
-        const inputDir = resolve(process.cwd(), input);
-        const outputDir = resolve(process.cwd(), options.output || defaultOptions.output);
-        if (options.verbose) {
-            console.log('Botdocs starting...');
-            console.log(`Input: ${inputDir}`);
-            console.log(`Output: ${outputDir}`);
-            console.log(`Chat enabled: ${!options.noChat}`);
-            console.log(`Theme override: ${options.theme || '(none — using config file or default)'}`);
-        }
+    const inputDir = resolve(process.cwd(), input);
+    const outputDir = resolve(process.cwd(), options.output || defaultOptions.output);
+    const verbose = options.verbose || false;
+    const runBuild = async () => {
         await build({
             inputDir,
             outputDir,
             chatEnabled: !options.noChat,
             configPath: options.config,
-            verbose: options.verbose || false,
+            verbose,
             theme: options.theme,
         });
-        console.log('Build complete!');
-        console.log(`Site generated at: ${outputDir}`);
+    };
+    try {
+        if (verbose) {
+            console.log('Botdocs starting...');
+            console.log(`Input: ${inputDir}`);
+            console.log(`Output: ${outputDir}`);
+            console.log(`Chat enabled: ${!options.noChat}`);
+            console.log(`Theme override: ${options.theme || '(none — using config file or default)'}`);
+        }
+        await runBuild();
+        if (options.watch) {
+            const server = await startServer(outputDir, options.port ?? defaultOptions.port);
+            console.log(`Site generated at: ${outputDir}`);
+            console.log(`Preview at: ${server.url}`);
+            console.log('Watching for changes... Press Ctrl+C to stop.');
+            const watcher = watchDocs(inputDir, (changes) => {
+                const names = [...new Set(changes.map((c) => c.path.split('/').pop()))].join(', ');
+                console.log(`Changed: ${names} — rebuilding...`);
+                runBuild().catch((error) => {
+                    console.error('Rebuild failed:', error);
+                });
+            });
+            let shuttingDown = false;
+            const shutdown = () => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                watcher.close();
+                server.close().finally(() => process.exit(0));
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        }
+        else {
+            console.log('Build complete!');
+            console.log(`Site generated at: ${outputDir}`);
+        }
     }
     catch (error) {
         console.error('Build failed:', error);

package/dist/src/cli/options.d.ts

@@ -5,5 +5,7 @@ export interface CliOptions {
     config?: string;
     verbose?: boolean;
     theme?: Theme;
+    watch?: boolean;
+    port?: number;
 }
 export declare const defaultOptions: Partial<CliOptions>;

package/dist/src/cli/options.js

@@ -2,4 +2,6 @@ export const defaultOptions = {
     output: 'output',
     noChat: false,
     verbose: false,
+    watch: false,
+    port: 3000,
 };

package/dist/src/cli/server.d.ts

@@ -0,0 +1,6 @@
+export interface RunningServer {
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startServer(rootDir: string, port?: number): Promise<RunningServer>;