ts-procedures 7.3.0 → 8.0.0

package/README.md

@@ -48,13 +48,75 @@ const user = await GetUser({}, { userId: '123' })
 const user2 = await procedure({}, { userId: '456' })
 ```
 
+## v8 Migration — Unified `HonoAppBuilder`
+
+The three Hono builders (`HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder`) are replaced in v8 by a single `HonoAppBuilder` that accepts any `Procedures<>()` factory and dispatches all four procedure kinds (`rpc`, `rpc-stream`, `http`, `http-stream`) by `procedure.kind` from a single `register()` call.
+
+```typescript
+// Before (v7)
+const rpc = new HonoRPCAppBuilder({ app, errors }).register(F1, ctx1)
+const api = new HonoAPIAppBuilder({ app, errors, queryParser }).register(F2, ctx2)
+const stream = new HonoStreamAppBuilder({ app, errors, onMidStreamError }).register(F3, ctx3)
+
+// After (v8)
+const builder = new HonoAppBuilder({
+  app,
+  errors,
+  api: { queryParser },
+  stream: { onMidStreamError },
+}).register(F1, ctx1).register(F2, ctx2).register(F3, ctx3)
+```
+
+Kind-specific config knobs are stratified into `rpc.*`, `api.*`, and `stream.*` blocks. Single-app users can call `builder.toDocEnvelope()` directly (no `DocRegistry` needed). `DocRegistry` remains for multi-app aggregation.
+
+Subpath imports change from `ts-procedures/hono-rpc`, `ts-procedures/hono-api`, `ts-procedures/hono-stream` to `ts-procedures/hono`.
+
+## HTTP Routes (v8) — `CreateHttp`
+
+v8 introduces `CreateHttp` and `CreateHttpStream` as first-class HTTP creators. HTTP fields (`path`, `method`, `scope`, `errors`) live on the creator config directly; no factory type parameter is required.
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoAppBuilder } from 'ts-procedures/hono'
+import { Type } from 'typebox'
+
+type AppContext = { userId: string }
+const API = Procedures<AppContext>()
+
+// Input channels: pathParams, query, body, headers (schema.req)
+// Response: schema.res.body (docs) + schema.res.headers (makes handler return { body, headers })
+API.CreateHttp('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    req: { pathParams: Type.Object({ id: Type.String() }) },
+    res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
+  },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
+
+API.CreateHttp('CreateUser', {
+  path: '/users',
+  method: 'post',
+  schema: {
+    req: { body: Type.Object({ name: Type.String(), email: Type.String() }) },
+  },
+}, async (ctx, { body }) => createUser(body))
+
+const app = new HonoAppBuilder({ pathPrefix: '/api' })
+  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
+  .build()
+// GET /api/users/:id → 200, POST /api/users → 201
+```
+
+**Migrating from v7?** Replace `Procedures<Ctx, APIConfig>()` → `Procedures<Ctx>()`, `.Create(` → `.CreateHttp(`, and `schema.input` → `schema.req`. Then re-run `npx ts-procedures-codegen`. See `CHANGELOG.md` for the full breaking-changes list.
+
 ## Features
 
-- **[Core Procedures](docs/core.md)** — Type-safe procedure definitions with `Procedures()`, `Create`, and `CreateStream`. Includes schema validation with TypeBox, error handling, generics, testing patterns, and the full API reference.
+- **[Core Procedures](docs/core.md)** — Type-safe procedure definitions with `Procedures()`, `Create`, `CreateHttp`, and `CreateStream`. Includes schema validation with TypeBox, error handling, generics, testing patterns, and the full API reference.
 
-- **[Streaming](docs/streaming.md)** — Async generator procedures with yield validation, abort signal integration, SSE examples, and stream error handling.
+- **[Streaming](docs/streaming.md)** — Async generator procedures with yield validation, abort signal integration, SSE examples, and stream error handling. `CreateHttpStream` supports response headers via `TypedStream.headers`.
 
