zero-http 0.2.5 → 0.3.1

package/documentation/public/data/api.json

@@ -1,24 +1,33 @@
 [
   {
     "name": "createApp()",
-    "description": "Returns an application instance with Express-like routing, middleware support, WebSocket handling, error handling, and an HTTP/HTTPS server.",
-    "example": "const { createApp, json, cors, logger, compress,\n\tstatic: serveStatic } = require('zero-http')\nconst app = createApp()\n\napp.use(logger({ format: 'dev' }))\napp.use(cors())\napp.use(compress())\napp.use(json({ limit: '10kb' }))\napp.use(serveStatic(path.join(__dirname, 'public')))\n\napp.get('/', (req, res) => res.json({ hello: 'world' }))\n\napp.ws('/chat', (ws, req) => {\n\tws.on('message', msg => ws.send('echo: ' + msg))\n})\n\napp.onError((err, req, res, next) => {\n\tconsole.error(err)\n\tres.status(500).json({ error: err.message })\n})\n\n// HTTP\napp.listen(3000, () => console.log('listening on :3000'))\n\n// HTTPS\napp.listen(443, { key: fs.readFileSync('key.pem'), cert: fs.readFileSync('cert.pem') })",
+    "description": "Returns an application instance with Express-like routing, middleware support, WebSocket handling, settings management, error handling, and an HTTP/HTTPS server. All HTTP method shortcuts return the App instance for chaining.",
+    "example": "const { createApp, json, cors, logger, compress, helmet, timeout,\n\trequestId, cookieParser, static: serveStatic } = require('zero-http')\nconst app = createApp()\n\n// Settings\napp.set('env', 'production')\napp.enable('trust proxy')\nconsole.log(app.get('env'))     // 'production'\nconsole.log(app.enabled('trust proxy')) // true\n\n// Shared locals across all requests\napp.locals.appName = 'My API'\n\n// Middleware stack\napp.use(logger({ format: 'dev' }))\napp.use(helmet())\napp.use(cors())\napp.use(compress())\napp.use(timeout(30000))\napp.use(requestId())\napp.use(cookieParser('my-secret'))\napp.use(json({ limit: '10kb' }))\napp.use(serveStatic(path.join(__dirname, 'public')))\n\n// Chained route registration\napp.get('/', (req, res) => res.json({ hello: 'world' }))\n   .get('/health', (req, res) => res.json({ status: 'ok' }))\n\n// Route grouping\napp.group('/api/v1', json(), (router) => {\n\trouter.get('/users', (req, res) => res.json([]))\n\trouter.post('/users', (req, res) => res.status(201).json(req.body))\n})\n\n// Param handler\napp.param('id', (req, res, next, value) => {\n\treq.item = items.find(i => i.id === value)\n\tif (!req.item) return res.status(404).json({ error: 'Not found' })\n\tnext()\n})\n\n// WebSocket\napp.ws('/chat', (ws, req) => {\n\tws.on('message', msg => ws.send('echo: ' + msg))\n})\n\n// Error handler\napp.onError((err, req, res, next) => {\n\tconsole.error(err)\n\tres.status(500).json({ error: err.message })\n})\n\n// HTTP\napp.listen(3000, () => console.log('listening on :3000'))\n\n// HTTPS\napp.listen(443, { key: fs.readFileSync('key.pem'), cert: fs.readFileSync('cert.pem') })",
     "methods": [
       { "method": "use", "signature": "use(fn)", "description": "Register global middleware; fn(req, res, next)." },
       { "method": "use", "signature": "use(prefix, fn|router)", "description": "Register path-scoped middleware or mount a Router sub-app. The prefix is stripped from req.url." },
-      { "method": "get", "signature": "get(path, [opts], ...handlers)", "description": "Register GET route handlers. Optional opts object for { secure } matching." },
-      { "method": "post", "signature": "post(path, [opts], ...handlers)", "description": "Register POST route handlers." },
-      { "method": "put", "signature": "put(path, [opts], ...handlers)", "description": "Register PUT route handlers." },
-      { "method": "delete", "signature": "delete(path, [opts], ...handlers)", "description": "Register DELETE route handlers." },
-      { "method": "patch", "signature": "patch(path, [opts], ...handlers)", "description": "Register PATCH route handlers." },
-      { "method": "options", "signature": "options(path, [opts], ...handlers)", "description": "Register OPTIONS route handlers." },
-      { "method": "head", "signature": "head(path, [opts], ...handlers)", "description": "Register HEAD route handlers." },
-      { "method": "all", "signature": "all(path, [opts], ...handlers)", "description": "Register handlers for ALL HTTP methods." },
+      { "method": "get", "signature": "get(path, [opts], ...handlers)", "description": "Register GET route handlers. Returns App (chainable). With 1 arg, acts as settings getter — see set()." },
+      { "method": "post", "signature": "post(path, [opts], ...handlers)", "description": "Register POST route handlers. Returns App (chainable)." },
+      { "method": "put", "signature": "put(path, [opts], ...handlers)", "description": "Register PUT route handlers. Returns App (chainable)." },
+      { "method": "delete", "signature": "delete(path, [opts], ...handlers)", "description": "Register DELETE route handlers. Returns App (chainable)." },
+      { "method": "patch", "signature": "patch(path, [opts], ...handlers)", "description": "Register PATCH route handlers. Returns App (chainable)." },
+      { "method": "options", "signature": "options(path, [opts], ...handlers)", "description": "Register OPTIONS route handlers. Returns App (chainable)." },
+      { "method": "head", "signature": "head(path, [opts], ...handlers)", "description": "Register HEAD route handlers. Returns App (chainable)." },
+      { "method": "all", "signature": "all(path, [opts], ...handlers)", "description": "Register handlers for ALL HTTP methods. Returns App (chainable)." },
+      { "method": "set", "signature": "set(key) | set(key, value)", "description": "Dual-purpose: 1 arg = get setting value, 2 args = set setting value. Setter returns App (chainable)." },
+      { "method": "enable", "signature": "enable(key)", "description": "Set a boolean setting to true. Returns App (chainable)." },
+      { "method": "disable", "signature": "disable(key)", "description": "Set a boolean setting to false. Returns App (chainable)." },
+      { "method": "enabled", "signature": "enabled(key)", "description": "Check if a setting is truthy. Returns boolean." },
+      { "method": "disabled", "signature": "disabled(key)", "description": "Check if a setting is falsy. Returns boolean." },
+      { "method": "locals", "signature": "(object)", "description": "Shared key-value store merged into every req.locals and res.locals per request." },
+      { "method": "param", "signature": "param(name, fn)", "description": "Register a handler for a named route parameter. fn(req, res, next, value). Returns App (chainable)." },
+      { "method": "group", "signature": "group(prefix, ...middleware, cb)", "description": "Create a route group under a prefix with shared middleware. Last arg is (router) => {} callback. Returns App." },
+      { "method": "chain", "signature": "chain(path)", "description": "Returns a chainable route object with .get(), .post(), etc. for a single path. Alias for router.route()." },
       { "method": "ws", "signature": "ws(path, [opts], handler)", "description": "Register a WebSocket upgrade handler. handler receives (ws, req)." },
       { "method": "onError", "signature": "onError(fn)", "description": "Register a global error handler: fn(err, req, res, next). Only one at a time." },
-      { "method": "listen", "signature": "listen(port, [tlsOpts], [cb])", "description": "Start HTTP server, or HTTPS if tlsOpts includes { key, cert }. Returns the server instance." },
+      { "method": "listen", "signature": "listen(port, [tlsOpts], [cb])", "description": "Start HTTP server (default port 3000), or HTTPS if tlsOpts includes { key, cert }. Returns the server instance." },
       { "method": "close", "signature": "close([cb])", "description": "Gracefully close the server and invoke the optional callback." },
-      { "method": "routes", "signature": "routes()", "description": "Return a flat array of all registered routes for introspection." },
+      { "method": "routes", "signature": "routes()", "description": "Return a flat array of all registered routes (including WS) for introspection." },
       { "method": "handler", "signature": "(property)", "description": "Bound request handler suitable for http.createServer(app.handler)." }
     ],
     "options": []
@@ -44,11 +53,14 @@
   },
   {
     "name": "Request (req)",
-    "description": "Wraps the incoming Node http.IncomingMessage with convenient properties and helpers. Includes HTTPS detection via req.secure and req.protocol.",
-    "example": "app.get('/info', (req, res) => {\n\tconsole.log(req.method)           // 'GET'\n\tconsole.log(req.url)              // '/info?foo=bar'\n\tconsole.log(req.query)            // { foo: 'bar' }\n\tconsole.log(req.ip)               // '127.0.0.1'\n\tconsole.log(req.secure)           // true/false\n\tconsole.log(req.protocol)         // 'https' or 'http'\n\tconsole.log(req.get('host'))      // 'localhost:3000'\n\tconsole.log(req.is('json'))       // false\n\tres.json({ ok: true })\n})",
+    "description": "Wraps the incoming Node http.IncomingMessage with convenient properties and helpers. Includes HTTPS detection, cookie access, content negotiation, and Express-compatible properties like originalUrl, baseUrl, hostname, and xhr.",
+    "example": "app.get('/info', (req, res) => {\n\tconsole.log(req.method)           // 'GET'\n\tconsole.log(req.url)              // '/info?foo=bar'\n\tconsole.log(req.originalUrl)      // '/api/info?foo=bar' (full original)\n\tconsole.log(req.baseUrl)          // '/api' (set by mounted routers)\n\tconsole.log(req.path)             // '/info'\n\tconsole.log(req.query)            // { foo: 'bar' }\n\tconsole.log(req.params)           // { id: '42' } (from route pattern)\n\tconsole.log(req.ip)               // '127.0.0.1'\n\tconsole.log(req.secure)           // true/false\n\tconsole.log(req.protocol)         // 'https' or 'http'\n\tconsole.log(req.hostname)         // 'example.com'\n\tconsole.log(req.xhr)              // true if X-Requested-With: XMLHttpRequest\n\tconsole.log(req.fresh)            // conditional GET freshness\n\tconsole.log(req.stale)            // !req.fresh\n\tconsole.log(req.app)              // the App instance\n\tconsole.log(req.cookies)          // {} (populated by cookieParser)\n\tconsole.log(req.locals)           // {} request-scoped store\n\tconsole.log(req.get('host'))      // 'localhost:3000'\n\tconsole.log(req.is('json'))       // false\n\tconsole.log(req.accepts('json', 'html'))  // 'json'\n\tconsole.log(req.subdomains())     // ['api'] for api.example.com\n\tconsole.log(req.range(1000))      // { type: 'bytes', ranges: [{start:0,end:499}] }\n\tres.json({ ok: true })\n})",
     "methods": [
       { "method": "method", "signature": "(string)", "description": "HTTP method (GET, POST, etc.)." },
-      { "method": "url", "signature": "(string)", "description": "Request URL path + query string." },
+      { "method": "url", "signature": "(string)", "description": "Request URL path + query string (may be rewritten by mounted routers)." },
+      { "method": "originalUrl", "signature": "(string)", "description": "The original request URL before any router rewrites. Never changes." },
+      { "method": "baseUrl", "signature": "(string)", "description": "The prefix path where the router was mounted. Empty string for root app." },
+      { "method": "path", "signature": "(string)", "description": "URL pathname without query string." },
       { "method": "headers", "signature": "(object)", "description": "Raw request headers (lowercased keys)." },
       { "method": "query", "signature": "(object)", "description": "Parsed query string via URLSearchParams." },
       { "method": "params", "signature": "(object)", "description": "Route parameters populated by the router (e.g. { id: '42' })." },
@@ -56,26 +68,50 @@
       { "method": "ip", "signature": "(string|null)", "description": "Remote IP address from req.socket.remoteAddress." },
       { "method": "secure", "signature": "(boolean)", "description": "true when the connection is over TLS (HTTPS)." },
       { "method": "protocol", "signature": "(string)", "description": "'https' or 'http' based on connection type." },
+      { "method": "hostname", "signature": "(string|undefined)", "description": "Hostname from x-forwarded-host or host header, port stripped." },
+      { "method": "fresh", "signature": "(boolean)", "description": "true for GET/HEAD when If-None-Match / If-Modified-Since match cached version." },
+      { "method": "stale", "signature": "(boolean)", "description": "Inverse of fresh — true when the response needs to be sent in full." },
+      { "method": "xhr", "signature": "(boolean)", "description": "true when X-Requested-With header equals 'XMLHttpRequest'." },
+      { "method": "cookies", "signature": "(object)", "description": "Parsed cookies (populated by cookieParser middleware)." },
+      { "method": "signedCookies", "signature": "(object)", "description": "Verified signed cookies (populated by cookieParser with a secret)." },
+      { "method": "locals", "signature": "(object)", "description": "Request-scoped store. Merged with app.locals on each request." },
+      { "method": "app", "signature": "(App|null)", "description": "Reference to the App instance handling this request." },
       { "method": "raw", "signature": "(object)", "description": "The underlying http.IncomingMessage." },
       { "method": "get", "signature": "get(name)", "description": "Get a request header (case-insensitive)." },
-      { "method": "is", "signature": "is(type)", "description": "Check if Content-Type contains the given type string (e.g. 'json', 'text/html')." }
+      { "method": "is", "signature": "is(type)", "description": "Check if Content-Type contains the given type string (e.g. 'json', 'text/html')." },
+      { "method": "accepts", "signature": "accepts(...types)", "description": "Content negotiation — returns the best match from the given types based on Accept header, or false. Supports shorthands: 'json', 'html', 'text', 'xml', 'css', 'js'." },
+      { "method": "subdomains", "signature": "subdomains([offset])", "description": "Returns subdomain array. Default offset=2 strips TLD+domain. E.g. 'api.blog.example.com' → ['blog', 'api']." },
+      { "method": "range", "signature": "range(size)", "description": "Parse Range header. Returns { type, ranges: [{start, end}] }, -1 (unsatisfiable), or -2 (malformed/missing)." }
     ],
     "options": []
   },
   {
     "name": "Response (res)",
-    "description": "Wraps the outgoing Node http.ServerResponse with chainable helpers for setting status, headers, sending responses, and opening an SSE stream.",
-    "example": "app.get('/demo', (req, res) => {\n\tres.status(200)\n\t   .set('X-Custom', 'hello')\n\t   .type('json')\n\t   .json({ message: 'ok' })\n})\n\napp.get('/page', (req, res) => res.html('<h1>Hello</h1>'))\napp.get('/go', (req, res) => res.redirect(301, '/new-location'))\n\n// Open an SSE stream\napp.get('/events', (req, res) => {\n\tconst sse = res.sse({ retry: 5000, autoId: true })\n\tsse.send('hello')\n})",
+    "description": "Wraps the outgoing Node http.ServerResponse with chainable helpers for setting status, headers, cookies, sending responses, content negotiation, file streaming, and opening an SSE stream.",
+    "example": "app.get('/demo', (req, res) => {\n\tres.status(200)\n\t   .set('X-Custom', 'hello')\n\t   .type('json')\n\t   .json({ message: 'ok' })\n})\n\napp.get('/page', (req, res) => res.html('<h1>Hello</h1>'))\napp.get('/go', (req, res) => res.redirect(301, '/new-location'))\n\n// Content negotiation\napp.get('/data', (req, res) => {\n\tres.format({\n\t\t'text/html': () => res.html('<p>data</p>'),\n\t\t'application/json': () => res.json({ data: true }),\n\t\tdefault: () => res.text('data')\n\t})\n})\n\n// Cookies\napp.get('/setcookie', (req, res) => {\n\tres.cookie('session', 'abc123', { maxAge: 3600, secure: true })\n\t   .json({ ok: true })\n})\n\n// File download\napp.get('/download', (req, res) => {\n\tres.download('/path/to/report.pdf', 'report.pdf')\n})\n\n// SSE\napp.get('/events', (req, res) => {\n\tconst sse = res.sse({ retry: 5000, autoId: true })\n\tsse.send('hello')\n})",
     "methods": [
       { "method": "status", "signature": "status(code)", "description": "Set HTTP status code. Returns this (chainable)." },
-      { "method": "set", "signature": "set(name, value)", "description": "Set a response header. Returns this (chainable)." },
+      { "method": "sendStatus", "signature": "sendStatus(code)", "description": "Set status code and send the status text as the response body (e.g. 404 → 'Not Found')." },
+      { "method": "set", "signature": "set(name, value)", "description": "Set a response header. CRLF injection protection built-in. Returns this (chainable)." },
       { "method": "get", "signature": "get(name)", "description": "Get a previously-set response header (case-insensitive)." },
+      { "method": "append", "signature": "append(name, value)", "description": "Append to a response header (comma-separated). CRLF injection protection. Returns this (chainable)." },
+      { "method": "vary", "signature": "vary(field)", "description": "Add a field to the Vary header. Deduplicates and handles '*'. Returns this (chainable)." },
       { "method": "type", "signature": "type(ct)", "description": "Set Content-Type. Accepts shorthands: 'json', 'html', 'text', 'xml', 'form', 'bin'. Chainable." },
+      { "method": "links", "signature": "links(links)", "description": "Set Link header from an object. E.g. links({ next: '/p/2', last: '/p/5' }) → '<\\/p/2>; rel=\"next\", <\\/p/5>; rel=\"last\"'. Chainable." },
+      { "method": "location", "signature": "location(url)", "description": "Set the Location header. Returns this (chainable)." },
+      { "method": "headersSent", "signature": "(boolean)", "description": "true once headers have been flushed to the client (delegates to raw response)." },
+      { "method": "app", "signature": "(App|null)", "description": "Reference to the App instance handling this request." },
+      { "method": "locals", "signature": "(object)", "description": "Response-scoped store. Merged with app.locals on each request." },
       { "method": "send", "signature": "send(body)", "description": "Send the response. Auto-detects Content-Type: Buffer→octet-stream, '<…'→html, string→text, object→json." },
       { "method": "json", "signature": "json(obj)", "description": "Set Content-Type to application/json and send the object." },
       { "method": "text", "signature": "text(str)", "description": "Set Content-Type to text/plain and send the string." },
       { "method": "html", "signature": "html(str)", "description": "Set Content-Type to text/html and send the string." },
       { "method": "redirect", "signature": "redirect([status], url)", "description": "Redirect to URL. Default status is 302." },
+      { "method": "format", "signature": "format(types)", "description": "Content negotiation — takes an object mapping MIME types to handler functions. Supports 'default' key. Returns 406 if no match." },
+      { "method": "sendFile", "signature": "sendFile(path, [opts], [cb])", "description": "Stream a file as the response. Auto-detects Content-Type. opts: { root, headers }. Path traversal protection built-in." },
+      { "method": "download", "signature": "download(path, [filename], [cb])", "description": "Set Content-Disposition: attachment and stream the file. Optional filename overrides the download name." },
+      { "method": "cookie", "signature": "cookie(name, value, [opts])", "description": "Set a cookie. Object values are auto-serialised as JSON cookies (j: prefix). opts: path('/'), httpOnly(true), sameSite('Lax'), domain, maxAge(seconds), expires, secure, signed(false), priority, partitioned. Returns this (chainable)." },
+      { "method": "clearCookie", "signature": "clearCookie(name, [opts])", "description": "Clear a cookie by setting expires to epoch. Returns this (chainable)." },
       { "method": "sse", "signature": "sse([opts])", "description": "Open a Server-Sent Events stream. Returns an SSEStream controller with send(), event(), comment(), close(), etc." }
     ],
     "options": []
@@ -105,8 +141,8 @@
   },
   {
     "name": "WebSocketConnection",
-    "description": "Represents a single WebSocket connection. Created automatically when a client upgrades to WebSocket at a registered ws() path. Provides an event-driven API with per-connection data store, connection metadata, and binary/text messaging.",
-    "example": "// Properties available on each ws connection:\napp.ws('/demo', (ws, req) => {\n\tconsole.log(ws.id)             // 'ws_1_a3x9k'\n\tconsole.log(ws.readyState)     // 1 (OPEN)\n\tconsole.log(ws.protocol)       // negotiated sub-protocol\n\tconsole.log(ws.headers)        // upgrade request headers\n\tconsole.log(ws.ip)             // remote IP\n\tconsole.log(ws.query)          // parsed query params\n\tconsole.log(ws.url)            // upgrade URL\n\tconsole.log(ws.secure)         // true for wss://\n\tconsole.log(ws.connectedAt)    // timestamp of connection\n\tconsole.log(ws.uptime)         // ms since connected\n\tconsole.log(ws.bufferedAmount) // pending bytes\n\n\t// Per-connection data store\n\tws.data.role = 'admin'\n\tif (ws.data.role === 'admin') ws.send('admin tools unlocked')\n})",
+    "description": "Represents a single WebSocket connection. Created automatically when a client upgrades to WebSocket at a registered ws() path. Provides an event-driven API with per-connection data store, connection metadata, and binary/text messaging. Exposes static state constants: CONNECTING (0), OPEN (1), CLOSING (2), CLOSED (3).",
+    "example": "// Properties available on each ws connection:\napp.ws('/demo', (ws, req) => {\n\tconsole.log(ws.id)             // 'ws_1_a3x9k'\n\tconsole.log(ws.readyState)     // 1 (OPEN)\n\tconsole.log(ws.protocol)       // negotiated sub-protocol\n\tconsole.log(ws.headers)        // upgrade request headers\n\tconsole.log(ws.ip)             // remote IP\n\tconsole.log(ws.query)          // parsed query params\n\tconsole.log(ws.url)            // upgrade URL\n\tconsole.log(ws.secure)         // true for wss://\n\tconsole.log(ws.connectedAt)    // timestamp of connection\n\tconsole.log(ws.uptime)         // ms since connected\n\tconsole.log(ws.bufferedAmount) // pending bytes\n\n\t// Per-connection data store\n\tws.data.role = 'admin'\n\tif (ws.data.role === 'admin') ws.send('admin tools unlocked')\n\n\t// State constants\n\tif (ws.readyState === WebSocketConnection.OPEN) { /* connected */ }\n})",
     "methods": [
       { "method": "id", "signature": "(string)", "description": "Unique connection identifier (e.g. ws_1_l8x3k)." },
       { "method": "readyState", "signature": "(number)", "description": "0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED (mirrors the WebSocket spec)." },
@@ -125,6 +161,29 @@
     ],
     "options": []
   },
+  {
+    "name": "WebSocketPool",
+    "description": "Connection and room manager for WebSocket connections. Provides broadcast, room-based messaging, and connection lifecycle management. Auto-removes connections on close. All mutating methods return the pool for chaining.",
+    "example": "const { createApp, WebSocketPool } = require('zero-http')\nconst app = createApp()\nconst pool = new WebSocketPool()\n\napp.ws('/chat', (ws, req) => {\n\tpool.add(ws)                      // auto-removed on close\n\tpool.join(ws, req.query.room || 'general')\n\n\tws.data.name = req.query.name || 'anon'\n\tpool.toRoomJSON('general', { type: 'join', user: ws.data.name }, ws)\n\n\tws.on('message', msg => {\n\t\tconst room = pool.roomsOf(ws)[0]\n\t\tpool.toRoom(room, ws.data.name + ': ' + msg, ws)\n\t})\n\n\tws.on('close', () => {\n\t\tconsole.log('pool size:', pool.size)\n\t\tconsole.log('rooms:', pool.rooms)\n\t})\n})\n\n// Broadcast to everyone\napp.get('/announce', (req, res) => {\n\tpool.broadcastJSON({ announcement: req.query.msg })\n\tres.json({ sent: pool.size })\n})\n\napp.listen(3000)",
+    "methods": [
+      { "method": "add", "signature": "add(ws)", "description": "Add a connection to the pool. Auto-removes on close. Returns this." },
+      { "method": "remove", "signature": "remove(ws)", "description": "Remove a connection from the pool and all its rooms. Returns this." },
+      { "method": "join", "signature": "join(ws, room)", "description": "Join a connection to a named room. Returns this." },
+      { "method": "leave", "signature": "leave(ws, room)", "description": "Remove a connection from a room. Cleans up empty rooms. Returns this." },
+      { "method": "broadcast", "signature": "broadcast(data, [exclude])", "description": "Send a message to ALL connected clients. Optional exclude connection (e.g. the sender)." },
+      { "method": "broadcastJSON", "signature": "broadcastJSON(obj, [exclude])", "description": "JSON-serialize and broadcast to all clients." },
+      { "method": "toRoom", "signature": "toRoom(room, data, [exclude])", "description": "Send a message to all connections in a specific room." },
+      { "method": "toRoomJSON", "signature": "toRoomJSON(room, obj, [exclude])", "description": "JSON-serialize and send to all connections in a room." },
+      { "method": "in", "signature": "in(room)", "description": "Get an array of all connections in a room." },
+      { "method": "roomsOf", "signature": "roomsOf(ws)", "description": "Get all room names a connection belongs to." },
+      { "method": "size", "signature": "(number)", "description": "Total number of active connections (getter)." },
+      { "method": "roomSize", "signature": "roomSize(room)", "description": "Number of connections in a specific room." },
+      { "method": "rooms", "signature": "(string[])", "description": "List of all active room names (getter)." },
+      { "method": "clients", "signature": "(WebSocketConnection[])", "description": "Array of all active connections (getter)." },
+      { "method": "closeAll", "signature": "closeAll([code], [reason])", "description": "Close all connections gracefully. Default code=1001, reason='Server shutdown'." }
+    ],
+    "options": []
+  },
   {
     "name": "res.sse([opts]) / SSEStream",
     "description": "Opens a Server-Sent Events stream from a route handler. Returns an SSEStream controller with methods for sending events, comments, and controlling the stream lifecycle. Supports auto-incrementing IDs, keep-alive, retry hints, and per-stream data store.",
@@ -155,10 +214,263 @@
       { "option": "headers", "type": "object", "default": "—", "notes": "Additional response headers merged into the SSE response." }
     ]
   },
