feat: update contributing guidelines and enhance documentation clarity

Author: jeffleyd

CONTRIBUTING.md

@@ -1,177 +1,113 @@
-# Contributing to DDLess Engine
+# Contributing
 
-Thanks for your interest in contributing! This document explains how to get started.
+## Setup
 
-## Getting Started
+Clone your fork at the root of a PHP project (alongside `composer.json`):
 
-1. Fork this repository
-2. Clone your fork at the root of a PHP project:
-   ```bash
-   cd /var/www/html          # your project root (must have composer.json)
-   git clone https://github.com/YOUR_USER/ddless-engine.git
-   cd ddless-engine
-   ```
-3. Make sure tests pass before making changes:
-   ```bash
-   php tests/run-all.php
-   ```
-
-## PHP Version Compatibility
-
-All code **must** work on PHP 7.4 through 8.4. This means:
-
-- No `mixed` type hints (use `#[\ReturnTypeWillChange]` where needed)
-- No named arguments in function calls
-- No `match` expressions
-- No enums (the engine detects them at runtime with `instanceof`)
-- No union types in signatures
-- No `readonly` properties
-- No fibers
-
-If you're unsure whether a feature is available on 7.4, check [php.net/migration80](https://www.php.net/migration80).
+```bash
+cd /var/www/html
+git clone https://github.com/YOUR_USER/ddless-engine.git
+cd ddless-engine
+php tests/run-all.php   # make sure everything passes first
+```
 
-## Project Structure
+## PHP compatibility
 
-```
-src/
-  debug.php              # Core engine (AST analysis, instrumentation, breakpoints)
-  http_trigger.php       # HTTP debug entry point
-  method_trigger.php     # Method debug entry point
-  task_trigger.php       # Task debug entry point
-  cli_trigger.php        # CLI debug entry point
-  frameworks/
-    laravel/             # Laravel-specific handlers
-    symfony/             # Symfony-specific handlers
-    codeigniter/         # CodeIgniter 4 handlers
-    tempest/             # Tempest handlers
-    wordpress/           # WordPress handlers
-    php/                 # Vanilla PHP handlers (minimal reference)
-  playground/            # Interactive terminal test suite
-  vendor-internal/       # Bundled PHP-Parser (do not modify)
-tests/
-  bootstrap.php          # Test runner and assertions
-  run-all.php            # Runs all test files
-  *Test.php              # Individual test files
-```
+All code must run on PHP 7.4 through 8.4. That means no:
 
-## Playground — Testing Your Changes
+- `mixed` type hints (use `#[\ReturnTypeWillChange]` where needed)
+- named arguments, `match`, union types, `readonly`, enums, fibers
 
