docs: update docs

Author: bcoles

CONTRIBUTING.md

@@ -288,7 +288,7 @@ version of this technique as `dmesg_free_reserved_area.c`, which additionally
 classifies the address by range and derives the physical address on coupled
 architectures. To see this exact result flow through a rule, the engine, and the
 rendered output, follow
-[the end-to-end walkthrough](../docs/architecture.md#a-leak-from-end-to-end).
+[the end-to-end walkthrough](docs/architecture.md#a-leak-from-end-to-end).
 
 Components that leak a physical address with a known extent (e.g. a
 `/proc/iomem` region) should use `kasld_result_range` to convey both

README.md

@@ -8,18 +8,20 @@
   <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"/>
 </p>
 
-KASLD derandomizes the Linux kernel's virtual and physical memory layout
-as an unprivileged local user. It recovers the kernel text base where a
-leak or side channel allows, and otherwise reduces it to the smallest set
-of placements the available evidence supports. On a fully-patched modern
+KASLD answers a practical question: **how effective is KASLR on this
+system, against an unprivileged local attacker?** It derandomizes the
+Linux kernel's virtual and physical memory layout from an unprivileged
+local process — recovering the kernel text base outright where a leak or
+side channel allows, and otherwise narrowing it to the smallest set of
+placements the available evidence supports. The inference engine fuses
+evidence from dozens of independent techniques with the architecture's
+known invariants, narrowing the kernel's placement to a residual window —
+reported as the surviving slot count and bits of entropy: a measure of
+how much protection KASLR actually retains. On a fully-patched modern
 kernel — where x86-64 side channels are mitigated and no direct
 kernel-text leak survives — full recovery is often impossible, but the
-constraint set is rarely empty. The inference engine combines parsed
-bootloader artifacts, `dmesg` landmarks, `/proc` and `/sys` facts, and
-architectural invariants to narrow the kernel's possible placement to a
-residual window, reported as the surviving slot count and bits of
-entropy. On architectures without KASLR, the engine locates the
-bootloader-chosen load address.
+constraint set is rarely empty. On architectures without KASLR, the
+engine locates the bootloader-chosen load address.
 
 Supports:
 
@@ -61,7 +63,7 @@ can temporarily relax these settings (requires root).
 The default text mode prints an answer-first overview:
 
 ```
-KASLD 0.3.0  --  Kernel ASLR derandomization
+KASLD 0.3.1-dev  --  Kernel ASLR derandomization
 Target: x86_64 / 6.15.6
 
 Running 83 components (10 experimental skipped; use -x to enable)...
@@ -71,9 +73,7 @@ Running 83 components (10 experimental skipped; use -x to enable)...
   Physical image base not derandomized     ~9 bits
                       0x0000000001000000 - 0x000000003c20ca00   (473 x 2.0 MiB)
   Direct map base     >= 0xffff800000000000
-
-  Coupling            virt and phys text are independent on this arch.
-                      A phys leak does NOT reveal the virt text base.
+  Phys/Virt Coupling  physical and virtual text randomize independently
 
 Leaks (1):
   virt kernel text    0xffffffff83800000   (prefetch)
@@ -92,6 +92,12 @@ details, explain mode, and hardening assessment.
 
 ## Documentation
 
+New to KASLD? Read in order: [docs/kaslr.md](docs/kaslr.md) (what KASLR is and
+what it randomizes) → [docs/architecture.md → A leak from end to
+end](docs/architecture.md#a-leak-from-end-to-end) (how KASLD turns one leak into
+an answer) → [CONTRIBUTING.md](CONTRIBUTING.md) (add a leak component or
+inference rule). The table below is the per-audience reference.
+
 | Audience | Document |
 |---|---|
 | End user / operator | [docs/usage.md](docs/usage.md) — CLI, output modes, explain mode, hardening assessment |

docs/architecture.md

@@ -22,6 +22,7 @@ mechanics of adding a component or rule, see
   - [Phases](#phases)
 - [The inference engine](#the-inference-engine)
   - [Three layers](#three-layers)
+  - [A constraint feeding the next pass](#a-constraint-feeding-the-next-pass)
   - [Soundness, monotonicity, and termination](#soundness-monotonicity-and-termination)
   - [Estimate narrowing and the store-vs-read seam](#estimate-narrowing-and-the-store-vs-read-seam)
   - [Design invariants: seams in the data flow](#design-invariants-seams-in-the-data-flow)
@@ -201,6 +202,38 @@ estimates then drive the reported summary, slot counts, and entropy. Every rule
 is listed once in `../src/engine_rules.c`, the single registry shared by the
 orchestrator and the test suite.
 
+### A constraint feeding the next pass
+
+The fixpoint earns its keep when one quantity's estimate is *input* to another
+rule. A worked example on x86_64, where the `vmalloc` base floor depends on the
+direct-map base (`Q_PAGE_OFFSET`):
+
+**Pass 1** — `randomize_memory_page_offset` reads a direct-map leak and a RAM
+base record and resolves `Q_PAGE_OFFSET`:
+
+```
+Q_PAGE_OFFSET    full VAS window  ->  0xffff8a0000000000
+Q_VMALLOC_BASE   unchanged — its rule has no tight PAGE_OFFSET to read yet
+```
+
+**Pass 2** — `x86_64_vmalloc_base_bound` now reads the tightened `Q_PAGE_OFFSET`
+plus `max_pfn` (the direct-map span, from physical memory size) and raises the
+`vmalloc` floor to `PAGE_OFFSET + directmap_span + PUD_SIZE`:
+
+```
+Q_VMALLOC_BASE   >= 0xffff8a0000000000 + 0x10000000000 + 0x40000000
+                 =  0xffff8b0040000000      (C_LOWER_BOUND, conf=inferred)
+```
+
+**Pass 3** — every rule re-runs; nothing narrows further, so the engine stops.
+
+The `vmalloc` floor could not have been computed in pass 1: its rule reads
+`est[Q_PAGE_OFFSET]`, which was still the full window until pass 1 tightened it.
+That is why the resolver iterates — and why rule order is irrelevant. Had the
+`vmalloc` rule run first, it would have read the wide `PAGE_OFFSET`, emitted a
+weak bound, and re-emitted the tight one on the next pass once `PAGE_OFFSET`
+resolved. Because estimates only narrow, re-emission can never undo progress.
+
 ### Soundness, monotonicity, and termination
 
 Three properties make that fixpoint well-defined and the result trustworthy:

docs/usage.md

@@ -88,7 +88,7 @@ derived from, and a hint about the verbose mode. No banner, no system
 config, no memory-layout diagram.
 
 ```
-KASLD 0.3.0  --  Kernel ASLR derandomization
+KASLD 0.3.1-dev  --  Kernel ASLR derandomization
 Target: x86_64 / 6.15.6
 
 Running 83 components (10 experimental skipped; use -x to enable)...
@@ -98,16 +98,19 @@ Running 83 components (10 experimental skipped; use -x to enable)...
   Physical image base not derandomized     ~9 bits
                       0x0000000001000000 - 0x000000003c20ca00   (473 x 2.0 MiB)
   Direct map base     >= 0xffff800000000000
-
-  Coupling            virt and phys text are independent on this arch.
-                      A phys leak does NOT reveal the virt text base.
+  Phys/Virt Coupling  physical and virtual text randomize independently
 
 Leaks (1):
   virt kernel text    0xffffffff83800000   (prefetch)
 
 [-v: detailed results, memory map, system info]  [-H: hardening assessment]
 ```
 
+Terms in this readout (slide, directmap, coupling, slot/entropy) are defined in
+the [kaslr.md glossary](kaslr.md#glossary); the engine vocabulary behind them
+(quantity, estimate, honest top) is in the
+[architecture.md glossary](architecture.md#glossary).
+
 ### Verbose (`-v`)
 
 `-v` (`--verbose`) restores the full banner, system-config block,
@@ -126,7 +129,7 @@ and a compact bracket-format virtual + physical memory layout:
     ███▐██▄     ███    ███          ███ ███       ███    ███
     ███ ▀███▄   ███    ███    ▄█    ███ ███▌    ▄ ███   ▄███
     ███   ▀█▀   ███    █▀   ▄████████▀  █████▄▄██ ████████▀
-    ▀                                   ▀ v0.3.0
+    ▀                                   ▀ v0.3.1-dev
 
 Kernel release:               6.15.6
 Kernel version:               #1 SMP PREEMPT_DYNAMIC Wed Jun 17 13:04:17 EDT 2026
@@ -666,8 +669,10 @@ their machine-readable metadata. The assessment has seven sections:
    no PRNG, insufficient memory). The kernel still relocates but lands
    at a firmware-/boot-stub-deterministic position rather than the
    link-time default — meaningfully different from a deliberate
-   opt-out, which the main results banner already reports. Omitted
-   when KASLR is healthy or opted out.
+   opt-out, which the main results banner already reports. The full set
+   of runtime states is catalogued in
+   [kaslr.md — KASLR runtime states](kaslr.md#kaslr-runtime-states).
+   Omitted when KASLR is healthy or opted out.
 
 2. **Active defenses** — runtime security settings detected on the system
    (`dmesg_restrict`, `kptr_restrict`, `perf_event_paranoid`, `%pK` pointer
@@ -694,6 +699,15 @@ their machine-readable metadata. The assessment has seven sections:
    represent leak vectors that cannot be blocked by runtime hardening
    alone.
 
+When the kernel-text function order can be determined, the assessment also
+prints a **Function layout** block above these sections: `text ordering`
+(canonical, or reordered static / per-boot) and `symbol resolution` (whether a
+generic `System.map` resolves symbols, or only this build's does). Reordered
+text is the [FG-KASLR / reordered-text class](kaslr.md#function-granular-kaslr-fg-kaslr)
+(LTO, AutoFDO, Propeller, or FG-KASLR): functions no longer sit at a constant
+offset from `_text`, so a leaked address pins only its own symbol and a generic
+`System.map` no longer locates the rest.
+
 The hardening assessment is also available in JSON output (`-j -H`),
 where it appears in a top-level `"hardening"` object with fields
 `exposure`, `kaslr_posture` (always present; `state` is one of