@soederpop/luca 0.0.5 → 0.0.7

package/src/scaffolds/generated.ts

@@ -1,6 +1,6 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-10T18:58:23.358Z
-// Source: docs/scaffolds/*.md and docs/mcp/readme.md
+// Generated at: 2026-03-19T00:28:06.880Z
+// Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds
 
@@ -20,8 +20,7 @@ export const scaffolds: Record<string, ScaffoldData> = {
     sections: [
       { heading: "Imports", code: `import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'` },
+import { Feature } from '@soederpop/luca'` },
       { heading: "Schemas", code: `export const {{PascalName}}StateSchema = FeatureStateSchema.extend({
   // Add your state fields here. These are observable — changes emit events.
   // Example: itemCount: z.number().default(0).describe('Number of items stored'),
@@ -40,8 +39,6 @@ export const {{PascalName}}EventsSchema = FeatureEventsSchema.extend({
 })` },
       { heading: "Class", code: `/**
  * {{description}}
- *
- * @example
  * \`\`\`typescript
  * const {{camelName}} = container.feature('{{camelName}}')
  * \`\`\`
@@ -53,25 +50,30 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
-    // Initialize state, set up resources
-  }
+  static { Feature.register(this, '{{camelName}}') }
 
-  // Add your methods here. Every public method needs JSDoc.
+  /**
+   * Called after the feature is initialized. Use this for any setup logic
+   * instead of overriding the constructor.
+   */
+  async afterInitialize() {
+    // Set up initial state, start background tasks, etc.
+  }
 }` },
       { heading: "Module Augmentation", code: `declare module '@soederpop/luca' {
   interface AvailableFeatures {
     {{camelName}}: typeof {{PascalName}}
   }
 }` },
-      { heading: "Registration", code: `export default features.register('{{camelName}}', {{PascalName}})` },
+      { heading: "Registration", code: `// Inside the class:
+static { Feature.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}` },
       { heading: "Complete Example", code: `import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
   interface AvailableFeatures {
@@ -99,19 +101,18 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override shortcut = 'features.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Feature.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default features.register('{{camelName}}', {{PascalName}})` }
+export default {{PascalName}}` }
     ],
     full: `import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
   interface AvailableFeatures {
@@ -139,14 +140,14 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override shortcut = 'features.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Feature.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default features.register('{{camelName}}', {{PascalName}})`,
+export default {{PascalName}}`,
     tutorial: `# Building a Feature
 
 A feature is a container-managed capability — something your application needs that lives on the machine (file I/O, caching, encryption, etc). Features are lazy-loaded, observable, and self-documenting.
@@ -161,12 +162,15 @@ When to build a feature:
 \`\`\`ts
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
 \`\`\`
 
 These are the only imports your feature file needs from luca. If your feature wraps a third-party library, import it here too — feature implementations are the ONE place where direct library imports are allowed.
 
+The use of dynamic imports is encouraged here, only import libraries you need when the feature is used, and only when necessary in the lifecycle of the feature if it can be done.
+
+feature's have built in ways to check if their requirements are supported and can be enabled cautiously.
+
 ## Schemas
 
 Define the shape of your feature's state, options, and events using Zod. Every field must have a \`.describe()\` — this becomes the documentation.
@@ -194,11 +198,11 @@ export const {{PascalName}}EventsSchema = FeatureEventsSchema.extend({
 
 The class extends \`Feature\` with your state and options types. Static properties drive registration and introspection. Every public method needs a JSDoc block with \`@param\`, \`@returns\`, and \`@example\`.
 
+Running \`luca introspect\` captures JSDoc blocks and Zod schemas and includes them in the description whenever somebody calls \`container.features.describe('{{camelName}}')\` or \`luca describe {{camelName}}\`.
+
 \`\`\`ts
 /**
  * {{description}}
- *
- * @example
  * \`\`\`typescript
  * const {{camelName}} = container.feature('{{camelName}}')
  * \`\`\`
@@ -210,17 +214,21 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
-    // Initialize state, set up resources
-  }
+  static { Feature.register(this, '{{camelName}}') }
 
-  // Add your methods here. Every public method needs JSDoc.
+  /**
+   * Called after the feature is initialized. Use this for any setup logic
+   * instead of overriding the constructor.
+   */
+  async afterInitialize() {
+    // Set up initial state, start background tasks, etc.
+  }
 }
 \`\`\`
 
+**Important**: You almost never need to override the constructor. Use \`afterInitialize()\` for any setup logic — it runs after the feature is fully wired into the container and has access to \`this.container\`, \`this.options\`, \`this.state\`, etc.
+
 ## Module Augmentation
 
 This is what gives \`container.feature('yourName')\` TypeScript autocomplete. Without it, the feature works but TypeScript won't know about it.
@@ -235,10 +243,14 @@ declare module '@soederpop/luca' {
 
 ## Registration
 
-The last line of the file registers the feature in the global registry. This must happen at module level (not inside a function).
+Registration happens inside the class body using a static block. The default export is just the class itself.
 
 \`\`\`ts
-export default features.register('{{camelName}}', {{PascalName}})
+// Inside the class:
+static { Feature.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}
 \`\`\`
 
 ## Complete Example
@@ -248,8 +260,7 @@ Here's a minimal but complete feature. This is what a real feature file looks li
 \`\`\`ts
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
   interface AvailableFeatures {
@@ -277,14 +288,14 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override shortcut = 'features.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Feature.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default features.register('{{camelName}}', {{PascalName}})
+export default {{PascalName}}
 \`\`\`
 
 ## Conventions
@@ -300,9 +311,8 @@ export default features.register('{{camelName}}', {{PascalName}})
   client: {
     sections: [
       { heading: "Imports", code: `import { z } from 'zod'
-import { Client, clients, RestClient } from '@soederpop/luca/client'
-import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'` },
+import { Client, RestClient } from '@soederpop/luca/client'
+import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca'` },
       { heading: "Schemas", code: `export const {{PascalName}}StateSchema = ClientStateSchema.extend({
   // Add your state fields here.
   // Example: authenticated: z.boolean().default(false).describe('Whether API auth is configured'),
@@ -328,14 +338,14 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
   static override shortcut = 'clients.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
-
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    options = {
-      ...options,
-      baseURL: options.baseURL || 'https://api.example.com',
-    }
-    super(options, context)
+  static { Client.register(this, '{{camelName}}') }
+
+  /**
+   * Called after the client is initialized. Use this for any setup logic
+   * instead of overriding the constructor.
+   */
+  async afterInitialize() {
+    // Set up default headers, configure auth, etc.
   }
 
   // Add API methods here. Each wraps an endpoint.
@@ -349,11 +359,14 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
     {{camelName}}: typeof {{PascalName}}
   }
 }` },
-      { heading: "Registration", code: `export default clients.register('{{camelName}}', {{PascalName}})` },
+      { heading: "Registration", code: `// Inside the class:
+static { Client.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}` },
       { heading: "Complete Example", code: `import { z } from 'zod'
-import { clients, RestClient } from '@soederpop/luca/client'
+import { Client, RestClient } from '@soederpop/luca/client'
 import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
 
 declare module '@soederpop/luca/client' {
   interface AvailableClients {
@@ -383,19 +396,18 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
   static override shortcut = 'clients.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Client.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super({ ...options, baseURL: options.baseURL }, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default clients.register('{{camelName}}', {{PascalName}})` }
+export default {{PascalName}}` }
     ],
     full: `import { z } from 'zod'
-import { clients, RestClient } from '@soederpop/luca/client'
+import { Client, RestClient } from '@soederpop/luca/client'
 import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
 
 declare module '@soederpop/luca/client' {
   interface AvailableClients {
@@ -425,14 +437,14 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
   static override shortcut = 'clients.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Client.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super({ ...options, baseURL: options.baseURL }, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default clients.register('{{camelName}}', {{PascalName}})`,
+export default {{PascalName}}`,
     tutorial: `# Building a Client
 
 A client is a container-managed connection to an external service. Clients handle network communication — HTTP APIs, WebSocket connections, GraphQL endpoints. They extend \`RestClient\` (for HTTP), \`WebSocketClient\` (for WS), or the base \`Client\` class.
@@ -446,9 +458,8 @@ When to build a client:
 
 \`\`\`ts
 import { z } from 'zod'
-import { Client, clients, RestClient } from '@soederpop/luca/client'
+import { Client, RestClient } from '@soederpop/luca/client'
 import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
 \`\`\`
 
 Use \`RestClient\` for HTTP APIs (most common). It gives you \`get\`, \`post\`, \`put\`, \`patch\`, \`delete\` methods that handle JSON, headers, and error wrapping.
@@ -471,6 +482,8 @@ export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
 
 ## Class
 
+Running \`luca introspect\` captures JSDoc blocks and Zod schemas and includes them in the description whenever somebody calls \`container.clients.describe('{{camelName}}')\` or \`luca describe {{camelName}}\`.
+
 \`\`\`ts
 /**
  * {{description}}
@@ -486,14 +499,14 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
   static override shortcut = 'clients.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
-
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    options = {
-      ...options,
-      baseURL: options.baseURL || 'https://api.example.com',
-    }
-    super(options, context)
+  static { Client.register(this, '{{camelName}}') }
+
+  /**
+   * Called after the client is initialized. Use this for any setup logic
+   * instead of overriding the constructor.
+   */
+  async afterInitialize() {
+    // Set up default headers, configure auth, etc.
   }
 
   // Add API methods here. Each wraps an endpoint.
@@ -504,6 +517,8 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
 }
 \`\`\`
 
+**Important**: You almost never need to override the constructor. Use \`afterInitialize()\` for setup logic — it runs after the client is fully wired into the container. Set \`baseURL\` via the options schema default instead of constructor manipulation.
+
 ## Module Augmentation
 
 \`\`\`ts
@@ -516,17 +531,22 @@ declare module '@soederpop/luca/client' {
 
 ## Registration
 
+Registration happens inside the class body using a static block. The default export is just the class itself.
+
 \`\`\`ts
-export default clients.register('{{camelName}}', {{PascalName}})
+// Inside the class:
+static { Client.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}
 \`\`\`
 
 ## Complete Example
 
 \`\`\`ts
 import { z } from 'zod'
-import { clients, RestClient } from '@soederpop/luca/client'
+import { Client, RestClient } from '@soederpop/luca/client'
 import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
 
 declare module '@soederpop/luca/client' {
   interface AvailableClients {
@@ -556,31 +576,32 @@ export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName
   static override shortcut = 'clients.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Client.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super({ ...options, baseURL: options.baseURL }, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default clients.register('{{camelName}}', {{PascalName}})
+export default {{PascalName}}
 \`\`\`
 
 ## Conventions
 
 - **Extend RestClient for HTTP**: It gives you typed HTTP methods. Only use base \`Client\` if you need a non-HTTP protocol.
-- **Set baseURL in constructor**: Override options to hardcode or default the API base URL.
+- **Set baseURL via options schema**: Use a Zod \`.default()\` on the \`baseURL\` field rather than overriding the constructor.
+- **Use \`afterInitialize()\`**: For any setup logic (auth, default headers, etc.) instead of overriding the constructor.
 - **Wrap endpoints as methods**: Each API endpoint gets a method. Keep them thin — just map to HTTP calls.
-- **JSDoc everything**: Every public method needs \`@param\`, \`@returns\`, \`@example\`.
-- **Auth in options**: Pass API keys, tokens via options schema. Check them in the constructor or a setup method.
+- **JSDoc everything**: Every public method needs \`@param\`, \`@returns\`, \`@example\`. Run \`luca introspect\` after changes to update generated docs.
+- **Auth in options**: Pass API keys, tokens via options schema. Check them in \`afterInitialize()\` or a setup method.
 `,
   },
   server: {
     sections: [
       { heading: "Imports", code: `import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'` },
       { heading: "Schemas", code: `export const {{PascalName}}StateSchema = ServerStateSchema.extend({
   // Add your state fields here.
@@ -614,7 +635,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -651,11 +672,15 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
     {{camelName}}: typeof {{PascalName}}
   }
 }` },
-      { heading: "Registration", code: `export default servers.register('{{camelName}}', {{PascalName}})` },
+      { heading: "Registration", code: `// Inside the class:
+static { Server.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}` },
       { heading: "Complete Example", code: `import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
@@ -688,7 +713,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -717,12 +742,12 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   }
 }
 
-export default servers.register('{{camelName}}', {{PascalName}})` }
+export default {{PascalName}}` }
     ],
     full: `import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
@@ -755,7 +780,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -784,7 +809,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   }
 }
 
-export default servers.register('{{camelName}}', {{PascalName}})`,
+export default {{PascalName}}`,
     tutorial: `# Building a Server
 
 A server is a container-managed listener — something that accepts connections and handles requests. Servers manage their own lifecycle (configure, start, stop) and expose observable state.
@@ -798,9 +823,9 @@ When to build a server:
 
 \`\`\`ts
 import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'
 \`\`\`
 
@@ -827,6 +852,8 @@ export const {{PascalName}}EventsSchema = ServerEventsSchema.extend({
 
 ## Class
 
+Running \`luca introspect\` captures JSDoc blocks and Zod schemas and includes them in the description whenever somebody calls \`container.servers.describe('{{camelName}}')\` or \`luca describe {{camelName}}\`.
+
 \`\`\`ts
 /**
  * {{description}}
@@ -844,7 +871,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -890,17 +917,23 @@ declare module '@soederpop/luca' {
 
 ## Registration
 
+Registration happens inside the class body using a static block. The default export is just the class itself.
+
 \`\`\`ts
-export default servers.register('{{camelName}}', {{PascalName}})
+// Inside the class:
+static { Server.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}
 \`\`\`
 
 ## Complete Example
 
 \`\`\`ts
 import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
@@ -933,7 +966,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -962,100 +995,101 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   }
 }
 
-export default servers.register('{{camelName}}', {{PascalName}})
+export default {{PascalName}}
 \`\`\`
 
 ## Conventions
 
 - **Lifecycle**: Implement \`configure()\`, \`start()\`, and \`stop()\`. Check guards (\`isConfigured\`, \`isListening\`, \`isStopped\`) at the top of each.
+- **Use \`afterInitialize()\`**: For any setup logic instead of overriding the constructor. Lifecycle methods (\`configure\`, \`start\`, \`stop\`) handle the server's runtime phases.
 - **State tracking**: Set \`configured\`, \`listening\`, \`stopped\`, and \`port\` on the state. This powers the introspection system.
 - **attach() is static**: It runs when the container first loads the server class. Use it for container-level setup if needed.
 - **Port from options**: Accept port via options schema and respect it in \`start()\`. Allow override via start options.
-- **JSDoc everything**: Every public method needs \`@param\`, \`@returns\`, \`@example\`.
+- **JSDoc everything**: Every public method needs \`@param\`, \`@returns\`, \`@example\`. Run \`luca introspect\` after changes to update generated docs.
 `,
   },
   command: {
     sections: [
       { heading: "Imports", code: `import { z } from 'zod'
-import { commands, CommandOptionsSchema } from '@soederpop/luca'
 import type { ContainerContext } from '@soederpop/luca'` },
-      { heading: "Args Schema", code: `export const argsSchema = CommandOptionsSchema.extend({
-  // Add your flags here. Each becomes a --flag on the CLI.
-  // Example: verbose: z.boolean().default(false).describe('Enable verbose output'),
-  // Example: output: z.string().optional().describe('Output file path'),
+      { heading: "Positional Arguments", code: `// luca {{kebabName}} ./src  =>  options.target === './src'
+export const positionals = ['target']` },
+      { heading: "Args Schema", code: `export const argsSchema = z.object({
+  // Positional: first arg after command name (via positionals array above)
+  // target: z.string().optional().describe('The target to operate on'),
+
+  // Flags: passed as --flag on the CLI
+  // verbose: z.boolean().default(false).describe('Enable verbose output'),
+  // output: z.string().optional().describe('Output file path'),
 })` },
+      { heading: "Description", code: `export const description = '{{description}}'` },
       { heading: "Handler", code: `export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const container = context.container as any
+  const { container } = context
   const fs = container.feature('fs')
-  const args = container.argv._ as string[]
 
-  // args[0] is your command name, args[1+] are positional arguments
-  // options contains parsed --flags
+  // options.target is set from the first positional arg (via positionals export)
+  // options.verbose, options.output, etc. come from --flags
 
   // Your implementation here
-}` },
-      { heading: "Registration", code: `commands.registerHandler('{{camelName}}', {
-  description: '{{description}}',
-  argsSchema,
-  handler: {{camelName}},
-})` },
-      { heading: "Module Augmentation", code: `declare module '@soederpop/luca' {
-  interface AvailableCommands {
-    {{camelName}}: ReturnType<typeof commands.registerHandler>
-  }
 }` },
       { heading: "Complete Example", code: `import { z } from 'zod'
-import { commands, CommandOptionsSchema } from '@soederpop/luca'
 import type { ContainerContext } from '@soederpop/luca'
 
-declare module '@soederpop/luca' {
-  interface AvailableCommands {
-    {{camelName}}: ReturnType<typeof commands.registerHandler>
-  }
-}
+export const description = '{{description}}'
 
-export const argsSchema = CommandOptionsSchema.extend({})
+// Map positional args to named options: luca {{kebabName}} myTarget => options.target === 'myTarget'
+export const positionals = ['target']
+
+export const argsSchema = z.object({
+  target: z.string().optional().describe('The target to operate on'),
+})
 
 export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const container = context.container as any
+  const { container } = context
   const fs = container.feature('fs')
 
-  console.log('{{camelName}} running...')
-}
+  console.log('{{kebabName}} running...', options.target)
+}` },
+      { heading: "Container Properties", code: `export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  // Current working directory
+  container.cwd                    // '/path/to/project'
+
+  // Path utilities (scoped to cwd)
+  container.paths.resolve('src')   // '/path/to/project/src'
+  container.paths.join('a', 'b')   // '/path/to/project/a/b'
+  container.paths.relative('src')  // 'src'
+
+  // Package manifest (parsed package.json)
+  container.manifest.name          // 'my-project'
+  container.manifest.version       // '1.0.0'
 
-commands.registerHandler('{{camelName}}', {
-  description: '{{description}}',
-  argsSchema,
-  handler: {{camelName}},
-})` }
+  // Raw CLI arguments (from minimist) — prefer positionals export for positional args
+  container.argv                   // { _: ['{{kebabName}}', ...], verbose: true, ... }
+}` }
     ],
     full: `import { z } from 'zod'
-import { commands, CommandOptionsSchema } from '@soederpop/luca'
 import type { ContainerContext } from '@soederpop/luca'
 
-declare module '@soederpop/luca' {
-  interface AvailableCommands {
-    {{camelName}}: ReturnType<typeof commands.registerHandler>
-  }
-}
+export const description = '{{description}}'
+
+// Map positional args to named options: luca {{kebabName}} myTarget => options.target === 'myTarget'
+export const positionals = ['target']
 
-export const argsSchema = CommandOptionsSchema.extend({})
+export const argsSchema = z.object({
+  target: z.string().optional().describe('The target to operate on'),
+})
 
 export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const container = context.container as any
+  const { container } = context
   const fs = container.feature('fs')
 
-  console.log('{{camelName}} running...')
-}
-
-commands.registerHandler('{{camelName}}', {
-  description: '{{description}}',
-  argsSchema,
-  handler: {{camelName}},
-})`,
+  console.log('{{kebabName}} running...', options.target)
+}`,
     tutorial: `# Building a Command
 
-A command extends the \`luca\` CLI. Commands live in a project's \`commands/\` folder and are automatically discovered. They receive parsed options and a container context.
+A command extends the \`luca\` CLI. Commands live in a project's \`commands/\` folder and are automatically discovered. They are Helper subclasses under the hood — the framework grafts your module exports into a Command class at runtime.
 
 When to build a command:
 - You need a CLI task for a project (build scripts, generators, automation)
@@ -1066,60 +1100,54 @@ When to build a command:
 
 \`\`\`ts
 import { z } from 'zod'
-import { commands, CommandOptionsSchema } from '@soederpop/luca'
 import type { ContainerContext } from '@soederpop/luca'
 \`\`\`
 
-## Args Schema
+## Positional Arguments
 
-Define your command's arguments and flags. Extend \`CommandOptionsSchema\` which gives you \`_\` (positional args) and \`name\` for free.
+Export a \`positionals\` array to map CLI positional args into named options fields. The first positional (\`_[0]\`) is always the command name — \`positionals\` maps \`_[1]\`, \`_[2]\`, etc.
 
 \`\`\`ts
-export const argsSchema = CommandOptionsSchema.extend({
-  // Add your flags here. Each becomes a --flag on the CLI.
-  // Example: verbose: z.boolean().default(false).describe('Enable verbose output'),
-  // Example: output: z.string().optional().describe('Output file path'),
-})
+// luca {{kebabName}} ./src  =>  options.target === './src'
+export const positionals = ['target']
 \`\`\`
 
-## Handler
+## Args Schema
 
-The handler function receives parsed options and the container context. Use the container for all I/O.
+Define your command's arguments and flags with Zod. Each field becomes a \`--flag\` on the CLI. Fields named in \`positionals\` also accept positional args.
 
 \`\`\`ts
-export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const container = context.container as any
-  const fs = container.feature('fs')
-  const args = container.argv._ as string[]
+export const argsSchema = z.object({
+  // Positional: first arg after command name (via positionals array above)
+  // target: z.string().optional().describe('The target to operate on'),
 
-  // args[0] is your command name, args[1+] are positional arguments
-  // options contains parsed --flags
-
-  // Your implementation here
-}
+  // Flags: passed as --flag on the CLI
+  // verbose: z.boolean().default(false).describe('Enable verbose output'),
+  // output: z.string().optional().describe('Output file path'),
+})
 \`\`\`
 
-## Registration
+## Description
 
-Register the command at the bottom of the file. The \`description\` shows up in \`luca --help\`.
+Export a description string for \`luca --help\` display:
 
 \`\`\`ts
-commands.registerHandler('{{camelName}}', {
-  description: '{{description}}',
-  argsSchema,
-  handler: {{camelName}},
-})
+export const description = '{{description}}'
 \`\`\`
 
-## Module Augmentation
+## Handler
 
-Optional but gives TypeScript autocomplete for \`commands.lookup('yourCommand')\`.
+Export a default async function. It receives parsed options and the container context. Use the container for all I/O. Positional args declared in the \`positionals\` export are available as named fields on \`options\`.
 
 \`\`\`ts
-declare module '@soederpop/luca' {
-  interface AvailableCommands {
-    {{camelName}}: ReturnType<typeof commands.registerHandler>
-  }
+export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  const fs = container.feature('fs')
+
+  // options.target is set from the first positional arg (via positionals export)
+  // options.verbose, options.output, etc. come from --flags
+
+  // Your implementation here
 }
 \`\`\`
 
@@ -1127,58 +1155,78 @@ declare module '@soederpop/luca' {
 
 \`\`\`ts
 import { z } from 'zod'
-import { commands, CommandOptionsSchema } from '@soederpop/luca'
 import type { ContainerContext } from '@soederpop/luca'
 
-declare module '@soederpop/luca' {
-  interface AvailableCommands {
-    {{camelName}}: ReturnType<typeof commands.registerHandler>
-  }
-}
+export const description = '{{description}}'
 
-export const argsSchema = CommandOptionsSchema.extend({})
+// Map positional args to named options: luca {{kebabName}} myTarget => options.target === 'myTarget'
+export const positionals = ['target']
+
+export const argsSchema = z.object({
+  target: z.string().optional().describe('The target to operate on'),
+})
 
 export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const container = context.container as any
+  const { container } = context
   const fs = container.feature('fs')
 
-  console.log('{{camelName}} running...')
+  console.log('{{kebabName}} running...', options.target)
 }
+\`\`\`
 
-commands.registerHandler('{{camelName}}', {
-  description: '{{description}}',
-  argsSchema,
-  handler: {{camelName}},
-})
+## Container Properties
+
+The \`context.container\` object provides useful properties beyond features:
+
+\`\`\`ts
+export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  // Current working directory
+  container.cwd                    // '/path/to/project'
+
+  // Path utilities (scoped to cwd)
+  container.paths.resolve('src')   // '/path/to/project/src'
+  container.paths.join('a', 'b')   // '/path/to/project/a/b'
+  container.paths.relative('src')  // 'src'
+
+  // Package manifest (parsed package.json)
+  container.manifest.name          // 'my-project'
+  container.manifest.version       // '1.0.0'
+
+  // Raw CLI arguments (from minimist) — prefer positionals export for positional args
+  container.argv                   // { _: ['{{kebabName}}', ...], verbose: true, ... }
+}
 \`\`\`
 
 ## Conventions
 
-- **File location**: \`commands/{{camelName}}.ts\` in the project root. The \`luca\` CLI discovers these automatically.
-- **Naming**: camelCase for both file and registration ID. \`luca my-command\` maps to \`commands/my-command.ts\`.
+- **File location**: \`commands/{{kebabName}}.ts\` in the project root. The \`luca\` CLI discovers these automatically.
+- **Naming**: kebab-case for filename. \`luca {{kebabName}}\` maps to \`commands/{{kebabName}}.ts\`.
 - **Use the container**: Never import \`fs\`, \`path\`, \`child_process\` directly. Use \`container.feature('fs')\`, \`container.paths\`, \`container.feature('proc')\`.
-- **Positional args**: Access via \`container.argv._\` — it's an array where \`_[0]\` is the command name.
+- **Positional args**: Export \`positionals = ['name1', 'name2']\` to map CLI positional args into named options fields. For raw access, use \`container.argv._\` where \`_[0]\` is the command name.
 - **Exit codes**: Return nothing for success. Throw for errors — the CLI catches and reports them.
+- **Help text**: Use \`.describe()\` on every schema field — it powers \`luca {{kebabName}} --help\`.
 `,
   },
   endpoint: {
     sections: [
-      { heading: "Imports", code: `import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'` },
       { heading: "Required Exports", code: `export const path = '/api/{{camelName}}'
 export const description = '{{description}}'
 export const tags = ['{{camelName}}']` },
-      { heading: "Handler Functions", code: `export async function get(params: any, ctx: EndpointContext) {
+      { heading: "Handler Functions", code: `export async function get(params: any, ctx: any) {
   const fs = ctx.container.feature('fs')
   // Your logic here
   return { message: 'ok' }
 }
 
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   // Create something
   return { created: true }
 }` },
-      { heading: "Validation Schemas", code: `export const getSchema = z.object({
+      { heading: "Validation Schemas", code: `import { z } from 'zod'
+
+export const getSchema = z.object({
   q: z.string().optional().describe('Search query'),
   limit: z.number().default(20).describe('Max results'),
 })
@@ -1192,82 +1240,66 @@ export const rateLimit = { maxRequests: 100, windowSeconds: 60 }
 
 // Per-method rate limit
 export const postRateLimit = { maxRequests: 10, windowSeconds: 1 }` },
-      { heading: "Delete Handler", code: `const del = async (params: any, ctx: EndpointContext) => {
+      { heading: "Delete Handler", code: `// Use a local name, then re-export as \`delete\`
+const del = async (params: any, ctx: any) => {
   return { deleted: true }
 }
 export { del as delete }` },
-      { heading: "Complete Example", code: `import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
-export const path = '/api/{{camelName}}'
+      { heading: "Complete Example", code: `export const path = '/api/{{camelName}}'
 export const description = '{{description}}'
 export const tags = ['{{camelName}}']
 
-export const getSchema = z.object({
-  q: z.string().optional().describe('Search query'),
-})
-
-export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   return { items: [], total: 0 }
 }
 
-export const postSchema = z.object({
-  name: z.string().min(1).describe('Item name'),
-})
-
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   return { item: { id: '1', ...params }, message: 'Created' }
-}` },
-      { heading: "Dynamic Route Example", code: `// endpoints/{{camelName}}/[id].ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
+}
 
+const del = async (params: any, ctx: any) => {
+  const { id } = ctx.params
+  return { message: \`Deleted \${id}\` }
+}
+export { del as delete }` },
+      { heading: "Dynamic Route Example", code: `// endpoints/{{camelName}}/[id].ts
 export const path = '/api/{{camelName}}/:id'
 export const description = 'Get, update, or delete a specific item'
 export const tags = ['{{camelName}}']
 
-export async function get(params: any, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   const { id } = ctx.params
   return { item: { id } }
 }
 
-export const putSchema = z.object({
-  name: z.string().min(1).optional().describe('Updated name'),
-})
-
-export async function put(params: z.infer<typeof putSchema>, ctx: EndpointContext) {
+export async function put(params: any, ctx: any) {
   const { id } = ctx.params
   return { item: { id, ...params }, message: 'Updated' }
 }
 
-const del = async (params: any, ctx: EndpointContext) => {
+const del = async (params: any, ctx: any) => {
   const { id } = ctx.params
   return { message: \`Deleted \${id}\` }
 }
 export { del as delete }` }
     ],
-    full: `import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
-export const path = '/api/{{camelName}}'
+    full: `export const path = '/api/{{camelName}}'
 export const description = '{{description}}'
 export const tags = ['{{camelName}}']
 
-export const getSchema = z.object({
-  q: z.string().optional().describe('Search query'),
-})
-
-export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   return { items: [], total: 0 }
 }
 
-export const postSchema = z.object({
-  name: z.string().min(1).describe('Item name'),
-})
-
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   return { item: { id: '1', ...params }, message: 'Created' }
-}`,
+}
+
+const del = async (params: any, ctx: any) => {
+  const { id } = ctx.params
+  return { message: \`Deleted \${id}\` }
+}
+export { del as delete }`,
     tutorial: `# Building an Endpoint
 
 An endpoint is a route handler that \`luca serve\` auto-discovers and mounts on an Express server. Endpoints live in \`endpoints/\` and follow a file-based routing convention — each file becomes an API route with automatic validation, OpenAPI spec generation, and rate limiting.
@@ -1288,12 +1320,14 @@ Run \`luca serve\` and they're automatically discovered and mounted.
 
 ## Imports
 
-\`\`\`ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-\`\`\`
+Endpoints are lightweight — just exports and handler functions. No imports are required.
+
+If your project has \`@soederpop/luca\` as an npm dependency, you can import \`z\` from \`zod\` and \`EndpointContext\` from \`@soederpop/luca\` for type safety. Otherwise, use \`any\` types — the framework handles validation and context injection for you.
 
-That's it. Endpoints are lightweight — just exports and functions.
+Access framework capabilities through the \`ctx\` parameter:
+- \`ctx.container.feature('fs')\` for file operations
+- \`ctx.container.feature('yaml')\` for YAML parsing
+- \`ctx.container.feature('sqlite')\` for database access
 
 ## Required Exports
 
@@ -1307,16 +1341,16 @@ export const tags = ['{{camelName}}']
 
 ## Handler Functions
 
-Export named functions for each HTTP method you support. Each receives validated parameters and an \`EndpointContext\`:
+Export named functions for each HTTP method you support. Each receives validated parameters and a context object:
 
 \`\`\`ts
-export async function get(params: any, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   const fs = ctx.container.feature('fs')
   // Your logic here
   return { message: 'ok' }
 }
 
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   // Create something
   return { created: true }
 }
@@ -1334,9 +1368,11 @@ Return any object — it's automatically JSON-serialized as the response.
 
 ## Validation Schemas
 
-Export Zod schemas to validate parameters for each method. Name them \`{method}Schema\`:
+If \`zod\` is available (via \`@soederpop/luca\` dependency or \`node_modules\`), export Zod schemas to validate parameters for each method. Name them \`{method}Schema\`:
 
 \`\`\`ts
+import { z } from 'zod'
+
 export const getSchema = z.object({
   q: z.string().optional().describe('Search query'),
   limit: z.number().default(20).describe('Max results'),
@@ -1348,7 +1384,7 @@ export const postSchema = z.object({
 })
 \`\`\`
 
-Invalid requests automatically return 400 with Zod error details. Schemas also feed the auto-generated OpenAPI spec.
+Invalid requests automatically return 400 with Zod error details. Schemas also feed the auto-generated OpenAPI spec. If zod is not available, skip schema exports — the endpoint still works, you just lose automatic validation.
 
 ## Rate Limiting
 
@@ -1364,42 +1400,40 @@ export const postRateLimit = { maxRequests: 10, windowSeconds: 1 }
 
 ## Delete Handler
 
-\`delete\` is a reserved word in JS. Use an alias:
+\`delete\` is a reserved word in JS, so you can't use it as a function name directly. Use a named export alias:
 
 \`\`\`ts
-const del = async (params: any, ctx: EndpointContext) => {
+// Use a local name, then re-export as \`delete\`
+const del = async (params: any, ctx: any) => {
   return { deleted: true }
 }
 export { del as delete }
 \`\`\`
 
+You can also export \`deleteSchema\` and \`deleteRateLimit\` for validation and rate limiting on DELETE.
+
 ## Complete Example
 
-A CRUD endpoint for a resource:
+A CRUD endpoint for a resource (no external imports needed):
 
 \`\`\`ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
 export const path = '/api/{{camelName}}'
 export const description = '{{description}}'
 export const tags = ['{{camelName}}']
 
-export const getSchema = z.object({
-  q: z.string().optional().describe('Search query'),
-})
-
-export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   return { items: [], total: 0 }
 }
 
-export const postSchema = z.object({
-  name: z.string().min(1).describe('Item name'),
-})
-
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   return { item: { id: '1', ...params }, message: 'Created' }
 }
+
+const del = async (params: any, ctx: any) => {
+  const { id } = ctx.params
+  return { message: \`Deleted \${id}\` }
+}
+export { del as delete }
 \`\`\`
 
 ## Dynamic Route Example
@@ -1408,28 +1442,21 @@ For routes with URL parameters, create a nested file:
 
 \`\`\`ts
 // endpoints/{{camelName}}/[id].ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
 export const path = '/api/{{camelName}}/:id'
 export const description = 'Get, update, or delete a specific item'
 export const tags = ['{{camelName}}']
 
-export async function get(params: any, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   const { id } = ctx.params
   return { item: { id } }
 }
 
-export const putSchema = z.object({
-  name: z.string().min(1).optional().describe('Updated name'),
-})
-
-export async function put(params: z.infer<typeof putSchema>, ctx: EndpointContext) {
+export async function put(params: any, ctx: any) {
   const { id } = ctx.params
   return { item: { id, ...params }, message: 'Updated' }
 }
 
-const del = async (params: any, ctx: EndpointContext) => {
+const del = async (params: any, ctx: any) => {
   const { id } = ctx.params
   return { message: \`Deleted \${id}\` }
 }
@@ -1444,10 +1471,185 @@ export { del as delete }
 - **Use the container**: Access features via \`ctx.container.feature('fs')\`, not Node.js imports.
 - **Return objects**: Handler return values are JSON-serialized. Use \`ctx.response\` only for streaming or custom status codes.
 - **OpenAPI for free**: Your \`path\`, \`description\`, \`tags\`, and schemas automatically generate an OpenAPI spec at \`/openapi.json\`.
+`,
+  },
+  selector: {
+    sections: [
+      { heading: "Imports", code: `import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'` },
+      { heading: "Args Schema", code: `export const argsSchema = z.object({
+  // Add your input arguments here.
+  // Example: field: z.string().optional().describe('Specific field to return'),
+})` },
+      { heading: "Description", code: `export const description = '{{description}}'` },
+      { heading: "Caching", code: `export function cacheKey(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  return context.container.git.currentCommitSha
+}` },
+      { heading: "Caching", code: `export const cacheable = false` },
+      { heading: "Handler", code: `export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  // Query and return your data
+  return { /* your data */ }
+}` },
+      { heading: "Complete Example", code: `import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = '{{description}}'
+
+export const argsSchema = z.object({})
+
+export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  // Return your data here
+  return {}
+}` }
+    ],
+    full: `import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = '{{description}}'
+
+export const argsSchema = z.object({})
+
+export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  // Return your data here
+  return {}
+}`,
+    tutorial: `# Building a Selector
+
+A selector returns data. Where commands perform actions, selectors query and return structured results with built-in caching. Selectors live in a project's \`selectors/\` folder and are automatically discovered.
+
+When to build a selector:
+- You need to query project data (package info, file listings, config values)
+- The result benefits from caching (keyed by git SHA or custom key)
+- You want the data available via \`container.select('name')\` or \`luca select name\`
+
+## Imports
+
+\`\`\`ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+\`\`\`
+
+## Args Schema
+
+Define the selector's input arguments with Zod.
+
+\`\`\`ts
+export const argsSchema = z.object({
+  // Add your input arguments here.
+  // Example: field: z.string().optional().describe('Specific field to return'),
+})
+\`\`\`
+
+## Description
+
+Export a description string for discoverability:
+
+\`\`\`ts
+export const description = '{{description}}'
+\`\`\`
+
+## Caching
+
+Selectors cache by default. The default cache key is \`hashObject({ selectorName, args, gitSha })\` — same args + same commit = cache hit.
+
+To customize the cache key:
+
+\`\`\`ts
+export function cacheKey(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  return context.container.git.currentCommitSha
+}
+\`\`\`
+
+To disable caching:
+
+\`\`\`ts
+export const cacheable = false
+\`\`\`
+
+## Handler
+
+Export a \`run\` function that returns data. It receives parsed args and the container context.
+
+\`\`\`ts
+export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  // Query and return your data
+  return { /* your data */ }
+}
+\`\`\`
+
+## Complete Example
+
+\`\`\`ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = '{{description}}'
+
+export const argsSchema = z.object({})
+
+export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  // Return your data here
+  return {}
+}
+\`\`\`
+
+## Conventions
+
+- **File location**: \`selectors/{{kebabName}}.ts\` in the project root. Discovered automatically.
+- **Naming**: kebab-case for filename. \`luca select {{kebabName}}\` maps to \`selectors/{{kebabName}}.ts\`.
+- **Use the container**: Never import \`fs\`, \`path\` directly. Use \`container.feature('fs')\`, \`container.paths\`.
+- **Return data**: The \`run\` function must return the data. It gets wrapped in \`{ data, cached, cacheKey }\` by the framework.
+- **Caching**: On by default. Override \`cacheKey()\` for custom invalidation, or set \`cacheable = false\` to skip.
+- **CLI**: \`luca select {{kebabName}}\` runs the selector and prints JSON. Use \`--json\` for data only, \`--no-cache\` to force fresh.
 `,
   }
 }
 
+export const assistantFiles: Record<string, string> = {
+    "CORE.md": `# Luca Assistant Example
+
+You are currently an example / template "Assistant" provided by the Luca framework.  ( You'll probably have no idea what that is, don't worry, it doesn't matter ).
+
+You are what gets scaffolded when a user writes the \`luca scaffold assistant\` command.
+
+In luca, an Assistant is backed by a folder which has a few components:
+
+- CORE.md -- this is a markdown file that will get injected into the system prompt of a chat completion call
+- tools.ts -- this file is expected to export functions, and a schemas object whose keys are the names of the functions that get exported, and whose values are zod v4 schemas that describe the parameters
+- hooks.ts -- this file is expexted to export functions, whose names match the events emitted by the luca assistant helper
+
+Currently, the user is chatting with you from the \`luca chat\` CLI.  
+
+You should tell them what each of these files is and how to edit them.
+
+It is also important for them to know that the luca \`container\` is globally available for them in the context of the \`tools.ts\` and \`hooks.ts\` files.
+
+`,
+    "tools.ts": `import { z } from 'zod'
+
+export const schemas = {
+	README: z.object({}).describe('CALL THIS README FUNCTION AS EARLY AS POSSIBLE')
+}
+
+export function README(options: z.infer<typeof schemas.README>) {
+	return 'YO YO'
+}
+
+`,
+    "hooks.ts": `export function started() {
+	console.log('Assistant started!')
+}
+`
+}
+
 export const mcpReadme = `# Luca Development Guide
 
 You are working in a **luca project**. The luca container provides all capabilities your code needs. Do not install npm packages or import Node.js builtins directly.