+  {
+    "name": "helmet([opts])",
+    "description": "Security headers middleware that sets sensible defaults for Content-Security-Policy, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and more. All 16 options can be individually overridden or disabled by setting them to false.",
+    "example": "const { createApp, helmet } = require('zero-http')\nconst app = createApp()\n\n// Sensible defaults — just use it!\napp.use(helmet())\n\n// Customize specific headers\napp.use(helmet({\n\tcontentSecurityPolicy: {\n\t\tdefaultSrc: [\"'self'\"],\n\t\tscriptSrc: [\"'self'\", 'cdn.example.com'],\n\t\tstyleSrc: [\"'self'\", \"'unsafe-inline'\"]\n\t},\n\tframeguard: 'sameorigin',      // allow same-origin iframes\n\thstsMaxAge: 31536000,           // 1 year\n\thstsPreload: true,              // opt-in to HSTS preload list\n\tcrossOriginEmbedderPolicy: true // enable COEP\n}))\n\n// Disable specific protections\napp.use(helmet({\n\thsts: false,                    // disable HSTS\n\tcontentSecurityPolicy: false    // disable CSP\n}))",
+    "methods": [],
+    "options": [
+      { "option": "contentSecurityPolicy", "type": "object|false", "default": "built-in directives", "notes": "CSP directive object. Keys: defaultSrc, scriptSrc, styleSrc, imgSrc, fontSrc, etc. Set false to disable." },
+      { "option": "crossOriginEmbedderPolicy", "type": "boolean", "default": "false", "notes": "Set true to send Cross-Origin-Embedder-Policy: require-corp." },
+      { "option": "crossOriginOpenerPolicy", "type": "string|false", "default": "same-origin", "notes": "Cross-Origin-Opener-Policy value. Set false to disable." },
+      { "option": "crossOriginResourcePolicy", "type": "string|false", "default": "same-origin", "notes": "Cross-Origin-Resource-Policy value. Set false to disable." },
+      { "option": "dnsPrefetchControl", "type": "boolean", "default": "true", "notes": "Set X-DNS-Prefetch-Control: off. Set false to skip." },
+      { "option": "frameguard", "type": "string|false", "default": "deny", "notes": "X-Frame-Options value: 'deny' or 'sameorigin'. Set false to disable." },
+      { "option": "hidePoweredBy", "type": "boolean", "default": "true", "notes": "Removes the X-Powered-By header. Set false to keep it." },
+      { "option": "hsts", "type": "boolean|number", "default": "true", "notes": "Enable Strict-Transport-Security. Set false to disable." },
+      { "option": "hstsMaxAge", "type": "number", "default": "15552000 (~180 days)", "notes": "HSTS max-age in seconds." },
+      { "option": "hstsIncludeSubDomains", "type": "boolean", "default": "true", "notes": "Include subdomains in HSTS policy." },
+      { "option": "hstsPreload", "type": "boolean", "default": "false", "notes": "Add preload flag for HSTS preload list eligibility." },
+      { "option": "ieNoOpen", "type": "boolean", "default": "true", "notes": "Set X-Download-Options: noopen. Set false to skip." },
+      { "option": "noSniff", "type": "boolean", "default": "true", "notes": "Set X-Content-Type-Options: nosniff. Set false to skip." },
+      { "option": "permittedCrossDomainPolicies", "type": "string|false", "default": "none", "notes": "X-Permitted-Cross-Domain-Policies value. Set false to disable." },
+      { "option": "referrerPolicy", "type": "string|false", "default": "no-referrer", "notes": "Referrer-Policy value. Set false to disable." },
+      { "option": "xssFilter", "type": "boolean", "default": "false", "notes": "Set true to enable X-XSS-Protection: 1; mode=block." }
+    ]
+  },
+  {
+    "name": "timeout(ms, [opts])",
+    "description": "Request timeout middleware. If the handler doesn't respond within the given time, the request is terminated with a configurable status code and message. Sets req.timedOut boolean for downstream checks.",
+    "example": "const { createApp, timeout, json } = require('zero-http')\nconst app = createApp()\n\n// Global 30-second timeout\napp.use(timeout())\n\n// Custom timeout with options\napp.use(timeout(5000, {\n\tstatus: 504,\n\tmessage: 'Gateway Timeout — the upstream took too long'\n}))\n\n// Per-route timeout\napp.post('/slow-task', timeout(60000), json(), async (req, res) => {\n\tconst result = await longRunningTask()\n\tif (req.timedOut) return   // guard against sending after timeout\n\tres.json(result)\n})",
+    "methods": [],
+    "options": [
+      { "option": "ms", "type": "number", "default": "30000", "notes": "Timeout duration in milliseconds. Can also be passed as the first argument." },
+      { "option": "status", "type": "number", "default": "408", "notes": "HTTP status code sent when the timeout fires." },
+      { "option": "message", "type": "string", "default": "Request Timeout", "notes": "Response body text sent on timeout." }
+    ]
+  },
+  {
+    "name": "requestId([opts])",
+    "description": "Generates a unique request ID for every incoming request. Sets req.id and mirrors it as a response header for request tracing and log correlation. Uses crypto.randomUUID() by default.",
+    "example": "const { createApp, requestId, logger } = require('zero-http')\nconst app = createApp()\n\napp.use(requestId())\napp.use(logger({ format: 'dev' }))\n\napp.get('/', (req, res) => {\n\tconsole.log('Request ID:', req.id)  // e.g. '550e8400-e29b-41d4-a716-446655440000'\n\tres.json({ requestId: req.id })\n})\n// Response header: X-Request-Id: 550e8400-e29b-41d4-a716-446655440000\n\n// Trust proxy-forwarded IDs\napp.use(requestId({\n\theader: 'X-Trace-Id',\n\ttrustProxy: true\n}))\n\n// Custom generator\napp.use(requestId({\n\tgenerator: () => 'req_' + Date.now() + '_' + Math.random().toString(36).slice(2, 8)\n}))",
+    "methods": [],
+    "options": [
+      { "option": "header", "type": "string", "default": "X-Request-Id", "notes": "Header name used to read (if trustProxy) and write the request ID." },
+      { "option": "generator", "type": "function", "default": "crypto.randomUUID()", "notes": "Custom function returning a unique ID string." },
+      { "option": "trustProxy", "type": "boolean", "default": "false", "notes": "When true, trusts the incoming header value (max 128 chars) instead of generating a new one." }
+    ]
+  },
+  {
+    "name": "cookieParser([secret], [opts])",
+    "description": "Parses the Cookie header and populates req.cookies. When a secret is provided, signed cookies (prefixed with 's:') are verified with timing-safe HMAC-SHA256 and placed in req.signedCookies. JSON cookies (prefixed with 'j:') are auto-parsed. Exposes req.secret and req.secrets for downstream middleware. Static helpers: sign, unsign, jsonCookie, parseJSON.",
+    "example": "const { createApp, cookieParser } = require('zero-http')\nconst app = createApp()\n\n// With signing + secret rotation\napp.use(cookieParser(['new-secret', 'old-secret']))\n\napp.get('/read', (req, res) => {\n\tconsole.log(req.cookies)        // { theme: 'dark' }\n\tconsole.log(req.signedCookies)  // { session: 'abc123' } (verified)\n\tconsole.log(req.secret)         // 'new-secret' (first secret)\n\tres.json({ cookies: req.cookies, signed: req.signedCookies })\n})\n\napp.get('/set', (req, res) => {\n\t// Auto-sign with signed:true (uses req.secret)\n\tres.cookie('session', 'abc123', { signed: true, httpOnly: true, maxAge: 3600 })\n\t// Auto-serialise object as JSON cookie (j: prefix)\n\t   .cookie('prefs', { theme: 'dark', lang: 'en' })\n\t// Priority + Partitioned (CHIPS)\n\t   .cookie('tracking', 'x', { priority: 'High', partitioned: true, secure: true, sameSite: 'None' })\n\t   .json({ ok: true })\n})\n\n// Static helpers\nconst signed = cookieParser.sign('value', 'secret')\nconst orig   = cookieParser.unsign(signed, 'secret')   // => 'value'\nconst jval   = cookieParser.jsonCookie({ cart: [1,2] }) // => 'j:{\"cart\":[1,2]}'\nconst parsed = cookieParser.parseJSON(jval)             // => { cart: [1,2] }",
+    "methods": [
+      { "method": "cookieParser.sign", "signature": "cookieParser.sign(value, secret)", "description": "Static method. Signs a value with HMAC-SHA256. Returns 's:<value>.<signature>'." },
+      { "method": "cookieParser.unsign", "signature": "cookieParser.unsign(value, secret|secrets)", "description": "Static method. Verifies and unsigns a signed cookie value. Secret can be a string or array (rotation). Returns the original value or false." },
+      { "method": "cookieParser.jsonCookie", "signature": "cookieParser.jsonCookie(value)", "description": "Static method. Serialises any value as a JSON cookie string prefixed with 'j:'." },
+      { "method": "cookieParser.parseJSON", "signature": "cookieParser.parseJSON(str)", "description": "Static method. Parses a 'j:'-prefixed JSON cookie string. Returns parsed value or original string." }
+    ],
+    "options": [
+      { "option": "secret", "type": "string|string[]", "default": "undefined", "notes": "Signing secret(s) for cookie verification. Array enables key rotation — first key signs, all keys verify. Exposed as req.secret and req.secrets." },
+      { "option": "decode", "type": "boolean", "default": "true", "notes": "When true, decodeURIComponent is applied to cookie values." }
+    ]
+  },
+  {
+    "name": "csrf([opts])",
+    "description": "CSRF protection middleware using the double-submit cookie pattern. Generates a cryptographic token on every state-changing request and validates it on subsequent mutations. Token is set as an HttpOnly cookie and must be sent back via header, body field, or query parameter.",
+    "example": "const { createApp, csrf, json, cookieParser } = require('zero-http')\nconst app = createApp()\n\napp.use(cookieParser())\napp.use(json())\napp.use(csrf())\n\n// GET requests are ignored by default — read the token\napp.get('/form', (req, res) => {\n\tres.json({ csrfToken: req.csrfToken })\n})\n\n// POST/PUT/DELETE must include the token\napp.post('/submit', (req, res) => {\n\t// Token validated automatically by csrf() middleware\n\tres.json({ success: true })\n})\n// Client sends token via:\n//   Header: x-csrf-token: <token>\n//   Body:   { _csrf: '<token>' }\n//   Query:  ?_csrf=<token>\n\n// Custom options\napp.use(csrf({\n\tcookie: '_xsrf',\n\theader: 'x-xsrf-token',\n\tsaltLength: 24,\n\tignorePaths: ['/api/webhooks'],\n\tonError: (err, req, res) => {\n\t\tres.status(403).json({ error: 'Invalid CSRF token' })\n\t}\n}))",
+    "methods": [],
+    "options": [
+      { "option": "cookie", "type": "string", "default": "_csrf", "notes": "Name of the cookie used to store the CSRF secret." },
+      { "option": "header", "type": "string", "default": "x-csrf-token", "notes": "Header name checked for the CSRF token." },
+      { "option": "saltLength", "type": "number", "default": "18", "notes": "Length of the random salt used in token generation." },
+      { "option": "secret", "type": "string", "default": "auto (32-byte hex)", "notes": "HMAC secret for token signing. Auto-generated per process if not provided." },
+      { "option": "ignoreMethods", "type": "string[]", "default": "['GET', 'HEAD', 'OPTIONS']", "notes": "HTTP methods that skip CSRF validation." },
+      { "option": "ignorePaths", "type": "string[]", "default": "[]", "notes": "URL paths that skip CSRF validation (e.g. webhook endpoints)." },
+      { "option": "onError", "type": "function", "default": "403 JSON response", "notes": "Custom error handler: fn(err, req, res). Called when token is missing or invalid." }
+    ]
+  },
+  {
+    "name": "validate(schema, [opts])",
+    "description": "Request validation middleware. Validates and coerces req.body, req.query, and req.params against a schema. Supports 11 data types with automatic type coercion, pattern matching, range checks, enum validation, and custom validators. Unknown fields are stripped by default (mass-assignment protection).",
+    "example": "const { createApp, json, validate } = require('zero-http')\nconst app = createApp()\napp.use(json())\n\n// Validate request body\napp.post('/users', validate({\n\tbody: {\n\t\tname:  { type: 'string', required: true, minLength: 2, maxLength: 50 },\n\t\temail: { type: 'email', required: true },\n\t\tage:   { type: 'integer', min: 13, max: 120 },\n\t\trole:  { type: 'string', enum: ['user', 'admin'], default: 'user' },\n\t\ttags:  { type: 'array', minItems: 1, maxItems: 10 }\n\t}\n}), (req, res) => {\n\t// req.body is sanitized and coerced\n\tres.status(201).json(req.body)\n})\n\n// Validate query params\napp.get('/search', validate({\n\tquery: {\n\t\tq:     { type: 'string', required: true, minLength: 1 },\n\t\tpage:  { type: 'integer', min: 1, default: 1 },\n\t\tlimit: { type: 'integer', min: 1, max: 100, default: 20 }\n\t}\n}), (req, res) => {\n\tres.json({ query: req.query })\n})\n\n// Validate route params\napp.get('/users/:id', validate({\n\tparams: { id: { type: 'uuid', required: true } }\n}), (req, res) => {\n\tres.json({ id: req.params.id })\n})\n\n// Custom validator function\napp.post('/register', validate({\n\tbody: {\n\t\tpassword: {\n\t\t\ttype: 'string', required: true, minLength: 8,\n\t\t\tvalidate: (v) => /[A-Z]/.test(v) && /[0-9]/.test(v)\n\t\t\t\t? undefined : 'Must contain uppercase and number'\n\t\t}\n\t}\n}), (req, res) => res.json({ ok: true }))\n\n// Static helpers — validate outside middleware\nconst { value, error } = validate.field('hello@test.com', { type: 'email' }, 'email')\nconst { sanitized, errors } = validate.object(data, schema)",
+    "methods": [
+      { "method": "validate.field", "signature": "validate.field(value, rule, fieldName)", "description": "Static helper. Validate and coerce a single value. Returns { value, error }." },
+      { "method": "validate.object", "signature": "validate.object(data, schema, [opts])", "description": "Static helper. Validate an entire object against a schema. Returns { sanitized, errors }." }
+    ],
+    "options": [
+      { "option": "stripUnknown", "type": "boolean", "default": "true", "notes": "Remove fields not defined in the schema (prevents mass-assignment attacks)." },
+      { "option": "onError", "type": "function", "default": "422 JSON response", "notes": "Custom error handler: fn(errors, req, res, next). errors is an array of error strings." }
+    ]
+  },
+  {
+    "name": "env",
+    "description": "Typed environment configuration. Loads and validates environment variables from .env files with schema enforcement, type coercion, and sensible defaults. Proxy-based — access variables as env.KEY, env('KEY'), or env.get('KEY'). Supports multi-file loading with environment-specific overrides.",
+    "example": "const { env } = require('zero-http')\n\n// Simple access (no schema) — reads from process.env\nconsole.log(env.NODE_ENV)          // 'development'\nconsole.log(env('PORT'))           // '3000' (string from env)\nconsole.log(env.get('API_KEY'))    // value or undefined\nconsole.log(env.has('DATABASE_URL')) // true/false\n\n// Load with schema validation and type coercion\nenv.load({\n\tPORT:         { type: 'port', default: 3000 },\n\tDATABASE_URL: { type: 'url', required: true },\n\tDEBUG:        { type: 'boolean', default: false },\n\tALLOWED_IPS:  { type: 'array', separator: ',', default: [] },\n\tNODE_ENV:     { type: 'enum', values: ['development', 'production', 'test'], default: 'development' },\n\tSECRET_KEY:   { type: 'string', required: true, min: 32 },\n\tMAX_UPLOAD:   { type: 'integer', min: 1, max: 100, default: 10 },\n\tAPP_CONFIG:   { type: 'json', default: {} }\n})\n\n// After loading, values are typed:\nconsole.log(typeof env.PORT)         // 'number' (3000)\nconsole.log(typeof env.DEBUG)        // 'boolean' (false)\nconsole.log(Array.isArray(env.ALLOWED_IPS))  // true\n\n// File load order (.env → .env.local → .env.{NODE_ENV} → .env.{NODE_ENV}.local)\n// process.env always takes priority\n\n// Require a variable (throws if missing)\nconst dbUrl = env.require('DATABASE_URL')\n\n// Get all loaded values\nconsole.log(env.all())\n\n// Parse a .env string manually\nconst parsed = env.parse('KEY=value\\nFOO=bar')\n\n// Reset loaded state\nenv.reset()",
+    "methods": [
+      { "method": "env(key)", "signature": "env(key) | env.KEY", "description": "Get an environment variable. Proxy-based — use either function call or property access." },
+      { "method": "env.load", "signature": "env.load([schema], [opts])", "description": "Load .env files, apply schema validation & type coercion. opts: { path, override }." },
+      { "method": "env.get", "signature": "env.get(key)", "description": "Get a variable from the loaded store or process.env." },
+      { "method": "env.require", "signature": "env.require(key)", "description": "Get a variable; throws if missing or empty." },
+      { "method": "env.has", "signature": "env.has(key)", "description": "Check if a variable exists. Returns boolean." },
+      { "method": "env.all", "signature": "env.all()", "description": "Return a shallow copy of all loaded variables." },
+      { "method": "env.reset", "signature": "env.reset()", "description": "Clear the loaded store and schema. Useful for testing." },
+      { "method": "env.parse", "signature": "env.parse(src)", "description": "Parse a .env-format string into a key-value object." }
+    ],
+    "options": [
+      { "option": "path", "type": "string", "default": "process.cwd()", "notes": "Directory to look for .env files." },
+      { "option": "override", "type": "boolean", "default": "false", "notes": "When true, .env values override existing process.env values." }
+    ]
+  },
+  {
+    "name": "Database",
+    "description": "Lightweight ORM entry point. Connect to a database, register models, sync schemas, and run queries. Supports 6 adapters: memory (in-process), json (file-based), sqlite, mysql, postgres, and mongo. All CRUD operations are async and adapter-agnostic.",
+    "example": "const { Database, Model, TYPES } = require('zero-http')\n\n// Define a model\nclass User extends Model {\n\tstatic table = 'users'\n\tstatic timestamps = true    // adds createdAt, updatedAt\n\tstatic softDelete = true    // adds deletedAt, enables restore()\n\tstatic schema = {\n\t\tid:    { type: TYPES.INTEGER, primaryKey: true, autoIncrement: true },\n\t\tname:  { type: TYPES.STRING, required: true, minLength: 2 },\n\t\temail: { type: TYPES.STRING, required: true, unique: true },\n\t\tage:   { type: TYPES.INTEGER, min: 0, max: 150 },\n\t\trole:  { type: TYPES.STRING, enum: ['user', 'admin'], default: 'user' },\n\t\tmeta:  { type: TYPES.JSON, default: {} }\n\t}\n\tstatic hooks = {\n\t\tbeforeCreate: (data) => { data.email = data.email.toLowerCase() },\n\t\tafterCreate: (instance) => console.log('Created:', instance.id)\n\t}\n}\n\n// Connect and sync\nconst db = Database.connect('memory')\ndb.register(User)\nawait db.sync()\n\n// CRUD\nconst user = await User.create({ name: 'Alice', email: 'alice@test.com', age: 30 })\nconst found = await User.findById(user.id)\nawait found.update({ age: 31 })\nawait found.delete()    // soft-delete (sets deletedAt)\nawait found.restore()   // undo soft-delete\n\n// Query builder\nconst admins = await User.query()\n\t.where('role', 'admin')\n\t.where('age', '>=', 18)\n\t.orderBy('name')\n\t.limit(10)\n\t.exec()\n\nconst count = await User.count({ role: 'user' })\n\n// Cleanup\nawait db.drop()\nawait db.close()",
+    "methods": [
+      { "method": "Database.connect", "signature": "Database.connect(type, [opts])", "description": "Static. Connect to a database. type: 'memory', 'json', 'sqlite', 'mysql', 'postgres', 'mongo'. Returns Database instance." },
+      { "method": "db.register", "signature": "db.register(ModelClass)", "description": "Register a Model class with this database. Returns this (chainable)." },
+      { "method": "db.registerAll", "signature": "db.registerAll(...models)", "description": "Register multiple Model classes at once. Returns this (chainable)." },
+      { "method": "db.sync", "signature": "db.sync()", "description": "Async. Create/update tables for all registered models." },
+      { "method": "db.drop", "signature": "db.drop()", "description": "Async. Drop tables for all registered models (reverse order)." },
+      { "method": "db.close", "signature": "db.close()", "description": "Async. Close the database connection." },
+      { "method": "db.model", "signature": "db.model(name)", "description": "Retrieve a registered model class by table name." },
+      { "method": "db.transaction", "signature": "db.transaction(fn)", "description": "Async. Execute callback within a transaction — rolls back on error, commits on success. Adapters without native transactions run the callback directly." }
+    ],
+    "options": [
+      { "option": "type", "type": "string", "default": "—", "notes": "Adapter type: 'memory' | 'json' | 'sqlite' | 'mysql' | 'postgres' | 'mongo'." },
+      { "option": "path", "type": "string", "default": "—", "notes": "File path for 'json' adapter." },
+      { "option": "filename", "type": "string", "default": "—", "notes": "Database file for 'sqlite' adapter." },
+      { "option": "host", "type": "string", "default": "—", "notes": "Hostname for mysql/postgres/mongo." },
+      { "option": "port", "type": "number", "default": "—", "notes": "Port for mysql/postgres/mongo." },
+      { "option": "database", "type": "string", "default": "—", "notes": "Database name for mysql/postgres/mongo." },
+      { "option": "user / password", "type": "string", "default": "—", "notes": "Auth credentials for mysql/postgres/mongo." }
+    ]
+  },
+  {
+    "name": "Model",
+    "description": "Base class for ORM models. Extend it to define your schema, table, timestamps, soft-deletes, hooks, scopes, hidden fields, and relationships. Provides static CRUD, upsert, exists, scoped queries, instance lifecycle methods, increment/decrement, a fluent query builder, and eager-loading including many-to-many.",
+    "example": "const { Model, TYPES } = require('zero-http')\n\nclass Post extends Model {\n\tstatic table = 'posts'\n\tstatic timestamps = true\n\tstatic hidden = ['internalNotes']  // excluded from toJSON()\n\tstatic scopes = {\n\t\tpublished: q => q.where('status', 'published'),\n\t\tbyAuthor: (q, id) => q.where('authorId', id)\n\t}\n\tstatic schema = {\n\t\tid:      { type: TYPES.INTEGER, primaryKey: true, autoIncrement: true },\n\t\ttitle:   { type: TYPES.STRING, required: true },\n\t\tbody:    { type: TYPES.TEXT },\n\t\tauthorId:{ type: TYPES.INTEGER, required: true },\n\t\tstatus:  { type: TYPES.STRING, enum: ['draft', 'published'], default: 'draft' },\n\t\tviews:   { type: TYPES.INTEGER, default: 0 },\n\t\tinternalNotes: { type: TYPES.TEXT }\n\t}\n}\n\n// Relationships\nUser.hasMany(Post, 'authorId')\nPost.belongsTo(User, 'authorId')\nPost.belongsToMany(Tag, { through: 'post_tags', foreignKey: 'postId', otherKey: 'tagId' })\n\n// Scoped queries\nconst published = await Post.scope('published')\nconst mine = await Post.scope('byAuthor', userId).scope('published')\n\n// Upsert + Exists\nconst { instance, created } = await Post.upsert({ title: 'Hello' }, { body: '...' })\nif (await Post.exists({ title: 'Hello' })) { ... }\n\n// Increment / Decrement\nawait post.increment('views')\nawait post.decrement('stock', 5)\n\n// Hidden fields\npost.toJSON() // internalNotes excluded",
+    "methods": [
+      { "method": "Model.create", "signature": "Model.create(data)", "description": "Async. Insert a record and return a Model instance." },
+      { "method": "Model.createMany", "signature": "Model.createMany(dataArray)", "description": "Async. Insert multiple records. Returns array of Model instances." },
+      { "method": "Model.find", "signature": "Model.find([conditions])", "description": "Async. Find all matching records. No conditions = find all." },
+      { "method": "Model.findOne", "signature": "Model.findOne(conditions)", "description": "Async. Find the first matching record or null." },
+      { "method": "Model.findById", "signature": "Model.findById(id)", "description": "Async. Find by primary key or null." },
+      { "method": "Model.findOrCreate", "signature": "Model.findOrCreate(conditions, [defaults])", "description": "Async. Find or create. Returns { instance, created: boolean }." },
+      { "method": "Model.upsert", "signature": "Model.upsert(conditions, data)", "description": "Async. Insert or update — finds by conditions, updates if exists, creates otherwise. Returns { instance, created: boolean }." },
+      { "method": "Model.exists", "signature": "Model.exists([conditions])", "description": "Async. Returns true if any matching records exist." },
+      { "method": "Model.updateWhere", "signature": "Model.updateWhere(conditions, data)", "description": "Async. Bulk update matching records. Returns affected count." },
+      { "method": "Model.deleteWhere", "signature": "Model.deleteWhere(conditions)", "description": "Async. Bulk delete matching records. Returns affected count." },
+      { "method": "Model.count", "signature": "Model.count([conditions])", "description": "Async. Count matching records." },
+      { "method": "Model.query", "signature": "Model.query()", "description": "Returns a Query builder for fluent querying." },
+      { "method": "Model.scope", "signature": "Model.scope(name, [...args])", "description": "Start a query with a named scope applied. Scopes are defined in static scopes = {}." },
+      { "method": "Model.first", "signature": "Model.first([conditions])", "description": "Async. Find the first record. Returns Promise<Model|null>." },
+      { "method": "Model.last", "signature": "Model.last([conditions])", "description": "Async. Find the last record (by PK descending). Returns Promise<Model|null>." },
+      { "method": "Model.all", "signature": "Model.all([conditions])", "description": "Async. Get all records (alias for find). Returns Promise<Model[]>." },
+      { "method": "Model.paginate", "signature": "Model.paginate(page, [perPage], [conditions])", "description": "Async. Rich pagination: returns { data, total, page, perPage, pages, hasNext, hasPrev }." },
+      { "method": "Model.chunk", "signature": "Model.chunk(size, fn, [conditions])", "description": "Async. Process all records in batches. fn(batch, batchIndex) — supports async." },
+      { "method": "Model.random", "signature": "Model.random([conditions])", "description": "Async. Get a random record. Returns Promise<Model|null>." },
+      { "method": "Model.pluck", "signature": "Model.pluck(field, [conditions])", "description": "Async. Pluck values for a single column. Returns Promise<Array>." },
+      { "method": "Model.hasMany", "signature": "Model.hasMany(RelatedModel, foreignKey, [localKey])", "description": "Define a one-to-many relationship." },
+      { "method": "Model.hasOne", "signature": "Model.hasOne(RelatedModel, foreignKey, [localKey])", "description": "Define a one-to-one relationship." },
+      { "method": "Model.belongsTo", "signature": "Model.belongsTo(RelatedModel, foreignKey, [otherKey])", "description": "Define an inverse one-to-one/many relationship." },
+      { "method": "Model.belongsToMany", "signature": "Model.belongsToMany(RelatedModel, opts)", "description": "Define a many-to-many relationship via junction table. opts: { through, foreignKey, otherKey, localKey, relatedKey }." },
+      { "method": "instance.save", "signature": "instance.save()", "description": "Async. Insert or update the record (upsert)." },
+      { "method": "instance.update", "signature": "instance.update(data)", "description": "Async. Update specific fields. Returns this." },
+      { "method": "instance.delete", "signature": "instance.delete()", "description": "Async. Delete the record (soft-delete if enabled)." },
+      { "method": "instance.restore", "signature": "instance.restore()", "description": "Async. Restore a soft-deleted record. Returns this." },
+      { "method": "instance.reload", "signature": "instance.reload()", "description": "Async. Re-fetch the record from the database. Returns this." },
+      { "method": "instance.increment", "signature": "instance.increment(field, [by=1])", "description": "Async. Increment a numeric field. Updates DB and instance." },
+      { "method": "instance.decrement", "signature": "instance.decrement(field, [by=1])", "description": "Async. Decrement a numeric field. Updates DB and instance." },
+      { "method": "instance.toJSON", "signature": "instance.toJSON()", "description": "Return a plain object copy of the record. Respects static hidden = [] to exclude sensitive fields." },
+      { "method": "instance.load", "signature": "instance.load(relationName)", "description": "Async. Eager-load a related model or collection. Supports hasMany, hasOne, belongsTo, and belongsToMany." }
+    ],
+    "options": [
+      { "option": "table", "type": "string", "default": "''", "notes": "Static property. Database table name." },
+      { "option": "schema", "type": "object", "default": "{}", "notes": "Static property. Column definitions with type, constraints, and defaults." },
+      { "option": "timestamps", "type": "boolean", "default": "false", "notes": "Static property. Automatically add createdAt / updatedAt columns." },
+      { "option": "softDelete", "type": "boolean", "default": "false", "notes": "Static property. Add deletedAt column; delete() sets it instead of removing." },
+      { "option": "hooks", "type": "object", "default": "{}", "notes": "Static property. Lifecycle hooks: beforeCreate, afterCreate, beforeUpdate, afterUpdate, beforeDelete, afterDelete." },
+      { "option": "hidden", "type": "string[]", "default": "[]", "notes": "Static property. Fields excluded from toJSON() — e.g. ['password', 'resetToken']." },
+      { "option": "scopes", "type": "object", "default": "{}", "notes": "Static property. Named query scopes — functions that receive a Query and return it. Called via Model.scope(name, ...args)." }
+    ]
+  },
+  {
+    "name": "Query",
+    "description": "Fluent query builder returned by Model.query(). All filter/sort/limit methods are chainable. Execute with .exec(), .first(), .count(), .exists(), .pluck(), or aggregates. Also thenable — you can await the query directly.",
+    "example": "const { Model, TYPES } = require('zero-http')\n\n// Fluent query building\nconst results = await User.query()\n\t.select('id', 'name', 'email')\n\t.where('role', 'admin')\n\t.where('age', '>=', 21)\n\t.orWhere('role', 'superadmin')\n\t.whereNotNull('email')\n\t.whereIn('status', ['active', 'pending'])\n\t.whereNotIn('role', ['banned'])\n\t.whereLike('name', '%alice%')\n\t.orderBy('name', 'asc')\n\t.limit(25)\n\t.offset(50)\n\t.exec()\n\n// Pagination\nconst page2 = await User.query()\n\t.where('role', 'user')\n\t.orderBy('createdAt', 'desc')\n\t.page(2, 20)   // page 2, 20 per page\n\t.exec()\n\n// Aggregation\nconst total = await User.query().where('role', 'admin').count()\nconst avgAge = await User.query().avg('age')\nconst maxPrice = await Product.query().max('price')\nconst minPrice = await Product.query().min('price')\nconst revenue = await Order.query().sum('total')\n\n// Existence + Pluck\nconst hasAdmins = await User.query().where('role', 'admin').exists()\nconst emails = await User.query().pluck('email') // ['a@b.com', ...]\n\n// Scoped queries (chained)\nconst active = await User.query().scope('active').scope('verified').limit(10)\n\n// Get first match\nconst oldest = await User.query().orderBy('age', 'desc').first()\n\n// Include soft-deleted records\nconst all = await User.query().withDeleted().exec()\n\n// Distinct + group by\nconst roles = await User.query().select('role').distinct().groupBy('role').exec()\n\n// Thenable — await directly\nconst users = await User.query().where('active', true)",
+    "methods": [
+      { "method": "select", "signature": "select(...fields)", "description": "Select specific columns. Chainable." },
+      { "method": "distinct", "signature": "distinct()", "description": "Return unique rows only. Chainable." },
+      { "method": "where", "signature": "where(field, [op], value)", "description": "Add a WHERE condition. Supports object form, (field, value), or (field, op, value). Operators: =, !=, >, <, >=, <=, LIKE, IN, NOT IN, BETWEEN, IS NULL, IS NOT NULL." },
+      { "method": "orWhere", "signature": "orWhere(field, [op], value)", "description": "Add an OR WHERE condition. Chainable." },
+      { "method": "whereNull", "signature": "whereNull(field)", "description": "WHERE field IS NULL. Chainable." },
+      { "method": "whereNotNull", "signature": "whereNotNull(field)", "description": "WHERE field IS NOT NULL. Chainable." },
+      { "method": "whereIn", "signature": "whereIn(field, values)", "description": "WHERE field IN (...values). Chainable." },
+      { "method": "whereNotIn", "signature": "whereNotIn(field, values)", "description": "WHERE field NOT IN (...values). Chainable." },
+      { "method": "whereBetween", "signature": "whereBetween(field, low, high)", "description": "WHERE field BETWEEN low AND high. Chainable." },
+      { "method": "whereNotBetween", "signature": "whereNotBetween(field, low, high)", "description": "WHERE field NOT BETWEEN low AND high. Chainable." },
+      { "method": "whereLike", "signature": "whereLike(field, pattern)", "description": "WHERE field LIKE pattern (% and _ wildcards). Chainable." },
+      { "method": "orderBy", "signature": "orderBy(field, [dir])", "description": "Sort results. dir: 'asc' (default) or 'desc'. Chainable." },
+      { "method": "limit", "signature": "limit(n)", "description": "Maximum number of results. Chainable." },
+      { "method": "offset", "signature": "offset(n)", "description": "Skip n records. Chainable." },
+      { "method": "page", "signature": "page(pageNum, [perPage])", "description": "Pagination helper. 1-indexed. perPage defaults to 20. Chainable." },
+      { "method": "groupBy", "signature": "groupBy(...fields)", "description": "Group results by columns. Chainable." },
+      { "method": "having", "signature": "having(field, [op], value)", "description": "Add a HAVING condition (use with groupBy). Chainable." },
+      { "method": "join", "signature": "join(table, localKey, foreignKey)", "description": "INNER JOIN. Chainable." },
+      { "method": "leftJoin", "signature": "leftJoin(table, localKey, foreignKey)", "description": "LEFT JOIN. Chainable." },
+      { "method": "rightJoin", "signature": "rightJoin(table, localKey, foreignKey)", "description": "RIGHT JOIN. Chainable." },
+      { "method": "withDeleted", "signature": "withDeleted()", "description": "Include soft-deleted records in results. Chainable." },
+      { "method": "scope", "signature": "scope(name, [...args])", "description": "Apply a named scope from the model's static scopes. Chainable." },
+      { "method": "exec", "signature": "exec()", "description": "Execute the query. Returns Promise<Model[]>." },
+      { "method": "first", "signature": "first()", "description": "Execute and return the first result. Returns Promise<Model|null>." },
+      { "method": "count", "signature": "count()", "description": "Execute and return the count. Returns Promise<number>." },
+      { "method": "exists", "signature": "exists()", "description": "Returns Promise<boolean> — true if any matching records exist." },
+      { "method": "pluck", "signature": "pluck(field)", "description": "Returns Promise<Array> of values for a single column." },
+      { "method": "sum", "signature": "sum(field)", "description": "Returns Promise<number> — sum of a numeric column." },
+      { "method": "avg", "signature": "avg(field)", "description": "Returns Promise<number> — average of a numeric column." },
+      { "method": "min", "signature": "min(field)", "description": "Returns Promise<*> — minimum value of a column." },
+      { "method": "max", "signature": "max(field)", "description": "Returns Promise<*> — maximum value of a column." },
+      { "method": "take", "signature": "take(n)", "description": "Alias for limit() — LINQ naming. Chainable." },
+      { "method": "skip", "signature": "skip(n)", "description": "Alias for offset() — LINQ naming. Chainable." },
+      { "method": "toArray", "signature": "toArray()", "description": "Alias for exec() — returns Promise<Model[]>." },
+      { "method": "orderByDesc", "signature": "orderByDesc(field)", "description": "Shorthand for orderBy(field, 'desc'). Chainable." },
+      { "method": "last", "signature": "last()", "description": "Execute and return the last result. Returns Promise<Model|null>." },
+      { "method": "when", "signature": "when(condition, fn)", "description": "Conditionally apply query logic if condition is truthy. Chainable." },
+      { "method": "unless", "signature": "unless(condition, fn)", "description": "Conditionally apply query logic if condition is falsy. Chainable." },
+      { "method": "tap", "signature": "tap(fn)", "description": "Inspect the query for debugging without breaking the chain. Chainable." },
+      { "method": "chunk", "signature": "chunk(size, fn)", "description": "Process results in batches. Calls fn(batch, batchIndex) for each chunk." },
+      { "method": "each", "signature": "each(fn)", "description": "Execute and iterate each result. fn(item, index) — supports async." },
+      { "method": "map", "signature": "map(fn)", "description": "Execute, transform each result. Returns Promise<Array>." },
+      { "method": "filter", "signature": "filter(fn)", "description": "Execute, post-filter results in JS. Returns Promise<Model[]>." },
+      { "method": "reduce", "signature": "reduce(fn, initial)", "description": "Execute and reduce results to a single value." },
+      { "method": "paginate", "signature": "paginate(page, [perPage])", "description": "Rich pagination: returns { data, total, page, perPage, pages, hasNext, hasPrev }." },
+      { "method": "whereRaw", "signature": "whereRaw(sql, ...params)", "description": "Inject raw SQL WHERE clause (SQL adapters only). Parameterized. Chainable." }
+    ],
+    "options": []
+  },
+  {
+    "name": "TYPES",
+    "description": "Column type constants for ORM schema definitions. Use these instead of raw strings for type safety and IDE autocomplete.",
+    "example": "const { TYPES } = require('zero-http')\n\nconst schema = {\n\tid:        { type: TYPES.INTEGER, primaryKey: true, autoIncrement: true },\n\tname:      { type: TYPES.STRING, required: true },\n\tbio:       { type: TYPES.TEXT },\n\tprice:     { type: TYPES.FLOAT, min: 0 },\n\tactive:    { type: TYPES.BOOLEAN, default: true },\n\tcreated:   { type: TYPES.DATE },\n\tupdated:   { type: TYPES.DATETIME },\n\tmeta:      { type: TYPES.JSON, default: {} },\n\tavatar:    { type: TYPES.BLOB },\n\texternalId:{ type: TYPES.UUID }\n}",
+    "methods": [
+      { "method": "TYPES.STRING", "signature": "'string'", "description": "Text column (varchar equivalent)." },
+      { "method": "TYPES.INTEGER", "signature": "'integer'", "description": "Integer column." },
+      { "method": "TYPES.FLOAT", "signature": "'float'", "description": "Floating-point number column." },
+      { "method": "TYPES.BOOLEAN", "signature": "'boolean'", "description": "Boolean column." },
+      { "method": "TYPES.DATE", "signature": "'date'", "description": "Date-only column." },
+      { "method": "TYPES.DATETIME", "signature": "'datetime'", "description": "Date+time column." },
+      { "method": "TYPES.JSON", "signature": "'json'", "description": "JSON column (stored as serialized object)." },
+      { "method": "TYPES.TEXT", "signature": "'text'", "description": "Long text column (no length limit)." },
+      { "method": "TYPES.BLOB", "signature": "'blob'", "description": "Binary data column." },
+      { "method": "TYPES.UUID", "signature": "'uuid'", "description": "UUID string column." }
+    ],
+    "options": []
+  },
   {
     "name": "compress([opts])",
-    "description": "Response compression middleware using brotli, gzip, or deflate based on the client's Accept-Encoding header. Brotli is preferred when available (Node \u2265 11.7). Automatically negotiates encoding, respects threshold, skips SSE streams, and supports a filter function to skip specific requests.",
-    "example": "const { createApp, compress } = require('zero-http')\nconst app = createApp()\n\n// Compress responses over 512 bytes (brotli > gzip > deflate)\napp.use(compress({ threshold: 512, level: 6 }))\n\n// Skip compression for specific routes\napp.use(compress({\n\tfilter: (req, res) => !req.url.startsWith('/stream')\n}))\n\napp.get('/big', (req, res) => {\n\tres.json({ data: 'x'.repeat(10000) })\n})",
+    "description": "Response compression middleware using brotli, gzip, or deflate based on the client's Accept-Encoding header. Brotli is preferred when available (Node ≥ 11.7). Automatically negotiates encoding, respects threshold, skips SSE streams, and supports a filter function to skip specific requests.",
+    "example": "const { createApp, compress, json } = require('zero-http')\nconst app = createApp()\n\n// Compress responses over 512 bytes (brotli > gzip > deflate)\napp.use(compress({ threshold: 512, level: 6 }))\n\n// Skip compression for specific routes\napp.use(compress({\n\tfilter: (req, res) => !req.url.startsWith('/stream')\n}))\n\napp.get('/big', (req, res) => {\n\tres.json({ data: 'x'.repeat(10000) })\n})",
     "methods": [],
     "options": [
       { "option": "threshold", "type": "number", "default": "1024", "notes": "Minimum response body size in bytes before compression is applied." },
@@ -272,7 +584,9 @@
       { "option": "max", "type": "number", "default": "100", "notes": "Maximum requests per window per key." },
       { "option": "statusCode", "type": "number", "default": "429", "notes": "HTTP status code for rate-limited responses." },
       { "option": "message", "type": "string", "default": "Too many requests, please try again later.", "notes": "Error message returned in the JSON response body when limit is exceeded." },
-      { "option": "keyGenerator", "type": "function", "default": "(req) => req.ip || 'unknown'", "notes": "Custom function to extract a rate-limit key from the request." }
+      { "option": "keyGenerator", "type": "function", "default": "(req) => req.ip || 'unknown'", "notes": "Custom function to extract a rate-limit key from the request." },
+      { "option": "skip", "type": "function", "default": "—", "notes": "(req) => boolean. Return true to skip rate limiting for the request." },
+      { "option": "handler", "type": "function", "default": "—", "notes": "(req, res) => void. Custom handler for rate-limited requests instead of the default JSON response." }
     ]
   },
   {
@@ -284,5 +598,71 @@
       { "option": "logger", "type": "function", "default": "console.log", "notes": "Custom log output function." },
       { "option": "colors", "type": "boolean", "default": "auto (TTY detection)", "notes": "Enable or disable ANSI color codes. Auto-detected from process.stdout.isTTY." }
     ]
