docs: sync public docs with single-package layout

README.md

@@ -141,25 +141,24 @@ $users = new Collection<User>(
 vendor/bin/xphp compile <source> <target> <cache>
 ```
 
-| Argument   | Purpose                                                                              |
-|------------|--------------------------------------------------------------------------------------|
-| `<source>` | Directory of `.xphp` files (PSR-4 layout)                                            |
-| `<target>` | Where rewritten `.php` files land -- your user code with generic call sites replaced |
-| `<cache>`  | Where specialized classes live                                                       |
+| Argument   | Required | Default        | Purpose                                                                              |
+|------------|----------|----------------|--------------------------------------------------------------------------------------|
+| `<source>` | yes      | --             | Directory of `.xphp` files (PSR-4 layout)                                            |
+| `<target>` | no       | `dist`         | Where rewritten `.php` files land -- your user code with generic call sites replaced |
+| `<cache>`  | no       | `.xphp-cache`  | Where specialized classes live                                                       |
 
 p.s. you can `gitignore` files in `<target>` and `<cache>` as they can be generated in your CI/CD pipeline.
 
-#### Sample output 
+#### Sample output
+
+The sample below uses a readable name (`Collection_User`) for clarity. The compiler actually emits hashed FQNs of the form `\XPHP\Generated\App\Collection\T_<hash>` -- see the [generics reference](docs/type-system/generics/index.md) for the real scheme.
 
 ```php
 // <cache>/Generated/Collection_User.php
 namespace XPHP\Generated;
 
 use App\User;
 
-// p.s. in reality it uses a hash in the class name,
-// but developers won't touch that,
-// only php runtime will see the hashed names.
 class Collection_User {
     private array $items;
 
@@ -205,5 +204,5 @@ Meaning every place where generics are declared or used is converted into normal
 
 ## See also
 
-- [Type-system comparison](core/docs/type-system/comparison.md)
-- [Full generics reference](core/docs/type-system/generics/index.md)
+- [Type-system comparison](docs/type-system/comparison.md)
+- [Full generics reference](docs/type-system/generics/index.md)

docs/compiler.md

@@ -1,23 +1,25 @@
 # How the xphp compiler works
 
-Narrative walkthrough of the `core/` pipeline -- what `bin/xphp compile`
+Narrative walkthrough of the compile pipeline -- what `bin/xphp compile`
 does between reading `.xphp` source and writing vanilla `.php` files
 that any stock PHP 8.4 runtime can execute. Each phase is paired with
 a Mermaid diagram so the same information is available both
 visually and in prose.
 
 For the feature inventory ("what does xphp support today?") see
-[generics reference](generics/index.md). For the strategic comparison
-against TypeScript / Kotlin / Rust see [comparison](type-system/comparison.md).
-For the forward-looking inventory see [roadmap](roadmap.md).
+[generics reference](type-system/generics/index.md). For the strategic
+comparison against TypeScript / Kotlin / Rust see
+[comparison](type-system/comparison.md). For the forward-looking inventory
+see [roadmap](roadmap.md).
 
 ---
 
 ## Pipeline overview
 
-`bin/xphp compile <source-dir> <target-dir> <cache-dir>` runs a single
+`bin/xphp compile <source-dir> [target-dir] [cache-dir]` runs a single
 function -- [`Compiler::compile()`](../src/Transpiler/Monomorphize/Compiler.php)
--- that orchestrates five phases. The data flows top-down: source bytes
+-- that orchestrates five phases. Only `<source-dir>` is required; `[target-dir]`
+defaults to `dist` and `[cache-dir]` defaults to `.xphp-cache`. The data flows top-down: source bytes
 turn into AST, the AST populates a Registry and a TypeHierarchy, a
 fixed-point loop expands every concrete instantiation into a specialized
 class file, and finally the rewritten user code lands in the target
@@ -119,8 +121,8 @@ Two parser entry points exist:
   source.
 - `parseTolerantWithMap()` -- recovers from trailing parse errors
   by feeding the stripped source through nikic's error-handler-
-  collecting mode. Used by the LSP path so mid-edit source still
-  yields useful results.
+  collecting mode. Used when callers need partial results from
+  incomplete source.
 
 ---
 
@@ -370,16 +372,14 @@ birthday collisions are impossible at any practical project size.
 
 `ByteOffsetMap` carries the bytes-stripped-and-where info so any
 diagnostic span computed after the strip can be translated back to
-the original `.xphp` source. The map gets serialised through to
-the LSP layer too, so editor squiggles land on the right column
-even though the parsed AST was built from stripped source.
+the original `.xphp` source.
 
 ---
 
 ## Class roster
 
 Every class under
-[`core/src/Transpiler/Monomorphize/`](../src/Transpiler/Monomorphize/),
+[`src/Transpiler/Monomorphize/`](../src/Transpiler/Monomorphize/),
 grouped by role.
 
 ```mermaid

docs/roadmap.md

@@ -31,7 +31,6 @@ timeline
                 : XPHP_HASH_LENGTH configurable (16..64)
         Developer experience
                 : PSR-4 fixtures
-                : --lint headless CLI for CI (file,line,col error output)
     section Next
         Type system depth
                 : default type parameters

docs/type-system/comparison.md

@@ -105,10 +105,8 @@ class) is supported. `$obj->method<T>(...)` requires knowing the static type of
 properties, the static type is usually known at the call site; the unsolved part
 is the dispatch table when `$obj` is a union / intersection / interface.
 
-Tracked in `core/roadmap.md` under "Next". The LSP already substitutes
-type-args at instance call sites for hover / signature help / inlay hints --
-that's display-only inference; the compiler-level lowering for runtime dispatch
-is the gap.
+Tracked in the [roadmap](../roadmap.md) under "Next". The compiler-level
+lowering for runtime dispatch is the gap.
 
 ### 5. Reified type parameters
 

docs/type-system/generics/index.md

@@ -4,7 +4,7 @@ This document covers how `xphp` implements generics: what the compiler emits,
 what's supported today, the naming scheme for generated classes, and the
 trade-offs the monomorphization model accepts.
 
-For the broader project context, see the [README](/README.md).
+For the broader project context, see the [README](../../../README.md).
 
 ---
 
@@ -23,7 +23,7 @@ For comparison, Rust does also apply monomorphization. Kotlin and TypeScript
 don't do that, and there they have no runtime safety.
 
 Variance annotations based on monomorphization become real subtype edges between
-specialized classes -- that's in the [roadmap](../roadmap.md).
+specialized classes -- that's in the [roadmap](../../roadmap.md).
 
 ---
 
@@ -263,5 +263,5 @@ intentional.
 
 ## Type-system comparison
 
-See a [side-by-side comparison](./comparison.md) against TypeScript, Kotlin,
+See a [side-by-side comparison](../comparison.md) against TypeScript, Kotlin,
 and Rust -- including the features `xphp` doesn't have yet.