ts-procedures 5.7.2 → 5.9.0

package/README.md

@@ -40,1063 +40,19 @@ const user = await GetUser({}, { userId: '123' })
 const user2 = await procedure({}, { userId: '456' })
 ```
 
-## Core Concepts
+## Features
 
-### Procedures Factory
+- **[Core Procedures](docs/core.md)** — Type-safe procedure definitions with `Procedures()`, `Create`, and `CreateStream`. Includes schema validation (Suretype / TypeBox), error handling, generics, testing patterns, and the full API reference.
 
-The `Procedures()` function creates a factory for defining procedures. It accepts two generic type parameters:
+- **[Streaming](docs/streaming.md)** — Async generator procedures with yield validation, abort signal integration, SSE examples, and stream error handling.
 
-```typescript
-Procedures<TContext, TExtendedConfig>(builder?: {
-    onCreate?: (procedure: TProcedureRegistration<TContext, TExtendedConfig>) => void
-})
-```
-
-| Parameter | Description                                                                |
-|-----------|----------------------------------------------------------------------------|
-| `TContext` | The base context type passed to all handlers as the first parameter        |
-| `TExtendedConfig` | Additional configuration properties for all procedures `config` properties |
-| `builder.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
-
-### Create Function
-
-The `Create` function defines individual procedures:
-
-```typescript
-Create(name, config, handler)
-```
-
-**Returns:**
-- `{ [name]: handler }` - Named export for the handler
-- `procedure` - Generic reference to the handler
-- `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
-
-### Structured Input with schema.input
-
-For HTTP APIs and other multi-channel transports, `schema.input` provides per-channel type safety. Each key is an independently validated input channel:
-
-```typescript
-const { Create } = Procedures<AppContext, APIConfig>()
-
-const { UpdateUser } = Create(
-  'UpdateUser',
-  {
-    path: '/users/:id',
-    method: 'put',
-    schema: {
-      input: {
-        pathParams: Type.Object({ id: Type.String() }),
-        query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
-        body: Type.Object({ name: Type.String(), email: Type.String() }),
-      },
-      returnType: Type.Object({ ok: Type.Boolean() }),
-    },
-  },
-  async (ctx, { pathParams, query, body }) => {
-    // Each channel is independently typed and validated
-    await updateUser(pathParams.id, body)
-    if (query.notify) await sendNotification(pathParams.id)
-    return { ok: true }
-  }
-)
-```
-
-**Rules:**
-- `schema.input` and `schema.params` are **mutually exclusive** — defining both throws `ProcedureRegistrationError`
-- Each channel is validated independently with per-channel error messages
-- Works with both `Create` and `CreateStream`
-
-### CreateStream Function
-
-The `CreateStream` function defines streaming procedures that yield values over time using async generators:
-
-```typescript
-CreateStream(name, config, handler)
-```
-
-**Config Options:**
-- `schema.params` - Input parameter schema (validated at runtime)
-- `schema.yieldType` - Schema for each yielded value (validated if `validateYields: true`)
-- `schema.returnType` - Schema for final return value (documentation only)
-- `validateYields` - Enable runtime validation of yielded values (default: `false`)
-
-**Handler Signature:**
-```typescript
-async function* (ctx, params) => AsyncGenerator<TYield, TReturn | void>
-```
-
-**Context Extensions (all handlers):**
-- `ctx.error(message, meta?)` - Create a ProcedureError
-- `ctx.signal?` - AbortSignal for cancellation support (optional for `Create`, always present for `CreateStream`)
-
-When using the built-in HTTP implementations (Hono, Express), `ctx.signal` is automatically injected from the HTTP request, so handlers can detect client disconnection. For direct usage without a server, `signal` is `undefined` unless you pass one in context.
-
-**Returns:**
-- `{ [name]: handler }` - Named generator export
-- `procedure` - Generic reference to the generator
-- `info` - Procedure meta with `isStream: true`
-
-## Using Generics
-
-### Base Context
-
-Define a shared context type for all procedures in your application:
-
-```typescript
-interface AppContext {
-  authToken: string
-  requestId: string
-  logger: Logger
-}
-
-const { Create } = Procedures<AppContext>()
-
-const { SecureEndpoint } = Create(
-  'SecureEndpoint',
-  {},
-  async (ctx, params) => {
-    // ctx.authToken is typed as string
-    // ctx.requestId is typed as string
-    // ctx.logger is typed as Logger
-    return { token: ctx.authToken }
-  },
-)
-
-// When calling, you must provide the context
-await SecureEndpoint({ authToken: 'abc', requestId: '123', logger: myLogger }, {})
-```
-
-### Extended Configuration
-
-Add custom properties to all procedure configs:
-
-```typescript
-interface ExtendedConfig {
-  permissions: string[]
-  rateLimit?: number
-  cacheTTL?: number
-}
-
-const { Create } = Procedures<AppContext, ExtendedConfig>()
-
-const { AdminOnly } = Create(
-  'AdminOnly',
-  {
-    permissions: ['admin'],  // Required by ExtendedConfig
-    rateLimit: 100,          // Optional
-    description: 'Admin-only endpoint',
-  },
-  async (ctx, params) => {
-    return { admin: true }
-  },
-)
-
-// Access extended config via info
-console.log(AdminOnly.info.permissions) // ['admin']
-```
-
-### Combined Example
-
-```typescript
-interface CustomContext {
-  authToken: string
-  tenantId: string
-}
-
-interface ExtendedConfig {
-  requiresAuth: boolean
-  auditLog?: boolean
-}
-
-const { Create, getProcedures } = Procedures<CustomContext, ExtendedConfig>({
-  onCreate: (procedure) => {
-    // Register with your framework
-    console.log(`Registered: ${procedure.name}`)
-    console.log(`Requires Auth: ${procedure.config.requiresAuth}`)
-  },
-})
-
-const { CreateUser } = Create(
-  'CreateUser',
-  {
-    requiresAuth: true,
-    auditLog: true,
-    description: 'Creates a new user',
-    schema: {
-      params: Type.Object({
-        email: Type.String(),
-        name: Type.String(),
-      }),
-      returnType: Type.Object({ id: Type.String() }),
-    },
-  },
-  async (ctx, params) => {
-    // Both context and params are fully typed
-    return { id: 'user-123' }
-  },
-)
-```
-
-## Schema Validation
-
-### Suretype
-
-```typescript
-import { v } from 'suretype'
-
-Create(
-  'CreatePost',
-  {
-    schema: {
-      params: Type.Object({
-        title: Type.String(),
-        content: Type.String(),
-        tags: Type.array(Type.String()),
-      }),
-      returnType: Type.Object({
-        id: Type.String(),
-        createdAt: Type.String(),
-      }),
-    },
-  },
-  async (ctx, params) => {
-    // params typed as { title: string, content: string, tags?: string[] }
-    return { id: '1', createdAt: new Date().toISOString() }
-  },
-)
-```
-
-### TypeBox
-
-```typescript
-import { Type } from 'typebox'
-
-Create(
-  'CreatePost',
-  {
-    schema: {
-      params: Type.Object({
-        title: Type.String(),
-        content: Type.String(),
-        tags: Type.Optional(Type.Array(Type.String())),
-      }),
-      returnType: Type.Object({
-        id: Type.String(),
-        createdAt: Type.String(),
-      }),
-    },
-  },
-  async (ctx, params) => {
-    // params typed as { title: string, content: string, tags?: string[] }
-    return { id: '1', createdAt: new Date().toISOString() }
-  },
-)
-```
-
-### Validation Behavior
-
-AJV is configured with:
-- `allErrors: true` - Report all validation errors
-- `coerceTypes: true` - Automatically coerce types when possible
-- `removeAdditional: true` - Strip properties not in schema
-
-**Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
-
-## Streaming Procedures
-
-Streaming procedures use async generators to yield values over time, enabling SSE (Server-Sent Events), HTTP streaming, and real-time data feeds.
-
-### Basic Streaming
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { v } from 'suretype'
-
-const { CreateStream } = Procedures<{ userId: string }>()
-
-const { StreamUpdates } = CreateStream(
-  'StreamUpdates',
-  {
-    description: 'Stream real-time updates',
-    schema: {
-      params: v.object({ topic: v.string().required() }),
-      yieldType: v.object({
-        id: v.string().required(),
-        message: v.string().required(),
-        timestamp: v.number().required(),
-      }),
-    },
-  },
-  async function* (ctx, params) {
-    // Types are inferred from schema:
-    // - params.topic: string
-    // - yield value must match { id, message, timestamp }
-    // - ctx.signal: AbortSignal for cancellation
-
-    let counter = 0
-    while (!ctx.signal.aborted) {
-      yield {
-        id: `${counter++}`,
-        message: `Update for ${params.topic}`,
-        timestamp: Date.now(),
-      }
-      await new Promise(r => setTimeout(r, 1000))
-    }
-  },
-)
-
-// Consume the stream
-for await (const update of StreamUpdates({ userId: 'user-123' }, { topic: 'news' })) {
-  console.log(update.message)
-}
-```
-
-### Yield Validation
-
-By default, yielded values are not validated for performance. Enable validation with `validateYields: true`:
-
-```typescript
-const { ValidatedStream } = CreateStream(
-  'ValidatedStream',
-  {
-    schema: {
-      yieldType: v.object({ count: v.number().required() }),
-    },
-    validateYields: true, // Enable runtime validation of each yield
-  },
-  async function* () {
-    yield { count: 1 }  // Valid
-    yield { count: 2 }  // Valid
-    // yield { count: 'invalid' } // Would throw ProcedureYieldValidationError
-  },
-)
-```
-
-### Abort Signal Integration
-
-#### Streaming Procedures
-
-The `ctx.signal` allows stream handlers to detect when consumers stop iterating. After completion, `signal.reason` indicates why the stream ended:
-
-```typescript
-const { CancellableStream } = CreateStream(
-  'CancellableStream',
-  {},
-  async function* (ctx) {
-    try {
-      while (!ctx.signal.aborted) {
-        yield await fetchNextItem()
-      }
-    } finally {
-      // Distinguish normal completion from client disconnect
-      if (ctx.signal.reason === 'stream-completed') {
-        // Stream finished normally
-      } else {
-        // Client disconnected or external abort
-      }
-      await cleanup()
-    }
-  },
-)
-
-// Consumer can break early - signal.aborted becomes true
-for await (const item of CancellableStream({}, {})) {
-  if (shouldStop) break // Triggers abort
-}
-```
-
-#### Regular Procedures
-
-For regular procedures, `ctx.signal` is available when the server implementation provides it. The built-in HTTP integrations (Hono RPC, Express RPC) inject the request's abort signal automatically:
-
-```typescript
-const { Create } = Procedures<{ signal: AbortSignal }>()
-
-const { LongQuery } = Create(
-  'LongQuery',
-  {},
-  async (ctx, params) => {
-    // Pass signal to downstream operations
-    const result = await fetch('https://api.example.com/data', {
-      signal: ctx.signal,
-    })
-    return result.json()
-  },
-)
-```
-
-When using the Hono or Express implementations, `ctx.signal` aborts when the client disconnects, automatically cancelling in-flight `fetch()` calls, database queries, or any other signal-aware operation.
-
-### SSE Integration Example
-
-```typescript
-import express from 'express'
-import { Procedures } from 'ts-procedures'
-
-const app = express()
-
-const { CreateStream, getProcedures } = Procedures<{ req: express.Request }>({
-  onCreate: (proc) => {
-    if (proc.isStream) {
-      // Register streaming procedures as SSE endpoints
-      app.get(`/stream/${proc.name}`, async (req, res) => {
-        res.writeHead(200, {
-          'Content-Type': 'text/event-stream',
-          'Cache-Control': 'no-cache',
-          'Connection': 'keep-alive',
-        })
-
-        const generator = proc.handler({ req }, req.query)
-
-        req.on('close', async () => {
-          // Client disconnected - stop the generator
-          await generator.return(undefined)
-        })
-
-        try {
-          for await (const data of generator) {
-            res.write(`data: ${JSON.stringify(data)}\n\n`)
-          }
-        } finally {
-          res.end()
-        }
-      })
-    }
-  },
-})
-
-// Define a streaming procedure
-CreateStream(
-  'LiveFeed',
-  {
-    schema: {
-      params: v.object({ channel: v.string() }),
-      yieldType: v.object({ event: v.string(), data: v.any() }),
-    },
-  },
-  async function* (ctx, params) {
-    while (!ctx.signal.aborted) {
-      const event = await pollForEvent(params.channel)
-      yield event
-    }
-  },
-)
-
-app.listen(3000)
-// SSE endpoint: GET /stream/LiveFeed?channel=updates
-```
-
-### Stream Errors
-
-Streaming procedures support the same error handling as regular procedures:
-
-```typescript
-const { StreamWithErrors } = CreateStream(
-  'StreamWithErrors',
-  {},
-  async function* (ctx) {
-    yield { status: 'starting' }
-
-    const data = await fetchData()
-    if (!data) {
-      throw ctx.error('No data available', { code: 'NO_DATA' })
-    }
-
-    yield { status: 'complete', data }
-  },
-)
-
-try {
-  for await (const item of StreamWithErrors({}, {})) {
-    console.log(item)
-  }
-} catch (e) {
-  if (e instanceof ProcedureError) {
-    console.log(e.message) // 'No data available'
-    console.log(e.meta)    // { code: 'NO_DATA' }
-  }
-}
-```
-
-## Error Handling
-
-### Using ctx.error()
-
-The `error()` function is injected into both hooks and handlers:
-
-```typescript
-Create(
-  'GetResource',
-  {},
-  async (ctx, params) => {
-    const resource = await db.find(params.id)
-    if (!resource) {
-      throw ctx.error(404, 'Resource not found', { id: params.id })
-    }
-    return resource
-  },
-)
-```
-
-### Error Handling
-
-| Error Class | Trigger |
-|-------------|---------|
-| ProcedureError | `ctx.error()` in handlers |
-| ProcedureValidationError | Schema validation failure (params) |
-| ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
-| ProcedureRegistrationError | Invalid schema at registration |
-
-### Error Properties
-
-```typescript
-try {
-  await MyProcedure(ctx, params)
-} catch (e) {
-  if (e instanceof ProcedureError) {
-    console.log(e.procedureName) // 'MyProcedure'
-    console.log(e.message)       // 'Resource not found'
-    console.log(e.meta)          // { id: '123' }
-  }
-}
-```
-
-## Framework Integration
-
-### onCreate Callback
-
-Register procedures with your framework (Express, Fastify, etc.):
+- **[HTTP Integrations](docs/http-integrations.md)** — Express and Hono builders with lifecycle hooks, route documentation, `DocRegistry` for composing docs, and per-channel input validation.
 
