Configure Copilot instructions per best practices

.github/copilot-instructions.md

@@ -2,8 +2,39 @@
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
+## About This Project
+
 OpenCV-JS is a TypeScript NPM package that provides OpenCV.js (JavaScript/WebAssembly version of OpenCV) for both Node.js and browser environments. The package wraps a pre-built 11MB OpenCV.js WASM binary with TypeScript type definitions.
 
+**Repository:** https://github.com/TechStark/opencv-js  
+**NPM Package:** [@techstark/opencv-js](https://www.npmjs.com/package/@techstark/opencv-js)  
+**Version:** 4.12.0-release.1
+
+## Technology Stack
+
+- **Language:** TypeScript
+- **Runtime:** Node.js 20.x (also supports browser environments)
+- **Build Tool:** TypeScript Compiler (tsc)
+- **Testing:** Jest with ts-jest
+- **Package Manager:** npm
+- **OpenCV Version:** 4.12.0 (WebAssembly/JavaScript build)
+- **Key Dependencies:** Jimp (for image loading in tests)
+
+## Table of Contents
+
+- [Working Effectively](#working-effectively)
+- [Package Usage Patterns](#package-usage-patterns)
+- [Testing and Validation](#testing-and-validation)
+- [File Structure and Navigation](#file-structure-and-navigation)
+- [CI/CD and Publishing](#cicd-and-publishing)
+- [Common Development Tasks](#common-development-tasks)
+- [Browser vs Node.js Differences](#browser-vs-nodejs-differences)
+- [Performance and Timing Expectations](#performance-and-timing-expectations)
+- [Troubleshooting](#troubleshooting)
+- [Security Considerations](#security-considerations)
+- [External Documentation](#external-documentation)
+- [Contributing Guidelines](#contributing-guidelines)
+
 ## Working Effectively
 
 ### Initial Setup and Build
@@ -176,4 +207,78 @@ After making changes, ALWAYS test these scenarios:
 - `npm audit` - Check for security vulnerabilities  
 - `npm pack && tar -tzf *.tgz | head -20` - Inspect package contents
 
+## Security Considerations
+
+### Dependency Security
+- ALWAYS run `npm audit` before committing changes
+- Use `npm audit fix` to automatically fix security vulnerabilities
+- Review security advisories for OpenCV.js and WebAssembly-related issues
+- Keep TypeScript and build dependencies up to date
+
+### WASM Binary Safety
+- The `dist/opencv.js` file is a pre-built WebAssembly binary from OpenCV.org
+- Verify the source when updating: https://docs.opencv.org/4.12.0/opencv.js
+- Do NOT accept modified opencv.js files from untrusted sources
+
+### Memory Safety
+- Always call `.delete()` on OpenCV objects to prevent memory leaks
+- Memory leaks in WASM can cause browser crashes or performance degradation
+- Use try/finally blocks to ensure cleanup even when errors occur
+
+### Input Validation
+- Validate image dimensions and formats before processing
+- Handle invalid inputs gracefully to prevent crashes
+- Be cautious with user-provided images in browser environments
+
+## External Documentation
+
+### OpenCV Resources
+- [OpenCV.js Documentation](https://docs.opencv.org/4.12.0/d5/d10/tutorial_js_root.html)
+- [OpenCV.js Tutorials](https://docs.opencv.org/4.12.0/#:~:text=OpenCV%2DPython%20Tutorials-,OpenCV.js%20Tutorials,-Tutorials%20for%20contrib)
+- [OpenCV.js API Reference](https://docs.opencv.org/4.12.0/d0/de1/group__js.html)
+- [OpenCV Build Information](https://docs.opencv.org/4.12.0/opencv.js)
+
+### Package Resources
+- [NPM Package Page](https://www.npmjs.com/package/@techstark/opencv-js)
+- [GitHub Repository](https://github.com/TechStark/opencv-js)
+- [Code Examples Repository](https://github.com/TechStark/opencv-js-examples)
+- [Live Demo (React)](https://codesandbox.io/s/techstarkopencv-js-demo-page-f7gvk)
+- [Live Demo (Angular)](https://codesandbox.io/s/techstark-opencv-js-angular-demo-hkmc1n)
+- [Face Detection Demo](https://codesandbox.io/s/opencv-js-face-detection-i1i3u)
+
+### TypeScript Resources
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Jest Testing Framework](https://jestjs.io/docs/getting-started)
+- [ts-jest Configuration](https://kulshekhar.github.io/ts-jest/)
+
+## Contributing Guidelines
+
+### Before Making Changes
+1. Search existing issues and PRs to avoid duplicates
+2. For significant changes, open an issue first to discuss
+3. Fork the repository and create a feature branch
+4. Ensure you understand the codebase by running: `npm install && npm run build && npm test`
+
+### Making Changes
+1. Follow existing code style and patterns
+2. Add TypeScript type definitions for new OpenCV features
+3. Include tests for new functionality in the `test/` directory
+4. Update documentation if adding new features or changing behavior
+5. Ensure all tests pass: `npm test`
+6. Format code: `npm run format`
+7. Check for security issues: `npm audit`
+
+### Submitting Changes
+1. Write clear, descriptive commit messages
+2. Reference related issues in commit messages (e.g., "Fixes #123")
+3. Ensure CI/CD workflows pass (unit tests, build)
+4. Provide clear PR description explaining the changes
+5. Be responsive to review feedback
+
+### Code Review Process
+- PRs require passing CI checks before merge
+- Maintainer review is required
+- Keep PRs focused and reasonably sized
+- Update type definitions when adding new OpenCV methods
+
 ALWAYS follow these patterns for reliable OpenCV-JS development and avoid common pitfalls with async initialization and memory management.