skrypt-ai 0.3.4 → 0.4.1

package/dist/template/src/app/docs/llms.txt

@@ -0,0 +1,2971 @@
+# Skrypt
+
+> API documentation for Skrypt
+
+## Overview
+
+This project contains 81 documented API elements across 14 modules.
+
+## Quick Reference
+
+### index
+
+- `getAuthConfig`: function - Use this to retrieve the current authentication configuration from the local auth file
+- `saveAuthConfig`: function - Use this to persist authentication credentials to a local config file, ensuring the config directory
+- `clearAuth`: function - Use this to log a user out by wiping stored authentication credentials from the local config file
+- `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 — it checks the user's auth config and print
+- `isProCommand`: function - Use this to check whether a given CLI command requires a Pro subscription before executing it, enabl
+- `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 and catch errors before execution, without needing a Python 
+- `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, register, and execute documentation plugins that transform or extend your build pi
+- `constructor`: method - Use this to initialize a `PluginManager` that coordinates documentation plugins, wiring together you
+- `loadPlugins`: method - Use this to initialize and load plugins into a `PluginManager` instance from a configuration file, e
+- `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' `onBeforeScan` lifecycle hook — ideal for running pre-sc
+- `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 set of generated documenta
+- `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 type-safe plugin configuration object for the Skrypt plugin system
+- `scanDirectory`: function - Use this to recursively scan a directory (or single file) and extract all API elements — functions, 
+- `scanFile`: function - Use this to analyze a single source file and extract structured metadata — functions, classes, types
+
+### 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 a configuration file for autodocs, either from a specific path or by auto-discoveri
+- `validateConfig`: function - Use this to validate a configuration object before using it, catching all errors upfront instead of 
+- `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 using an LLM client, without running any
+- `generateForElements`: function - Use this to batch-generate documentation for multiple API elements in a single call, processing an e
+- `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 — for example, when one
+- `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 convert an array of documentation topics into a sidebar navigation configuration compati
+- `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 API documentation, making it discoverable and consu
+- `writeDocsToDirectory`: function - Use this to persist generated documentation to disk, writing markdown files into an output directory
+- `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 issue summaries as review comments on GitHub Pull Reque
+- `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
+
+### anthropic-client
+
+- `AnthropicClient`: class - Use this to send completion requests to Anthropic's Claude models with automatic retry logic and a s
+- `constructor`: method - Use this to create an Anthropic-backed LLM client for sending completion requests, with built-in ret
+- `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 a unified LLM client that connects to any OpenAI-compatible API provider (OpenAI,
+- `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 should be documen
+- `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 list of API elements into a recommended documentation structure
+- `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 given file path should be processed by the Python scanner before
+- `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 parsed AST components — usef
+- `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 AST `ClassDef` node and extract structured metadata about a class and all
+- `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 quickly determine whether a given file path should be processed by the Rust scanner befo
+- `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 check whether a file path is a TypeScript/JavaScript source file that the scanne
+- `scanFile`: method - Use this to extract API elements (functions, classes, interfaces, types) from a TypeScript or JavaSc
+
+## API Details
+
+### getAuthConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+function getAuthConfig(): AuthConfig
+```
+
+Use this to retrieve the current authentication configuration from the local auth file. This is the primary way to check if a user is logged in, access their stored credentials, or verify token expiration before making API calls.
+
+Returns an `AuthConfig` object with the user's stored auth data, or an empty object `{}` if no auth file exists yet (unauthenticated state).
+
+## Parameters
+
+This function takes no parameters.
+
+## Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| 
+
+**Example:**
+```typescript
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// Inline the AuthConfig type
+type AuthConfig = {
+  token?: string
+  email?: string
+  expiresAt?: string
+  error?: string
+}
+
+// Inline the auth file path logic (mirrors the real implementation)
+co
+```
+
+### saveAuthConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+function saveAuthConfig(config: AuthConfig): void
+```
+
+Use this to persist authentication credentials to a local config file, ensuring the config directory exists before writing.
+
+Saves an `AuthConfig` object as formatted JSON to a file on disk. Automatically creates any missing parent directories in the config path before writing, so you don't need to pre-create the directory structure.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| config | `AuthConfig` | ✅ | Authentication configuration object
+
+**Example:**
+```typescript
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline type definition ---
+interface AuthConfig {
+  token: string
+  userId: string
+  expiresAt?: number
+  refreshToken?: string
+}
+
+// --- Inline config path consta
+```
+
+### clearAuth
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+function clearAuth(): void
+```
+
+Use this to log a user out by wiping stored authentication credentials from the local config file. Calling this resets the auth file to an empty state (`{}`) without deleting the file itself — safe to call even if no credentials have been saved yet.
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`void` — no return value. The auth config file is overwritten with `{}` if it exists; if no file is found, the function exits silently.
+
+**Behavior**
+- ✅ Auth file exists → contents replaced with `{}`
+- ✅ Auth fil
+
+**Example:**
+```typescript
+import { existsSync, writeFileSync, readFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline config (mirrors autodocs internals) ---
+const CONFIG_DIR = join(homedir(), '.config', 'autodocs-demo')
+const AUTH_FILE = join(CONFIG_DIR, 'auth.json')
+
+type
+```
+
+### 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.
+
+`checkPlan` hits the `/v1/plan` endpoint with a Bearer token and returns plan metadata — useful for gating features, displaying plan info to users, or validating credentials at startup.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `apiKey` | `string` | ✅ Yes | The Bearer token used to authenticate against the API |
+
+## Ret
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type PlanCheckResponse = {
+  plan: string
+  valid: boolean
+  limits?: {
+    requests: number
+    storage: number
+  }
+  error?: string
+}
+
+// Self-contained implementation mirroring the real checkPlan behavior
+async function checkPlan(apiKey: string): Promi
+```
+
+### 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 — it checks the user's auth config and prints a helpful upgrade message if they're not on a paid plan.
+
+Call `requirePro` at the top of any command handler that requires a Pro account. It returns `true` if the user is authorized to proceed, or `false` (after printing an error) if they are not.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `commandName` | `string` | ✅ | The name of the CL
+
+**Example:**
+```typescript
+import * as fs from 'fs'
+import * as path from 'path'
+import * as os from 'os'
+
+// --- Inline types and helpers (self-contained, no external imports) ---
+
+type AuthConfig = {
+  apiKey: string | null
+}
+
+type LicenseStatus = {
+  valid: boolean
+  plan: 'free' | 'pro'
+  email: string
+  error?: string
+}
+
+```
+
+### isProCommand
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/auth/index.ts
+
+```
+function isProCommand(command: string): boolean
+```
+
+Use this to check whether a given CLI command requires a Pro subscription before executing it, enabling you to gate features and show appropriate upgrade prompts.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| command | string | Yes | The CLI command name to check against the list of Pro-only commands |
+
+## Returns
+
+- **`true`** — the command is Pro-only and requires an upgraded account
+- **`false`** — the command is available on the free tier
+
+**Example:**
+```typescript
+// Define the Pro commands list inline (mirrors the source)
+const PRO_COMMANDS = ['gh-action', 'ci', 'mcp']
+
+// Inline implementation of isProCommand
+function isProCommand(command: string): boolean {
+  return PRO_COMMANDS.includes(command)
+}
+
+// Simulate a user running a CLI command
+function runComm
+```
+
+### 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 is valid or the maximum retry limit is reached.
+
+This is ideal for CI pipelines, documentation generators, or developer tools that need to ensure code examples stay compilable and correct as APIs evolve.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `example` | `CodeExample` | ✅ | The code example to fix, including its sou
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type CodeExample = {
+  code: string
+  language: string
+  errorContext?: string
+}
+
+type AutoFixOptions = {
+  maxIterations?: number
+}
+
+type FixResult = {
+  success: boolean
+  fixedCode: string | null
+  iterations: number
+
+```
+
+### 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 examples that need validation and repair, such as during a documentation build pipeline or CI check.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `examples` | `CodeExample[]` | ✅ Yes | Array of code examples to fix, each w
+
+**Example:**
+```typescript
+// ── Inline types (do not import from autodocs) ──────────────────────────────
+
+type CodeExample = {
+  code: string
+  language?: string
+  filename?: string
+}
+
+type FixResult = {
+  fixed: boolean
+  code: string
+  error?: string
+  attempts: number
+}
+
+type AutoFixOptions = {
+  maxRetries?: number
+  la
+```
+
+### 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 that accepts a TypeScript code string and resolves with a `ValidationResult` indicating whether the code is valid and any diagnostic errors found.
+
+## Parameters
+
+This factory function takes no parameters.
+
+## Returned Validator Function
+
+| Name | Type | Required | Description |
+|------|------|-
+
+**Example:**
+```typescript
+import * as ts from 'typescript'
+
+// --- Inline types (do not import from autodocs) ---
+interface ValidationResult {
+  valid: boolean
+  errors: string[]
+}
+
+// --- Inline implementation matching the library's behavior ---
+function createTypeScriptValidator(): (code: string) => Promise<ValidationResul
+```
+
+### createPythonValidator
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/autofix/index.ts
+
+```
+function createPythonValidator(): (code: string) => Promise<ValidationResult>
+```
+
+Use this to validate Python code syntax and catch errors before execution, without needing a Python runtime wrapper or external validation service — just `python3` in your PATH.
+
+Returns a reusable validator function you can call repeatedly with different code strings. Each call spawns a `python3` process to perform real syntax checking.
+
+## Parameters
+
+This factory function takes no parameters.
+
+## Returns
+
+| Return | Type | Description |
+|--------|------|-------------|
+| validator | `(code: st
+
+**Example:**
+```typescript
+import { spawnSync } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// Inline the ValidationResult type (matches the library's shape)
+type ValidationResult = {
+  valid: boolean
+  errors: string[]
+}
+
+// Self-contained imple
+```
+
+### 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`).
+
+Returns the **full path** to the first matching config file found, or `null` if none exist in the given directory. Useful for resolving config before initializing your toolchain, or for validating that a project is properly configured.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|---
+
+**Example:**
+```typescript
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+// Supported config filenames (in priority order)
+const CONFIG_FILENAMES = ['.skrypt.yaml', '.skrypt.yml', 'skrypt.yaml', 'skrypt.yml']
+
+// Inline implementation of findConfigFile
+function findConfigFile(dir: string): string | null {
+  for
+```
+
+### loadConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/config/loader.ts
+
+```
+function loadConfig(configPath?: string): Config
+```
+
+Use this to load a configuration file for autodocs, either from a specific path or by auto-discovering it from standard locations in your project.
+
+Searches for config files in common locations (e.g., `autodocs.config.yml`, `.autodocs.yml`) when no path is provided. Throws an error if an explicit path is given but the file does not exist.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `configPath` | `string` | No | Absolute or relative path t
+
+**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: string[]
+  exclude: string[]
+```
+
+### 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 instead of failing at runtime.
+
+Returns an array of error message strings — an empty array means the config is valid. Each string describes a specific validation failure, making it easy to surface all problems at once rather than one at a time.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| config | `Config` | ✅ | The configuration object to validate |
+
+#
+
+**Example:**
+```typescript
+// Inline type definition — mirrors the real Config shape
+type LLMProvider = 'openai' | 'anthropic' | 'gemini'
+
+type Config = {
+  version: number
+  provider?: LLMProvider
+  apiKey?: string
+  outputDir?: string
+  license?: string
+}
+
+// Inline implementation — mirrors the real validation logic
+functio
+```
+
+### 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). Use this at startup or before inference calls to give users clear, actionable feedback when credentials are missing.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|--------
+
+**Example:**
+```typescript
+// Inline types — do not import from autodocs
+type LLMProvider = 'openai' | 'anthropic' | 'ollama' | 'gemini'
+
+// Maps each provider to its required environment variable (null = no key needed)
+const PROVIDER_ENV_KEYS: Record<LLMProvider, string | null> = {
+  openai: 'OPENAI_API_KEY',
+  anthropic: 'A
+```
+
+### 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 using an LLM client, without running any test validation on the output.
+
+This is the core documentation generation function — pass it a parsed API element (function, class, type, etc.), an LLM client, and generation options to receive structured documentation. Optionally track progress in real time via the `onProgress` callback.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `element`
+
+**Example:**
+```typescript
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type'
+  signature: string
+  docstring?: string
+  filePath: string
+}
+
+type GenerationOptions = {
+  model: string
+  style: 'concise' | 'deta
+```
+
+### 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 entire scanned API surface and returning structured docs for each element.
+
+This is the primary entry point for bulk documentation generation — pass in your parsed API elements, an LLM client, and generation options to get back a full array of generated documentation objects.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `APIElement
+
+**Example:**
+```typescript
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'type' | 'interface' | 'variable'
+  signature: string
+  docstring?: string
+  filePath: string
+}
+
+type GeneratedDoc = {
+  elementName: string
+  kind: APIE
+```
+
+### 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 site.
+
+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 containi
+
+**Example:**
+```typescript
+// ---- Inline types (mirrors the real GeneratedDoc / APIElement shape) ----
+type ElementKind = 'function' | 'class' | 'method'
+
+interface APIElement {
+  name: string
+  kind: ElementKind
+  signature?: string
+}
+
+interface GeneratedDoc {
+  element: APIElement
+  documentation: string
+}
+
+// ---- Inline 
+```
+
+### 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 sidebars, or categorized API references.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | Yes | Array of generated documentation objects to organize |
+| `config` | `TopicConfig` | No | Configuration controlling how topics are detected and grouped. Defaults to `DEFAULT_TOPI
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type GeneratedDoc = {
+  id: string
+  title: string
+  topic: string
+  content: string
+  slug: string
+}
+
+type Topic = {
+  label: string
+  slug: string
+  docs: GeneratedDoc[]
+}
+
+type TopicConfig = {
+  defaultTopic: string
+ 
+```
+
+### 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 — for example, when one function references another by name in its parameters, return type, or description.
+
+Given an array of generated documentation objects, this scans each element and identifies where one doc references another by name, returning a flat list of directed cross-references you can use to build navigation links, dependency graphs, or "See Also" sections.
+
+## Parameters
+
+| Name | Type | Required | Descri
+
+**Example:**
+```typescript
+// ─── Inline types (do NOT import from autodocs) ───────────────────────────────
+
+type DocElement = {
+  name: string;
+  params?: { type: string }[];
+  returnType?: string;
+  description?: string;
+};
+
+type GeneratedDoc = {
+  element: DocElement;
+  topics: string[];
+};
+
+type CrossReference = {
+  from
+```
+
+### 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 navigation, dependency graphs, or "see also" sections for a given function, class, or module.
+
+Given an element name and a full list of cross-references, it returns only the references where `fromElement` matches the provided name.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elementName` | `string` | ✅ | The name of 
+
+**Example:**
+```typescript
+// Inline the CrossReference type (matches the real shape from autodocs)
+type CrossReference = {
+  fromElement: string
+  toElement: string
+  description?: string
+}
+
+// Inline the function implementation
+function getCrossRefsForElement(
+  elementName: string,
+  allRefs: CrossReference[]
+): CrossRefer
+```
+
+### 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.
+
+Given an array of `Topic` objects (each containing an ID, name, and associated docs), `buildNavigation` returns a nested `NavigationItem[]` where each top-level item maps to a topic and its children map to individual documented elements.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topics`
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type DocElement = {
+  name: string;
+  description?: string;
+};
+
+type GeneratedDoc = {
+  element: DocElement;
+  markdown: string;
+};
+
+type Topic = {
+  id: string;
+  name: string;
+  docs: GeneratedDoc[];
+};
+
+type Navigatio
+```
+
+### generateSidebarConfig
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/generator/organizer.ts
+
+```
+function generateSidebarConfig(topics: Topic[]): object
+```
+
+Use this to convert an array of documentation topics into a sidebar navigation configuration compatible with multiple documentation platforms (Mintlify, Docusaurus, etc.).
+
+The function maps each topic to a navigation group, with its documents as slugified page paths in the format `topicId/doc-name`.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topics` | `Topic[]` | ✅ | Array of topic objects, each containing an `id`, `name`, and `docs` arr
+
+**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 helper (mirrors the real implementation) ───────────
+```
+
+### 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 the resulting config is always complete and valid.
+
+This is useful when users supply only a subset of configuration options (e.g., overriding a few topics) and you need to fill in the rest from sensible defaults without losing any required fields.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `userConfig` | `Partial<TopicConfig>` | Yes | The
+
+**Example:**
+```typescript
+// Inline types (no external imports needed)
+type Topic = {
+  label: string
+  description: string
+  color?: string
+}
+
+type TopicConfig = {
+  topics: Record<string, Topic>
+}
+
+// Simulate DEFAULT_TOPIC_CONFIG
+const DEFAULT_TOPIC_CONFIG: TopicConfig = {
+  topics: {
+    general: {
+      label: 'General'
+```
+
+### 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 API documentation, making it discoverable and consumable by LLM-powered answer engines following the [llmstxt.org](https://llmstxt.org) convention.
+
+This is particularly useful for Answer Engine Optimization (AEO) — the equivalent of SEO but for AI assistants and LLM-based search tools.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | Yes | Array of generated documentat
+
+**Example:**
+```typescript
+import { mkdir, writeFile } from 'fs/promises'
+import { join } from 'path'
+import * as os from 'os'
+import * as path from 'path'
+
+// --- Inline types (mirrors the real GeneratedDoc shape) ---
+type GeneratedDoc = {
+  filePath: string
+  elementName: string
+  content: string
+  description?: string
+}
+
+/
+```
+
+### 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, writing markdown files into an output directory while preserving the relative structure of your source directory.
+
+After generating docs for your source files, pass the results to this function to write them out as organized markdown files. It handles directory creation automatically and maps each source file to a corresponding output path.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `re
+
+**Example:**
+```typescript
+import { mkdir, writeFile } from 'fs/promises'
+import { join, dirname, relative, basename } from 'path'
+
+// --- Inline types (mirrors autodocs internals) ---
+interface GeneratedDoc {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type'
+  markdown: string
+}
+
+interface FileGenerationResu
+```
+
+### 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 file-keyed structure so you can iterate over files and write each one independently.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | 
+
+**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: Date
+```
+
+### 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.
+
+Instead of dumping all docs into a flat directory, `writeDocsByTopic` automatically clusters your `GeneratedDoc` entries by topic and writes each one into the appropriate subfolder, returning a summary of what was written.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|-----
+
+**Example:**
+```typescript
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+// ── Inline types (mirrors autodocs internals) ────────────────────────────────
+
+type GeneratedDoc = {
+  elementName: string
+  topic: string
+  filePath: string
+  markdown: string
+}
+
+type Topic = {
+  name: string
+  slug: strin
+```
+
+### 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 issue summaries as review comments on GitHub Pull Requests — ideal for CI pipelines that lint or validate docs on every PR.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | GitHub connection details including repo owner, repo name, PR number, and optional auth token |
+| `issues` | `DocumentationIssue[]` | Yes | Array of documentation issues to summarize in the PR c
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type PRCommentConfig = {
+  owner: string
+  repo: string
+  prNumber: number
+  token?: string
+}
+
+type DocumentationIssue = {
+  file: string
+  line?: number
+  message: string
+  severity: 'error' | 'warning'
+}
+
+type CommentR
+```
+
+### 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 attaches each as an inline comment to the relevant file and line in a PR — ideal for automated doc linters, CI checks, or code review bots.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | PR tar
+
+**Example:**
+```typescript
+// ── Inline type definitions (no external imports needed) ──────────────────────
+
+type PRCommentConfig = {
+  token?: string
+  owner: string
+  repo: string
+  pullNumber: number
+  commitSha: string
+}
+
+type DocumentationIssue = {
+  file: string
+  line: number
+  message: string
+}
+
+type CommentResult = 
+```
+
+### 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.
+
+Accepts a `PRCommentConfig` object describing the GitHub PR to analyze, plus optional flags to control analysis depth. Returns a list of `DocumentationIssue` objects, each describing a specific documentation problem found in the PR's changed files.
+
+### Parameters
+
+| Name | Type | Required | Description 
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+type PRCommentConfig = {
+  token?: string
+  owner: string
+  repo: string
+  prNumber: number
+}
+
+type DocumentationIssue = {
+  file: string
+  line: number
+  severity: 'error' | 'warning' | 'info'
+  message: string
+  rule: string
+}
+
+// --- Simulated
+```
+
+### AnthropicClient
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/llm/anthropic-client.ts
+
+```
+class AnthropicClient implements LLMClient
+```
+
+Use this to send completion requests to Anthropic's Claude models with automatic retry logic and a standardized LLM interface.
+
+`AnthropicClient` wraps the Anthropic SDK and implements the `LLMClient` interface, giving you a consistent way to interact with Claude models alongside other LLM providers in your application.
+
+## Constructor Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.model` | `string` | Yes | The Claude model to use (e.g. `"
+
+**Example:**
+```typescript
+// ─── Inline types (no imports from autodocs) ───────────────────────────────
+
+type LLMProvider = 'anthropic' | 'openai' | 'gemini'
+
+interface LLMClientConfig {
+  model: string
+  maxRetries?: number
+  apiKey?: string
+}
+
+interface CompletionRequest {
+  messages: Array<{ role: 'user' | 'assistant'; c
+```
+
+### constructor
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/llm/anthropic-client.ts
+
+```
+constructor(config: LLMClientConfig)
+```
+
+Use this to create an Anthropic-backed LLM client for sending completion requests, with built-in retry logic and model configuration.
+
+The `AnthropicClient` constructor initializes a client that wraps the Anthropic SDK, binding it to a specific model and API key. It defaults to 3 retries on failure unless overridden.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `LLMClientConfig` | ✅ | Configuration object for the client |
+| `conf
+
+**Example:**
+```typescript
+// Inline types — no library imports needed
+type LLMProvider = 'anthropic' | 'openai'
+
+interface LLMClientConfig {
+  apiKey: string
+  model: string
+  maxRetries?: number
+}
+
+interface CompletionRequest {
+  prompt: string
+  maxTokens?: number
+}
+
+interface CompletionResponse {
+  text: string
+  model: s
+```
+
+### 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 submitting requests in workflows where client configuration may be conditional or deferred.
+
+**Returns**
+
+| Value | Condition |
+|-------|-----------|
+| `true` | Always — the client is initiali
+
+**Example:**
+```typescript
+// Inline types to simulate AnthropicClient behavior
+interface LLMClientConfig {
+  apiKey: string
+  model?: string
+  timeout?: number
+  maxRetries?: number
+}
+
+// Simulated AnthropicClient class
+class AnthropicClient {
+  private apiKey: string
+  private model: string
+  private timeout: number
+  priva
+```
+
+### 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 message history automatically.
+
+This method separates system messages from conversation messages internally, so you can pass a unified message array without pre-processing. It falls back to the client's default model if none is specified in the request.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `request` |
+
+**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 retry and timeout handling built in.
+
+This is your entry point for all LLM interactions — call it once at startup and reuse the returned `LLMClient` throughout your application.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.provider` | `LLMProvider` | ✅ Yes | The AI provider to use. Accepted values: `"openai"`, `"anthropic"`, `"azure"` 
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+type LLMProvider = "openai" | "anthropic" | "azure"
+
+interface LLMClientConfig {
+  provider: LLMProvider
+  model: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+}
+
+interface ChatMessage {
+  role: "user" | "assistant" | "system
+```
+
+### 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.
+
+Takes a configured LLM client and a code element's context, then returns structured documentation output — useful for automating doc generation pipelines or IDE tooling.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `LLMClient` | ✅ Yes | A configured LLM client instance (e.
+
+**Example:**
+```typescript
+// ── Inline type definitions (no external imports needed) ──────────────────────
+
+type ElementKind = 'function' | 'class' | 'method' | 'interface'
+
+interface ElementContext {
+  name: string
+  kind: ElementKind
+  signature: string
+  sourceCode: string
+  filePath: string
+  language: string
+}
+
+interfa
+```
+
+### 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 iterative code generation pipelines where generated code fails validation or execution.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `LLMClient` | Yes | An initialized LLM client instance used to send the fix request |
+| `code` | `string` | Yes | The broken code sample that needs to be 
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+interface LLMMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+interface LLMClient {
+  complete(messages: LLMMessage[]): Promise<string>
+}
+
+// --- Inline implementation of fixCodeSample ---
+async function fixCodeSample(
+  cli
+```
+
+### 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 a unified LLM client that connects to any OpenAI-compatible API provider (OpenAI, Anthropic, Mistral, local models, etc.) with automatic retry logic and provider-specific configuration.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `LLMClientConfig` | Yes | Configuration object for the LLM client |
+| `config.provider` | `LLMProvider` | Yes | The LLM provider identifier (e.g., `'openai'`, `'mistral'`, `'anthropic'
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type LLMProvider = 'openai' | 'mistral' | 'anthropic' | 'local'
+
+interface LLMClientConfig {
+  provider: LLMProvider
+  model: string
+  apiKey: string
+  baseUrl?: string
+  maxRetries?: number
+}
+
+const PROVIDER_BASE_URLS: 
+```
+
+### 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 follow a consistent "is configured?" pattern across multiple LLM client types.
+
+### Returns
+
+| Condition | Value |
+|-----------|-------|
+|
+
+**Example:**
+```typescript
+// Inline types to simulate the OpenAICompatibleClient behavior
+type LLMProvider = 'openai' | 'azure' | 'groq' | 'custom'
+
+interface LLMClientConfig {
+  apiKey: string
+  provider: LLMProvider
+  model?: string
+  baseURL?: string
+}
+
+// Simulated OpenAICompatibleClient
+class OpenAICompatibleClient {
+  
+```
+
+### 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
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type Message = { role: 'system' | 'user' | 'assistant'; content: string }
+
+type CompletionRequest = {
+  messages: Message[]
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  systemPrompt?: string
+}
+
+type Com
+```
+
+### PluginManager
+
+**Type:** class
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+class PluginManager
+```
+
+Use this to load, register, and execute documentation plugins that transform or extend your build pipeline's source and output processing.
+
+`PluginManager` orchestrates a collection of `SkryptPlugin` instances, providing each plugin with a shared context (paths, config, and a logger) so plugins can coordinate without direct coupling.
+
+## Constructor Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sourcePath` | `string` | Yes | Absolute or relative
+
+**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 `PluginManager` that coordinates documentation plugins, wiring together your source code directory, output destination, and any custom configuration options before plugins are registered and executed.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sourcePath` | `string` | ✅ Yes | Absolute or relative path to the source code directory to be documented |
+| `outputPath` | `string` | ✅ Yes | Absolute or relative path to t
+
+**Example:**
+```typescript
+// --- Inline types (mirroring autodocs internals) ---
+type Logger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+type PluginContext = {
+  sourcePath: string
+  outputPath: string
+  config: Record<string, unknown>
+  logger: Logger
+}
+
+type SkryptPlugi
+```
+
+### 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 a `PluginManager` instance from a configuration file, enabling dynamic plugin discovery at startup.
+
+This method reads from a `skrypt.config.js` or `skrypt.config.ts` file (auto-detected if no path is provided) and registers all declared plugins into the manager. Call it once during application bootstrap before executing any plugin-dependent logic.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `co
+
+**Example:**
+```typescript
+// Inline types to simulate PluginManager behavior
+type Logger = {
+  info: (msg: string) => void
+  error: (msg: string) => void
+}
+
+type Plugin = {
+  name: string
+  setup: () => void
+}
+
+type PluginConfig = {
+  plugins: Plugin[]
+}
+
+// Simulated PluginManager class (self-contained, no external imports)
+```
+
+### 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 programmatic alternative to loading plugins from disk — ideal for built-in plugins, testing, or dynamically constructed plugin objects.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `plugin` | `SkryptPlugin` | ✅ Yes | The plugin object to register. Must have at l
+
+**Example:**
+```typescript
+// Inline type definitions (no external imports needed)
+type SkryptPlugin = {
+  name: string
+  version?: string
+  onBuildStart?: (...args: unknown[]) => unknown
+  onBuildEnd?: (...args: unknown[]) => unknown
+}
+
+// Inline PluginManager implementation
+class PluginManager {
+  private plugins: SkryptPlu
+```
+
+### 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. This enables a plugin pipeline where each plugin can transform or augment the result before passing it to the next.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `hook` | `keyof SkryptPlugin` | Yes | The name of the hook method to invoke on each registered plugin (e.g., `'beforeCompile'`, `'afterCompile'
+
+**Example:**
+```typescript
+// --- Inline types (do not import from autodocs) ---
+interface SkryptPlugin {
+  name: string
+  version?: string
+  beforeCompile?: (...args: unknown[]) => Promise<string> | string
+  afterCompile?: (...args: unknown[]) => Promise<string> | string
+  transform?: (...args: unknown[]) => Promise<string> 
+```
+
+### 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 — typically called once at application startup before any scanning or processing begins.
+
+When invoked, `onInit` runs the `'onInit'` hook on every registered plugin that implements it, allowing plugins to set up connections, load configuration, or prepare internal state.
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `Pro
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type PluginHook = () => Promise<void>
+
+interface Plugin {
+  name: string
+  onInit?: PluginHook
+  onBeforeScan?: PluginHook
+}
+
+// Simulated PluginManager class matching the real implementation's behavior
+class PluginManager {
+  private plugins: Plugin[] = 
+```
+
+### onBeforeScan
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+async onBeforeScan(): Promise<void>
+```
+
+Use this to trigger all registered plugins' `onBeforeScan` lifecycle hook — ideal for running pre-scan setup logic (e.g., clearing caches, validating config, preparing output directories) before your autodocs scan begins.
+
+This method iterates over every loaded plugin and calls their `onBeforeScan` handler in sequence. It resolves when all hooks have completed, making it safe to `await` before starting a scan.
+
+### Parameters
+
+_None_
+
+### Returns
+
+| Type | Description |
+|------|-------------|
+| 
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager behavior
+type Plugin = {
+  name: string
+  onBeforeScan?: () => Promise<void>
+}
+
+// Simulated PluginManager class (self-contained, no external imports)
+class PluginManager {
+  private plugins: Plugin[]
+
+  constructor(plugins: Plugin[]) {
+    this.plugins 
+```
+
+### 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 `PluginManager` after the scan phase 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[]> | T[]
+}
+
+type ScannedFile = {
+  path: string
+  exported: boolean
+  tags: string[]
+}
+
+// Simulated PluginManager with onAfterScan
+class PluginManager {
+  private 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 last chance to filter, transform, enrich, or reorder elements before the generation pipeline processes them.
+
+If no plugin modifies the elements (or no plugins are registered), the original array is returned unchanged.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `T[]` | Yes | The
+
+**Example:**
+```typescript
+// Inline types — no external imports needed
+type HookName = 'onBeforeGenerate' | 'onAfterGenerate' | 'onAfterScan'
+
+interface Plugin {
+  name: string
+  onBeforeGenerate?: <T>(elements: T[]) => Promise<T[]>
+}
+
+interface DocElement {
+  name: string
+  kind: 'function' | 'class' | 'interface'
+  isInter
+```
+
+### 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 set of generated documentation objects, allowing plugins to transform, filter, or enrich docs immediately after generation but before they are written to disk.
+
+This is the second lifecycle hook in the documentation pipeline:
+1. `onBeforeGenerate` → elements are prepared
+2. **`onAfterGenerate`** → generated docs are post-processed ← you are here
+3. `onBeforeWrite` → docs are finalized before writing
+
+If no plugin hook modi
+
+**Example:**
+```typescript
+// Inline types to simulate the PluginManager behavior
+type Hook<T> = (data: T) => Promise<T> | T
+
+interface Plugin {
+  onAfterGenerate?: Hook<any[]>
+}
+
+interface GeneratedDoc {
+  id: string
+  title: string
+  content: string
+  tags?: string[]
+}
+
+// Simulated PluginManager with onAfterGenerate suppor
+```
+
+### 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 opportunity in the pipeline to mutate documentation objects before persistence. Each plugin in the manager can modify the array; if no plugin handles the hook, the original array is returned unchanged.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|--
+
+**Example:**
+```typescript
+// Inline types to keep example self-contained
+type Doc = {
+  id: string
+  title: string
+  content: string
+  slug?: string
+  writtenAt?: string
+}
+
+type Hook = 'onBeforeWrite' | 'onAfterGenerate' | 'onAfterWrite'
+
+type Plugin = {
+  name: string
+  hooks?: Partial<Record<Hook, (data: unknown) => unknow
+```
+
+### 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>
+
+interface Plugin {
+  name: string
+  hooks: Record<string, Hook>
+}
+
+// Simulated PluginManager with onAfterWrite
+class PluginManager {
+  private plugins: Plugin[] = []
+
+  register(plugin: Plugin): voi
+```
+
+### 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.
+
+`transformContent` iterates over all registered plugins in order, passing the current content string to each plugin's `transformContent` method. The output of each plugin becomes the input for the next, making it a sequential transformation pipeline. If a plugin doesn't implement `transformContent`, it is skipped.
+
+## Parameters
+
+| Name | Type | Required | Descr
+
+**Example:**
+```typescript
+// Inline plugin interface — no external imports needed
+interface Plugin {
+  name: string;
+  transformContent?: (content: string, filePath: string) => Promise<string>;
+}
+
+// Inline PluginManager implementation
+class PluginManager {
+  private plugins: Plugin[] = [];
+
+  register(plugin: Plugin): void 
+```
+
+### definePlugin
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/plugins/index.ts
+
+```
+function definePlugin(plugin: SkryptPlugin): SkryptPlugin
+```
+
+Use this to define a type-safe plugin configuration object for the Skrypt plugin system. This is an identity function that provides TypeScript type inference and autocompletion when authoring plugins, ensuring your plugin object conforms to the `SkryptPlugin` interface at compile time.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| plugin | `SkryptPlugin` | ✅ | The plugin configuration object to validate and return |
+
+### Returns
+
+Returns the
+
+**Example:**
+```typescript
+// Inline the SkryptPlugin type (do not import from autodocs)
+type SkryptPlugin = {
+  name: string
+  version?: string
+  setup?: (context: Record<string, unknown>) => void | Promise<void>
+  teardown?: () => void | Promise<void>
+  hooks?: {
+    beforeRun?: () => void
+    afterRun?: (result: unknown) =
+```
+
+### 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 should be documented as an API reference, a guide, or a tutorial — so you can route elements to the correct documentation generator automatically.
+
+This function analyzes an `APIElement` and returns a `ContentClassification` indicating the most appropriate documentation style, along with reasoning scores and explanations for the decision.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----
+
+**Example:**
+```typescript
+// ---- Inline types (do not import from autodocs) ----
+type APIElementKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'enum'
+
+interface APIElement {
+  name: string
+  kind: APIElementKind
+  description?: string
+  parameters?: { name: string; type: string; description?: string }[]
+ 
+```
+
+### 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 (no external imports needed) ──────────────────────────────
+
+type ContentType = 'api' | 'guide' | 'tutorial' | 'overview'
+
+interface APIElement {
+  id: string
+  title: string
+  kind: ContentType
+  tags?: string[]
+}
+
+// ── Inline implementation matching the real function's behavior
+```
+
+### 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 list of API elements into a recommended documentation structure — grouping them into logical sections (API reference, guides, tutorials, overviews) and providing a count breakdown by content type.
+
+This is ideal when you have a mixed set of API elements and want a ready-made layout for generating a documentation site or navigation structure.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `APIEl
+
+**Example:**
+```typescript
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type ContentType = 'api' | 'guide' | 'tutorial' | 'overview'
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type' | 'variable' | 'module'
+  description?: string
+  tags?: string[]
+}
+
+typ
+```
+
+### 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 pass the right instructions to an LLM when auto-generating docs for APIs, components, functions, or other code elements.
+
+This function acts as a prompt router — given a content type identifier, it returns a tailored prompt string that instructs a documentation generator on what to include and how to format the output for that specific type.
+
+### Parameters
+
+| Name | Type | Required | Desc
+
+**Example:**
+```typescript
+// Inline the ContentType definition — no external imports needed
+type ContentType = 'api' | 'component' | 'function' | 'class'
+
+// Self-contained implementation matching the autodocs behavior
+function getPromptForContentType(type: ContentType): string {
+  switch (type) {
+    case 'api':
+      retur
+```
+
+### 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 useful when routing files through a scanner pipeline, letting you skip unsupported or test files before attempting a full scan.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the file being evaluated |
+
+### Returns
+
+| Va
+
+**Example:**
+```typescript
+// Inline implementation of GoScanner.canHandle for a self-contained example
+class GoScanner {
+  languages = ['go']
+
+  canHandle(filePath: string): boolean {
+    return /\.go$/.test(filePath) && !filePath.includes('_test.go')
+  }
+}
+
+const scanner = new GoScanner()
+
+const testCases: Array<{ path: str
+```
+
+### 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 { 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' | 'type' | 
+```
+
+### 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) and extract all API elements — functions, classes, types, and exports — across multiple languages including Python, TypeScript, JavaScript, Go, and Rust.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ Yes | Path to the directory or single file to scan |
+| `options` | `ScanOptions` | ❌ No | Configuration options to control which files are included or excluded |
+| `op
+
+### scanFile
+
+**Type:** function
+**File:** /Users/debmukherjee/autodocs/src/scanner/index.ts
+
+```
+async function scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to analyze a single source file and extract structured metadata — functions, classes, types, and other code constructs — without scanning an entire directory.
+
+`scanFile` automatically detects the file's language, selects the appropriate scanner, and returns a normalized `ScanResult` regardless of whether the file is Python, TypeScript, or another supported language.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string`
+
+**Example:**
+```typescript
+// Inline types to simulate the autodocs ScanResult shape
+type FunctionInfo = {
+  name: string
+  signature: string
+  docstring?: string
+  lineStart: number
+  lineEnd: number
+}
+
+type ClassInfo = {
+  name: string
+  methods: FunctionInfo[]
+  lineStart: number
+  lineEnd: number
+}
+
+type ScanResult = {
+  
+```
+
+### 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 and returns a `ScanResult` with the extracted symbols and structure.
+
+---
+
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `languages` | `string[
+
+**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) ---
+type ScanResult = {
+  filePath: string
+  language: string
+  symbols?: Array<{ name: string; kind:
+```
+
+### canHandle
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/python.ts
+
+```
+canHandle(filePath: string): boolean
+```
+
+Use this to quickly check whether a given file path should be processed by the Python scanner before committing to a full file scan.
+
+Call `canHandle` as a pre-flight check to filter out non-Python files in a pipeline, avoiding unnecessary scan overhead.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | The file path to evaluate. Can be a relative path, absolute path, or just a filename. |
+
+### Returns
+
+| Value | Cond
+
+**Example:**
+```typescript
+// Inline implementation of PythonScanner.canHandle
+class PythonScanner {
+  languages = ['python']
+
+  canHandle(filePath: string): boolean {
+    return filePath.endsWith('.py')
+  }
+}
+
+// Simulate a list of files discovered in a project directory
+const discoveredFiles = [
+  '/project/src/main.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 — by running a Python parser subprocess and returning the results asynchronously.
+
+This is the core method of `PythonScanner`. It delegates parsing to a `python3` child process, making it suitable for deep, AST-level analysis of `.py` files without reimplementing Python parsing in TypeScript.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|---------
+
+**Example:**
+```typescript
+import { spawn } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// --- Inline types (mirrors the real ScanResult shape) ---
+interface ScanResult {
+  filePath: string
+  language: string
+  functions: string[]
+  classes: stri
+```
+
+### 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, or `None` if the node has no docstring.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| node | `ast.AST` | ✅ | Any parsed AST node — typically a `Module`, `FunctionDef`, `AsyncFunctionDef`, or `ClassDef` |
+
+## Returns
+
+| Value | When |
+|------
+
+**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:
+       
+```
+
+### 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 — ideal for documentation generators, code analyzers, or introspection tools.
+
+When parsing Python source code with the `ast` module, default values are stored as AST nodes. This function converts those nodes back into readable strings (e.g., `"42"`, `"'hello'"`, `"None"`). Returns `None` if no default value exists.
+
+### Parameters
+
+| Name | Type | Required | Description |
+
+
+**Example:**
+```python
+import ast
+
+# Inline implementation of get_default_value
+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)
+
+# Helper: parse a function and extract its argument defau
+```
+
+### 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 (obtained by parsing Python source code), this function 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 |
+|------|------|----------|-------------|
+| `
+
+**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]] = []
+
+    # Calculate offset
+```
+
+### 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 parsed AST components — useful when generating documentation, code analysis tools, or displaying function metadata 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, containing all parameter info (defaults, ann
+
+**Example:**
+```python
+import ast
+
+# Inline implementation of build_signature
+def build_signature(name: str, args: ast.arguments, returns: ast.AST | None, is_async: bool) -> str:
+    """Build the function signature as a string."""
+    prefix = "async def" if is_async else "def"
+
+    # Build argument list
+    arg_parts = [
+```
+
+### 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, signature, docstring, 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 relevant metadata about that function, ready for further processing or storage.
+
+## 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 AST `ClassDef` node and extract structured metadata about a class and all its methods into a flat list of dictionaries.
+
+Each dictionary in the returned list represents either the class itself or one of its methods, making it easy to index, search, or analyze Python source code programmatically.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `node` | `ast.ClassDef` | Yes | The AST node representing the class definiti
+
+**Example:**
+```python
+import ast
+from typing import Any
+
+# ── Inline implementation of extract_class ────────────────────────────────────
+
+def extract_class(node: ast.ClassDef, file_path: str) -> list[dict[str, Any]]:
+    """Extract a class and its methods into a flat list of metadata dicts."""
+    results: list[dict[str
+```
+
+### 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 workflow 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 |
+
+## R
+
+**Example:**
+```python
+import ast
+import os
+from typing import Any
+
+# Inline implementation of scan_file — no external imports needed
+def scan_file(file_path: str) -> dict[str, Any]:
+    """Scan a Python file and extract all API elements."""
+    result: dict[str, Any] = {
+        "file": file_path,
+        "functions": []
+```
+
+### 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.
+
+`RustScanner` implements the `Scanner` interface and targets `.rs` files, automatically skipping test files in `/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 quickly determine whether a given file path should be processed by the Rust scanner before committing to a full file scan.
+
+`canHandle` returns `true` only when **both** conditions are met:
+- The file path ends with `.rs`
+- The file path does **not** contain `/tests/`
+
+This acts as a fast pre-flight check, letting you skip incompatible files without reading them from disk.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` 
+
+**Example:**
+```typescript
+// Inline implementation matching RustScanner.canHandle behavior
+class RustScanner {
+  languages = ['rust']
+
+  canHandle(filePath: string): boolean {
+    return /\.rs$/.test(filePath) && !filePath.includes('/tests/')
+  }
+}
+
+const scanner = new RustScanner()
+
+const filePaths = [
+  'src/main.rs',     
+```
+
+### 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.
+
+Handles `.rs` files outside of test directories (`/tests/`). Reads the file synchronously and returns a promise resolving to a structured scan result.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the `.rs` fi
+
+**Example:**
+```typescript
+import { readFileSync } from 'fs'
+import { writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// --- Inline types (mirrors the real library's types) ---
+interface Parameter {
+  name: string
+  type: string
+}
+
+interface APIElement {
+  name: string
+  kind: 'fu
+```
+
+### 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 signatures) for automatic documentation generation.
+
+`TypeScriptScanner` implements the `Scanner` interface and handles `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files. It skips declaration files (`.d.ts`) automatically.
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `languages` | `string[]` | Always `['typescript', 'javascript']` — the languages this sc
+
+### canHandle
+
+**Type:** method
+**File:** /Users/debmukherjee/autodocs/src/scanner/typescript.ts
+
+```
+canHandle(filePath: string): boolean
+```
+
+Use this to quickly check 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` | ✅ | Absolute or relative path to the file being evalua
+
+**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, interfaces, types) from a TypeScript or JavaScript source file, returning structured metadata about each discovered element.
+
+`scanFile` analyzes a `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, or `.cjs` file and produces a `ScanResult` containing all documented API surface — parameters, return types, visibility, and more. Use it as the core step in building documentation pipelines, API audits, or code analysis tools.
+
+> **Note:** Declaration files (
+