-- **[HTTP Integrations](docs/http-integrations.md)** — Express and Hono builders with lifecycle hooks, route documentation, `DocRegistry` for composing docs, and per-channel input validation.
+- **[HTTP Integrations](docs/http-integrations.md)** — `HonoAppBuilder` with lifecycle hooks, route documentation, `DocRegistry` for composing docs, and per-channel input validation via `schema.req`.
 
 - **[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.
 

package/agent_config/claude-code/agents/ts-procedures-architect.md

@@ -22,7 +22,7 @@ When asked to plan an API or procedure set:
 3. **List procedures** — name, type (Create vs CreateStream), description
 4. **Design schemas** — params (validated), returnType/yieldType (documented)
 5. **Design context** — what each handler needs from the request
-6. **Choose HTTP implementation** — Express, Hono RPC, Hono Stream, Hono API, or combination
+6. **Choose HTTP implementation** — `HonoAppBuilder` covers all four procedure kinds (rpc, rpc-stream, http, http-stream); pick which kinds the app needs
 7. **Plan error handling** — which layer for each error type
 8. **Map route structure** — scope + version for RPC routes, path + method for API routes
 
@@ -109,19 +109,17 @@ type AuthContext = { userId: string; requestId: string; db: Database }
 ```
 
 ### HTTP Setup
-- ExpressRPCAppBuilder or HonoRPCAppBuilder for standard RPC
-- HonoStreamAppBuilder for streaming (SSE mode)
-- HonoAPIAppBuilder for REST-style endpoints
-- DocRegistry to compose docs from all builders
+- HonoAppBuilder for RPC, streams (SSE/text), and REST endpoints
+- DocRegistry to compose docs across multiple builders (or `builder.toDocEnvelope()` for single-app)
 - Path prefix: /api
 
 ### Route Map
 - POST /api/health/health-check/1
 - POST /api/users/get-user/1
 - GET|POST /api/activity/stream-activity/1
-- GET /api/users/:id (HonoAPIAppBuilder)
-- POST /api/users (HonoAPIAppBuilder, 201)
-- DELETE /api/users/:id (HonoAPIAppBuilder, 204)
+- GET /api/users/:id (HonoAppBuilder)
+- POST /api/users (HonoAppBuilder, 201)
+- DELETE /api/users/:id (HonoAppBuilder, 204)
 
 ### Error Handling (pick a mode, optionally combine)
 - **Declarative mode (recommended for structured apps)**: `defineErrorTaxonomy({ AuthError: {class, 401}, NotFoundError: {class, 404}, ... })` wired via `errors` config. Drives typed client dispatch + DocEnvelope.

package/agent_config/claude-code/skills/ts-procedures/SKILL.md

@@ -66,7 +66,7 @@ Uses **TypeBox** for schema definitions (`import { Type } from 'typebox'`):
 | `schema.params` | **Validated at runtime** via AJV |
 | `schema.returnType` | **Documentation only**, never validated |
 | `schema.yieldType` | Validated only if `validateYields: true` in CreateStream config |
-| `schema.input` | Structured multi-channel input — alternative to `schema.params`, mutually exclusive |
+| `schema.req` | Structured multi-channel HTTP input (`pathParams`, `query`, `body`, `headers`) — available on `CreateHttp` / `CreateHttpStream` only |
 
 AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
 
@@ -94,7 +94,7 @@ const appErrors = defineErrorTaxonomy({
   UseCaseError: { class: UseCaseError, statusCode: 422, toResponse: (e) => ({ message: e.externalMsg }) },
 })
 
-new HonoAPIAppBuilder({ errors: appErrors, unknownError: { toResponse: () => ({ error: '...' }) } })
+new HonoAppBuilder({ errors: appErrors, unknownError: { toResponse: () => ({ error: '...' }) } })
 ```
 
 Per-route narrowing: `APIConfig<keyof typeof appErrors & string>` / `RPCConfig<keyof typeof appErrors & string>` with a `errors: [...]` array on the config. Generated `_errors.ts` emits runtime classes — clients catch with `instanceof ${Service}Errors.${Name}` when using `create${Service}Client`.
@@ -103,13 +103,10 @@ Full contract: `docs/http-integrations.md § Error Handling` (canonical) and `ap
 
 ## HTTP Implementations
 
-| Builder | Import | Transport |
-|---------|--------|-----------|
-| `ExpressRPCAppBuilder` | `ts-procedures/express-rpc` | POST JSON |
-| `HonoRPCAppBuilder` | `ts-procedures/hono-rpc` | POST JSON |
-| `HonoStreamAppBuilder` | `ts-procedures/hono-stream` | SSE or newline-delimited JSON |
-| `HonoAPIAppBuilder` | `ts-procedures/hono-api` | REST-style with per-channel input |
-| `DocRegistry` | `ts-procedures/http-docs` | Compose route docs from multiple builders |
+| Builder | Import | Handles |
+|---------|--------|---------|
+| `HonoAppBuilder` | `ts-procedures/hono` | RPC, REST-style HTTP, and streaming (SSE / newline-JSON) — one builder dispatches all four procedure kinds |
+| `DocRegistry` | `ts-procedures/http-docs` | Compose route docs from multiple builders (single-app users can also call `builder.toDocEnvelope()`) |
 
 ### Route Path Format (RPC)
 
@@ -122,24 +119,28 @@ Example: `Create('GetUser', { scope: 'users', version: 1 }, ...)` --> `POST /use
 ### Builder Pattern
 
 ```typescript
-const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
-  .register(factory, (req) => ({ /* context */ }))
+const app = new HonoAppBuilder({ pathPrefix: '/api' })
+  .register(factory, (c) => ({ /* context */ }))
   .build()
 ```
 
 ### Lifecycle Hooks (HTTP builders)
 
-| Hook | When |
-|------|------|
-| `onRequestStart` | Before context resolution |
-| `onRequestEnd` | After response sent |
-| `onSuccess` | After successful handler execution |
-| `onError` | Imperative error callback — first-class peer of the declarative `errors` taxonomy |
-| `onStreamStart` | Before first yield (HonoStreamAppBuilder) |
-| `onStreamEnd` | After stream closes (HonoStreamAppBuilder) |
-| `onError` (HonoStream) | Imperative pre-stream error callback — peer of `errors` taxonomy |
-| `onRequestError` | Cross-cutting observer — fires for every caught error before dispatch |
-| `onMidStreamError` | Error during streaming (return data to yield as final event) |
+For `HonoAppBuilder` (v8), hooks are stratified: cross-cutting hooks live at the top level, kind-specific hooks live inside `rpc:` / `api:` / `stream:` blocks.
+
+| Hook | Block | When |
+|------|-------|------|
+| `onRequestStart` | top level | Before context resolution (every kind) |
+| `onRequestEnd` | top level | After response sent (every kind) |
+| `onError` | top level | Imperative pre-stream / unary error callback — first-class peer of the declarative `errors` taxonomy |
+| `onRequestError` | top level | Cross-cutting observer — fires for every caught error before dispatch |
+| `rpc.onSuccess` | `rpc` block | After successful `Create` handler execution |
+| `api.onSuccess` | `api` block | After successful `CreateHttp` handler execution |
+| `api.queryParser` | `api` block | Custom query string parser for `CreateHttp` routes |
+| `stream.defaultStreamMode` | `stream` block | Default mode for streaming routes (`'sse'` or `'text'`) |
+| `stream.onStreamStart` | `stream` block | Before first yield |
+| `stream.onStreamEnd` | `stream` block | After stream closes |
+| `stream.onMidStreamError` | `stream` block | Error during streaming (return data to yield as final event — the only mid-stream path) |
 
 ## Decision Framework
 
@@ -148,17 +149,13 @@ const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
 - Request --> multiple values over time --> **CreateStream**
 
 **Which schema approach?**
-- RPC-style (single `params` object, POST-only) --> `schema.params`
-- REST-style (multiple HTTP input sources) --> `schema.input`
-- `schema.params` and `schema.input` are **mutually exclusive**
+- RPC-style (single `params` object, POST-only) --> `Create` / `CreateStream` with `schema.params`
+- REST-style (multiple HTTP input sources: pathParams, query, body, headers) --> `CreateHttp` / `CreateHttpStream` with `schema.req`
 
 **Which HTTP implementation?**
-- Express app --> **ExpressRPCAppBuilder**
-- Hono app (standard RPC) --> **HonoRPCAppBuilder**
-- Hono app (streaming) --> **HonoStreamAppBuilder**
-- Hono app (REST-style) --> **HonoAPIAppBuilder**
-- SSE with browser EventSource --> `streamMode: 'sse'`
-- Simple text streaming --> `streamMode: 'text'`
+- Hono app (any combination of RPC / REST / streaming) --> **HonoAppBuilder** (one builder dispatches every kind)
+- SSE with browser EventSource --> `stream.defaultStreamMode: 'sse'` on the builder, or `streamMode: 'sse'` per `register()` call
+- Simple text streaming --> `stream.defaultStreamMode: 'text'`
 
 **How to group procedures?**
 - By domain: `UserProcedures`, `OrderProcedures`
@@ -171,9 +168,9 @@ The npm package ships user-facing documentation with narrative explanations and
 
 | File | Covers |
 |------|--------|
-| `docs/core.md` | Procedures factory, Create, CreateStream, schema.input, error handling |
+| `docs/core.md` | Procedures factory, Create, CreateStream, schema.req, error handling |
 | `docs/streaming.md` | Streaming procedures, AbortSignal, SSE patterns |
-| `docs/http-integrations.md` | Express RPC, Hono RPC/Stream/API builders, **error taxonomy (canonical)**, DocRegistry (unified constructor, `.documentError()`) |
+| `docs/http-integrations.md` | Hono unified builder (`HonoAppBuilder` — RPC + HTTP + streaming with stratified config), **error taxonomy (canonical)**, DocRegistry (unified constructor, `.documentError()`) |
 | `docs/client-and-codegen.md` | Client code generation, `createApiClient`/`createClient`, typed error dispatch, per-route `Errors` unions, per-call options, client-level defaults, typed RequestMeta augmentation, CLI options |
 | `docs/client-error-handling.md` | **Canonical guide** for 7.0+ client error surface: normalized error classes, `.safe()` Result API, `ClientErrorMap` augmentation, custom `ErrorClassifier`, migration from `ClientRequestError`. |
 | `CHANGELOG.md` | Release notes — see `[7.0.0]` for the safe-result API, new error classes, and `ClientRequestError` → `ClientHttpError` rename. See `[6.0.0]` for the peer error-handling model (taxonomy + `onError` + `onRequestError`). |

package/agent_config/claude-code/skills/ts-procedures/anti-patterns.md

@@ -342,29 +342,37 @@ Create('GetUser', {}, async (ctx, params) => {
 
 ---
 
-## 12. Registering Standard Procedures with HonoStreamAppBuilder
+## 12. Splitting Procedures Across Multiple HonoAppBuilder Instances
 
-**Problem:** Using `Create` procedures with `HonoStreamAppBuilder` — it only handles `CreateStream` procedures.
+**Problem:** Creating one `HonoAppBuilder` per procedure kind (RPC, stream, HTTP) the way v7 required — duplicating cross-cutting config (errors, lifecycle hooks, context factories) in every instance.
 
 ```typescript
-// BAD — Create procedures are silently ignored
-const { Create, CreateStream } = Procedures<AppContext, RPCConfig>()
-Create('GetUser', { scope: 'users', version: 1 }, handler)
-CreateStream('StreamEvents', { scope: 'events', version: 1 }, streamHandler)
-
-new HonoStreamAppBuilder()
-  .register(factory, ctx)  // Only StreamEvents is registered
-  .build()
+// BAD — three builders, three copies of the same config
+const rpcApp    = new HonoAppBuilder({ errors: appErrors }).register(RPC, ctx).build()
+const streamApp = new HonoAppBuilder({ errors: appErrors }).register(StreamRPC, ctx).build()
+const apiApp    = new HonoAppBuilder({ errors: appErrors }).register(API, ctx).build()
 ```
 
-**Fix:** Use `HonoRPCAppBuilder` or `ExpressRPCAppBuilder` for standard procedures. Use `HonoStreamAppBuilder` only for stream procedures.
+**Fix:** In v8, `HonoAppBuilder` dispatches all four procedure kinds (`Create`, `CreateStream`, `CreateHttp`, `CreateHttpStream`) from a single `register()` call. One builder, one config block, all procedures.
 
 ```typescript
-// GOOD
-const rpcApp = new HonoRPCAppBuilder().register(RPC, ctx).build()
-const streamApp = new HonoStreamAppBuilder().register(StreamRPC, ctx).build()
+// GOOD — one builder, all procedure kinds
+const procs = Procedures<AppContext, RPCConfig>()
+procs.Create('GetUser', { scope: 'users', version: 1 }, rpcHandler)
+procs.CreateStream('StreamEvents', { scope: 'events', version: 1 }, streamHandler)
+procs.CreateHttp('CreateUser', { path: '/users', method: 'post', schema: { /* ... */ } }, httpHandler)
+
+const app = new HonoAppBuilder({
+  errors: appErrors,
+  unknownError: { toResponse: (err) => ({ error: (err as Error).message }) },
+  stream: { defaultStreamMode: 'sse' },
+})
+  .register(procs, (c) => ({ /* ctx */ }))
+  .build()
 ```
 
+**Why:** v8 collapsed v7's `HonoRPCAppBuilder` / `HonoStreamAppBuilder` / `HonoAPIAppBuilder` into one builder with stratified config (`rpc.{onSuccess}`, `api.{queryParser, onSuccess}`, `stream.{defaultStreamMode, onStreamStart, onStreamEnd, onMidStreamError}`). Cross-cutting config (`errors`, `unknownError`, `onError`, `onRequestError`, `onRequestStart`, `onRequestEnd`) lives at the top level and applies uniformly across kinds.
+
 ---
 
 ## 13. Missing Schema at Registration Time
@@ -398,9 +406,14 @@ Create('GetUser', {
 **Problem:** Using a single error handler for both validation errors (before streaming) and runtime errors (during streaming).
 
 ```typescript
-// BAD — onError doesn't apply to streaming
-new HonoStreamAppBuilder({
-  onError: (proc, c, err) => { /* This doesn't exist */ },
+// BAD — top-level onError fires for pre-stream errors only.
+// Errors thrown after the first yield will NOT reach this callback.
+new HonoAppBuilder({
+  onError: (proc, c, err) => {
+    // Catches pre-stream (validation / context) errors only.
+    // Mid-stream errors silently pass through — the HTTP status is already
+    // committed, so the response can't be rewritten here.
+  },
 })
 ```
 
@@ -410,15 +423,17 @@ new HonoStreamAppBuilder({
 // GOOD
 import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
 
-new HonoStreamAppBuilder({
+new HonoAppBuilder({
   // Taxonomy handles all pre-stream errors (validation, auth, context)
   errors: defineErrorTaxonomy({
     AuthError: { class: AuthError, statusCode: 401 },
   }),
   unknownError: { toResponse: (err) => ({ error: (err as Error).message }) },
-  // Mid-stream still goes through onMidStreamError — the HTTP status is
-  // already committed, so errors become yields, not responses.
-  onMidStreamError: (proc, c, error) => ({ data: { error: error.message }, closeStream: true }),
+  // Mid-stream still goes through stream.onMidStreamError — the HTTP status
+  // is already committed, so errors become yields, not responses.
+  stream: {
+    onMidStreamError: (proc, c, error) => ({ data: { error: error.message }, closeStream: true }),
+  },
 })
 ```
 
@@ -516,75 +531,70 @@ const appErrors = defineErrorTaxonomy({
   },
 })
 
-const app = new ExpressRPCAppBuilder({
+const app = new HonoAppBuilder({
   errors: appErrors,
   unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
 })
-  .register(factory, async (req) => {
-    const user = await authenticate(req.headers.authorization)
+  .register(factory, async (c) => {
+    const user = await authenticate(c.req.header('authorization'))
     if (!user) throw new AuthError('invalid token')
     return { userId: user.id }
   })
 ```
 
-The imperative `onError: (procedure, req, res, error) => void` callback is a first-class peer — use it for apps that prefer a single response handler or when you want to handle the tail of errors the taxonomy doesn't cover.
+The imperative `onError: (procedure, c, error) => Response` callback is a first-class peer — use it for apps that prefer a single response handler or when you want to handle the tail of errors the taxonomy doesn't cover.
 
 ---
 
-## 18. Using Both schema.params and schema.input
+## 18. Mixing schema.params and schema.req on the same procedure
 
-**Problem:** Defining both `schema.params` and `schema.input` on the same procedure.
+**Problem:** `schema.params` (RPC channel) and `schema.req` (HTTP channel) are mutually exclusive on `CreateHttp`. Using both throws at registration.
 
 ```typescript
 // BAD — throws ProcedureRegistrationError at registration
-Create('GetUser', {
+API.CreateHttp('GetUser', {
   path: '/users/:id',
   method: 'get',
   schema: {
-    params: Type.Object({ id: Type.String() }),
-    input: {
+    params: Type.Object({ id: Type.String() }),  // RPC-only field — invalid on CreateHttp
+    req: {
       pathParams: Type.Object({ id: Type.String() }),
     },
   },
 }, handler)
 ```
 
-**Fix:** Choose one. Use `schema.params` for flat RPC-style input, `schema.input` for structured multi-channel input.
+**Fix:** Use `schema.req` for HTTP routes (`CreateHttp`). Use `schema.params` for RPC routes (`Create`). Never mix them.
 
 ```typescript
-// GOOD — schema.input for REST-style with per-channel validation
-Create('GetUser', {
+// GOOD — CreateHttp with schema.req for per-channel validation
+API.CreateHttp('GetUser', {
   path: '/users/:id',
   method: 'get',
   schema: {
-    input: {
-      pathParams: Type.Object({ id: Type.String() }),
-    },
+    req: { pathParams: Type.Object({ id: Type.String() }) },
   },
 }, async (ctx, { pathParams }) => fetchUser(pathParams.id))
 
-// GOOD — schema.params for simple RPC-style
-Create('GetUser', {
-  scope: 'users', version: 1,
+// GOOD — Create with schema.params for flat RPC-style
+const { GetUser } = Create('GetUser', {
   schema: { params: Type.Object({ id: Type.String() }) },
 }, async (ctx, params) => fetchUser(params.id))
 ```
 
-**Why:** `schema.params` and `schema.input` are mutually exclusive by design. They represent different input paradigms — flat (RPC) vs structured (HTTP API).
-
 ---
 
-## 19. Mismatched Path Param Names in schema.input
+## 19. Mismatched Path Param Names in schema.req.pathParams
 
-**Problem:** Path template param names don't match `schema.input.pathParams` property names.
+**Problem:** Path template param names don't match `schema.req.pathParams` property names.
 
 ```typescript
-// BAD — path has :id but schema declares userId — throws at build time
-Create('GetUser', {
+// BAD — path has :id but schema declares userId — throws at registration
+API.CreateHttp('GetUser', {
   path: '/users/:id',
   method: 'get',
   schema: {
-    input: {
+    req: {
       pathParams: Type.Object({ userId: Type.String() }), // Wrong name!
     },
   },
@@ -595,18 +605,18 @@ Create('GetUser', {
 
 ```typescript
 // GOOD
-Create('GetUser', {
+API.CreateHttp('GetUser', {
   path: '/users/:id',
   method: 'get',
   schema: {
-    input: {
+    req: {
       pathParams: Type.Object({ id: Type.String() }), // Matches :id
     },
   },
 }, handler)
 ```
 
-**Why:** `HonoAPIAppBuilder` validates at build time that `:param` names in the path match schema properties. A mismatch would cause runtime validation failures with confusing error messages.
+**Why:** `CreateHttp` validates at registration time that `:param` names in the path match `schema.req.pathParams` property names. A mismatch throws `ProcedureRegistrationError` immediately so you catch it at startup, not at runtime.
 
 ---
 
@@ -616,7 +626,7 @@ Create('GetUser', {
 
 ```typescript
 // BAD — duplicated across builders, invisible to generated clients
-new HonoAPIAppBuilder({
+new HonoAppBuilder({
   onError: (procedure, c, error) => {
     if (error instanceof ValidationError) return c.json({ error: error.message }, 400)
     if (error instanceof AuthError)       return c.json({ error: 'Unauthorized' }, 401)
@@ -642,7 +652,7 @@ const appErrors = defineErrorTaxonomy({
   },
 })
 
-new HonoAPIAppBuilder({
+new HonoAppBuilder({
   errors: appErrors,
   unknownError: {
     toResponse: () => ({ error: 'Internal server error' }),
@@ -651,7 +661,7 @@ new HonoAPIAppBuilder({
 })
 ```
 
-The same `errors` / `unknownError` shape plugs into every builder (`HonoAPIAppBuilder`, `HonoRPCAppBuilder`, `ExpressRPCAppBuilder`, `HonoStreamAppBuilder` pre-stream only). `ctx.error()` still works and is caught by the default taxonomy at 500.
+The same `errors` / `unknownError` shape plugs into `HonoAppBuilder` and applies uniformly across RPC, HTTP, and pre-stream paths. `ctx.error()` still works and is caught by the default taxonomy at 500.
 
 **The anti-pattern is the ladder, not `onError`.** `onError` is a first-class peer of the taxonomy — it's perfectly fine for simple apps or when you want full response control. The problem is writing `instanceof` ladders *inside* it to route by error class, because that's exactly what the taxonomy is designed to express declaratively.
 
@@ -729,6 +739,46 @@ const { Create: CreateInternal } = Procedures({
 
 ---
 
+## 23. Using `Create` for HTTP routes (v8+)
+
+**Problem:** Using `Create` with HTTP-specific fields (`path`, `method`, `schema.input`) — this throws at registration time in v8.
+
+```typescript
+// BAD — throws ProcedureRegistrationError in v8; Create is the RPC primitive only
+const API = Procedures<Ctx, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: { input: { pathParams: Type.Object({ id: Type.String() }) } },
+}, async (ctx, params) => { /* ... */ })
+```
+
+**Fix:** Use `CreateHttp` for HTTP routes. `schema.input` is renamed `schema.req` in v8.
+
+```typescript
+// GOOD — v8 HTTP surface
+const API = Procedures<Ctx>()
+
+API.CreateHttp('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
+```
+
+**Migration checklist:**
+
+1. Replace `Procedures<Ctx, APIConfig>()` with `Procedures<Ctx>()` for HTTP factories.
+2. Replace `.Create(` with `.CreateHttp(` for every HTTP route.
+3. Rename `schema.input` → `schema.req` (same channels: `pathParams`, `query`, `body`, `headers`).
+4. Move response type to `schema.res.body` (optional — `returnType` was docs-only anyway).
+5. Re-run `npx ts-procedures-codegen` to regenerate clients.
+
+**Why:** `Create` is the RPC primitive (`params` / `returnType` only). HTTP routes with `path`, `method`, and per-channel input belong on `CreateHttp` (unary) or `CreateHttpStream` (streaming). Separating the surfaces makes the builder routing explicit and allows `CreateHttp` to support response headers (`schema.res.headers`) without leaking HTTP concepts into the RPC path.
+
+---
+
 ## Summary Table
 
 | # | Anti-Pattern | Risk | Severity |
@@ -744,7 +794,7 @@ const { Create: CreateInternal } = Procedures({
 | 9 | Manual type coercion | Unnecessary code, coercion mismatch | SUGGESTION |
 | 10 | Expecting extra fields to survive | Silent data loss | WARNING |
 | 11 | Missing context type | No type safety in handlers | WARNING |
-| 12 | Create with HonoStreamAppBuilder | Procedures silently ignored | CRITICAL |
+| 12 | Splitting procedures across multiple HonoAppBuilder instances | Duplicated cross-cutting config; one builder dispatches all kinds in v8 | WARNING |
 | 13 | Plain JSON Schema objects instead of TypeBox | ProcedureRegistrationError | CRITICAL |
 | 14 | Wrong error handler for streams | Unhandled errors or wrong response format | WARNING |
 | 15 | Manual doc building instead of extendProcedureDoc | Fragile, incomplete documentation | SUGGESTION |
@@ -755,3 +805,4 @@ const { Create: CreateInternal } = Procedures({
 | 20 | Hand-writing onError instanceof ladders | Drifting response shapes, untyped client errors | WARNING |
 | 21 | Catching raw DOMException/TypeError from generated callables | Framework normalizes these; raw platform errors won't reach catch blocks after 7.0.0 | WARNING |
 | 22 | `noRuntimeValidation` on a public-facing factory | Untrusted wire data reaches handlers without AJV; coerceTypes/removeAdditional also disabled | CRITICAL |
+| 23 | Using `Create` for HTTP routes (v8+) | ProcedureRegistrationError at startup; HTTP fields require `CreateHttp` / `CreateHttpStream` | CRITICAL |