te.js 2.0.1 → 2.1.0

package/README.md

@@ -41,12 +41,13 @@ api.register('/hello/:name', (ammo) => {
 app.takeoff();
 ```
 
+
 ## Features
 
 - **AI-Native (MCP)** — Ship with an MCP server so AI assistants can scaffold projects, generate routes, and write correct code with full framework knowledge
 - **Simple Routing** — Clean, method-agnostic URL structures with parameterized routes
 - **Express Compatible** — Use existing Express middleware alongside Tejas middleware
-- **Zero-Config Error Handling** — No try-catch needed! Tejas catches all errors automatically
+- **Zero-Config Error Handling** — No try-catch needed! Tejas catches all errors automatically. Opt in to have an LLM determine error code and message when you don't specify them (see [Error Handling](./docs/error-handling.md))
 - **Built-in Rate Limiting** — Three algorithms (Token Bucket, Sliding Window, Fixed Window) with memory or Redis storage
 - **Database Ready** — First-class Redis and MongoDB support with auto-install of drivers
 - **File Uploads** — Easy file handling with size limits and type validation
@@ -55,6 +56,7 @@ app.takeoff();
 - **Auto-Discovery** — Automatic route registration from `.target.js` files
 - **Request Logging** — Built-in HTTP request and exception logging
 
+
 ## AI-Assisted Setup (MCP)
 
 > **Recommended** — The best way to get started with Tejas in the age of AI.
@@ -78,6 +80,7 @@ The [Tejas MCP server](https://www.npmjs.com/package/tejas-mcp) gives your IDE's
 
 Once connected, prompt your AI with things like *"Scaffold a new te.js project called my-api"* or *"Create a REST API with user CRUD routes"* — the assistant will generate framework-correct code using real te.js patterns.
 
+
 ## Quick Start
 
 ### Install
@@ -128,6 +131,7 @@ node index.js
 # Server running at http://localhost:3000
 ```
 
+
 ## Core Concepts
 
 | Tejas Term  | Purpose                  | Express Equivalent |
@@ -139,6 +143,7 @@ node index.js
 | `midair()`  | Register middleware      | `use()`            |
 | `takeoff()` | Start server             | `listen()`         |
 
+
 ## CLI
 
 ```bash
@@ -147,6 +152,7 @@ tejas generate:docs [--ci]   # Generate OpenAPI docs (interactive or CI mode)
 tejas docs:on-push           # Auto-generate docs when pushing to production branch
 ```
 
+
 ## API Documentation
 
 Generate and serve interactive API docs:
@@ -161,6 +167,7 @@ app.takeoff();
 // Visit http://localhost:1403/docs
 ```
 
+
 ## Documentation
 
 For comprehensive documentation, see the [docs folder](./docs) or visit [tejas-documentation.vercel.app](https://tejas-documentation.vercel.app).
@@ -178,10 +185,12 @@ For comprehensive documentation, see the [docs folder](./docs) or visit [tejas-d
 - [Auto-Documentation](./docs/auto-docs.md) — OpenAPI generation
 - [API Reference](./docs/api-reference.md) — Complete API docs
 
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+
 ## License
 
 ISC © [Hirak Chhatbar](https://github.com/hirakchhatbar)

package/auto-docs/docs-llm/index.js

@@ -0,0 +1,7 @@
+/**
+ * LLM provider for auto-documentation (docs-specific).
+ * Use createProvider(config) with baseURL, apiKey, model.
+ * For the generic LLM client only, use lib/llm.
+ */
+
+export { LLMProvider, createProvider, extractJSON, extractJSONArray, reconcileOrderedTags } from './provider.js';

package/auto-docs/{llm → docs-llm}/provider.js

@@ -1,10 +1,9 @@
 /**
- * LLM provider for auto-documentation: single OpenAI-compatible implementation.
- * Works with OpenAI, OpenRouter, Ollama (OpenAI-compatible endpoint), Azure, etc.
- * Uses fetch() only — no provider-specific npm dependencies.
+ * LLM provider for auto-documentation: extends shared lib/llm client with doc-specific methods.
+ * Single OpenAI-compatible implementation; works with OpenAI, OpenRouter, Ollama, Azure, etc.
  */
 
-import { extractJSON, extractJSONArray, reconcileOrderedTags } from './parse.js';
+import { LLMProvider as BaseLLMProvider, extractJSON, extractJSONArray, reconcileOrderedTags } from '../../lib/llm/index.js';
 import {
   buildSummarizeGroupPrompt,
   buildEnhanceEndpointPrompt,
@@ -13,59 +12,10 @@ import {
   buildOverviewPrompt,
 } from './prompts.js';
 
-const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
-const DEFAULT_MODEL = 'gpt-4o-mini';
-
 /**
- * OpenAI-compatible LLM provider. POSTs to {baseURL}/chat/completions.
+ * Docs-specific LLM provider: base analyze() from lib/llm plus summarizeTargetGroup, enhanceEndpointDocs, etc.
  */
-class LLMProvider {
-  constructor(options = {}) {
-    this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, '');
-    this.model = options.model ?? DEFAULT_MODEL;
-    this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
-    this.options = options;
-  }
-
-  /**
-   * Send a prompt to the LLM and return the raw text response.
-   * @param {string} prompt
-   * @returns {Promise<string>}
-   */
-  async analyze(prompt) {
-    const url = `${this.baseURL}/chat/completions`;
-    const headers = {
-      'Content-Type': 'application/json',
-      ...(this.apiKey && { Authorization: `Bearer ${this.apiKey}` }),
-    };
-    const body = {
-      model: this.model,
-      messages: [{ role: 'user', content: prompt }],
-    };
-
-    const res = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(body),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`LLM request failed (${res.status}): ${text.slice(0, 300)}`);
-    }
-
-    const data = await res.json();
-    const content = data.choices?.[0]?.message?.content ?? '';
-    const text = typeof content === 'string' ? content : JSON.stringify(content);
-    const rawUsage = data.usage;
-    const usage = {
-      prompt_tokens: rawUsage?.prompt_tokens ?? 0,
-      completion_tokens: rawUsage?.completion_tokens ?? 0,
-      total_tokens: rawUsage?.total_tokens ?? (rawUsage?.prompt_tokens ?? 0) + (rawUsage?.completion_tokens ?? 0),
-    };
-    return { content: text, usage };
-  }
-
+class DocsLLMProvider extends BaseLLMProvider {
   /**
    * Summarize what a target file (group) does from its endpoints and handler context.
    * @param {string} groupId - Group id (e.g. target file path without .target.js)
@@ -166,22 +116,17 @@ class LLMProvider {
 }
 
 /**
- * Create an LLM provider from config.
- * Single OpenAI-compatible setup: works with OpenAI, OpenRouter, Ollama (compat), Azure, etc.
- *
+ * Create a docs-specific LLM provider from config (same config shape as lib/llm).
  * @param {object} config - { baseURL?, apiKey?, model? }
- *   - baseURL: e.g. 'https://api.openai.com/v1' | 'https://openrouter.ai/api/v1' | 'http://localhost:11434/v1'
- *   - apiKey: optional for local (e.g. Ollama); use OPENAI_API_KEY or OPENROUTER_API_KEY
- *   - model: e.g. 'gpt-4o-mini' | 'openai/gpt-4o-mini' (OpenRouter)
- * @returns {LLMProvider}
+ * @returns {DocsLLMProvider}
  */
 function createProvider(config) {
   if (!config || typeof config !== 'object') {
-    return new LLMProvider({});
+    return new DocsLLMProvider({});
   }
-  return new LLMProvider(config);
+  return new DocsLLMProvider(config);
 }
 
-export { LLMProvider, createProvider };
-export { extractJSON, extractJSONArray } from './parse.js';
-export default LLMProvider;
+export { DocsLLMProvider as LLMProvider, createProvider };
+export { extractJSON, extractJSONArray, reconcileOrderedTags } from '../../lib/llm/index.js';
+export default DocsLLMProvider;

package/auto-docs/index.js

@@ -7,13 +7,13 @@
  * - openapi/level3.js — level-3 pipeline: reorder tags by importance, generate and write overview page
  * - analysis/handler-analyzer.js — detect HTTP methods from handler source
  * - analysis/source-resolver.js — resolve target file and dependencies (for level 2 context)
- * - llm/ — LLM provider (enhanceEndpointDocs, summarizeTargetGroup, reorderTagsByImportance, generateOverviewPage)
+ * - docs-llm/ — Docs-specific LLM provider (enhanceEndpointDocs, summarizeTargetGroup, reorderTagsByImportance, generateOverviewPage)
  * - ui/docs-ui.js — build Scalar docs HTML, registerDocRoutes
  */
 
 import { writeFile } from 'node:fs/promises';
 import TejLogger from 'tej-logger';
-import { createProvider } from './llm/index.js';
+import { createProvider } from './docs-llm/index.js';
 import { generateOpenAPISpec } from './openapi/generator.js';
 import { runLevel3 } from './openapi/level3.js';
 import targetRegistry from '../server/targets/registry.js';
@@ -141,6 +141,6 @@ export async function generateDocs(registry = targetRegistry, options = {}) {
 }
 
 export { generateOpenAPISpec } from './openapi/generator.js';
-export { createProvider } from './llm/index.js';
+export { createProvider } from './docs-llm/index.js';
 export { buildDocsPage } from './ui/docs-ui.js';
 export { analyzeHandler, detectMethods } from './analysis/handler-analyzer.js';

package/docs/ammo.md

@@ -138,33 +138,34 @@ After `fire()` is called, the sent data is available as `ammo.dispatchedData`.
 
 ### throw() — Send Error Response
 
-For intentional error responses:
+**One mechanism** for error responses: you don't log the error and send the response separately — `ammo.throw()` takes care of everything. The framework uses the same `ammo.throw()` when it catches an error, so one config, one behaviour. For intentional errors, call `ammo.throw()` (or pass an error); when [LLM-inferred errors](./error-handling.md#llm-inferred-errors) are enabled, call with no arguments and an LLM infers status and message from code context. Explicit code/message always override. See [Error Handling](./error-handling.md) and per-call options (e.g. `messageType`).
 
 ```javascript
-// Send 500 Internal Server Error
-ammo.throw();
-
-// Send specific error code
+// Explicit: status code and/or message
 ammo.throw(404);
 ammo.throw(404, 'User not found');
+ammo.throw(new TejError(400, 'Invalid input'));
 
-// Throw from Error object
-ammo.throw(new Error('Something went wrong'));
+// When errors.llm.enabled: no args — LLM infers from code context (surrounding + upstream/downstream)
+ammo.throw();
 
-// Throw TejError
-import { TejError } from 'te.js';
-throw new TejError(400, 'Invalid input');
+// Optional: pass caught error for secondary signal; LLM still uses code context (error stack) as primary
+ammo.throw(caughtErr);
+
+// Per-call: skip LLM or override message type
+ammo.throw({ useLlm: false });
+ammo.throw({ messageType: 'developer' });
 ```
 
 **All `throw()` signatures:**
 
 | Call | Status | Message |
 |------|--------|---------|
-| `throw()` | 500 | `"Internal Server Error"` |
+| `throw()` | 500 or LLM-inferred | Default or LLM-derived from **code context** (see [LLM-inferred errors](./error-handling.md#llm-inferred-errors)) |
 | `throw(404)` | 404 | Default message for that status code |
 | `throw(404, "msg")` | 404 | `"msg"` |
 | `throw(new TejError(code, msg))` | `code` | `msg` |
-| `throw(new Error("msg"))` | 500 | `"msg"` (or parses numeric messages as status codes) |
+| `throw(error)` (optional) | LLM-inferred | LLM-derived from code context (error stack used to find call site) |
 
 > **Note:** You don't need try-catch blocks in your handlers! Tejas automatically catches all errors and converts them to appropriate HTTP responses. Use `throw()` or `TejError` only for intentional, expected error conditions. See [Error Handling](./error-handling.md) for details.
 
@@ -359,4 +360,3 @@ target.register('/profile', authMiddleware, (ammo) => {
   });
 });
 ```
-

package/docs/api-reference.md

@@ -263,15 +263,16 @@ Send a response to the client.
 
 #### throw()
 
-Send an error response.
+Send an error response. When [LLM-inferred errors](./error-handling.md#llm-inferred-errors) are enabled (`errors.llm.enabled`), calls without explicit status code or message use an LLM to infer code and message; explicit code/message always override.
 
 | Signature | Behavior |
 |-----------|----------|
-| `throw()` | 500 "Internal Server Error" |
+| `throw()` | 500 "Internal Server Error" (or LLM-inferred when `errors.llm.enabled`) |
 | `throw(404)` | 404 with default status message |
 | `throw(404, "msg")` | 404 with custom message |
 | `throw(new TejError(code, msg))` | Uses TejError's code and message |
-| `throw(new Error("msg"))` | 500 with error message |
+| `throw(new Error("msg"))` | 500 with error message, or LLM-inferred when `errors.llm.enabled` |
+| LLM-inferred (no explicit code/message, `errors.llm.enabled`) | Status and message derived by LLM from context |
 
 #### redirect(url, statusCode)
 
@@ -307,7 +308,7 @@ Sends the default Tejas HTML entry page. Used internally for the root `/` route
 
 ## TejError Class
 
-Custom error class for HTTP errors.
+Custom error class for HTTP errors. Use it when you want to set the response explicitly; both status code and message are optional when errors are passed through `ammo.throw()` with [LLM-inferred errors](./error-handling.md#llm-inferred-errors) enabled (the LLM can infer them).
 
 ```javascript
 import { TejError } from 'te.js';
@@ -317,8 +318,8 @@ throw new TejError(statusCode, message);
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `statusCode` | number | HTTP status code |
-| `message` | string | Error message |
+| `statusCode` | number | HTTP status code (optional when LLM infers; otherwise use for override) |
+| `message` | string | Error message (optional when LLM infers; otherwise use for override) |
 
 | Property | Type | Description |
 |----------|------|-------------|

package/docs/auto-docs.md

@@ -213,3 +213,4 @@ npx tejas generate:docs
 - [CLI Reference](./cli.md) — Detailed CLI command documentation
 - [Configuration](./configuration.md) — Full framework configuration reference
 - [Routing](./routing.md) — Learn about endpoint metadata
+

package/docs/configuration.md

@@ -66,9 +66,13 @@ app.takeoff();
 | `body.max_size` | `BODY_MAX_SIZE` | number | `10485760` (10 MB) | Maximum request body size in bytes. Requests exceeding this receive a 413 error |
 | `body.timeout` | `BODY_TIMEOUT` | number | `30000` (30 s) | Body parsing timeout in milliseconds. Requests exceeding this receive a 408 error |
 
+### LLM configuration (feature as parent, LLM inside each feature)
+
+Tejas uses a **feature-as-parent** pattern: each feature that needs an LLM has its own `*.llm` block (`docs.llm` for auto-documentation, `errors.llm` for LLM-inferred errors). **Inheritance from `LLM_*`:** unset feature-specific values fall back to `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL`. One set of `LLM_*` env vars can serve both features when you don't override with `DOCS_LLM_*` or `ERRORS_LLM_*`. You can also use different LLMs per feature (e.g. a lighter model for errors, a stronger one for docs).
+
 ### Auto-Documentation
 
-These options configure the `tejas generate:docs` CLI command and the auto-documentation system. See [Auto-Documentation](./auto-docs.md) for full details.
+These options configure the `tejas generate:docs` CLI command and the auto-documentation system. The **`docs.llm`** block is the LLM configuration for this feature. See [Auto-Documentation](./auto-docs.md) for full details.
 
 | Config Key | Env Variable | Type | Default | Description |
 |------------|-------------|------|---------|-------------|
@@ -78,12 +82,26 @@ These options configure the `tejas generate:docs` CLI command and the auto-docum
 | `docs.version` | — | string | `"1.0.0"` | API version in the OpenAPI `info` block |
 | `docs.description` | — | string | `""` | API description |
 | `docs.level` | — | number | `1` | LLM enhancement level (1–3). Higher = better docs, more tokens |
-| `docs.llm.baseURL` | `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint |
-| `docs.llm.apiKey` | `LLM_API_KEY` | string | — | LLM provider API key |
-| `docs.llm.model` | `LLM_MODEL` | string | `"gpt-4o-mini"` | LLM model name |
+| `docs.llm.baseURL` | `DOCS_LLM_BASE_URL` or `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint for auto-docs |
+| `docs.llm.apiKey` | `DOCS_LLM_API_KEY` or `LLM_API_KEY` | string | — | LLM provider API key for auto-docs |
+| `docs.llm.model` | `DOCS_LLM_MODEL` or `LLM_MODEL` | string | `"gpt-4o-mini"` | LLM model for auto-docs |
 | `docs.overviewPath` | — | string | `"./API_OVERVIEW.md"` | Path for the generated overview page (level 3 only) |
 | `docs.productionBranch` | `DOCS_PRODUCTION_BRANCH` | string | `"main"` | Git branch that triggers `docs:on-push` |
 
+### Error handling (LLM-inferred errors)
+
+When [LLM-inferred error codes and messages](./error-handling.md#llm-inferred-errors) are enabled, the **`errors.llm`** block configures the LLM used for inferring status code and message when you call `ammo.throw()` without explicit code or message. Unset values fall back to `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL`. You can also enable (and optionally set connection options) by calling **`app.withLLMErrors(config?)`** before `takeoff()` — e.g. `app.withLLMErrors()` to use env/config for baseURL, apiKey, model, or `app.withLLMErrors({ baseURL, apiKey, model, messageType })` to override in code.
+
+| Config Key | Env Variable | Type | Default | Description |
+|------------|-------------|------|---------|-------------|
+| `errors.llm.enabled` | `ERRORS_LLM_ENABLED` or `LLM_*` (for connection) | boolean | `false` | Enable LLM-inferred error code and message for `ammo.throw()` |
+| `errors.llm.baseURL` | `ERRORS_LLM_BASE_URL` or `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint for error inference |
+| `errors.llm.apiKey` | `ERRORS_LLM_API_KEY` or `LLM_API_KEY` | string | — | LLM provider API key for error inference |
+| `errors.llm.model` | `ERRORS_LLM_MODEL` or `LLM_MODEL` | string | `"gpt-4o-mini"` | LLM model for error inference |
+| `errors.llm.messageType` | `ERRORS_LLM_MESSAGE_TYPE` or `LLM_MESSAGE_TYPE` | `"endUser"` \| `"developer"` | `"endUser"` | Default tone for LLM-generated message: `endUser` (safe for clients) or `developer` (technical detail). Overridable per `ammo.throw()` call. |
+
+When enabled, the same behaviour applies whether you call `ammo.throw()` or the framework calls it when it catches an error — one mechanism, no separate config.
+
 ## Configuration File
 
 Create a `tejas.config.json` in your project root:
@@ -108,7 +126,19 @@ Create a `tejas.config.json` in your project root:
     "title": "My API",
     "version": "1.0.0",
     "level": 2,
-    "productionBranch": "main"
+    "productionBranch": "main",
+    "llm": {
+      "baseURL": "https://api.openai.com/v1",
+      "model": "gpt-4o-mini"
+    }
+  },
+  "errors": {
+    "llm": {
+      "enabled": true,
+      "baseURL": "https://api.openai.com/v1",
+      "model": "gpt-4o-mini",
+      "messageType": "endUser"
+    }
   }
 }
 ```
@@ -132,10 +162,22 @@ BODY_TIMEOUT=15000
 # Target directory
 DIR_TARGETS=targets
 
-# LLM (for tejas generate:docs)
+# LLM — shared fallback for docs.llm and errors.llm when feature-specific vars are unset
 LLM_BASE_URL=https://api.openai.com/v1
 LLM_API_KEY=sk-...
 LLM_MODEL=gpt-4o-mini
+
+# Optional: override per feature (docs.llm)
+# DOCS_LLM_BASE_URL=...
+# DOCS_LLM_API_KEY=...
+# DOCS_LLM_MODEL=...
+
+# Optional: override for error-inference (errors.llm)
+# ERRORS_LLM_ENABLED=true
+# ERRORS_LLM_BASE_URL=...
+# ERRORS_LLM_API_KEY=...
+# ERRORS_LLM_MODEL=...
+# ERRORS_LLM_MESSAGE_TYPE=endUser   # or "developer" for technical messages
 ```
 
 ## Constructor Options

package/docs/database.md

@@ -388,4 +388,3 @@ process.on('SIGTERM', async () => {
   process.exit(0);
 });
 ```
-

package/docs/error-handling.md

@@ -1,6 +1,6 @@
 # Error Handling
 
-Tejas provides robust error handling to keep your application running even when unexpected errors occur.
+Tejas keeps your application from crashing on unhandled errors. You don't log the error and send the response separately — **`ammo.throw()` is the single mechanism**: it sends the appropriate HTTP response (logging is optional via `log.exceptions`). Whether you call `ammo.throw()` or the framework calls it when it catches an error, the same behaviour applies. When LLM-inferred errors are enabled, call `ammo.throw()` with no arguments and an LLM infers status and message from code context; explicit code and message always override.
 
 ## Zero-Config Error Handling
 
@@ -8,13 +8,7 @@ Tejas provides robust error handling to keep your application running even when
 
 ### How It Works
 
-Tejas wraps all middleware and route handlers with built-in error catching. Any error thrown in your code is automatically:
-
-1. **Caught** by the framework's error handler
-2. **Logged** (if exception logging is enabled)
-3. **Converted** to an appropriate HTTP error response
-
-This means your application **never crashes** from unhandled exceptions, and clients always receive proper error responses.
+Tejas wraps all middleware and route handlers with built-in error catching. Any error thrown in your code is automatically passed to `ammo.throw(err)` — the same mechanism you use for intentional errors. So: one place handles everything (response + optional logging via `log.exceptions`). No separate "log then send response"; your app never crashes and clients always receive a proper response.
 
 ### Write Clean Code Without Try-Catch
 
@@ -27,25 +21,24 @@ target.register('/users/:id', async (ammo) => {
 });
 ```
 
-Compare this to traditional frameworks where you'd need:
+In other frameworks you typically **log the error and then send the response** (two separate steps). With Tejas, **`ammo.throw()` does both** — and when the framework catches an error it uses the same `ammo.throw()`, so you never define them separately:
 
 ```javascript
-// ❌ Traditional approach requires manual error handling
+// ❌ Traditional: log then send response (two separate things)
 app.get('/users/:id', async (req, res) => {
   try {
     const user = await database.findUser(req.params.id);
-    const posts = await database.getUserPosts(user.id);
-    res.json({ user, posts });
+    res.json(user);
   } catch (error) {
-    console.error(error);
-    res.status(500).json({ error: 'Internal Server Error' });
+    console.error(error);           // 1. log
+    res.status(500).json({ error: 'Internal Server Error' });  // 2. send response
   }
 });
 ```
 
 ### Automatic Error Responses
 
-When an unhandled error occurs, Tejas automatically sends a `500 Internal Server Error` response. For intentional errors using `TejError`, the appropriate status code is used.
+When an unhandled error occurs, the framework calls `ammo.throw(err)` — the same method you use for intentional errors. So one mechanism: explicit `ammo.throw()` or framework-caught, both go through `ammo.throw()`. When [LLM-inferred errors](#llm-inferred-errors) are enabled, status and message are inferred from code context; otherwise or when you pass explicit code/message, those are used.
 
 ### Enable Error Logging
 
@@ -60,26 +53,54 @@ const app = new Tejas({
 ```
 
 Or via environment variable:
+
 ```bash
 LOG_EXCEPTIONS=true
 ```
 
 ---
 
+## LLM-Inferred Errors
+
+When **`errors.llm.enabled`** is true and you call `ammo.throw()` without an explicit status code or message, Tejas uses an LLM to infer an appropriate HTTP status code and message from **code context** — you do not pass an error object. The framework captures the code surrounding the `ammo.throw()` call (with line numbers) and all **upstream** (callers) and **downstream** (code that would have run next) context, and the LLM infers what went wrong from that. Explicit code and message always override.
+
+- **No error object required:** Call `ammo.throw()` with no arguments (or only options). The LLM receives the source code around the call site and upstream call stacks so it can infer status and message from control flow and intent.
+- **Opt-in:** Enable via config: `errors.llm.enabled: true` and configure `errors.llm` (baseURL, apiKey, model), or call **`app.withLLMErrors()`** / **`app.withLLMErrors({ baseURL, apiKey, model, messageType })`** before `takeoff()`. See [Configuration](./configuration.md#error-handling-llm-inferred-errors).
+- **Framework-caught errors:** When the framework catches an unhandled error (in a handler or middleware), it uses the same `ammo.throw(err)` — so the same `errors.llm` config applies. No separate "log then send response"; one mechanism handles everything.
+- **Override:** Whenever you pass a status code or message (e.g. `ammo.throw(404, 'User not found')` or `throw new TejError(404, 'User not found')`), that value is used; the LLM is not called.
+- **Message type:** Configure whether the LLM generates **end-user-friendly** or **developer-friendly** messages via `errors.llm.messageType`; override per call (see [Per-call overrides](#per-call-overrides)).
+- **Non-production:** In non-production, the LLM can also provide developer insight (e.g. bug vs environment, suggested fix), attached to the response as `_dev` or in logs only — never in production.
+
+### Per-call overrides
+
+For any LLM-eligible `ammo.throw()` call (no explicit status code), you can pass an options object as the last argument to override behaviour for that call only:
+
+- **`useLlm`** (boolean): Set to `false` to skip the LLM for this call and respond with a default 500 / "Internal Server Error" (or the error's message when you pass an Error/string). Set to `true` to force using the LLM (same as default when eligible).
+- **`messageType`** (`"endUser"` | `"developer"`): Override the configured default for this call — request an end-user-friendly or developer-friendly message.
+
+```javascript
+// Skip LLM for this call; send 500
+ammo.throw({ useLlm: false });
+
+// Request a developer-friendly message for this call only
+ammo.throw({ messageType: 'developer' });
+
+// When an error was caught and passed in, you can still pass options
+ammo.throw(caughtErr, { useLlm: false });
+```
+
+---
+
 ## TejError Class
 
-Use `TejError` for throwing HTTP errors with status codes:
+Use `TejError` for throwing HTTP errors with status codes. Both status code and message are **optional** when [LLM-inferred errors](#llm-inferred-errors) are enabled and the error is passed through `ammo.throw()`; otherwise, supply them to set the response explicitly.
 
 ```javascript
 import { TejError } from 'te.js';
 
-// Throw a 404 error
+// Explicit code and message (always used as override)
 throw new TejError(404, 'User not found');
-
-// Throw a 400 error
 throw new TejError(400, 'Invalid email format');
-
-// Throw a 500 error
 throw new TejError(500, 'Database connection failed');
 ```
 
@@ -116,22 +137,22 @@ ammo.unauthorized();
 
 ## Using ammo.throw()
 
-For more control, use `ammo.throw()`:
+For more control, use `ammo.throw()`. When [LLM-inferred errors](#llm-inferred-errors) are enabled, you can omit code and message and the LLM will infer them; otherwise, or when you want to override, pass them explicitly.
 
 ```javascript
-// Just status code (uses default message)
+// Explicit: status code and/or message
 ammo.throw(404);
-
-// Status code with message
 ammo.throw(404, 'User not found');
+ammo.throw(new TejError(400, 'Bad request'));
 
-// Error object
+// When errors.llm.enabled: LLM infers code and message from context
 ammo.throw(new Error('Something went wrong'));
-
-// TejError
-ammo.throw(new TejError(400, 'Bad request'));
+ammo.throw('Validation failed');
+ammo.throw();  // context still used when available
 ```
 
+See [Ammo — throw()](./ammo.md#throw--send-error-response) for all signatures and the LLM-inferred row.
+
 ## Error Handling in Routes
 
 ### Basic Pattern
@@ -375,15 +396,15 @@ Supported content types:
 
 ## Error Flow
 
-When any error occurs in your handler or middleware, this is what happens internally:
+When any error occurs in your handler or middleware, the framework uses the **same** `ammo.throw(err)` you use for intentional errors — one mechanism:
 
 1. The framework's `executeChain()` catches the error
 2. If `LOG_EXCEPTIONS` is enabled, the error is logged
-3. The error is passed to `ammo.throw()`:
-   - **TejError** — uses the error's `code` and `message` directly
-   - **Standard Error** — returns 500 with the error message
-   - **Anything else** — returns 500 with a string representation
-4. `ammo.throw()` calls `ammo.fire(statusCode, message)` to send the HTTP response
+3. The error is passed to `ammo.throw(err)` (no separate "send response" step — `ammo.throw()` does it)
+4. **TejError** — uses the error's `code` and `message` directly
+5. **When errors.llm.enabled** — LLM infers status and message from code context (same as explicit `ammo.throw()`)
+6. **Otherwise** — 500 with the error message or string representation
+7. `ammo.throw()` sends the HTTP response via `ammo.fire(statusCode, message)`
 
 Once a response has been sent (`res.headersSent` is true), no further middleware or handlers execute.
 
@@ -413,5 +434,5 @@ Once a response has been sent (`res.headersSent` is true), no further middleware
 4. **Log errors** — Enable exception logging for debugging
 5. **Be consistent** — Use the same error format throughout your API
 6. **Validate early** — Check input before processing
-7. **Use TejError** — For HTTP-specific errors with status codes
-
+7. **Use TejError or ammo.throw(code, message)** — For HTTP-specific errors when you want explicit control
+8. **Opt in to LLM-inferred errors when helpful** — Enable via `errors.llm.enabled` in config or **`app.withLLMErrors(config?)`** before `takeoff()`, then configure baseURL, apiKey, and model so you can throw without specifying code or message and let the LLM infer them; see [Configuration](./configuration.md#error-handling-llm-inferred-errors)

package/docs/file-uploads.md

@@ -331,4 +331,3 @@ target.register('/images/:filename', (ammo) => {
 4. **Store outside web root** — For sensitive files, store in private directories
 5. **Clean up on errors** — Delete uploaded files if validation fails
 6. **Scan for malware** — For production systems, integrate virus scanning
-

package/docs/getting-started.md

@@ -212,4 +212,3 @@ api.register('/echo', (ammo) => {
   }
 });
 ```
-

package/docs/middleware.md

@@ -353,4 +353,3 @@ target.register('/expensive', cache(300), (ammo) => {
 4. **Use factories** — For configurable middleware
 5. **Order matters** — Place authentication before authorization
 6. **Don't mutate payload directly** — Add new properties instead
-

package/docs/rate-limiting.md

@@ -391,4 +391,3 @@ The built-in backends (`MemoryStorage` and `RedisStorage`) both extend this base
 5. **Provide clear error messages** — Tell users when they can retry
 6. **Consider user tiers** — Premium users may need higher limits
 7. **Monitor and adjust** — Track rate limit hits and adjust accordingly
-

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "te.js",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A nodejs framework",
   "type": "module",
   "main": "te.js",
   "bin": {
-    "tejas": "./cli/index.js"
+    "tejas": "cli/index.js"
   },
   "scripts": {
     "start": "node te.js",
@@ -25,8 +25,19 @@
   },
   "repository": {
     "type": "git",
-    "url": "git@github.com:hirakchhatbar/te.js.git"
+    "url": "git+ssh://git@github.com/hirakchhatbar/te.js.git"
   },
+  "files": [
+    "te.js",
+    "cli",
+    "server",
+    "database",
+    "rate-limit",
+    "utils",
+    "auto-docs",
+    "README.md",
+    "docs"
+  ],
   "dependencies": {
     "ansi-colors": "^4.1.3",
     "filesize": "^10.1.1",