Add comprehensive @jk-com/adblock-compiler documentation with CI/CD integration examples (#216)

* Initial plan

* Add comprehensive adblock-compiler documentation with CI/CD examples

Co-authored-by: jaypatrick <1800595+jaypatrick@users.noreply.github.com>

---------

Signed-off-by: Jayson Knight <jayson.knight@jaysonknight.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jaypatrick <1800595+jaypatrick@users.noreply.github.com>
Co-authored-by: Jayson Knight <jayson.knight@jaysonknight.com>

Author: Copilot

.github/copilot-instructions.md

@@ -39,13 +39,15 @@ Multi-language toolkit for ad-blocking and AdGuard DNS management with **identic
 - `adguard-validate` (CLI tool)
 
 ### Compiler Equivalence
-All four compilers (TypeScript, .NET, Python, Rust) use `@jk-com/adblock-compiler` and **must**:
+All four compilers (TypeScript, .NET, Python, Rust) use **[@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler)** and **must**:
 - Support JSON, YAML, TOML config formats (except PowerShell: JSON only)
 - Count rules identically (exclude empty lines and `!`/`#` comments)
 - Compute SHA-384 hash of output (96 hex chars)
 - Return same result structure: `{ success, ruleCount, hash, elapsedMs, outputPath }`
 - **Use centralized validation library** for all security checks
 
+📘 **See [adblock-compiler guide](../docs/guides/adblock-compiler-guide.md)** for package details, benefits, and CI/CD integration examples.
+
 ### ConsoleUI DI Pattern
 `src/adguard-api-dotnet/src/AdGuard.ConsoleUI/` uses service-oriented architecture:
 ```

README.md

@@ -44,7 +44,17 @@ A comprehensive multi-language toolkit for ad-blocking, network protection, and
 | **Rust** | Native binary | Cargo/Binary | Zero-runtime deps, LTO optimization |
 | **PowerShell** | PowerShell 7+ | Module | Pipeline-friendly, Pester tests |
 
-All compilers use [@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler) with **built-in security validation** and support:
+All compilers use **[@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler)** - a modern, SOLID-compliant TypeScript package distributed via JSR. [📘 See comprehensive guide →](docs/guides/adblock-compiler-guide.md)
+
+**Why @jk-com/adblock-compiler?**
+- ✨ **SOLID Architecture**: 8+ specialized classes following Single Responsibility Principle
+- 🔧 **Dependency Injection**: Full DI support for testability and customization
+- 📘 **Superior Type Safety**: Complete TypeScript interfaces with JSDoc coverage
+- ⚡ **Performance Optimized**: Improved pattern matching and rule processing
+- 🎯 **Better Error Handling**: Descriptive errors with context and suggestions
+- 📦 **JSR Distribution**: Modern registry with better dependency management
+
+**Compilation Features:**
 - **All 11 transformations**: Deduplicate, Validate, RemoveComments, Compress, RemoveModifiers, etc.
 - **Multi-format config**: JSON, YAML, and TOML configuration files
 - **Source-specific settings**: Per-source transformations, inclusions, exclusions
@@ -568,6 +578,9 @@ All compilers use [@jk-com/adblock-compiler](https://github.com/jaypatrick/adblo
 - **All 11 transformations**: Deduplicate, Validate, RemoveComments, Compress, etc.
 - **Source-specific settings**: Per-source transformations, inclusions, exclusions
 - **Pattern matching**: Wildcards, regex, file-based patterns
+- **SOLID Architecture**: Dependency injection, single responsibility, better testing
+
+📘 **[Complete @jk-com/adblock-compiler Guide](docs/guides/adblock-compiler-guide.md)** - Why it's better, CI/CD integration, API reference, migration guide
 
 **AdBlock Compiler Documentation**:
 - [Migration Guide](https://github.com/jaypatrick/adblock-compiler/blob/master/docs/MIGRATION.md) - Migrate from @adguard/hostlist-compiler
@@ -1468,7 +1481,8 @@ A user-friendly Gatsby-powered website with:
 
 ### Rules Compilers
 
-- [TypeScript Compiler](src/rules-compiler-typescript/) - Node.js/Deno compiler
+- **[@jk-com/adblock-compiler Guide](docs/guides/adblock-compiler-guide.md)** - Core package documentation with CI/CD examples
+- [TypeScript Compiler](src/rules-compiler-typescript/) - Deno compiler with JSR integration
 - [.NET Compiler README](src/rules-compiler-dotnet/README.md) - C# library and CLI
 - [Python Compiler README](src/rules-compiler-python/README.md) - pip-installable package
 - [Rust Compiler README](src/rules-compiler-rust/README.md) - Single binary distribution

docs/README.md

@@ -29,6 +29,7 @@ This directory contains comprehensive documentation for the ad-blocking reposito
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](getting-started.md) | Installation, prerequisites, and quick start |
+| [**@jk-com/adblock-compiler Guide**](guides/adblock-compiler-guide.md) | **Core compilation package with CI/CD examples** |
 | [Docker Guide](docker-guide.md) | Using Docker for development |
 | [Configuration Reference](configuration-reference.md) | Full configuration schema documentation |
 | [Compiler Comparison](compiler-comparison.md) | Feature comparison of all compilers |