-```typescript
-import express from 'express'
-
-const app = express()
-const routes: Map<string, Function> = new Map()
-
-const { Create } = Procedures<{ req: Request; res: Response }>({
-  onCreate: ({ name, handler, config }) => {
-    // Register as Express route
-    app.post(`/rpc/${name}`, async (req, res) => {
-      try {
-        const result = await handler({ req, res }, req.body)
-        res.json(result)
-      } catch (e) {
-        if (e instanceof ProcedureError) {
-          res.status(500).json({ error: e.message })
-        } else {
-          res.status(500).json({ error: 'Internal error' })
-        }
-      }
-    })
-  },
-})
-
-// Procedures are automatically registered as /rpc/GetUser, /rpc/CreateUser, etc.
-```
-
-### Express RPC Integration
-
-`ts-procedures` includes an RPC-style HTTP integration for Express that creates POST routes at `/rpc/{name}/{version}` paths with automatic JSON schema documentation.
-
-```typescript
-import { ExpressRPCAppBuilder, RPCConfig } from 'ts-procedures/express-rpc'
-
-// Create procedure factory with RPC config
-const RPC = Procedures<AppContext, RPCConfig>()
-
-// Define procedures with name and version
-RPC.Create(
-  'GetUser',
-  {
-    name: ['users', 'get'],
-    version: 1,
-    schema: {
-      params: Type.Object({ id: Type.String() }),
-      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-    },
-  },
-  async (ctx, params) => {
-    return { id: params.id, name: 'John Doe' }
-  }
-)
-
-// Build Express app with registered procedures
-const app = new ExpressRPCAppBuilder()
-  .register(RPC, (req) => ({ userId: req.headers['x-user-id'] as string }))
-  .build()
-
-app.listen(3000)
-// Route created: POST /rpc/users/get/1
-```
-
-See [Express RPC Integration Guide](src/implementations/http/express-rpc/README.md) for complete setup instructions including lifecycle hooks, error handling, and route documentation.
-
-### Hono API Integration
-
-`ts-procedures` includes a REST-style HTTP integration for Hono that routes by HTTP method with per-channel input validation via `schema.input`.
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
-import type { APIConfig } from 'ts-procedures/http'
-import { Type } from 'typebox'
-
-const API = Procedures<{ userId: string }, APIConfig>()
-
-API.Create('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  schema: {
-    input: {
-      pathParams: Type.Object({ id: Type.String() }),
-    },
-    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-  },
-}, async (ctx, { pathParams }) => {
-  return await fetchUser(pathParams.id)
-})
-
-API.Create('CreateUser', {
-  path: '/users',
-  method: 'post',
-  schema: {
-    input: {
-      body: Type.Object({ name: Type.String(), email: Type.String() }),
-    },
-  },
-}, async (ctx, { body }) => {
-  return await createUser(body)
-})
-
-const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
-  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
-  .build()
-
-// Routes:
-// GET  /api/users/:id  → 200
-// POST /api/users      → 201
-```
-
-See [Hono API Integration Guide](src/implementations/http/hono-api/) for complete setup.
-
-### Introspection with getProcedures()
-
-Access all registered procedures for documentation or routing:
-
-```typescript
-const { Create, getProcedures } = Procedures()
-
-Create('GetUser', { schema: { params: Type.Object({ id: Type.String() }) } }, async () => {})
-Create('ListUsers', { schema: { params: Type.Object({}) } }, async () => {})
-
-// Get all registered procedures
-const procedures = getProcedures()
-
-// Generate OpenAPI spec
-for (const config of procedures) {
-  console.log(`${config.name}:`, config.schema)
-}
-```
-
-### DocRegistry — Composing Docs from Multiple Builders
-
-Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
-
-```typescript
-import { DocRegistry } from 'ts-procedures/http-docs'
-
-const docs = new DocRegistry({
-  basePath: '/api',
-  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-  errors: DocRegistry.defaultErrors(),
-})
-  .from(rpcBuilder)
-  .from(apiBuilder)
-  .from(streamBuilder)
-
-app.get('/docs', (c) => c.json(docs.toJSON()))
-```
-
-`from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
-
-## Testing
-
-Procedures return handlers that can be called directly in tests:
-
-```typescript
-import { describe, test, expect } from 'vitest'
-import { Procedures } from 'ts-procedures'
-import { Type } from 'typebox'
-
-interface MyCustomContext {
-  userId?: string
-  userName?: string
-}
-
-const { Create } = Procedures<MyCustomContext>()
-
-const { GetUser, info } = Create(
-  'GetUser',
-  {
-    schema: {
-      params: Type.Object({ hideName: Type.Optional(Type.Boolean()) }),
-      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-    },
-  },
-  async (ctx, params) => {
-    if (!params.userName || !ctx.userId) {
-      throw ctx.error('User is not authenticated')
-    }
-    
-    return { 
-      id: params.userId, 
-      name: params?.hideName ? '*******' : params.userName 
-    }
-  },
-)
-
-describe('GetUser', () => {
-  test('returns user', async () => {
-    const result = await GetUser({userId:'123',userName:'Ray'}, { hideName: false })
-    expect(result).toEqual({ id: '123', name: 'Ray' })
-  })
-  
-  test('hides user name', async () => {
-    const result = await GetUser({userId:'123',userName:'Ray'}, { hideName: true })
-    expect(result).toEqual({ id: '123', name: '*******' })
-  })
-
-  test('validates params', async () => {
-    await expect(GetUser({}, {})).rejects.toThrow(ProcedureValidationError)
-  })
-
-  test('has correct schema', () => {
-    expect(info.schema.params).toEqual({
-      type: 'object',
-      properties: { id: { type: 'string' } },
-      required: ['id'],
-    })
-  })
-})
-```
-
-## API Reference
-
-### Procedures(builder?)
-
-Creates a procedure factory.
-
-**Parameters:**
-- `builder.onCreate` - Callback invoked when each procedure is registered
-
-**Returns:**
-- `Create` - Function to define procedures
-- `getProcedures()` - Returns `Array` of all registered procedures
-
-### Create(name, config, handler)
-
-Defines a procedure.
-
-**Parameters:**
-- `name` - Unique procedure name (becomes named export)
-- `config.description` - Optional description
-- `config.schema.params` - Suretype or TypeBox schema for params (validated at runtime)
-- `config.schema.returnType` - Suretype or TypeBox schema for return returnType (documentation only)
-- Additional properties from `TExtendedConfig`
-- `handler` - Async function `(ctx, params) => Promise<returnType>`
-
-**Returns:**
-- `{ [name]: handler }` - Named handler export
-- `procedure` - Generic handler reference
-- `info` - Procedure metareturnType
-
-### Type Exports
-
-```typescript
-import {
-  // Core
-  Procedures,
-
-  // Errors
-  ProcedureError,
-  ProcedureValidationError,
-  ProcedureRegistrationError,
-  ProcedureYieldValidationError,  // For streaming yield validation
-
-  // Types
-  TLocalContext,
-  TStreamContext,               // Streaming context (AbortSignal always present)
-  TProcedureRegistration,
-  TStreamProcedureRegistration, // Streaming procedure registration
-  TNoContextProvided,
-
-  // Schema utilities
-  extractJsonSchema,
-  schemaParser,
-  isTypeboxSchema,
-  isSuretypeSchema,
-
-  // Schema types
-  TJSONSchema,
-  TSchemaLib,
-  TSchemaLibGenerator,          // AsyncGenerator type utility
-  TSchemaParsed,
-  TSchemaValidationError,
-  Prettify,
-} from 'ts-procedures'
-
-// HTTP types
-import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+- **[Client Code Generation](docs/client-and-codegen.md)** — Generate type-safe client SDKs from your server's `DocRegistry`. CLI and programmatic API, adapters, hooks, streaming support, and self-contained mode.
 
-// Hono API (REST-style)
-import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
-import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod, QueryParser } from 'ts-procedures/hono-api'
-
-// Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
-
-// Code Generation
-import { generateClient } from 'ts-procedures/codegen'
-```
-
-## Client Code Generation
-
-ts-procedures can generate type-safe client SDKs directly from your server's `DocRegistry` output. Generated files include TypeScript types and callable functions for every registered procedure, organized by scope — no manual type duplication required.
-
-### Quick Start
-
-**Step 1 — Serve your docs endpoint:**
-
-```typescript
-app.get('/docs', (c) => c.json(docs.toJSON()))
-```
-
-**Step 2 — Generate the client:**
-
-```bash
-npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
-```
-
-**Step 3 — Use the client:**
-
-```typescript
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import { createScopeBindings } from './generated/api'
-
-const client = createClient({
-  adapter: createFetchAdapter(),
-  basePath: 'http://localhost:3000',
-  scopes: createScopeBindings,
-  hooks: {
-    onBeforeRequest(ctx) {
-      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
-      return ctx
-    },
-  },
-})
-
-// Fully typed — params and response inferred from server schemas
-const user = await client.users.GetUser({ pathParams: { id: '123' } })
-```
-
-### Generated File Structure
-
-Running the codegen command produces one file per scope, plus shared error types and a barrel export:
-
-```
-generated/
-  users.ts           # Types + callables for "users" scope
-  billing.ts         # Types + callables for "billing" scope
-  notifications.ts   # Types + callables for stream procedures
-  _errors.ts         # Typed error classes + ProcedureErrorUnion
-  index.ts           # Barrel exports + createScopeBindings
-```
-
-### CLI Reference
-
-| Flag | Description | Required |
-|------|-------------|----------|
-| `--url <url>` | Fetch DocEnvelope from URL | One of `--url` or `--file` |
-| `--file <path>` | Read DocEnvelope from JSON file | One of `--url` or `--file` |
-| `--out <dir>` | Output directory | Yes |
-| `--watch` | Poll for changes and regenerate | No |
-| `--interval <ms>` | Watch poll interval (default: 3000) | No |
-| `--dry-run` | Preview without writing files | No |
-| `--client-import-path <path>` | Override import path (default: `ts-procedures/client`) | No |
-| `--namespace-types` | Wrap types in nested TypeScript namespaces per scope/route | No |
-| `--config <path>` | Path to config file (default: `ts-procedures-codegen.config.json`) | No |
-| `--enum-style <union\|enum>` | TypeScript enum style (requires `--namespace-types`) | No |
-| `--depluralize` | Singularize array item type names (requires `--namespace-types`) | No |
-| `--array-item-naming <value>` | Postfix for array item type names (requires `--namespace-types`) | No |
-| `--uncountable-words <list>` | Comma-separated words to skip singularization (requires `--namespace-types`) | No |
-| `--jsdoc` | Emit JSDoc comments from JSON Schema descriptions (requires `--namespace-types`) | No |
-| `--self-contained` | Emit `_types.ts` and `_client.ts` — no runtime dependency on `ts-procedures` | No |
-
-> **Note:** ajsc formatting options (`--enum-style enum`, `--depluralize`, `--array-item-naming`, `--uncountable-words`, `--jsdoc`) only take effect with `--namespace-types`. In flat mode, all types are inlined and these options have no effect.
->
-> You can also use a `ts-procedures-codegen.config.json` file in your project root instead of CLI flags. CLI flags override config values.
-
-### Adapter Interface
-
-The client requires an adapter that handles the actual HTTP transport. A built-in fetch adapter is included, and you can implement your own for any HTTP library:
-
-```typescript
-import { createFetchAdapter } from 'ts-procedures/client'
-
-// Use the built-in fetch adapter
-const adapter = createFetchAdapter({ headers: { 'X-API-Key': 'my-key' } })
-
-// Or implement your own (e.g., for axios)
-const axiosAdapter: ClientAdapter = {
-  async request({ url, method, headers, body }) {
-    const res = await axios({ url, method, headers, data: body })
-    return { status: res.status, headers: res.headers, body: res.data }
-  },
-  async stream({ url, method, headers, body }) {
-    // Return AsyncIterable of SSE events
-  },
-}
-```
-
-### Hooks
-
-Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks override or extend them for a single invocation.
-
-```typescript
-// Global hooks (apply to all calls)
-const client = createClient({
-  adapter,
-  basePath: 'http://localhost:3000',
-  scopes: createScopeBindings,
-  hooks: {
-    onBeforeRequest(ctx) { /* add auth headers */ return ctx },
-    onAfterResponse(ctx) { /* handle errors, logging */ },
-    onError(ctx) { /* error reporting */ },
-  },
-})
-
-// Per-procedure hook override
-await client.users.GetUser({ pathParams: { id: '123' } }, {
-  onAfterResponse(ctx) {
-    const rateLimit = ctx.response.headers['x-rate-limit-remaining']
-  },
-})
-```
-
-### Streaming
-
-Stream procedures return a `TypedStream` — an async iterable for yield values, with a `.result` promise for the final return value:
-
-```typescript
-const stream = client.events.WatchNotifications({ filter: 'all' })
-
-for await (const event of stream) {
-  console.log(event) // typed as WatchNotificationsYield
-}
-
-const result = await stream.result // typed as WatchNotificationsReturn
-```
-
-### Programmatic API
-
-For build pipelines or custom tooling, `generateClient` can be called directly without the CLI:
-
-```typescript
-import { generateClient } from 'ts-procedures/codegen'
-
-await generateClient({
-  url: 'http://localhost:3000/docs',
-  outDir: './src/generated/api',
-  clientImportPath: '@my-app/procedures-client', // optional
-  namespaceTypes: true, // optional — wrap types in nested namespaces
-  selfContained: true, // optional — emit _types.ts + _client.ts (no ts-procedures runtime dep)
-  dryRun: false, // optional
-  ajsc: { // optional — ajsc TypescriptConverter options
-    enumStyle: 'union',
-    depluralize: true,
-    arrayItemNaming: 'Item',
-    uncountableWords: ['criteria'],
-  },
-})
-```
-
-### Self-Contained Mode
-
-With `--self-contained`, the generated output includes two additional files in the output directory:
-
-- **`_types.ts`** — All client type definitions (`ClientInstance`, `TypedStream`, `ProcedureCallOptions`, hooks, adapters, descriptors)
-- **`_client.ts`** — Full client runtime: `createClient`, `createFetchAdapter`, hook pipeline, and error classes (`ClientRequestError`, `ClientPathParamError`, `ClientStreamError`)
-
-All generated scope files and `index.ts` import from `./_types` instead of `ts-procedures/client`, so app consumers can import everything from the generated directory without needing `ts-procedures` as a runtime dependency. `ts-procedures` becomes a devDependency only.
-
-```typescript
-// Without --self-contained (default)
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-
-// With --self-contained
-import { createClient, createFetchAdapter } from './generated/_client'
-```
-
-## AI Agent Setup
-
-ts-procedures ships with built-in AI assistant configuration for **Claude Code**, **Cursor**, and **GitHub Copilot**. This gives AI tools framework-aware context when writing ts-procedures code in your project.
-
-### Quick Setup
-
-```bash
-npx ts-procedures-setup
-```
-
-This installs rules for all supported AI tools. You can also target specific tools:
-
-```bash
-npx ts-procedures-setup claude       # Claude Code only
-npx ts-procedures-setup cursor       # Cursor only
-npx ts-procedures-setup copilot      # GitHub Copilot only
-```
-
-### What Gets Installed
-
-| Tool | Files | Auto-updates? |
-|------|-------|---------------|
-| **Claude Code** | `.claude/rules/ts-procedures.md`, `.claude/commands/ts-procedures-scaffold.md`, `.claude/commands/ts-procedures-review.md`, `.claude/agents/ts-procedures-architect.md` | Yes |
-| **Cursor** | `.cursorrules` (marker-based section) | Yes |
-| **GitHub Copilot** | `.github/copilot-instructions.md` (marker-based section) | Yes |
-
-### Auto-Updates
-
-After initial setup, rules are automatically refreshed on every `npm install` or `npm update`. When ts-procedures publishes a new version, your AI tools get the latest framework guidance without any manual steps.
-
-### Claude Code Features
-
-Once installed, Claude Code gets:
-
-- **Framework reference** — auto-loaded rules with core API, schema system, error handling, and decision framework
-- **Scaffold command** — `/project:ts-procedures-scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
-- **Review command** — `/project:ts-procedures-review <path>` checks code against a 60+ item checklist
-- **Architecture agent** — `ts-procedures-architect` helps plan procedure structure, schema design, and HTTP implementation choices
-
-### CLI Options
-
-```bash
-npx ts-procedures-setup --force      # Overwrite without prompting
-npx ts-procedures-setup --dry-run    # Preview what would be created/updated
-npx ts-procedures-setup --check      # Exit with code 1 if files are outdated (for CI)
-```
-
-### Gitignore
-
-The `.claude/` files are auto-generated and regenerated on `npm install`. You can add them to `.gitignore`:
-
-```gitignore
-# Auto-generated AI agent rules (regenerated on npm install)
-.claude/rules/ts-procedures.md
-.claude/commands/ts-procedures-*.md
-.claude/agents/ts-procedures-*.md
-```
+- **[AI Agent Setup](docs/ai-agent-setup.md)** — Built-in configuration for Claude Code, Cursor, and GitHub Copilot. Auto-updates on `npm install`.
 
-Cursor and Copilot files use marker-based sections that coexist with your own rules, so they should typically be committed.
+Full documentation is available on [GitHub](https://github.com/thermsio/ts-procedures).
 
 ## License