docs: refine descriptions and address inaccuracies across multiple guides

Ardenexal · Ardenexal · commit 6077ecba4edf · 2026-06-14T21:54:41.000+10:00
diff --git a/docs/README.md b/docs/README.md
@@ -6,10 +6,11 @@ icon: book-medical
 # Introduction
 
 PHP FHIR Tools is a PHP 8.3+ library monorepo for working with
-[FHIR](https://www.hl7.org/fhir/) (Fast Healthcare Interoperability Resources). It generates PHP
-model classes from FHIR Structure Definitions, serializes resources to and from JSON and XML,
-validates resources against the specification and Implementation Guides, and evaluates FHIRPath 2.0
-expressions.
+[FHIR](https://www.hl7.org/fhir/) (Fast Healthcare Interoperability Resources). FHIR is the HL7
+standard for exchanging healthcare data as structured resources such as `Patient`, `Observation`,
+and `Questionnaire`. This toolkit generates PHP model classes from FHIR Structure Definitions,
+serializes resources to and from JSON and XML, validates resources against the specification and
+Implementation Guides, and evaluates FHIRPath 2.0 expressions.
 
 {% hint style="info" %}
 The packages can be used independently or together. If you only need serialization, install
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -26,8 +26,8 @@
 * [Overview](serialization/overview.md)
 * [JSON Serialization](serialization/json.md)
 * [XML Serialization](serialization/xml.md)
-* [Serialization Context & Options](serialization/context.md)
-* [IG-Aware Serialization](serialization/ig-aware.md)
+* [Configuring Serialization Behavior](serialization/context.md)
+* [Serializing IG Extensions & Profiles](serialization/ig-aware.md)
 
 ## Validation
 
@@ -61,9 +61,9 @@
 
 ## Symfony Bundle
 
-* [Installation & Configuration](bundle/configuration.md)
-* [Services & Dependency Injection](bundle/services.md)
-* [Console Commands](bundle/console-commands.md)
+* [Install and Configure the Bundle](bundle/configuration.md)
+* [Inject and Use FHIR Services](bundle/services.md)
+* [Run the Console Commands](bundle/console-commands.md)
 * [Flex Recipe](bundle/flex-recipe.md)
 
 ## Reference
diff --git a/docs/bundle/configuration.md b/docs/bundle/configuration.md
@@ -3,7 +3,7 @@ description: Install and configure the FHIR Symfony bundle.
 icon: gear
 ---
 
-# Installation & Configuration
+# Install and configure the bundle
 
 The bundle (`Ardenexal\FHIRTools\Bundle\FHIRBundle\FHIRBundle`) registers all FHIR Tools services
 automatically in a Symfony application: serialization, validation, code generation, and FHIRPath.
@@ -57,6 +57,7 @@ fhir:
     cache_directory: '%kernel.cache_dir%/fhir'
 
     # Default FHIR version: R4, R4B, or R5
+    # (the Flex recipe overrides this to R4B via the FHIR_DEFAULT_VERSION env var)
     default_version: 'R4'
 
     validation:
diff --git a/docs/bundle/console-commands.md b/docs/bundle/console-commands.md
@@ -3,7 +3,7 @@ description: Console commands provided by the FHIR bundle.
 icon: terminal
 ---
 
-# Console Commands
+# Run the bundle's console commands
 
 The bundle adds these commands to a Symfony application:
 
diff --git a/docs/bundle/services.md b/docs/bundle/services.md
@@ -3,7 +3,7 @@ description: Inject and use FHIR Tools services in a Symfony application.
 icon: diagram-project
 ---
 
-# Services & Dependency Injection
+# Inject and use FHIR services
 
 When the bundle is enabled, it registers the serialization, validation, code-generation, and
 FHIRPath services in the Symfony container. Each public service is available both by a `fhir.*`
diff --git a/docs/code-generation/base-models.md b/docs/code-generation/base-models.md
@@ -64,7 +64,13 @@ composer run generate-models-all   # R4 + R4B + R5
 composer run generate-models       # fhir:generate with default (R4) packages
 ```
 
-## Core classes
+## Advanced: the programmatic API
+
+{% hint style="info" %}
+Most integrators only need the `fhir:generate` command above. This section documents the
+internal generator classes for people embedding code generation in their own tooling. Skip it if
+you are running the command.
+{% endhint %}
 
 The command orchestrates these generators (all under
 `Ardenexal\FHIRTools\Component\CodeGeneration\`):
diff --git a/docs/code-generation/implementation-guides.md b/docs/code-generation/implementation-guides.md
@@ -47,6 +47,10 @@ class PatientBirthPlaceExtension extends Extension
 }
 ```
 
+In FHIR, `value[x]` is an extension's polymorphic value element: it can hold one of several types
+(`valueString`, `valueAddress`, and so on). A *slice* is a named constraint that pins one entry of a
+repeating element to a specific shape.
+
 `FHIRExtensionGenerator` detects simple vs. complex extensions automatically: simple extensions
 narrow the `value[x]` type to a concrete PHP type, complex extensions map sub-extension slices to
 typed properties.
diff --git a/docs/code-generation/overview.md b/docs/code-generation/overview.md
@@ -6,9 +6,11 @@ icon: gears
 # Overview
 
 The Code Generation component loads FHIR packages from the registry and generates strongly-typed PHP
-classes — Resources, DataTypes, Primitives, and Enums — from their Structure Definitions and
-ValueSets. It is the engine behind the [`fhir:generate`](base-models.md) and
-[`fhir:generate-ig`](implementation-guides.md) console commands.
+classes from their definitions. A `StructureDefinition` is FHIR's machine-readable description of a
+resource or data type, and a `ValueSet` is a named set of permitted codes. The generator turns them
+into Resources, DataTypes, Primitives, and Enums. It is the engine behind the
+[`fhir:generate`](base-models.md) and [`fhir:generate-ig`](implementation-guides.md) console
+commands.
 
 Namespace: `Ardenexal\FHIRTools\Component\CodeGeneration\`.
 
diff --git a/docs/fhirpath/expressions.md b/docs/fhirpath/expressions.md
@@ -26,9 +26,8 @@ membership, and type operators.
 | **Type** | `is`, `as` | Type testing and casting |
 
 {% hint style="info" %}
-Equivalence (`~` / `!~`) is implemented: it is recognised by the lexer, parsed as a binary
-operator, and dispatched in the evaluator to the comparison service. (Earlier drafts described
-it as unimplemented — that is no longer accurate.)
+`~` tests equivalence and `!~` its negation. Equivalence differs from `=` by ignoring collection
+order and, for strings, case and whitespace.
 {% endhint %}
 
 ### Examples
@@ -67,10 +66,9 @@ The parser and evaluator support the core FHIRPath 2.0 syntax:
 
 ### Type system
 
-Types are resolved through `FHIRTypeResolver` and exposed as `TypeInfo`. The `is` operator tests
-whether an item conforms to a named type; `as` filters the collection to items of that type.
-Temporal values use dedicated types (`FHIRPathDate`, `FHIRPathDateTime`, `FHIRPathTime`) and
-decimals use `FHIRPathDecimal` to preserve precision.
+The `is` operator tests whether an item conforms to a named type, and `as` filters the collection
+to items of that type. Temporal values use dedicated types (`FHIRPathDate`, `FHIRPathDateTime`,
+`FHIRPathTime`), and decimals use `FHIRPathDecimal` to preserve precision.
 
 See the [Function Reference](functions/README.md) for the full library of built-in functions,
 including type-conversion helpers such as `toInteger()`, `toQuantity()`, and `ofType()`.
diff --git a/docs/fhirpath/functions/math.md b/docs/fhirpath/functions/math.md
@@ -25,3 +25,17 @@ Math functions operate on numeric values. Single-value functions (`abs()`,
 | `min()` | Smallest item in the collection. | `(3 \| 1 \| 2).min()` → `1` |
 | `max()` | Largest item in the collection. | `(3 \| 1 \| 2).max()` → `3` |
 | `avg()` | Arithmetic mean of the collection. | `(2 \| 4 \| 6).avg()` → `4` |
+
+## Precision & boundaries
+
+These three functions report or derive the precision of a value. They accept a
+decimal, integer, date, dateTime, or time, using FHIRPath positional precision
+numbers (e.g. `YYYY`=4, `YYYY-MM`=6, `YYYY-MM-DD`=8 for dates; digits after the
+decimal point for numbers). `lowBoundary()` and `highBoundary()` take an optional
+output-precision argument.
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `precision()` | Number of significant positions in the input. Trailing zeros on a decimal are preserved. | `(1.58700).precision()` → `5` |
+| `lowBoundary([precision])` | Lowest value in the natural range the input represents. For numbers, `value - 0.5×10^-precision`; for dates/times, fills unspecified components with their minimum. | `(1.587).lowBoundary()` → `1.5865...` |
+| `highBoundary([precision])` | Highest value in the natural range the input represents. For numbers, `value + 0.5×10^-precision`; for dates/times, fills unspecified components with their maximum. | `(1.587).highBoundary()` → `1.5875...` |
diff --git a/docs/fhirpath/overview.md b/docs/fhirpath/overview.md
@@ -5,8 +5,10 @@ icon: magnifying-glass
 
 # Overview & Quick Start
 
-A FHIRPath 2.0 expression evaluator: path navigation, filtering, aggregation, a broad library
-of built-in functions, and a FHIR-aligned type system with `is`/`as` support.
+FHIRPath is a query language for FHIR data, much like XPath for the resource tree. Use it to pull
+fields, filter collections, and test conditions without walking PHP objects by hand. This component
+is a FHIRPath 2.0 evaluator: path navigation, filtering, aggregation, a library of built-in
+functions, and a FHIR-aligned type system with `is`/`as` support.
 
 The public entry point is `FHIRPathService`
 (`Ardenexal\FHIRTools\Component\FHIRPath\Service\FHIRPathService`), which wraps lexing, parsing,
diff --git a/docs/fhirpath/status.md b/docs/fhirpath/status.md
@@ -24,10 +24,8 @@ and conversion expressions work, while a small number of spec edge cases remain
   reserved identifiers (`$this`, `$index`, `$total`), and expression compilation/caching.
 
 {% hint style="info" %}
-Every function in the registry is registered through `FunctionRegistry`. The previously
-documented "98 functions" figure has drifted from the code (for example `sort()` is registered
-but was absent from the old table). Treat the [Function Reference](functions/README.md) as the
-authoritative inventory rather than a fixed count.
+Treat the [Function Reference](functions/README.md) as the authoritative inventory of registered
+functions rather than a fixed count.
 {% endhint %}
 
 ## Known issues
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -38,12 +38,18 @@ Provides the Symfony Validator constraints and `FHIRValidationService`. It depen
 ```bash
 composer require ardenexal/fhir-path
 ```
+
+Provides the FHIRPath 2.0 engine (`FHIRPathService`). Depends only on `ardenexal/fhir-metadata`,
+not on the model classes.
 {% endtab %}
 
 {% tab title="Code Generation" %}
 ```bash
 composer require ardenexal/fhir-code-generation
 ```
+
+Generates model classes from FHIR packages. Needs the `zip` extension and pulls in
+`nette/php-generator` for code emission.
 {% endtab %}
 {% endtabs %}
 
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -27,10 +27,11 @@ use Ardenexal\FHIRTools\Component\Models\R4\Resource\PatientResource;
 
 $service = FHIRSerializationService::createDefault();
 
+$json = file_get_contents('patient.json');
 $patient = $service->deserializeFromJson($json, PatientResource::class);
 
 // Round-trip back to JSON (or use serializeToXml() for XML):
-$json = $service->serializeToJson($patient);
+$roundTripped = $service->serializeToJson($patient);
 ```
 
 {% hint style="info" %}
@@ -49,6 +50,7 @@ to also evaluate profile constraints; with none, only base constraints run.
 ```php
 use Ardenexal\FHIRTools\Component\Validation\FHIRValidationService;
 
+// $validationService is autowired from the container (see the note below)
 /** @var FHIRValidationService $validationService */
 $report = $validationService->validate($patient);
 
diff --git a/docs/models/namespaces.md b/docs/models/namespaces.md
@@ -31,8 +31,9 @@ use Ardenexal\FHIRTools\Component\Models\R4\Enum\AdministrativeGender;
 
 ## Backbone elements
 
-Backbone elements are nested in a sub-namespace named after their parent resource, so they
-never collide with same-named backbones on other resources:
+A backbone element is an inline nested structure defined within a single resource (for example
+`Patient.contact`). Generated backbone classes are nested in a sub-namespace named after their
+parent resource, so they never collide with same-named backbones on other resources:
 
 ```
 R4/Resource/
diff --git a/docs/serialization/context.md b/docs/serialization/context.md
@@ -3,7 +3,7 @@ description: Configure serialization with the immutable FHIRSerializationContext
 icon: sliders
 ---
 
-# Serialization Context & Options
+# Configuring serialization behavior
 
 `FHIRSerializationContext` is an immutable, chainable value object that configures how serialization
 behaves — validation mode, unknown-element policy, debug info, and more. Start from a format factory
@@ -28,6 +28,9 @@ The context is immutable — every `with*()` call returns a **new** instance and
 unchanged. Always capture the return value.
 {% endhint %}
 
+If the snippet above covers your needs — strict validation, rejecting unknown elements — you can
+stop here. The sections below document the full option surface.
+
 ## Factories and modifiers
 
 | Member | Effect |
diff --git a/docs/serialization/ig-aware.md b/docs/serialization/ig-aware.md
@@ -3,7 +3,7 @@ description: Serialize typed extension and profile classes from Implementation G
 icon: sitemap
 ---
 
-# IG-Aware Serialization
+# Serializing Implementation Guide extensions and profiles
 
 When you generate typed classes for an [Implementation Guide](../code-generation/implementation-guides.md),
 the serializer must be IG-aware to deserialize those typed extensions and profile subclasses into
@@ -24,8 +24,9 @@ $serializer = FHIRSerializationService::createWithIG(
 ```
 
 `createWithIG()` scans the base model `Extension` directories plus the optional IG output directory,
-building an IG type registry that enables typed extension deserialization, `meta.profile` URL
-resolution, and discriminator-based slice resolution.
+building an IG type registry. The registry deserializes typed extensions into their PHP classes,
+resolves `meta.profile` URLs to their profile classes, and picks the right class for a sliced
+element using the discriminator (the field an IG names to tell sliced entries apart).
 
 {% hint style="info" %}
 With no IG arguments, `createWithIG()` (and therefore `createDefault()`, which delegates to it)
diff --git a/docs/serialization/json.md b/docs/serialization/json.md
@@ -5,7 +5,11 @@ icon: brackets-curly
 
 # JSON Serialization
 
-FHIR model classes use promoted public properties — set values via the constructor's named
+`serializeToJson()` turns a FHIR model object into a JSON string. `deserializeFromJson()` reads JSON
+back into a typed model object. The round-trip below builds a `PatientResource`, serializes it, and
+deserializes it back.
+
+FHIR model classes use promoted public properties, so you set values through the constructor's named
 arguments or by assigning the public property. There are no `setX()` setters.
 
 ```php
@@ -56,8 +60,8 @@ $resource = $serializer->deserialize($json);          // format + class auto-det
 $resource = $serializer->deserialize($json, PatientResource::class); // explicit class
 ```
 
-Class resolution delegates to the type resolver, so `meta.profile` and the IG type registry are
-applied when available (see [IG-Aware Serialization](ig-aware.md)).
+Class resolution delegates to the type resolver, so it applies `meta.profile` and the IG type
+registry when available (see [IG-Aware Serialization](ig-aware.md)).
 
 ## Error handling
 
diff --git a/docs/validation/configuration.md b/docs/validation/configuration.md
@@ -5,9 +5,9 @@ icon: gear
 
 # Configuration
 
-Several validation concerns rely on pluggable services you wire yourself. Each ships with a
-null object so the feature degrades gracefully (silently skipped, or surfaced as an INFO
-violation) until you provide a real implementation.
+Several validation concerns rely on pluggable services you wire yourself. Each ships with a null
+object, so until you provide a real implementation the feature is skipped or surfaced as an INFO
+violation rather than failing.
 
 ## Terminology clients
 
@@ -21,6 +21,7 @@ flag plus an optional corrected display string).
 | `HttpFHIRTerminologyClient` | Calls a terminology server's `ValueSet/$validate-code` operation (GET by default, POST optional). Returns `false` / invalid on any HTTP, transport, or parse error (graceful degradation). |
 | `CachingFHIRTerminologyClient` | Decorator caching results. An in-process array cache is always active; a PSR-6 pool is optional for cross-request persistence. |
 | `NullFHIRTerminologyClient` | Null object — treats every code as valid. Equivalent to having no client: extensible/preferred checks are skipped. |
+| `InMemoryFHIRTerminologyClient` | Validates against a pre-loaded code map for offline and test use. Codes not in the map fall back to a configurable default (allow or deny). |
 | `PreferredServerAwareTerminologyClient` | Tries an ordered list of preferred clients, failing over to a fallback. Only a `\Throwable` triggers failover — a definitive `false` is final. |
 | `HttpFHIRTerminologyClientFactory` | Builds `HttpFHIRTerminologyClient` instances per server base URL (`createForServer()`), wrapping in a caching decorator when a pool is configured. |
 
@@ -88,17 +89,9 @@ $terminologyClient = new PreferredServerAwareTerminologyClient(
 
 When the client is `null` or a `NullFHIRTerminologyClient`, no violation is raised for invalid
 codes against extensible or preferred value sets. Instead each skipped check emits a single
-`fhir:unchecked-binding` INFO violation surfacing the coverage gap:
-
-```php
-$report = $service->validate($patient);
-
-if ($report->hasUncheckedBindings()) {
-    foreach ($report->uncheckedBindings() as $unchecked) {
-        echo $unchecked->message . "\n";
-    }
-}
-```
+`fhir:unchecked-binding` INFO violation surfacing the coverage gap. Query these via
+`FHIRValidationReport::hasUncheckedBindings()` — see
+[Terminology & Binding Validation](terminology.md) for the example.
 
 {% hint style="info" %}
 The `HttpClientInterface` is Symfony's HTTP client contract
diff --git a/docs/validation/extensions.md b/docs/validation/extensions.md
@@ -82,8 +82,10 @@ foreach ($report->info() as $info) {
 
 ## Obligations
 
-Obligation validation is opt-in and actor-scoped via `FHIRObligationContext`. When a context is
-provided, `collectObligationViolations()` enforces matching populate obligations
+An *obligation* is a statement in a profile that a particular actor (a system playing a role, such
+as a data producer or consumer) SHALL or SHOULD do something with an element — most commonly
+populate it. Obligation validation is opt-in and actor-scoped via `FHIRObligationContext`. When a
+context is provided, `collectObligationViolations()` enforces matching populate obligations
 (`SHALL`/`SHOULD:populate`) at ERROR/WARNING/INFO severity, and `applyNoErrorSuppression()`
 suppresses errors for `SHALL:no-error` obligations.
 
diff --git a/docs/validation/invariants.md b/docs/validation/invariants.md
@@ -5,7 +5,8 @@ icon: function
 
 # FHIRPath Invariant Validation
 
-Validates FHIRPath invariant expressions defined on Structure Definitions, via
+An *invariant* is a rule a FHIR resource must satisfy, written as a FHIRPath expression and
+identified by a `key` such as `obs-7`. This validator evaluates those expressions via
 `FHIRPathInvariantValidator` (backed by the [FHIRPath](../fhirpath/overview.md) engine). Each
 invariant is emitted as a `#[FHIRPathInvariant]` attribute carrying the invariant `key` (e.g.
 `obs-7`), `expression`, `human` message, and `severity`.
diff --git a/docs/validation/overview.md b/docs/validation/overview.md
@@ -10,6 +10,19 @@ attributes on the generated model classes: structural rules, FHIRPath invariants
 bindings, profiles, extension contexts, ranges, and obligations. It supports R4, R4B, and R5,
 and produces a structured [validation report](reports.md).
 
+## In this section
+
+* [Structural & Profile Validation](structural.md) — cardinality, slices, fixed and pattern values.
+* [FHIRPath Invariant Validation](invariants.md) — constraint expressions such as `obs-7`.
+* [Terminology & Binding Validation](terminology.md) — codes against ValueSet bindings.
+* [Reference & Target Profile Validation](references.md) — what a `Reference` may point to.
+* [Quantity & Temporal Range Validation](ranges.md) — `minValue` / `maxValue` bounds.
+* [Extensions, Modifiers & Obligations](extensions.md) — context, modifier, must-support, and obligation checks.
+* [Questionnaire Validation](questionnaire.md) — a separate validator for questionnaires and responses.
+* [The $validate Operation](operation-outcome.md) — producing an `OperationOutcome`.
+* [Configuration](configuration.md) — wiring terminology clients, resolvers, and obligation contexts.
+* [Validation Reports & Violation Codes](reports.md) — report structure and severity codes.
+
 ## Quick start
 
 ```php
diff --git a/docs/validation/questionnaire.md b/docs/validation/questionnaire.md
diff --git a/docs/validation/ranges.md b/docs/validation/ranges.md
diff --git a/docs/validation/terminology.md b/docs/validation/terminology.md
