init ruler

Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
2026-04-06 20:48:07 -04:00
parent 4db02f47bf
commit 206f028fdf
12 changed files with 1201 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -67,3 +67,11 @@ yarn-error.log*
 next-env.d.ts
 public/sw.js
 public/workbox-*.js
+
+
+# START Ruler Generated Files
+/AGENTS.md
+/AGENTS.md.bak
+/opencode.json
+/opencode.json.bak
+# END Ruler Generated Files
--- a/.ruler/00-LINT-RULES.md
+++ b/.ruler/00-LINT-RULES.md
@@ -0,0 +1,93 @@
+## CRITICAL: Lint Rules Are Sacred and Immutable
+
+**ABSOLUTE PROHIBITION**: You are **FORBIDDEN** from modifying, disabling, or bypassing any lint rules, ESLint configurations, TypeScript compiler settings, or any other code quality enforcement mechanisms in this repository.
+
+## Non-Negotiable Principles
+
+### 1. Rules Must NEVER Be Changed
+
+- **NO** adding `// eslint-disable` comments
+- **NO** adding `// @ts-ignore` or `// @ts-expect-error` comments
+- **NO** modifying `.eslintrc`, `eslint.config.js`, or any ESLint configuration files
+- **NO** modifying `tsconfig.json` compiler options to silence errors
+- **NO** modifying `biome.json`, `prettier.config.js`, `.oxlintrc`, or any formatter settings
+- **NO** adding files to `.eslintignore` or exclude patterns
+- **NO** downgrading errors to warnings or warnings to off
+- **NO** adjusting rule severity or options
+
+### 2. Fix the Root Cause, Not the Symptom
+
+When encountering a lint error or type error:
+
+1. **Attempt 1-10**: Fix the underlying code issue that violates the rule
+   - Refactor the code to comply with the rule
+   - Restructure the logic to avoid the violation
+   - Use proper types and patterns that satisfy the linter
+   - Redesign the approach entirely if needed
+   - Consider alternative implementations
+   - Review similar patterns in the codebase for guidance
+   - Consult documentation for the library/framework being used
+   - Try multiple different architectural approaches
+   - Explore edge cases and alternative solutions
+   - Exhaust ALL possible code-level fixes
+
+2. **After 10+ Genuine Attempts**: If you have exhausted ALL reasonable code fixes and the error persists:
+   - **STOP** and **ASK THE USER** for guidance
+   - Present the specific rule violation
+   - Explain what you've tried (all 10+ attempts)
+   - Ask if there's a pattern you're missing or if an exception is warranted
+   - **NEVER** make the decision to disable or modify rules yourself
+
+### 3. Why Rules Exist
+
+- Lint rules enforce consistency across the codebase
+- They prevent bugs and anti-patterns
+- They represent team decisions and conventions
+- They ensure code quality and maintainability
+- They are project-specific and carefully chosen
+
+### 4. Common Scenarios and Correct Responses
+
+#### Scenario: "Unused variable" error
+- ❌ WRONG: Add `// eslint-disable-next-line no-unused-vars`
+- ✅ RIGHT: Remove the unused variable or use it properly
+
+#### Scenario: "any type" error
+- ❌ WRONG: Add `// @ts-ignore` or change to `unknown` just to silence
+- ✅ RIGHT: Define proper types that accurately represent the data
+
+#### Scenario: "Missing dependency in useEffect" warning
+- ❌ WRONG: Add `// eslint-disable-next-line react-hooks/exhaustive-deps`
+- ✅ RIGHT: Add the missing dependency or restructure to avoid the issue
+
+#### Scenario: "Type errors in third-party library"
+- ❌ WRONG: Use `@ts-expect-error` or cast to `any`
+- ✅ RIGHT: Install proper type definitions, create a typed wrapper, or use proper type assertions
+
+#### Scenario: "Complexity too high" error
+- ❌ WRONG: Disable the complexity rule
+- ✅ RIGHT: Refactor the function into smaller, simpler functions
+
+### 5. Enforcement Priority
+
+Lint rules have **MAXIMUM PRIORITY**. They outrank:
+- Personal coding preferences
+- Convenience
+- Speed of implementation
+- Desire to "just make it work"
+
+### 6. Remember
+
+**You are here to serve the repository's conventions, not to modify them.**
+
+If you find yourself thinking "it would be easier to just disable this rule," that is **EXACTLY** when you must **NOT** do it.
+
+## Summary
+
+1. ❌ NEVER disable, ignore, or modify lint rules
+2. ✅ ALWAYS fix the code to comply with rules
+3. ✅ Try 10+ different approaches to fix the root issue
+4. ✅ ASK THE USER if all code-level fixes fail
+5. ❌ NEVER act autonomously on rule modifications
+
+**These are not guidelines. These are absolute requirements.**
--- a/.ruler/02-BUN-GUIDE.md
+++ b/.ruler/02-BUN-GUIDE.md
@@ -0,0 +1,52 @@
+## Bun Guidelines
+
+**CRITICAL**: Do not assume you know full Bun APIs. For **ANY** Bun API you use, confirm them by using `bun-docs` MCP tools.
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+### APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+### Testing
+
+#### Quick Start
+- Run tests: `bun test`
+- Write tests in `tests/` folder
+
+#### Test Structure
+- Use `describe` blocks to group related tests
+- Use `test` for individual test cases
+- Use `beforeEach`/`afterEach` for setup/teardown
+
+#### Assertions
+- Import: `import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";`
+- Common: `expect(value).toBe(expected)`, `expect(fn).rejects.toThrow()`
+- Async: `await expect(asyncFn()).resolves.toBe(expected)`
+
+#### Mocking
+- Mock functions: `mock(fn)`
+- Mock globals: `global.fetch = mock(...)`
+- Restore mocks in `afterEach` or `finally`
+
+#### Best Practices
+- Mock external APIs (fetch, file I/O)
+- Test error cases and edge conditions
+- Use descriptive test names
+- Clean up resources in `afterEach`
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
--- a/.ruler/03-ZOD-GUIDE.md
+++ b/.ruler/03-ZOD-GUIDE.md
@@ -0,0 +1,19 @@
+## Zod Guidelines
+
+### Schema Definition
+- Define all schemas in `src/types.ts`
+- Use `z.object()` for objects, `z.array()` for arrays
+- Mark optional fields with `.optional()`
+- Create generic schemas for reusable structures
+
+### Type Inference
+- Always infer types from schemas: `export type Foo = z.infer<typeof FooSchema>`
+
+### Validation
+- Use `.parse()` to validate API responses
+- Only validate successful responses (`retcode === RESPONSE_CODES.SUCCESS`)
+- Return unvalidated responses for error cases
+
+### Patterns
+- Follow existing schema naming: `FooSchema` for schemas, `Foo` for types
+- Use `ZZZResponseSchema(dataSchema)` for API responses
--- a/.ruler/05-TESTING-DOCTRINE.md
+++ b/.ruler/05-TESTING-DOCTRINE.md
@@ -0,0 +1,460 @@
+# Production Testing Doctrine
+_Project-Agnostic Engineering Standard_
+
+---
+
+# 1. Purpose of Testing
+
+Testing exists to:
+
+- Prevent regressions
+- Protect critical business behavior
+- Enforce invariants
+- Guard boundaries
+- Provide safe refactoring
+- Reduce production incidents
+
+Testing does not exist to:
+
+- Increase coverage numbers
+- Satisfy tooling requirements
+- Mirror implementation line‑by‑line
+- Create a false sense of security
+
+If a test does not reduce real-world risk, it should not exist.
+
+---
+
+# 2. Core Principles
+
+---
+
+## 2.1 Determinism Is Non-Negotiable
+
+A test must:
+
+- Produce the same result every run
+- Not depend on execution order
+- Not depend on global state
+- Not depend on wall-clock time
+- Not depend on external networks
+- Not depend on randomness (unless seeded)
+
+A flaky test is worse than no test.
+
+If a test fails intermittently:
+- Fix it immediately
+- Or delete it
+
+There is no third option.
+
+---
+
+## 2.2 Isolation of Behavior
+
+Tests should verify behavior in isolation from unrelated systems.
+
+The smaller the scope of the test, the more reliable and faster it is.
+
+We separate:
+
+- Pure logic
+- System interactions
+- External integrations
+- Full-system behavior
+
+Confusing these layers results in slow, fragile suites.
+
+---
+
+## 2.3 Risk-Based Testing
+
+Testing effort should scale with risk.
+
+High-risk areas:
+- Financial logic
+- Security and access control
+- Data mutation
+- Distributed coordination
+- Concurrency
+- Migration and transformation logic
+
+Low-risk areas:
+- Static rendering
+- Formatting helpers
+- Simple data mapping
+
+Testing must prioritize business-critical systems.
+
+---
+
+## 2.4 Tests Are Part of the System
+
+Tests must follow the same standards as production code:
+
+- Clean structure
+- Clear naming
+- Maintainable
+- Reviewed in PRs
+- Refactored when necessary
+
+Test code quality reflects engineering quality.
+
+---
+
+# 3. Testing Layers (Architecture-Neutral)
+
+These layers apply universally.
+
+---
+
+# 3.1 Unit Tests (Logic Layer)
+
+Definition:
+Tests that validate pure behavior without system dependencies.
+
+Must:
+
+- Run fast
+- Avoid I/O
+- Avoid network
+- Avoid persistent state
+- Avoid framework bootstrapping
+
+Should test:
+
+- Business rules
+- Domain invariants
+- Edge cases
+- Validation
+- Transformation logic
+
+Reasoning:
+If logic cannot be tested without infrastructure, it is coupled too tightly.
+
+---
+
+# 3.2 Integration Tests (System Boundary Layer)
+
+Definition:
+Tests that validate interactions between internal components.
+
+May include:
+
+- Datastores
+- Filesystems
+- Queues
+- Caches
+- Framework wiring
+- Service boundaries
+
+Must:
+
+- Use real internal components
+- Reset state between runs
+- Avoid real external services
+
+Reasoning:
+Most production bugs occur at boundaries, not in pure functions.
+
+---
+
+# 3.3 External Integration Tests
+
+Definition:
+Tests that validate interaction with third-party systems.
+
+Policy:
+
+- Prefer mocking or simulation
+- Use sandbox environments only when necessary
+- Never depend on live production services
+
+Reasoning:
+External systems are outside your control and introduce nondeterminism.
+
+---
+
+# 3.4 End-to-End Tests (System-Level)
+
+Definition:
+Tests that validate complete workflows from entry to outcome.
+
+Must:
+
+- Cover only critical flows
+- Be minimal in number
+- Run in isolated environments
+- Avoid unnecessary duplication of lower-level tests
+
+End-to-end tests are expensive and fragile. Use them surgically.
+
+---
+
+# 4. State Management Policy
+
+---
+
+## 4.1 No Shared State Between Tests
+
+Every test must assume a blank environment.
+
+Options:
+
+- Fresh environment per test
+- Transaction rollback
+- Full reset between runs
+- Isolated test containers
+
+No test may depend on side effects from another test.
+
+---
+
+## 4.2 Reproducible Environments
+
+Tests must run consistently:
+
+- Locally
+- In CI
+- In parallel
+- Across operating systems (if supported)
+
+Environment drift is unacceptable.
+
+---
+
+# 5. Mocking Policy
+
+---
+
+## 5.1 Mock External Systems
+
+Mock:
+
+- Third-party APIs
+- Payment providers
+- Email systems
+- External storage
+- Network services outside system boundary
+
+Reasoning:
+You do not control them.
+
+---
+
+## 5.2 Do Not Mock Core Logic
+
+Never mock:
+
+- Business rules
+- Authorization checks
+- Data validation
+- Domain logic
+
+Mocking internal logic invalidates the test.
+
+---
+
+## 5.3 Avoid Over-Mocking
+
+Over-mocking:
+
+- Couples tests to implementation
+- Breaks refactoring
+- Creates fragile tests
+
+Mock only what crosses system boundaries.
+
+---
+
+# 6. Error & Edge Case Policy
+
+Every public interface must have tests for:
+
+- Valid input
+- Invalid input
+- Unauthorized or restricted access (if applicable)
+- Boundary values
+- Failure paths
+- Concurrency conflicts (if applicable)
+
+Most real-world failures happen outside happy paths.
+
+---
+
+# 7. Security Testing Doctrine
+
+All systems must test:
+
+- Access control enforcement
+- Privilege boundaries
+- Input validation
+- Injection resistance (where applicable)
+- Role escalation prevention
+
+Security-sensitive logic must have near-complete coverage.
+
+---
+
+# 8. Concurrency & Race Conditions
+
+If the system involves:
+
+- Multi-threading
+- Distributed nodes
+- Async processing
+- Queues
+- Parallel writes
+
+Then tests must include:
+
+- Concurrent execution scenarios
+- Conflict handling
+- Idempotency verification
+- Retry logic behavior
+
+These bugs rarely appear in simple test cases.
+
+---
+
+# 9. Migration & Data Evolution
+
+If the system stores data over time:
+
+- Schema migrations must be tested
+- Data transformation must be verified
+- Backward compatibility must be validated
+- Downgrade scenarios (if supported) must be considered
+
+Silent data corruption is catastrophic.
+
+---
+
+# 10. CI Enforcement
+
+Tests must run automatically:
+
+- On every pull request
+- On main branch
+- Before release
+
+CI must:
+
+- Fail fast
+- Prevent merges on failure
+- Run in clean environments
+- Be reproducible
+
+If tests only run locally, they are not part of the system.
+
+---
+
+# 11. Coverage Philosophy
+
+Coverage is a diagnostic tool, not a goal.
+
+Required:
+
+- High coverage on business-critical modules
+- Full coverage on security boundaries
+- Full coverage on financial logic
+
+Optional:
+
+- High coverage on trivial UI or formatting
+
+100% coverage does not imply correctness.
+Low coverage in critical areas is unacceptable.
+
+---
+
+# 12. Performance of the Test Suite
+
+The test suite must:
+
+- Run quickly enough to encourage frequent execution
+- Support parallelization
+- Avoid arbitrary sleeps
+- Avoid unnecessary bootstrapping
+
+Slow tests reduce engineering velocity and discourage use.
+
+---
+
+# 13. Red Flags (Immediate Rejection)
+
+- Tests that sometimes fail
+- Tests that depend on execution order
+- Snapshot abuse
+- Arbitrary timeouts to “fix” flakiness
+- Global mutable state
+- Randomized data without seed
+- Testing implementation details instead of behavior
+- Excessive E2E replacing proper layering
+- Mocking core domain logic
+- Tests that assert only truthy values
+
+---
+
+# 14. Refactoring Policy
+
+Tests must enable refactoring.
+
+If changing internal structure breaks many tests without changing behavior:
+
+- The tests are coupled incorrectly.
+
+Behavioral contracts should remain stable under refactor.
+
+---
+
+# 15. Production Observability Complements Testing
+
+Testing does not replace:
+
+- Logging
+- Monitoring
+- Alerting
+- Metrics
+- Tracing
+
+Tests prevent known failures.
+Observability detects unknown ones.
+
+Both are required.
+
+---
+
+# 16. The Engineering Mindset
+
+Before writing any test, ask:
+
+1. What failure would hurt the business most?
+2. What invariant must never break?
+3. What boundary is being crossed?
+4. What assumptions are being made?
+5. Can this test fail nondeterministically?
+6. Is this testing behavior or implementation?
+
+If the test does not meaningfully reduce risk, reconsider it.
+
+---
+
+# 17. Definition of Production-Grade Testing
+
+A system with production-grade testing:
+
+- Can be refactored safely
+- Rarely ships regressions
+- Catches security violations before release
+- Detects data integrity failures early
+- Has a stable, trusted CI pipeline
+- Has a fast feedback loop
+- Is boringly reliable
+
+Engineers trust the test suite.
+They do not ignore it.
+They do not fear it.
+They rely on it.
+
+That is the standard.
--- a/.ruler/08-CONTEXT7.md
+++ b/.ruler/08-CONTEXT7.md
@@ -0,0 +1 @@
+**CRITICAL**: Always use context7 when I need code generation, setup or configuration steps, or library/API documentation. This means you should automatically use the Context7 MCP tools to resolve library id and get library docs without me having to explicitly ask.
--- a/.ruler/09-NIX.md
+++ b/.ruler/09-NIX.md
@@ -0,0 +1,287 @@
+# Nix Tool Preference Directive
+
+## Core Instruction
+
+**Always prioritize Nix-based tools (`nix_nix`, `nix_nix_versions`, `nix-shell`, `nix run`, etc.) for querying packages, versions, options, environments, and reproducible workflows whenever relevant.**
+
+Nix ensures declarative, isolated, reproducible results. Use these before generic searches, manual installs, or distro tools.
+
+## Trigger Conditions
+
+- Package discovery/version info: `nix_nix` or `nix_nix_versions`.
+- Environment setup: `nix-shell`, `nix develop`.
+- NixOS/Home-manager config: `nix_nix action=options`.
+- Reproducibility/CI: Nix flakes/builds.
+
+**Fallback**: Native tools if Nix unsuitable; note Nix alternative.
+
+## Specific Tools
+
+### **`nix_nix`** - Query NixOS, Home Manager, Darwin, flakes, and more
+
+| Parameter | Description |
+|-----------|-------------|
+| `action` | `search`, `info`, `stats`, `options`, `channels`, `flake-inputs`, `cache` |
+| `source` | `nixos`, `home-manager`, `darwin`, `flakes`, `flakehub`, `nixvim`, `wiki`, `nix-dev`, `noogle`, `nixhub` |
+| `query` | Search term, name, or prefix |
+| `type` | `packages`, `options`, `programs`, `list`, `ls`, `read` |
+| `channel` | `unstable`, `stable`, `25.05` |
+| `limit` | 1-100 (or 1-2000 for flake-inputs read) |
+
+### **`nix_nix_versions`** - Get package version history from NixHub.io
+
+| Parameter | Description |
+|-----------|-------------|
+| `package` | Package name |
+| `version` | Specific version to find (optional) |
+| `limit` | 1-50 |
+
+## Key Use-Cases
+
+| Use-Case | Tool/Command | Example |
+|----------|--------------|---------|
+| Search packages | `nix_nix` | `nix_nix action=search query=ripgrep source=nixos` |
+| Find options | `nix_nix` | `nix_nix action=options query=services.nginx source=nixos` |
+| Flake inputs | `nix_nix` | `nix_nix action=flake-inputs query=read source=flakes` |
+| Version history | `nix_nix_versions` | `nix_nix_versions package=nodejs` |
+| Temporary tool | `nix run` | `nix run nixpkgs#ripgrep -- search_term` |
+| Project env | `nix develop` | Loads `flake.nix` deps |
+| Pure shell | `nix-shell --pure` | Isolated env |
+
+## Agent Integration
+
+- **Query packages/options first**: Use `nix_nix` before assuming availability.
+- **Pin versions**: Check `nix_nix_versions` for stable choices.
+- **Generate configs**: Create `shell.nix`/flakes based on queries.
+- **Verify**: `nix --version` if needed.
+
+## Example `shell.nix`
+
+````nix
+{ pkgs ? import <nixpkgs> {} }:
+
+pkgs.mkShell {
+  buildInputs = with pkgs; [ nodejs_20 python311 ripgrep ];
+}
+````
+
+## Flake Creation for Packages
+
+**Guideline**: Create `flake.nix` for building packages, reproducible dev shells, multi-language support, and cross-platform compatibility.
+
+**Triggers**:
+- Building language-specific packages (e.g., Rust via `crane`).
+- Configurable dev environments (Rust/Node/Go/etc.).
+- Use `nix_nix` first: e.g., `nix_nix action=search query=crane source=flakes` for libs.
+
+**Key Structure**:
+- **inputs**: `nixpkgs`, `flake-parts`, lang tools (`crane`, `fenix`, etc.).
+- **outputs**: `packages.default`, `devShells.default` with `shellHook`.
+- Multi-system: `x86_64-linux`, `aarch64-darwin`, etc.
+
+**Example `flake.nix`** (Rust MCP server + configurable dev envs via `dev-environments`):
+
+````nix
+{
+  description = "Rust documentation MCP server";
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    dev-environments.url = "github:Govcraft/dev-environments";
+    crane = {
+      url = "github:ipetkov/crane";
+    };
+  };
+  outputs =
+    inputs@{ flake-parts, nixpkgs, crane, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        inputs.dev-environments.flakeModules.rust
+        inputs.dev-environments.flakeModules.golang
+        inputs.dev-environments.flakeModules.node
+        inputs.dev-environments.flakeModules.typst
+      ];
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "aarch64-darwin"
+        "x86_64-darwin"
+      ];
+      perSystem =
+        {
+          config,
+          self',
+          inputs',
+          pkgs,
+          system,
+          ...
+        }:
+        let
+          craneLib = inputs.crane.mkLib pkgs;
+
+          # Common arguments shared between all builds
+          commonArgs = {
+            src = craneLib.cleanCargoSource ./.;
+            buildInputs = with pkgs; [
+              openssl
+            ] ++ pkgs.lib.optionals pkgs.stdenv.isDarwin [
+              # Additional darwin specific inputs
+              pkgs.darwin.apple_sdk.frameworks.Security
+              pkgs.darwin.apple_sdk.frameworks.SystemConfiguration
+            ];
+            nativeBuildInputs = with pkgs; [
+              pkg-config
+              perl
+            ];
+          };
+
+          # Build *just* the cargo dependencies
+          cargoArtifacts = craneLib.buildDepsOnly commonArgs;
+
+          # Build the actual crate itself
+          rustdocs-mcp-server = craneLib.buildPackage (commonArgs // {
+            inherit cargoArtifacts;
+          });
+        in
+        {
+          # Add the package
+          packages = {
+            default = rustdocs-mcp-server;
+            rustdocs-mcp-server = rustdocs-mcp-server;
+          };
+
+          # Golang Development Environment Options
+          # ----------------------------------
+          # enable: boolean - Enable/disable the Golang environment
+          # goVersion: enum - Go toolchain version ("1.18", "1.19", "1.20", "1.21, "1.22", "1.23") (default: "1.23")
+          # withTools: list of strings - Additional Go tools to include (e.g., "golint", "gopls")
+          # extraPackages: list of packages - Additional packages to include
+          go-dev = {
+            # enable = true;
+            # goVersion = "1.23";
+            # withTools = [ "gopls" "golint" ];
+            # extraPackages = [ ];
+          };
+
+          # Rust Development Environment Options
+          # ----------------------------------
+          # enable: boolean - Enable/disable the Rust environment
+          # rustVersion: enum - Rust toolchain ("stable", "beta", "nightly") (default: "stable")
+          # withTools: list of strings - Additional Rust tools to include (converted to cargo-*)
+          # extraPackages: list of packages - Additional packages to include
+          # ide.type: enum - IDE preference ("rust-rover", "vscode", "none") (default: "none")
+          rust-dev = {
+            enable = true;
+            rustVersion = "stable";
+            # Example configuration:
+            # withTools = [ ];  # Will be prefixed with cargo-
+            extraPackages = [ pkgs.openssl pkgs.openssl.dev pkgs.pkg-config ]; # Add openssl libs, dev libs, and pkg-config
+            # ide.type = "none";
+          };
+
+          # Node.js Development Environment Options
+          # -------------------------------------
+          # enable: boolean - Enable/disable the Node environment
+          # nodeVersion: string - Version of Node.js to use (default: "20")
+          # withTools: list of packages - Global tools to include (default: ["typescript" "yarn" "pnpm"])
+          # extraPackages: list of packages - Additional packages to include
+          # ide.type: enum - IDE preference ("vscode", "webstorm", "none") (default: "none")
+          node-dev = {
+            # Example configuration:
+            # enable = true;
+            # nodeVersion = "20";
+            # withTools = [ "typescript" "yarn" "pnpm" ];
+            # extraPackages = [ ];
+            # ide.type = "none";
+          };
+
+          typst-dev = {
+            # Example configuration:
+            # enable = true;
+            # withTools = [ "typst-fmt" "typst-lsp" ];
+            # extraPackages = [ ];
+            # ide.type = "none";
+          };
+          # Create the combined shell
+          devShells.default = pkgs.mkShell {
+            buildInputs = nixpkgs.lib.flatten (nixpkgs.lib.attrValues config.env-packages ++ [ ]);
+            # Combine existing hooks with new exports for OpenSSL
+            shellHook = ''
+              ${nixpkgs.lib.concatStringsSep "\n" (nixpkgs.lib.attrValues config.env-hooks)}
+
+              # Export paths for openssl-sys build script
+              export OPENSSL_DIR="${pkgs.openssl.out}"
+              export OPENSSL_LIB_DIR="${pkgs.openssl.out}/lib"
+              export OPENSSL_INCLUDE_DIR="${pkgs.openssl.dev}/include"
+              # Ensure pkg-config can find the openssl .pc file
+              export PKG_CONFIG_PATH="${pkgs.openssl.dev}/lib/pkgconfig:${pkgs.pkg-config}/lib/pkgconfig:$PKG_CONFIG_PATH"
+              # Debug: List contents of OpenSSL lib directory to verify
+              echo "OpenSSL lib directory contents:"
+              ls -la ${pkgs.openssl.out}/lib || echo "Failed to list OpenSSL lib directory"
+              echo ">>> OpenSSL environment variables set by shellHook <<<"
+            '';
+          };
+
+          # Add app for `nix run`
+          apps = {
+            default = {
+              type = "app";
+              program = "${rustdocs-mcp-server}/bin/rustdocs_mcp_server";
+            };
+          };
+        };
+    };
+}
+````
+
+**Usage**:
+- `nix develop` for dev shell.
+- `nix build` for package.
+- `nix run` for app.
+
+## uv2nix for Python Projects
+
+**When to use**: Python projects with `uv.lock` - handles complex dependencies not in nixpkgs.
+
+**Inputs needed**:
+```nix
+pyproject-nix.url = "github:pyproject-nix/pyproject.nix";
+uv2nix.url = "github:pyproject-nix/uv2nix";
+pyproject-build-systems.url = "github:pyproject-nix/build-system-pkgs";
+```
+
+**Critical API details**:
+- Function is `loadWorkspace`, NOT `loadUvWorkspace` (despite tool name)
+- Use `python = pkgs.python313`, NOT `inherit (pkgs) python313`
+- Creates virtual environments via `mkVirtualEnv`, not traditional derivations
+
+**Overlay composition order** (must be exact):
+1. `pyproject-build-systems.overlays.default`
+2. Project overlay from `workspace.mkPyprojectOverlay`
+3. Custom `pyprojectOverrides`
+
+**Pattern**:
+```nix
+workspace = uv2nix.lib.workspace.loadWorkspace { workspaceRoot = ./.; };
+overlay = workspace.mkPyprojectOverlay { sourcePreference = "wheel"; };
+pythonSet = (pkgs.callPackage pyproject-nix.build.packages {
+  python = pkgs.python313;
+}).overrideScope (lib.composeManyExtensions [
+  pyproject-build-systems.overlays.default
+  overlay
+  pyprojectOverrides
+]);
+in {
+  packages.default = pythonSet.mkVirtualEnv "env-name" workspace.deps.default;
+}
+```
+
+**Output**: Virtual env with executables in `result/bin/<package-name>`.
+
+## Prohibitions
+
+- Avoid non-reproducible installs (e.g., `apt`).
+- Avoid non-declarative package management (e.g., `nix-env -iA nixos.ripgrep` or `nix profile add nixpkgs#ripgrep`)
+- Always check Nix tools first.
+
+**Next**: Query a package with `nix_nix` or generate `shell.nix`.
--- a/.ruler/99-OPENSKILLS.md
+++ b/.ruler/99-OPENSKILLS.md
@@ -0,0 +1,106 @@
+# 99-OPENSKILLS
+
+<skills_system priority="1">
+
+## Available Skills
+
+<!-- SKILLS_TABLE_START -->
+<usage>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+How to use skills:
+- Invoke: `openskills read <skill-name>` (run in your shell)
+  - For multiple: `openskills read skill-one,skill-two`
+- The skill content will load with detailed instructions on how to complete the task
+- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)
+
+Usage notes:
+- Only use skills listed in <available_skills> below
+- Do not invoke a skill that is already loaded in your context
+- Each skill invocation is stateless
+</usage>
+
+<available_skills>
+
+<skill>
+<name>auth-implementation-patterns</name>
+<description>Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing APIs, or debugging security issues.</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>broken-authentication</name>
+<description>"Identify and exploit authentication and session management vulnerabilities in web applications. Broken authentication consistently ranks in the OWASP Top 10 and can lead to account takeover, identity theft, and unauthorized access to sensitive systems."</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>bun-development</name>
+<description>"Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by [oven-sh/bun](https://github.com/oven-sh/bun)."</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>drizzle-orm-expert</name>
+<description>"Expert in Drizzle ORM for TypeScript — schema design, relational queries, migrations, and serverless database integration. Use when building type-safe database layers with Drizzle."</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>grill-me</name>
+<description>Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>nextjs-app-router-patterns</name>
+<description>Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, implementing SSR/SSG, or optimizing React Server Components.</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>nextjs-best-practices</name>
+<description>"Next.js App Router principles. Server Components, data fetching, routing patterns."</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>nextjs-developer</name>
+<description>"Use when building Next.js 14+ applications with App Router, server components, or server actions. Invoke to configure route handlers, implement middleware, set up API routes, add streaming SSR, write generateMetadata for SEO, scaffold loading.tsx/error.tsx boundaries, or deploy to Vercel. Triggers on: Next.js, Next.js 14, App Router, RSC, use server, Server Components, Server Actions, React Server Components, generateMetadata, loading.tsx, Next.js deployment, Vercel, Next.js performance."</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>react-nextjs-development</name>
+<description>"React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns."</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>tdd</name>
+<description>Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>typescript-advanced-types</name>
+<description>Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>typescript-expert</name>
+<description>TypeScript and JavaScript expert with deep knowledge of type-level programming, performance optimization, monorepo management, migration strategies, and modern tooling.</description>
+<location>project</location>
+</skill>
+
+<skill>
+<name>typescript-pro</name>
+<description>Implements advanced TypeScript type systems, creates custom type guards, utility types, and branded types, and configures tRPC for end-to-end type safety. Use when building TypeScript applications requiring advanced generics, conditional or mapped types, discriminated unions, monorepo setup, or full-stack type safety with tRPC.</description>
+<location>project</location>
+</skill>
+
+</available_skills>
+<!-- SKILLS_TABLE_END -->
+
+</skills_system>
--- a/.ruler/AGENTS.md
+++ b/.ruler/AGENTS.md
@@ -0,0 +1 @@
+AGENTS.md
--- a/.ruler/chrome-devtools-openurl.sh
+++ b/.ruler/chrome-devtools-openurl.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# Get the absolute path of this script
+SCRIPT_PATH="$(realpath "$0")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+SCRIPT_NAME="$(basename "$SCRIPT_PATH")"
+
+# Target directory is ../.chrome relative to script location
+TARGET_DIR="$(realpath "$SCRIPT_DIR/../.chrome" 2>/dev/null || echo "$SCRIPT_DIR/../.chrome")"
+TARGET_PATH="$TARGET_DIR/$SCRIPT_NAME"
+
+# Check if script is NOT in the .chrome directory
+if [[ "$SCRIPT_DIR" != "$TARGET_DIR" ]]; then
+	# Create .chrome directory if it doesn't exist
+	if [[ ! -d "$TARGET_DIR" ]]; then
+		mkdir -p "$TARGET_DIR"
+	fi
+
+	# Move script to .chrome directory
+	mv "$SCRIPT_PATH" "$TARGET_PATH"
+	chmod +x "$TARGET_PATH"
+
+	# Execute from new location and exit
+	exec "$TARGET_PATH" "$@"
+	# If we get here, exec failed
+	echo "Failed to execute from $TARGET_PATH" >&2
+	exit 1
+fi
+
+SOCKET_PATH="${SOCKET_PATH:-$TARGET_DIR/chrome-devtools-mcp.sock}"
+
+if [[ "$SOCKET_PATH" != /* ]]; then
+	SOCKET_PATH="$TARGET_DIR/$SOCKET_PATH"
+fi
+
+if [[ ! -S "$SOCKET_PATH" ]]; then
+	echo "No socket exists at $SOCKET_PATH" >&2
+	exit 1
+fi
+
+(
+	echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"bash","version":"1.0"}}}'
+	sleep 1
+	echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"navigate_page","arguments":{"url":"'"https://example.com"'"}}}'
+	sleep 3
+) | socat - UNIX-CONNECT:"$SOCKET_PATH"
--- a/.ruler/ruler.toml
+++ b/.ruler/ruler.toml
@@ -0,0 +1,105 @@
+# Ruler Configuration File
+# See https://ai.intellectronica.net/ruler for documentation.
+
+# To specify which agents are active by default when --agents is not used,
+# uncomment and populate the following line. If omitted, all agents are active.
+default_agents = ["opencode"]
+
+# Enable nested rule loading from nested .ruler directories
+# When enabled, ruler will search for and process .ruler directories throughout the project hierarchy
+nested = true
+
+# [gitignore]
+# enabled = true
+# local = false  # set true to write generated ignores to .git/info/exclude instead
+
+# --- Agent Specific Configurations ---
+# You can enable/disable agents and override their default output paths here.
+# Use lowercase agent identifiers: aider, amp, claude, cline, codex, copilot, cursor, jetbrains-ai, kilocode, pi, windsurf
+
+# [agents.copilot]
+# enabled = true
+# output_path = ".github/copilot-instructions.md"
+
+# [agents.aider]
+# enabled = true
+# output_path_instructions = "AGENTS.md"
+# output_path_config = ".aider.conf.yml"
+
+# [agents.gemini-cli]
+# enabled = true
+
+# --- MCP Servers ---
+# Define Model Context Protocol servers here. Two examples:
+# 1. A stdio server (local executable)
+# 2. A remote server (HTTP-based)
+
+# [mcp_servers.example_stdio]
+# command = "node"
+# args = ["scripts/your-mcp-server.js"]
+# env = { API_KEY = "replace_me" }
+
+# [mcp_servers.example_remote]
+# url = "https://api.example.com/mcp"
+# headers = { Authorization = "Bearer REPLACE_ME" }
+# 
+# mcp-template: mcp_servers
+#
+[mcp_servers."Better Auth"]
+url = "https://mcp.chonkie.ai/better-auth/better-auth-builder/mcp"
+type = "remote"
+#
+# [mcp_servers.beads]
+# command = "beads-mcp"
+# type = "stdio"
+#
+[mcp_servers.bun]
+url = "https://bun.com/docs/mcp"
+type = "remote"
+#
+[mcp_servers.chrome-devtools]
+command = "stdio-multiplexer"
+args = ["chrome-devtools-mcp", "--", "--user-data-dir=.chrome/profile"]
+env.SOCKET_PATH = ".chrome/chrome-devtools-mcp.sock"
+#
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"
+type = "remote"
+#
+[mcp_servers.next-devtools]
+command = "bun"
+args = ["/home/dstanchiev/projects/next-devtools-mcp/dist/index.js"]
+env.NEXT_TELEMETRY_DISABLED = "1"
+env.NEXT_DEVTOOLS_PKG_MANAGER = "bun"
+#
+# [mcp_servers.niri]
+# command = "niri-mcp-server"
+#
+# [mcp_servers.rustdocs]
+# command = "rustdocs-mcp"
+#
+[mcp_servers.shadcn]
+command = "bunx"
+args = ["--bun", "shadcn@latest", "mcp"]
+#
+# [mcp_servers.github]
+# url = "https://api.githubcopilot.com/mcp"
+# headers.Authorization = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+#
+[mcp_servers.grep-app]
+command = "grep-app-mcp-server"
+#
+[mcp_servers."openrouter.ai"]
+url = "https://openrouter.ai/docs/_mcp/server"
+type = "remote"
+#
+[mcp_servers.nix]
+command = "mcp-nixos"
+#
+# [mcp_servers.devenv]
+# command = "devenv"
+# args = ["mcp"]
+#
+# [mcp_servers.kagi]
+# command = "kagimcp"
+# env.KAGI_API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--- a/.ruler/skill-selector.yaml
+++ b/.ruler/skill-selector.yaml
@@ -0,0 +1,23 @@
+# skill-selector config
+# Repos can be GitHub shorthands (owner/repo), full URLs, or local paths
+repos:
+  - anthropics/skills
+  - BrownFineSecurity/iothackbot
+  - HacktronAI/skills
+  - Italink/UnrealClientProtocol
+  - Jeffallan/claude-skills
+  - SimoneAvogadro/android-reverse-engineering-skill
+  - SylphAI-Inc/skills
+  - buzzer-re/Rikugan
+  - coleam00/excalidraw-diagram-skill
+  - gmh5225/awesome-game-security
+  - kalil0321/reverse-api-engineer
+  - kevinpbuckley/VibeUE
+  - mattpocock/skills
+  - mukul975/Anthropic-Cybersecurity-Skills
+  - nyldn/claude-octopus
+  - pluginagentmarketplace/custom-plugin-game-developer
+  - sickn33/antigravity-awesome-skills
+  - tfriedel/claude-office-skills
+  - wshobson/agents
+  - ~/projects/ai-skills
				`@@ -0,0 +1 @@`
				`CRITICAL: Always use context7 when I need code generation, setup or configuration steps, or library/API documentation. This means you should automatically use the Context7 MCP tools to resolve library id and get library docs without me having to explicitly ask.`