AGENTS.md for this repository

Purpose
- This document guides agent-like contributors (human or AI) on how to build, lint, test, and style the codebase.
- It also captures preferences or constraints used by the team and by automated agents operating in this repo.

Scope
- Build, test, and lint commands for common environments (Node/TS, Python, Go, Rust, Java).
- Code style guidelines: imports, formatting, types, naming, error handling, tests, and documentation.
- Cursor rules and Copilot rules inclusion if present in the repo.
- How to handle running a single test and how to extend tests locally.

1) Quick start: common commands
- Build (preferred entry point):
  - Node/TypeScript: npm run build (or yarn build)
  - Python: python -m build or your project-specific build script
  - Go: go build ./...
  - Rust: cargo build
- Lint:
  - Node/TypeScript: npm run lint (or yarn lint)
  - Python: ruff check . | flake8 or your project’s linter
  - Go: golangci-lint run
  - Rust: cargo clippy
- Test:
  - Node/TS: npm test (or yarn test)
  - Python: pytest
  - Go: go test ./...
  - Rust: cargo test
- Note: If your repo uses a mixed tech stack, prefer using the language-specific script in package.json or equivalent courier scripts.

2) Run a single test (typical patterns)
- Node / Jest
  - Run a specific test by name: npm test -- -t "should render the component"
  - Run a specific file: npm test -- path/to/file.test.js
- Python / Pytest
  - Run tests matching a keyword: pytest -k "test_name_substring" -q
  - Run a specific file: pytest tests/test_module.py -q
- Go
  - Run a single test by name: go test -run TestName ./...
- Rust / Cargo
  - Exact test: cargo test -- --exact TestName
  - Run a file-like subset: cargo test -- 'pattern'
- Java / Maven or Gradle
  - Maven: mvn -Dtest=MyTest#testMethod test
  - Gradle: ./gradlew test --tests "com.example.MyTest.testMethod"

3) Code style guidelines
<A) Imports and modules>
- Group imports into three blocks: standard library, third-party, and first-party modules.
- Order blocks alphabetically within each group; separate blocks with a newline.
- Avoid wildcard imports; prefer explicit imports.
- For TS/JS, prefer absolute/alias imports over relative when it improves clarity.

<B) Formatting and tooling>
- Use the project’s formatter (Prettier, gofmt, black, etc.) with the configured settings.
- Respect the repository’s line length (commonly 100-120 chars). Break long lines at logical points.
- Use semicolons consistently if the project enforces them; otherwise adhere to the established style.
- Enable and respect lint rules; fix all autofixable issues during code edits.

<C) Types and APIs>
- In TypeScript, enable strict type checking; prefer interfaces for public APIs and type aliases for shapes.
- Use readonly modifiers where possible to express intent and optimize immutability guarantees.
- Prefer explicit return types for exported functions and public APIs.
- Avoid any where possible; if necessary, use unknown with proper checks.

<D) Naming conventions>
- Variables and functions: camelCase
- Classes and types: PascalCase
- Constants: UPPER_SNAKE_CASE
- File and module names: kebab-case or snake_case, consistent with project convention

<E) Error handling>
- Do not swallow errors; attach context when rethrowing (e.g., throw new Error(`Context: ${err.message}`)).
- Propagate errors to callers with meaningful messages.
- Use try/catch around IO-bound or network-bound operations and ensure resources are released in finally or via finally-like blocks.

<F) Async/Promises>
- Prefer async/await syntax for readability.
- Handle rejections at the call site when possible; avoid unhandled promises.
- Use Promise.all when performing independent async tasks, but catch and handle failures gracefully.

<G) Tests>
- Tests should be fast, deterministic, and hermetic.
- Use descriptive test names and structure (Arrange-Act-Assert patterns where helpful).
- Isolate external dependencies; mock/stub network/db calls effectively.
- Include tests for error paths and boundary conditions.

<H) Documentation and comments>
- Document non-obvious logic with concise comments; avoid obvious boilerplate.
- Public APIs should have JSDoc / TSdoc-style comments describing inputs, outputs, and side effects.
- Update or add READMEs where necessary to reflect changes in behavior.

<I) Security and compliance>
- Do not log sensitive data; mask secrets in logs.
- Validate inputs and sanitize outputs where appropriate.
- Treat untrusted data carefully; avoid code paths that execute untrusted input without validation.

4) Cursor and Copilot rules
- Cursor rules: If this repo uses Cursor tooling, its rules can live under .cursor/rules/ or .cursorrules. Copy or adapt them into this document when agents are created.
- Copilot rules: If there is .github/copilot-instructions.md, follow its guidance and ensure code generation adheres to the outlined constraints.
- If the repo contains these files, consider linking to them here and summarizing any special constraints applicable to agents.

5) Git workflow and contribution notes
- Do not modify dependencies without explicit approval.
- Keep commits small and focused; write 1-2 sentence messages describing why a change was made, not just what changed.
- For AGENTS.md updates, include a short rationale in the commit message.
- Prefer small, reviewed edits over sweeping rewrites.

6) Local integration guidance
- Run: npm install or yarn to install deps before building/tests.
- For multi-language repos, ensure the local environment has language runtimes and tooling installed (Node, Python, Go, Rust, etc.).
- Use a clean environment (e.g., nvm, virtualenv) to avoid cross-project contamination.

7) Example usage scenarios
- A single-file feature: create a minimal unit test, run npm test -- -t "feature X" to validate.
- A refactor: run lint and then a subset of tests; fix issues flagged by lints before merging.
- A CI-like dry run: run npm ci; npm run build; npm test; and report failures with minimal noise.

Notes
- If you want me to tailor this file to the exact repo, I can incorporate the actual existing AGENTS.md content (if present) or sync with Cursor/Copilot rules after inspecting the repo. Right now this is a solid, language-agnostic baseline.