luca 3.0.0 → 3.0.2

package/docs/philosophy.md

@@ -1,86 +0,0 @@
-# Luca's Philosophy
-
-> LUCA - Lightweight Universal Conversational Architecture.
-
-If you open up a Developer console on a blank HTML page, you have the `window` object and the `document` object, and from those objects you have everything you need to build every web application you've ever interacted with, IN THEORY, without ever reloading the page.
-
-Obviously nobody builds applications this way in a single REPL, but in 2026 developers are people and Agent AIs collaborating on the same codebase in a bigger Read, Eval, Print, Loop that takes place across more computers and brains.
-
-Luca aims to provide a `container` object that gets you 60% of the way to having ANY kind of real world, production grade full stack software, before you ever write your own line of application code. As the types of applications you build and who you build them for further narrow, the container can grow to cover 95% of every boring but necessary component you need.
-
-How? By layering, the way you layer dockerfiles. The things which change least frequently are solved once and cached. The things which change more frequently live in their own isolated layer. That loop is smaller, quicker — the difference between a dockerfile that reinstalls the OS every time you change the HTML file, and one that doesn't.
-
-## The Layer Model
-> Cache to the max == CA$H to the max
-> 
-Think of it like docker layers:
-
-**Layer 1: Platform** — `NodeContainer`, `WebContainer`. Features that are universally applicable to any application in that runtime. Filesystem, networking, process management, event buses, observable state. You solve this once.
-
-**Layer 2: Domain** — `AGIContainer`, or imagine a `RestaurantContainer`, `FinanceContainer`. Features, clients, servers specific to that category of application. You solve this rarely.
-
-**Layer 3: The Actual Work** — The specific thing you're building for the specific person who needs it. This is what changes every day.
-
-Layer 1 and Layer 2 you solve once and almost never again. When you get to Layer 3, everything is so specific that it changes constantly. The entire point is to spend all of your energy on Layer 3. If you fix something in Layer 1, every project that uses it benefits immediately — just like every docker image based on alpine benefits when alpine patches something.
-
-The `container` is the central piece. You build it in layers with components that are stable enough to be reused across tasks, use cases, projects, and clients. And since it's JavaScript, it works in the browser or the server. Build a GitHub client in one project, add it to the container, start a brand new project with that same container, and the GitHub client is already there.
-
-## Helpers and Registries: Conversational Dependency Injection
-
-The `container` provides `Registries` of `Helpers`. A `Helper` is a formal, consistent interface for a category of thing. Features can be enabled. Servers can be started and stopped. Clients can be connected. Commands can be run. These "things" share common lifecycles (state) and emit similar events (started, connected, enabled). Clients, servers, features are part of almost every application I've built for 20 years, but every domain has its own categories too — Helpers can be customized to represent those.
-
-`Registries` are a central place for storing the various implementations and being able to discover which ones are available.
-
-The `container` provides factory functions — `feature()`, `server()`, `client()` — to create instances. Every helper instance has its own event bus, its own observable state, can be `introspected()` at runtime, and has fully typed interfaces that light up your IDE.
-
-## Why "Conversational"?
-
-The name means two things at once.
-
-First, you can literally talk to the container. Give an LLM access to the container object and tool calls, and it can discover what's available, learn how to use it, and build with it — all at runtime. The introspection system means nothing is hidden. Every feature, every method signature, every event, every state shape is discoverable programmatically.
-
-Second, the components talk to each other. Observable state, event buses, and well-documented typed interfaces mean that everything in the system can react to everything else through formal, predictable channels. Not magic strings and implicit coupling — actual typed contracts with build-time autocomplete and runtime introspection of the same.
-
-## A Shared Mental Model
-
-This is the real thesis.
-
-The human and the AI share the same mental model of how the code should be organized and structured. The human isn't just directing the AI — they're collaborating inside the same architecture, speaking the same language about the same things.
-
-A human defines the Helper — the interface, the lifecycle, the state shape, the events it emits. They decide *what* a thing is, *how* it behaves from the outside, and *where* it lives in the system. The AI understands that same structure and works within it. When the human says "make a client for Stripe," the AI already knows what a Client is, where it goes, what interface it needs to satisfy, and what lifecycle it follows. They're not negotiating from scratch every time — they're both operating from the same map.
-
-This matters because as AI builds more and more of the internals, the human still feels at home. The organization of the code is still theirs. The names are theirs. The architecture is theirs. The folder structure, the class hierarchy, the way things relate to each other — that's their map, and the AI respects it because the AI shares it.
-
-Defining Helpers is how a human says "in my world, these are the categories of things that exist, and this is how they work." The AI doesn't need to understand *why* those categories make sense for the business or the domain — it just needs the interface contract and it can implement anything that satisfies it.
-
-## Trust Through Composition
-
-Here's where it gets really interesting.
-
-Because everything is captured as Helpers with formal interfaces, every component can be reviewed, audited, and secured independently. You can track provenance — who wrote it, when, what it depends on. A Helper that's been vetted is a Helper you can trust.
-
-Over time, the AI generates less and less net-new code. Instead, it composes with existing Helpers — calling their interfaces, subscribing to their events, reading their state. The new code it does write gets captured into new Helpers that go through the same review cycle. The codebase becomes a growing library of trusted, audited building blocks.
-
-This flips the usual fear about AI-generated code on its head. Normally, the more an AI writes, the less confident you feel about what's in there. With Luca, the more an AI writes, the more it's using components you've already reviewed. The codebase gets *more* trustworthy as it grows, not less. The surface area of unreviewed code shrinks because the AI is reaching for existing Helpers instead of generating raw implementations from scratch every time.
-
-This also constrains the AI in a productive way. Instead of generating sprawling, unstructured code that the human has to reverse-engineer, the AI is given a clear place to put things and a clear shape they need to be. The result is a codebase that grows but stays navigable, because the human designed the map and the AI respects it.
-
-## The Agent Runtime
-
-Take this one step further.
-
-Imagine an Agent that already knows JavaScript like a master. Give it a `container` object. Through introspection alone, it can learn about every feature, server, client, and command available to it. It can discover their options, their observable state, the events they emit, and the signatures for all of these things. It can write code against them. It can modify itself at runtime. You can watch the thing being built, interact with it, steer it.
-
-This is not theoretical. The AGI container layer already does this — it wraps tools like Claude Code and OpenAI into the same Helper pattern, gives them the same observable state and event buses, and lets agents use the full container to build and extend themselves.
-
-The REPL-driven development style that Luca was originally designed for maps perfectly onto this. The same properties that make something nice to work with in a REPL — discoverability, introspection, observable state, immediate feedback — are exactly the properties that make something nice for an AI agent to work with.
-
-## Why This Architecture Specifically?
-
-Observable state, events, and well-documented APIs aren't arbitrary choices. They're specifically what makes things *conversational* in both senses:
-
-- **Observable state** means anything can watch anything else and react. Debugging, analytics, reporting, reactive UI patterns, data providers for React — all fall out naturally. An AI agent can monitor state to understand what's happening.
-- **Events** are the necessary primitive for JavaScript's async event loop, and they're also how components announce things to the rest of the system without needing to know who's listening. An AI agent can subscribe to events to understand what just happened.
-- **Introspection** means you never have to remember the specifics. You only need to know the philosophy, and the container will teach you the rest. This is true whether "you" is a human in a REPL or an AI agent with tool access.
-
-The fact that you can start from a single `container` object and learn everything it provides — how to interact with it, how to use it, what to expect from it — means the philosophy *is* the documentation. Know the pattern, and the system reveals itself.

