skrypt-ai 0.5.0 → 0.6.0

package/dist/template/content/docs/llms.txt

@@ -0,0 +1,4588 @@
+# Skrypt
+
+> API documentation for Skrypt
+
+## Overview
+
+This project contains 130 documented API elements across 28 modules.
+
+## Quick Reference
+
+### index
+
+- `getAuthConfig`: function - Use this to synchronously retrieve the current authentication configuration from environment variabl
+- `getAuthConfigAsync`: function - Use this to retrieve the current user's authentication configuration in any CLI command action
+- `saveAuthConfig`: function - Use this to persist authentication configuration (API keys, endpoints, tokens) to a secure local con
+- `clearAuth`: function - Use this to completely sign out a user by wiping all stored authentication credentials — both from t
+- `getKeyStorageMethod`: function - Use this to detect where an API key is currently stored, so you can display storage status to users,
+- `checkPlan`: function - Use this to verify an API key's validity and retrieve the associated subscription plan details befor
+- `requirePro`: function - Use this to gate CLI commands behind a Pro subscription, automatically printing upgrade instructions
+- `autoFixExample`: function - Use this to automatically repair broken or invalid code examples by iteratively applying LLM-powered
+- `autoFixBatch`: function - Use this to automatically fix multiple broken code examples in a single batch operation, getting bac
+- `createTypeScriptValidator`: function - Use this to validate TypeScript code strings at runtime — perfect for checking LLM-generated code, u
+- `createPythonValidator`: function - Use this to validate Python code syntax before executing or storing it — catches syntax errors witho
+- `runImport`: function - Use this to automatically import and process a documentation directory based on its detected format 
+- `createLLMClient`: function - Use this to initialize a typed LLM client for a specific AI provider (OpenAI, Anthropic, etc.) with 
+- `generateDocumentation`: function - Use this to automatically generate documentation for a code element (function, class, method, etc.) 
+- `fixCodeSample`: function - Use this to automatically repair broken code samples by sending them to an LLM with the error contex
+- `PluginManager`: class - Use this to load, manage, and execute documentation plugins that transform source files into output 
+- `constructor`: method - Use this to initialize a plugin manager that coordinates documentation plugins across a source codeb
+- `loadPlugins`: method - Use this to initialize and load plugins into the `PluginManager` from a configuration file, enabling
+- `register`: method - Use this to manually register a plugin with the `PluginManager`, adding it to the active plugin list
+- `runHook`: method - Use this to execute a named hook across all registered plugins in sequence, passing data through eac
+- `onInit`: method - Use this to trigger the initialization lifecycle hook across all registered plugins in a `PluginMana
+- `onBeforeScan`: method - Use this to trigger all registered plugins' pre-scan lifecycle hooks before a documentation scan beg
+- `onAfterScan`: method - Use this to run all registered plugins' `onAfterScan` hooks against a list of scanned elements, allo
+- `onBeforeGenerate`: method - Use this to run all registered plugins' `onBeforeGenerate` hooks against a collection of elements be
+- `onAfterGenerate`: method - Use this to run all registered plugins' `onAfterGenerate` hooks against a collection of generated do
+- `onBeforeWrite`: method - Use this to run all registered plugins' `onBeforeWrite` hooks against your generated docs array, all
+- `onAfterWrite`: method - Use this to trigger all registered plugin hooks after documentation has been written to disk — ideal
+- `transformContent`: method - Use this to pipe file content through a chain of registered plugins, each of which can modify the co
+- `definePlugin`: function - Use this to define a typed plugin configuration object for the Skrypt plugin system with full type s
+- `scanDirectory`: function - Use this to recursively scan a directory (or single file) for all API elements — functions, classes,
+- `scanFile`: function - Use this to extract structured metadata from a single source file — functions, classes, types, and o
+
+### keychain
+
+- `keychainAvailable`: function - Use this to check whether the system keychain is available and functional before attempting to store
+- `keychainStore`: function - Use this to securely store an API key or secret in the operating system's native keychain (macOS Key
+- `keychainRetrieve`: function - Use this to securely retrieve a stored API key or password from the operating system's native keycha
+- `keychainDelete`: function - Use this to securely delete a stored password/credential from the system keychain
+- `getKeychainPlatformName`: function - Use this to display a human-readable name for the current platform's credential storage system in us
+
+### notices
+
+- `hasSeenNotice`: function - Use this to check whether a user has already acknowledged a specific notice, warning, or announcemen
+- `markNoticeSeen`: function - Use this to permanently record that a user has seen a specific notice, warning, or announcement — pr
+- `showSecurityNotice`: function - Use this to display a one-time security notice to users in the terminal — the message is shown only 
+
+### loader
+
+- `findConfigFile`: function - Use this to locate a Skrypt configuration file by searching a directory for any of the supported con
+- `loadConfig`: function - Use this to load and parse a YAML/JSON configuration file for the autodocs tool, with optional path 
+- `validateConfig`: function - Use this to validate a configuration object before using it, catching all errors upfront rather than
+- `checkApiKey`: function - Use this to verify whether a required API key environment variable is set for a given LLM provider b
+
+### generator
+
+- `generateForElement`: function - Use this to generate documentation for a single API element (function, class, method, etc.) using an
+- `generateForElements`: function - Use this to batch-generate documentation for multiple API elements in a single call, processing an a
+- `formatAsMarkdown`: function - Use this to convert an array of generated documentation objects into a formatted Markdown string, re
+
+### organizer
+
+- `organizeByTopic`: function - Use this to group a flat list of generated documentation objects into organized topic clusters — ide
+- `detectCrossReferences`: function - Use this to automatically discover relationships between documented elements — finding which functio
+- `getCrossRefsForElement`: function - Use this to filter a list of cross-references down to only those originating from a specific element
+- `buildNavigation`: function - Use this to convert a flat list of documentation topics into a hierarchical navigation structure sui
+- `generateSidebarConfig`: function - Use this to generate a sidebar navigation configuration from a list of documentation topics — compat
+- `mergeTopicConfig`: function - Use this to safely merge a partial user-provided topic configuration with a set of defaults, ensurin
+
+### writer
+
+- `writeLlmsTxt`: function - Use this to generate an `llms.txt` file for your project — a standardized index that helps LLMs (lik
+- `writeDocsToDirectory`: function - Use this to persist generated documentation to disk, organizing output files in a directory structur
+- `groupDocsByFile`: function - Use this to organize a flat list of generated documentation objects into groups by their source file
+- `writeDocsByTopic`: function - Use this to write generated documentation files to disk, organized into topic-based subdirectories —
+
+### pr-comments
+
+- `postPRComment`: function - Use this to automatically post documentation quality feedback as a review comment on a GitHub Pull R
+- `postInlineComments`: function - Use this to post inline review comments on specific lines of a pull request, flagging documentation 
+- `analyzePRForDocs`: function - Use this to scan a pull request for documentation issues — missing docstrings, undocumented paramete
+
+### confluence
+
+- `importConfluence`: function - Use this to convert a Confluence HTML space export into structured markdown pages, ready for use in 
+
+### detect
+
+- `detectFormat`: function - Use this to automatically identify which documentation framework a project uses, so you can process 
+- `isGitHubUrl`: function - Use this to validate whether a string is a GitHub repository or profile URL before processing it as 
+- `parseGitHubUrl`: function - Use this to extract the owner, repository name, branch/tag reference, and file path from a GitHub UR
+
+### docusaurus
+
+- `importDocusaurus`: function - Use this to convert a Docusaurus documentation directory into a structured, normalized `ImportResult
+
+### gitbook
+
+- `importGitBook`: function - Use this to convert a GitBook documentation directory into a structured import result, transforming 
+
+### github
+
+- `importFromGitHub`: function - Use this to pull documentation directly from a GitHub repository and import it into your system — no
+
+### markdown
+
+- `importMarkdown`: function - Use this to convert a directory of Markdown or MDX files into a structured import result, where fold
+
+### mintlify
+
+- `importMintlify`: function - Use this to convert a Mintlify documentation project into a standardized `ImportResult` format, read
+
+### notion
+
+- `importNotion`: function - Use this to convert a Notion export folder into structured, importable page data — stripping UUIDs, 
+
+### readme
+
+- `importReadme`: function - Use this to convert a ReadMe.io documentation export into a structured import result, transforming R
+
+### transform
+
+- `transformMintlifyCallouts`: function - Use this to convert Mintlify-flavored callout components (`<Note>`, `<Warning>`, `<Tip>`, `<Info>`, 
+- `transformDocusaurusAdmonitions`: function - Use this to convert Docusaurus admonition blocks (:::note, :::tip, :::danger, etc.) into a standardi
+- `transformGitBookHints`: function - Use this to convert GitBook hint/callout blocks into `<Callout>` JSX components during documentation
+- `transformReadmeCallouts`: function - Use this to convert ReadMe RDMD-style callout blocks (using emoji prefixes) into standard markdown o
+- `transformNotionCallouts`: function - Use this to convert Notion-style callout markup — both `<aside>` HTML blocks and `:::callout` fenced
+- `transformConfluenceCallouts`: function - Use this to convert Confluence structured macro callouts (`info`, `note`, `warning`, `tip`) into cle
+- `transformMintlifyTabs`: function - Use this to convert Mintlify-flavored `<Tabs>/<Tab>` JSX syntax into standard Markdown or a compatib
+- `transformDocusaurusTabs`: function - Use this to convert Docusaurus `<Tabs>` / `<TabItem>` JSX syntax into plain markdown or a renderable
+- `transformGitBookTabs`: function - Use this to convert GitBook tab syntax into clean markdown, stripping the `{% tabs %}` / `{% tab %}`
+- `transformReadmeCodeBlocks`: function - Use this to convert ReadMe.io's proprietary `[block:code]` syntax into standard `<CodeGroup>` compon
+- `transformGitBookSteps`: function - Use this to convert GitBook stepper/step syntax into clean markdown, stripping the `{% stepper %}`, 
+- `transformGitBookExpandable`: function - Use this to convert GitBook expandable blocks into Accordion components for rendering in documentati
+- `transformGitBookContentRef`: function - Use this to convert GitBook `content-ref` shortcode blocks into standard markdown links during docum
+- `transformGitBookEmbed`: function - Use this to strip GitBook `{% embed url="..." %}` syntax from content, replacing it with plain URLs 
+- `transformNotionToggles`: function - Use this to convert Notion-exported toggle blocks (HTML `<details>`/`<summary>` elements) into `<Acc
+- `transformConfluenceHtml`: function - Use this to convert Confluence HTML pages (including Atlassian Confluence macros) into clean, readab
+- `stripDocusaurusImports`: function - Use this to clean Docusaurus-specific theme import statements from MDX/markdown content before proce
+- `normalizeFrontmatter`: function - Use this to standardize frontmatter fields in markdown content to Skrypt format, optionally injectin
+- `rewriteImagePaths`: function - Use this to update image paths in documentation content after assets have been copied to a new locat
+- `stripNotionUUIDs`: function - Use this to clean up Notion export filenames by removing the 32-character hex UUID suffixes that Not
+- `getSortWeight`: function - Use this to determine the sort order of a documentation file by extracting its position weight from 
+
+### anthropic-client
+
+- `AnthropicClient`: class - Use this to send prompts to Anthropic's Claude models and receive structured completions — with auto
+- `constructor`: method - Use this to create an Anthropic-backed LLM client that handles retries and model configuration for s
+- `isConfigured`: method - Use this to verify that an `AnthropicClient` instance is ready to make API calls before attempting c
+- `complete`: method - Use this to send a conversation to Anthropic's Claude models and receive a completion response, hand
+
+### openai-client
+
+- `OpenAICompatibleClient`: class - Use this to connect to any OpenAI-compatible LLM provider — including OpenAI, DeepSeek, Ollama, Open
+- `constructor`: method - Use this to create an LLM client that connects to any OpenAI-compatible API provider (OpenAI, Azure,
+- `isConfigured`: method - Use this to verify that an `OpenAICompatibleClient` instance is ready to make API calls before attem
+- `complete`: method - Use this to send a chat completion request to any OpenAI-compatible API endpoint (OpenAI, Azure, Gro
+
+### content-type
+
+- `classifyElement`: function - Use this to determine what type of documentation an API element needs — whether it's best suited for
+- `classifyElements`: function - Use this to sort a mixed list of documentation elements into typed groups — API references, guides, 
+- `getRecommendedStructure`: function - Use this to automatically organize a mixed set of API elements into a recommended documentation stru
+- `getPromptForContentType`: function - Use this to get the appropriate documentation generation prompt string for a given content type — so
+
+### go
+
+- `GoScanner`: class - Use this to scan Go source files and extract API elements — functions, methods, structs, and interfa
+- `canHandle`: method - Use this to check whether a Go source file should be processed by the `GoScanner` — it returns `true
+- `scanFile`: method - Use this to extract API elements from a Go source file, returning all discovered functions, types, a
+
+### python
+
+- `PythonScanner`: class - Use this to scan Python source files and extract structured metadata (functions, classes, imports, e
+- `canHandle`: method - Use this to quickly check whether a file should be processed by the Python scanner before attempting
+- `scanFile`: method - Use this to scan a Python source file and extract structured metadata — functions, classes, imports,
+
+### python_parser
+
+- `get_docstring`: function - Use this to extract the docstring from any Python AST node (functions, classes, modules) when parsin
+- `get_type_annotation`: function - Use this to convert a Python AST type annotation node into its human-readable string representation 
+- `get_default_value`: function - Use this to extract a human-readable string representation of a Python function parameter's default 
+- `extract_parameters`: function - Use this to convert Python AST function arguments into a structured list of parameter metadata — ide
+- `build_signature`: function - Use this to reconstruct a human-readable function signature string from its parsed AST components — 
+- `extract_function`: function - Use this to extract structured metadata from a Python function or method AST node — including its na
+- `extract_class`: function - Use this to parse a Python class AST node into a structured list of dictionaries containing the clas
+- `scan_file`: function - Use this to extract all API elements from a Python source file — functions, classes, methods, import
+
+### rust
+
+- `RustScanner`: class - Use this to scan Rust source files and extract public API elements — functions, structs, enums, impl
+- `canHandle`: method - Use this to check whether a file path should be processed by the Rust scanner before attempting to s
+- `scanFile`: method - Use this to extract API elements from a Rust source file, parsing its contents into a structured res
+
+### typescript
+
+- `TypeScriptScanner`: class - Use this to scan TypeScript and JavaScript source files and extract API elements (functions, classes
+- `canHandle`: method - Use this to quickly determine whether a file path is a TypeScript/JavaScript source file that the sc
+- `scanFile`: method - Use this to extract API elements (functions, classes, methods, parameters) from a TypeScript or Java
+
+### files
+
+- `findMdxFiles`: function - Use this to collect all Markdown and MDX file paths from a directory tree — useful for documentation
+- `slugify`: function - Use this to convert any string into a clean, URL-safe slug — stripping special characters, spaces, a
+- `parseFrontmatter`: function - Use this to extract structured metadata and body content from Markdown files that use YAML frontmatt
+
+### validation
+
+- `validatePath`: function - Use this to safely resolve and validate file system paths before performing file operations — preven
+- `validateUrl`: function - Use this to validate and sanitize URL strings before making HTTP requests or storing user-provided U
+- `validateSlug`: function - Use this to validate that a string is a safe slug before using it in URLs, file paths, or database i
+- `sanitizeForShell`: function - Use this to validate and sanitize strings before passing them to shell commands, git operations, or 
+
+## API Details
+
+### getAuthConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+function getAuthConfig(): AuthConfig
+```
+
+Use this to synchronously retrieve the current authentication configuration from environment variables or a local auth file — without touching the keychain.
+
+This is the fast, synchronous option for reading auth state. It checks `SKRYPT_API_KEY` env var first, then falls back to a local auth file. When you need keychain access (e.g., in interactive CLI flows), use `getAuthConfigAsync()` instead.
+
+**Common use cases:**
+- Reading auth config at startup in a script or server process
+- Checking if a
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type AuthConfig = {
+  apiKey: string | undefined
+  email: string | undefined
+}
+
+// Simulate the auth file structure stored on disk
+type AuthFileMeta = {
+  apiKey?: string
+  email?: string
+}
+
+// Simulate reading a local auth file (e.g., ~/.skrypt/auth.json
+```
+
+### getAuthConfigAsync
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+async function getAuthConfigAsync(): Promise<AuthConfig>
+```
+
+Use this to retrieve the current user's authentication configuration in any CLI command action. It automatically resolves credentials by checking three sources in priority order: environment variable → system keychain → auth file on disk.
+
+This is the **preferred method** for reading auth in all command handlers — it handles all credential sources transparently so you don't need to check each one manually.
+
+## Returns
+
+| Condition | Result |
+|---|---|
+| `SKRYPT_API_KEY` env var is set | Returns 
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type AuthConfig = {
+  apiKey: string
+  email?: string
+}
+
+type AuthFileMeta = {
+  email?: string
+  apiKey?: string
+}
+
+// --- Simulated dependencies (stand-ins for fs, keychain, etc.) ---
+
+const mockAuthFile: AuthFileMeta = {
+  email: 'jane@example.com',
+  
+```
+
+### saveAuthConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+async function saveAuthConfig(config: AuthConfig): Promise<void>
+```
+
+Use this to persist authentication configuration (API keys, endpoints, tokens) to a secure local config directory, with automatic keychain integration when available.
+
+This function:
+- Creates the config directory with restricted permissions (`0o700`) if it doesn't exist
+- Attempts to store the API key in the system keychain for added security
+- Falls back to writing credentials to a local config file if keychain storage is unavailable
+
+## Parameters
+
+| Name | Type | Required | Description |
+|--
+
+**Example:**
+```typescript
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline types ---
+interface AuthConfig {
+  apiKey?: string
+  endpoint?: string
+  token?: string
+}
+
+// --- Inline config path constants ---
+const CONFIG_D
+```
+
+### clearAuth
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+async function clearAuth(): Promise<void>
+```
+
+Use this to completely sign out a user by wiping all stored authentication credentials — both from the system keychain and any local auth config file.
+
+This is the "logout" operation. It removes credentials from two places:
+1. **System keychain** (macOS Keychain, Linux Secret Service, Windows Credential Manager)
+2. **Local auth file** on disk (typically `~/.config/yourapp/auth.json` or similar)
+
+After calling this, any subsequent authenticated requests will fail until the user logs in again.
+
+##
+
+**Example:**
+```typescript
+import { existsSync, unlinkSync, writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline simulation of keychain operations ---
+const inMemoryKeychain: Record<string, string> = {
+  'myapp/auth': 'super-secret-token-abc123'
+}
+
+async function keychai
+```
+
+### getKeyStorageMethod
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+async function getKeyStorageMethod(): Promise<'keychain' | 'file' | 'env' | 'none'>
+```
+
+Use this to detect where an API key is currently stored, so you can display storage status to users, conditionally prompt for re-authentication, or branch logic based on the active credential source.
+
+Returns a promise resolving to one of four string literals indicating the active storage method — checked in priority order: environment variable → keychain → file → none.
+
+### Return Values
+
+| Value | Description |
+|---|---|
+| `'env'` | API key found in `SKRYPT_API_KEY` environment variable |
+| `'
+
+**Example:**
+```typescript
+// Simulate the storage detection logic inline
+// (mirrors the real priority order: env → keychain → file → none)
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+type KeyStorageMethod = 'keychain' | 'file' | 'env' | 'none'
+
+// Simulate keychain lookup (real
+```
+
+### checkPlan
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+async function checkPlan(apiKey: string): Promise<PlanCheckResponse>
+```
+
+Use this to verify an API key's validity and retrieve the associated subscription plan details before making API calls or gating features by plan tier.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `apiKey` | `string` | Yes | The Bearer token used to authenticate against the plan endpoint |
+
+## Returns
+
+Returns a `Promise<PlanCheckResponse>` that resolves with the plan details for the provided API key.
+
+| Scenario | Result |
+|----------|-----
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type PlanCheckResponse = {
+  plan: 'free' | 'pro' | 'enterprise'
+  valid: boolean
+  requestsPerMonth: number
+  expiresAt: string | null
+  error?: string
+}
+
+// Simulated implementation matching the real function's behavior
+async function checkPlan(apiKey: 
+```
+
+### requirePro
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+async function requirePro(commandName: string): Promise<boolean>
+```
+
+Use this to gate CLI commands behind a Pro subscription, automatically printing upgrade instructions and returning `false` if the user isn't authenticated or doesn't have a Pro plan.
+
+Call `requirePro` at the top of any command handler that requires a paid plan. It handles all messaging to the user — you just check the return value and exit early if it's `false`.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `commandName` | `string` | ✅ | The
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type Plan = 'free' | 'pro' | 'enterprise'
+
+interface AuthConfig {
+  apiKey: string | null
+  plan: Plan
+  email: string
+}
+
+// Simulate stored auth config (in real usage, read from disk/keychain)
+const mockAuthStore: AuthConfig = {
+  apiKey: process.env.SKR
+```
+
+### keychainAvailable
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/keychain.ts
+
+```
+async function keychainAvailable(): Promise<boolean>
+```
+
+Use this to check whether the system keychain is available and functional before attempting to store or retrieve secrets. This prevents runtime errors in environments where keychain access is unavailable (e.g., headless CI servers, containers, or systems without a keyring daemon).
+
+Returns `true` if the keychain is accessible and operational, `false` if the keyring module cannot be loaded or the keychain is non-functional.
+
+### Parameters
+
+This function takes no parameters.
+
+### Returns
+
+| Value
+
+**Example:**
+```typescript
+// Inline types and simulate the keychainAvailable behavior
+// (self-contained — no external imports required)
+
+// Simulated keyring entry for demonstration
+class MockEntry {
+  constructor(private service: string, private account: string) {}
+  async getPassword(): Promise<string | null> {
+    // Sim
+```
+
+### keychainStore
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/keychain.ts
+
+```
+async function keychainStore(key: string): Promise<boolean>
+```
+
+Use this to securely store an API key or secret in the operating system's native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
+
+This is the recommended way to persist sensitive credentials locally without storing them in plaintext config files or environment variables.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✅ | The secret value (e.g. API key, token, password) to store in the system k
+
+**Example:**
+```typescript
+// Inline types to simulate keychainStore behavior
+// (self-contained — no external imports required)
+
+// Simulated in-memory keychain store for demonstration
+const mockKeychain: Record<string, string> = {}
+
+const SERVICE_NAME = 'my-app'
+const ACCOUNT_NAME = 'default'
+
+// Simulated keychainStore imp
+```
+
+### keychainRetrieve
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/keychain.ts
+
+```
+async function keychainRetrieve(): Promise<string | null>
+```
+
+Use this to securely retrieve a stored API key or password from the operating system's native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
+
+Returns `null` if the keyring is unavailable or no entry exists, making it safe to use as a fallback check before prompting the user for credentials.
+
+## Parameters
+
+_None_ — retrieves from a fixed service/account name configured internally.
+
+## Returns
+
+| Value | When |
+|---|---|
+| `Promise<string>` | A stored password/API
+
+**Example:**
+```typescript
+// Simulated keychain store (mimics OS keychain behavior)
+const keychainStore: Record<string, string> = {}
+
+// Inline types
+type KeychainEntry = {
+  getPassword: () => string | null
+}
+
+type KeyringModule = {
+  Entry: new (service: string, account: string) => KeychainEntry
+}
+
+// Constants (as used in
+```
+
+### keychainDelete
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/keychain.ts
+
+```
+async function keychainDelete(): Promise<boolean>
+```
+
+Use this to securely delete a stored password/credential from the system keychain. This is useful for logout flows, credential rotation, or cleaning up stored secrets from the OS-level secure storage.
+
+**Returns**
+| Value | When |
+|-------|------|
+| `true` | The credential was found and successfully deleted from the keychain |
+| `false` | The keyring module could not be loaded, or deletion failed |
+
+> **Note:** This function targets a fixed service/account name pair internally (`SERVICE_NAME` / 
+
+**Example:**
+```typescript
+// Simulated keychain store (mimics OS keychain behavior)
+const keychainStore: Record<string, string> = {
+  "MyApp:default-user": "super-secret-token-abc123"
+}
+
+// Inline types
+type KeychainEntry = {
+  service: string
+  account: string
+  deletePassword: () => void
+}
+
+// Simulate the keychain delete 
+```
+
+### getKeychainPlatformName
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/keychain.ts
+
+```
+function getKeychainPlatformName(): string
+```
+
+Use this to display a human-readable name for the current platform's credential storage system in user-facing messages, logs, or CLI output.
+
+Returns the appropriate keychain/credential manager name based on the operating system:
+
+| Platform | Returns |
+|----------|---------|
+| macOS (`darwin`) | `"macOS Keychain"` |
+| Windows (`win32`) | `"Windows Credential Manager"` |
+| Linux / other | `"system keyring (libsecret)"` |
+
+### Parameters
+
+None.
+
+### Returns
+
+| Type | Description |
+|------|-------
+
+**Example:**
+```typescript
+// Inline implementation of getKeychainPlatformName
+function getKeychainPlatformName(): string {
+  switch (process.platform) {
+    case 'darwin':  return 'macOS Keychain'
+    case 'win32':   return 'Windows Credential Manager'
+    default:        return 'system keyring (libsecret)'
+  }
+}
+
+// Example
+```
+
+### hasSeenNotice
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/notices.ts
+
+```
+function hasSeenNotice(id: string): boolean
+```
+
+Use this to check whether a user has already acknowledged a specific notice, warning, or announcement — preventing repeat displays of one-time messages.
+
+This is ideal for CLI tools or apps that show onboarding tips, deprecation warnings, or changelog notices only once per user.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier for the notice to check (e.g. `"welcome-v2"`, `"deprecation-warning"`) |
+
+## Ret
+
+**Example:**
+```typescript
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline implementation (self-contained, no external imports) ---
+
+const CONFIG_DIR = join(homedir(), '.config', 'myapp')
+const NOTICES_FILE = join(CONFIG_DIR, 'noti
+```
+
+### markNoticeSeen
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/notices.ts
+
+```
+function markNoticeSeen(id: string): void
+```
+
+Use this to permanently record that a user has seen a specific notice, warning, or announcement — preventing it from being shown again in future sessions.
+
+The notice state is persisted to disk, so once marked as seen, the record survives process restarts. Each notice is stored with the exact timestamp it was acknowledged.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier for the notice (e.g. `"welcome-v2"
+
+**Example:**
+```typescript
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline implementation (do not import from autodocs) ---
+
+const NOTICES_DIR = join(homedir(), '.autodocs')
+const NOTICES_FILE = join(NOTICES_DIR, 'notices.json')
+
+t
+```
+
+### showSecurityNotice
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/notices.ts
+
+```
+function showSecurityNotice(): void
+```
+
+Use this to display a one-time security notice to users in the terminal — the message is shown only once per machine and silently skipped on all subsequent runs.
+
+This is ideal for CLI tools that need to surface important security information (e.g., API key handling, data privacy warnings) without repeatedly interrupting the user's workflow.
+
+### Parameters
+
+This function takes no parameters.
+
+### Returns
+
+| Condition | Result |
+|---|---|
+| First time called on this machine | Prints a formatted 
+
+**Example:**
+```typescript
+import * as fs from 'fs'
+import * as path from 'path'
+import * as os from 'os'
+
+// --- Inline implementation (mirrors autodocs internals) ---
+
+const NOTICES_DIR = path.join(os.homedir(), '.autodocs')
+const NOTICES_FILE = path.join(NOTICES_DIR, 'notices.json')
+
+type NoticesState = {
+  seen: Record<st
+```
+
+### autoFixExample
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/autofix/index.ts
+
+```
+async function autoFixExample(example: CodeExample, client: LLMClient, options: AutoFixOptions = {}): Promise<FixResult>
+```
+
+Use this to automatically repair broken or invalid code examples by iteratively applying LLM-powered fixes until the code compiles and runs correctly.
+
+This function takes a code example that may contain errors, submits it to an LLM client for analysis and correction, and retries up to a configurable number of times — returning the fixed code along with metadata about what changed and how many attempts it took.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|--
+
+**Example:**
+```typescript
+// ---- Inline type definitions (no external imports needed) ----
+
+type CodeExample = {
+  code: string
+  language: string
+  errorMessage?: string
+}
+
+type AutoFixOptions = {
+  maxIterations?: number
+  verbose?: boolean
+}
+
+type FixResult = {
+  success: boolean
+  fixedCode: string | null
+  iterations: 
+```
+
+### autoFixBatch
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/autofix/index.ts
+
+```
+async function autoFixBatch(examples: CodeExample[], client: LLMClient, options: AutoFixOptions = {}): Promise<Map<number, FixResult>>
+```
+
+Use this to automatically fix multiple broken code examples in a single batch operation, getting back a map of results indexed by position.
+
+This is the batch version of `autoFix` — ideal when you have a collection of code snippets that need validation and repair, such as processing documentation examples, test fixtures, or user-submitted code samples all at once.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `examples` | `CodeExample[]` | ✅ 
+
+**Example:**
+```typescript
+// ─── Inline types (do NOT import from autodocs) ───────────────────────────────
+
+type CodeExample = {
+  code: string
+  language?: string
+  filename?: string
+}
+
+type FixResult = {
+  success: boolean
+  fixedCode?: string
+  error?: string
+  attempts?: number
+}
+
+type AutoFixOptions = {
+  maxAttempts?:
+```
+
+### createTypeScriptValidator
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/autofix/index.ts
+
+```
+function createTypeScriptValidator(): (code: string) => Promise<ValidationResult>
+```
+
+Use this to validate TypeScript code strings at runtime — perfect for checking LLM-generated code, user-submitted snippets, or dynamically built TypeScript before execution.
+
+Returns a validator function you call with any TypeScript code string. The validator uses the TypeScript compiler (`tsc`) under the hood to catch type errors, syntax issues, and compilation failures.
+
+## Parameters
+
+This factory function takes no parameters.
+
+## Returns
+
+| Value | Type | Description |
+|---|---|---|
+| `valid
+
+**Example:**
+```typescript
+import { transpileModule, type TranspileOptions } from 'typescript'
+
+// --- Inline types (mirrors the real ValidationResult) ---
+interface ValidationResult {
+  valid: boolean
+  errors: string[]
+}
+
+// --- Self-contained implementation mirroring the real function ---
+function createTypeScriptValidator
+```
+
+### createPythonValidator
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/autofix/index.ts
+
+```
+function createPythonValidator(): (code: string) => Promise<ValidationResult>
+```
+
+Use this to validate Python code syntax before executing or storing it — catches syntax errors without running the code.
+
+`createPythonValidator` returns a reusable validator function that writes code to a temporary file and checks it with `python3 -m py_compile`. Requires `python3` to be available in your system `PATH`.
+
+## Parameters
+
+The factory function takes no parameters. The returned validator accepts:
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `c
+
+**Example:**
+```typescript
+import { spawnSync } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// Inline the ValidationResult type
+type ValidationError = {
+  message: string
+  line?: number
+}
+
+type ValidationResult = {
+  valid: boolean
+  errors: Val
+```
+
+### findConfigFile
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/config/loader.ts
+
+```
+function findConfigFile(dir: string): string | null
+```
+
+Use this to locate a Skrypt configuration file by searching a directory for any of the supported config filenames (`.skrypt.yaml`, `.skrypt.yml`, `skrypt.yaml`, `skrypt.yml`).
+
+This is useful when you need to resolve the config file path before loading it — for example, when bootstrapping a CLI tool or build process that needs to find project-level configuration starting from a given directory.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `
+
+**Example:**
+```typescript
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+// Inline the supported config filenames (mirrors the real implementation)
+const CONFIG_FILENAMES = ['.skrypt.yaml', '.skrypt.yml', 'skrypt.yaml', 'skrypt.yml']
+
+// Self-contained implementation of findConfigFile
+function findConfigFile(di
+```
+
+### loadConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/config/loader.ts
+
+```
+function loadConfig(configPath?: string): Config
+```
+
+Use this to load and parse a YAML/JSON configuration file for the autodocs tool, with optional path override. When no path is provided, it searches for a config file in default locations (e.g., `autodocs.config.yml` in the current directory). When a path is provided, it loads that specific file — throwing immediately if it doesn't exist.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `configPath` | `string` | No | Explicit path to a config fi
+
+**Example:**
+```typescript
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+// ── Inline types (mirrors autodocs internals) ────────────────────────────────
+type LLMProvider = 'openai' | 'anthropic' | 'gemini'
+
+interface Config {
+  provider: LLMProvider
+  model: string
+  outputDir: string
+  include: 
+```
+
+### validateConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/config/loader.ts
+
+```
+function validateConfig(config: Config): string[]
+```
+
+Use this to validate a configuration object before using it, catching all errors upfront rather than failing at runtime.
+
+`validateConfig` checks a `Config` object against known rules (such as supported version numbers) and returns a list of human-readable error messages. An empty array means the config is valid.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `Config` | Yes | The configuration object to validate. Must include at min
+
+**Example:**
+```typescript
+// Inline type definition (mirrors the real Config shape)
+type LLMProvider = 'openai' | 'anthropic' | 'ollama'
+
+type Config = {
+  version: number
+  provider?: LLMProvider
+  model?: string
+  license?: string
+  [key: string]: unknown
+}
+
+// Inline implementation matching the real validateConfig logic
+f
+```
+
+### checkApiKey
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/config/loader.ts
+
+```
+function checkApiKey(provider: LLMProvider): { ok: boolean; envKey: string | null }
+```
+
+Use this to verify whether a required API key environment variable is set for a given LLM provider before making requests.
+
+Returns `{ ok: true }` for providers that don't require an API key (e.g., Ollama), and checks the appropriate environment variable for cloud providers (e.g., OpenAI, Anthropic). This is useful for fail-fast validation at startup or before executing LLM calls.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `provider` | `L
+
+**Example:**
+```typescript
+// Inline the types and dependencies — no external imports needed
+type LLMProvider = 'openai' | 'anthropic' | 'ollama' | 'gemini'
+
+const PROVIDER_ENV_KEYS: Record<LLMProvider, string | null> = {
+  openai: 'OPENAI_API_KEY',
+  anthropic: 'ANTHROPIC_API_KEY',
+  ollama: null, // No API key required
+  ge
+```
+
+### generateForElement
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/generator.ts
+
+```
+async function generateForElement(element: APIElement, client: LLMClient, options: GenerationOptions, onProgress?: (progress: GenerationProgress) => void): Promise<GeneratedDoc>
+```
+
+Use this to generate documentation for a single API element (function, class, method, etc.) using an LLM client, with optional real-time progress tracking.
+
+This is the core documentation generation function — pass it a parsed API element and an LLM client, and it returns structured documentation ready for output. Use `onProgress` to stream status updates to a UI or CLI spinner.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `element` | `APIEl
+
+**Example:**
+```typescript
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'method' | 'interface' | 'type'
+  signature: string
+  docstring?: string
+  filePath: string
+  lineNumber: number
+}
+
+type LLMClient = {
+  model: string
+  
+```
+
+### generateForElements
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/generator.ts
+
+```
+async function generateForElements(elements: APIElement[], client: LLMClient, options: GenerationOptions): Promise<GeneratedDoc[]>
+```
+
+Use this to batch-generate documentation for multiple API elements in a single call, processing an array of functions, classes, or methods through an LLM client with shared generation options.
+
+This is the primary entry point for bulk documentation generation — pass in your scanned API elements, an LLM client, and configuration options to receive an array of generated docs ready for output.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `eleme
+
+**Example:**
+```typescript
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'method' | 'interface'
+  signature: string
+  docstring?: string
+  sourceContext?: string
+  filePath: string
+}
+
+type GeneratedDoc = {
+  elementName: strin
+```
+
+### formatAsMarkdown
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/generator.ts
+
+```
+function formatAsMarkdown(docs: GeneratedDoc[], title: string): string
+```
+
+Use this to convert an array of generated documentation objects into a formatted Markdown string, ready to write to a `.md` file or display in a docs portal.
+
+Takes structured doc data (functions, classes, methods) and a page title, and returns a complete Markdown document with sections organized by element type.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | Array of generated documentation objects, each contai
+
+**Example:**
+```typescript
+// --- Inline types (mirrors autodocs internals) ---
+type ElementKind = 'function' | 'class' | 'method'
+
+interface APIElement {
+  name: string
+  kind: ElementKind
+  signature?: string
+}
+
+interface GeneratedDoc {
+  element: APIElement
+  documentation: string
+}
+
+// --- Inline implementation of formatA
+```
+
+### organizeByTopic
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function organizeByTopic(docs: GeneratedDoc[], config: TopicConfig = DEFAULT_TOPIC_CONFIG): Topic[]
+```
+
+Use this to group a flat list of generated documentation objects into organized topic clusters — ideal for building navigation menus, documentation sites, or categorized API references.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | Yes | Array of generated documentation objects to organize. Each doc must include at least a `topic` or category field used for grouping. |
+| `config` | `TopicConfig` | No | Configuratio
+
+**Example:**
+```typescript
+// ── Inline types (do NOT import from autodocs) ──────────────────────────────
+
+type GeneratedDoc = {
+  id: string
+  title: string
+  topic: string          // primary grouping key
+  content: string
+  slug: string
+}
+
+type Topic = {
+  name: string
+  slug: string
+  docs: GeneratedDoc[]
+}
+
+type TopicCo
+```
+
+### detectCrossReferences
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function detectCrossReferences(docs: GeneratedDoc[]): CrossReference[]
+```
+
+Use this to automatically discover relationships between documented elements — finding which functions, classes, or types reference each other by name across your documentation set.
+
+Given a list of generated documentation objects, it scans each element's content and metadata to detect when one element mentions another by name, returning a list of cross-reference links you can use to build navigation, "See Also" sections, or dependency graphs.
+
+## Parameters
+
+| Name | Type | Required | Descripti
+
+**Example:**
+```typescript
+// ─── Inline types (do not import from autodocs) ───────────────────────────────
+
+type ElementKind = 'function' | 'class' | 'interface' | 'type'
+
+interface DocElement {
+  name: string
+  kind: ElementKind
+  description: string
+  params?: { name: string; type: string }[]
+  returns?: string
+}
+
+interfa
+```
+
+### getCrossRefsForElement
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function getCrossRefsForElement(elementName: string, allRefs: CrossReference[]): CrossReference[]
+```
+
+Use this to filter a list of cross-references down to only those originating from a specific element — useful when building documentation graphs, dependency trees, or navigation links for a given function, class, or module.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elementName` | `string` | ✅ | The name of the element to find cross-references for (matched against `fromElement`) |
+| `allRefs` | `CrossReference[]` | ✅ | The full list of cr
+
+**Example:**
+```typescript
+// Inline the CrossReference type (no external imports needed)
+type CrossReference = {
+  fromElement: string
+  toElement: string
+  type?: string
+  description?: string
+}
+
+// Inline the function implementation
+function getCrossRefsForElement(
+  elementName: string,
+  allRefs: CrossReference[]
+): Cros
+```
+
+### buildNavigation
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function buildNavigation(topics: Topic[]): NavigationItem[]
+```
+
+Use this to convert a flat list of documentation topics into a hierarchical navigation structure suitable for rendering sidebars, menus, or breadcrumbs.
+
+Each topic becomes a top-level navigation item with its documented elements nested as children, with auto-generated URL paths.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topics` | `Topic[]` | ✅ | Array of topics, each containing a name, id, and list of associated docs |
+
+## Returns
+
+Retu
+
+**Example:**
+```typescript
+// --- Inline types (mirrors the real library's shape) ---
+type DocElement = {
+  name: string;
+  description?: string;
+};
+
+type Doc = {
+  element: DocElement;
+};
+
+type Topic = {
+  id: string;
+  name: string;
+  docs: Doc[];
+};
+
+type NavigationItem = {
+  title: string;
+  path: string;
+  children?: Nav
+```
+
+### generateSidebarConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function generateSidebarConfig(topics: Topic[]): object
+```
+
+Use this to generate a sidebar navigation configuration from a list of documentation topics — compatible with multiple documentation platforms (Mintlify, Docusaurus, etc.).
+
+Given an array of topics (each with an ID, name, and list of docs), this function produces a structured `navigation` object where each topic becomes a group with slugified page paths.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topics` | `Topic[]` | ✅ | Array of topic
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+type DocElement = { name: string }
+type GeneratedDoc = { element: DocElement }
+type Topic = {
+  id: string
+  name: string
+  docs: GeneratedDoc[]
+}
+
+// ── Inline slugify utility ────────────────────────────────────────────
+```
+
+### mergeTopicConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function mergeTopicConfig(userConfig: Partial<TopicConfig>, defaults: TopicConfig = DEFAULT_TOPIC_CONFIG): TopicConfig
+```
+
+Use this to safely merge a partial user-provided topic configuration with a set of defaults, ensuring all required fields are always present in the final config.
+
+This is useful when users supply only a subset of configuration options (e.g., overriding a few topics) and you need a complete, valid `TopicConfig` to work with — without manually checking for missing fields.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `userConfig` | `Partial<To
+
+**Example:**
+```typescript
+// Inline types (do not import from autodocs)
+type Topic = {
+  label: string
+  description?: string
+  order?: number
+}
+
+type TopicConfig = {
+  topics: Record<string, Topic>
+}
+
+// Simulated DEFAULT_TOPIC_CONFIG
+const DEFAULT_TOPIC_CONFIG: TopicConfig = {
+  topics: {
+    guides: { label: 'Guides', des
+```
+
+### writeLlmsTxt
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/writer.ts
+
+```
+async function writeLlmsTxt(docs: GeneratedDoc[], outputDir: string, options: { projectName?: string; description?: string } = {}): Promise<void>
+```
+
+Use this to generate an `llms.txt` file for your project — a standardized index that helps LLMs (like ChatGPT, Claude, etc.) discover and understand your API documentation. Follows the [llmstxt.org](https://llmstxt.org) convention for Answer Engine Optimization (AEO).
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ Yes | Array of generated documentation objects to index |
+| `outputDir` | `string` | ✅ Yes | Director
+
+**Example:**
+```typescript
+import { mkdir, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// --- Inline types (mirrors the real GeneratedDoc shape) ---
+type GeneratedDoc = {
+  title: string
+  description?: string
+  outputPath: string
+  content: string
+  slug?: string
+}
+
+// --- Inline i
+```
+
+### writeDocsToDirectory
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/writer.ts
+
+```
+async function writeDocsToDirectory(results: FileGenerationResult[], outputDir: string, sourceDir: string): Promise<{ filesWritten: number; totalDocs: number }>
+```
+
+Use this to persist generated documentation to disk, organizing output files in a directory structure that mirrors your source code layout.
+
+After generating docs for your codebase, `writeDocsToDirectory` takes the in-memory results and writes each file's documentation to the corresponding path under `outputDir`, preserving the relative structure from `sourceDir`. It returns a summary of how many files were written and how many total doc entries were produced.
+
+### Parameters
+
+| Name | Type | Re
+
+**Example:**
+```typescript
+import { mkdir, writeFile } from 'fs/promises'
+import { dirname, join, relative, resolve, basename } from 'path'
+import { existsSync } from 'fs'
+
+// ── Inline types (mirrors autodocs internals) ────────────────────────────────
+
+interface GeneratedDoc {
+  name: string
+  kind: 'function' | 'class' | '
+```
+
+### groupDocsByFile
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/writer.ts
+
+```
+function groupDocsByFile(docs: GeneratedDoc[]): FileGenerationResult[]
+```
+
+Use this to organize a flat list of generated documentation objects into groups by their source file, making it easy to write one output file per source file.
+
+This is the key step between generating individual doc entries and writing them to disk — it collapses a flat array into a structure where each entry represents a single source file and all the docs that belong to it.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDo
+
+**Example:**
+```typescript
+// ─── Inline types (do not import from autodocs) ───────────────────────────────
+
+interface CodeElement {
+  name: string
+  filePath: string
+  kind: 'function' | 'class' | 'interface' | 'type'
+  signature: string
+}
+
+interface GeneratedDoc {
+  element: CodeElement
+  markdown: string
+  generatedAt: Da
+```
+
+### writeDocsByTopic
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/writer.ts
+
+```
+async function writeDocsByTopic(docs: GeneratedDoc[], outputDir: string): Promise<{ filesWritten: number; totalDocs: number; topics: Topic[] }>
+```
+
+Use this to write generated documentation files to disk, organized into topic-based subdirectories — ideal for creating structured doc sites where related functions and classes are grouped together.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | Array of generated documentation objects, each containing content and metadata about a code element |
+| `outputDir` | `string` | ✅ | Root directory path where topic-orga
+
+**Example:**
+```typescript
+import { mkdir, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+// --- Inline types (mirrors autodocs internals) ---
+type GeneratedDoc = {
+  elementName: string
+  topic: string
+  content: string
+  filePath: string
+}
+
+type Topic = {
+  name: string
+  slug: string
+  docCount: number
+}
+
+// -
+```
+
+### postPRComment
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/github/pr-comments.ts
+
+```
+async function postPRComment(config: PRCommentConfig, issues: DocumentationIssue[]): Promise<CommentResult>
+```
+
+Use this to automatically post documentation quality feedback as a review comment on a GitHub Pull Request, summarizing all detected documentation issues in one structured comment.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | GitHub PR connection details including repo owner, repo name, PR number, and optional auth token |
+| `issues` | `DocumentationIssue[]` | Yes | Array of documentation issues to report
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+type PRCommentConfig = {
+  owner: string;
+  repo: string;
+  prNumber: number;
+  token?: string;
+};
+
+type DocumentationIssue = {
+  file: string;
+  line: number;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+};
+
+type CommentResult =
+
+```
+
+### postInlineComments
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/github/pr-comments.ts
+
+```
+async function postInlineComments(config: PRCommentConfig, issues: DocumentationIssue[]): Promise<CommentResult[]>
+```
+
+Use this to post inline review comments on specific lines of a pull request, flagging documentation issues directly in the GitHub code review interface.
+
+This function iterates over a list of documentation issues and creates inline PR comments at the exact file and line locations where problems were detected — ideal for automated documentation linting in CI pipelines.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` 
+
+**Example:**
+```typescript
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type PRCommentConfig = {
+  token: string;
+  owner: string;
+  repo: string;
+  pullNumber: number;
+  commitSha: string;
+};
+
+type DocumentationIssue = {
+  filePath: string;
+  line: number;
+  message: string;
+  severity: 'e
+```
+
+### analyzePRForDocs
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/github/pr-comments.ts
+
+```
+async function analyzePRForDocs(config: PRCommentConfig, _options: { checkExamples?: boolean } = {}): Promise<DocumentationIssue[]>
+```
+
+Use this to scan a pull request for documentation issues — missing docstrings, undocumented parameters, or incomplete return type descriptions — and get a structured list of problems to act on.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | GitHub PR connection details including repo owner, repo name, PR number, and auth token |
+| `_options` | `{ checkExamples?: boolean }` | No | Additional analysis options
+
+**Example:**
+```typescript
+// Inline types (do not import from autodocs)
+type PRCommentConfig = {
+  owner: string
+  repo: string
+  pullNumber: number
+  token?: string
+}
+
+type DocumentationIssue = {
+  file: string
+  line: number
+  severity: 'error' | 'warning' | 'info'
+  message: string
+  ruleId: string
+}
+
+// Simulated impleme
+```
+
+### importConfluence
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/confluence.ts
+
+```
+function importConfluence(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a Confluence HTML space export into structured markdown pages, ready for use in documentation pipelines.
+
+Given a directory containing a Confluence HTML export, `importConfluence` walks all HTML files, transforms Confluence-specific markup (callouts, tabs, code groups, etc.) into standard markdown, and returns a structured result with all imported pages and transformation statistics.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|----------
+
+### detectFormat
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/detect.ts
+
+```
+function detectFormat(dir: string): ImportFormat
+```
+
+Use this to automatically identify which documentation framework a project uses, so you can process or convert docs without requiring users to manually specify the format.
+
+Given a directory path, `detectFormat` inspects marker files (like `mint.json`, `docs.json`, `_sidebar.md`, etc.) in priority order and returns the first matching format. This is ideal for CLI tools, migration scripts, or any workflow that needs to handle multiple doc formats transparently.
+
+### Parameters
+
+| Name | Type | Re
+
+**Example:**
+```typescript
+import { existsSync, writeFileSync, mkdirSync, rmSync } from 'fs'
+import { join } from 'path'
+import * as os from 'os'
+
+// --- Inline types (from autodocs, not imported) ---
+type ImportFormat = 'mintlify' | 'docusaurus' | 'gitbook' | 'docsify' | 'generic'
+
+// --- Inline implementation of detectForma
+```
+
+### isGitHubUrl
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/detect.ts
+
+```
+function isGitHubUrl(input: string): boolean
+```
+
+Use this to validate whether a string is a GitHub repository or profile URL before processing it as a GitHub resource.
+
+Useful for input validation pipelines, routing logic, or distinguishing GitHub URLs from local file paths or other URL types.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | ✅ | The string to test against the GitHub URL pattern |
+
+## Returns
+
+| Value | Condition |
+|-------|-----------|
+| `true` | The strin
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function isGitHubUrl(input: string): boolean {
+  return /^https?:\/\/(www\.)?github\.com\//.test(input)
+}
+
+// --- Example usage ---
+
+const inputs = [
+  'https://github.com/microsoft/typescript',        // ✅ valid HTTPS
+  'http://github.com/facebo
+```
+
+### parseGitHubUrl
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/detect.ts
+
+```
+function parseGitHubUrl(url: string): { owner: string; repo: string; path: string; ref: string }
+```
+
+Use this to extract the owner, repository name, branch/tag reference, and file path from a GitHub URL — useful when building tools that fetch repo contents, generate documentation links, or construct GitHub API requests.
+
+Parses URLs in the format:
+`https://github.com/owner/repo/tree/branch/path/to/file`
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✅ | A full GitHub URL pointing to a repo, branch, or path |
+
+### Returns
+
+An object with t
+
+**Example:**
+```typescript
+// Inline implementation of parseGitHubUrl (do not import from autodocs)
+function parseGitHubUrl(url: string): { owner: string; repo: string; path: string; ref: string } {
+  const match = url.match(
+    /^https?:\/\/(www\.)?github\.com\/([^/]+)\/([^/]+)(?:\/tree\/([^/]+)(?:\/(.*))?)?/
+  )
+  if (!mat
+```
+
+### importDocusaurus
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/docusaurus.ts
+
+```
+function importDocusaurus(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a Docusaurus documentation directory into a structured, normalized `ImportResult` object — transforming admonitions, tabs, frontmatter, and image paths into a portable format ready for further processing or migration.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ Yes | Absolute or relative path to the root of the Docusaurus project (the directory containing `docusaurus.config.js` or `docusaurus.config
+
+### importGitBook
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/gitbook.ts
+
+```
+function importGitBook(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a GitBook documentation directory into a structured import result, transforming GitBook-specific syntax (hints, tabs, steps, expandables, content refs, embeds) into a normalized format ready for further processing or migration.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ Yes | Path to the root directory of the GitBook documentation |
+| `name` | `string` | ❌ No | Optional name to assign to the import 
+
+**Example:**
+```typescript
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join } from 'path'
+
+// ── Inline types (mirrors the real library's types) ──────────────────────────
+
+interface TransformStats {
+  callouts: number
+  tabs: number
+  codeGroups: number
+  steps: number
+  accordions: number
+  im
+```
+
+### importFromGitHub
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/github.ts
+
+```
+async function importFromGitHub(owner: string, repo: string, path: string, ref: string, options?: { format?: ImportFormat; name?: string }): Promise<ImportResult>
+```
+
+Use this to pull documentation directly from a GitHub repository and import it into your system — no manual downloading or cloning required.
+
+Given a repo owner, repository name, file path, and branch/tag/commit ref, this function fetches the content from GitHub and processes it as importable documentation.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `owner` | `string` | ✅ | GitHub username or organization name (e.g. `"vercel"`) |
+| `repo` 
+
+**Example:**
+```typescript
+// --- Inline types (mirroring the real library's shape) ---
+type ImportFormat = 'markdown' | 'openapi' | 'html' | 'text' | 'auto'
+
+interface ImportResult {
+  name: string
+  format: ImportFormat
+  pagesImported: number
+  source: string
+  success: boolean
+}
+
+// --- Simulated implementation (replace w
+```
+
+### runImport
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/index.ts
+
+```
+function runImport(dir: string, format: ImportFormat, name?: string): ImportResult
+```
+
+Use this to automatically import and process a documentation directory based on its detected format (Mintlify, Docusaurus, GitBook, ReadMe, Confluence, or plain Markdown).
+
+Instead of manually selecting the right importer, pass the directory path and detected format — `runImport` routes to the correct importer and returns a normalized result.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ Yes | Path to the documentation di
+
+**Example:**
+```typescript
+// --- Inline types (mirrors autodocs internals) ---
+type ImportFormat = 'mintlify' | 'docusaurus' | 'gitbook' | 'readme' | 'confluence' | 'markdown'
+
+interface ImportedPage {
+  path: string
+  title: string
+  content: string
+}
+
+interface ImportResult {
+  name: string
+  format: ImportFormat
+  pages: 
+```
+
+### importMarkdown
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/markdown.ts
+
+```
+function importMarkdown(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a directory of Markdown or MDX files into a structured import result, where folder hierarchy becomes groups and individual files become pages.
+
+This is the starting point when migrating a plain Markdown documentation site — it recursively scans the target directory, preserves your folder structure as navigation groups, and returns a normalized `ImportResult` ready for further processing or output.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|-------
+
+### importMintlify
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/mintlify.ts
+
+```
+function importMintlify(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a Mintlify documentation project into a standardized `ImportResult` format, ready for further processing or migration to another docs platform.
+
+This function scans a Mintlify project directory, reads its configuration, transforms MDX components (callouts, tabs, code groups, steps, accordions), and returns all pages with normalized frontmatter and rewritten image paths.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` |
+
+### importNotion
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/notion.ts
+
+```
+function importNotion(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a Notion export folder into structured, importable page data — stripping UUIDs, normalizing frontmatter, and transforming Notion-specific syntax into clean markdown.
+
+This is the entry point for processing a Notion HTML/Markdown export. Point it at the extracted export directory and it returns all discovered pages with their transformed content and transformation statistics.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `d
+
+### importReadme
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/readme.ts
+
+```
+function importReadme(dir: string, name?: string): ImportResult
+```
+
+Use this to convert a ReadMe.io documentation export into a structured import result, transforming ReadMe-specific markdown syntax (callouts, code blocks, frontmatter) into a normalized format ready for further processing or migration.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ Yes | Path to the root directory of the ReadMe.io export. ReadMe organizes exports into category folders, each containing an `_order.yaml` file
+
+### transformMintlifyCallouts
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformMintlifyCallouts(content: string): string
+```
+
+Use this to convert Mintlify-flavored callout components (`<Note>`, `<Warning>`, `<Tip>`, `<Info>`, `<Check>`) into a unified `<Callout type="...">` format during documentation migration or preprocessing.
+
+This is useful when migrating docs from Mintlify to another platform (e.g., Nextra, Fumadocs) that uses a generic `<Callout>` component with a `type` prop instead of named tags.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `st
+
+**Example:**
+```typescript
+// Inline the callout tag mapping (mirrors the library's internal map)
+const MINTLIFY_CALLOUT_MAP: Record<string, string> = {
+  Note: 'note',
+  Warning: 'warning',
+  Tip: 'tip',
+  Info: 'info',
+  Check: 'check',
+}
+
+// Self-contained implementation of transformMintlifyCallouts
+function transformMintl
+```
+
+### transformDocusaurusAdmonitions
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformDocusaurusAdmonitions(content: string): string
+```
+
+Use this to convert Docusaurus admonition blocks (:::note, :::tip, :::danger, etc.) into a standardized callout format for rendering in other documentation systems.
+
+This is useful when migrating or syncing Docusaurus docs to platforms that use a different callout/admonition syntax — the function handles all standard Docusaurus admonition types and optional custom titles.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| content | `string` | ✅ | 
+
+**Example:**
+```typescript
+// Inline the admonition type mapping (mirrors the real implementation)
+const DOCUSAURUS_ADMONITION_MAP: Record<string, string> = {
+  note: 'note',
+  tip: 'tip',
+  info: 'info',
+  caution: 'warning',
+  danger: 'danger',
+  warning: 'warning',
+}
+
+// Self-contained implementation of transformDocusaurus
+```
+
+### transformGitBookHints
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformGitBookHints(content: string): string
+```
+
+Use this to convert GitBook hint/callout blocks into `<Callout>` JSX components during documentation migration or preprocessing.
+
+GitBook uses a custom `{% hint style="..." %}` syntax that won't render in standard MDX or React-based doc systems. This function transforms those blocks into `<Callout type="...">` components, preserving the hint style and content.
+
+**Supported style mappings** (based on typical GitBook hint styles):
+| GitBook Style | Callout Type |
+|---------------|--------------|
+|
+
+**Example:**
+```typescript
+// Inline the hint style map (mirrors the real implementation)
+const GITBOOK_HINT_MAP: Record<string, string> = {
+  info: 'info',
+  warning: 'warning',
+  danger: 'danger',
+  success: 'success',
+}
+
+// Self-contained implementation of transformGitBookHints
+function transformGitBookHints(content: strin
+```
+
+### transformReadmeCallouts
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformReadmeCallouts(content: string): string
+```
+
+Use this to convert ReadMe RDMD-style callout blocks (using emoji prefixes) into standard markdown or HTML callout components — ideal for preprocessing `.md` files exported from ReadMe before rendering them in your own docs pipeline.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | Raw markdown string containing ReadMe RDMD callout syntax (e.g., `> 📘 Title\n> body text`) |
+
+### Returns
+
+| Condition | Returns |
+|-----
+
+**Example:**
+```typescript
+// Inline the emoji map and transformation logic (self-contained, no imports needed)
+const README_EMOJI_MAP: Record<string, string> = {
+  '📘': 'info',
+  '👍': 'success',
+  '🚧': 'warning',
+  '❗': 'danger',
+}
+
+// Inline implementation of transformReadmeCallouts
+function transformReadmeCallouts(conte
+```
+
+### transformNotionCallouts
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformNotionCallouts(content: string): string
+```
+
+Use this to convert Notion-style callout markup — both `<aside>` HTML blocks and `:::callout` fenced syntax — into a normalized format suitable for rendering or further processing.
+
+This is especially useful when parsing exported Notion content that mixes raw HTML callouts with Markdown-style callout blocks, ensuring consistent output regardless of which format Notion used.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` |
+
+**Example:**
+```typescript
+// Inline implementation of transformNotionCallouts for demonstration
+// (mirrors the real behavior: converts Notion callout formats to normalized blockquotes)
+function transformNotionCallouts(content: string): string {
+  // Transform <aside>...</aside> HTML blocks
+  content = content.replace(
+    /
+```
+
+### transformConfluenceCallouts
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformConfluenceCallouts(content: string): string
+```
+
+Use this to convert Confluence structured macro callouts (`info`, `note`, `warning`, `tip`) into clean `<Callout>` components suitable for rendering in documentation systems like Nextra or MDX.
+
+When migrating Confluence pages to Markdown/MDX, callout macros come through as verbose XML-like `<ac:structured-macro>` tags. This function strips that boilerplate and outputs a compact, framework-friendly `<Callout type="...">` element with the inner text content preserved.
+
+## Parameters
+
+| Name | Typ
+
+**Example:**
+```typescript
+// Inline implementation of the helper and main function (self-contained)
+function stripHtmlTags(html: string): string {
+  return html.replace(/<[^>]*>/g, '')
+}
+
+function transformConfluenceCallouts(content: string): string {
+  return content.replace(
+    /<ac:structured-macro[^>]*ac:name="(info|not
+```
+
+### transformMintlifyTabs
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformMintlifyTabs(content: string): string
+```
+
+Use this to convert Mintlify-flavored `<Tabs>/<Tab>` JSX syntax into standard Markdown or a compatible tab format — useful when migrating docs from Mintlify to another platform or pre-processing MDX content.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | Raw documentation string containing Mintlify `<Tabs>` and `<Tab>` components |
+
+### Returns
+
+| Condition | Return Value |
+|-----------|-------------|
+| Content cont
+
+**Example:**
+```typescript
+// Inline implementation of transformMintlifyTabs (self-contained, no imports needed)
+function transformMintlifyTabs(content: string): string {
+  return content.replace(
+    /<Tabs>([\s\S]*?)<\/Tabs>/g,
+    (_match, inner: string) => {
+      const tabs: { title: string; content: string }[] = []
+    
+```
+
+### transformDocusaurusTabs
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformDocusaurusTabs(content: string): string
+```
+
+Use this to convert Docusaurus `<Tabs>` / `<TabItem>` JSX syntax into plain markdown or a renderable alternative — useful when migrating Docusaurus docs to another format or stripping framework-specific markup from content.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | Raw documentation string containing Docusaurus `<Tabs>` and `<TabItem>` JSX elements |
+
+### Returns
+
+| Condition | Return Value |
+|-----------|-----
+
+**Example:**
+```typescript
+// Inline implementation of transformDocusaurusTabs (self-contained, no imports needed)
+function transformDocusaurusTabs(content: string): string {
+  return content.replace(
+    /<Tabs[^>]*>([\s\S]*?)<\/Tabs>/g,
+    (_match, inner: string) => {
+      const tabs: { value: string; label: string; conte
+```
+
+### transformGitBookTabs
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformGitBookTabs(content: string): string
+```
+
+Use this to convert GitBook tab syntax into clean markdown, stripping the `{% tabs %}` / `{% tab %}` / `{% endtab %}` / `{% endtabs %}` block tags while preserving each tab's title and content.
+
+This is useful when migrating GitBook documentation to standard markdown or when rendering GitBook-flavored content in environments that don't support GitBook's templating syntax.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ 
+
+**Example:**
+```typescript
+// Inline implementation of transformGitBookTabs (no external imports needed)
+function transformGitBookTabs(content: string): string {
+  return content.replace(
+    /\{%\s*tabs\s*%\}([\s\S]*?)\{%\s*endtabs\s*%\}/g,
+    (_match, inner: string) => {
+      const tabs: { title: string; content: string }
+```
+
+### transformReadmeCodeBlocks
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformReadmeCodeBlocks(content: string): string
+```
+
+Use this to convert ReadMe.io's proprietary `[block:code]` syntax into standard `<CodeGroup>` components for modern documentation platforms.
+
+When migrating content from ReadMe.io, code blocks are stored as JSON-wrapped `[block:code]...[/block]` tags. This function parses those blocks and transforms them into portable `<CodeGroup>` elements that work with MDX-based doc systems like Mintlify or Nextra.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|------------
+
+**Example:**
+```typescript
+// Inline implementation of transformReadmeCodeBlocks
+// (mirrors the real function behavior for demonstration)
+
+function transformReadmeCodeBlocks(content: string): string {
+  return content.replace(
+    /\[block:code\]\n?([\s\S]*?)\n?\[\/block\]/g,
+    (_match, jsonStr: string) => {
+      try {
+  
+```
+
+### transformGitBookSteps
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformGitBookSteps(content: string): string
+```
+
+Use this to convert GitBook stepper/step syntax into clean markdown, stripping the `{% stepper %}`, `{% step %}`, `{% endstep %}`, and `{% endstepper %}` tags while preserving the step content in a readable format.
+
+This is useful when migrating GitBook documentation to standard markdown or rendering GitBook content in environments that don't support GitBook's custom block syntax.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `st
+
+**Example:**
+```typescript
+// Inline implementation of transformGitBookSteps (self-contained, no imports needed)
+function transformGitBookSteps(content: string): string {
+  return content.replace(
+    /\{%\s*stepper\s*%\}([\s\S]*?)\{%\s*endstepper\s*%\}/g,
+    (_match, inner: string) => {
+      const steps = inner
+        .sp
+```
+
+### transformGitBookExpandable
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformGitBookExpandable(content: string): string
+```
+
+Use this to convert GitBook expandable blocks into Accordion components for rendering in documentation frameworks that support `<Accordion>` syntax (e.g., Mintlify).
+
+Transforms `{% expandable title="X" %}...{% endexpandable %}` GitBook shortcodes into `<Accordion title="X">...</Accordion>` HTML/JSX elements. Handles multiline content and multiple expandable blocks in a single pass.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `
+
+**Example:**
+```typescript
+// Inline implementation of transformGitBookExpandable
+function transformGitBookExpandable(content: string): string {
+  return content.replace(
+    /\{%\s*expandable\s+title="([^"]+)"\s*%\}([\s\S]*?)\{%\s*endexpandable\s*%\}/g,
+    (_match, title: string, body: string) =>
+      `<Accordion title="${
+```
+
+### transformGitBookContentRef
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformGitBookContentRef(content: string): string
+```
+
+Use this to convert GitBook `content-ref` shortcode blocks into standard markdown links during documentation migration or content processing pipelines.
+
+GitBook uses a proprietary `{% content-ref %}...{% endcontent-ref %}` block syntax to create page references. This function strips that syntax and produces a clean `[label](url)` markdown link, where the label is automatically derived from the URL's filename (with `.md` extension removed).
+
+**Parameters**
+
+| Name | Type | Required | Description 
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function transformGitBookContentRef(content: string): string {
+  return content.replace(
+    /\{%\s*content-ref\s+url="([^"]+)"\s*%\}[\s\S]*?\{%\s*endcontent-ref\s*%\}/g,
+    (_match, url: string) => {
+      const label = url.replace(/\.md$/, '')
+```
+
+### transformGitBookEmbed
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformGitBookEmbed(content: string): string
+```
+
+Use this to strip GitBook `{% embed url="..." %}` syntax from content, replacing it with plain URLs for rendering in non-GitBook environments.
+
+This is useful when migrating GitBook documentation to other platforms, or when processing GitBook markdown files that contain embed tags that would appear as raw syntax instead of rendered links.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | A string containing GitBook emb
+
+**Example:**
+```typescript
+// Inline implementation of transformGitBookEmbed
+function transformGitBookEmbed(content: string): string {
+  return content.replace(
+    /\{%\s*embed\s+url="([^"]+)"\s*%\}/g,
+    (_match, url: string) => url
+  )
+}
+
+// --- Examples ---
+
+// 1. Single embed tag
+const singleEmbed = `Check out this reso
+```
+
+### transformNotionToggles
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformNotionToggles(content: string): string
+```
+
+Use this to convert Notion-exported toggle blocks (HTML `<details>`/`<summary>` elements) into `<Accordion>` components for MDX or documentation frameworks like Mintlify or Docusaurus.
+
+When you export content from Notion, toggles become `<details><summary>Title</summary>content</details>` HTML. This function transforms all of them in a single pass into `<Accordion title="...">` components ready for rendering.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|--
+
+**Example:**
+```typescript
+// Inline implementation — no imports needed
+function transformNotionToggles(content: string): string {
+  return content.replace(
+    /<details>\s*<summary>([\s\S]*?)<\/summary>([\s\S]*?)<\/details>/g,
+    (_match, title: string, body: string) =>
+      `<Accordion title="${title.trim()}">\n${body.tr
+```
+
+### transformConfluenceHtml
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function transformConfluenceHtml(content: string): string
+```
+
+Use this to convert Confluence HTML pages (including Atlassian Confluence macros) into clean, readable Markdown strings — ideal for ingesting Confluence content into AI pipelines, search indexes, or documentation systems.
+
+This function handles:
+- `ac:structured-macro` code blocks (with optional language tags) → fenced Markdown code blocks
+- Common HTML elements → Markdown equivalents
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | 
+
+**Example:**
+```typescript
+// Inline implementation of transformConfluenceHtml (self-contained, no imports needed)
+function transformConfluenceHtml(content: string): string {
+  // Code macros: <ac:structured-macro ac:name="code"> with optional language
+  content = content.replace(
+    /<ac:structured-macro[^>]*ac:name="code"[
+```
+
+### stripDocusaurusImports
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function stripDocusaurusImports(content: string): string
+```
+
+Use this to clean Docusaurus-specific theme import statements from MDX/markdown content before processing it in non-Docusaurus environments, or when extracting plain content from Docusaurus documentation files.
+
+Strips all lines matching the pattern `import ... from '@theme/...'` — the special Docusaurus theme component imports that would cause errors or noise outside of a Docusaurus build context.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function stripDocusaurusImports(content: string): string {
+  return content.replace(/^import\s+.*from\s+['"]@theme\/.*['"];?\s*\n?/gm, '')
+}
+
+// --- Example usage ---
+
+const rawMdxContent = `import Tabs from '@theme/Tabs';
+import TabItem from '@t
+```
+
+### normalizeFrontmatter
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function normalizeFrontmatter(content: string, defaults?: FrontmatterDefaults): string
+```
+
+Use this to standardize frontmatter fields in markdown content to Skrypt format, optionally injecting default values when fields are missing.
+
+This is useful when processing markdown files from multiple sources that may use inconsistent frontmatter conventions — it normalizes them into a predictable structure while preserving the document body.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | Full markdown string, incl
+
+**Example:**
+```typescript
+// Inline types (do not import from autodocs)
+type FrontmatterDefaults = {
+  title?: string
+  description?: string
+  tags?: string[]
+  author?: string
+  date?: string
+  [key: string]: unknown
+}
+
+// --- Simulated implementation of normalizeFrontmatter ---
+function parseFrontmatterRaw(content: string)
+```
+
+### rewriteImagePaths
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function rewriteImagePaths(content: string, mapping: Map<string, string>): string
+```
+
+Use this to update image paths in documentation content after assets have been copied to a new location. When you move or rename image files during a build process, this function rewrites all references in your content string to point to the new paths.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | The raw content string (e.g., Markdown or HTML) containing image path references to be updated |
+| `mapping` | `Map<stri
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function rewriteImagePaths(content: string, mapping: Map<string, string>): string {
+  for (const [oldPath, newPath] of mapping) {
+    content = content.replaceAll(oldPath, newPath)
+  }
+  return content
+}
+
+// Simulate a docs page with several imag
+```
+
+### stripNotionUUIDs
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function stripNotionUUIDs(filename: string): string
+```
+
+Use this to clean up Notion export filenames by removing the 32-character hex UUID suffixes that Notion automatically appends to every file and folder name.
+
+When you export content from Notion, filenames look like `My Page a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4.md`. This function strips those suffixes, giving you human-readable filenames like `My Page.md`.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filename` | `string` | ✅ | The Notion-exporte
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function stripNotionUUIDs(filename: string): string {
+  return filename.replace(/\s+[0-9a-f]{32}/g, '')
+}
+
+async function main() {
+  try {
+    // Basic usage: single file with UUID suffix
+    const raw = 'Getting Started a1b2c3d4e5f6a1b2c3d4e5f6a
+```
+
+### getSortWeight
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/importers/transform.ts
+
+```
+function getSortWeight(content: string): number
+```
+
+Use this to determine the sort order of a documentation file by extracting its position weight from frontmatter metadata. Returns a numeric weight so you can sort an array of markdown files into the correct sidebar order.
+
+Supports the following frontmatter keys (in priority order): `sidebar_position`, `order`, `weight`, `position`.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | Yes | Raw markdown/MDX file content, inclu
+
+**Example:**
+```typescript
+// Inline frontmatter parser (simulates gray-matter / parseFrontmatterRaw)
+function parseFrontmatterRaw(content: string): { data: Record<string, unknown> | null } {
+  const match = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!match) return { data: null }
+
+  const yaml = match[1]
+  const data: Recor
+```
+
+### AnthropicClient
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/llm/anthropic-client.ts
+
+```
+class AnthropicClient implements LLMClient
+```
+
+Use this to send prompts to Anthropic's Claude models and receive structured completions — with automatic retries built in.
+
+`AnthropicClient` wraps the Anthropic SDK and implements a common `LLMClient` interface, making it easy to swap between LLM providers without changing your application logic.
+
+## Constructor Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.model` | `string` | Yes | The Claude model to use (e.g. `"claude-3-5-sonnet-2024
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type LLMProvider = 'anthropic' | 'openai'
+
+type LLMClientConfig = {
+  model: string
+  apiKey: string
+  maxRetries?: number
+}
+
+type CompletionRequest = {
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+
+```
+
+### constructor
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/anthropic-client.ts
+
+```
+constructor(config: LLMClientConfig)
+```
+
+Use this to create an Anthropic-backed LLM client that handles retries and model configuration for sending completion requests.
+
+The `AnthropicClient` constructor initializes a client instance configured with your Anthropic API key, target model, and retry behavior. It wraps the Anthropic SDK to provide a consistent interface for making LLM calls.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.apiKey` | `string` | Yes | Your Anthropic
+
+**Example:**
+```typescript
+// Inline type definitions (do not import from autodocs)
+type LLMProvider = 'anthropic' | 'openai'
+
+interface LLMClientConfig {
+  apiKey: string
+  model: string
+  maxRetries?: number
+}
+
+interface CompletionRequest {
+  prompt: string
+  maxTokens?: number
+}
+
+interface CompletionResponse {
+  text: stri
+```
+
+### isConfigured
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/anthropic-client.ts
+
+```
+isConfigured(): boolean
+```
+
+Use this to verify that an `AnthropicClient` instance is ready to make API calls before attempting completions.
+
+This method acts as a readiness check — it confirms the client has been initialized and the underlying Anthropic SDK has taken responsibility for credential validation. Call it as a guard before executing requests in conditional flows or health checks.
+
+**Returns**
+
+| Value | Condition |
+|-------|-----------|
+| `true` | Always — the client is initialized and the Anthropic SDK handles 
+
+**Example:**
+```typescript
+// Inline types to simulate AnthropicClient behavior
+interface LLMClientConfig {
+  apiKey: string
+  model?: string
+  timeout?: number
+  maxRetries?: number
+}
+
+// Simulated AnthropicClient class (self-contained, no external imports)
+class AnthropicClient {
+  private apiKey: string
+  private model: st
+```
+
+### complete
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/anthropic-client.ts
+
+```
+async complete(request: CompletionRequest): Promise<CompletionResponse>
+```
+
+Use this to send a conversation to Anthropic's Claude models and receive a completion response, handling system prompts and multi-turn conversations automatically.
+
+This method separates system messages from conversation messages internally, so you can pass a unified message array without pre-processing. It wraps Anthropic's SDK and returns a normalized `CompletionResponse` regardless of which Claude model you target.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|------
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type MessageRole = 'system' | 'user' | 'assistant'
+
+interface Message {
+  role: MessageRole
+  content: string
+}
+
+interface CompletionRequest {
+  messages: Message[]
+  model?: string
+  maxTokens?: number
+  temperature?: n
+```
+
+### createLLMClient
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/llm/index.ts
+
+```
+function createLLMClient(config: {
+  provider: LLMProvider
+  model: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+}): LLMClient
+```
+
+Use this to initialize a typed LLM client for a specific AI provider (OpenAI, Anthropic, etc.) with built-in retry and timeout handling.
+
+This is your entry point for all LLM interactions — call it once at startup, then reuse the returned client across your application to send prompts and receive completions.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.provider` | `LLMProvider` | ✅ Yes | The AI provider to use. Accepted values: `"op
+
+**Example:**
+```typescript
+// --- Inline types (mirrors the real library's shape) ---
+type LLMProvider = "openai" | "anthropic" | "azure"
+
+interface Message {
+  role: "user" | "assistant" | "system"
+  content: string
+}
+
+interface CompletionResponse {
+  id: string
+  content: string
+  model: string
+  usage: { promptTokens: numb
+```
+
+### generateDocumentation
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/llm/index.ts
+
+```
+async function generateDocumentation(client: LLMClient, element: ElementContext, options?: { multiLanguage?: boolean }): Promise<GeneratedDocResult>
+```
+
+Use this to automatically generate documentation for a code element (function, class, method, etc.) using an LLM client, with optional multi-language support.
+
+This is the primary entry point for producing structured documentation output from parsed code context. Pass in your configured LLM client and a description of the code element, and receive a ready-to-use documentation result.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `L
+
+**Example:**
+```typescript
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type LLMMessage = { role: 'user' | 'assistant' | 'system'; content: string }
+
+interface LLMClient {
+  complete(messages: LLMMessage[]): Promise<string>
+}
+
+interface ElementContext {
+  name: string
+  signature: string
+  
+```
+
+### fixCodeSample
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/llm/index.ts
+
+```
+async function fixCodeSample(client: LLMClient, code: string, error: string, context: string, iteration: number = 1): Promise<string>
+```
+
+Use this to automatically repair broken code samples by sending them to an LLM with the error context and receiving a corrected version. Ideal for documentation pipelines, code generation workflows, or CI systems that validate and self-heal code examples.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `LLMClient` | ✅ | An initialized LLM client instance used to generate the fix |
+| `code` | `string` | ✅ | The broken code sample that
+
+**Example:**
+```typescript
+// ── Inline types (do not import from autodocs) ──────────────────────────────
+interface LLMMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+interface LLMClient {
+  complete(messages: LLMMessage[]): Promise<string>
+}
+
+// ── Simulated LLM client (replace with your real client i
+```
+
+### OpenAICompatibleClient
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/llm/openai-client.ts
+
+```
+class OpenAICompatibleClient implements LLMClient
+```
+
+Use this to connect to any OpenAI-compatible LLM provider — including OpenAI, DeepSeek, Ollama, OpenRouter, and Google Gemini — through a single unified client interface.
+
+`OpenAICompatibleClient` normalizes provider differences (base URLs, auth headers, retry logic) so you can swap providers without changing your application code.
+
+## Constructor Config
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `provider` | `LLMProvider` | ✅ | Provider identifier (e.g.
+
+### constructor
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/openai-client.ts
+
+```
+constructor(config: LLMClientConfig)
+```
+
+Use this to create an LLM client that connects to any OpenAI-compatible API provider (OpenAI, Azure, Anthropic, local models, etc.) with automatic retry logic and provider-specific configuration.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `LLMClientConfig` | ✅ | Configuration object for the LLM client |
+| `config.provider` | `LLMProvider` | ✅ | The LLM provider identifier (e.g., `'openai'`, `'anthropic'`, `'azure'`) |
+| `config.
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type LLMProvider = 'openai' | 'anthropic' | 'azure' | 'ollama' | string
+
+interface LLMClientConfig {
+  provider: LLMProvider
+  model: string
+  apiKey: string
+  baseUrl?: string
+  maxRetries?: number
+}
+
+interface Completi
+```
+
+### isConfigured
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/openai-client.ts
+
+```
+isConfigured(): boolean
+```
+
+Use this to verify that an `OpenAICompatibleClient` instance is ready to make API calls before attempting completions.
+
+This method acts as a readiness check — it always returns `true` because the underlying OpenAI SDK handles API key validation and configuration errors at request time rather than at initialization. Use it in guard clauses or health checks to conform to a standard client interface without worrying about pre-flight validation logic.
+
+### Returns
+
+| Condition | Value |
+|----------
+
+**Example:**
+```typescript
+// Inline the minimal interface and class needed to demonstrate isConfigured()
+interface LLMClientConfig {
+  apiKey: string
+  model?: string
+  baseURL?: string
+  maxRetries?: number
+}
+
+// Simulated OpenAICompatibleClient with isConfigured behavior
+class OpenAICompatibleClient {
+  private apiKey: str
+```
+
+### complete
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/openai-client.ts
+
+```
+async complete(request: CompletionRequest): Promise<CompletionResponse>
+```
+
+Use this to send a chat completion request to any OpenAI-compatible API endpoint (OpenAI, Azure, Groq, Together AI, etc.) and receive a structured response with the generated text and token usage.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `request` | `CompletionRequest` | Yes | The completion request object containing messages, model, and generation settings |
+| `request.messages` | `Array<{role: string, content: string}>` | Yes | Convers
+
+**Example:**
+```typescript
+import OpenAI from 'openai'
+
+// --- Inline types (do not import from library) ---
+interface Message {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+interface CompletionRequest {
+  messages: Message[]
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  systemPrompt?: string
+
+```
+
+### PluginManager
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+class PluginManager
+```
+
+Use this to load, manage, and execute documentation plugins that transform source files into output during the autodocs build process.
+
+`PluginManager` orchestrates the full plugin lifecycle — registering plugins, running them in sequence, and providing each plugin with shared context (paths, config, and a logger).
+
+## Constructor Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sourcePath` | `string` | Yes | Absolute or relative path to the source
+
+**Example:**
+```typescript
+// --- Inline types (no external imports needed) ---
+
+type PluginContext = {
+  sourcePath: string
+  outputPath: string
+  config: Record<string, unknown>
+  logger: {
+    info: (msg: string) => void
+    warn: (msg: string) => void
+    error: (msg: string) => void
+  }
+}
+
+type SkryptPlugin = {
+  name: s
+```
+
+### constructor
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+constructor(sourcePath: string, outputPath: string, config: Record<string, unknown> = {})
+```
+
+Use this to initialize a plugin manager that coordinates documentation plugins across a source codebase, wiring together input/output paths and shared configuration before any plugins are registered or executed.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sourcePath` | `string` | ✅ Yes | Absolute or relative path to the source code directory to be processed |
+| `outputPath` | `string` | ✅ Yes | Absolute or relative path to the directory wh
+
+**Example:**
+```typescript
+// --- Inline types (mirroring the real autodocs internals) ---
+interface PluginContext {
+  sourcePath: string
+  outputPath: string
+  config: Record<string, unknown>
+  logger: {
+    info: (msg: string) => void
+    warn: (msg: string) => void
+    error: (msg: string) => void
+  }
+}
+
+interface SkryptPl
+```
+
+### loadPlugins
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async loadPlugins(configPath?: string): Promise<void>
+```
+
+Use this to initialize and load plugins into the `PluginManager` from a configuration file, enabling plugin-based extensibility in your application.
+
+This method reads plugin definitions from a `skrypt.config.js` or `skrypt.config.ts` file (auto-discovered if no path is provided) and registers them with the manager. Call this once during application startup before executing any plugin-dependent logic.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|------------
+
+**Example:**
+```typescript
+// Inline types to simulate PluginManager behavior
+type Plugin = {
+  name: string
+  execute: (input: string) => string
+}
+
+type PluginConfig = {
+  plugins: Plugin[]
+}
+
+// Simulated PluginManager class (self-contained, no external imports)
+class PluginManager {
+  private plugins: Map<string, Plugin> =
+```
+
+### register
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+register(plugin: SkryptPlugin): void
+```
+
+Use this to manually register a plugin with the `PluginManager`, adding it to the active plugin list so its hooks can be executed during the build or runtime lifecycle.
+
+This is the direct registration path — useful when you have a plugin object already constructed in memory and don't need to load it from disk.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `plugin` | `SkryptPlugin` | ✅ Yes | The plugin object to register. Must have at minimu
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+type HookFn = (...args: unknown[]) => unknown | Promise<unknown>
+
+interface SkryptPlugin {
+  name: string
+  version?: string
+  onBuildStart?: HookFn
+  onBuildEnd?: HookFn
+  transform?: HookFn
+}
+
+// --- Inline PluginManager implementation ---
+clas
+```
+
+### runHook
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async runHook<T>(hook: keyof SkryptPlugin, ...args: unknown[]): Promise<T | undefined>
+```
+
+Use this to execute a named hook across all registered plugins in sequence, passing data through each plugin's implementation of that hook.
+
+`runHook` iterates over every registered plugin, finds those that implement the specified hook method, and calls them in registration order. Each plugin receives the result of the previous plugin, enabling a pipeline/middleware pattern where plugins can transform data as it flows through.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|----
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+interface SkryptPlugin {
+  name: string
+  version?: string
+  beforeCompile?: (source: string) => Promise<string> | string
+  afterCompile?: (output: string) => Promise<string> | string
+  onError?: (error: Error) => Promise<void> | void
+}
+
+// --- I
+```
+
+### onInit
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onInit(): Promise<void>
+```
+
+Use this to trigger the initialization lifecycle hook across all registered plugins in a `PluginManager` instance. Call this once after all plugins have been registered and before any scanning or processing begins.
+
+This method delegates to the internal `runHook('onInit')` mechanism, ensuring every plugin's `onInit` handler is executed in sequence.
+
+## Parameters
+
+_None_
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<void>` | Resolves when all plugin `onInit` hooks have co
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager lifecycle
+type HookName = 'onInit' | 'onBeforeScan' | 'onAfterScan'
+
+type Plugin = {
+  name: string
+  onInit?: () => Promise<void>
+  onBeforeScan?: () => Promise<void>
+}
+
+// Simulated PluginManager class (self-contained, no external imports)
+class Plugin
+```
+
+### onBeforeScan
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onBeforeScan(): Promise<void>
+```
+
+Use this to trigger all registered plugins' pre-scan lifecycle hooks before a documentation scan begins. This allows plugins to perform setup tasks, validate configurations, or prepare resources before any files are processed.
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<void>` | Resolves when all registered plugins have completed their `onBeforeScan` hooks. Rejects if any plugin hook throws an error. |
+
+## When to Call
+
+C
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager behavior
+type HookName = 'onInit' | 'onBeforeScan' | 'onAfterScan'
+
+interface Plugin {
+  name: string
+  onInit?: () => Promise<void>
+  onBeforeScan?: () => Promise<void>
+  onAfterScan?: <T>(elements: T[]) => Promise<T[]>
+}
+
+// Simulated PluginManager cla
+```
+
+### onAfterScan
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onAfterScan<T>(elements: T[]): Promise<T[]>
+```
+
+Use this to run all registered plugins' `onAfterScan` hooks against a list of scanned elements, allowing plugins to filter, transform, or enrich the results before further processing.
+
+This is called automatically by the `PluginManager` after a scan completes. Each plugin that implements `onAfterScan` gets a chance to modify the elements array in sequence. If no plugin modifies the elements, the original array is returned unchanged.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|-----
+
+**Example:**
+```typescript
+// Inline types to simulate PluginManager behavior
+type Plugin = {
+  name: string
+  onAfterScan?: <T>(elements: T[]) => Promise<T[]>
+}
+
+type ScannedFile = {
+  path: string
+  type: string
+  exported: boolean
+}
+
+// Simulate the PluginManager class
+class PluginManager {
+  private plugins: Plugin[] = []
+```
+
+### onBeforeGenerate
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onBeforeGenerate<T>(elements: T[]): Promise<T[]>
+```
+
+Use this to run all registered plugins' `onBeforeGenerate` hooks against a collection of elements before documentation generation begins. This is the ideal interception point for filtering, transforming, sorting, or enriching your elements (e.g., parsed AST nodes, function signatures, class definitions) before they are handed off to the doc generator.
+
+If no plugin hook modifies the elements, the original array is returned unchanged.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|----
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager behavior
+type Hook<T> = (elements: T[]) => Promise<T[] | null | undefined>
+
+interface Plugin {
+  onBeforeGenerate?: <T>(elements: T[]) => Promise<T[]>
+}
+
+// Simulated PluginManager with onBeforeGenerate support
+class PluginManager {
+  private plugins: Pl
+```
+
+### onAfterGenerate
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onAfterGenerate<T>(docs: T[]): Promise<T[]>
+```
+
+Use this to run all registered plugins' `onAfterGenerate` hooks against a collection of generated documentation objects, allowing plugins to transform, filter, enrich, or reorder docs before they are written to disk.
+
+This is the final transformation stage in the generation pipeline — ideal for plugins that need to post-process docs (e.g., injecting metadata, removing internal-only entries, sorting output).
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|------
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager behavior
+type Hook<T> = (data: T) => Promise<T> | T
+
+interface Plugin {
+  name: string
+  onAfterGenerate?: Hook<any[]>
+}
+
+interface DocEntry {
+  id: string
+  title: string
+  content: string
+  internal?: boolean
+}
+
+// Minimal self-contained PluginManager 
+```
+
+### onBeforeWrite
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onBeforeWrite<T>(docs: T[]): Promise<T[]>
+```
+
+Use this to run all registered plugins' `onBeforeWrite` hooks against your generated docs array, allowing plugins to transform, filter, or enrich documents just before they are written to disk.
+
+This is the last interception point before output is committed — ideal for plugins that need to inject metadata, reorder entries, strip internal fields, or validate documents.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `T[]` | Yes | Array 
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager behavior
+type Plugin<T> = {
+  onBeforeWrite?: (docs: T[]) => Promise<T[]>
+}
+
+type DocEntry = {
+  name: string
+  content: string
+  metadata?: Record<string, unknown>
+}
+
+// Simulated PluginManager with onBeforeWrite support
+class PluginManager<T> {
+  priva
+```
+
+### onAfterWrite
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onAfterWrite(): Promise<void>
+```
+
+Use this to trigger all registered plugin hooks after documentation has been written to disk — ideal for post-write tasks like cache invalidation, notifications, or cleanup.
+
+`onAfterWrite` runs through every loaded plugin's `onAfterWrite` hook in sequence. It resolves when all hooks complete and does not return a value. If no plugins define this hook, it resolves immediately.
+
+### Parameters
+
+This method takes no parameters.
+
+### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise
+
+**Example:**
+```typescript
+// Inline types to keep example self-contained
+type Hook = (...args: unknown[]) => Promise<unknown> | unknown
+
+interface Plugin {
+  name: string
+  onAfterWrite?: () => Promise<void> | void
+  onBeforeWrite?: <T>(docs: T[]) => Promise<T[]> | T[]
+}
+
+// Simulated PluginManager implementation
+class Plugi
+```
+
+### transformContent
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async transformContent(content: string, filePath: string): Promise<string>
+```
+
+Use this to pipe file content through a chain of registered plugins, each of which can modify the content before it's written to disk. Ideal for applying transformations like syntax highlighting, markdown processing, code formatting, or custom replacements across your documentation pipeline.
+
+Each plugin in the manager that implements `transformContent` is called in sequence — the output of one becomes the input of the next.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type TransformPlugin = {
+  name: string
+  transformContent?: (content: string, filePath: string) => Promise<string>
+}
+
+// Simulated PluginManager class
+class PluginManager {
+  private plugins: TransformPlugin[]
+
+  constructor(plugins: TransformPlugin[]) {
+```
+
+### definePlugin
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+function definePlugin(plugin: SkryptPlugin): SkryptPlugin
+```
+
+Use this to define a typed plugin configuration object for the Skrypt plugin system with full type safety and IDE autocompletion.
+
+This is an identity function that acts as a **type helper** — it takes your plugin definition and returns it unchanged, but ensures your object conforms to the `SkryptPlugin` interface at compile time. Think of it as the Skrypt equivalent of Vue's `defineComponent` or Vite's `defineConfig`.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|-----
+
+**Example:**
+```typescript
+// Inline the SkryptPlugin type (do not import from autodocs)
+type PluginHookContext = {
+  cwd: string
+  config: Record<string, unknown>
+}
+
+type SkryptPlugin = {
+  name: string
+  version?: string
+  description?: string
+  setup?: (context: PluginHookContext) => void | Promise<void>
+  teardown?: () =>
+```
+
+### classifyElement
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/content-type.ts
+
+```
+function classifyElement(element: APIElement): ContentClassification
+```
+
+Use this to determine what type of documentation an API element needs — whether it's best suited for API reference docs, a guide, or a tutorial.
+
+Given an `APIElement`, `classifyElement` analyzes its characteristics and returns a `ContentClassification` indicating the recommended documentation type and the reasoning behind that recommendation. Use this when auto-generating or organizing documentation to ensure each element gets the right treatment.
+
+## Parameters
+
+| Name | Type | Required | Desc
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type APIElementKind = 'function' | 'class' | 'interface' | 'type' | 'variable'
+
+interface APIElement {
+  name: string
+  kind: APIElementKind
+  parameters?: { name: string; type: string; optional?: boolean }[]
+  returnTyp
+```
+
+### classifyElements
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/content-type.ts
+
+```
+function classifyElements(elements: APIElement[]): Map<ContentType, APIElement[]>
+```
+
+Use this to sort a mixed list of documentation elements into typed groups — API references, guides, tutorials, and overviews — in a single pass.
+
+Instead of manually filtering arrays for each content type, `classifyElements` returns a `Map` keyed by content type so you can immediately access any group by name.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `APIElement[]` | ✅ | Array of documentation elements to classify. Each ele
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+type ContentType = 'api' | 'guide' | 'tutorial' | 'overview'
+
+interface APIElement {
+  id: string
+  title: string
+  type: ContentType
+  content: string
+}
+
+// --- Inline implementation matching autodocs behavior ---
+function classifyElements(eleme
+```
+
+### getRecommendedStructure
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/content-type.ts
+
+```
+function getRecommendedStructure(elements: APIElement[]): {
+  sections: { name: string; type: ContentType; elements: APIElement[] }[]
+  stats: { api: number; guide: number; tutorial: number; overview: number }
+}
+```
+
+Use this to automatically organize a mixed set of API elements into a recommended documentation structure — grouping them into logical sections (API reference, guides, tutorials, overviews) and getting a count breakdown by content type.
+
+This is useful when you have a large set of parsed API elements and need to determine how to structure your documentation site or output files without manually categorizing each element.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|---
+
+**Example:**
+```typescript
+// ---- Inline types (do not import from autodocs) ----
+type ContentType = 'api' | 'guide' | 'tutorial' | 'overview'
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type' | 'variable' | 'module'
+  description?: string
+  tags?: string[]
+}
+
+type Section = {
+  name: st
+```
+
+### getPromptForContentType
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/content-type.ts
+
+```
+function getPromptForContentType(type: ContentType): string
+```
+
+Use this to get the appropriate documentation generation prompt string for a given content type — so you can feed the right instructions into an AI model or documentation pipeline based on what you're documenting.
+
+This function maps a `ContentType` value to a tailored prompt string that instructs a documentation generator on what to include (e.g., parameter types for APIs, usage examples for components, etc.).
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|--
+
+**Example:**
+```typescript
+// Inline the ContentType definition — no external imports needed
+type ContentType = 'api' | 'component' | 'guide' | 'utility'
+
+// Inline a representative implementation of getPromptForContentType
+function getPromptForContentType(type: ContentType): string {
+  switch (type) {
+    case 'api':
+      r
+```
+
+### GoScanner
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/scanner/go.ts
+
+```
+class GoScanner implements Scanner
+```
+
+Use this to scan Go source files and extract API elements — functions, methods, structs, and interfaces — for automated documentation generation pipelines.
+
+`GoScanner` implements the `Scanner` interface and targets `.go` files, automatically skipping test files (`_test.go`).
+
+## Methods
+
+### `canHandle(filePath: string): boolean`
+Returns `true` if the file path ends in `.go` and is not a test file. Use this to check compatibility before scanning.
+
+### `scanFile(filePath: string): Promise<ScanRe
+
+### canHandle
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/go.ts
+
+```
+canHandle(filePath: string): boolean
+```
+
+Use this to check whether a Go source file should be processed by the `GoScanner` — it returns `true` for `.go` files that are **not** test files (`_test.go`).
+
+This is the gating method called before scanning a file for functions, methods, types, and interfaces. It prevents test files from being included in documentation output.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the file b
+
+**Example:**
+```typescript
+// Inline implementation matching GoScanner.canHandle behavior
+class GoScanner {
+  languages = ['go']
+
+  canHandle(filePath: string): boolean {
+    return /\.go$/.test(filePath) && !filePath.includes('_test.go')
+  }
+}
+
+const scanner = new GoScanner()
+
+const testCases: Array<{ path: string; expected:
+```
+
+### scanFile
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/go.ts
+
+```
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to extract API elements from a Go source file, returning all discovered functions, types, and parameters in a structured result.
+
+`scanFile` reads and parses a `.go` file (excluding test files), identifying exported API elements and collecting any parse errors encountered during scanning.
+
+> **Note:** Only handles non-test Go files (`.go` extension, not `_test.go`). Use `canHandle(filePath)` to verify compatibility before calling.
+
+## Parameters
+
+| Name | Type | Required | Description |
+
+**Example:**
+```typescript
+import { writeFileSync, unlinkSync } from 'fs'
+import { promisify } from 'util'
+
+// --- Inline types (mirrors the real library's types) ---
+type Parameter = {
+  name: string
+  type: string
+  required?: boolean
+}
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'type' | 'method'
+  parameters?
+```
+
+### scanDirectory
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/index.ts
+
+```
+async function scanDirectory(dir: string, options: ScanOptions = {}): Promise<ScanAllResult>
+```
+
+Use this to recursively scan a directory (or single file) for all API elements — functions, classes, types, and exports — across multiple languages including Python, TypeScript, JavaScript, Go, and Rust.
+
+This is the primary entry point for automated documentation generation pipelines. Point it at a project root and get back a structured inventory of every public API element found.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string
+
+### scanFile
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/index.ts
+
+```
+async function scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to extract structured metadata from a single source file — functions, classes, types, and other symbols — without scanning an entire directory.
+
+`scanFile` inspects a file at the given path, selects the appropriate language scanner (TypeScript, JavaScript, Python, etc.), and returns a structured `ScanResult` containing all discovered symbols and language information.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string`
+
+**Example:**
+```typescript
+// Inline types matching the autodocs ScanResult shape
+type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable'
+
+interface DocSymbol {
+  name: string
+  kind: SymbolKind
+  line: number
+  docstring?: string
+  signature?: string
+}
+
+interface ScanResult {
+  filePath: string
+  language:
+```
+
+### PythonScanner
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/scanner/python.ts
+
+```
+class PythonScanner implements Scanner
+```
+
+Use this to scan Python source files and extract structured metadata (functions, classes, imports, etc.) by delegating parsing to a Python3 subprocess.
+
+`PythonScanner` implements the `Scanner` interface and is the go-to handler for any `.py` file in an autodocs pipeline. It spawns a `python3` process running an internal parser script, then resolves a `ScanResult` with the extracted code structure.
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `languages` | `string[]` | Alway
+
+**Example:**
+```typescript
+import { spawn } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// --- Inline types (mirrors autodocs Scanner interface) ---
+interface ScanResult {
+  filePath: string
+  language: string
+  symbols?: Symbol[]
+  error?: strin
+```
+
+### canHandle
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/python.ts
+
+```
+canHandle(filePath: string): boolean
+```
+
+Use this to quickly check whether a file should be processed by the Python scanner before attempting to parse or analyze it.
+
+`canHandle` inspects a file path and returns `true` if it ends with `.py`, allowing you to gate Python-specific scanning logic without wasting resources on unsupported file types.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | The path or filename to check for Python file extension |
+
+### Re
+
+**Example:**
+```typescript
+// Inline implementation matching PythonScanner behavior
+class PythonScanner {
+  languages = ['python']
+
+  canHandle(filePath: string): boolean {
+    return filePath.endsWith('.py')
+  }
+}
+
+const scanner = new PythonScanner()
+
+const testFiles = [
+  '/project/src/main.py',
+  '/project/src/utils.py',
+ 
+```
+
+### scanFile
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/python.ts
+
+```
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to scan a Python source file and extract structured metadata — functions, classes, imports, and other code elements — for documentation generation or static analysis pipelines.
+
+`scanFile` spawns a Python3 parser subprocess against the target `.py` file and resolves with a structured `ScanResult` object. It is a method on `PythonScanner`, which only handles files ending in `.py` (check with `canHandle` before calling).
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|---
+
+**Example:**
+```typescript
+import { spawn } from 'child_process'
+import { resolve } from 'path'
+import { writeFileSync, unlinkSync } from 'fs'
+
+// --- Inline types (mirrors the real ScanResult shape) ---
+interface ScannedFunction {
+  name: string
+  lineStart: number
+  lineEnd: number
+  docstring?: string
+}
+
+interface ScannedC
+```
+
+### get_docstring
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def get_docstring(node: ast.AST) -> str | None
+```
+
+Use this to extract the docstring from any Python AST node (functions, classes, modules) when parsing or analyzing Python source code programmatically.
+
+Returns the docstring as a `str` if one is present on the node, or `None` if no docstring exists.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| node | `ast.AST` | ✅ Yes | Any parsed AST node — typically a `Module`, `FunctionDef`, `AsyncFunctionDef`, or `ClassDef` node |
+
+## Returns
+
+| Value |
+
+**Example:**
+```python
+import ast
+
+# Inline implementation of get_docstring
+def get_docstring(node: ast.AST) -> str | None:
+    """Extract docstring from a node if present."""
+    if not isinstance(node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return None
+    if not node.body:
+        r
+```
+
+### get_type_annotation
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def get_type_annotation(annotation: ast.AST | None) -> str | None
+```
+
+Use this to convert a Python AST type annotation node into its human-readable string representation — ideal for documentation generators, code analyzers, or any tool that needs to display type hints as readable text.
+
+Returns `None` if the annotation is `None` or cannot be resolved. Returns a string like `"str"`, `"int"`, `"List[str]"`, or `"Optional[int]"` for valid annotations.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `annotation` | `a
+
+**Example:**
+```python
+import ast
+
+# Inline implementation of get_type_annotation
+def get_type_annotation(annotation: ast.AST | None) -> str | None:
+    """Convert type annotation AST to string."""
+    if annotation is None:
+        return None
+    try:
+        return ast.unparse(annotation)
+    except Exception:
+        
+```
+
+### get_default_value
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def get_default_value(default: ast.AST | None) -> str | None
+```
+
+Use this to extract a human-readable string representation of a Python function parameter's default value from its AST node — perfect for documentation generators, code analyzers, or introspection tools that need to display default values as they appear in source code.
+
+Returns `None` if no default exists (i.e., the parameter has no default value), or a string like `"42"`, `"'hello'"`, or `"None"` when a default is present.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|
+
+**Example:**
+```python
+import ast
+
+def get_default_value(default: ast.AST | None) -> str | None:
+    """Convert default value AST to string."""
+    if default is None:
+        return None
+    return ast.unparse(default)
+
+
+def extract_param_defaults(source_code: str) -> dict:
+    """Parse a function and extract parameter n
+```
+
+### extract_parameters
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def extract_parameters(args: ast.arguments) -> list[dict[str, Any]]
+```
+
+Use this to convert Python AST function arguments into a structured list of parameter metadata — ideal for building documentation generators, code analyzers, or introspection tools.
+
+Given an `ast.arguments` object (from parsing a Python function), this returns a list of dictionaries, each describing one parameter: its name, type annotation (if any), and default value (if any).
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `ast.argum
+
+**Example:**
+```python
+import ast
+from typing import Any
+
+# ── Inline implementation of extract_parameters ──────────────────────────────
+
+def extract_parameters(args: ast.arguments) -> list[dict[str, Any]]:
+    """Extract parameters from function arguments."""
+    params: list[dict[str, Any]] = []
+
+    all_args = args.po
+```
+
+### build_signature
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def build_signature(name: str, args: ast.arguments, returns: ast.AST | None, is_async: bool) -> str
+```
+
+Use this to reconstruct a human-readable function signature string from its parsed AST components — useful for code analysis tools, documentation generators, or any system that needs to display or compare function signatures without executing the code.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `str` | ✅ | The function name to include in the signature |
+| `args` | `ast.arguments` | ✅ | The parsed argument node from the AST, contai
+
+**Example:**
+```python
+import ast
+
+def build_signature(name: str, args: ast.arguments, returns, is_async: bool) -> str:
+    """Reconstruct a function signature string from AST components."""
+    parts = []
+
+    # Build each argument with optional annotation and default
+    num_args = len(args.args)
+    num_defaults = len(
+```
+
+### extract_function
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def extract_function(node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str, parent_class: str | None) -> dict[str, Any]
+```
+
+Use this to extract structured metadata from a Python function or method AST node — including its name, arguments, return type, decorators, and source location — for use in code analysis, documentation generation, or static analysis tooling.
+
+Given an AST node representing a function or async function, this returns a dictionary containing all key metadata about that function, ready for serialization or further processing.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|--
+
+**Example:**
+```python
+import ast
+from typing import Any
+
+# Inline implementation of extract_function
+def extract_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    file_path: str,
+    parent_class: str | None = None
+) -> dict[str, Any]:
+    """Extract structured metadata from a function or method AST node.""
+```
+
+### extract_class
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def extract_class(node: ast.ClassDef, file_path: str) -> list[dict[str, Any]]
+```
+
+Use this to parse a Python class AST node into a structured list of dictionaries containing the class definition and all its methods — ideal for building code analysis tools, documentation generators, or code indexing pipelines.
+
+Each dictionary in the returned list represents either the class itself or one of its methods, with metadata like name, docstring, line numbers, and source file path.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `no
+
+**Example:**
+```python
+import ast
+from typing import Any
+
+# Inline implementation of extract_class for a self-contained example
+def extract_class(node: ast.ClassDef, file_path: str) -> list[dict[str, Any]]:
+    """Extract a class and its methods into structured dicts."""
+    results = []
+
+    # Extract class-level entry
+ 
+```
+
+### scan_file
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/python_parser.py
+
+```
+def scan_file(file_path: str) -> dict[str, Any]
+```
+
+Use this to extract all API elements from a Python source file — functions, classes, methods, imports, and metadata — in a single structured dictionary.
+
+Ideal for building documentation generators, code analysis tools, static analyzers, or any tooling that needs to introspect a Python file programmatically.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `file_path` | `str` | ✅ Yes | Absolute or relative path to the `.py` file to scan |
+
+## Re
+
+**Example:**
+```python
+import ast
+import os
+from typing import Any
+
+# Inline implementation of scan_file
+def scan_file(file_path: str) -> dict[str, Any]:
+    """Scan a Python file and extract all API elements."""
+    result: dict[str, Any] = {
+        "file_path": file_path,
+        "functions": [],
+        "classes": [],
+```
+
+### RustScanner
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/scanner/rust.ts
+
+```
+class RustScanner implements Scanner
+```
+
+Use this to scan Rust source files and extract public API elements — functions, structs, enums, impl blocks, and traits — for automated documentation generation or API analysis pipelines.
+
+`RustScanner` implements the `Scanner` interface and targets `.rs` files, automatically skipping test files under `/tests/` directories.
+
+## Methods
+
+### `canHandle(filePath: string): boolean`
+Determines whether this scanner should process a given file.
+
+| Name | Type | Required | Description |
+|------|------|
+
+### canHandle
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/rust.ts
+
+```
+canHandle(filePath: string): boolean
+```
+
+Use this to check whether a file path should be processed by the Rust scanner before attempting to scan it. Returns `true` only for `.rs` files that are **not** inside a `/tests/` directory.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | Yes | The file path to evaluate (relative or absolute) |
+
+### Returns
+
+| Value | Condition |
+|-------|-----------|
+| `true` | Path ends with `.rs` **and** does not contain `/tests/` |
+
+
+**Example:**
+```typescript
+// Inline implementation of RustScanner.canHandle — no external imports needed
+class RustScanner {
+  languages = ['rust']
+
+  canHandle(filePath: string): boolean {
+    return /\.rs$/.test(filePath) && !filePath.includes('/tests/')
+  }
+}
+
+const scanner = new RustScanner()
+
+const testCases: Array<{ pa
+```
+
+### scanFile
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/rust.ts
+
+```
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to extract API elements from a Rust source file, parsing its contents into a structured result containing discovered elements and any errors encountered during scanning.
+
+Designed for use with non-test `.rs` files, `scanFile` reads the file at the given path and returns a `ScanResult` containing all parsed `APIElement` entries alongside any parsing errors.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Abso
+
+**Example:**
+```typescript
+import { readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// --- Inline types (mirrors the real library's types) ---
+interface Parameter {
+  name: string
+  type: string
+}
+
+interface APIElement {
+  name: string
+  kind: 'function' | 'struct' 
+```
+
+### TypeScriptScanner
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/scanner/typescript.ts
+
+```
+class TypeScriptScanner implements Scanner
+```
+
+Use this to scan TypeScript and JavaScript source files and extract API elements (functions, classes, parameters, and metadata) for automated documentation generation.
+
+`TypeScriptScanner` implements the `Scanner` interface and uses the TypeScript compiler API to parse and analyze `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files. It skips declaration files (`.d.ts`) automatically.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `languages` | `string[]`
+
+**Example:**
+```typescript
+// ─── Inline types (mirrors the real Scanner/ScanResult interface) ───────────
+
+type Parameter = {
+  name: string
+  type: string
+  required: boolean
+  description?: string
+}
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'method' | 'variable'
+  parameters?: Paramet
+```
+
+### canHandle
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/typescript.ts
+
+```
+canHandle(filePath: string): boolean
+```
+
+Use this to quickly determine whether a file path is a TypeScript/JavaScript source file that the scanner can process — filtering out declaration files (`.d.ts`) automatically.
+
+Returns `true` for `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files. Returns `false` for `.d.ts` declaration files and any other file types.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | The file path (relative or absolute) to check 
+
+**Example:**
+```typescript
+// Inline implementation matching TypeScriptScanner.canHandle behavior
+class TypeScriptScanner {
+  languages = ['typescript', 'javascript']
+
+  canHandle(filePath: string): boolean {
+    return /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) && !filePath.includes('.d.ts')
+  }
+}
+
+const scanner = new TypeS
+```
+
+### scanFile
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/typescript.ts
+
+```
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to extract API elements (functions, classes, methods, parameters) from a TypeScript or JavaScript source file for documentation generation or code analysis.
+
+`scanFile` parses a `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, or `.cjs` file and returns a structured `ScanResult` containing all discovered API elements. It automatically detects whether to treat the file as TypeScript or JavaScript based on the file extension.
+
+> **Note:** Does not handle `.d.ts` declaration files — use `canHandle()`
+
+**Example:**
+```typescript
+import { readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+
+// --- Inline types (mirrors the real ScanResult shape) ---
+type Parameter = {
+  name: string
+  type: string
+  required: boolean
+  description?: string
+}
+
+type APIElement = {
+  name: string
+  kind: 'function' |
+```
+
+### findMdxFiles
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/files.ts
+
+```
+function findMdxFiles(dir: string): string[]
+```
+
+Use this to collect all Markdown and MDX file paths from a directory tree — useful for documentation pipelines, static site generators, or any tooling that needs to process `.md`/`.mdx` content in bulk.
+
+Recursively walks a directory and returns the absolute paths of every `.md` and `.mdx` file found. Automatically skips hidden directories (e.g. `.git`), `node_modules`, and symlinks to avoid infinite loops and irrelevant files. Stops at a maximum depth of 30 levels.
+
+### Parameters
+
+| Name | Typ
+
+**Example:**
+```typescript
+import { readdirSync, statSync, lstatSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join, extname } from 'path'
+
+// Self-contained implementation of findMdxFiles
+function findMdxFiles(dir: string): string[] {
+  const files: string[] = []
+
+  function walk(currentDir: string, depth: numbe
+```
+
+### slugify
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/files.ts
+
+```
+function slugify(str: string): string
+```
+
+Use this to convert any string into a clean, URL-safe slug — stripping special characters, spaces, and leading/trailing hyphens.
+
+Ideal for generating URL paths from titles, creating file-safe identifiers, or normalizing user input for routing.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `str` | `string` | ✅ | The input string to convert into a slug |
+
+## Returns
+
+A lowercase `string` with all non-alphanumeric characters replaced by hyphens
+
+**Example:**
+```typescript
+// Inline implementation — no imports needed
+function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+// --- Example Usage ---
+
+const examples = [
+  "Hello World",
+  "My Awesome Blog Post #42!",
+  "  Leading & Trailing Spa
+```
+
+### parseFrontmatter
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/files.ts
+
+```
+function parseFrontmatter(content: string): { data: Record<string, unknown>; content: string }
+```
+
+Use this to extract structured metadata and body content from Markdown files that use YAML frontmatter blocks (delimited by `---`).
+
+This is useful when processing `.md` files that contain metadata like titles, dates, tags, or authors at the top — it splits the file into a usable data object and the remaining content body.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | `string` | ✅ | The full raw string content of a file, optional
+
+**Example:**
+```typescript
+// Inline implementation matching the real function's behavior
+function parseFrontmatter(content: string): { data: Record<string, unknown>; content: string } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!match) return { data: {}, content }
+
+  const yamlStr = m
+```
+
+### validatePath
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/validation.ts
+
+```
+function validatePath(input: string, mustExist = true): string
+```
+
+Use this to safely resolve and validate file system paths before performing file operations — preventing path traversal issues and catching missing files early.
+
+`validatePath` resolves a relative or absolute path to its canonical form and optionally checks that the path exists on disk. It guards against directory traversal attacks by flagging paths that escape the current working directory.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `inpu
+
+**Example:**
+```typescript
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+
+// Inline implementation — do not import from 'autodocs'
+function validatePath(input: string, mustExist = true): string {
+  const resolved = resolve(input)
+
+  // Warn on paths outside cwd (but allow absolute paths like /tmp)
+  if (!reso
+```
+
+### validateUrl
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/validation.ts
+
+```
+function validateUrl(input: string): string
+```
+
+Use this to validate and sanitize URL strings before making HTTP requests or storing user-provided URLs. Ensures the input is a well-formed URL with a safe protocol (`http:` or `https:`), throwing descriptive errors for invalid input.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | ✅ | The URL string to validate. Must be a well-formed URL using `http:` or `https:` protocol. |
+
+## Returns
+
+| Condition | Result |
+|-----------
+
+**Example:**
+```typescript
+// Inline implementation of validateUrl — no external imports needed
+function validateUrl(input: string): string {
+  try {
+    const url = new URL(input)
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw new Error(`Invalid protocol: ${url.protocol}`)
+    }
+    return input
+  } catch
+```
+
+### validateSlug
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/validation.ts
+
+```
+function validateSlug(input: string): string
+```
+
+Use this to validate that a string is a safe slug before using it in URLs, file paths, or database identifiers. Throws immediately if the input contains invalid characters, so you can catch bad data early.
+
+**Validation rule:** Only alphanumeric characters (`a-z`, `A-Z`, `0-9`), hyphens (`-`), and underscores (`_`) are allowed. Spaces, dots, slashes, and any other special characters will cause a throw.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|----------
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function validateSlug(input: string): string {
+  if (!/^[a-zA-Z0-9_-]+$/.test(input)) {
+    throw new Error(
+      `Invalid slug: ${input}. Only alphanumeric, hyphens, and underscores allowed.`
+    )
+  }
+  return input
+}
+
+// --- Valid slug exampl
+```
+
+### sanitizeForShell
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/utils/validation.ts
+
+```
+function sanitizeForShell(input: string): string
+```
+
+Use this to validate and sanitize strings before passing them to shell commands, git operations, or filesystem paths — preventing command injection and unsafe character exploits.
+
+Accepts an input string and throws immediately if it contains any characters outside the safe allowlist (`a-z`, `A-Z`, `0-9`, `/`, `_`, `~`, `.`, `^`, `@`, `{`, `}`, `-`). Returns the original string unchanged if it passes validation.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|--
+
+**Example:**
+```typescript
+// Inline implementation — no external imports needed
+function sanitizeForShell(input: string): string {
+  // Only allow safe characters for git refs, filenames, etc.
+  if (!/^[a-zA-Z0-9/_~.^@{}\-]+$/.test(input)) {
+    throw new Error(`Unsafe characters in input: ${input}`)
+  }
+  return input
+}
+
+//
+```
+