docs: add AGENTS.md with build/lint/test commands and code style guidelines

.gitignore

@@ -0,0 +1,2 @@
+# Ignore environment files
+.env

AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS.md
+
+## 1. Build, Lint, and Test Commands
+
+### 1.1 Build
+- **Development build**: `npm run build:dev`
+  - Compiles source files with source maps enabled.
+  - Output directory: `dist/`.
+- **Production build**: `npm run build:prod`
+  - Optimized bundle, minified assets, no source maps.
+  - Output directory: `dist/`.
+- **Watch mode**: `npm run build:watch`
+  - Rebuilds on file changes; useful during active development.
+
+### 1.2 Lint
+- **ESLint**: `npm run lint`
+  - Runs ESLint over all `src/**/*.js` and `src/**/*.ts`.
+  - Fails on any error with exit code `1`.
+- **Prettier**: `npm run format`
+  - Checks for formatting violations without fixing them.
+  - Use `npm run format:fix` to automatically format all files.
+
+### 1.3 Test
+- **Full test suite**: `npm test`
+  - Executes all Jest test files (`**/__tests__/**/*.js`).
+- **Run a single test**: `npm test -- <testFilePath>`
+  - Example: `npm test -- src/__tests__/utils/format.test.js`
+  - Runs only the specified test file, preserving test isolation.
+- **Coverage**: `npm run coverage`
+  - Generates an Istanbul coverage report in `coverage/`.
+
+### 1.4 Common npm Scripts (add to `package.json` if missing)
+```json
+{
+  "scripts": {
+    "build:dev": "webpack --mode development",
+    "build:prod": "webpack --mode production",
+    "build:watch": "webpack --watch",
+    "lint": "eslint src/**/*.js",
+    "format": "prettier --check src/**/*.js",
+    "format:fix": "prettier --write src/**/*.js",
+    "test": "jest",
+    "coverage": "jest --coverage"
+  }
+}
+```
+
+---
+
+## 2. Code Style Guidelines
+
+### 2.1 File Organization
+- Keep related components, utilities, and hooks in feature‑specific directories.
+- Use index files (`index.js`) to re‑export public APIs from each folder.
+
+### 2.2 Imports
+- **Named imports only** when possible:
+  ```js
+  import { foo, bar } from './utils';
+  ```
+- **Default imports** only for modules that expose a default export:
+  ```js
+  import defaultFn from './default';
+  ```
+- **Relative paths** (`./`, `../`) must be used; no root‑path shortcuts.
+
+### 2.3 Formatting
+- **Indent**: 2 spaces, no tabs.
+- **Quotes**: Prefer single quotes (`'`) for strings.
+- **Semicolons**: Optional but encouraged for consistency.
+- **Line length**: Limit to 100 characters; wrap when exceeded.
+- **Trailing commas**: Use in object/array literals.
+
+### 2.4 Naming Conventions
+- **Variables / Functions**: `camelCase`.
+- **Classes**: `PascalCase`.
+- **Constants**: `UPPER_SNAKE_CASE`.
+- **File names**: kebab-case for CSS, snake_case for utility modules.
+- **Test files**: suffix with `.test.js` or `.spec.js`.
+
+### 2.5 TypeScript (if used)
+- Enable `strict` mode in `tsconfig.json`.
+- Prefer `interface` for object shapes; use `type` only for unions or conditional types.
+- Export types explicitly when they are part of a public API.
+
+### 2.6 Error Handling
+- **Synchronous**: Throw descriptive `Error` objects.
+- **Asynchronous**: Return rejected promises or use `try/catch` with custom error classes.
+- **Logging**: Use `console.error` for runtime errors; include context (e.g., `error.message + ' at ' + stack`).
+
+### 2.7 Async/Await
+- Always handle rejected promises; avoid unhandled promise warnings.
+- Prefer `await` over `.then()` chains for readability.
+
+### 2.8 Dependency Management
+- Keep third‑party imports at the top of the file.
+- Avoid direct use of global Node APIs (`process`, `__dirname`) unless wrapped in utility functions.
+- Pin versions in `package.json`; run `npm audit` regularly.
+
+### 2.9 Testing Conventions
+- **Arrange**: Setup → Exercise → Verify.
+- **Describe**: Use `describe` blocks for logical groups.
+- **It**: Use `it` with a clear, past‑tense description.
+- **BeforeEach / AfterEach**: Clean up mocks and state.
+
+---
+
+## 3. Project‑Specific Rules
+
+### 3.1 Cursor Rules
+- No `.cursor` configuration detected in the repository. If you add a `.cursor` folder, include:
+  - `cursor.json` with `"maxLineLength": 100`
+  - `"preferTabs": false`
+  - `"tabWidth": 2`
+
+### 3.2 Copilot Instructions
+- No `.github/copilot-instructions.md` found. If you create one, place:
+  - `rules` section outlining PR checklist.
+  - `codeowners` snippet if needed.
+
+### 3.3 Commit Message Style
+- Use Conventional Commits (`feat:`, `fix:`, `docs:`, etc.).
+- Body should explain **why** the change was made, not just **what**.
+
+### 3.4 Dependency Updates
+- Run `npm outdated` before any major version bump.
+- Update `package-lock.json` and run `npm install` to ensure reproducibility.
+
+---
+
+## 4. Utility Scripts
+
+### 4.1 Clean Build Artifacts
+```bash
+# Remove generated files
+rm -rf dist/ coverage/ node_modules/
+```
+
+### 4.2 Reset Lint Cache
+```bash
+# Clear ESLint cache to force re‑lint
+rm -rf .eslintcache
+```
+
+### 4.3 Generate Documentation (if used)
+```bash
+# Assuming JSDoc is configured
+jsdoc -c jsdoc.conf.json -r src/ -o docs/
+```
+
+---
+
+## 5. FAQ
+
+**Q:** *How do I run a single test without the whole suite?*  
+**A:** `npm test -- path/to/single.test.js`
+
+**Q:** *Where should I add new utility functions?*  
+**A:** Place them in `src/utils/` with a descriptive filename and export via `index.js`.
+
+**Q:** *What is the preferred way to handle environment variables?*  
+**A:** Store them in `.env.local` and access via `process.env.VAR_NAME`. Do not commit `.env*` files.
+
+---
+
+*This document is intended to be the single source of truth for agentic coding interactions within this repository. Keep it updated as tooling or conventions evolve.*