package/docs/principles.md

@@ -1,7 +0,0 @@
-# Random Principles
-
-- I've built so many different client / server applications with JavaScript ( and many other languages ).  I've reinvented way too many things that could have been solved once.  The clearest example of this pain is a poorly structured dockerfile, e.g. one that reinstalls core os dependencies when you change an html file.
-
-- Nearly every application, I've structured as a "boss with liuetenants" so to speak, that everything else talked to.  The boss, the liuetenants, had some kind of state.  Events occur during their operations.  Sometimes these events need to be triggered.  Overtime, core patterns emerged, somewhat encouraged by popular frameworks in the shape they took or names I gave them.
-
-- In building Luca, we want to provide ways to ultimately narrow the range of possible outputs a first time developer, or AI assistant, might produce when asked to build something using a Luca `container` and its components.  The names themselves of the helpers, `clients`, `servers`, `features` already begin to describe their shape, purpose, where their code should live, etc. By going through the extra effort of building essentially a wrapper class, with descriptive interfaces, the developer will ultimately be delivering code that is easier to work with, and re-use in future efforts.

package/docs/prompts/audit-codebase-for-failures-to-use-the-container.md

@@ -1,34 +0,0 @@
----
-reusable: true
-lastRanAt: 1772162827313
-durationMs: 278913
-outputTokens: 552
----
-
-
-# Code Audit
-
-Do an audit of the code in the following folders:
-
-- src/**/features/**
-- src/**/clients/**
-- src/clients/**
-- src/servers/**
-- src/commands/**
-
-Ignore the fs, proc, git features in src/node/features.  These are a core abstraction that wraps the underlying ones provided by node or bun, so it is expected they would use child_process, fs, etc.  In general, if the feature you're looking at is intended to be wrapping a core runtime / os primitive, it is probably ok ( that's the point of the feature )
-
-if a completely unrelated feature is using the fs or path module, or Bun unguarded, then that's probably an issue.
-
-Look for instances of the following, but don't fix them yet.
-
-- using file system directly, instead of this.container.fs ( except the file system feature itself )
-- using the path module functions instead of this.container.paths.resolve ( with the exception of fileManager, where it is ok )
-- reinventing the wheel in general instead of using functionality already provided by the container
-- anything that would break compatibility with node.js instead of Bun.  make sure you wrap it in a guard (if this.container.isBun)
-
-Save the results of your audit in docs/reports/code-audit-results.md
-
-If this file already exists, read it first, and note cases where items persist.
-
-The next step will be me reviewing the audit, providing commentary, and advising you what to fix

package/docs/prompts/check-for-undocumented-features.md

@@ -1,27 +0,0 @@
----
-agentOptions:
-    permissionMode: bypassPermissions
----
-
-# Check for undocumented features
-
-The luca introspection and luca cli's describe command is powered by the JSDoc comments in the code base, and the values passed to the describe methods in the zod schema.  This documentation is what is fed to AI Coding assistants to be able to understand how to use the individual features
-
-Please scan the following paths:
-
-```ts
-const fm = await container.feature('fileManager').start()
-const results = fm.match(['src/node/features/*.ts', 'src/agi/features/*.ts', 'src/web/features/*.ts'])
-console.log(results.join("\n"))
-```
-
-Please ensure every feature has accurate and valid JSDoc documentation for the class definitions, methods, and getters.
-
-Validate the output of `bun run src/cli/cli.ts describe whatever` for each item you're working on, that it displays properly, is easy to understand, accurate, in terms of how your comments display there.  You may need to run `bun run src/cli/cli.ts introspect` to generate the build time data.
-
-You can pass `--platform=web` to see web specific output.
-
-## Quality not just Quantity
-
-- The presence of documentation isn't sufficient.  Is it good documentation? Is it not overly verbose? Does it not explain stuff that doesn't matter? Is it accurate? If there are examples, do they work?
-- The main consumer of `luca describe` will be an LLM so token budget matters.  Every word has to be doing work.  It should still be nice to look at for human coders too.

package/docs/prompts/mcp-test-easy-command.md

@@ -1,27 +0,0 @@
----
-target: claude
-reusable: true
-repeatable: true
----
-
-# MCP Test: Build a Command
-
-You are in an empty luca project. The `luca` CLI is available and you have a `luca-sandbox` MCP server connected.
-
-## Task
-
-Create a luca command called `greet` in `commands/greet.ts` that:
-
-1. Accepts a `--name` flag (string, defaults to "world")
-2. Accepts a `--shout` flag (boolean, defaults to false)
-3. Prints "Hello, {name}!" to stdout
-4. If `--shout` is true, uppercases the entire message
-
-The command should be runnable via `luca greet --name Jon --shout`.
-
-## Rules
-
-- Do not install any npm packages
-- Import only from `@soederpop/luca`
-- Use the MCP tools to learn the command pattern before writing code
-- After creating the file, verify it works by running `luca greet --name Test`

package/docs/scaffolds/client.md

@@ -1,149 +0,0 @@
-# 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.
-
-When to build a client:
-- You need to talk to an external API or service
-- You want connection management, error handling, and observability for free
-- You're wrapping an API so the rest of the codebase uses `container.client('name')`
-
-## Imports
-
-```ts
-import { z } from 'zod'
-import { Client, RestClient } from '@soederpop/luca/client'
-import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } 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.
-
-## Schemas
-
-```ts
-export const {{PascalName}}StateSchema = ClientStateSchema.extend({
-  // Add your state fields here.
-  // Example: authenticated: z.boolean().default(false).describe('Whether API auth is configured'),
-})
-export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
-
-export const {{PascalName}}OptionsSchema = ClientOptionsSchema.extend({
-  // Add constructor options here.
-  // Example: apiKey: z.string().optional().describe('API key for authentication'),
-})
-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}}
- *
- * @example
- * ```typescript
- * const {{camelName}} = container.client('{{camelName}}')
- * ```
- *
- * @extends RestClient
- */
-export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName}}Options> {
-  static override shortcut = 'clients.{{camelName}}' as const
-  static override stateSchema = {{PascalName}}StateSchema
-  static override optionsSchema = {{PascalName}}OptionsSchema
-  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.
-  // Example:
-  // async listItems(): Promise<Item[]> {
-  //   return this.get('/items')
-  // }
-}
-```
-
-**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
-declare module '@soederpop/luca/client' {
-  interface AvailableClients {
-    {{camelName}}: typeof {{PascalName}}
-  }
-}
-```
-
-## Registration
-
-Registration happens inside the class body using a static block. The default export is just the class itself.
-
-```ts
-// Inside the class:
-static { Client.register(this, '{{camelName}}') }
-
-// At module level:
-export default {{PascalName}}
-```
-
-## Complete Example
-
-```ts
-import { z } from 'zod'
-import { Client, RestClient } from '@soederpop/luca/client'
-import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca'
-
-declare module '@soederpop/luca/client' {
-  interface AvailableClients {
-    {{camelName}}: typeof {{PascalName}}
-  }
-}
-
-export const {{PascalName}}StateSchema = ClientStateSchema.extend({})
-export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
-
-export const {{PascalName}}OptionsSchema = ClientOptionsSchema.extend({
-  baseURL: z.string().default('https://api.example.com').describe('API base URL'),
-})
-export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
-
-/**
- * {{description}}
- *
- * @example
- * ```typescript
- * const {{camelName}} = container.client('{{camelName}}')
- * ```
- *
- * @extends RestClient
- */
-export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName}}Options> {
-  static override shortcut = 'clients.{{camelName}}' as const
-  static override stateSchema = {{PascalName}}StateSchema
-  static override optionsSchema = {{PascalName}}OptionsSchema
-  static { Client.register(this, '{{camelName}}') }
-
-  async afterInitialize() {
-    // Setup logic goes here — not in the constructor
-  }
-}
-
-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 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`. 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.

