@soederpop/luca 0.0.29 → 0.0.31

package/src/introspection/generated.web.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-24T01:41:39.159Z
+// Generated at: 2026-03-24T09:08:05.900Z
 
 setBuildTimeData('features.containerLink', {
   "id": "features.containerLink",
@@ -520,7 +520,34 @@ setBuildTimeData('features.speech', {
       "language": "ts",
       "code": "const speech = container.feature('speech')\nspeech.say('Hello from the browser!')\n\n// Choose a specific voice\nconst speech = container.feature('speech', { voice: 'Google UK English Female' })\nspeech.say('Cheerio!')"
     }
-  ]
+  ],
+  "types": {
+    "Voice": {
+      "description": "",
+      "properties": {
+        "voiceURI": {
+          "type": "string",
+          "description": ""
+        },
+        "name": {
+          "type": "string",
+          "description": ""
+        },
+        "lang": {
+          "type": "string",
+          "description": ""
+        },
+        "localService": {
+          "type": "boolean",
+          "description": ""
+        },
+        "default": {
+          "type": "boolean",
+          "description": ""
+        }
+      }
+    }
+  }
 });
 
 setBuildTimeData('features.helpers', {
@@ -635,10 +662,10 @@ setBuildTimeData('features.helpers', {
 // Container introspection data
 setContainerBuildTimeData('Container', {
   "className": "Container",
-  "description": "Containers are single objects that contain state, an event bus, and registries of helpers such as: - features - clients - servers A Helper represents a category of components in your program which have a common interface, e.g. all servers can be started / stopped, all features can be enabled, if supported, all clients can connect to something. A Helper can be introspected at runtime to learn about the interface of the helper. A helper has state, and emits events. You can design your own containers and load them up with the helpers you want for that environment.",
+  "description": "The Container is the core runtime object in Luca. It is a singleton per process that acts as an event bus, state machine, and dependency injector. It holds registries of helpers (features, clients, servers, commands, endpoints) and provides factory methods to create instances from them. All helper instances share the container's context, enabling them to communicate and coordinate. The container detects its runtime environment (Node, Bun, browser, Electron) and can load platform-specific feature implementations accordingly. Use `container.feature('name')` to create feature instances, `container.use(Plugin)` to extend the container with new capabilities, and `container.on('event', handler)` to react to lifecycle events.",
   "methods": {
     "subcontainer": {
-      "description": "Creates a new subcontainer instance of the same concrete Container subclass. The new instance is constructed with the same options as this container, shallow-merged with any overrides you provide. This preserves the runtime container type (e.g. NodeContainer, BrowserContainer, etc.).",
+      "description": "Creates a new subcontainer instance of the same concrete Container subclass. The new instance is constructed with the same options as this container, shallow-merged with any overrides you provide. This preserves the runtime container type (e.g. NodeContainer, AGIContainer, etc.).",
       "parameters": {
         "this": {
           "type": "This",
@@ -646,17 +673,23 @@ setContainerBuildTimeData('Container', {
         },
         "options": {
           "type": "ConstructorParameters<This['constructor']>[0]",
-          "description": "Options to override for the new container instance."
+          "description": "Options to override for the new container instance"
         }
       },
       "required": [
         "this",
         "options"
       ],
-      "returns": "This"
+      "returns": "This",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const child = container.subcontainer({ cwd: '/tmp/workspace' })\nchild.cwd // '/tmp/workspace'"
+        }
+      ]
     },
     "addContext": {
-      "description": "",
+      "description": "Add a value to the container's shared context, which is passed to all helper instances. Accepts either a key and value, or an object of key-value pairs to merge in.",
       "parameters": {
         "keyOrContext": {
           "type": "keyof ContainerContext | Partial<ContainerContext>",
@@ -664,105 +697,67 @@ setContainerBuildTimeData('Container', {
         },
         "value": {
           "type": "ContainerContext[keyof ContainerContext]",
-          "description": "Parameter value"
+          "description": "The context value (omit when passing an object)"
         }
       },
       "required": [
         "keyOrContext"
       ],
-      "returns": "this"
+      "returns": "this",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "container.addContext('db', dbConnection)\ncontainer.addContext({ db: dbConnection, cache: redisClient })"
+        }
+      ]
     },
     "setState": {
-      "description": "Sets the state of the container.",
+      "description": "Sets the state of the container. Accepts a partial state object to merge, or a function that receives the current state and returns the new state.",
       "parameters": {
         "newState": {
           "type": "SetStateValue<ContainerState>",
-          "description": "The new state of the container."
+          "description": "A partial state object to merge, or a function `(current) => newState`"
         }
       },
       "required": [
         "newState"
       ],
-      "returns": "void"
+      "returns": "this",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "container.setState({ started: true })\ncontainer.setState((prev) => ({ ...prev, started: true }))"
+        }
+      ]
     },
     "bus": {
-      "description": "Convenience method for creating a new event bus instance.",
+      "description": "Create a new standalone event bus instance. Useful when you need a scoped event channel that is independent of the container's own event bus.",
       "parameters": {},
       "required": [],
-      "returns": "void"
+      "returns": "Bus",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const myBus = container.bus()\nmyBus.on('data', (payload) => console.log(payload))\nmyBus.emit('data', { count: 42 })"
+        }
+      ]
     },
     "newState": {
-      "description": "Convenience method for creating a new observable State object.",
+      "description": "Create a new standalone observable State object. Useful when you need reactive state that is independent of the container's own state.",
       "parameters": {
         "initialState": {
           "type": "T",
-          "description": "Parameter initialState"
+          "description": "The initial state object (defaults to empty)"
         }
       },
       "required": [],
-      "returns": "void"
-    },
-    "normalizeHelperOptions": {
-      "description": "Parse helper options through the helper's static options schema so defaults are materialized.",
-      "parameters": {
-        "BaseClass": {
-          "type": "any",
-          "description": "Parameter BaseClass"
-        },
-        "options": {
-          "type": "any",
-          "description": "Parameter options"
-        },
-        "fallbackName": {
-          "type": "string",
-          "description": "Parameter fallbackName"
-        }
-      },
-      "required": [
-        "BaseClass",
-        "options"
-      ],
-      "returns": "void"
-    },
-    "buildHelperCacheKey": {
-      "description": "",
-      "parameters": {
-        "type": {
-          "type": "string",
-          "description": "Parameter type"
-        },
-        "id": {
-          "type": "string",
-          "description": "Parameter id"
-        },
-        "options": {
-          "type": "any",
-          "description": "Parameter options"
-        },
-        "omitOptionKeys": {
-          "type": "string[]",
-          "description": "Parameter omitOptionKeys"
+      "returns": "State<T>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const myState = container.newState({ count: 0, loading: false })\nmyState.observe(() => console.log('Changed:', myState.current))\nmyState.set('count', 1)"
         }
-      },
-      "required": [
-        "type",
-        "id",
-        "options"
-      ],
-      "returns": "void"
-    },
-    "createHelperInstance": {
-      "description": "",
-      "parameters": {
-        "{\n    cache,\n    type,\n    id,\n    BaseClass,\n    options,\n    fallbackName,\n    omitOptionKeys = [],\n    context,\n  }": {
-          "type": "{\n    cache: Map<string, any>\n    type: string\n    id: string\n    BaseClass: any\n    options?: any\n    fallbackName?: string\n    omitOptionKeys?: string[]\n    context?: any\n  }",
-          "description": "Parameter {\n    cache,\n    type,\n    id,\n    BaseClass,\n    options,\n    fallbackName,\n    omitOptionKeys = [],\n    context,\n  }"
-        }
-      },
-      "required": [
-        "{\n    cache,\n    type,\n    id,\n    BaseClass,\n    options,\n    fallbackName,\n    omitOptionKeys = [],\n    context,\n  }"
-      ],
-      "returns": "void"
+      ]
     },
     "feature": {
       "description": "Creates a new instance of a feature. If you pass the same arguments, it will return the same instance as last time you created that. If you need the ability to create fresh instances, it is up to you how you define your options to support that.",
@@ -782,136 +777,154 @@ setContainerBuildTimeData('Container', {
       "returns": "InstanceType<Features[T]>"
     },
     "start": {
-      "description": "TODO: A container should be able to container.use(plugin) and that plugin should be able to define an asynchronous method that will be run when the container is started.  Right now there's nothing to do with starting / stopping a container but that might be neat.",
+      "description": "Start the container. Emits the 'started' event and sets `state.started` to true. Plugins and features can listen for this event to perform initialization.",
       "parameters": {},
       "required": [],
-      "returns": "void"
+      "returns": "Promise<this>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "container.on('started', () => console.log('Ready'))\nawait container.start()"
+        }
+      ]
     },
     "emit": {
       "description": "Emit an event on the container's event bus.",
       "parameters": {
         "event": {
           "type": "string",
-          "description": "Parameter event"
+          "description": "The event name"
         },
         "args": {
           "type": "any[]",
-          "description": "Parameter args"
+          "description": "Arguments to pass to listeners"
         }
       },
       "required": [
         "event",
         "args"
       ],
-      "returns": "void"
+      "returns": "this",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "container.emit('taskCompleted', { id: 'abc', result: 42 })"
+        }
+      ]
     },
     "on": {
       "description": "Subscribe to an event on the container's event bus.",
       "parameters": {
         "event": {
           "type": "string",
-          "description": "Parameter event"
+          "description": "The event name"
         },
         "listener": {
           "type": "(...args: any[]) => void",
-          "description": "Parameter listener"
+          "description": "The callback function"
         }
       },
       "required": [
         "event",
         "listener"
       ],
-      "returns": "void"
+      "returns": "this",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "container.on('featureEnabled', (id, feature) => {\n console.log(`Feature ${id} enabled`)\n})"
+        }
+      ]
     },
     "off": {
       "description": "Unsubscribe a listener from an event on the container's event bus.",
       "parameters": {
         "event": {
           "type": "string",
-          "description": "Parameter event"
+          "description": "The event name"
         },
         "listener": {
           "type": "(...args: any[]) => void",
-          "description": "Parameter listener"
+          "description": "The listener to remove"
         }
       },
       "required": [
         "event"
       ],
-      "returns": "void"
+      "returns": "this"
     },
     "once": {
       "description": "Subscribe to an event on the container's event bus, but only fire once.",
       "parameters": {
         "event": {
           "type": "string",
-          "description": "Parameter event"
+          "description": "The event name"
         },
         "listener": {
           "type": "(...args: any[]) => void",
-          "description": "Parameter listener"
+          "description": "The callback function (invoked at most once)"
         }
       },
       "required": [
         "event",
         "listener"
       ],
-      "returns": "void"
+      "returns": "this"
     },
     "waitFor": {
-      "description": "Returns a promise that will resolve when the event is emitted",
+      "description": "Returns a promise that resolves the next time the given event is emitted. Useful for awaiting one-time lifecycle transitions.",
       "parameters": {
         "event": {
           "type": "string",
-          "description": "Parameter event"
+          "description": "The event name to wait for"
         }
       },
       "required": [
         "event"
       ],
-      "returns": "void"
-    },
-    "registerHelperType": {
-      "description": "Register a helper type (registry + factory pair) on this container. Called automatically by Helper.attach() methods (e.g. Client.attach, Server.attach).",
-      "parameters": {
-        "registryName": {
-          "type": "string",
-          "description": "The plural name of the registry, e.g. \"clients\", \"servers\""
-        },
-        "factoryName": {
-          "type": "string",
-          "description": "The singular factory method name, e.g. \"client\", \"server\""
+      "returns": "Promise<any>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await container.waitFor('started')\nconsole.log('Container is ready')"
         }
-      },
-      "required": [
-        "registryName",
-        "factoryName"
-      ],
-      "returns": "void"
+      ]
     },
     "inspect": {
       "description": "Returns a full introspection object for this container, merging build-time AST data (JSDoc descriptions, methods, getters) with runtime data (registries, factories, state, environment).",
       "parameters": {},
       "required": [],
-      "returns": "ContainerIntrospection"
+      "returns": "ContainerIntrospection",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const info = container.inspect()\nconsole.log(info.methods)   // all public methods with descriptions\nconsole.log(info.getters)   // all getters with return types\nconsole.log(info.registries) // features, clients, servers, etc."
+        }
+      ]
     },
     "inspectAsText": {
-      "description": "Returns a human-readable markdown representation of this container's introspection data. Useful in REPLs, AI agent contexts, or documentation generation. The first argument can be a section name (`'methods'`, `'getters'`, etc.) to render only that section, or a number for the starting heading depth (backward compatible).",
+      "description": "Returns a human-readable markdown representation of this container's introspection data. Useful in REPLs, AI agent contexts, or documentation generation. Pass a section name to render only that section (e.g. 'methods', 'getters', 'events', 'state').",
       "parameters": {
         "sectionOrDepth": {
           "type": "IntrospectionSection | number",
-          "description": "Parameter sectionOrDepth"
+          "description": "A section name to render, or heading depth number"
         },
         "startHeadingDepth": {
           "type": "number",
-          "description": "Parameter startHeadingDepth"
+          "description": "Starting markdown heading depth (default 1)"
         }
       },
       "required": [],
-      "returns": "string"
+      "returns": "string",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "console.log(container.inspectAsText())           // full description\nconsole.log(container.inspectAsText('methods'))   // just methods"
+        }
+      ]
     },
     "introspectAsText": {
-      "description": "Alias for inspectAsText",
+      "description": "Alias for inspectAsText.",
       "parameters": {
         "sectionOrDepth": {
           "type": "IntrospectionSection | number",
@@ -926,33 +939,42 @@ setContainerBuildTimeData('Container', {
       "returns": "string"
     },
     "introspectAsJSON": {
-      "description": "Alias for inspectAsJSON",
-      "parameters": {
-        "sectionOrDepth": {
-          "type": "IntrospectionSection | number",
-          "description": "Parameter sectionOrDepth"
-        },
-        "startHeadingDepth": {
-          "type": "number",
-          "description": "Parameter startHeadingDepth"
+      "description": "Alias for inspect, returns JSON introspection data.",
+      "parameters": {},
+      "required": [],
+      "returns": "ContainerIntrospection"
+    },
+    "inspectAsType": {
+      "description": "Returns the container's introspection data formatted as a TypeScript interface declaration. Includes the container's own methods, getters, factories, and registered helper types.",
+      "parameters": {},
+      "required": [],
+      "returns": "string",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "console.log(container.inspectAsType())\n// interface NodeContainer {\n//   feature<T>(id: string, options?: object): T;\n//   readonly uuid: string;\n//   ...\n// }"
         }
-      },
+      ]
+    },
+    "introspectAsType": {
+      "description": "",
+      "parameters": {},
       "required": [],
-      "returns": "any"
+      "returns": "string"
     },
     "sleep": {
       "description": "Sleep for the specified number of milliseconds. Useful for scripting and sequencing.",
       "parameters": {
         "ms": {
-          "type": "any",
+          "type": "number",
           "description": "Parameter ms"
         }
       },
       "required": [],
-      "returns": "void"
+      "returns": "Promise<this>"
     },
     "use": {
-      "description": "Apply a plugin or enable a feature by string name. Plugins must have a static attach(container) method.",
+      "description": "Apply a plugin or enable a feature by string name. Plugins are classes with a static `attach(container)` method that extend the container with new registries, factories, or capabilities.",
       "parameters": {
         "plugin": {
           "type": "Extension<T>",
@@ -966,25 +988,37 @@ setContainerBuildTimeData('Container', {
       "required": [
         "plugin"
       ],
-      "returns": "this & T"
+      "returns": "this & T",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "// Enable a feature by name\ncontainer.use('contentDb')\n\n// Attach a plugin class (e.g. Client, Server, or custom)\ncontainer.use(Client)    // registers the clients registry + client() factory\ncontainer.use(Server)    // registers the servers registry + server() factory"
+        }
+      ]
     }
   },
   "getters": {
     "state": {
       "description": "The observable state object for this container instance.",
-      "returns": "any"
+      "returns": "State<ContainerState>"
     },
     "enabledFeatureIds": {
       "description": "Returns the list of shortcut IDs for all currently enabled features.",
-      "returns": "any"
+      "returns": "string[]"
     },
     "enabledFeatures": {
       "description": "Returns a map of enabled feature shortcut IDs to their instances.",
       "returns": "Partial<AvailableInstanceTypes<Features>>"
     },
-    "describer": {
-      "description": "Lazy-initialized ContainerDescriber for introspecting registries, helpers, and members.",
-      "returns": "ContainerDescriber"
+    "utils": {
+      "description": "Common utilities available on every container. Provides UUID generation, object hashing, string case conversion, and lodash helpers — no imports needed. - `utils.uuid()` — generate a v4 UUID - `utils.hashObject(obj)` — deterministic hash of any object - `utils.stringUtils` — `{ kebabCase, camelCase, upperFirst, lowerFirst, pluralize, singularize }` - `utils.lodash` — `{ uniq, keyBy, uniqBy, groupBy, debounce, throttle, mapValues, mapKeys, pick, get, set, omit }`",
+      "returns": "ContainerUtils",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const id = container.utils.uuid()\nconst hash = container.utils.hashObject({ foo: 'bar' })\nconst name = container.utils.stringUtils.camelCase('my-feature')\nconst unique = container.utils.lodash.uniq([1, 2, 2, 3])"
+        }
+      ]
     },
     "context": {
       "description": "The Container's context is an object that contains the enabled features, the container itself, and any additional context that has been added to the container. All helper instances that are created by the container will have access to the shared context.",
@@ -992,35 +1026,45 @@ setContainerBuildTimeData('Container', {
     },
     "currentState": {
       "description": "The current state of the container. This is a snapshot of the container's state at the time this method is called.",
-      "returns": "any"
+      "returns": "ContainerState"
+    },
+    "features": {
+      "description": "The features registry. Use it to check what features are available, look up feature classes, or check if a feature is registered.",
+      "returns": "FeaturesRegistry",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "container.features.available   // ['fs', 'git', 'grep', ...]\ncontainer.features.has('fs')   // true\ncontainer.features.lookup('fs') // FS class"
+        }
+      ]
     },
     "isBrowser": {
       "description": "Returns true if the container is running in a browser.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "isBun": {
       "description": "Returns true if the container is running in Bun.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "isNode": {
       "description": "Returns true if the container is running in Node.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "isElectron": {
       "description": "Returns true if the container is running in Electron.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "isDevelopment": {
       "description": "Returns true if the container is running in development mode.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "isProduction": {
       "description": "Returns true if the container is running in production mode.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "isCI": {
       "description": "Returns true if the container is running in a CI environment.",
-      "returns": "any"
+      "returns": "boolean"
     },
     "registryNames": {
       "description": "Returns the names of all attached registries (e.g. [\"features\", \"clients\", \"servers\"]).",
@@ -1571,7 +1615,34 @@ export const introspectionData = [
         "language": "ts",
         "code": "const speech = container.feature('speech')\nspeech.say('Hello from the browser!')\n\n// Choose a specific voice\nconst speech = container.feature('speech', { voice: 'Google UK English Female' })\nspeech.say('Cheerio!')"
       }
-    ]
+    ],
+    "types": {
+      "Voice": {
+        "description": "",
+        "properties": {
+          "voiceURI": {
+            "type": "string",
+            "description": ""
+          },
+          "name": {
+            "type": "string",
+            "description": ""
+          },
+          "lang": {
+            "type": "string",
+            "description": ""
+          },
+          "localService": {
+            "type": "boolean",
+            "description": ""
+          },
+          "default": {
+            "type": "boolean",
+            "description": ""
+          }
+        }
+      }
+    }
   },
   {
     "id": "features.helpers",
@@ -1686,10 +1757,10 @@ export const introspectionData = [
 export const containerIntrospectionData = [
   {
     "className": "Container",
-    "description": "Containers are single objects that contain state, an event bus, and registries of helpers such as: - features - clients - servers A Helper represents a category of components in your program which have a common interface, e.g. all servers can be started / stopped, all features can be enabled, if supported, all clients can connect to something. A Helper can be introspected at runtime to learn about the interface of the helper. A helper has state, and emits events. You can design your own containers and load them up with the helpers you want for that environment.",
+    "description": "The Container is the core runtime object in Luca. It is a singleton per process that acts as an event bus, state machine, and dependency injector. It holds registries of helpers (features, clients, servers, commands, endpoints) and provides factory methods to create instances from them. All helper instances share the container's context, enabling them to communicate and coordinate. The container detects its runtime environment (Node, Bun, browser, Electron) and can load platform-specific feature implementations accordingly. Use `container.feature('name')` to create feature instances, `container.use(Plugin)` to extend the container with new capabilities, and `container.on('event', handler)` to react to lifecycle events.",
     "methods": {
       "subcontainer": {
-        "description": "Creates a new subcontainer instance of the same concrete Container subclass. The new instance is constructed with the same options as this container, shallow-merged with any overrides you provide. This preserves the runtime container type (e.g. NodeContainer, BrowserContainer, etc.).",
+        "description": "Creates a new subcontainer instance of the same concrete Container subclass. The new instance is constructed with the same options as this container, shallow-merged with any overrides you provide. This preserves the runtime container type (e.g. NodeContainer, AGIContainer, etc.).",
         "parameters": {
           "this": {
             "type": "This",
@@ -1697,17 +1768,23 @@ export const containerIntrospectionData = [
           },
           "options": {
             "type": "ConstructorParameters<This['constructor']>[0]",
-            "description": "Options to override for the new container instance."
+            "description": "Options to override for the new container instance"
           }
         },
         "required": [
           "this",
           "options"
         ],
-        "returns": "This"
+        "returns": "This",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const child = container.subcontainer({ cwd: '/tmp/workspace' })\nchild.cwd // '/tmp/workspace'"
+          }
+        ]
       },
       "addContext": {
-        "description": "",
+        "description": "Add a value to the container's shared context, which is passed to all helper instances. Accepts either a key and value, or an object of key-value pairs to merge in.",
         "parameters": {
           "keyOrContext": {
             "type": "keyof ContainerContext | Partial<ContainerContext>",
@@ -1715,105 +1792,67 @@ export const containerIntrospectionData = [
           },
           "value": {
             "type": "ContainerContext[keyof ContainerContext]",
-            "description": "Parameter value"
+            "description": "The context value (omit when passing an object)"
           }
         },
         "required": [
           "keyOrContext"
         ],
-        "returns": "this"
+        "returns": "this",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "container.addContext('db', dbConnection)\ncontainer.addContext({ db: dbConnection, cache: redisClient })"
+          }
+        ]
       },
       "setState": {
-        "description": "Sets the state of the container.",
+        "description": "Sets the state of the container. Accepts a partial state object to merge, or a function that receives the current state and returns the new state.",
         "parameters": {
           "newState": {
             "type": "SetStateValue<ContainerState>",
-            "description": "The new state of the container."
+            "description": "A partial state object to merge, or a function `(current) => newState`"
           }
         },
         "required": [
           "newState"
         ],
-        "returns": "void"
+        "returns": "this",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "container.setState({ started: true })\ncontainer.setState((prev) => ({ ...prev, started: true }))"
+          }
+        ]
       },
       "bus": {
-        "description": "Convenience method for creating a new event bus instance.",
+        "description": "Create a new standalone event bus instance. Useful when you need a scoped event channel that is independent of the container's own event bus.",
         "parameters": {},
         "required": [],
-        "returns": "void"
+        "returns": "Bus",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const myBus = container.bus()\nmyBus.on('data', (payload) => console.log(payload))\nmyBus.emit('data', { count: 42 })"
+          }
+        ]
       },
       "newState": {
-        "description": "Convenience method for creating a new observable State object.",
+        "description": "Create a new standalone observable State object. Useful when you need reactive state that is independent of the container's own state.",
         "parameters": {
           "initialState": {
             "type": "T",
-            "description": "Parameter initialState"
+            "description": "The initial state object (defaults to empty)"
           }
         },
         "required": [],
-        "returns": "void"
-      },
-      "normalizeHelperOptions": {
-        "description": "Parse helper options through the helper's static options schema so defaults are materialized.",
-        "parameters": {
-          "BaseClass": {
-            "type": "any",
-            "description": "Parameter BaseClass"
-          },
-          "options": {
-            "type": "any",
-            "description": "Parameter options"
-          },
-          "fallbackName": {
-            "type": "string",
-            "description": "Parameter fallbackName"
-          }
-        },
-        "required": [
-          "BaseClass",
-          "options"
-        ],
-        "returns": "void"
-      },
-      "buildHelperCacheKey": {
-        "description": "",
-        "parameters": {
-          "type": {
-            "type": "string",
-            "description": "Parameter type"
-          },
-          "id": {
-            "type": "string",
-            "description": "Parameter id"
-          },
-          "options": {
-            "type": "any",
-            "description": "Parameter options"
-          },
-          "omitOptionKeys": {
-            "type": "string[]",
-            "description": "Parameter omitOptionKeys"
+        "returns": "State<T>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const myState = container.newState({ count: 0, loading: false })\nmyState.observe(() => console.log('Changed:', myState.current))\nmyState.set('count', 1)"
           }
-        },
-        "required": [
-          "type",
-          "id",
-          "options"
-        ],
-        "returns": "void"
-      },
-      "createHelperInstance": {
-        "description": "",
-        "parameters": {
-          "{\n    cache,\n    type,\n    id,\n    BaseClass,\n    options,\n    fallbackName,\n    omitOptionKeys = [],\n    context,\n  }": {
-            "type": "{\n    cache: Map<string, any>\n    type: string\n    id: string\n    BaseClass: any\n    options?: any\n    fallbackName?: string\n    omitOptionKeys?: string[]\n    context?: any\n  }",
-            "description": "Parameter {\n    cache,\n    type,\n    id,\n    BaseClass,\n    options,\n    fallbackName,\n    omitOptionKeys = [],\n    context,\n  }"
-          }
-        },
-        "required": [
-          "{\n    cache,\n    type,\n    id,\n    BaseClass,\n    options,\n    fallbackName,\n    omitOptionKeys = [],\n    context,\n  }"
-        ],
-        "returns": "void"
+        ]
       },
       "feature": {
         "description": "Creates a new instance of a feature. If you pass the same arguments, it will return the same instance as last time you created that. If you need the ability to create fresh instances, it is up to you how you define your options to support that.",
@@ -1833,136 +1872,154 @@ export const containerIntrospectionData = [
         "returns": "InstanceType<Features[T]>"
       },
       "start": {
-        "description": "TODO: A container should be able to container.use(plugin) and that plugin should be able to define an asynchronous method that will be run when the container is started.  Right now there's nothing to do with starting / stopping a container but that might be neat.",
+        "description": "Start the container. Emits the 'started' event and sets `state.started` to true. Plugins and features can listen for this event to perform initialization.",
         "parameters": {},
         "required": [],
-        "returns": "void"
+        "returns": "Promise<this>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "container.on('started', () => console.log('Ready'))\nawait container.start()"
+          }
+        ]
       },
       "emit": {
         "description": "Emit an event on the container's event bus.",
         "parameters": {
           "event": {
             "type": "string",
-            "description": "Parameter event"
+            "description": "The event name"
           },
           "args": {
             "type": "any[]",
-            "description": "Parameter args"
+            "description": "Arguments to pass to listeners"
           }
         },
         "required": [
           "event",
           "args"
         ],
-        "returns": "void"
+        "returns": "this",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "container.emit('taskCompleted', { id: 'abc', result: 42 })"
+          }
+        ]
       },
       "on": {
         "description": "Subscribe to an event on the container's event bus.",
         "parameters": {
           "event": {
             "type": "string",
-            "description": "Parameter event"
+            "description": "The event name"
           },
           "listener": {
             "type": "(...args: any[]) => void",
-            "description": "Parameter listener"
+            "description": "The callback function"
           }
         },
         "required": [
           "event",
           "listener"
         ],
-        "returns": "void"
+        "returns": "this",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "container.on('featureEnabled', (id, feature) => {\n console.log(`Feature ${id} enabled`)\n})"
+          }
+        ]
       },
       "off": {
         "description": "Unsubscribe a listener from an event on the container's event bus.",
         "parameters": {
           "event": {
             "type": "string",
-            "description": "Parameter event"
+            "description": "The event name"
           },
           "listener": {
             "type": "(...args: any[]) => void",
-            "description": "Parameter listener"
+            "description": "The listener to remove"
           }
         },
         "required": [
           "event"
         ],
-        "returns": "void"
+        "returns": "this"
       },
       "once": {
         "description": "Subscribe to an event on the container's event bus, but only fire once.",
         "parameters": {
           "event": {
             "type": "string",
-            "description": "Parameter event"
+            "description": "The event name"
           },
           "listener": {
             "type": "(...args: any[]) => void",
-            "description": "Parameter listener"
+            "description": "The callback function (invoked at most once)"
           }
         },
         "required": [
           "event",
           "listener"
         ],
-        "returns": "void"
+        "returns": "this"
       },
       "waitFor": {
-        "description": "Returns a promise that will resolve when the event is emitted",
+        "description": "Returns a promise that resolves the next time the given event is emitted. Useful for awaiting one-time lifecycle transitions.",
         "parameters": {
           "event": {
             "type": "string",
-            "description": "Parameter event"
+            "description": "The event name to wait for"
           }
         },
         "required": [
           "event"
         ],
-        "returns": "void"
-      },
-      "registerHelperType": {
-        "description": "Register a helper type (registry + factory pair) on this container. Called automatically by Helper.attach() methods (e.g. Client.attach, Server.attach).",
-        "parameters": {
-          "registryName": {
-            "type": "string",
-            "description": "The plural name of the registry, e.g. \"clients\", \"servers\""
-          },
-          "factoryName": {
-            "type": "string",
-            "description": "The singular factory method name, e.g. \"client\", \"server\""
+        "returns": "Promise<any>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await container.waitFor('started')\nconsole.log('Container is ready')"
           }
-        },
-        "required": [
-          "registryName",
-          "factoryName"
-        ],
-        "returns": "void"
+        ]
       },
       "inspect": {
         "description": "Returns a full introspection object for this container, merging build-time AST data (JSDoc descriptions, methods, getters) with runtime data (registries, factories, state, environment).",
         "parameters": {},
         "required": [],
-        "returns": "ContainerIntrospection"
+        "returns": "ContainerIntrospection",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const info = container.inspect()\nconsole.log(info.methods)   // all public methods with descriptions\nconsole.log(info.getters)   // all getters with return types\nconsole.log(info.registries) // features, clients, servers, etc."
+          }
+        ]
       },
       "inspectAsText": {
-        "description": "Returns a human-readable markdown representation of this container's introspection data. Useful in REPLs, AI agent contexts, or documentation generation. The first argument can be a section name (`'methods'`, `'getters'`, etc.) to render only that section, or a number for the starting heading depth (backward compatible).",
+        "description": "Returns a human-readable markdown representation of this container's introspection data. Useful in REPLs, AI agent contexts, or documentation generation. Pass a section name to render only that section (e.g. 'methods', 'getters', 'events', 'state').",
         "parameters": {
           "sectionOrDepth": {
             "type": "IntrospectionSection | number",
-            "description": "Parameter sectionOrDepth"
+            "description": "A section name to render, or heading depth number"
           },
           "startHeadingDepth": {
             "type": "number",
-            "description": "Parameter startHeadingDepth"
+            "description": "Starting markdown heading depth (default 1)"
           }
         },
         "required": [],
-        "returns": "string"
+        "returns": "string",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "console.log(container.inspectAsText())           // full description\nconsole.log(container.inspectAsText('methods'))   // just methods"
+          }
+        ]
       },
       "introspectAsText": {
-        "description": "Alias for inspectAsText",
+        "description": "Alias for inspectAsText.",
         "parameters": {
           "sectionOrDepth": {
             "type": "IntrospectionSection | number",
@@ -1977,33 +2034,42 @@ export const containerIntrospectionData = [
         "returns": "string"
       },
       "introspectAsJSON": {
-        "description": "Alias for inspectAsJSON",
-        "parameters": {
-          "sectionOrDepth": {
-            "type": "IntrospectionSection | number",
-            "description": "Parameter sectionOrDepth"
-          },
-          "startHeadingDepth": {
-            "type": "number",
-            "description": "Parameter startHeadingDepth"
+        "description": "Alias for inspect, returns JSON introspection data.",
+        "parameters": {},
+        "required": [],
+        "returns": "ContainerIntrospection"
+      },
+      "inspectAsType": {
+        "description": "Returns the container's introspection data formatted as a TypeScript interface declaration. Includes the container's own methods, getters, factories, and registered helper types.",
+        "parameters": {},
+        "required": [],
+        "returns": "string",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "console.log(container.inspectAsType())\n// interface NodeContainer {\n//   feature<T>(id: string, options?: object): T;\n//   readonly uuid: string;\n//   ...\n// }"
           }
-        },
+        ]
+      },
+      "introspectAsType": {
+        "description": "",
+        "parameters": {},
         "required": [],
-        "returns": "any"
+        "returns": "string"
       },
       "sleep": {
         "description": "Sleep for the specified number of milliseconds. Useful for scripting and sequencing.",
         "parameters": {
           "ms": {
-            "type": "any",
+            "type": "number",
             "description": "Parameter ms"
           }
         },
         "required": [],
-        "returns": "void"
+        "returns": "Promise<this>"
       },
       "use": {
-        "description": "Apply a plugin or enable a feature by string name. Plugins must have a static attach(container) method.",
+        "description": "Apply a plugin or enable a feature by string name. Plugins are classes with a static `attach(container)` method that extend the container with new registries, factories, or capabilities.",
         "parameters": {
           "plugin": {
             "type": "Extension<T>",
@@ -2017,25 +2083,37 @@ export const containerIntrospectionData = [
         "required": [
           "plugin"
         ],
-        "returns": "this & T"
+        "returns": "this & T",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "// Enable a feature by name\ncontainer.use('contentDb')\n\n// Attach a plugin class (e.g. Client, Server, or custom)\ncontainer.use(Client)    // registers the clients registry + client() factory\ncontainer.use(Server)    // registers the servers registry + server() factory"
+          }
+        ]
       }
     },
     "getters": {
       "state": {
         "description": "The observable state object for this container instance.",
-        "returns": "any"
+        "returns": "State<ContainerState>"
       },
       "enabledFeatureIds": {
         "description": "Returns the list of shortcut IDs for all currently enabled features.",
-        "returns": "any"
+        "returns": "string[]"
       },
       "enabledFeatures": {
         "description": "Returns a map of enabled feature shortcut IDs to their instances.",
         "returns": "Partial<AvailableInstanceTypes<Features>>"
       },
-      "describer": {
-        "description": "Lazy-initialized ContainerDescriber for introspecting registries, helpers, and members.",
-        "returns": "ContainerDescriber"
+      "utils": {
+        "description": "Common utilities available on every container. Provides UUID generation, object hashing, string case conversion, and lodash helpers — no imports needed. - `utils.uuid()` — generate a v4 UUID - `utils.hashObject(obj)` — deterministic hash of any object - `utils.stringUtils` — `{ kebabCase, camelCase, upperFirst, lowerFirst, pluralize, singularize }` - `utils.lodash` — `{ uniq, keyBy, uniqBy, groupBy, debounce, throttle, mapValues, mapKeys, pick, get, set, omit }`",
+        "returns": "ContainerUtils",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const id = container.utils.uuid()\nconst hash = container.utils.hashObject({ foo: 'bar' })\nconst name = container.utils.stringUtils.camelCase('my-feature')\nconst unique = container.utils.lodash.uniq([1, 2, 2, 3])"
+          }
+        ]
       },
       "context": {
         "description": "The Container's context is an object that contains the enabled features, the container itself, and any additional context that has been added to the container. All helper instances that are created by the container will have access to the shared context.",
@@ -2043,35 +2121,45 @@ export const containerIntrospectionData = [
       },
       "currentState": {
         "description": "The current state of the container. This is a snapshot of the container's state at the time this method is called.",
-        "returns": "any"
+        "returns": "ContainerState"
+      },
+      "features": {
+        "description": "The features registry. Use it to check what features are available, look up feature classes, or check if a feature is registered.",
+        "returns": "FeaturesRegistry",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "container.features.available   // ['fs', 'git', 'grep', ...]\ncontainer.features.has('fs')   // true\ncontainer.features.lookup('fs') // FS class"
+          }
+        ]
       },
       "isBrowser": {
         "description": "Returns true if the container is running in a browser.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "isBun": {
         "description": "Returns true if the container is running in Bun.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "isNode": {
         "description": "Returns true if the container is running in Node.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "isElectron": {
         "description": "Returns true if the container is running in Electron.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "isDevelopment": {
         "description": "Returns true if the container is running in development mode.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "isProduction": {
         "description": "Returns true if the container is running in production mode.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "isCI": {
         "description": "Returns true if the container is running in a CI environment.",
-        "returns": "any"
+        "returns": "boolean"
       },
       "registryNames": {
         "description": "Returns the names of all attached registries (e.g. [\"features\", \"clients\", \"servers\"]).",