adds mermaid charts to illustate env inheritance

Author: rsgalloway

README.md

@@ -15,6 +15,16 @@ Environment variable composition and activation layer for tools and processes.
 
 envstack focuses on **configuration and activation**, not dependency resolution.
 
+```mermaid
+flowchart TD
+  default[default.env] --> prod[prod.env]
+  prod --> dev[dev.env]
+  prod --> test[test.env]
+```
+
+Later layers override earlier ones. Use envstack -t VAR to trace where a value
+comes from.
+
 For the core concepts, see `docs/index.md`.
 
 ## Installation

docs/design.md

@@ -48,6 +48,19 @@ Stacks may be composed by:
 
 Variables flow through the stack according to precedence rules.
 
+```mermaid
+flowchart TD
+  base[base.env]
+  prod[prod.env]
+  project[project.env]
+  task[task.env]
+  keys[keys.env]
+
+  base --> prod --> project --> task
+  keys -. include .-> prod
+  keys -. include .-> project
+```
+
 ## Precedence and overrides
 
 Precedence in envstack is **explicit and ordered**.
@@ -81,6 +94,13 @@ variable.
 `ENVPATH` is an ordered, colon-separated list of directories that envstack
 searches when resolving environment names.
 
+envstack searches `ENVPATH` left-to-right; earlier entries win when the same env
+name exists in multiple locations:
+
+```bash
+ENVPATH=/mnt/tools/dev/env:/mnt/tools/prod/env
+```
+
 Resolution follows these rules:
 - Directories are searched left to right
 - Later entries override earlier ones

docs/examples.md

@@ -12,6 +12,11 @@ document every feature.
 
 This is the simplest envstack use case and a direct evolution of a `.env` file.
 
+```mermaid
+flowchart LR
+  base[default.env] --> local[local.env]
+```
+
 Typical characteristics:
 - One base environment
 - A small number of variables
@@ -32,6 +37,13 @@ Common use cases:
 A common pattern is to define a shared base environment and layer environment
 tiers on top (e.g. dev, prod, CI).
 
+```mermaid
+flowchart TD
+  base[default.env] --> prod[prod.env]
+  prod --> dev[dev.env]
+  prod --> test[test.env]
+```
+
 Typical characteristics:
 - A base environment defines common paths and defaults
 - Environment tiers override a small number of variables
@@ -52,8 +64,14 @@ Common use cases:
 Projects often share infrastructure but differ in paths, naming, or behavior.
 envstack models this naturally through inheritance and layering.
 
+```mermaid
+flowchart LR
+  base[default.env] --> prod[prod.env]
+  prod -. include .-> project[project.env]
+```
+
 Typical characteristics:
-- Facility or global base environment
+- Facility or global default environment
 - Project environment that includes the base
 - Minimal duplication of shared configuration
 
@@ -72,6 +90,11 @@ Common use cases:
 This pattern combines multiple layers into a single stack, with each layer
 responsible for a specific concern.
 
+```mermaid
+flowchart LR
+  default --> env --> project --> task
+```
+
 Typical characteristics:
 - Clear separation of responsibility per layer
 - Downstream layers override upstream values