package/docs/scaffolds/command.md

@@ -1,120 +0,0 @@
-# Building a Command
-
-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)
-- You want argument parsing, help text, and container access for free
-- The task should be runnable via `luca yourCommand`
-
-## Imports
-
-```ts
-import { z } from 'zod'
-import type { ContainerContext } from '@soederpop/luca'
-```
-
-## Positional Arguments
-
-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
-// luca {{kebabName}} ./src  =>  options.target === './src'
-export const positionals = ['target']
-```
-
-## Args Schema
-
-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 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'),
-})
-```
-
-## Description
-
-Export a description string for `luca --help` display:
-
-```ts
-export const description = '{{description}}'
-```
-
-## Handler
-
-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
-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
-}
-```
-
-## Complete Example
-
-```ts
-import { z } from 'zod'
-import type { ContainerContext } from '@soederpop/luca'
-
-export const description = '{{description}}'
-
-// 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
-  const fs = container.feature('fs')
-
-  console.log('{{kebabName}} running...', options.target)
-}
-```
-
-## 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/{{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**: 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`.

package/docs/scaffolds/endpoint.md

@@ -1,171 +0,0 @@
-# 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.
-
-When to build an endpoint:
-- You need a REST API route (GET, POST, PUT, PATCH, DELETE)
-- You want Zod validation, OpenAPI docs, and rate limiting for free
-- You're building an API that `luca serve` manages
-
-## File Location
-
-Endpoints go in `endpoints/` at your project root:
-- `endpoints/health.ts` → `/health`
-- `endpoints/posts.ts` → `/api/posts`
-- `endpoints/posts/[id].ts` → `/api/posts/:id` (requires `path` export)
-
-Run `luca serve` and they're automatically discovered and mounted.
-
-## Imports
-
-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.
-
-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
-
-Every endpoint MUST export a `path` string:
-
-```ts
-export const path = '/api/{{camelName}}'
-export const description = '{{description}}'
-export const tags = ['{{camelName}}']
-```
-
-## Handler Functions
-
-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: any) {
-  const fs = ctx.container.feature('fs')
-  // Your logic here
-  return { message: 'ok' }
-}
-
-export async function post(params: any, ctx: any) {
-  // Create something
-  return { created: true }
-}
-```
-
-The `EndpointContext` gives you:
-- `ctx.container` — the luca container (access any feature, client, etc.)
-- `ctx.request` — Express request object
-- `ctx.response` — Express response object
-- `ctx.query` — parsed query string
-- `ctx.body` — parsed request body
-- `ctx.params` — URL parameters (`:id`, etc.)
-
-Return any object — it's automatically JSON-serialized as the response.
-
-## Validation Schemas
-
-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'),
-})
-
-export const postSchema = z.object({
-  title: z.string().min(1).describe('Item title'),
-  body: z.string().min(1).describe('Item content'),
-})
-```
-
-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
-
-Export rate limit config to protect endpoints:
-
-```ts
-// Global rate limit for all methods
-export const rateLimit = { maxRequests: 100, windowSeconds: 60 }
-
-// Per-method rate limit
-export const postRateLimit = { maxRequests: 10, windowSeconds: 1 }
-```
-
-## Delete Handler
-
-`delete` is a reserved word in JS, so you can't use it as a function name directly. Use a named export alias:
-
-```ts
-// 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 (no external imports needed):
-
-```ts
-export const path = '/api/{{camelName}}'
-export const description = '{{description}}'
-export const tags = ['{{camelName}}']
-
-export async function get(params: any, ctx: any) {
-  return { items: [], total: 0 }
-}
-
-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
-
-For routes with URL parameters, create a nested file:
-
-```ts
-// 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: any) {
-  const { id } = ctx.params
-  return { item: { id } }
-}
-
-export async function put(params: any, ctx: any) {
-  const { id } = ctx.params
-  return { item: { id, ...params }, message: 'Updated' }
-}
-
-const del = async (params: any, ctx: any) => {
-  const { id } = ctx.params
-  return { message: `Deleted ${id}` }
-}
-export { del as delete }
-```
-
-## Conventions
-
-- **File = route**: The file path maps to the URL path. `endpoints/users.ts` serves `/api/users`.
-- **Export `path`**: Every endpoint must export a `path` string. This is the mounted route.
-- **Use Zod schemas**: Name them `getSchema`, `postSchema`, etc. They validate AND document.
-- **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`.