skrypt-ai 0.8.0 → 0.8.1

package/dist/commands/bind.js

@@ -0,0 +1,139 @@
+import { Command } from 'commander';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, join } from 'path';
+import { extractSymbols } from '../binding/extractor.js';
+import { parseDocSections } from '../binding/doc-parser.js';
+import { createBindings } from '../binding/binder.js';
+import { detectStale } from '../binding/detector.js';
+const BINDINGS_PATH = '.skrypt/bindings.json';
+export const bindCommand = new Command('bind')
+    .description('Bind documentation sections to source code symbols')
+    .argument('[source]', 'Source code directory', '.')
+    .option('--docs <dir>', 'Documentation directory', './docs')
+    .option('--check', 'Check current bindings for stale docs')
+    .option('--diff', 'Show changes since last bind')
+    .option('--json', 'Output as JSON')
+    .action(async (source, options) => {
+    try {
+        const sourcePath = resolve(source);
+        const docsPath = resolve(options.docs || './docs');
+        if (!existsSync(sourcePath)) {
+            console.error(`Error: Source directory not found: ${sourcePath}`);
+            process.exit(1);
+        }
+        if (!existsSync(docsPath)) {
+            console.error(`Error: Docs directory not found: ${docsPath}`);
+            process.exit(1);
+        }
+        console.log('skrypt bind');
+        console.log(`  source: ${sourcePath}`);
+        console.log(`  docs:   ${docsPath}`);
+        console.log('');
+        // Step 1: Extract code symbols
+        console.log('Extracting code symbols...');
+        const symbols = await extractSymbols(sourcePath);
+        const exported = symbols.filter(s => s.isExported);
+        console.log(`  Found ${symbols.length} symbols (${exported.length} exported)`);
+        // Step 2: Parse doc sections
+        console.log('Parsing documentation sections...');
+        const sections = parseDocSections(docsPath);
+        console.log(`  Found ${sections.length} sections across ${new Set(sections.map(s => s.filePath)).size} files`);
+        // Step 3: Create bindings
+        console.log('\nCreating bindings...');
+        const bindings = createBindings(symbols, sections);
+        console.log(`  Created ${bindings.length} bindings`);
+        const explicit = bindings.filter(b => b.bindingType === 'explicit').length;
+        const reference = bindings.filter(b => b.bindingType === 'reference').length;
+        console.log(`    Explicit (code block): ${explicit}`);
+        console.log(`    Reference (prose):     ${reference}`);
+        // Handle --check mode
+        if (options.check) {
+            const existing = readBindingsFile(sourcePath);
+            if (!existing) {
+                console.error('\nNo existing bindings found. Run `skrypt bind` first.');
+                process.exit(1);
+            }
+            const staleDocs = detectStale(existing.symbols, symbols, existing.bindings);
+            if (staleDocs.length === 0) {
+                console.log('\n\x1b[32mAll documentation is up to date.\x1b[0m');
+                return;
+            }
+            console.log(`\n\x1b[33m${staleDocs.length} stale doc section(s) found:\x1b[0m\n`);
+            for (const stale of staleDocs) {
+                const severityColor = stale.severity === 'high' ? '\x1b[31m' : stale.severity === 'medium' ? '\x1b[33m' : '\x1b[2m';
+                console.log(`  ${severityColor}[${stale.severity.toUpperCase()}]\x1b[0m ${stale.docPath}`);
+                console.log(`    Section: ${stale.section}`);
+                console.log(`    Reason:  ${stale.reason}`);
+                console.log('');
+            }
+            if (options.json) {
+                console.log(JSON.stringify({ staleDocs }, null, 2));
+            }
+            const highCount = staleDocs.filter(s => s.severity === 'high').length;
+            if (highCount > 0)
+                process.exit(1);
+            return;
+        }
+        // Handle --diff mode
+        if (options.diff) {
+            const existing = readBindingsFile(sourcePath);
+            if (!existing) {
+                console.log('\nNo previous bindings to diff against.');
+            }
+            else {
+                const staleDocs = detectStale(existing.symbols, symbols, existing.bindings);
+                const newBindings = bindings.length - existing.bindings.length;
+                console.log(`\n  Previous bindings: ${existing.bindings.length}`);
+                console.log(`  Current bindings:  ${bindings.length}`);
+                console.log(`  Net change:        ${newBindings >= 0 ? '+' : ''}${newBindings}`);
+                console.log(`  Stale sections:    ${staleDocs.length}`);
+            }
+            return;
+        }
+        // Default: save bindings
+        const bindingsFile = {
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            bindings,
+            symbols,
+            sections,
+        };
+        const outputPath = join(sourcePath, BINDINGS_PATH);
+        mkdirSync(join(sourcePath, '.skrypt'), { recursive: true });
+        writeFileSync(outputPath, JSON.stringify(bindingsFile, null, 2));
+        if (options.json) {
+            console.log(JSON.stringify({ bindings: bindings.length, symbols: symbols.length, sections: sections.length }, null, 2));
+        }
+        console.log(`\nBindings saved to ${outputPath}`);
+        console.log(`\n=== Summary ===`);
+        console.log(`  Symbols:  ${symbols.length}`);
+        console.log(`  Sections: ${sections.length}`);
+        console.log(`  Bindings: ${bindings.length}`);
+        const boundSymbols = new Set(bindings.map(b => b.codeSymbol.name));
+        const unboundExported = exported.filter(s => !boundSymbols.has(s.name));
+        if (unboundExported.length > 0) {
+            console.log(`\n  \x1b[33mUnbound exported symbols: ${unboundExported.length}\x1b[0m`);
+            for (const s of unboundExported.slice(0, 10)) {
+                console.log(`    ${s.kind.padEnd(10)} ${s.name}`);
+            }
+            if (unboundExported.length > 10) {
+                console.log(`    ... and ${unboundExported.length - 10} more`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});
+function readBindingsFile(projectDir) {
+    const filePath = join(projectDir, BINDINGS_PATH);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/claims.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const claimsCommand: Command;

package/dist/commands/claims.js

@@ -0,0 +1,84 @@
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { requirePro } from '../auth/index.js';
+import { loadConfig, checkApiKey } from '../config/index.js';
+import { createLLMClient } from '../llm/index.js';
+import { extractClaimsFromDirectory } from '../claims/extractor.js';
+import { readClaims, writeClaims, mergeClaims } from '../claims/store.js';
+import { printClaimsReport, formatClaimsJson } from '../claims/reporter.js';
+export const claimsCommand = new Command('claims')
+    .description('Extract testable claims from documentation')
+    .argument('[docs]', 'Documentation directory', './docs')
+    .option('--file <path>', 'Target a specific doc file')
+    .option('--type <type>', 'Filter by claim type (behavioral, constraint, integration, performance, error_handling)')
+    .option('--json', 'Output as JSON')
+    .option('--verify', 'Verify extracted claims (coming soon)')
+    .option('--provider <name>', 'LLM provider')
+    .option('--model <name>', 'LLM model')
+    .option('-c, --config <file>', 'Config file path')
+    .action(async (docs, options) => {
+    try {
+        if (!await requirePro('claims')) {
+            process.exit(1);
+        }
+        const docsPath = resolve(docs);
+        if (!existsSync(docsPath)) {
+            console.error(`Error: Docs directory not found: ${docsPath}`);
+            process.exit(1);
+        }
+        if (options.verify) {
+            console.log('\nClaim verification is coming in a future release.');
+            console.log('For now, claims are extracted and stored for review.\n');
+        }
+        console.log('skrypt claims');
+        console.log(`  docs: ${docsPath}`);
+        if (options.file)
+            console.log(`  file: ${options.file}`);
+        if (options.type)
+            console.log(`  type: ${options.type}`);
+        console.log('');
+        // Set up LLM client
+        const config = loadConfig(options.config);
+        if (options.provider)
+            config.llm.provider = options.provider;
+        if (options.model)
+            config.llm.model = options.model;
+        const { ok, envKey } = checkApiKey(config.llm.provider);
+        if (!ok && envKey) {
+            console.error(`Error: ${envKey} required for ${config.llm.provider}`);
+            process.exit(1);
+        }
+        const client = createLLMClient({
+            provider: config.llm.provider,
+            model: config.llm.model,
+        });
+        // Extract claims
+        console.log('Extracting testable claims...');
+        const claims = await extractClaimsFromDirectory(docsPath, client, {
+            file: options.file ? resolve(options.file) : undefined,
+            type: options.type,
+        });
+        if (claims.length === 0) {
+            console.log('\nNo testable claims found.');
+            return;
+        }
+        // Merge with existing claims
+        const projectDir = resolve('.');
+        const existing = readClaims(projectDir);
+        const merged = existing ? mergeClaims(existing.claims, claims) : claims;
+        writeClaims(projectDir, merged);
+        // Output
+        if (options.json) {
+            console.log(formatClaimsJson(claims));
+        }
+        else {
+            printClaimsReport(claims);
+            console.log(`  Claims saved to .skrypt/claims.json`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});

package/dist/commands/coverage.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const coverageCommand: Command;

package/dist/commands/coverage.js

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { scanDirectory } from '../scanner/index.js';
+import { parseDocumentedElements } from '../audit/doc-parser.js';
+import { calculateCoverage } from '../coverage/calculator.js';
+import { printCoverageReport, formatCoverageJson } from '../coverage/reporter.js';
+export const coverageCommand = new Command('coverage')
+    .description('Measure documentation coverage across your codebase')
+    .argument('[source]', 'Source code directory', '.')
+    .option('--docs <dir>', 'Documentation directory', './docs')
+    .option('--include-internal', 'Include non-exported symbols')
+    .option('--min-coverage <percent>', 'Fail if coverage is below this threshold')
+    .option('--json', 'Output as JSON')
+    .action(async (source, options) => {
+    try {
+        const sourcePath = resolve(source);
+        const docsPath = resolve(options.docs || './docs');
+        if (!existsSync(sourcePath)) {
+            console.error(`Error: Source directory not found: ${sourcePath}`);
+            process.exit(1);
+        }
+        if (!existsSync(docsPath)) {
+            console.error(`Error: Docs directory not found: ${docsPath}`);
+            process.exit(1);
+        }
+        // Step 1: Scan source code
+        console.log('Scanning source code...');
+        const scanResult = await scanDirectory(sourcePath, {
+            onProgress: (current, total, file) => {
+                process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
+            }
+        });
+        console.log('');
+        const codeElements = scanResult.files.flatMap(f => f.elements);
+        // Step 2: Parse documented elements
+        console.log('Parsing documentation...');
+        const docElements = parseDocumentedElements(docsPath);
+        // Step 3: Calculate coverage
+        const report = calculateCoverage(codeElements, docElements, options.includeInternal ?? false);
+        // Step 4: Output
+        if (options.json) {
+            console.log(formatCoverageJson(report));
+        }
+        else {
+            printCoverageReport(report);
+        }
+        // Step 5: Threshold check
+        if (options.minCoverage) {
+            const threshold = parseInt(options.minCoverage, 10);
+            if (!isNaN(threshold) && report.coveragePercent < threshold) {
+                console.error(`\nCoverage ${report.coveragePercent}% is below threshold ${threshold}%`);
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});

package/dist/commands/generate/index.js

@@ -169,6 +169,11 @@ export const generateCommand = new Command('generate')
         else if (config.llm.provider !== 'ollama') {
             console.log('  routing:  via Skrypt API proxy');
         }
+        // Quality recommendation for non-optimal models
+        const RECOMMENDED_MODELS = ['claude-sonnet-4-6', 'claude-sonnet-4-20250514', 'claude-opus-4-6'];
+        if (!RECOMMENDED_MODELS.some(m => config.llm.model.includes(m))) {
+            console.log('  tip:      For best results, use --provider anthropic (Claude Sonnet 4 recommended)');
+        }
         console.log('');
         // Scan sources
         const scanResult = await scanSources(sources, {

package/dist/commands/generate/scan.js

@@ -67,6 +67,36 @@ export function findOpenAPISpec(sourcePath) {
     }
     return null;
 }
+/** Cache compiled RegExp for name-based exclude patterns (avoids recompiling per element). */
+const nameRegexCache = new Map();
+/** ReDoS guard pattern — reject patterns with nested quantifiers. */
+const REDOS_GUARD = /(\+|\*|\?)\{|\(\?[^:)]|\(\.[*+].*\)\+|\([^)]*[+*][^)]*\)[+*]/;
+/** Metacharacter test — only compile regex if the pattern contains these. */
+const HAS_META = /[*+?{}()|[\]\\^$.]/;
+function getCachedNameRegex(namePattern) {
+    if (nameRegexCache.has(namePattern)) {
+        return nameRegexCache.get(namePattern);
+    }
+    // Only compile if pattern contains regex metacharacters
+    if (!HAS_META.test(namePattern)) {
+        nameRegexCache.set(namePattern, null);
+        return null;
+    }
+    // Reject patterns prone to catastrophic backtracking
+    if (REDOS_GUARD.test(namePattern)) {
+        nameRegexCache.set(namePattern, null);
+        return null;
+    }
+    try {
+        const regex = new RegExp(namePattern);
+        nameRegexCache.set(namePattern, regex);
+        return regex;
+    }
+    catch {
+        nameRegexCache.set(namePattern, null);
+        return null;
+    }
+}
 /**
  * Check if element should be excluded based on patterns
  */
@@ -78,20 +108,9 @@ export function shouldExcludeElement(element, patterns) {
             if (element.name === namePattern) {
                 return true;
             }
-            // Only use regex if the pattern contains regex metacharacters
-            // Reject patterns with nested quantifiers to prevent catastrophic backtracking (ReDoS)
-            if (/[*+?{}()|[\]\\^$.]/.test(namePattern)) {
-                if (/(\+|\*|\?)\{|\(\?[^:)]|\(\.[*+].*\)\+|\([^)]*[+*][^)]*\)[+*]/.test(namePattern)) {
-                    continue; // Skip patterns prone to catastrophic backtracking
-                }
-                try {
-                    if (new RegExp(namePattern).test(element.name))
-                        return true;
-                }
-                catch {
-                    // Invalid regex — treat as literal match (already checked above)
-                }
-            }
+            const regex = getCachedNameRegex(namePattern);
+            if (regex && regex.test(element.name))
+                return true;
         }
         // Match by file path
         else if (pattern.includes('/') || pattern.includes('*')) {

package/dist/commands/generate/write.d.ts

@@ -1,3 +1,4 @@
+import { type Topic } from '../../generator/index.js';
 import { APIElement } from '../../scanner/index.js';
 type GeneratedDoc = Awaited<ReturnType<typeof import('../../generator/index.js').generateForElements>>[number];
 interface WriteDocsOptions {
@@ -22,4 +23,10 @@ interface WriteAssetsOptions {
  * Write post-generation assets: OpenAPI spec copy, llms.txt, AGENTS.md, manifest.
  */
 export declare function writeAssets(docs: GeneratedDoc[], allElements: APIElement[], outputPath: string, primarySourcePath: string, configOutputPath: string, filesWritten: number, options: WriteAssetsOptions): Promise<void>;
+/**
+ * Update docs.json navigation after topic-based generation.
+ * Preserves all non-"API Reference" groups and replaces the
+ * "API Reference" group with pages derived from the generated topics.
+ */
+export declare function updateDocsJsonNavigation(topics: Topic[], outputDir: string): void;
 export {};

package/dist/commands/generate/write.js

@@ -1,4 +1,4 @@
-import { existsSync, copyFileSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, copyFileSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { resolve, basename, dirname, join, relative } from 'path';
 import { groupDocsByFile, writeDocsToDirectory, writeDocsByTopic, writeLlmsTxt, generateAgentsMd } from '../../generator/index.js';
 import { writeManifest, buildManifestEntries } from '../../refresh/manifest.js';
@@ -15,6 +15,8 @@ export async function writeDocs(docs, outputPath, primarySourcePath, isMultiSour
         filesWritten = result.filesWritten;
         totalDocs = result.totalDocs;
         console.log(`  topics: ${result.topics.map(t => t.name).join(', ')}`);
+        // Auto-update docs.json navigation with generated topics
+        updateDocsJsonNavigation(result.topics, outputPath);
     }
     else if (isMultiSource) {
         // Multi-source: write docs namespaced by source label
@@ -118,3 +120,65 @@ export async function writeAssets(docs, allElements, outputPath, primarySourcePa
         // Non-fatal — manifest is optional
     }
 }
+/**
+ * Find docs.json by walking up from the output directory (max 3 levels).
+ * Returns the path if found, null otherwise.
+ */
+function findDocsJson(outputDir) {
+    let dir = resolve(outputDir);
+    for (let i = 0; i < 4; i++) {
+        const candidate = join(dir, 'docs.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Update docs.json navigation after topic-based generation.
+ * Preserves all non-"API Reference" groups and replaces the
+ * "API Reference" group with pages derived from the generated topics.
+ */
+export function updateDocsJsonNavigation(topics, outputDir) {
+    const docsJsonPath = findDocsJson(outputDir);
+    if (!docsJsonPath)
+        return;
+    let docsJson;
+    try {
+        docsJson = JSON.parse(readFileSync(docsJsonPath, 'utf-8'));
+    }
+    catch {
+        return; // corrupted or unreadable — skip silently
+    }
+    if (!docsJson || typeof docsJson !== 'object')
+        return;
+    const navigation = Array.isArray(docsJson.navigation) ? docsJson.navigation : [];
+    // Build updated "API Reference" pages sorted by topic order
+    const apiRefPages = topics
+        .slice()
+        .sort((a, b) => a.order - b.order)
+        .map(t => ({ title: t.name, path: `/docs/${t.id}` }));
+    // Preserve all groups except "API Reference", then insert updated one
+    const otherGroups = navigation.filter((g) => g.group !== 'API Reference');
+    // Find the original API Reference group to preserve its icon
+    const existingApiRef = navigation.find((g) => g.group === 'API Reference');
+    const apiRefGroup = {
+        group: 'API Reference',
+        icon: existingApiRef?.icon ?? 'Code',
+        pages: apiRefPages,
+    };
+    // Re-insert API Reference at its original position (or at the end)
+    const originalIndex = navigation.findIndex((g) => g.group === 'API Reference');
+    const updated = [...otherGroups];
+    if (originalIndex >= 0 && originalIndex < updated.length) {
+        updated.splice(originalIndex, 0, apiRefGroup);
+    }
+    else {
+        updated.push(apiRefGroup);
+    }
+    docsJson.navigation = updated;
+    writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2) + '\n', 'utf-8');
+}

package/dist/commands/import.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync } from 'fs';
-import { resolve, join, dirname, basename } from 'path';
+import { resolve, join, dirname, basename, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { detectFormat, isGitHubUrl, parseGitHubUrl, runImport, importFromGitHub } from '../importers/index.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -102,14 +102,23 @@ function scaffoldOutput(outputDir, result) {
         mkdirSync(outputDir, { recursive: true });
     }
     // Write transformed content files
+    const resolvedOutputDir = resolve(outputDir) + sep;
     for (const [filePath, content] of result.files) {
-        const outputPath = join(outputDir, filePath);
+        const outputPath = resolve(join(outputDir, filePath));
+        if (!outputPath.startsWith(resolvedOutputDir)) {
+            console.warn(`  Skipping file outside output directory: ${filePath}`);
+            continue;
+        }
         mkdirSync(dirname(outputPath), { recursive: true });
         writeFileSync(outputPath, content);
     }
     // Copy assets
     for (const [destPath, srcPath] of result.assets) {
-        const outputPath = join(outputDir, destPath);
+        const outputPath = resolve(join(outputDir, destPath));
+        if (!outputPath.startsWith(resolvedOutputDir)) {
+            console.warn(`  Skipping asset outside output directory: ${destPath}`);
+            continue;
+        }
         mkdirSync(dirname(outputPath), { recursive: true });
         try {
             cpSync(srcPath, outputPath);

package/dist/commands/init.js

@@ -1,20 +1,62 @@
 import { Command } from 'commander';
-import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, readdirSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+import { existsSync, mkdirSync, cpSync, copyFileSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, dirname, resolve, extname } from 'path';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+/** Returns true if the value looks like a URL (http/https/data URI). */
+function isUrl(value) {
+    return /^https?:\/\/|^data:/.test(value);
+}
+/** Validate a hex color string (#RGB or #RRGGBB). */
+function isValidHex(color) {
+    return /^#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3})?$/.test(color);
+}
+/**
+ * Copy a local asset into the template's public/ directory and return the
+ * public-relative path (e.g. `/logo.png`). If the source is a URL, return
+ * it as-is.
+ */
+function resolveAsset(value, targetDir, defaultName) {
+    if (isUrl(value))
+        return value;
+    const src = resolve(value);
+    if (!existsSync(src)) {
+        console.error(`Error: File not found: ${src}`);
+        process.exit(1);
+    }
+    const ext = extname(src);
+    const destName = `${defaultName}${ext}`;
+    const publicDir = join(targetDir, 'public');
+    mkdirSync(publicDir, { recursive: true });
+    copyFileSync(src, join(publicDir, destName));
+    return `/${destName}`;
+}
 export const initCommand = new Command('init')
     .description('Initialize a new documentation site')
     .argument('[directory]', 'Target directory', '.')
     .option('--name <name>', 'Project name', 'my-docs')
+    .option('--color <hex>', 'Primary brand color (hex, e.g. "#FF5733")')
+    .option('--logo <url-or-path>', 'Logo URL or local file path')
+    .option('--favicon <url-or-path>', 'Favicon URL or local file path')
     .action(async (directory, options) => {
     try {
         const targetDir = resolve(directory);
         console.log('skrypt init');
         console.log(`  directory: ${targetDir}`);
         console.log(`  name:      ${options.name}`);
+        if (options.color)
+            console.log(`  color:     ${options.color}`);
+        if (options.logo)
+            console.log(`  logo:      ${options.logo}`);
+        if (options.favicon)
+            console.log(`  favicon:   ${options.favicon}`);
         console.log('');
+        // Validate color if provided
+        if (options.color && !isValidHex(options.color)) {
+            console.error(`Error: Invalid hex color "${options.color}". Use format #RGB or #RRGGBB.`);
+            process.exit(1);
+        }
         // Check if directory exists and is not empty
         if (existsSync(targetDir)) {
             const files = readdirSync(targetDir);
@@ -44,15 +86,32 @@ export const initCommand = new Command('init')
             console.error('Error: Template package.json is missing or corrupted. Please reinstall skrypt.');
             process.exit(1);
         }
-        // Update docs.json with project name
+        // Update docs.json with project name and branding
         const docsJsonPath = join(targetDir, 'docs.json');
         try {
             const docsJson = JSON.parse(readFileSync(docsJsonPath, 'utf-8'));
             docsJson.name = options.name;
             docsJson.description = `${options.name} documentation`;
+            // Branding: primary color
+            if (options.color) {
+                if (!docsJson.theme)
+                    docsJson.theme = {};
+                docsJson.theme.primaryColor = options.color;
+            }
+            // Branding: logo
+            if (options.logo) {
+                docsJson.logo = resolveAsset(options.logo, targetDir, 'logo');
+            }
+            // Branding: favicon
+            if (options.favicon) {
+                docsJson.favicon = resolveAsset(options.favicon, targetDir, 'favicon');
+            }
             writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2));
         }
-        catch {
+        catch (e) {
+            // Re-throw asset resolution errors (already printed)
+            if (e instanceof Error && e.message.includes('ENOENT'))
+                throw e;
             console.error('Error: Template docs.json is missing or corrupted. Please reinstall skrypt.');
             process.exit(1);
         }
@@ -63,7 +122,11 @@ export const initCommand = new Command('init')
         console.log('  npm install');
         console.log('  npm run dev');
         console.log('');
-        console.log('Then open http://localhost:3000 to see your docs.');
+        console.log('Customize your docs in docs.json:');
+        console.log('  - theme.primaryColor: Your brand color (hex)');
+        console.log('  - logo: Path to your logo image');
+        console.log('  - favicon: Path to your favicon');
+        console.log('  - fonts: { sans, mono } font families');
         console.log('');
         console.log('To generate API documentation:');
         console.log('  skrypt generate ./src -o ./content/docs');

package/dist/commands/monitor.d.ts

@@ -1,2 +1,17 @@
 import { Command } from 'commander';
+export interface CodeChange {
+    file: string;
+    status: 'added' | 'modified' | 'deleted';
+    diff: string;
+    isUserFacing: boolean;
+}
+export interface DocSuggestion {
+    file: string;
+    action: 'create' | 'update' | 'delete';
+    reason: string;
+    suggestedContent?: string;
+    priority: 'high' | 'medium' | 'low';
+}
+export declare function isCodeFile(file: string): boolean;
+export declare function isUserFacingChange(file: string, diff: string): boolean;
 export declare const monitorCommand: Command;

package/dist/commands/monitor.js

@@ -50,11 +50,11 @@ function getGitChanges(since, repoPath) {
     }
     return changes;
 }
-function isCodeFile(file) {
+export function isCodeFile(file) {
     const codeExtensions = ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.rb', '.java', '.swift', '.kt'];
     return codeExtensions.some(ext => file.endsWith(ext));
 }
-function isUserFacingChange(file, diff) {
+export function isUserFacingChange(file, diff) {
     // Check if file is in common API/public paths
     const publicPaths = ['src/api', 'lib/', 'pkg/', 'public/', 'exports/', 'index.'];
     if (publicPaths.some(p => file.includes(p)))

package/dist/commands/mutate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const mutateCommand: Command;