-The playground lets you test the debug engine and framework integrations directly
-from the terminal, without the DDLess desktop app. Use it to validate your changes
-before submitting a PR.
+When in doubt: [php.net/migration80](https://www.php.net/migration80).
 
-### Setup
+## Playground
 
-Clone ddless-engine **at the root of a real PHP project** (alongside `composer.json`):
+The playground lets you test the engine and framework integrations from the terminal, without the desktop app. It expects ddless-engine to live inside a real PHP project:
 
 ```
-/var/www/html/                  ← your project root (has composer.json)
+/var/www/html/                  ← project root (has composer.json)
 ├── app/
 ├── vendor/
 ├── composer.json
-└── ddless-engine/              ← clone here
-    └── src/
-        ├── debug.php
-        ├── frameworks/
-        └── playground/
+└── ddless-engine/              ← your fork
 ```
 
-```bash
-cd /var/www/html                # go to your project root
-git clone https://github.com/YOUR_USER/ddless-engine.git
-cd ddless-engine                # all playground commands run from here
-```
-
-The playground auto-detects your project root by looking for `composer.json`
-one directory above `ddless-engine/`. All breakpoint paths (e.g.
-`app/Services/OrderService.php:38`) resolve relative to that project root.
+Each step validates a layer. If one fails, you know exactly where to look.
 
-### Step 1 — Engine Test
+### Engine test
 
-Validates the core debug engine (breakpoints, stepping, variable inspection).
+Validates breakpoints, stepping, and variable inspection:
 
 ```bash
-# Quick sanity check — no framework
 php src/playground/test_trigger.php --code '$x = 1; $y = 2; echo $x + $y;' --bp 2
 ```
 
-To test with a framework, create two files inside the ddless-engine directory:
+With a framework, create `boot.php` and a test file:
 
-**boot.php** — boots the framework (runs without stream wrapper):
 ```php
+// boot.php — boots the framework (runs without stream wrapper)
 <?php
-define('DDLESS_PROJECT_ROOT', dirname(__DIR__));  // points to actual project root
+define('DDLESS_PROJECT_ROOT', dirname(__DIR__));
 require __DIR__ . '/../vendor/autoload.php';
 $app = require __DIR__ . '/../bootstrap/app.php';
 $app->make(\Illuminate\Contracts\Console\Kernel::class)->bootstrap();
 ```
 
-**test_orders.php** — what you want to test:
 ```php
+// test_orders.php
 <?php
 $service = app(\App\Services\OrderService::class);
 $result = $service->calculate(42);
 var_dump($result);
 ```
 
 ```bash
-# Run with breakpoints inside the service code
 php src/playground/test_trigger.php --boot boot.php --file test_orders.php \
   --bp app/Services/OrderService.php:38
 ```
 
-`DDLESS_PROJECT_ROOT` in boot.php must point to your actual project root so that
-breakpoint paths like `app/Services/OrderService.php:38` resolve correctly.
-
-This is the first test when adding a new framework. If the boot works and breakpoints
-hit inside framework code, you understand the bootstrap — and can replicate it in
-the handlers.
-
-### Step 2 — Method Test
+### Method test
 
-Validates a framework's `method_executor.php` — resolves a class from the container
-and calls a method:
+Validates `method_executor.php` — resolves a class from the container and calls a method:
 
 ```bash
 php src/playground/test_trigger.php --test method --framework laravel \
   --class "App\Services\OrderService" --method calculate
 
-# With parameters
+# with parameters
 php src/playground/test_trigger.php --test method --framework laravel \
   --class "App\Services\OrderService" --method calculate \
   --params-file test_params.php
 
-# With breakpoints
+# with breakpoints
 php src/playground/test_trigger.php --test method --framework laravel \
   --class "App\Services\OrderService" --method calculate \
   --bp app/Services/OrderService.php:45
 ```
 
-### Step 3 — Task Test
+### Task test
 
-Validates a framework's `task_runner.php` — executes arbitrary PHP code with
-framework context:
+Validates `task_runner.php` — executes PHP code with framework context:
 
 ```bash
 php src/playground/test_trigger.php --test task --framework laravel \
   -c '$this->info("Users: " . User::count());' \
   -u "App\Models\User"
 
-# From a file
+# from a file
 php src/playground/test_trigger.php --test task --framework laravel \
   --file my_task.php
 ```
 
-### Step 4 — HTTP Test
+### HTTP test
 
-Validates a framework's `http_request.php` — sends real HTTP requests through
-the full pipeline:
+Validates `http_request.php` — sends real requests through the full pipeline:
 
 **Terminal 1:**
 ```bash
 DDLESS_FRAMEWORK=laravel php -S localhost:8080 src/playground/test_trigger.php
 
-# With breakpoints
+# with breakpoints
 DDLESS_FRAMEWORK=laravel DDLESS_BP="app/Http/Controllers/OrderController.php:45" \
   php -S localhost:8080 src/playground/test_trigger.php
 ```
@@ -183,30 +119,23 @@ curl -X POST http://localhost:8080/api/orders \
   -H "Content-Type: application/json" -d '{"item":"test"}'
 ```
 
-Each step validates a layer. If one fails, you know exactly where to look.
-See `src/playground/README.md` for full details and all options.
-
-## Adding a New Framework
-
-To add support for a new framework (e.g. CakePHP):
+See `src/playground/README.md` for all options and protocols.
 
-1. Create `src/frameworks/cakephp/` with three files:
+## Adding a framework
 
-   | File | Purpose |
-   |------|---------|
-   | `method_executor.php` | Resolve class from container, call method, output result |
-   | `task_runner.php` | Boot framework, eval user code with `DdlessTask` context |
-   | `http_request.php` | Process HTTP request through full middleware pipeline |
+To add support for a new framework (e.g. CakePHP), create `src/frameworks/cakephp/` with:
 
-2. Use `src/frameworks/php/` as a minimal reference and `src/frameworks/laravel/` as a full example.
+| File | Purpose |
+|------|---------|
+| `method_executor.php` | Resolve class from container, call method, output result |
+| `task_runner.php` | Boot framework, eval user code with `DdlessTask` context |
+| `http_request.php` | Process HTTP request through the full middleware pipeline |
 
-3. Test with the playground (Steps 2, 3, 4 above).
+Use `src/frameworks/php/` as a minimal reference and `src/frameworks/laravel/` as a full one. Validate with the playground steps above.
 
-4. See `src/playground/README.md` for input/output protocols of each handler.
+## Writing tests
 
-## Writing Tests
-
-Tests use a zero-dependency mini test runner defined in `tests/bootstrap.php`.
+Tests use a zero-dependency runner defined in `tests/bootstrap.php`:
 
 ```php
 <?php
@@ -230,22 +159,21 @@ if (basename(__FILE__) === basename($_SERVER['SCRIPT_FILENAME'] ?? '')) {
 
 Available assertions: `assert_eq`, `assert_true`, `assert_false`, `assert_null`, `assert_not_null`, `assert_contains`, `assert_not_contains`, `assert_array_has_key`, `assert_array_not_has_key`, `assert_count`.
 
-## Submitting Changes
-
-1. Create a branch from `main`
-2. Write or update tests for your changes
-3. Test with the playground to validate framework integrations
-4. Make sure all tests pass: `php tests/run-all.php`
-5. Open a Pull Request with a clear description of what you changed and why
+## Submitting changes
 
-## What Not to Modify
+1. Branch from `main`
+2. Write or update tests
+3. Validate with the playground
+4. `php tests/run-all.php` — all green
+5. Open a PR with a clear description of what and why
 
-- `src/vendor-internal/` — This is a bundled copy of nikic/PHP-Parser. Changes here will be overwritten.
+## Don't modify
 
-## Reporting Issues
+`src/vendor-internal/` is a bundled copy of nikic/PHP-Parser. Changes will be overwritten.
 
-Open an issue on this repository. Include:
+## Reporting issues
 
+Open an issue with:
 - PHP version (`php -v`)
-- A minimal code snippet that reproduces the problem
+- Minimal reproduction snippet
 - Expected vs actual behavior

README.md

@@ -1,67 +1,65 @@
-# DDLess PHP Debug Engine
+# ddless-engine
 
 ![Tests](https://github.com/behindSolution/ddless-engine/actions/workflows/tests.yml/badge.svg)
 
-> **This is the PHP engine only.** For the full debugging experience (desktop app, UI, AI Copilot, Task Runner), visit [ddless.com](https://ddless.com)
+The PHP runtime engine behind [DDLess](https://ddless.com) — a visual step-through debugger for PHP.
 
-The PHP runtime engine that powers [DDLess](https://ddless.com) — a visual debugger for PHP applications.
+This repo contains the engine only. The desktop app, UI, and AI Copilot are available at [ddless.com](https://ddless.com).
 
-This engine handles code instrumentation, breakpoint management, step-through execution, and variable inspection. It works with any PHP project (vanilla PHP, Laravel, Symfony, etc.) running on PHP 7.4+.
+## What it does
 
-## How It Works
+ddless-engine parses PHP source via AST ([nikic/PHP-Parser](https://github.com/nikic/PHP-Parser)), injects `ddless_step_check()` calls before each executable line using a custom stream wrapper, and communicates with the desktop app through file-based IPC. Your original files are never modified on disk.
 
-DDLess uses AST-based analysis (via [nikic/PHP-Parser](https://github.com/nikic/PHP-Parser)) to understand your code structure. It injects step-check calls before each executable line, allowing the debugger to pause, inspect variables, and control execution flow — all without modifying your original files.
+Supports breakpoints (conditional, logpoints, dumppoints), step-in/over/out, watch expressions, variable inspection, and trace mode.
 
-### Core Components
+## Frameworks
 
-| File | Purpose |
-|------|---------|
-| `src/debug.php` | Main engine — AST analysis, instrumentation, breakpoint handler, variable serialization |
-| `src/http_trigger.php` | Entry point for HTTP debug sessions |
-| `src/method_trigger.php` | Entry point for method-level debugging |
-| `src/task_trigger.php` | Entry point for task/command debugging |
-| `src/cli_trigger.php` | Entry point for CLI script debugging |
-| `src/frameworks/laravel/` | Laravel-specific request handling, method execution, task runner |
-| `src/frameworks/symfony/` | Symfony request handling, method execution, task runner |
-| `src/frameworks/codeigniter/` | CodeIgniter 4 request handling, method execution, task runner |
-| `src/frameworks/tempest/` | Tempest request handling, method execution, task runner |
-| `src/frameworks/wordpress/` | WordPress request handling, method execution, task runner |
-| `src/frameworks/php/` | Vanilla PHP request handling, method execution, task runner |
-| `src/vendor-internal/` | Bundled PHP-Parser (no Composer required) |
+Laravel · Symfony · CodeIgniter 4 · Tempest · WordPress · vanilla PHP
 
-### Key Functions
+## Project layout
 
-- `ddless_analyze_code_ast()` — Parses PHP source into AST and identifies instrumentable lines
-- `ddless_instrument_code_with_ast()` — Injects debug hooks into source code
-- `ddless_step_check()` — Called before every executable line, decides whether to pause
-- `ddless_handle_breakpoint()` — Pauses execution, captures state, waits for debugger command
-- `ddless_normalize_value()` — Serializes variables for display (handles objects, enums, DateTime, etc.)
+```
+src/
+├── debug.php                Core engine (AST analysis, instrumentation, breakpoint handler)
+├── http_trigger.php         Entry point for HTTP debug sessions
+├── method_trigger.php       Entry point for method-level debugging
+├── cli_trigger.php          Entry point for CLI script debugging
+├── task_trigger.php         Entry point for task/command debugging
+├── ssh_proxy_router.php     SSH remote debugging support
+├── frameworks/              Framework-specific request handling and bootstrapping
+│   ├── laravel/
+│   ├── symfony/
+│   ├── codeigniter/
+│   ├── tempest/
+│   ├── wordpress/
+│   └── php/
+├── sessions/                File-based IPC (runtime ↔ desktop app)
+├── cache/                   Pre-instrumented code cache
+└── vendor-internal/         Bundled PHP-Parser (no Composer required)
+```
 
 ## Requirements
 
-- PHP 7.4 or higher (tested up to 8.4)
-- `json` extension (included by default)
+- PHP 7.4+ (tested up to 8.4)
+- `json` extension (ships with PHP by default)
+- No external dependencies
 
-## Running Tests
+## Tests
 
 ```bash
 php tests/run-all.php
 ```
 
-Individual test files can also be run directly:
+Or run individually:
 
 ```bash
 php tests/NormalizeValueTest.php
 php tests/InstrumentCodeAstTest.php
 php tests/HttpRequestTest.php
 ```
 
-## Test Matrix
-
-Tests run automatically on every push and PR against PHP 7.4, 8.0, 8.1, 8.2, 8.3, and 8.4.
+CI runs against PHP 7.4, 8.0, 8.1, 8.2, 8.3, and 8.4 on every push and PR.
 
 ## License
 
-Source-available. You may read, audit, and report issues.
-Redistribution and derivative products are not permitted.
-See [LICENSE](LICENSE) for full terms.
+Source-available. See [LICENSE](LICENSE).