claude-brain 0.5.1 → 0.9.0

package/VERSION

@@ -1 +1 @@
-0.5.1
+0.9.0

package/assets/CLAUDE-unified.md

@@ -0,0 +1,11 @@
+# Claude Brain
+
+Call `brain()` with what you are doing. The server handles the rest.
+
+Examples:
+- brain("starting work on the auth system")
+- brain("decided to use JWT because sessions don't scale")
+- brain("finished the login page, next is the dashboard")
+- brain("what auth patterns have we used?")
+- brain("the bug was a race condition, fixed by adding a mutex")
+- brain("React vs Vue for the new project?")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.5.1",
+  "version": "0.9.0",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",
@@ -9,6 +9,7 @@
   },
   "files": [
     "src/**/*.ts",
+    "packs/",
     "assets/",
     "package.json",
     "tsconfig.json",
@@ -44,6 +45,9 @@
   ],
   "author": "",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^20",

package/packs/backend/node.json

@@ -0,0 +1,173 @@
+{
+  "id": "backend/node",
+  "name": "Node.js Backend Patterns",
+  "version": "1.0.0",
+  "stack": ["node", "express", "fastify", "hono", "nestjs", "elysia", "bun"],
+  "description": "Error handling, streams, worker threads, security, graceful shutdown, and server patterns",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "best-practice",
+      "category": "Error Handling",
+      "title": "Centralize error handling middleware",
+      "content": "Use a centralized error handling middleware/handler instead of try/catch in every route. Map error types to HTTP status codes. Log the full error server-side but return safe messages to clients.",
+      "confidence": 0.95,
+      "tags": ["node", "error-handling", "middleware"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Error Handling",
+      "title": "Handle unhandled rejections and exceptions",
+      "content": "Always register handlers for 'uncaughtException' and 'unhandledRejection' process events. Log the error and perform graceful shutdown. These are last-resort safety nets.",
+      "confidence": 0.95,
+      "tags": ["node", "error-handling", "process"],
+      "example": "process.on('unhandledRejection', (reason) => { logger.fatal({ reason }, 'Unhandled rejection'); shutdown(); })"
+    },
+    {
+      "type": "pattern",
+      "category": "Graceful Shutdown",
+      "title": "Implement graceful shutdown",
+      "content": "Handle SIGTERM and SIGINT signals to gracefully shut down. Stop accepting new connections, finish in-flight requests, close database connections, then exit. This prevents data corruption during deployments.",
+      "confidence": 0.95,
+      "tags": ["node", "shutdown", "deployment"],
+      "example": "process.on('SIGTERM', async () => { await server.close(); await db.close(); process.exit(0); })"
+    },
+    {
+      "type": "best-practice",
+      "category": "Security",
+      "title": "Validate all input at system boundaries",
+      "content": "Validate and sanitize all external input (request body, query params, headers) at the API boundary using a schema validation library (Zod, Joi, AJV). Never trust client data.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "validation"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Security",
+      "title": "Never expose internal errors to clients",
+      "content": "Don't send stack traces, database errors, or internal paths to API clients. Map all errors to safe, generic messages with appropriate HTTP status codes. Log the full error server-side only.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "error-handling"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Security",
+      "title": "Use parameterized queries for databases",
+      "content": "Always use parameterized queries or an ORM for database operations. Never concatenate user input into SQL strings. This prevents SQL injection, the most critical web vulnerability.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "sql-injection", "database"]
+    },
+    {
+      "type": "pattern",
+      "category": "Architecture",
+      "title": "Separate route handlers from business logic",
+      "content": "Keep route handlers thin — they should parse input, call service functions, and format responses. Business logic belongs in service modules that are independently testable and reusable.",
+      "confidence": 0.9,
+      "tags": ["node", "architecture", "separation-of-concerns"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Logging",
+      "title": "Use structured logging with levels",
+      "content": "Use a structured logger (pino, winston) that outputs JSON. Include request IDs, timestamps, and context. Use log levels (debug, info, warn, error, fatal) consistently.",
+      "confidence": 0.9,
+      "tags": ["node", "logging", "observability"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Performance",
+      "title": "Don't block the event loop",
+      "content": "Avoid synchronous operations (readFileSync, crypto, JSON.parse on large data) in request handlers. Use async alternatives, worker threads, or break work into chunks with setImmediate.",
+      "confidence": 0.95,
+      "tags": ["node", "performance", "event-loop"]
+    },
+    {
+      "type": "pattern",
+      "category": "Streams",
+      "title": "Use streams for large data processing",
+      "content": "Process large files, HTTP bodies, and datasets with streams instead of loading everything into memory. Pipe readable to writable streams. Use pipeline() for proper error handling.",
+      "confidence": 0.9,
+      "tags": ["node", "streams", "performance"],
+      "example": "import { pipeline } from 'stream/promises';\nawait pipeline(readStream, transform, writeStream);"
+    },
+    {
+      "type": "best-practice",
+      "category": "Configuration",
+      "title": "Use environment variables for configuration",
+      "content": "Load configuration from environment variables, not hardcoded values. Use a library (dotenv, env-schema) to validate env vars at startup. Fail fast if required configuration is missing.",
+      "confidence": 0.9,
+      "tags": ["node", "configuration", "environment"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Security",
+      "title": "Never store secrets in code or git",
+      "content": "Don't commit API keys, database passwords, or tokens to version control. Use environment variables, secret management services (Vault, AWS Secrets Manager), or .env files in .gitignore.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "secrets"]
+    },
+    {
+      "type": "best-practice",
+      "category": "API Design",
+      "title": "Use proper HTTP status codes",
+      "content": "Return semantically correct HTTP status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 500 (Server Error).",
+      "confidence": 0.9,
+      "tags": ["node", "api", "http", "rest"]
+    },
+    {
+      "type": "pattern",
+      "category": "Middleware",
+      "title": "Use middleware for cross-cutting concerns",
+      "content": "Implement authentication, rate limiting, request logging, CORS, and compression as middleware. This keeps route handlers focused on business logic and makes concerns reusable.",
+      "confidence": 0.9,
+      "tags": ["node", "middleware", "architecture"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Performance",
+      "title": "Implement connection pooling for databases",
+      "content": "Always use connection pooling for database connections. Creating a new connection per request is slow and exhausts database limits. Most ORMs and drivers support pooling out of the box.",
+      "confidence": 0.9,
+      "tags": ["node", "database", "performance", "connection-pooling"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Security",
+      "title": "Set appropriate security headers",
+      "content": "Use helmet or set security headers manually: Content-Security-Policy, X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options. These prevent common web attacks.",
+      "confidence": 0.9,
+      "tags": ["node", "security", "headers"]
+    },
+    {
+      "type": "pattern",
+      "category": "Testing",
+      "title": "Use dependency injection for testability",
+      "content": "Pass dependencies (database, logger, external services) as constructor/function parameters instead of importing singletons. This enables easy mocking in tests and flexible composition.",
+      "confidence": 0.85,
+      "tags": ["node", "testing", "dependency-injection"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Error Handling",
+      "title": "Avoid empty catch blocks",
+      "content": "Never swallow errors silently with empty catch blocks. At minimum, log the error. Silently ignoring errors makes debugging impossible and can mask serious issues.",
+      "confidence": 0.95,
+      "tags": ["node", "error-handling"]
+    },
+    {
+      "type": "best-practice",
+      "category": "API Design",
+      "title": "Implement request rate limiting",
+      "content": "Add rate limiting to protect against abuse and DDoS. Use token bucket or sliding window algorithms. Apply stricter limits to authentication endpoints. Return 429 Too Many Requests.",
+      "confidence": 0.9,
+      "tags": ["node", "security", "rate-limiting", "api"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Memory",
+      "title": "Watch for memory leaks in long-running processes",
+      "content": "Node.js servers can leak memory through event listeners, caches without size limits, closures holding references, and global arrays. Monitor heap usage and use WeakMap/WeakRef where appropriate.",
+      "confidence": 0.85,
+      "tags": ["node", "memory", "performance", "debugging"]
+    }
+  ]
+}

package/packs/core/javascript.json

@@ -0,0 +1,176 @@
+{
+  "id": "core/javascript",
+  "name": "JavaScript Fundamentals",
+  "version": "1.0.0",
+  "stack": ["javascript"],
+  "description": "Closures, event loop, async patterns, modern ES features, and coercion pitfalls",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "best-practice",
+      "category": "Async Patterns",
+      "title": "Use async/await over raw promises",
+      "content": "Prefer async/await over .then() chains for readability and debuggability. Async/await produces clearer stack traces and is easier to reason about for error handling with try/catch.",
+      "confidence": 0.95,
+      "tags": ["javascript", "async", "promises"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Async Patterns",
+      "title": "Avoid unhandled promise rejections",
+      "content": "Always handle promise rejections with try/catch in async functions or .catch() on promises. Unhandled rejections can crash Node.js processes and cause silent failures in browsers.",
+      "confidence": 0.95,
+      "tags": ["javascript", "async", "error-handling"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Async Patterns",
+      "title": "Avoid sequential awaits for independent operations",
+      "content": "Don't await independent async operations sequentially. Use Promise.all() or Promise.allSettled() to run them concurrently. Sequential awaits waste time waiting for operations that could run in parallel.",
+      "confidence": 0.9,
+      "tags": ["javascript", "async", "performance"],
+      "example": "const [users, posts] = await Promise.all([fetchUsers(), fetchPosts()])"
+    },
+    {
+      "type": "best-practice",
+      "category": "Modern ES",
+      "title": "Use destructuring for cleaner code",
+      "content": "Use destructuring assignment for objects and arrays to extract values concisely. This reduces intermediate variables and makes function parameter expectations clearer.",
+      "confidence": 0.9,
+      "tags": ["javascript", "es6", "destructuring"],
+      "example": "const { name, age } = user; const [first, ...rest] = items;"
+    },
+    {
+      "type": "best-practice",
+      "category": "Modern ES",
+      "title": "Prefer const, use let sparingly, avoid var",
+      "content": "Use `const` by default for all bindings. Only use `let` when reassignment is necessary. Never use `var` — it has function scoping and hoisting that causes bugs.",
+      "confidence": 0.95,
+      "tags": ["javascript", "variables", "scoping"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Closures",
+      "title": "Understand closure variable capture",
+      "content": "Closures capture variables by reference, not by value. In loops, use `let` (block-scoped) instead of `var` to ensure each iteration gets its own copy. Arrow functions in loops with `var` all share the same variable.",
+      "confidence": 0.9,
+      "tags": ["javascript", "closures", "scoping"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Event Loop",
+      "title": "Understand microtask vs macrotask ordering",
+      "content": "Promise callbacks (microtasks) run before setTimeout/setInterval callbacks (macrotasks). This matters for operation ordering. process.nextTick runs before all other microtasks in Node.js.",
+      "confidence": 0.85,
+      "tags": ["javascript", "event-loop", "async"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Coercion",
+      "title": "Avoid loose equality (==)",
+      "content": "Always use strict equality (===) to avoid JavaScript's type coercion rules. Loose equality has unintuitive results like `'' == 0` being true and `null == undefined` being true.",
+      "confidence": 0.95,
+      "tags": ["javascript", "equality", "coercion"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Modern ES",
+      "title": "Use optional chaining and nullish coalescing",
+      "content": "Use `?.` for safe property access on potentially null/undefined values. Use `??` for default values (only triggers on null/undefined, unlike `||` which triggers on falsy values).",
+      "confidence": 0.9,
+      "tags": ["javascript", "null-safety", "es2020"],
+      "example": "const name = user?.profile?.name ?? 'Anonymous'"
+    },
+    {
+      "type": "pattern",
+      "category": "Error Handling",
+      "title": "Create custom error classes for domain errors",
+      "content": "Extend the Error class for domain-specific errors. Include error codes, HTTP status codes, or other structured data to enable programmatic error handling.",
+      "confidence": 0.85,
+      "tags": ["javascript", "error-handling"],
+      "example": "class NotFoundError extends Error { constructor(resource) { super(`${resource} not found`); this.name = 'NotFoundError'; this.status = 404; } }"
+    },
+    {
+      "type": "best-practice",
+      "category": "Modern ES",
+      "title": "Use spread operator for immutable updates",
+      "content": "Use the spread operator to create shallow copies when updating objects or arrays. This supports immutable patterns without external libraries.",
+      "confidence": 0.9,
+      "tags": ["javascript", "immutability", "spread"],
+      "example": "const updated = { ...user, name: 'New Name' }"
+    },
+    {
+      "type": "common-issue",
+      "category": "Modern ES",
+      "title": "Understand shallow vs deep copy",
+      "content": "Spread and Object.assign only create shallow copies. Nested objects are still references. Use structuredClone() for deep copies, or libraries like immer for complex immutable updates.",
+      "confidence": 0.9,
+      "tags": ["javascript", "immutability", "deep-copy"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Functions",
+      "title": "Avoid modifying function arguments",
+      "content": "Don't mutate objects or arrays passed as function arguments. This causes action-at-a-distance bugs. Return new values instead of modifying inputs.",
+      "confidence": 0.85,
+      "tags": ["javascript", "functions", "immutability"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Modules",
+      "title": "Use ES modules (import/export)",
+      "content": "Prefer ES modules over CommonJS require(). ESM enables static analysis, tree-shaking, and top-level await. Most modern tools and runtimes support ESM natively.",
+      "confidence": 0.9,
+      "tags": ["javascript", "modules", "esm"]
+    },
+    {
+      "type": "pattern",
+      "category": "Arrays",
+      "title": "Use array methods for data transformations",
+      "content": "Prefer map, filter, reduce, find, and some over imperative loops for data transformations. They're more declarative, composable, and less error-prone.",
+      "confidence": 0.85,
+      "tags": ["javascript", "arrays", "functional"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Coercion",
+      "title": "Be cautious with truthy/falsy checks",
+      "content": "JavaScript has six falsy values: false, 0, '', null, undefined, NaN. Be explicit when checking for null/undefined vs falsy. `if (value)` will miss 0 and empty string.",
+      "confidence": 0.9,
+      "tags": ["javascript", "coercion", "truthiness"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Modern ES",
+      "title": "Use Map and Set for appropriate data structures",
+      "content": "Use Map instead of plain objects when keys are dynamic or non-string. Use Set for unique collections. Both have better performance characteristics and cleaner APIs than object-based alternatives.",
+      "confidence": 0.85,
+      "tags": ["javascript", "data-structures", "es6"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Async Patterns",
+      "title": "Avoid mixing callbacks and promises",
+      "content": "Don't mix callback-style and promise-style async code. Use util.promisify() or write promise wrappers to convert callback APIs. Mixing styles leads to unhandled errors and confusing control flow.",
+      "confidence": 0.9,
+      "tags": ["javascript", "async", "callbacks"]
+    },
+    {
+      "type": "pattern",
+      "category": "Performance",
+      "title": "Use AbortController for cancellable operations",
+      "content": "Use AbortController with AbortSignal for cancellable fetch requests, event listeners, and async operations. This prevents memory leaks from abandoned operations.",
+      "confidence": 0.85,
+      "tags": ["javascript", "performance", "abort"],
+      "example": "const controller = new AbortController(); fetch(url, { signal: controller.signal })"
+    },
+    {
+      "type": "best-practice",
+      "category": "Modern ES",
+      "title": "Use Object.hasOwn over hasOwnProperty",
+      "content": "Use `Object.hasOwn(obj, prop)` instead of `obj.hasOwnProperty(prop)`. It works on objects created with Object.create(null) and is more readable.",
+      "confidence": 0.8,
+      "tags": ["javascript", "es2022", "objects"]
+    }
+  ]
+}

package/packs/core/typescript.json

@@ -0,0 +1,222 @@
+{
+  "id": "core/typescript",
+  "name": "TypeScript Essentials",
+  "version": "1.0.0",
+  "stack": ["typescript"],
+  "description": "Type narrowing, strict mode patterns, generics, enums vs unions, and module best practices",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "best-practice",
+      "category": "Type Safety",
+      "title": "Prefer unknown over any",
+      "content": "Use `unknown` instead of `any` for values of uncertain type. Unlike `any`, `unknown` requires type narrowing before use, catching errors at compile time rather than runtime.",
+      "confidence": 0.95,
+      "tags": ["typescript", "type-safety", "strict-mode"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Safety",
+      "title": "Use discriminated unions for state modeling",
+      "content": "Model mutually exclusive states with discriminated unions using a literal type discriminant. This ensures exhaustive checking and prevents impossible states.",
+      "confidence": 0.95,
+      "tags": ["typescript", "unions", "state-management"],
+      "example": "type Result<T> = { status: 'success'; data: T } | { status: 'error'; error: Error }"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid type assertions as default escape hatch",
+      "content": "Avoid `as` type assertions to silence type errors. They bypass the type checker entirely. Instead, use type guards, narrowing, or fix the underlying type mismatch.",
+      "confidence": 0.9,
+      "tags": ["typescript", "type-safety", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Narrowing",
+      "title": "Use in operator for interface discrimination",
+      "content": "The `in` operator narrows types by checking for property existence. Combined with discriminated unions, it provides type-safe branching without runtime overhead.",
+      "confidence": 0.85,
+      "tags": ["typescript", "narrowing"],
+      "example": "if ('error' in result) { /* result is ErrorResult */ }"
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Narrowing",
+      "title": "Use satisfies for type checking without widening",
+      "content": "The `satisfies` operator validates that an expression matches a type without changing the inferred type. Use it to catch errors while preserving literal types.",
+      "confidence": 0.9,
+      "tags": ["typescript", "satisfies", "type-inference"],
+      "example": "const routes = { home: '/', about: '/about' } satisfies Record<string, string>"
+    },
+    {
+      "type": "pattern",
+      "category": "Generics",
+      "title": "Constrain generics with extends",
+      "content": "Always constrain generic type parameters with `extends` when the function relies on specific properties. This provides better error messages and prevents misuse.",
+      "confidence": 0.9,
+      "tags": ["typescript", "generics"],
+      "example": "function getProperty<T extends object, K extends keyof T>(obj: T, key: K): T[K]"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Generics",
+      "title": "Avoid unnecessary generics",
+      "content": "Don't add generic type parameters that are only used once or don't provide additional type safety. A generic that appears in only the return type without constraining input is usually unnecessary.",
+      "confidence": 0.85,
+      "tags": ["typescript", "generics", "simplicity"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Enums vs Unions",
+      "title": "Prefer const objects or union types over enums",
+      "content": "TypeScript enums generate runtime code and have surprising behaviors (numeric enums allow any number). Prefer `as const` objects with derived union types for better tree-shaking and type inference.",
+      "confidence": 0.9,
+      "tags": ["typescript", "enums", "unions"],
+      "example": "const Status = { Active: 'active', Inactive: 'inactive' } as const;\ntype Status = typeof Status[keyof typeof Status];"
+    },
+    {
+      "type": "common-issue",
+      "category": "Strict Mode",
+      "title": "Enable strict mode in tsconfig.json",
+      "content": "Always enable `strict: true` in tsconfig.json. This enables strictNullChecks, noImplicitAny, strictFunctionTypes, and other checks that catch the majority of type-related bugs.",
+      "confidence": 0.95,
+      "tags": ["typescript", "strict-mode", "configuration"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Strict Mode",
+      "title": "Handle null and undefined explicitly",
+      "content": "With strictNullChecks enabled, use optional chaining (?.), nullish coalescing (??), and explicit null checks. Never use non-null assertions (!) unless you can prove the value exists.",
+      "confidence": 0.9,
+      "tags": ["typescript", "null-safety", "strict-mode"]
+    },
+    {
+      "type": "pattern",
+      "category": "Utility Types",
+      "title": "Use built-in utility types effectively",
+      "content": "TypeScript provides Partial, Required, Pick, Omit, Record, ReturnType, Parameters, and more. Use these instead of manually redefining type transformations.",
+      "confidence": 0.9,
+      "tags": ["typescript", "utility-types"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Modules",
+      "title": "Use type-only imports for types",
+      "content": "Use `import type { ... }` for type-only imports. This ensures the import is erased at compile time, reducing bundle size and preventing circular dependency issues.",
+      "confidence": 0.9,
+      "tags": ["typescript", "modules", "imports"],
+      "example": "import type { Config } from './config'"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid using Function type",
+      "content": "The `Function` type accepts any function regardless of parameters or return type. Use specific function signatures like `(x: number) => string` or `(...args: unknown[]) => unknown`.",
+      "confidence": 0.9,
+      "tags": ["typescript", "type-safety"]
+    },
+    {
+      "type": "pattern",
+      "category": "Error Handling",
+      "title": "Type-safe error handling with instanceof narrowing",
+      "content": "In catch blocks, the error is `unknown`. Use `instanceof Error` to narrow it before accessing `.message` or `.stack`. Create custom error classes for domain-specific errors.",
+      "confidence": 0.9,
+      "tags": ["typescript", "error-handling"],
+      "example": "catch (error) { if (error instanceof Error) { log(error.message) } }"
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Safety",
+      "title": "Use readonly for immutable data",
+      "content": "Mark arrays as `readonly T[]` and objects as `Readonly<T>` when mutation is not intended. This prevents accidental modification and communicates intent clearly.",
+      "confidence": 0.85,
+      "tags": ["typescript", "immutability", "readonly"]
+    },
+    {
+      "type": "pattern",
+      "category": "Type Guards",
+      "title": "Create custom type guard functions",
+      "content": "Use `is` return type annotations to create reusable type guards. These narrow types in conditional branches and can be tested independently.",
+      "confidence": 0.85,
+      "tags": ["typescript", "type-guards", "narrowing"],
+      "example": "function isString(value: unknown): value is string { return typeof value === 'string' }"
+    },
+    {
+      "type": "common-issue",
+      "category": "Async",
+      "title": "Always type async function return values",
+      "content": "Async functions always return a Promise. Explicitly typing the return as `Promise<T>` prevents accidentally returning the wrong type and makes the API contract clear.",
+      "confidence": 0.85,
+      "tags": ["typescript", "async", "promises"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid excessive type casting chains",
+      "content": "If you need `value as unknown as TargetType`, the type system is telling you something is wrong. Fix the underlying type issue instead of casting through unknown.",
+      "confidence": 0.9,
+      "tags": ["typescript", "type-safety", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Configuration",
+      "title": "Use path aliases in tsconfig",
+      "content": "Configure path aliases in tsconfig.json compilerOptions.paths (e.g., `@/` mapping to `src/`) to avoid deep relative imports and make refactoring easier.",
+      "confidence": 0.85,
+      "tags": ["typescript", "configuration", "imports"],
+      "example": "\"paths\": { \"@/*\": [\"src/*\"] }"
+    },
+    {
+      "type": "pattern",
+      "category": "Inference",
+      "title": "Leverage type inference where possible",
+      "content": "Don't annotate types that TypeScript can infer. Over-annotating adds noise without safety. Annotate function parameters, return types of exported functions, and complex objects.",
+      "confidence": 0.85,
+      "tags": ["typescript", "inference", "readability"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Zod Integration",
+      "title": "Use Zod for runtime validation with type inference",
+      "content": "Zod schemas provide both runtime validation and compile-time types via `z.infer<typeof schema>`. Define the schema once and derive the type, keeping them in sync.",
+      "confidence": 0.85,
+      "tags": ["typescript", "zod", "validation"],
+      "example": "const UserSchema = z.object({ name: z.string() });\ntype User = z.infer<typeof UserSchema>;"
+    },
+    {
+      "type": "common-issue",
+      "category": "Modules",
+      "title": "Understand ESM vs CJS module resolution",
+      "content": "TypeScript's module resolution depends on moduleResolution setting. Use 'bundler' or 'nodenext' for modern projects. With ESM, imports require file extensions in output.",
+      "confidence": 0.8,
+      "tags": ["typescript", "modules", "esm", "commonjs"]
+    },
+    {
+      "type": "pattern",
+      "category": "Type Safety",
+      "title": "Use template literal types for string patterns",
+      "content": "Template literal types can enforce string patterns at the type level, like route paths, event names, or ID formats.",
+      "confidence": 0.8,
+      "tags": ["typescript", "template-literals"],
+      "example": "type EventName = `on${Capitalize<string>}`"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid using object type",
+      "content": "The `object` type is too broad — it matches arrays, functions, dates, and any non-primitive. Use `Record<string, unknown>` for key-value objects or define a specific interface.",
+      "confidence": 0.85,
+      "tags": ["typescript", "type-safety"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Error Handling",
+      "title": "Use Result types for expected failures",
+      "content": "For operations that can fail expectedly (validation, parsing), return a discriminated union Result type instead of throwing. Reserve exceptions for unexpected failures.",
+      "confidence": 0.85,
+      "tags": ["typescript", "error-handling", "result-type"],
+      "example": "type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E }"
+    }
+  ]
+}