@meistrari/tela-build 1.0.0

package/lib/doc-generator.ts

@@ -0,0 +1,903 @@
+/* eslint-disable no-console */
+import { join, resolve, relative, dirname, basename } from 'pathe'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { parse as parseVue } from 'vue-docgen-api'
+// Load glob dynamically for compatibility across versions (v8 vs v11)
+import { getTypeResolver, type TypeResolver } from './type-resolver'
+import { createVolarExtractor, type VolarExtractor } from './extractors/volar-extract'
+
+const colors = {
+    gray: '\x1B[90m',
+    orange: '\x1B[38;5;208m',
+    reset: '\x1B[0m',
+}
+
+export interface ComponentDoc {
+    name: string
+    tagName: string
+    path: string
+    directory: string
+    description: string
+    props: any[]
+    events: any[]
+    slots: any[]
+    stories?: StoryDoc
+    parseError?: string
+}
+
+export interface StoryDoc {
+    title: string
+    examples: any[]
+    argTypes: any
+}
+
+export async function collectComponentDocs(layerPath: string, appRootDir?: string): Promise<{ docs: ComponentDoc[], typeResolver: TypeResolver }> {
+    const componentPath = join(layerPath, 'components')
+    const componentPattern = join(componentPath, '**/*.vue')
+
+    const debug = process.env.TELA_BUILD_DEBUG === 'true'
+    const preferVolar = process.env.TELA_BUILD_EXTRACTOR !== 'docgen' // 'auto' (default) or 'volar'
+
+    // Debug: Check what paths exist
+    const layerNodeModules = resolve(layerPath, 'node_modules')
+    const appNodeModules = appRootDir ? resolve(appRootDir, 'node_modules') : null
+    const overlayRoot = appRootDir ?? layerPath
+
+    if (debug) {
+        console.log(`${colors.gray}[tela/build] Layer path: ${layerPath}${colors.reset}`)
+        console.log(`${colors.gray}[tela/build] Layer node_modules exists: ${existsSync(layerNodeModules)} (${layerNodeModules})${colors.reset}`)
+        if (appNodeModules) {
+            console.log(`${colors.gray}[tela/build] App node_modules exists: ${existsSync(appNodeModules)} (${appNodeModules})${colors.reset}`)
+        }
+        console.log(`${colors.gray}[tela/build] Extractor preference: ${preferVolar ? 'volar-first' : 'docgen-only'} (root=${overlayRoot})${colors.reset}`)
+
+        // Check if specific packages exist
+        const radixPath = resolve(layerNodeModules, 'radix-vue')
+        const rekaPath = resolve(layerNodeModules, 'reka-ui')
+        console.log(`${colors.gray}[tela/build] radix-vue exists: ${existsSync(radixPath)} (${radixPath})${colors.reset}`)
+        console.log(`${colors.gray}[tela/build] reka-ui exists: ${existsSync(rekaPath)} (${rekaPath})${colors.reset}`)
+    }
+
+    // Initialize type resolver for the project (used to format types in markdown)
+    const typeResolver = await getTypeResolver(layerPath, appRootDir)
+
+    // Prepare Volar extractor once (optional)
+    let volar: VolarExtractor | null = null
+    if (preferVolar) {
+        try {
+            volar = createVolarExtractor(overlayRoot, layerPath)
+            if (debug) {
+                console.log(`${colors.gray}[tela/build] Using Volar extractor with tsconfig overlay at ${overlayRoot}/.docs/tsconfig.tela-docs.json${colors.reset}`)
+            }
+        }
+        catch (e: any) {
+            if (debug) {
+                console.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} Failed to init Volar extractor: ${e.message}${colors.reset}`)
+            }
+            volar = null
+        }
+    }
+
+    const files = await globAsync(componentPattern, { ignore: ['**/*.story.vue', '**/*.test.vue', '**/*.spec.vue'] })
+    const docs: ComponentDoc[] = []
+
+    for (const file of files) {
+        let info
+        let parseError: string | undefined
+
+        try {
+            const absoluteFile = resolve(file)
+
+            if (volar) {
+                try {
+                    const volarInfo = volar.extract(absoluteFile)
+                    info = {
+                        displayName: volarInfo.name,
+                        exportName: volarInfo.name,
+                        description: volarInfo.description,
+                        props: volarInfo.props.map(p => ({
+                            name: p.name,
+                            required: p.required,
+                            type: p.type,
+                            defaultValue: p.defaultValue,
+                            description: p.description,
+                        })),
+                        events: volarInfo.events.map(e => ({
+                            name: e.name,
+                            type: e.type,
+                            description: e.description,
+                        })),
+                        slots: volarInfo.slots.map(s => ({
+                            name: s.name,
+                            description: s.description,
+                            scoped: Array.isArray(s.bindings) && s.bindings.length > 0,
+                            bindings: (s.bindings || []).map(b => ({ name: b.name, type: b.type })),
+                        })),
+                    }
+                }
+                catch (volarError: any) {
+                    if (debug) {
+                        console.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} Volar extractor failed for ${relative(layerPath, file)}: ${volarError.message}. Falling back to vue-docgen-api.${colors.reset}`)
+                    }
+                }
+            }
+
+            if (!info) {
+                // Configure module resolution - this is the key to fixing import resolution
+                // The 'modules' option mirrors webpack's resolve.modules option
+                const parseOptions = {
+                    modules: [
+                        layerNodeModules, // Layer's node_modules (where packages actually exist)
+                        appNodeModules, // App's node_modules as fallback
+                    ].filter(Boolean),
+                    jsx: false, // Disable JSX parsing to avoid babel issues with TypeScript
+                }
+
+                if (debug) {
+                    console.log(`${colors.gray}[tela/build] Using vue-docgen-api with modules:${colors.reset}`, parseOptions.modules)
+                }
+
+                info = await parseVue(file, parseOptions as any)
+            }
+        }
+        catch (error: any) {
+            // Capture the parse error but still create documentation
+            parseError = error.message
+            console.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} Failed to parse ${relative(layerPath, file)}: ${error.message}${colors.reset}`)
+
+            // Create basic component info from filename
+            const fileName = basename(file, '.vue')
+            info = {
+                displayName: fileName,
+                exportName: fileName,
+                description: '',
+                props: [],
+                events: [],
+                slots: [],
+            }
+        }
+
+        const fileName = basename(file, '.vue')
+        const directory = relative(componentPath, dirname(file))
+
+        // Generate component tag name
+        const tagName = generateTagName(fileName)
+
+        const componentDoc: ComponentDoc = {
+            name: info.displayName || info.exportName || fileName,
+            tagName,
+            path: relative(layerPath, file),
+            directory,
+            description: info.description || '',
+            // Normalize props/events/slots shape to your generator consumption
+            props: (info.props || []).map((p: any) => ({
+                name: p.name,
+                required: !!p.required,
+                type: typeof p.type === 'string' ? p.type : (p.type?.name ?? p.type ?? 'any'),
+                defaultValue: p.defaultValue,
+                description: p.description,
+            })),
+            events: (info.events || []).map((e: any) => ({
+                name: e.name,
+                type: typeof e.type === 'string' ? e.type : (e.type?.name ?? e.type ?? 'any'),
+                description: e.description,
+            })),
+            slots: (info.slots || []).map((s: any) => ({
+                name: s.name,
+                description: s.description,
+                scoped: s.scoped || (Array.isArray(s.bindings) && s.bindings.length > 0),
+                bindings: s.bindings,
+            })),
+            parseError,
+        }
+
+        // Look for associated MDX documentation file
+        const mdxPath = file.replace('.vue', '.mdx')
+        if (existsSync(mdxPath)) {
+            componentDoc.stories = await parseMdxFile(mdxPath)
+        }
+
+        docs.push(componentDoc)
+    }
+
+    const sortedDocs = docs.sort((a, b) => {
+    // Sort by directory first, then by name
+        const dirCompare = a.directory.localeCompare(b.directory)
+        return dirCompare !== 0 ? dirCompare : a.name.localeCompare(b.name)
+    })
+
+    return { docs: sortedDocs, typeResolver }
+}
+
+async function globAsync(pattern: string, options: any): Promise<string[]> {
+    const mod: any = await import('glob')
+    const fn = mod.glob ?? mod.default ?? mod
+    // Prefer sync API for widest compatibility (glob v8+)
+    if (fn && typeof fn.sync === 'function') {
+        return fn.sync(pattern, options)
+    }
+    const res = await fn(pattern, options)
+    if (Array.isArray(res))
+        return res
+    try {
+    // Some versions may return an iterable or Glob instance
+        if (res && typeof res[Symbol.iterator] === 'function') {
+            return Array.from(res)
+        }
+    }
+    catch {}
+    return []
+}
+
+export function generateTagName(fileName: string): string {
+    // Convert file name to PascalCase tag name
+    // Components in tela/ directory should preserve the Tela prefix
+    // e.g., tela-input -> TelaInput, button -> TelaButton
+
+    let tagName: string
+
+    // Check if the file already starts with 'tela-'
+    if (fileName.startsWith('tela-')) {
+    // Already has tela prefix, just convert to PascalCase
+        const parts = fileName.split('-')
+        tagName = parts.map(part =>
+            part.charAt(0).toUpperCase() + part.slice(1),
+        ).join('')
+    }
+    else {
+    // Add Tela prefix for components without it
+        const parts = fileName.split('-')
+        const componentName = parts.map(part =>
+            part.charAt(0).toUpperCase() + part.slice(1),
+        ).join('')
+        tagName = `Tela${componentName}`
+    }
+
+    return tagName
+}
+
+export async function parseMdxFile(mdxPath: string): Promise<StoryDoc | undefined> {
+    try {
+        const content = readFileSync(mdxPath, 'utf-8')
+
+        // Extract title from the main heading
+        const titleMatch = content.match(/^#\s+(.+)$/m)
+        const title = titleMatch ? titleMatch[1] : ''
+
+        // Extract code examples from ```vue blocks with better heading detection
+        const examples: any[] = []
+        const codeBlockRegex = /```vue\n([\s\S]*?)\n```/g
+        const matches = Array.from(content.matchAll(codeBlockRegex))
+
+        for (let i = 0; i < matches.length; i++) {
+            const match = matches[i]
+            const codeContent = match[1].trim()
+            const codeBlockStart = match.index
+
+            // Find the closest heading before this code block
+            const beforeCode = content.substring(0, codeBlockStart)
+            const exampleName = findClosestHeading(beforeCode, i + 1)
+
+            examples.push({
+                name: exampleName,
+                code: codeContent,
+            })
+        }
+
+        return {
+            title,
+            examples,
+            argTypes: '',
+        }
+    }
+    catch (error: any) {
+        console.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} Failed to parse MDX ${basename(mdxPath)}: ${error.message}${colors.reset}`)
+        return undefined
+    }
+}
+
+function findClosestHeading(textBeforeCode: string, exampleIndex: number): string {
+    // Split into lines and work backwards to find the closest heading
+    const lines = textBeforeCode.split('\n')
+
+    // Look for headings starting from the end (closest to code block)
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim()
+
+        // Check for markdown headings (### or ####)
+        const headingMatch = line.match(/^###?\s+(.+)/)
+        if (headingMatch) {
+            return headingMatch[1].trim()
+        }
+
+        // Check for bold text that might be a heading (**text**)
+        const boldMatch = line.match(/^\*\*([^*]+)\*\*\s*$/)
+        if (boldMatch) {
+            return boldMatch[1].trim()
+        }
+
+        // If we hit a higher level heading (## or #), stop looking
+        // This prevents us from going too far up the document
+        if (line.match(/^##?\s+/) && !line.match(/^###/)) {
+            break
+        }
+    }
+
+    // Fallback to generic name
+    return `Example ${exampleIndex}`
+}
+
+export function generateMarkdown(componentDocs: ComponentDoc[], typeResolver: TypeResolver): string {
+    const lines: string[] = []
+
+    // Header
+    lines.push('# tela/build — Components Documentation')
+    lines.push('')
+    lines.push('> Auto-generated documentation for tela/build components')
+    lines.push(`> Generated on ${new Date().toISOString()}`)
+    lines.push('')
+
+    // Group components by directory
+    const componentsByDir = groupByDirectory(componentDocs)
+
+    // Table of Contents
+    lines.push('## Table of Contents')
+    lines.push('')
+
+    for (const [dir, components] of Object.entries(componentsByDir)) {
+        if (dir && dir !== '.') {
+            lines.push(`- **${dir}**`)
+            components.forEach((comp) => {
+                lines.push(`  - [${comp.tagName}](#${comp.tagName.toLowerCase()})`)
+            })
+        }
+        else {
+            components.forEach((comp) => {
+                lines.push(`- [${comp.tagName}](#${comp.tagName.toLowerCase()})`)
+            })
+        }
+    }
+    lines.push('')
+
+    lines.push('---')
+    lines.push('')
+
+    // Component sections grouped by directory
+    for (const [dir, components] of Object.entries(componentsByDir)) {
+        if (dir && dir !== '.') {
+            lines.push(`## ${dir}`)
+            lines.push('')
+        }
+
+        for (const comp of components) {
+            lines.push(`### ${comp.tagName}`)
+            lines.push('')
+
+            // Add parse error disclaimer if component failed to parse
+            if (comp.parseError) {
+                lines.push('> ⚠️ **Documentation incomplete**: This component could not be fully analyzed due to import resolution issues.')
+                lines.push('> Props, events, and slots information may be missing or incomplete.')
+                lines.push('')
+            }
+
+            if (comp.description) {
+                lines.push(comp.description)
+                lines.push('')
+            }
+
+            // Props
+            if (comp.props && comp.props.length > 0) {
+                lines.push('#### Props')
+                lines.push('')
+                lines.push('```typescript')
+                lines.push('interface Props {')
+
+                comp.props.forEach((prop: any) => {
+                    const type = formatTypeForInterface(prop.type, typeResolver)
+                    const required = prop.required ? '' : '?'
+
+                    const commentParts: string[] = []
+                    const cleanedDescription = sanitizeInlineComment(prop.description)
+                    if (cleanedDescription) {
+                        commentParts.push(cleanedDescription)
+                    }
+                    if (prop.defaultValue?.value) {
+                        commentParts.push(`default: ${String(prop.defaultValue.value)}`)
+                    }
+
+                    const comment = commentParts.length > 0 ? ` // ${commentParts.join(', ')}` : ''
+
+                    lines.push(`  ${prop.name}${required}: ${type}${comment}`)
+                })
+
+                lines.push('}')
+                lines.push('```')
+                lines.push('')
+            }
+
+            // Events
+            if (comp.events && comp.events.length > 0) {
+                lines.push('#### Events')
+                lines.push('')
+                lines.push('```typescript')
+                lines.push('interface Events {')
+
+                comp.events.forEach((event: any) => {
+                    const payload = event.type ? formatTypeForInterface(event.type, typeResolver) : 'any'
+                    const cleanedDescription = sanitizeInlineComment(event.description)
+                    const description = cleanedDescription ? ` // ${cleanedDescription}` : ''
+
+                    lines.push(`  '${event.name}': (payload: ${payload}) => void${description}`)
+                })
+
+                lines.push('}')
+                lines.push('```')
+                lines.push('')
+            }
+
+            // Slots
+            if (comp.slots && comp.slots.length > 0) {
+                const hasDefaultSlot = comp.slots.some((slot: any) => slot.name === 'default')
+                const namedSlots = comp.slots.filter((slot: any) => slot.name !== 'default')
+
+                lines.push('#### Slots')
+                lines.push('')
+
+                if (hasDefaultSlot && namedSlots.length === 0) {
+                    // Only has default slot
+                    lines.push('Supports slots')
+                }
+                else if (hasDefaultSlot && namedSlots.length > 0) {
+                    // Has default slot plus named slots
+                    lines.push('Supports slots with additional named slots:')
+                    lines.push('')
+                    namedSlots.forEach((slot: any) => {
+                        const description = slot.description ? ` - ${slot.description}` : ''
+                        const scopedProps = slot.scoped && slot.bindings ? ` (scoped: ${formatScopedPropsInline(slot.bindings, typeResolver)})` : ''
+                        lines.push(`- \`${slot.name}\`${description}${scopedProps}`)
+                    })
+                }
+                else if (namedSlots.length > 0) {
+                    // Only named slots, no default
+                    lines.push('Named slots:')
+                    lines.push('')
+                    namedSlots.forEach((slot: any) => {
+                        const description = slot.description ? ` - ${slot.description}` : ''
+                        const scopedProps = slot.scoped && slot.bindings ? ` (scoped: ${formatScopedPropsInline(slot.bindings, typeResolver)})` : ''
+                        lines.push(`- \`${slot.name}\`${description}${scopedProps}`)
+                    })
+                }
+
+                lines.push('')
+            }
+
+            // MDX examples
+            if (comp.stories && comp.stories.examples.length > 0) {
+                lines.push('#### Examples')
+                lines.push('')
+
+                comp.stories.examples.forEach((example) => {
+                    lines.push(`**${example.name}**`)
+                    lines.push('')
+                    lines.push('```vue')
+                    lines.push(example.code)
+                    lines.push('```')
+                    lines.push('')
+                })
+            }
+
+            lines.push('---')
+            lines.push('')
+        }
+    }
+
+    return lines.join('\n')
+}
+
+/**
+ * Generate a directory-based documentation set suitable for Claude Skills-style usage:
+ * - Root index at `${outDir}/index.md`
+ * - Per-component pages under `${outDir}/components/<original-dir?>/<TagName>.md`
+ * - Design tokens documentation embedded in SKILL.md
+ */
+export function generateDocsToDirectory(componentDocs: ComponentDoc[], typeResolver: TypeResolver, outDir: string, layerPath?: string): void {
+    // Ensure root directory exists
+    if (!existsSync(outDir)) {
+        mkdirSync(outDir, { recursive: true })
+    }
+
+    // Single Skill: tela-build
+    const skillDir = join(outDir, 'tela-build')
+    const supportingDir = join(skillDir, 'components')
+    if (!existsSync(supportingDir)) {
+        mkdirSync(supportingDir, { recursive: true })
+    }
+
+    // Group components by family (e.g., tela-dropdown-*) → tela-dropdown.md
+    const groups = new Map<string, ComponentDoc[]>()
+    for (const comp of componentDocs) {
+        const kebab = toKebabFromTag(comp.tagName)
+        const group = toGroupSlugFromKebab(kebab)
+        if (!groups.has(group))
+            groups.set(group, [])
+        groups.get(group)!.push(comp)
+    }
+
+    // Sort groups by name and components by tagName
+    const sortedGroups = Array.from(groups.entries()).sort((a, b) => a[0].localeCompare(b[0]))
+    sortedGroups.forEach(([_, list]) => list.sort((a, b) => a.tagName.localeCompare(b.tagName)))
+
+    const componentLinks: string[] = []
+
+    for (const [groupSlug, comps] of sortedGroups) {
+        const targetFile = join(supportingDir, `${groupSlug}.md`)
+        const content = generateGroupMarkdown(groupSlug, comps, typeResolver)
+        writeFileSync(targetFile, content, 'utf-8')
+        const title = toTitleFromGroupSlug(groupSlug)
+        componentLinks.push(`- [${title}](components/${groupSlug}.md)`)
+    }
+
+    // Read design-tokens.md content if it exists
+    let designTokensContent = ''
+    if (layerPath) {
+        const designTokensSourcePath = join(layerPath, 'docs', 'design-tokens.md')
+        if (existsSync(designTokensSourcePath)) {
+            designTokensContent = readFileSync(designTokensSourcePath, 'utf-8')
+        }
+    }
+
+    // Create SKILL.md describing Tela Build with links to supporting md
+    const skillDescription = buildTelaBuildSkillDescription()
+    const designTokensSection = designTokensContent
+        ? `\n\n---\n\n${designTokensContent}`
+        : ''
+    const body = dedent`
+# Tela Build
+
+This Skill provides structured documentation for the Tela Build component library (Vue 3 + Nuxt).
+Use it when building, refactoring, or using Tela components — props, events, slots, and examples are included where available.
+
+## Instructions
+
+- IMPORTANT: Before making ANY UI change or introducing NEW UI, ALWAYS consult this Tela Build components index first.
+- Prefer reusing existing Tela components and patterns. Only create new components when a clear gap exists.
+- When a new component is needed, align with existing naming, props, events, and patterns documented here.
+- Keep this documentation current when components are added or changed (update supporting files under \
+  \`components/\`).
+
+## Components Index
+
+${componentLinks.join('\n')}${designTokensSection}
+  `
+
+    const skillMd = wrapWithSkillFrontmatter({ name: 'tela-build', description: skillDescription }, body)
+    writeFileSync(join(skillDir, 'SKILL.md'), skillMd, 'utf-8')
+}
+
+function generateSingleComponentMarkdown(comp: ComponentDoc, typeResolver: TypeResolver, opts?: { includeTitle?: boolean }): string {
+    const lines: string[] = []
+    if (opts?.includeTitle !== false) {
+        lines.push(`# ${comp.tagName}`)
+        lines.push('')
+    }
+
+    if (comp.parseError) {
+        lines.push('> ⚠️ **Documentation incomplete**: This component could not be fully analyzed due to import resolution issues.')
+        lines.push('> Props, events, and slots information may be missing or incomplete.')
+        lines.push('')
+    }
+
+    if (comp.description) {
+        lines.push(comp.description)
+        lines.push('')
+    }
+
+    // Props
+    if (comp.props && comp.props.length > 0) {
+        lines.push('## Props')
+        lines.push('')
+        lines.push('```typescript')
+        lines.push('interface Props {')
+        comp.props.forEach((prop: any) => {
+            const type = formatTypeForInterface(prop.type, typeResolver)
+            const required = prop.required ? '' : '?'
+
+            const commentParts: string[] = []
+            const cleanedDescription = sanitizeInlineComment(prop.description)
+            if (cleanedDescription)
+                commentParts.push(cleanedDescription)
+            if (prop.defaultValue?.value)
+                commentParts.push(`default: ${String(prop.defaultValue.value)}`)
+            const comment = commentParts.length > 0 ? ` // ${commentParts.join(', ')}` : ''
+            lines.push(`  ${prop.name}${required}: ${type}${comment}`)
+        })
+        lines.push('}')
+        lines.push('```')
+        lines.push('')
+    }
+
+    // Events
+    if (comp.events && comp.events.length > 0) {
+        lines.push('## Events')
+        lines.push('')
+        lines.push('| Event | Type | Description |')
+        lines.push('|------:|:-----|:------------|')
+        comp.events.forEach((event: any) => {
+            const name = escapeTableCell(event.name)
+            const type = escapeTableCell(formatType(event.type))
+            const description = escapeTableCell(event.description || '')
+            lines.push(`| \`${name}\` | ${type} | ${description} |`)
+        })
+        lines.push('')
+    }
+
+    // Slots
+    if (comp.slots && comp.slots.length > 0) {
+        lines.push('## Slots')
+        lines.push('')
+        lines.push('| Slot | Scoped Props | Description |')
+        lines.push('|-----:|:-------------|:------------|')
+        comp.slots.forEach((slot: any) => {
+            const name = escapeTableCell(slot.name)
+            const scoped = escapeTableCell(formatScopedPropsInline(slot.bindings || [], typeResolver))
+            const description = escapeTableCell(slot.description || '')
+            lines.push(`| \`${name}\` | ${scoped || '—'} | ${description} |`)
+        })
+        lines.push('')
+    }
+
+    // Examples (from MDX)
+    if (comp.stories && comp.stories.examples && comp.stories.examples.length > 0) {
+        lines.push('## Examples')
+        lines.push('')
+        comp.stories.examples.forEach((ex: any) => {
+            lines.push(`### ${ex.name}`)
+            lines.push('')
+            lines.push('```vue')
+            lines.push(ex.code)
+            lines.push('```')
+            lines.push('')
+        })
+    }
+
+    return `${lines.join('\n')}\n`
+}
+
+function toKebabFromTag(tagName: string): string {
+    // Convert PascalCase or camelCase to kebab-case
+    return tagName
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9-]/g, '-')
+        .toLowerCase()
+        .replace(/--+/g, '-')
+        .replace(/^-+|-+$/g, '')
+}
+
+function wrapWithSkillFrontmatter(meta: { name: string; description: string; allowedTools?: string[] }, body: string): string {
+    const { name, description, allowedTools } = meta
+    const lines: string[] = []
+    lines.push('---')
+    lines.push(`name: ${sanitizeSkillName(name)}`)
+    lines.push(`description: ${sanitizeDescription(description)}`)
+    if (allowedTools && allowedTools.length > 0) {
+        lines.push(`allowed-tools: ${allowedTools.join(', ')}`)
+    }
+    lines.push('---')
+    lines.push('')
+    lines.push(body.trimStart())
+    if (!body.endsWith('\n'))
+        lines.push('')
+    return lines.join('\n')
+}
+
+function sanitizeSkillName(name: string): string {
+    // Lowercase + hyphens + digits only, max 64 chars
+    return name.toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 64).replace(/--+/g, '-')
+}
+
+function sanitizeDescription(desc: string): string {
+    const trimmed = desc.replace(/\s+/g, ' ').trim()
+    return trimmed.slice(0, 1024)
+}
+
+function buildTelaBuildSkillDescription(): string {
+    const base = 'Documentation and usage references for the Tela Build component library (Vue 3 + Nuxt). '
+        + 'Always consult this Tela Build index BEFORE making any UI changes or creating new UI. '
+        + 'Use when working on UI in this repository: ask for component props, events, slots, or examples. '
+        + 'Supporting files under components/ contain per-component details.'
+    return sanitizeDescription(base)
+}
+
+function toGroupSlugFromKebab(kebab: string): string {
+    const parts = kebab.split('-').filter(Boolean)
+    if (parts.length <= 2)
+        return kebab
+    // Prefer first two parts (e.g., tela-dropdown), otherwise fallback to entire kebab
+    return `${parts[0]}-${parts[1]}`
+}
+
+function toTitleFromGroupSlug(groupSlug: string): string {
+    return groupSlug
+        .split('-')
+        .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+        .join('')
+}
+
+function generateGroupMarkdown(groupSlug: string, comps: ComponentDoc[], typeResolver: TypeResolver): string {
+    const title = toTitleFromGroupSlug(groupSlug)
+    const sections = comps.map((comp) => {
+        const section = generateSingleComponentMarkdown(comp, typeResolver, { includeTitle: false }).trim()
+        return dedent`
+## ${comp.tagName}
+
+${section}
+    `
+    }).join('\n')
+
+    return dedent`
+# ${title}
+
+This page groups related components in the same family.
+
+${sections}
+  `
+}
+
+// Small utility to write readable multi-line strings in code
+function dedent(strings: TemplateStringsArray, ...values: any[]): string {
+    let result = ''
+    for (let i = 0; i < strings.length; i++) {
+        result += strings[i].replace(/\r/g, '')
+        if (i < values.length)
+            result += String(values[i])
+    }
+    result = result.replace(/^\n/, '')
+    const lines = result.split('\n')
+    // Determine minimum indentation (skip empty lines)
+    let minIndent: number | null = null
+    for (const line of lines) {
+        if (!line.trim())
+            continue
+        const m = line.match(/^\s+/)
+        const indent = m ? m[0].length : 0
+        if (minIndent === null || indent < minIndent)
+            minIndent = indent
+    }
+    if (minIndent && minIndent > 0) {
+        for (let i = 0; i < lines.length; i++) {
+            lines[i] = lines[i].startsWith(' '.repeat(minIndent)) ? lines[i].slice(minIndent) : lines[i]
+        }
+    }
+    return `${lines.join('\n').replace(/[ \t]+$/gm, '').trim()}\n`
+}
+
+function groupByDirectory(components: ComponentDoc[]): Record<string, ComponentDoc[]> {
+    const grouped: Record<string, ComponentDoc[]> = {}
+
+    components.forEach((comp) => {
+        const dir = comp.directory || 'root'
+        if (!grouped[dir]) {
+            grouped[dir] = []
+        }
+        grouped[dir].push(comp)
+    })
+
+    // Sort directories
+    const sortedGrouped: Record<string, ComponentDoc[]> = {}
+    Object.keys(grouped).sort().forEach((key) => {
+        sortedGrouped[key] = grouped[key]
+    })
+
+    return sortedGrouped
+}
+
+function sanitizeInlineComment(value?: string): string {
+    if (!value)
+        return ''
+
+    const withoutMarkdown = value.replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1')
+    const singleLine = withoutMarkdown.replace(/\s+/g, ' ').trim()
+    if (!singleLine)
+        return ''
+
+    const sentenceMatch = singleLine.match(/^(.*?\.)\s/)
+    if (sentenceMatch) {
+        return sentenceMatch[1].trim()
+    }
+    return singleLine
+}
+
+function formatType(type: any): string {
+    if (!type)
+        return '`any`'
+
+    if (typeof type === 'string')
+        return `\`${type}\``
+
+    if (type.name) {
+        if (type.name === 'union' && type.value) {
+            const values = type.value.map((v: any) => {
+                if (typeof v === 'string')
+                    return v
+                return v.name || v
+            }).join(' \\| ')
+            return `\`${values}\``
+        }
+        return `\`${type.name}\``
+    }
+
+    if (Array.isArray(type)) {
+        const types = type.map((t) => {
+            const formatted = formatType(t)
+            // Remove backticks if already present to avoid double backticks
+            return formatted.replace(/`/g, '')
+        }).join(' \\| ')
+        return `\`${types}\``
+    }
+
+    return '`any`'
+}
+
+function escapeTableCell(content: string): string {
+    // Escape pipes and newlines for markdown table cells
+    return content
+        .replace(/\|/g, '\\|')
+        .replace(/\n/g, ' ')
+        .replace(/\r/g, '')
+}
+
+function formatTypeForInterface(type: any, typeResolver: TypeResolver): string {
+    if (!type)
+        return 'any'
+
+    if (typeof type === 'string') {
+    // Try to resolve the type using our TypeScript resolver
+        const resolved = typeResolver.resolveType(type)
+        return resolved !== type ? resolved : type
+    }
+
+    if (type.name) {
+    // First try to resolve using our TypeScript resolver
+        const resolved = typeResolver.resolveType(type.name)
+        if (resolved !== type.name) {
+            return resolved
+        }
+
+        if (type.name === 'union' && type.value) {
+            const values = type.value.map((v: any) => {
+                if (typeof v === 'string')
+                    return `'${v}'`
+                if (v.name)
+                    return `'${v.name}'`
+                return v
+            }).join(' | ')
+            return values
+        }
+
+        // Handle common Vue prop types
+        if (type.name === 'Array')
+            return 'Array<any>'
+        if (type.name === 'Function')
+            return '(...args: any[]) => any'
+        if (type.name === 'Object')
+            return 'Record<string, any>'
+
+        // Use TypeScript resolver for unknown types
+        return typeResolver.resolveType(type.name)
+    }
+
+    if (Array.isArray(type)) {
+        const types = type.map(t => formatTypeForInterface(t, typeResolver)).join(' | ')
+        return types
+    }
+
+    return 'any'
+}
+
+function formatScopedPropsInline(bindings: any[], typeResolver: TypeResolver): string {
+    if (!bindings || bindings.length === 0)
+        return ''
+
+    return bindings.map(b => `${b.name}: ${formatTypeForInterface(b.type, typeResolver)}`).join(', ')
+}