skrypt-ai 0.7.0 → 0.8.0

package/dist/template/src/app/docs/plugins/page.mdx

@@ -1,1793 +0,0 @@
-## Functions
-
-### `definePlugin`
-
-```typescript
-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 same `SkryptPlugin` object passed in, unchanged. The value is identical to the input — the benefit is purely type-safety and IDE autocompletion during authoring.
-
-**Example:**
-
-```typescript example.ts
-// 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) => void
-  }
-}
-
-// Inline the definePlugin function
-function definePlugin(plugin: SkryptPlugin): SkryptPlugin {
-  return plugin
-}
-
-// Define a plugin with full type safety and autocompletion
-const myPlugin = definePlugin({
-  name: 'my-analytics-plugin',
-  version: '1.0.0',
-
-  setup: async (context) => {
-    const apiKey = process.env.ANALYTICS_API_KEY || 'sk-analytics-abc123'
-    console.log(`[${myPlugin.name}] Setting up with key: ${apiKey.slice(0, 8)}...`)
-    context.initialized = true
-  },
-
-  teardown: async () => {
-    console.log(`[${myPlugin.name}] Tearing down, releasing resources...`)
-  },
-
-  hooks: {
-    beforeRun: () => {
-      console.log(`[${myPlugin.name}] Hook: before run triggered`)
-    },
-    afterRun: (result) => {
-      console.log(`[${myPlugin.name}] Hook: after run triggered with result:`, result)
-    },
-  },
-})
-
-async function main() {
-  try {
-    console.log('Plugin defined:', myPlugin.name, `v${myPlugin.version}`)
-    // Output: Plugin defined: my-analytics-plugin v1.0.0
-
-    const context: Record<string, unknown> = {}
-    await myPlugin.setup?.(context)
-    // Output: [my-analytics-plugin] Setting up with key: sk-analy...
-
-    myPlugin.hooks?.beforeRun?.()
-    // Output: [my-analytics-plugin] Hook: before run triggered
-
-    myPlugin.hooks?.afterRun?.({ status: 'success', records: 42 })
-    // Output: [my-analytics-plugin] Hook: after run triggered with result: { status: 'success', records: 42 }
-
-    await myPlugin.teardown?.()
-    // Output: [my-analytics-plugin] Tearing down, releasing resources...
-
-    // definePlugin returns the exact same object reference
-    console.log('Same reference:', definePlugin(myPlugin) === myPlugin)
-    // Output: Same reference: true
-  } catch (error) {
-    console.error('Plugin error:', error)
-  }
-}
-
-main()
-```
-
-## Classes
-
-### `PluginManager`
-
-```typescript
-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 path to the source files directory |
-| `outputPath` | `string` | Yes | Absolute or relative path where processed output will be written |
-| `config` | `Record<string, unknown>` | No | Arbitrary key-value config passed to every plugin via context. Defaults to `{}` |
-
-## Plugin Context
-
-Every registered plugin receives a shared context object:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `sourcePath` | `string` | The source directory path |
-| `outputPath` | `string` | The output directory path |
-| `config` | `Record<string, unknown>` | The config passed to the constructor |
-| `logger.info` | `(msg: string) => void` | Logs an info message prefixed with `[plugin]` |
-| `logger.warn` | `(msg: string) => void` | Logs a warning prefixed with `[plugin]` |
-| `logger.error` | `(msg: string) => void` | Logs an error prefixed with `[plugin]` |
-
-#### Returns
-
-`new PluginManager(...)` returns a `PluginManager` instance ready to accept plugin registrations and execute them against the shared context.
-
-**Example:**
-
-```typescript example.ts
-// --- 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: string
-  setup?: (context: PluginContext) => void | Promise<void>
-  teardown?: (context: PluginContext) => void | Promise<void>
-}
-
-// --- Self-contained PluginManager implementation ---
-
-class PluginManager {
-  private plugins: SkryptPlugin[] = []
-  private context: PluginContext
-
-  constructor(
-    sourcePath: string,
-    outputPath: string,
-    config: Record<string, unknown> = {}
-  ) {
-    this.context = {
-      sourcePath,
-      outputPath,
-      config,
-      logger: {
-        info:  (msg) => console.log(`[plugin] INFO  ${msg}`),
-        warn:  (msg) => console.log(`[plugin] WARN  ${msg}`),
-        error: (msg) => console.log(`[plugin] ERROR ${msg}`),
-      },
-    }
-  }
-
-  register(plugin: SkryptPlugin): void {
-    this.plugins.push(plugin)
-    this.context.logger.info(`Registered plugin: ${plugin.name}`)
-  }
-
-  async runSetup(): Promise<void> {
-    for (const plugin of this.plugins) {
-      if (plugin.setup) {
-        this.context.logger.info(`Running setup for: ${plugin.name}`)
-        await plugin.setup(this.context)
-      }
-    }
-  }
-
-  async runTeardown(): Promise<void> {
-    for (const plugin of this.plugins) {
-      if (plugin.teardown) {
-        this.context.logger.info(`Running teardown for: ${plugin.name}`)
-        await plugin.teardown(this.context)
-      }
-    }
-  }
-}
-
-// --- Usage example ---
-
-const markdownPlugin: SkryptPlugin = {
-  name: 'markdown-transformer',
-  setup: async (ctx) => {
-    ctx.logger.info(`Reading from: ${ctx.sourcePath}`)
-    ctx.logger.info(`Writing to:   ${ctx.outputPath}`)
-
-    const theme = ctx.config.theme ?? 'default'
-    ctx.logger.info(`Applying theme: ${theme}`)
-
-    // Simulate async file processing
-    await new Promise((resolve) => setTimeout(resolve, 10))
-    ctx.logger.info('Markdown transformation complete')
-  },
-  teardown: async (ctx) => {
-    ctx.logger.info('Cleaning up temporary markdown assets')
-  },
-}
-
-const analyticsPlugin: SkryptPlugin = {
-  name: 'analytics-injector',
-  setup: async (ctx) => {
-    const trackingId = ctx.config.trackingId
-    if (!trackingId) {
-      ctx.logger.warn('No trackingId provided — analytics will be skipped')
-      return
-    }
-    ctx.logger.info(`Injecting analytics with ID: ${trackingId}`)
-  },
-}
-
-async function main() {
-  try {
-    const manager = new PluginManager(
-      process.env.SOURCE_PATH  || './src/docs',
-      process.env.OUTPUT_PATH  || './dist/docs',
-      {
-        theme:      process.env.DOCS_THEME      || 'dark',
-        trackingId: process.env.ANALYTICS_ID    || '',   // intentionally empty to demo warn
-      }
-    )
-
-    manager.register(markdownPlugin)
-    manager.register(analyticsPlugin)
-
-    console.log('\n--- Running plugin setup ---')
-    await manager.runSetup()
-
-    console.log('\n--- Running plugin teardown ---')
-    await manager.runTeardown()
-
-    console.log('\nDone.')
-    /*
-    Expected output:
-      [plugin] INFO  Registered plugin: markdown-transformer
-      [plugin] INFO  Registered plugin: analytics-injector
-
-      --- Running plugin setup ---
-      [plugin] INFO  Running setup for: markdown-transformer
-      [plugin] INFO  Reading from: ./src/docs
-      [plugin] INFO  Writing to:   ./dist/docs
-      [plugin] INFO  Applying theme: dark
-      [plugin] INFO  Markdown transformation complete
-      [plugin] INFO  Running setup for: analytics-injector
-      [plugin] WARN  No trackingId provided — analytics will be skipped
-
-      --- Running plugin teardown ---
-      [plugin] INFO  Running teardown for: markdown-transformer
-      [plugin] INFO  Cleaning up temporary markdown assets
-
-      Done.
-    */
-  } catch (error) {
-    console.error('PluginManager failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-### Methods
-
-#### `constructor`
-
-```typescript
-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 the directory where generated docs will be written |
-| `config` | `Record<string, unknown>` | ❌ No | Optional key-value configuration passed to all plugins via shared context (defaults to `{}`) |
-
-#### Returns
-
-A `PluginManager` instance with an initialized plugin context. The internal `plugins` array starts empty — use the instance's registration methods to add plugins before running them.
-
-## Notes
-
-- `sourcePath` and `outputPath` are stored in the shared `PluginContext`, making them accessible to every registered plugin
-- Passing `config` lets you forward options like theme settings, version strings, or feature flags to all plugins without coupling them directly
-- The logger is set up automatically during construction — plugins receive it via context without additional setup
-
-**Example:**
-
-```typescript example.ts
-// --- 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 SkryptPlugin = {
-  name: string
-  run: (context: PluginContext) => Promise<void>
-}
-
-// --- Self-contained PluginManager implementation ---
-class PluginManager {
-  private plugins: SkryptPlugin[] = []
-  private context: PluginContext
-
-  constructor(
-    sourcePath: string,
-    outputPath: string,
-    config: Record<string, unknown> = {}
-  ) {
-    this.context = {
-      sourcePath,
-      outputPath,
-      config,
-      logger: {
-        info:  (msg) => console.log(`[INFO]  ${msg}`),
-        warn:  (msg) => console.warn(`[WARN]  ${msg}`),
-        error: (msg) => console.error(`[ERROR] ${msg}`),
-      },
-    }
-  }
-
-  register(plugin: SkryptPlugin): void {
-    this.plugins.push(plugin)
-    this.context.logger.info(`Registered plugin: "${plugin.name}"`)
-  }
-
-  async runAll(): Promise<void> {
-    for (const plugin of this.plugins) {
-      this.context.logger.info(`Running plugin: "${plugin.name}"`)
-      await plugin.run(this.context)
-    }
-  }
-
-  getContext(): PluginContext {
-    return this.context
-  }
-}
-
-// --- Usage example ---
-async function main() {
-  try {
-    const manager = new PluginManager(
-      './src',           // sourcePath
-      './docs/output',   // outputPath
-      {                  // optional config
-        version: '2.1.0',
-        theme: 'dark',
-        includePrivate: false,
-      }
-    )
-
-    // Inspect the initialized context
-    const ctx = manager.getContext()
-    console.log('PluginManager initialized:')
-    console.log('  sourcePath:', ctx.sourcePath)
-    console.log('  outputPath:', ctx.outputPath)
-    console.log('  config:    ', ctx.config)
-    // Output:
-    // PluginManager initialized:
-    //   sourcePath: ./src
-    //   outputPath: ./docs/output
-    //   config:     { version: '2.1.0', theme: 'dark', includePrivate: false }
-
-    // Register and run a sample plugin to verify context is passed correctly
-    manager.register({
-      name: 'markdown-emitter',
-      run: async (context) => {
-        context.logger.info(
-          `Emitting docs from "${context.sourcePath}" → "${context.outputPath}" ` +
-          `(v${context.config.version})`
-        )
-      },
-    })
-
-    await manager.runAll()
-    // Output:
-    // [INFO]  Registered plugin: "markdown-emitter"
-    // [INFO]  Running plugin: "markdown-emitter"
-    // [INFO]  Emitting docs from "./src" → "./docs/output" (v2.1.0)
-
-  } catch (error) {
-    console.error('PluginManager setup failed:', error)
-  }
-}
-
-main()
-```
-
-#### `loadPlugins`
-
-```typescript
-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 |
-|------|------|----------|-------------|
-| `configPath` | `string` | No | Absolute or relative path to a config file. If omitted, the manager searches for `skrypt.config.js` or `skrypt.config.ts` in the current working directory. |
-
-#### Returns
-
-Returns `Promise<void>`. Resolves when all plugins have been loaded. Resolves silently (no error thrown) if no config file is found — check your logs if plugins appear missing.
-
-### Behavior Notes
-
-- **No config file found** → resolves immediately without loading anything
-- **Config file found** → loads and registers all plugins declared in the file
-- **Invalid config** → may throw or log errors depending on the plugin's implementation
-
-**Example:**
-
-```typescript example.ts
-// 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)
-class PluginManager {
-  private plugins: Plugin[] = []
-  private logger: Logger
-
-  constructor(logger?: Logger) {
-    this.logger = logger ?? {
-      info: (msg) => console.log(`[plugin] ${msg}`),
-      error: (msg) => console.error(`[plugin] ${msg}`),
-    }
-  }
-
-  // Simulates finding skrypt.config.js / skrypt.config.ts
-  private findConfigFile(): string | null {
-    const candidates = ['skrypt.config.js', 'skrypt.config.ts']
-    // In a real implementation this uses existsSync from 'fs'
-    // Here we simulate a found config for demonstration
-    console.log(`[plugin] Searching for config: ${candidates.join(', ')}`)
-    return process.env.PLUGIN_CONFIG_PATH || null
-  }
-
-  async loadPlugins(configPath?: string): Promise<void> {
-    const configFile = configPath || this.findConfigFile()
-
-    if (!configFile) {
-      this.logger.info('No config file found — skipping plugin load')
-      return
-    }
-
-    try {
-      this.logger.info(`Loading plugins from: ${configFile}`)
-
-      // Simulate loading a config module
-      const config: PluginConfig = await this.simulateConfigLoad(configFile)
-
-      for (const plugin of config.plugins) {
-        plugin.setup()
-        this.plugins.push(plugin)
-        this.logger.info(`Loaded plugin: ${plugin.name}`)
-      }
-
-      this.logger.info(`Total plugins loaded: ${this.plugins.length}`)
-    } catch (err) {
-      this.logger.error(`Failed to load plugins: ${(err as Error).message}`)
-      throw err
-    }
-  }
-
-  // Simulates dynamic import of a config file
-  private async simulateConfigLoad(_path: string): Promise<PluginConfig> {
-    return {
-      plugins: [
-        { name: 'markdown-plugin', setup: () => console.log('  → markdown-plugin initialized') },
-        { name: 'auth-plugin',     setup: () => console.log('  → auth-plugin initialized') },
-      ],
-    }
-  }
-
-  getLoadedPlugins(): string[] {
-    return this.plugins.map((p) => p.name)
-  }
-}
-
-// --- Usage ---
-async function main() {
-  const manager = new PluginManager()
-
-  try {
-    // Option 1: Auto-detect config file (uses PLUGIN_CONFIG_PATH env or returns null)
-    await manager.loadPlugins()
-
-    // Option 2: Provide an explicit config path
-    await manager.loadPlugins(
-      process.env.PLUGIN_CONFIG_PATH || './skrypt.config.js'
-    )
-
-    console.log('\nLoaded plugins:', manager.getLoadedPlugins())
-    // Output:
-    // [plugin] Loading plugins from: ./skrypt.config.js
-    //   → markdown-plugin initialized
-    //   → auth-plugin initialized
-    // [plugin] Total plugins loaded: 2
-    // Loaded plugins: [ 'markdown-plugin', 'auth-plugin' ]
-  } catch (error) {
-    console.error('Plugin initialization failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-#### `register`
-
-```typescript
-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 least a `name` property; `version` is optional but recommended. |
-
-#### Returns
-
-`void` — Registers the plugin in-place. After calling `register()`, the plugin is immediately available for hook execution via `runHook()`.
-
-### Behavior Notes
-- Plugins are stored in insertion order and hooks are run in that order.
-- A confirmation log is printed: `Loaded plugin: <name> v<version>` (version omitted if not provided).
-- No deduplication is performed — registering the same plugin twice will add it twice.
-
-**Example:**
-
-```typescript example.ts
-// 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: SkryptPlugin[] = []
-
-  register(plugin: SkryptPlugin): void {
-    this.plugins.push(plugin)
-    console.log(
-      `Loaded plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}`
-    )
-  }
-
-  async runHook<T>(hook: keyof SkryptPlugin, ...args: unknown[]): Promise<T | undefined> {
-    for (const plugin of this.plugins) {
-      const fn = plugin[hook]
-      if (typeof fn === 'function') {
-        await fn(...args)
-      }
-    }
-    return undefined
-  }
-
-  getPlugins(): SkryptPlugin[] {
-    return [...this.plugins]
-  }
-}
-
-// --- Usage Example ---
-
-const manager = new PluginManager()
-
-// Plugin with version
-const analyticsPlugin: SkryptPlugin = {
-  name: 'analytics-tracker',
-  version: '2.1.0',
-  onBuildStart: () => console.log('  [analytics] Build started, initializing trackers...'),
-  onBuildEnd: () => console.log('  [analytics] Build complete, flushing events.'),
-}
-
-// Plugin without version (version log is omitted)
-const minifierPlugin: SkryptPlugin = {
-  name: 'html-minifier',
-  onBuildEnd: () => console.log('  [minifier] Minifying HTML output...'),
-}
-
-async function main() {
-  try {
-    // Register plugins manually
-    manager.register(analyticsPlugin)
-    // Output: Loaded plugin: analytics-tracker v2.1.0
-
-    manager.register(minifierPlugin)
-    // Output: Loaded plugin: html-minifier
-
-    console.log(`\nRegistered plugins: ${manager.getPlugins().map(p => p.name).join(', ')}`)
-    // Output: Registered plugins: analytics-tracker, html-minifier
-
-    // Trigger hooks to confirm plugins are active
-    console.log('\n-- Running onBuildStart --')
-    await manager.runHook('onBuildStart')
-
-    console.log('\n-- Running onBuildEnd --')
-    await manager.runHook('onBuildEnd')
-
-  } catch (error) {
-    console.error('Plugin registration failed:', error)
-  }
-}
-
-main()
-```
-
-#### `runHook`
-
-```typescript
-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'`) |
-| `...args` | `unknown[]` | No | Arguments passed to each plugin's hook function. The first argument (`args[0]`) serves as the initial result value that gets threaded through the pipeline |
-
-**Returns**
-
-| Condition | Return Value |
-|-----------|-------------|
-| One or more plugins implement the hook | `Promise<T>` — the final transformed result after all plugins have run |
-| No plugins implement the hook | `Promise<undefined>` — resolves with the initial `args[0]` value cast as `T`, or `undefined` if no args provided |
-
-The return value is the **accumulated result** after all plugins have had a chance to process it — plugins run in registration order.
-
-**Example:**
-
-```typescript example.ts
-// --- 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> | string
-}
-
-// --- Inline PluginManager implementation ---
-class PluginManager {
-  private plugins: SkryptPlugin[] = []
-
-  register(plugin: SkryptPlugin): void {
-    this.plugins.push(plugin)
-    console.log(
-      `Loaded plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}`
-    )
-  }
-
-  async runHook<T>(hook: keyof SkryptPlugin, ...args: unknown[]): Promise<T | undefined> {
-    let result = args[0] as T
-
-    for (const plugin of this.plugins) {
-      const fn = plugin[hook] as ((...args: unknown[]) => Promise<T> | T) | undefined
-      if (typeof fn === 'function') {
-        result = await fn.call(plugin, result, ...args.slice(1))
-      }
-    }
-
-    return result
-  }
-}
-
-// --- Example: transform source code through a plugin pipeline ---
-const manager = new PluginManager()
-
-// Plugin 1: strips comments
-manager.register({
-  name: 'strip-comments',
-  version: '1.0.0',
-  transform: (source: unknown) => {
-    return (source as string).replace(/\/\/.*$/gm, '').trim()
-  },
-})
-
-// Plugin 2: minifies whitespace
-manager.register({
-  name: 'minify-whitespace',
-  version: '2.1.3',
-  transform: (source: unknown) => {
-    return (source as string).replace(/\s+/g, ' ').trim()
-  },
-})
-
-// Plugin 3: only implements 'afterCompile' — skipped during 'transform' hook
-manager.register({
-  name: 'logger-plugin',
-  afterCompile: (source: unknown) => {
-    console.log('[logger-plugin] Compilation finished.')
-    return source as string
-  },
-})
-
-async function main() {
-  const rawSource = `
-    // This is a comment
-    const   x   =   42;
-    // Another comment
-    const   y   =   x   +   1;
-  `
-
-  try {
-    // Run the 'transform' hook — only plugins that define it will participate
-    const transformed = await manager.runHook<string>('transform', rawSource)
-    console.log('Transformed source:', transformed)
-    // Output: "const x = 42; const y = x + 1;"
-
-    // Run the 'afterCompile' hook — only logger-plugin participates
-    const afterResult = await manager.runHook<string>('afterCompile', transformed)
-    console.log('After compile result:', afterResult)
-    // Output: [logger-plugin] Compilation finished.
-    //         "const x = 42; const y = x + 1;"
-
-    // Run a hook with no implementations — returns initial value unchanged
-    const noOp = await manager.runHook<string>('beforeCompile', 'original code')
-    console.log('No-op hook result:', noOp)
-    // Output: "original code"
-  } catch (error) {
-    console.error('Hook execution failed:', error)
-  }
-}
-
-main()
-```
-
-#### `onInit`
-
-```typescript
-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 |
-|------|-------------|
-| `Promise<void>` | Resolves when all plugin `onInit` hooks have completed. Rejects if any plugin's hook throws. |
-
-## Behavior Notes
-
-- Execution is **sequential** — plugins are initialized in registration order.
-- If a plugin does **not** implement `onInit`, it is silently skipped.
-- A failure in one plugin's `onInit` will **halt** the chain and reject the promise.
-
-**Example:**
-
-```typescript example.ts
-// 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[] = []
-
-  register(plugin: Plugin): void {
-    this.plugins.push(plugin)
-    console.log(`[PluginManager] Registered plugin: ${plugin.name}`)
-  }
-
-  private async runHook(hookName: keyof Plugin): Promise<void> {
-    for (const plugin of this.plugins) {
-      const hook = plugin[hookName]
-      if (typeof hook === 'function') {
-        console.log(`[PluginManager] Running '${hookName}' for plugin: ${plugin.name}`)
-        await (hook as PluginHook).call(plugin)
-      } else {
-        console.log(`[PluginManager] Plugin '${plugin.name}' has no '${hookName}' hook — skipping`)
-      }
-    }
-  }
-
-  async onInit(): Promise<void> {
-    await this.runHook('onInit')
-  }
-}
-
-// Example plugins — one with onInit, one without
-const databasePlugin: Plugin = {
-  name: 'DatabasePlugin',
-  onInit: async () => {
-    const dbUrl = process.env.DATABASE_URL || 'postgres://localhost:5432/mydb'
-    console.log(`  → Connecting to database at: ${dbUrl}`)
-    // Simulate async connection setup
-    await new Promise((resolve) => setTimeout(resolve, 50))
-    console.log('  → Database connection established')
-  },
-}
-
-const loggerPlugin: Plugin = {
-  name: 'LoggerPlugin',
-  // No onInit — will be skipped gracefully
-}
-
-const cachePlugin: Plugin = {
-  name: 'CachePlugin',
-  onInit: async () => {
-    const cacheHost = process.env.CACHE_HOST || 'redis://localhost:6379'
-    console.log(`  → Initializing cache at: ${cacheHost}`)
-    await new Promise((resolve) => setTimeout(resolve, 30))
-    console.log('  → Cache ready')
-  },
-}
-
-async function main() {
-  const manager = new PluginManager()
-
-  manager.register(databasePlugin)
-  manager.register(loggerPlugin)
-  manager.register(cachePlugin)
-
-  console.log('\n--- Running onInit lifecycle hook ---')
-
-  try {
-    await manager.onInit()
-    console.log('\n✓ All plugins initialized successfully')
-    // Expected output:
-    // [PluginManager] Running 'onInit' for plugin: DatabasePlugin
-    //   → Connecting to database at: postgres://localhost:5432/mydb
-    //   → Database connection established
-    // [PluginManager] Plugin 'LoggerPlugin' has no 'onInit' hook — skipping
-    // [PluginManager] Running 'onInit' for plugin: CachePlugin
-    //   → Initializing cache at: redis://localhost:6379
-    //   → Cache ready
-    // ✓ All plugins initialized successfully
-  } catch (error) {
-    console.error('✗ Plugin initialization failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-#### `onBeforeScan`
-
-```typescript
-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 |
-|------|-------------|
-| `Promise<void>` | Resolves when all registered `onBeforeScan` plugin hooks have completed. Does not return a value. |
-
-#### When to Call It
-
-Call `onBeforeScan` **after** `onInit` and **before** you begin scanning source files. The typical lifecycle order is:
-
-1. `onInit()` — plugin initialization
-2. `onBeforeScan()` — pre-scan preparation ← **this method**
-3. _(scan runs)_
-4. `onAfterScan(elements)` — post-scan transformation
-
-**Example:**
-
-```typescript example.ts
-// 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 = plugins
-  }
-
-  private async runHook(hookName: keyof Plugin): Promise<void> {
-    for (const plugin of this.plugins) {
-      const hook = plugin[hookName]
-      if (typeof hook === 'function') {
-        console.log(`[PluginManager] Running "${hookName}" for plugin: ${plugin.name}`)
-        await (hook as () => Promise<void>)()
-      }
-    }
-  }
-
-  async onInit(): Promise<void> {
-    await this.runHook('onInit')
-  }
-
-  async onBeforeScan(): Promise<void> {
-    await this.runHook('onBeforeScan')
-  }
-}
-
-// Example plugins with onBeforeScan hooks
-const plugins: Plugin[] = [
-  {
-    name: 'CachePlugin',
-    onBeforeScan: async () => {
-      console.log('  → CachePlugin: Clearing stale cache entries...')
-      // Simulate async cache-clearing work
-      await new Promise((resolve) => setTimeout(resolve, 10))
-      console.log('  → CachePlugin: Cache cleared.')
-    },
-  },
-  {
-    name: 'OutputPlugin',
-    onBeforeScan: async () => {
-      console.log('  → OutputPlugin: Ensuring output directory exists...')
-      await new Promise((resolve) => setTimeout(resolve, 5))
-      console.log('  → OutputPlugin: Output directory ready.')
-    },
-  },
-  {
-    name: 'LoggerPlugin',
-    // No onBeforeScan hook — will be skipped automatically
-  },
-]
-
-async function main() {
-  const manager = new PluginManager(plugins)
-
-  try {
-    console.log('Step 1: Initializing plugins...')
-    await manager.onInit()
-
-    console.log('\nStep 2: Running pre-scan hooks...')
-    await manager.onBeforeScan()
-
-    console.log('\n✓ All onBeforeScan hooks completed. Safe to begin scanning.')
-    // Output:
-    // Step 1: Initializing plugins...
-    // Step 2: Running pre-scan hooks...
-    // [PluginManager] Running "onBeforeScan" for plugin: CachePlugin
-    //   → CachePlugin: Clearing stale cache entries...
-    //   → CachePlugin: Cache cleared.
-    // [PluginManager] Running "onBeforeScan" for plugin: OutputPlugin
-    //   → OutputPlugin: Ensuring output directory exists...
-    //   → OutputPlugin: Output directory ready.
-    // ✓ All onBeforeScan hooks completed. Safe to begin scanning.
-  } catch (error) {
-    console.error('onBeforeScan failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-#### `onAfterScan`
-
-```typescript
-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 |
-|------|------|----------|-------------|
-| `elements` | `T[]` | Yes | The array of scanned elements to pass through the plugin hook chain |
-
-#### Returns
-
-**`Promise<T[]>`** — Resolves to the (potentially modified) array of elements after all plugins have processed them. Falls back to the original `elements` array if no plugin returns a value.
-
-## Behavior Notes
-
-- Plugins are executed in registration order
-- If a plugin's `onAfterScan` returns `null`/`undefined`, the previous elements array is preserved
-- The generic type `T` is inferred from the input array — no explicit type annotation needed in most cases
-
-**Example:**
-
-```typescript example.ts
-// 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 plugins: Plugin[] = []
-
-  register(plugin: Plugin) {
-    this.plugins.push(plugin)
-    console.log(`Plugin registered: ${plugin.name}`)
-  }
-
-  private async runHook<R>(hookName: string, arg?: R): Promise<R | undefined> {
-    let result: R | undefined = arg
-    for (const plugin of this.plugins) {
-      const hook = (plugin as Record<string, unknown>)[hookName]
-      if (typeof hook === 'function') {
-        const hookResult = await hook.call(plugin, result)
-        if (hookResult !== undefined && hookResult !== null) {
-          result = hookResult
-        }
-      }
-    }
-    return result
-  }
-
-  async onAfterScan<T>(elements: T[]): Promise<T[]> {
-    return (await this.runHook<T[]>('onAfterScan', elements)) || elements
-  }
-}
-
-// --- Example usage ---
-
-const manager = new PluginManager()
-
-// Plugin 1: Filter out unexported files
-manager.register({
-  name: 'export-filter-plugin',
-  onAfterScan: async <T>(elements: T[]): Promise<T[]> => {
-    const files = elements as unknown as ScannedFile[]
-    const filtered = files.filter((f) => f.exported)
-    console.log(`[export-filter-plugin] Filtered ${elements.length} → ${filtered.length} elements`)
-    return filtered as unknown as T[]
-  }
-})
-
-// Plugin 2: Enrich elements with additional tags
-manager.register({
-  name: 'tag-enrichment-plugin',
-  onAfterScan: async <T>(elements: T[]): Promise<T[]> => {
-    const files = elements as unknown as ScannedFile[]
-    const enriched = files.map((f) => ({ ...f, tags: [...f.tags, 'scanned'] }))
-    console.log(`[tag-enrichment-plugin] Added "scanned" tag to ${enriched.length} elements`)
-    return enriched as unknown as T[]
-  }
-})
-
-// Simulated scan results
-const scannedFiles: ScannedFile[] = [
-  { path: 'src/index.ts',      exported: true,  tags: ['entry'] },
-  { path: 'src/internal.ts',   exported: false, tags: [] },
-  { path: 'src/utils.ts',      exported: true,  tags: ['utility'] },
-  { path: 'src/helpers.ts',    exported: false, tags: [] },
-]
-
-async function main() {
-  try {
-    console.log('\nRunning onAfterScan with', scannedFiles.length, 'elements...\n')
-
-    const result = await manager.onAfterScan(scannedFiles)
-
-    console.log('\nFinal elements after all plugins:')
-    result.forEach((f) => {
-      console.log(`  ${f.path} | tags: [${f.tags.join(', ')}]`)
-    })
-
-    // Expected output:
-    // Plugin registered: export-filter-plugin
-    // Plugin registered: tag-enrichment-plugin
-    //
-    // Running onAfterScan with 4 elements...
-    //
-    // [export-filter-plugin] Filtered 4 → 2 elements
-    // [tag-enrichment-plugin] Added "scanned" tag to 2 elements
-    //
-    // Final elements after all plugins:
-    //   src/index.ts | tags: [entry, scanned]
-    //   src/utils.ts | tags: [utility, scanned]
-  } catch (error) {
-    console.error('onAfterScan failed:', error)
-  }
-}
-
-main()
-```
-
-#### `onBeforeGenerate`
-
-```typescript
-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 array of elements (e.g. parsed source items, doc nodes) to pass through all registered plugin hooks before generation |
-
-#### Returns
-
-**`Promise<T[]>`** — Resolves to the transformed array after all `onBeforeGenerate` plugin hooks have run. Falls back to the original `elements` array if no hook returns a value.
-
-#### When to use
-- **Filter out elements** you don't want documented (e.g. internal/private members)
-- **Enrich elements** with extra metadata before templates render them
-- **Reorder or group** elements before the generator processes them
-- **Inject synthetic elements** that don't exist in source but should appear in docs
-
-**Example:**
-
-```typescript example.ts
-// 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'
-  isInternal: boolean
-  description?: string
-}
-
-// Self-contained PluginManager implementation
-class PluginManager {
-  private plugins: Plugin[] = []
-
-  register(plugin: Plugin) {
-    this.plugins.push(plugin)
-    console.log(`Plugin registered: ${plugin.name}`)
-  }
-
-  private async runHook<T>(hookName: HookName, elements: T[]): Promise<T | null> {
-    let current: T = elements as unknown as T
-    for (const plugin of this.plugins) {
-      const hook = plugin[hookName] as ((el: T) => Promise<T>) | undefined
-      if (typeof hook === 'function') {
-        current = await hook.call(plugin, current)
-      }
-    }
-    return current ?? null
-  }
-
-  async onBeforeGenerate<T>(elements: T[]): Promise<T[]> {
-    return (await this.runHook<T[]>('onBeforeGenerate', elements)) || elements
-  }
-}
-
-// --- Example usage ---
-
-const manager = new PluginManager()
-
-// Plugin 1: Strip internal/private elements before generation
-manager.register({
-  name: 'filter-internals',
-  onBeforeGenerate: async <T>(elements: T[]): Promise<T[]> => {
-    const filtered = (elements as unknown as DocElement[]).filter(
-      (el) => !el.isInternal
-    )
-    console.log(`[filter-internals] Removed ${elements.length - filtered.length} internal element(s)`)
-    return filtered as unknown as T[]
-  },
-})
-
-// Plugin 2: Enrich remaining elements with default descriptions
-manager.register({
-  name: 'enrich-descriptions',
-  onBeforeGenerate: async <T>(elements: T[]): Promise<T[]> => {
-    const enriched = (elements as unknown as DocElement[]).map((el) => ({
-      ...el,
-      description: el.description ?? `Auto-generated docs for ${el.kind} "${el.name}"`,
-    }))
-    console.log(`[enrich-descriptions] Enriched ${enriched.length} element(s)`)
-    return enriched as unknown as T[]
-  },
-})
-
-// Sample parsed source elements
-const sourceElements: DocElement[] = [
-  { name: 'UserService',   kind: 'class',     isInternal: false },
-  { name: '_InternalUtil', kind: 'class',     isInternal: true  },
-  { name: 'fetchUser',     kind: 'function',  isInternal: false },
-  { name: 'IUserProfile',  kind: 'interface', isInternal: false, description: 'Represents a user profile' },
-]
-
-async function main() {
-  try {
-    console.log(`\nInput elements (${sourceElements.length}):`, sourceElements.map(e => e.name))
-
-    const result = await manager.onBeforeGenerate(sourceElements)
-
-    console.log(`\nOutput elements (${result.length}):`)
-    result.forEach((el) => {
-      console.log(`  [${el.kind}] ${el.name} — "${el.description}"`)
-    })
-
-    // Expected output:
-    // Input elements (4): [ 'UserService', '_InternalUtil', 'fetchUser', 'IUserProfile' ]
-    // [filter-internals]    Removed 1 internal element(s)
-    // [enrich-descriptions] Enriched 3 element(s)
-    // Output elements (3):
-    //   [class]     UserService    — "Auto-generated docs for class "UserService""
-    //   [function]  fetchUser      — "Auto-generated docs for function "fetchUser""
-    //   [interface] IUserProfile   — "Represents a user profile"
-  } catch (error) {
-    console.error('onBeforeGenerate failed:', error)
-  }
-}
-
-main()
-```
-
-#### `onAfterGenerate`
-
-```typescript
-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 modifies the docs, the original array is returned unchanged.
-
-### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `docs` | `T[]` | ✅ | Array of generated documentation objects to pass through registered plugin hooks |
-
-#### Returns
-
-**`Promise<T[]>`** — Resolves to the transformed array of docs after all plugins have processed them. Falls back to the original `docs` array if no plugin hook returns a value.
-
-**Example:**
-
-```typescript example.ts
-// 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 support
-class PluginManager {
-  private plugins: Plugin[] = []
-
-  register(plugin: Plugin) {
-    this.plugins.push(plugin)
-  }
-
-  private async runHook<T>(hookName: keyof Plugin, data: T): Promise<T | undefined> {
-    let result: T | undefined = undefined
-    for (const plugin of this.plugins) {
-      const hook = plugin[hookName] as Hook<T> | undefined
-      if (typeof hook === 'function') {
-        result = await hook(result ?? data)
-      }
-    }
-    return result
-  }
-
-  async onAfterGenerate<T>(docs: T[]): Promise<T[]> {
-    return (await this.runHook<T[]>('onAfterGenerate', docs)) || docs
-  }
-}
-
-// --- Example usage ---
-
-const manager = new PluginManager()
-
-// Plugin 1: Adds auto-generated tags based on content keywords
-manager.register({
-  onAfterGenerate: async (docs: GeneratedDoc[]) => {
-    return docs.map(doc => ({
-      ...doc,
-      tags: doc.content.toLowerCase().includes('async')
-        ? ['async', 'promise']
-        : ['sync'],
-    }))
-  },
-})
-
-// Plugin 2: Filters out any docs marked as internal
-manager.register({
-  onAfterGenerate: async (docs: GeneratedDoc[]) => {
-    return docs.filter(doc => !doc.title.startsWith('[internal]'))
-  },
-})
-
-const rawDocs: GeneratedDoc[] = [
-  { id: 'doc-001', title: 'fetchUser',           content: 'An async function that fetches a user by ID.' },
-  { id: 'doc-002', title: '[internal] authToken', content: 'Manages internal auth tokens.' },
-  { id: 'doc-003', title: 'formatDate',           content: 'Formats a date string into locale format.' },
-]
-
-async function main() {
-  try {
-    const processedDocs = await manager.onAfterGenerate(rawDocs)
-
-    console.log('Docs after onAfterGenerate:', JSON.stringify(processedDocs, null, 2))
-    // Expected output:
-    // [
-    //   { id: 'doc-001', title: 'fetchUser',    content: '...', tags: ['async', 'promise'] },
-    //   { id: 'doc-003', title: 'formatDate',   content: '...', tags: ['sync'] }
-    // ]
-    // Note: '[internal] authToken' was removed by Plugin 2
-  } catch (error) {
-    console.error('onAfterGenerate failed:', error)
-  }
-}
-
-main()
-```
-
-#### `onBeforeWrite`
-
-```typescript
-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 |
-|------|------|----------|-------------|
-| `docs` | `T[]` | Yes | Array of documentation objects to be passed through all registered plugin hooks before writing |
-
-#### Returns
-
-| Condition | Return Value |
-|-----------|-------------|
-| One or more plugins handle the hook | `Promise<T[]>` — the transformed array returned by the last plugin that handled it |
-| No plugin handles the hook | `Promise<T[]>` — the original `docs` array, unchanged |
-
-**Example:**
-
-```typescript example.ts
-// 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) => unknown>>
-}
-
-// Minimal self-contained PluginManager implementation
-class PluginManager {
-  private plugins: Plugin[] = []
-
-  register(plugin: Plugin) {
-    this.plugins.push(plugin)
-    console.log(`Plugin registered: ${plugin.name}`)
-  }
-
-  private async runHook<T>(hookName: Hook, data?: T): Promise<T | undefined> {
-    let result: T | undefined = data
-    for (const plugin of this.plugins) {
-      const hook = plugin.hooks?.[hookName]
-      if (hook) {
-        result = (await hook(result)) as T
-        console.log(`  [${plugin.name}] ran hook: ${hookName}`)
-      }
-    }
-    return result
-  }
-
-  async onBeforeWrite<T>(docs: T[]): Promise<T[]> {
-    return (await this.runHook<T[]>('onBeforeWrite', docs)) || docs
-  }
-}
-
-// --- Example plugins ---
-
-// Plugin 1: Adds a slug derived from the title
-const slugPlugin: Plugin = {
-  name: 'SlugPlugin',
-  hooks: {
-    onBeforeWrite: (data) => {
-      const docs = data as Doc[]
-      return docs.map((doc) => ({
-        ...doc,
-        slug: doc.title.toLowerCase().replace(/\s+/g, '-'),
-      }))
-    },
-  },
-}
-
-// Plugin 2: Stamps each doc with the write timestamp
-const timestampPlugin: Plugin = {
-  name: 'TimestampPlugin',
-  hooks: {
-    onBeforeWrite: (data) => {
-      const docs = data as Doc[]
-      return docs.map((doc) => ({
-        ...doc,
-        writtenAt: new Date().toISOString(),
-      }))
-    },
-  },
-}
-
-// --- Run the pipeline ---
-async function main() {
-  const manager = new PluginManager()
-  manager.register(slugPlugin)
-  manager.register(timestampPlugin)
-
-  const rawDocs: Doc[] = [
-    { id: 'doc-001', title: 'Getting Started', content: 'Welcome to the docs.' },
-    { id: 'doc-002', title: 'API Reference',   content: 'Full API details here.' },
-    { id: 'doc-003', title: 'Advanced Usage',  content: 'Tips for power users.'  },
-  ]
-
-  console.log('\nRunning onBeforeWrite hooks...')
-
-  try {
-    const finalDocs = await manager.onBeforeWrite<Doc>(rawDocs)
-
-    console.log('\nDocs ready to write:')
-    finalDocs.forEach((doc) => {
-      console.log(`  [${doc.id}] "${doc.title}" → slug: "${doc.slug}", writtenAt: ${doc.writtenAt}`)
-    })
-
-    // Expected output (timestamps will vary):
-    // [doc-001] "Getting Started" → slug: "getting-started", writtenAt: 2024-05-01T12:00:00.000Z
-    // [doc-002] "API Reference"   → slug: "api-reference",   writtenAt: 2024-05-01T12:00:00.000Z
-    // [doc-003] "Advanced Usage"  → slug: "advanced-usage",  writtenAt: 2024-05-01T12:00:00.000Z
-  } catch (error) {
-    console.error('onBeforeWrite pipeline failed:', error)
-  }
-}
-
-main()
-```
-
-#### `onAfterWrite`
-
-```typescript
-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<void>` | Resolves when all plugin `onAfterWrite` hooks have completed |
-
-#### When to Call
-
-Call this immediately after all documentation files have been written. It pairs with `onBeforeWrite` (pre-write transformation) to form a complete write lifecycle:
-
-1. `onBeforeWrite(docs)` — transform/filter docs before writing
-2. *(write files to disk)*
-3. `onAfterWrite()` — notify plugins that writing is complete
-
-**Example:**
-
-```typescript example.ts
-// 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): void {
-    this.plugins.push(plugin)
-    console.log(`Plugin registered: ${plugin.name}`)
-  }
-
-  private async runHook(hookName: string, ...args: unknown[]): Promise<unknown> {
-    let result: unknown
-    for (const plugin of this.plugins) {
-      if (typeof plugin.hooks[hookName] === 'function') {
-        result = await plugin.hooks[hookName](...args)
-      }
-    }
-    return result
-  }
-
-  async onBeforeWrite<T>(docs: T[]): Promise<T[]> {
-    return (await this.runHook('onBeforeWrite', docs) as T[]) || docs
-  }
-
-  async onAfterWrite(): Promise<void> {
-    await this.runHook('onAfterWrite')
-  }
-}
-
-// Example plugins that use the onAfterWrite hook
-const cacheInvalidationPlugin: Plugin = {
-  name: 'cache-invalidation',
-  hooks: {
-    onAfterWrite: async () => {
-      console.log('[cache-invalidation] Clearing documentation cache...')
-      // Simulate async cache clear
-      await new Promise(resolve => setTimeout(resolve, 50))
-      console.log('[cache-invalidation] Cache cleared successfully.')
-    }
-  }
-}
-
-const notificationPlugin: Plugin = {
-  name: 'slack-notifier',
-  hooks: {
-    onAfterWrite: async () => {
-      const webhookUrl = process.env.SLACK_WEBHOOK_URL || 'https://hooks.slack.com/your-webhook'
-      console.log(`[slack-notifier] Sending notification to: ${webhookUrl}`)
-      // Simulate async notification
-      await new Promise(resolve => setTimeout(resolve, 30))
-      console.log('[slack-notifier] Notification sent: docs updated.')
-    }
-  }
-}
-
-async function main() {
-  const manager = new PluginManager()
-
-  manager.register(cacheInvalidationPlugin)
-  manager.register(notificationPlugin)
-
-  // Simulate the full write lifecycle
-  const docs = [
-    { id: 'doc-001', title: 'Getting Started', content: 'Welcome...' },
-    { id: 'doc-002', title: 'API Reference', content: 'Endpoints...' }
-  ]
-
-  try {
-    console.log('\n--- Step 1: Pre-write hook ---')
-    const processedDocs = await manager.onBeforeWrite(docs)
-    console.log(`Processed ${processedDocs.length} docs for writing.`)
-
-    console.log('\n--- Step 2: Writing files to disk (simulated) ---')
-    await new Promise(resolve => setTimeout(resolve, 20))
-    console.log('Files written successfully.')
-
-    console.log('\n--- Step 3: Post-write hook ---')
-    await manager.onAfterWrite()
-
-    console.log('\n✅ Write lifecycle complete.')
-    // Expected output:
-    // [cache-invalidation] Clearing documentation cache...
-    // [cache-invalidation] Cache cleared successfully.
-    // [slack-notifier] Sending notification to: https://hooks.slack.com/your-webhook
-    // [slack-notifier] Notification sent: docs updated.
-  } catch (error) {
-    console.error('Write lifecycle failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-#### `transformContent`
-
-```typescript
-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 | Description |
-|------|------|----------|-------------|
-| `content` | `string` | ✅ | The raw file content to be transformed |
-| `filePath` | `string` | ✅ | The path of the file being processed — plugins may use this to apply transformations conditionally based on file type or location |
-
-#### Returns
-
-| Condition | Return Value |
-|-----------|-------------|
-| One or more plugins transform the content | `Promise<string>` — the fully transformed content after all plugins have run |
-| No plugins implement `transformContent` | `Promise<string>` — the original `content` string, unchanged |
-
-**Example:**
-
-```typescript example.ts
-// 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 {
-    this.plugins.push(plugin);
-    console.log(`Registered plugin: ${plugin.name}`);
-  }
-
-  async transformContent(content: string, filePath: string): Promise<string> {
-    let result = content;
-
-    for (const plugin of this.plugins) {
-      if (typeof plugin.transformContent === 'function') {
-        try {
-          result = await plugin.transformContent(result, filePath);
-        } catch (error) {
-          console.error(`Plugin "${plugin.name}" failed during transformContent:`, error);
-        }
-      }
-    }
-
-    return result;
-  }
-}
-
-// --- Example plugins ---
-
-// Plugin 1: Injects a timestamp header into markdown files
-const timestampPlugin: Plugin = {
-  name: 'timestamp-injector',
-  async transformContent(content, filePath) {
-    if (filePath.endsWith('.md')) {
-      return `<!-- Generated: ${new Date().toISOString()} -->\n${content}`;
-    }
-    return content;
-  },
-};
-
-// Plugin 2: Replaces placeholder tokens with environment values
-const envReplacerPlugin: Plugin = {
-  name: 'env-replacer',
-  async transformContent(content, _filePath) {
-    const apiBase = process.env.API_BASE_URL || 'https://api.example.com';
-    return content.replace(/\{\{API_BASE_URL\}\}/g, apiBase);
-  },
-};
-
-// Plugin 3: No transformContent — should be silently skipped
-const noOpPlugin: Plugin = {
-  name: 'lifecycle-only-plugin',
-  // intentionally omits transformContent
-};
-
-// --- Run the pipeline ---
-async function main() {
-  try {
-    const manager = new PluginManager();
-    manager.register(timestampPlugin);
-    manager.register(envReplacerPlugin);
-    manager.register(noOpPlugin);
-
-    const rawContent = `# API Reference\n\nBase URL: {{API_BASE_URL}}\n\nWelcome to the docs.`;
-    const filePath = 'docs/api-reference.md';
-
-    console.log('\n--- Input ---');
-    console.log(rawContent);
-
-    const transformed = await manager.transformContent(rawContent, filePath);
-
-    console.log('\n--- Transformed Output ---');
-    console.log(transformed);
-    // Expected output:
-    // <!-- Generated: 2024-01-15T10:30:00.000Z -->
-    // # API Reference
-    //
-    // Base URL: https://api.example.com
-    //
-    // Welcome to the docs.
-  } catch (error) {
-    console.error('Transformation pipeline failed:', error);
-  }
-}
-
-main();
-```
-