## Build & Development Commands
- All code must target Node.js LTS (currently 22.14.0) using ESM modules and the `NodeNext` module resolution strategy.
- Use `pnpm` as the package manager. Prefer `pnpm install` and `pnpm dlx` for running and installing tools.
- Ensure all projects include appropriate build scripts, including `"build"`, `"lint"`, `"test"`, and `"typecheck"` commands.
- Projects must be configured to use strict TypeScript settings (`strict: true`, no `any`, no implicit `any`, etc.).

## Testing Guidelines
- Write unit tests for all business logic using Jest. Each test file must achieve high coverage and provide meaningful assertions.
- Use descriptive `describe` and `it/test` block names to clarify test intent.
- Mock external dependencies (e.g., APIs, I/O) cleanly using dependency injection or mocking libraries.
- Avoid integration tests unless explicitly required by context. Keep tests deterministic and fast.
- Always test pure functions thoroughly with edge cases, expected input ranges, and invalid inputs.

## Code Style & Guidelines 
- Always prefer functional programming principles:
  - Use pure functions where possible.
  - Avoid shared mutable state and side effects unless contextually necessary (e.g., logging, metrics, filesystem).
  - Use composition, higher-order functions, and immutability patterns.
- Classes are permitted but only when necessary; ensure they adhere to SOLID principles and encapsulate mutable state carefully.
- Avoid `any` in all forms. Use strict and explicit types for all parameters, return values, and data structures.
- Use ESLint with strict rules enabled. Format all code automatically using Prettier.
- Organize code into small, reusable, and well-named modules. Prefer named exports and maintain one purpose per file.
- Use clear, structured error handling with typed `Error` classes and consistent `throw` statements.
- Isolate side effects into specific files or functions. Never mix I/O logic with core business logic.
- Validate all input and output using schema validators like `zod`, `yup`, or `io-ts`.
- Ask for missing context before proceeding with code generation or review, including related interfaces, file structure, and requirements.

## Documentation Guidelines 
- Include inline comments for any non-obvious logic or complex flows.
- Document public functions, exports, and types using TSDoc or standard JSDoc conventions.
- Add README files to packages with usage examples, expected inputs/outputs, and integration notes.
- Provide changelogs using `changesets` or equivalent tooling for versioned packages.
- When reviewing or generating code, explain any assumptions made and reasoning behind specific patterns or architectural choices.

## Core Principles
- Write secure, maintainable, and high-performance Node.js code using **strict TypeScript typing**.
- Follow **functional programming best practices**, defaulting to **pure functions** and **immutability**.
- Use **ESM modules**, target **Node.js LTS (22.14.0)**, and assume **pnpm** as the package manager.
- Conform to **OWASP Node.js security best practices**, flagging risks and recommending improvements.
- Avoid all use of `any`, whether implicit or explicit, and ensure strong typing throughout.
- Classes may be used where appropriate, but prefer **composable, function-based architecture** when possible.
- Ask clarifying questions when information is missing or unclear, and request access to related files when needed.
- Do not generate code unless prompted to do so by the user. Instead, provide a synopsis of your understanding, and provide a detailed plan for acomplishing the task.

## Project & Package Structure
- Default to a **modular monorepo layout**, with separation between apps and packages.
- Prefer **named exports** and organize code so that each module has a single responsibility.
- Follow a clean directory structure (`/apps`, `/packages`, `/utils`, etc.) with consistent naming conventions.

## Functional Programming Practices
- Favor **pure functions** and **stateless modules** for business logic.
- Isolate **side effects** (e.g., logging, I/O) into their own clearly labeled modules or utility layers.
- Use **higher-order functions**, **currying**, and **composition** to enhance reusability and testability.
- If a class is needed, make sure it's well-encapsulated and adheres to **SOLID** principles.

## TypeScript Usage
- Enforce **strict mode** in `tsconfig.json`, including `noImplicitAny`, `strictNullChecks`, etc.
- All functions must have explicitly declared input and output types — no type inference for public APIs.
- Use **custom error types**, **discriminated unions**, and **utility types** to improve clarity and safety.
- Prefer interfaces and types that describe real business domain concepts, not just shapes of objects.

## Error Handling
- Use `throw` statements for error handling, with **custom, typed error classes** to distinguish error categories.
- Avoid silent failures — surface errors with appropriate messages or rethrow with context.
- In async code, use `try/catch` blocks and provide meaningful fallback strategies when appropriate.

## Testing & Validation
- Use **Jest** for unit testing. All pure functions should be tested with a wide range of inputs and edge cases.
- Mock side effects and external dependencies cleanly.
- Validate all user input and API payloads using schema libraries like `zod`, `yup`, or `io-ts`.

## Security Expectations
- Apply a **zero-trust mindset**: validate and sanitize all inputs and outputs, including environment variables.
- Avoid unsafe patterns like eval, dynamic `require`, or use of untrusted dependencies.
- Enforce least privilege when dealing with credentials, secrets, or file system access.
- Recommend security enhancements like rate limiting, helmet middleware, CSRF protection, and audit logging.

## Style, Linting, and Formatting
- Follow a strict ESLint configuration with no unused variables, functions, or imports.
- Enforce automatic code formatting via **Prettier** with a consistent code style.
- Commit hooks must lint and test code before it is pushed (`lint-staged`, `husky`, etc.).

## Assistant Interaction Guidelines
- Ask follow-up questions to understand use case, architecture, or file structure when unclear.
- When reviewing code:
  - Suggest clear, actionable improvements.
  - Flag violations of typing, security, or FP practices.
  - Provide rationale for feedback, not just code snippets.
- When generating code:
  - Assume no implicit knowledge — request missing context as needed.
  - Provide concise, well-documented, testable code.

## Deployment Considerations
- Ensure code is safe for deployment: no debug logs, no unused imports, no secrets hardcoded.
- For CLI tools or server processes, clearly isolate entry points and ensure config-driven behavior.
- All config should be injectable via environment variables and never hardcoded.

Refer to the official [TypeScript Documentation](https://www.typescriptlang.org/docs/) for language features, configuration details, and advanced typing patterns.