+  },
+  {
+    "name": "Error Classes",
+    "description": "Built-in HTTP error classes with status codes, machine-readable codes, and optional details. Every error extends HttpError which carries statusCode, code, and details. Throw them in route handlers — the router catches and sends the correct HTTP response automatically.",
+    "example": "const { NotFoundError, ValidationError, createError, isHttpError, HttpError } = require('zero-http')\n\n// Throw in route handlers — automatically caught\napp.get('/users/:id', async (req, res) => {\n\tconst user = await User.findById(req.params.id)\n\tif (!user) throw new NotFoundError('User not found')\n\tres.json(user)\n})\n\n// Validation with field-level errors\napp.post('/users', async (req, res) => {\n\tconst errors = {}\n\tif (!req.body.email) errors.email = 'required'\n\tif (!req.body.name) errors.name = 'required'\n\tif (Object.keys(errors).length > 0) {\n\t\tthrow new ValidationError('Invalid input', errors)\n\t}\n\tres.json(await User.create(req.body))\n})\n\n// Factory — create by status code\nthrow createError(409, 'Duplicate entry', { details: { id: 42 } })\n\n// Type checking\nif (isHttpError(err)) {\n\tres.status(err.statusCode).json(err.toJSON())\n}",
+    "methods": [
+      { "method": "HttpError", "signature": "new HttpError(statusCode, [message], [opts])", "description": "Base class. opts: { code, details }." },
+      { "method": "BadRequestError", "signature": "new BadRequestError([message], [opts])", "description": "400 Bad Request." },
+      { "method": "UnauthorizedError", "signature": "new UnauthorizedError([message], [opts])", "description": "401 Unauthorized." },
+      { "method": "ForbiddenError", "signature": "new ForbiddenError([message], [opts])", "description": "403 Forbidden." },
+      { "method": "NotFoundError", "signature": "new NotFoundError([message], [opts])", "description": "404 Not Found." },
+      { "method": "MethodNotAllowedError", "signature": "new MethodNotAllowedError([message], [opts])", "description": "405 Method Not Allowed." },
+      { "method": "ConflictError", "signature": "new ConflictError([message], [opts])", "description": "409 Conflict." },
+      { "method": "GoneError", "signature": "new GoneError([message], [opts])", "description": "410 Gone." },
+      { "method": "PayloadTooLargeError", "signature": "new PayloadTooLargeError([message], [opts])", "description": "413 Payload Too Large." },
+      { "method": "UnprocessableEntityError", "signature": "new UnprocessableEntityError([message], [opts])", "description": "422 Unprocessable Entity." },
+      { "method": "ValidationError", "signature": "new ValidationError([message], [errors], [opts])", "description": "422 with field-level errors. errors stored in .errors and .details." },
+      { "method": "TooManyRequestsError", "signature": "new TooManyRequestsError([message], [opts])", "description": "429 Too Many Requests." },
+      { "method": "InternalError", "signature": "new InternalError([message], [opts])", "description": "500 Internal Server Error." },
+      { "method": "NotImplementedError", "signature": "new NotImplementedError([message], [opts])", "description": "501 Not Implemented." },
+      { "method": "BadGatewayError", "signature": "new BadGatewayError([message], [opts])", "description": "502 Bad Gateway." },
+      { "method": "ServiceUnavailableError", "signature": "new ServiceUnavailableError([message], [opts])", "description": "503 Service Unavailable." },
+      { "method": "createError", "signature": "createError(statusCode, [message], [opts])", "description": "Factory — creates the correct error class for any status code." },
+      { "method": "isHttpError", "signature": "isHttpError(err)", "description": "Returns true if err is an HttpError or has a statusCode. Type guard." },
+      { "method": "toJSON", "signature": "err.toJSON()", "description": "Serialize: { error, code, statusCode, details? }." }
+    ],
+    "options": []
+  },
+  {
+    "name": "errorHandler([opts])",
+    "description": "Configurable error-handling middleware. Formats error responses based on environment (dev vs production), includes stack traces in dev, hides internal details in production, and supports custom formatters and logging. Use with app.onError().",
+    "example": "const { createApp, errorHandler } = require('zero-http')\nconst app = createApp()\n\n// Basic — dev mode with stack traces\napp.onError(errorHandler())\n\n// Production — hide internals\napp.onError(errorHandler({ stack: false }))\n\n// Custom formatter + error monitoring\napp.onError(errorHandler({\n\tformatter: (err, req, isDev) => ({\n\t\tsuccess: false,\n\t\tmessage: err.message,\n\t\t...(isDev && { stack: err.stack })\n\t}),\n\tonError: (err, req) => {\n\t\terrorTracker.capture(err, { url: req.url })\n\t}\n}))",
+    "methods": [],
+    "options": [
+      { "option": "stack", "type": "boolean", "default": "true (non-production)", "notes": "Include stack traces in responses. Auto-detected from NODE_ENV." },
+      { "option": "log", "type": "boolean", "default": "true", "notes": "Log errors to console." },
+      { "option": "logger", "type": "function", "default": "console.error", "notes": "Custom log function." },
+      { "option": "formatter", "type": "function", "default": "—", "notes": "Custom response formatter: (err, req, isDev) => responseBody." },
+      { "option": "onError", "type": "function", "default": "—", "notes": "Callback on every error: (err, req, res) => void." }
+    ]
+  },
+  {
+    "name": "debug(namespace)",
+    "description": "Lightweight namespaced debug logger with levels, colors, and timestamps. Enable via DEBUG env var or programmatically. Each namespace gets a unique color. Supports text and structured JSON output.",
+    "example": "const { debug } = require('zero-http')\n\nconst log = debug('app:routes')\nconst dbLog = debug('db:queries')\n\nlog.info('server started on port %d', 3000)\nlog.warn('deprecated endpoint hit: %s', req.url)\nlog.error('request failed', err)\n\n// JSON mode for log aggregators\ndebug.json(true)\ndebug.level('info')\n\n// Enable specific namespaces\ndebug.enable('app:*,db:*')\n// DEBUG=app:* node server.js",
+    "methods": [
+      { "method": "debug(namespace)", "signature": "debug('app:routes')", "description": "Create a namespaced logger. Returns a function with level methods." },
+      { "method": "log()", "signature": "log(...args)", "description": "Log at debug level. Supports %s, %d, %j, %o format specifiers." },
+      { "method": "log.trace()", "signature": "log.trace(...args)", "description": "Log at trace level (most verbose)." },
+      { "method": "log.info()", "signature": "log.info(...args)", "description": "Log at info level." },
+      { "method": "log.warn()", "signature": "log.warn(...args)", "description": "Log at warn level." },
+      { "method": "log.error()", "signature": "log.error(...args)", "description": "Log at error level." },
+      { "method": "log.fatal()", "signature": "log.fatal(...args)", "description": "Log at fatal level (most severe)." },
+      { "method": "debug.level()", "signature": "debug.level('info')", "description": "Set minimum log level globally." },
+      { "method": "debug.enable()", "signature": "debug.enable('app:*')", "description": "Enable namespaces by pattern." },
+      { "method": "debug.disable()", "signature": "debug.disable()", "description": "Disable all debug output." },
+      { "method": "debug.json()", "signature": "debug.json(true)", "description": "Enable structured JSON output." },
+      { "method": "debug.timestamps()", "signature": "debug.timestamps(false)", "description": "Toggle timestamps." },
+      { "method": "debug.colors()", "signature": "debug.colors(false)", "description": "Toggle ANSI colors." },
+      { "method": "debug.output()", "signature": "debug.output(stream)", "description": "Set custom output stream." },
+      { "method": "debug.reset()", "signature": "debug.reset()", "description": "Reset all settings to defaults." }
+    ],
+    "options": [
+      { "option": "DEBUG", "type": "env var", "default": "—", "notes": "Comma-separated namespace patterns. Supports * glob and - prefix to exclude." },
+      { "option": "DEBUG_LEVEL", "type": "env var", "default": "debug", "notes": "Minimum log level: trace, debug, info, warn, error, fatal, silent." }
+    ]
   }
 ]