expressir 2.1.30 → 2.2.0

data/README.adoc

@@ -30,6 +30,132 @@ Expressir consists of 3 parts:
 // ** OMG UML 2 for Eclipse (XMI 2.1)
 
 
+== Features
+
+=== Remark preservation
+
+Expressir fully preserves EXPRESS remarks (comments) during parsing and formatting, maintaining them in their original positions:
+
+==== Preamble remarks
+
+Remarks between a scope declaration and its first child are preserved as preamble remarks:
+
+[source,express]
+----
+SCHEMA example;
+  -- This is a preamble remark
+  -- It appears after SCHEMA but before declarations
+
+  ENTITY person;
+    -- Entity preamble remark
+    name : STRING;
+  END_ENTITY;
+
+END_SCHEMA;
+----
+
+==== Inline tail remarks
+
+Remarks on the same line as attribute or enumeration item declarations:
+
+[source,express]
+----
+ENTITY person;
+  name : STRING; -- Inline remark for name attribute
+  age : INTEGER; -- Inline remark for age attribute
+END_ENTITY;
+
+TYPE status = ENUMERATION OF
+  (active,   -- Active status
+   inactive, -- Inactive status
+   pending); -- Pending status
+END_TYPE;
+----
+
+==== END_* scope remarks
+
+Remarks on END_TYPE, END_ENTITY, END_SCHEMA, etc. lines:
+
+[source,express]
+----
+TYPE status = ENUMERATION OF
+  (active,
+   inactive);
+END_TYPE; -- Status enumeration type
+
+ENTITY person;
+  name : STRING;
+END_ENTITY; -- Person entity
+
+END_SCHEMA; -- schema_name
+----
+
+==== Unicode support
+
+All remark types support full Unicode content:
+
+[source,express]
+----
+SCHEMA test;
+  -- 日本語、中文、한글 in remarks
+
+  ENTITY person;
+    name : STRING; -- Name in Japanese: 名前
+  END_ENTITY;
+
+END_SCHEMA; -- test
+----
+
+For implementation details, see link:docs/ARCHITECTURE.md#remark-attachment-system[Remark Attachment System].
+
+
+== Performance: Parsanol Integration
+
+Expressir uses the link:https://github.com/parsanol/parsanol-ruby[Parsanol] gem for high-performance parsing when available.
+
+=== Performance Comparison
+
+[cols="3,2,2,3"]
+|===
+| Mode | Time | Speedup | Notes
+
+| Ruby (Parsanol) | 3036 ms | 1x (baseline) | Pure Ruby parsing
+| Native Batch (Parsanol) | 153 ms | 19.9x faster | AST via u64 array transfer
+| Native ZeroCopy (Parsanol) | 106 ms | 28.7x faster | Zero-copy with source positions
+|===
+
+=== Features
+
+When Parsanol is installed:
+
+* **18-44x faster parsing** - Rust native backend
+* **99.5% fewer allocations** - Arena-based AST construction
+* **Source position tracking** - Slice objects for error reporting
+* **Streaming Builder API** - Zero-allocation custom parsing
+
+=== Usage
+
+Expressir automatically uses Parsanol when available:
+
+[source,ruby]
+----
+# Automatically uses Parsanol native parser when available
+repo = Expressir::Express::Parser.from_file("geometry.exp")
+
+# Check if native parser is being used
+if Parsanol::Native.available?
+  puts "Using Parsanol (Rust parser)"
+end
+----
+
+For maximum performance, ensure the Parsanol gem is installed:
+
+[source,sh]
+----
+gem install parsanol
+----
+
+
 == Installation
 
 Add this line to your application's `Gemfile`:
@@ -80,7 +206,8 @@ Commands:
   expressir clean PATH                         # Strip remarks and prettify EXPRESS schema at PATH
   expressir format PATH                        # pretty print EXPRESS schema located at PATH
   expressir help [COMMAND]                     # Describe available commands or one specific command
-  expressir validate *PATH                     # validate EXPRESS schema located at PATH
+  expressir validate load *PATH                # validate EXPRESS schema located at PATH
+  expressir validate ascii PATH                # Validate EXPRESS files for ASCII-only content (excluding remarks)
   expressir coverage *PATH                     # List EXPRESS entities and check documentation coverage
   expressir version                            # Expressir Version
 ----
@@ -97,9 +224,255 @@ expressir format schemas/resources/action_schema/action_schema.exp
 ----
 
 This command:
-1. Parses the EXPRESS schema
-2. Formats it with consistent indentation and spacing
-3. Outputs the formatted schema to stdout
+
+. Parses the EXPRESS schema
+. Formats it with consistent indentation and spacing
+. Outputs the formatted schema to stdout
+
+=== Pretty print with ELF compliance
+
+The `PrettyFormatter` class provides ELF (EXPRESS Language Foundation) compliant
+pretty printing with configurable formatting options. This formatter follows the
+https://www.express-language-foundation.org/pretty-print-spec/[ELF Pretty Print specification].
+
+==== Using PrettyFormatter in Ruby
+
+[source,ruby]
+----
+# Basic usage - formats with default settings
+repository = Expressir::Express::Parser.from_file("schema.exp")
+formatter = Expressir::Express::PrettyFormatter.new
+formatted = formatter.format(repository)
+puts formatted
+----
+
+==== Configuration options
+
+The PrettyFormatter supports several configuration options to customize the output.
+
+[source,ruby]
+----
+formatter = Expressir::Express::PrettyFormatter.new(
+  indent: 4,                    # Spaces per indentation level (default: 4)
+  line_length: 80,              # Maximum line length (default: nil)
+  provenance: true,             # Include provenance info (default: true)
+  provenance_name: "MyTool",    # Tool name (default: "Expressir")
+  provenance_version: "1.0.0",  # Tool version (default: Expressir::VERSION)
+  no_remarks: false             # Suppress remarks (default: false)
+)
+----
+
+[options="header"]
+|===
+| Option | Type | Default | Description
+
+| `indent`
+| Integer
+| `4`
+| Number of spaces per indentation level
+
+| `line_length`
+| Integer or nil
+| `nil`
+| Maximum line length (not yet enforced)
+
+| `provenance`
+| Boolean
+| `true`
+| Include provenance information in output
+
+| `provenance_name`
+| String
+| `"Expressir"`
+| Tool name for provenance
+
+| `provenance_version`
+| String
+| `Expressir::VERSION`
+| Tool version for provenance
+
+| `no_remarks`
+| Boolean
+| `false`
+| Suppress remarks from source schema
+|===
+
+==== Environment variable configuration
+
+Configuration can be overridden using environment variables. Environment variables
+take precedence over defaults but are overridden by explicit options:
+
+[source,sh]
+----
+# Set environment variables
+export EXPRESSIR_INDENT=2
+export EXPRESSIR_LINE_LENGTH=100
+export EXPRESSIR_PROVENANCE=false
+export EXPRESSIR_PROVENANCE_NAME="CustomTool"
+export EXPRESSIR_PROVENANCE_VERSION="2.0.0"
+
+# These will be used unless overridden by options
+ruby my_formatter.rb
+----
+
+[options="header"]
+|===
+| Environment Variable | Description
+
+| `EXPRESSIR_INDENT`
+| Indentation width (spaces)
+
+| `EXPRESSIR_LINE_LENGTH`
+| Maximum line length
+
+| `EXPRESSIR_PROVENANCE`
+| Enable/disable provenance (`true`/`false`)
+
+| `EXPRESSIR_PROVENANCE_NAME`
+| Tool name for provenance
+
+| `EXPRESSIR_PROVENANCE_VERSION`
+| Tool version for provenance
+|===
+
+The configuration follows a MECE (Mutually Exclusive, Collectively Exhaustive)
+hierarchy: **Options > ENV > Defaults**
+
+==== Key features
+
+The PrettyFormatter provides several enhancements over the standard formatter:
+
+CONSTANT alignment:: Constants in CONSTANT blocks are aligned at both the colon
+and assignment operator positions for improved readability.
++
+[example]
+====
+[source]
+----
+CONSTANT
+  short_name   : INTEGER := 1;
+  longer_name  : STRING  := 'test';
+  x            : REAL    := 3.14;
+END_CONSTANT;
+----
+====
+
+Provenance information:: Automatically includes metadata about the formatting
+tool and parameters used, aiding in reproducibility.
++
+[example]
+====
+[source]
+----
+(*
+  Generated by: Expressir version 2.1.31
+  Format parameters: indent: 4
+*)
+----
+====
+
+Configurable indentation:: Supports custom indentation width (2, 4, 8 spaces, etc.)
+to match project coding standards.
+
+Preamble support:: Preserves and formats source-level remarks that appear before
+the first SCHEMA declaration.
+
+==== Comparison with standard Formatter
+
+[options="header"]
+|===
+| Feature | Formatter | PrettyFormatter
+
+| Indentation
+| 2 spaces (fixed)
+| Configurable (default: 4)
+
+| CONSTANT alignment
+| No
+| Yes (colons and assignments)
+
+| Provenance
+| No
+| Yes (configurable)
+
+| Preamble formatting
+| No
+| Yes
+
+| Line length enforcement
+| No
+| Planned (not yet implemented)
+
+| ELF compliant
+| No
+| Yes
+
+| Configuration via ENV
+| No
+| Yes
+|===
+
+==== Example usage
+
+.Formatting with custom settings
+[example]
+====
+[source,ruby]
+----
+# Parse schema
+repository = Expressir::Express::Parser.from_file("examples/ler/simple_schema.exp")
+
+# Format with custom indentation and provenance
+formatter = Expressir::Express::PrettyFormatter.new(
+  indent: 2,
+  provenance_name: "MyFormatter",
+  provenance_version: "1.0.0"
+)
+
+formatted = formatter.format(repository)
+
+# Save to file
+File.write("formatted_schema.exp", formatted)
+----
+====
+
+.Formatting without provenance
+[example]
+====
+[source,ruby]
+----
+# Format without provenance information
+formatter = Expressir::Express::PrettyFormatter.new(provenance: false)
+repository = Expressir::Express::Parser.from_file("schema.exp")
+formatted = formatter.format(repository)
+
+# Output is clean without metadata comments
+puts formatted
+----
+====
+
+.Round-trip formatting verification
+[example]
+====
+[source,ruby]
+----
+# Format a schema
+original = Expressir::Express::Parser.from_file("schema.exp")
+formatter = Expressir::Express::PrettyFormatter.new
+
+# Format once
+formatted1 = formatter.format(original)
+
+# Parse the formatted output
+File.write("temp.exp", formatted1)
+reparsed = Expressir::Express::Parser.from_file("temp.exp")
+
+# Format again - should be identical (stable formatting)
+formatted2 = formatter.format(reparsed)
+
+puts "Formatting is stable" if formatted1 == formatted2
+----
+====
 
 === Clean schema
 
@@ -124,29 +497,136 @@ expressir clean schemas/resources/action_schema/action_schema.exp --output clean
 
 === Validate schema
 
-The `validate` command performs validation checks on EXPRESS schema files.
+The `validate load` command performs validation checks on EXPRESS schema files.
 
 It verifies:
 
-. That the schema can be parsed correctly
+. That the schema can be parsed correctly into the EXPRESS data model
 . That the schema includes a version string
 
 [source, sh]
 ----
 # Validate a single schema
-expressir validate schemas/resources/action_schema/action_schema.exp
+expressir validate load schemas/resources/action_schema/action_schema.exp
 
 # Validate multiple schemas
-expressir validate schemas/resources/action_schema/action_schema.exp schemas/resources/approval_schema/approval_schema.exp
+expressir validate load schemas/resources/action_schema/action_schema.exp schemas/resources/approval_schema/approval_schema.exp
+
+# Validate schemas from a schema manifest YAML
+expressir validate load schemas.yml
 ----
 
 The command reports any schemas that:
 
-* Failed to parse
+* Failed to parse into the EXPRESS data model
 * Are missing a version string
 
 If all validations pass, it will display "Validation passed for all EXPRESS schemas."
 
+=== Validate ASCII content
+
+The `validate ascii` command validates that EXPRESS schema files contain only
+ASCII characters outside of remarks. This ensures compatibility with systems
+that don't support Unicode, while allowing Unicode in documentation comments.
+
+[source, sh]
+----
+# Validate a single file
+expressir validate ascii schema.exp
+
+# Validate schema manifest YAML
+expressir validate ascii schemas.yml
+
+# Validate directory (non-recursive)
+expressir validate ascii schemas/
+
+# Validate directory recursively
+expressir validate ascii schemas/ --recursive
+
+# Output in YAML format
+expressir validate ascii schemas/ --yaml
+
+# Check remarks as well (include remarks in validation)
+expressir validate ascii schema.exp --check-remarks
+----
+
+The command checks that all EXPRESS code (excluding remarks) contains only
+7-bit ASCII characters. Tagged remarks (both embedded `(* ... *)` and tail
+`-- ...` comments) are excluded from validation, allowing documentation to
+contain Unicode without triggering errors.
+
+[options="header"]
+|===
+| Option | Description
+
+| `--recursive`, `-r`
+| Validate EXPRESS files under the specified path recursively
+
+| `--yaml`, `-y`
+| Output results in YAML format for programmatic processing
+
+| `--check-remarks`
+| Include remarks in ASCII validation (default: false, remarks are excluded)
+|===
+
+The validator provides:
+
+* Detailed violation reports with line and column numbers
+* Replacement suggestions (AsciiMath for math symbols, ISO 10303-11 encoding for others)
+* Summary statistics
+* Visual indicators for non-ASCII sequences
+
+This command is particularly useful before exporting schemas to formats that
+don't support Unicode, such as EEP (Express Engine Parser) and eengine (Express
+Engine).
+
+
+[example]
+====
+[source, sh]
+----
+$ expressir validate ascii spec/fixtures/validate_ascii/non_ascii_in_code.exp
+
+spec/fixtures/validate_ascii/non_ascii_in_code.exp:
+  Line 3, Column 9:
+      ENTITY 製品;
+             ^^ Non-ASCII sequence
+      "製" - Hex: 0x88fd, UTF-8 bytes: 0xe8 0xa3 0xbd
+      Replacement: ISO 10303-11: "000088FD"
+      "品" - Hex: 0x54c1, UTF-8 bytes: 0xe5 0x93 0x81
+      Replacement: ISO 10303-11: "000054C1"
+
+  ...
+  Line 10, Column 24:
+        symbol : STRING := 'μ';
+                            ^ Non-ASCII sequence
+      "μ" - Hex: 0x3bc, UTF-8 bytes: 0xce 0xbc
+      Replacement: AsciiMath: mu
+
+  ...
+
+  Found 7 non-ASCII sequence(s) in non_ascii_in_code.exp
+
+Summary:
+  Scanned 1 EXPRESS file(s)
+  Found 7 non-ASCII sequence(s) in 1 file(s)
+
+╭──────────────────────────────────────────────────────────────────────────╮
+│                       Non-ASCII Characters Summary                       │
+├──────────────────────────┬─────────────┬────────────────────┬────────────┤
+│ File                     │ Symbol      │ Replacement        │ Occurrenc… │
+├──────────────────────────┼─────────────┼────────────────────┼────────────┤
+│ validate_ascii/non_asci… │ "製" (0x88… │ ISO 10303-11: "00… │          1 │
+│ validate_ascii/non_asci… │ "品" (0x54… │ ISO 10303-11: "00… │          1 │
+│ ...                      │             │                    │            │
+│ validate_ascii/non_asci… │ "μ" (0x3bc) │ AsciiMath: mu      │          1 │
+│ ...                      │             │                    │            │
+│ TOTAL                    │ 10 unique   │ —                  │         11 │
+╰──────────────────────────┴─────────────┴────────────────────┴────────────╯
+----
+====
+
+
 === Version
 
 The `version` command displays the current version of the Expressir gem.
@@ -1026,9 +1506,10 @@ all_entities = Expressir::Coverage.find_entities(schema)
 puts "Found #{all_entities.size} entities in schema #{schema.id}"
 ----
 
-=== EXPRESS schema manifest
 
-==== General
+== EXPRESS schema manifests
+
+=== General
 
 The EXPRESS schema manifest is a file format defined by ELF at
 https://www.expresslang.org/docs[EXPRESS schema manifest specification].
@@ -1045,8 +1526,30 @@ The `SchemaManifest` class allows you to:
 * Save manifest configurations to files
 
 
+=== File format
+
+The schema manifest uses a structured YAML format:
+
+[source,yaml]
+----
+schemas:
+  - path: schemas/resources/action_schema/action_schema.exp
+    id: action_schema
+  - path: schemas/resources/approval_schema/approval_schema.exp
+    id: approval_schema
+  - path: schemas/resources/date_time_schema/date_time_schema.exp
+    id: date_time_schema
+----
+
+Each schema entry in the manifest can have the following attributes:
+
+`path`:: (Required) The file path to the EXPRESS schema file
+`id`:: (Optional) A unique identifier for the schema
+`container_path`:: (Optional) Container path information
+
+
 [example]
-.Example project structure with schema manifest:
+.Example project structure with schema manifest
 ====
 [source]
 ----
@@ -1073,9 +1576,362 @@ schemas:
 ----
 ====
 
-==== Creating a schema manifest
 
-===== From a YAML file
+=== Commands for schema manifests
+
+==== Creating a manifest from a root schema
+
+The `manifest create` command generates a schema manifest YAML file by
+resolving all referenced schemas starting from a specified root schema file.
+
+.`manifest create` - Generate schema manifest
+[source,sh]
+----
+Usage:
+  expressir manifest create ROOT_SCHEMA [MORE_SCHEMAS...] -o, --output=OUTPUT
+
+Options:
+  -o, --output=OUTPUT                                # Output YAML file path
+      [--base-dirs=BASE_DIRS]                        # Comma-separated base directories for schema resolution
+      [--verbose], [--no-verbose], [--skip-verbose]  # Show detailed output
+                                                     # Default: false
+
+Description:
+  Generate a YAML manifest of all schemas required for packaging.
+
+  The manifest uses the existing SchemaManifest format: schemas: schema_id: path:
+  /path/to/schema.exp
+
+  Workflow: 1. Create manifest from root schema 2. Edit manifest to add paths for
+  schemas with null paths 3. Validate manifest 4. Build package using manifest
+
+  Example: expressir manifest create schemas/activity/mim.exp \ -o
+  activity_manifest.yaml \ --base-dirs /path/to/schemas
+----
+
+Options:
+
+`--output, -o FILE`:: (Required) Output YAML file path
+
+`--base-dirs DIRS`:: Base directories for schema resolution (space-separated). Also supports comma-separated for backward compatibility.
++
+Searches for schema files using these patterns:
+schema files named according to schema ID::: `<SCHEMA_ID>.exp`
+schema files named in the STEP module pattern::: `<LOWERCASE_SCHEMA_WO_MIMARM>/{mim,arm}.exp`
++
+[source,sh]
+----
+# Space-separated (preferred)
+--base-dirs /path/to/schemas /another/path
+
+# Comma-separated (backward compatible)
+--base-dirs /path/to/schemas,/another/path
+----
+
+`--verbose`:: Show detailed output
+
+Base directories can be provided to help locate schema files:
+
+* During the resolving process, Expressir will search these directories for
+schema files matching known naming patterns.
+* Once a referenced schema is found, it will indicate from which source they
+were resolved.
+* If multiple matches are found, the first one encountered will be used, and a
+warning will be displayed for the user to manually edit the manifest if a
+different path is desired.
+
+In the case of unresolved schemas, the created manifest will include entries
+without the `path:` field. The manifest can then be edited manually to add the
+correct paths.
+
+
+.Creating a manifest from a root schema
+[example]
+====
+The following command creates a manifest starting from the
+`schemas/modules/activity/mim.exp` root schema, searching for referenced schemas
+in the `schemas/resources` and `schemas/modules` base directories.
+
+[source,sh]
+----
+$ expressir manifest create \
+  schemas/modules/activity/mim.exp \
+  -o new.yaml \
+  --base-dirs schemas/modules schemas/resources/ \
+  --verbose
+
+Creating manifest from 1 root schema(s)...
+  Base directories:
+    - [source 1]: ~/src/mn/iso-10303/schemas/modules
+    - [source 2]: ~/src/mn/iso-10303/schemas/resources/
+Resolving dependencies...
+  USE FROM action_schema (in mim): ✓ [source 2] action_schema/action_schema.exp
+  REFERENCE FROM basic_attribute_schema (in action_schema): ✓ [source 2] basic_attribute_schema/basic_attribute_schema.exp
+  REFERENCE FROM support_resource_schema (in basic_attribute_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+  REFERENCE FROM support_resource_schema (in action_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+  USE FROM Activity_method_mim (in mim): ✓ [source 1] activity_method/mim.exp
+  ...
+  REFERENCE FROM support_resource_schema (in management_resources_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+✓ Manifest created: new.yaml
+  Resolved schemas: 42
+  All schemas resolved successfully!
+----
+====
+
+.Creating a manifest from a root schema with unresolved schemas
+[example]
+====
+The following command creates a manifest starting from the
+`schemas/modules/activity/mim.exp` root schema, searching for referenced schemas
+in the `schemas/resources` base directory only (i.e. it will miss schemas
+in `schemas/modules`).
+
+[source,sh]
+----
+$ expressir manifest create \
+  -o manifest.yaml \
+  --base-dirs schemas/resources \
+  --verbose \
+  schemas/modules/activity/mim.exp
+
+Creating manifest from 1 root schema(s)...
+  Base directories:
+    - [source 1]: ~/src/mn/iso-10303/schemas/resources
+Resolving dependencies...
+  USE FROM action_schema (in mim): ✓ [source 1] action_schema/action_schema.exp
+  REFERENCE FROM basic_attribute_schema (in action_schema): ✓ [source 1] basic_attribute_schema/basic_attribute_schema.exp
+  REFERENCE FROM support_resource_schema (in basic_attribute_schema): ✓ [source 1] support_resource_schema/support_resource_schema.exp
+  REFERENCE FROM support_resource_schema (in action_schema): ✓ [source 1] support_resource_schema/support_resource_schema.exp
+  USE FROM Activity_method_mim (in mim): ✗ not found
+  ...
+  REFERENCE FROM support_resource_schema (in management_resources_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+✓ Manifest created: manifest.yaml
+  Resolved schemas: 41
+
+⚠ Unresolved schemas (1):
+  - Activity_method_mim
+
+Please edit manifest.yaml and set 'path:' for unresolved schemas
+Then validate with: expressir manifest validate manifest.yaml
+----
+====
+
+
+
+==== Resolving schemas from a manifest
+
+A schema manifest can be used as input to resolve and load all referenced
+schemas into a new manifest.
+
+
+[source,sh]
+----
+expressir manifest resolve MANIFEST -o, --output=OUTPUT
+----
+
+[source,sh]
+----
+Usage:
+  expressir manifest resolve MANIFEST -o, --output=OUTPUT
+
+Options:
+  -o, --output=OUTPUT                                # Output file path for resolved manifest
+      [--base-dirs=one two three]                    # Base directories for schema search (can be specified multiple times)
+      [--verbose], [--no-verbose], [--skip-verbose]  # Show detailed resolution progress
+                                                     # Default: false
+
+Description:
+  Resolve missing or incomplete schema paths in a manifest file.
+
+  This command attempts to find file paths for schemas with missing or empty
+  paths by searching in base directories using naming patterns:
+
+  Supported patterns:
+    - Resource schemas: {schema_name}.exp
+    - Module ARM/MIM: {module_name}/{arm|mim}.exp
+    Example: Activity_method_mim -> activity_method/mim.exp
+
+  The resolved manifest is written to the output file, leaving the original
+  unchanged.
+
+  Use this command after 'expressir manifest validate --check-references' fails
+  to automatically resolve missing schema paths.
+
+  Examples: # Resolve paths using manifest's existing base directories expressir
+  manifest resolve manifest.yaml -o resolved_manifest.yaml
+  # Resolve with explicit base directories
+  expressir manifest resolve manifest.yaml -o resolved.yaml \
+    --base-dirs /path/to/schemas,/another/path
+  # With verbose output
+  expressir manifest resolve manifest.yaml -o resolved.yaml --verbose
+----
+
+Options:
+
+`--output, -o FILE`:: (Required) Output file path for resolved manifest
+
+`--base-dirs DIRS`:: Base directories for schema search (space-separated). Also
+supports comma-separated for backward compatibility.
++
+Searches for schema files using these patterns:
+schema files named according to schema ID::: `<SCHEMA_ID>.exp`
+schema files named in the STEP module pattern::: `<LOWERCASE_SCHEMA_WO_MIMARM>/{mim,arm}.exp`
++
+[source,sh]
+----
+# Space-separated (preferred)
+--base-dirs /path/to/schemas /another/path
+
+# Comma-separated (backward compatible)
+--base-dirs /path/to/schemas,/another/path
+----
+
+`--verbose`:: Show detailed resolution progress
+
+.Fully resolving a schema manifest
+[example]
+====
+The following command resolves all schemas in the `manifest.yaml` file and writes the
+fully resolved manifest to `resolved_manifest.yaml`.
+
+[source,sh]
+----
+$ expressir manifest resolve manifest.yaml -o resolved.yaml --verbose
+
+Resolving schema paths in: manifest.yaml...
+  Using base directories:
+    - [source 1] ~/src/mn/iso-10303/schemas/
+Attempting to resolve paths...
+Resolving dependencies from 1 root schema(s)...
+  USE FROM action_schema (in mim): ✓ [source 1] resources/action_schema/action_schema.exp
+  REFERENCE FROM basic_attribute_schema (in action_schema): ✓ [source 1] resources/basic_attribute_schema/basic_attribute_schema.exp
+  REFERENCE FROM support_resource_schema (in basic_attribute_schema): ✓ [source 1] resources/support_resource_schema/support_resource_schema.exp
+  REFERENCE FROM support_resource_schema (in action_schema): ✓ [source 1] resources/support_resource_schema/support_resource_schema.exp
+  USE FROM Activity_method_mim (in mim): ✗ not found
+  USE FROM basic_attribute_schema (in mim): ✓ [source 1] resources/basic_attribute_schema/basic_attribute_schema.exp
+  USE FROM management_resources_schema (in mim): ✓ [source 1] resources/management_resources_schema/management_resources_schema.exp
+  ...
+  REFERENCE FROM support_resource_schema (in management_resources_schema): ✓ [source 1] resources/support_resource_schema/support_resource_schema.exp
+✓ Manifest resolved: resolved.yaml
+  Total schemas: 42
+  Resolved schemas: 41
+
+⚠ Unresolved schemas (1):
+  - Activity_method_mim
+
+These schemas could not be found in the search directories.
+You may need to:
+  1. Add more base directories with --base-dirs
+  2. Manually edit resolved.yaml and set their paths
+----
+====
+
+.Resolving a manifest with multiple base directories
+[example]
+====
+[source,sh]
+----
+$ expressir manifest resolve manifest.yaml \
+  -o resolved.yaml \
+  --base-dirs ~/src/mn/iso-10303/schemas/modules \
+              ~/src/mn/iso-10303/schemas/resources/ --verbose
+
+Resolving schema paths in: manifest.yaml...
+  Using base directories:
+    - [source 1]: ~/src/mn/iso-10303/schemas/modules
+    - [source 2]: ~/src/mn/iso-10303/schemas/resources/
+Attempting to resolve paths...
+Resolving dependencies from 1 root schema(s)...
+  Using base directories:
+    - [source 1]: ~/src/mn/iso-10303/schemas/modules
+    - [source 2]: ~/src/mn/iso-10303/schemas/resources
+  USE FROM action_schema (in mim): ✓ [source 2] action_schema/action_schema.exp
+  REFERENCE FROM basic_attribute_schema (in action_schema): ✓ [source 2] basic_attribute_schema/basic_attribute_schema.exp
+  REFERENCE FROM support_resource_schema (in basic_attribute_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+  REFERENCE FROM support_resource_schema (in action_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+  USE FROM Activity_method_mim (in mim): ✓ [source 1] activity_method/mim.exp
+  ...
+  REFERENCE FROM support_resource_schema (in management_resources_schema): ✓ [source 2] support_resource_schema/support_resource_schema.exp
+✓ Manifest resolved: resolved.yaml
+  Total schemas: 42
+  Resolved schemas: 42
+  All schema paths resolved successfully!
+----
+====
+
+
+==== Validating a manifest
+
+A schema manifest can be validated to ensure all referenced schemas are fully
+resolvable and correctly defined.
+
+.`manifest validate` - Validate manifest
+[source,sh]
+----
+expressir manifest validate MANIFEST.yaml [OPTIONS]
+----
+
+[source,sh]
+----
+Usage:
+  expressir manifest validate MANIFEST
+
+Options:
+  [--verbose], [--no-verbose], [--skip-verbose]                             # Show detailed validation results
+                                                                            # Default: false
+  [--check-references], [--no-check-references], [--skip-check-references]  # Validate referential integrity using dependency resolver
+                                                                            # Default: false
+
+Description:
+  Validate a schema manifest file.
+
+  Validation types: - File existence: All schema paths exist on disk - Path
+  completeness: All schemas have paths specified (warnings) - Referential integrity
+  (--check-references): All USE/REFERENCE FROM resolve
+
+  Examples: # Basic validation (file existence and path completeness) expressir manifest
+  validate activity_manifest.yaml # With referential integrity checking expressir
+  manifest validate activity_manifest.yaml --check-references # With verbose output
+  expressir manifest validate activity_manifest.yaml --check-references --verbose
+----
+
+Options:
+
+`--verbose`:: Show detailed validation results
+
+`--check-references`:: Validate referential integrity using dependency resolver
+
+.Validating a manifest to ensure all dependencies are defined
+[example]
+====
+Checking `REFERENCE FROM` and `USE FROM` references to ensure all dependencies
+are defined in EXPRESS schemas included in the manifest:
+
+[source,sh]
+----
+$ expressir manifest validate manifest.yaml --check-references --verbose
+
+Validating manifest: manifest.yaml...
+Checking referential integrity...
+Validating referential integrity for 42 schemas...
+
+  USE FROM action_schema (in Activity_method_mim): ✓ action_schema.exp
+  REFERENCE FROM basic_attribute_schema (in action_schema): ✓ basic_attribute_schema.exp
+...
+  USE FROM action_schema (in mim): ✓ action_schema.exp
+...
+  REFERENCE FROM support_resource_schema (in topology_schema): ✓ support_resource_schema.exp
+✓ Manifest is valid
+  Total schemas: 42
+  Resolved schemas: 42
+----
+====
+
+
+
+=== Ruby API for schema manifests
+
+==== Loading manifests
 
 Load an existing schema manifest from a YAML file:
 
@@ -1094,7 +1950,7 @@ end
 schema_paths = manifest.schemas.map(&:path)
 ----
 
-===== Programmatically
+==== Creating manifests
 
 Create a new schema manifest programmatically:
 
@@ -1117,32 +1973,7 @@ manifest.schemas << Expressir::SchemaManifestEntry.new(
 manifest.base_path = "/path/to/schemas"
 ----
 
-==== Schema manifest YAML format
-
-The schema manifest uses a structured YAML format:
-
-[source,yaml]
-----
-schemas:
-  - path: schemas/resources/action_schema/action_schema.exp
-    id: action_schema
-  - path: schemas/resources/approval_schema/approval_schema.exp
-    id: approval_schema
-  - path: schemas/resources/date_time_schema/date_time_schema.exp
-----
-
-===== Schema entry attributes
-
-Each schema entry in the manifest can have the following attributes:
-
-`path`:: (Required) The file path to the EXPRESS schema file
-`id`:: (Optional) A unique identifier for the schema
-`container_path`:: (Optional) Container path information
-
-
-==== Working with schema manifests
-
-===== Saving manifests
+==== Saving manifests
 
 Save a manifest to a file:
 
@@ -1155,7 +1986,7 @@ manifest.to_file("output_schemas.yml")
 manifest.save_to_path("/path/to/output/")
 ----
 
-===== Concatenating manifests
+==== Concatenating manifests
 
 Combine multiple manifests:
 
@@ -1171,7 +2002,7 @@ combined_manifest = manifest1.concat(manifest2)
 combined_manifest = manifest1 + manifest2
 ----
 
-===== Using manifests with parsers
+==== Using manifests with parsers
 
 Parse all schemas from a manifest:
 
@@ -1196,11 +2027,110 @@ repository = Expressir::Express::Parser.from_files(schema_paths) do |filename, s
 end
 ----
 
-==== Integration with CLI commands
 
-Schema manifests are supported by several CLI commands:
 
-===== Benchmarking with manifests
+== LER packages
+
+=== General
+
+LER (LutaML EXPRESS Repository) is a package format for distributing EXPRESS
+schemas and related resources in a single binary file.
+
+EXPRESS schemas often utilize `REFERENCE FROM` or `USE FROM` statements to
+import definitions from other schemas, and those referenced schemas
+can deviate across different versions. Managing these dependencies
+is crucial for maintaining compatibility.
+
+The LER package format helps encapsulate these dependencies, ensuring that all
+required schemas are included and versioned correctly, allowing the package
+to be used reliably in different environments.
+
+LER packages have the `.ler` file extension and are essentially ZIP archives
+containing:
+
+* EXPRESS schema files (`.exp`)
+* Metadata files (`metadata.yaml`)
+* pre-parsed model cache (serialized Ruby objects)
+
+
+=== Creating a package
+
+Expressir provides a command-line interface for creating LER packages from
+an EXPRESS manifest.
+
+Expressir supports building LER packages from EXPRESS schemas using a
+manifest-based workflow.
+
+**Using a manifest (recommended for production)**::
+
+[source,sh]
+----
+# Build from validated manifest
+expressir package build --manifest activity_manifest.yaml activity.ler \
+  --name "Activity Module" \
+  --validate
+----
+
+**Using auto-resolution (quick prototyping)**:
+
+[source,sh]
+----
+# Build from root schema with auto-resolution
+expressir package build schemas/activity/mim.exp activity.ler \
+  --base-dirs ~/schemas/resources ~/schemas/modules \
+  --name "Activity Module" \
+  --validate
+----
+
+Complete manifest workflow:
+
+[source,sh]
+----
+# 1. Create manifest from root schema
+expressir manifest create schemas/activity/mim.exp \
+  -o activity_manifest.yaml \
+  --base-dirs ~/iso-10303/schemas \
+  --name "Activity Module"
+
+# 2. Edit manifest to add missing schema paths
+
+# 3. Validate manifest
+expressir manifest validate activity_manifest.yaml
+
+# 4. Build package from manifest
+expressir package build --manifest activity_manifest.yaml activity.ler
+----
+
+
+Unresolved schemas appear without `path:` field. Edit the manifest to add missing paths.
+
+[source,yaml]
+----
+schemas:
+  - name: action_schema
+    path: /path/to/action_schema.exp
+  - name: Activity_method_mim  # Unresolved - no path
+----
+
+
+.`package build --manifest` - Build from manifest
+[source,sh]
+----
+expressir package build --manifest MANIFEST.yaml OUTPUT.ler [OPTIONS]
+----
+
+See link:docs/_pages/ler-packages#manifest-workflow[LER Packages documentation] for complete details.
+
+
+
+== Benchmarking
+
+=== General
+
+Expressir includes benchmarking tools to measure the performance of parsing and
+processing EXPRESS schemas.
+
+=== Benchmarking with manifests
 
 [source,sh]
 ----
@@ -1211,7 +2141,15 @@ expressir benchmark schemas.yml --verbose
 expressir benchmark-cache schemas.yml --cache_path /tmp/cache.bin
 ----
 
-===== Coverage analysis with manifests
+
+== Coverage reporting
+
+=== General
+
+Expressir provides coverage analysis tools to evaluate the documentation
+coverage of EXPRESS schemas.
+
+=== Coverage analysis with manifests
 
 [source,sh]
 ----
@@ -1224,7 +2162,7 @@ expressir coverage schemas.yml --format json --exclude=TYPE:SELECT
 
 
 
-== Working with EXPRESS Changes
+== EXPRESS Changes
 
 === General
 
@@ -1287,9 +2225,9 @@ end
 change_schema.to_file("output.changes.yaml")
 ----
 
-==== Compare modes
+=== Compare modes
 
-===== General
+==== General
 
 Expressir automatically detects and parses all three Eengine XML modes.
 
@@ -1305,7 +2243,7 @@ puts mim_report.mode     # => "mim"
 puts schema_report.mode  # => "schema"
 ----
 
-===== Schema mode
+==== Schema mode
 
 `<schema.changes>` with `<schema.additions>`, `<schema.modifications>`, `<schema.deletions>`
 
@@ -1327,7 +2265,7 @@ puts schema_report.mode  # => "schema"
 ----
 ====
 
-===== ARM mode
+==== ARM mode
 
 `<arm.changes>` root element with `<arm.additions>`,
 `<arm.modifications>`, and `<arm.deletions>` sections
@@ -1345,7 +2283,7 @@ puts schema_report.mode  # => "schema"
 ====
 
 
-===== MIM mode
+==== MIM mode
 
 `<mim.changes>` root element with `<mim.additions>`,
 `<mim.modifications>`, and `<mim.deletions>` sections
@@ -1362,7 +2300,7 @@ puts schema_report.mode  # => "schema"
 ----
 ====
 
-==== Interface changes
+=== Interface changes
 
 The eengine XML format tracks interface changes (USE_FROM, REFERENCE_FROM) with
 the `interfaced.items` attribute. This attribute lists the specific items being
@@ -1425,7 +2363,7 @@ end
 ----
 
 
-==== Supported change types
+=== Supported change types
 
 The import command recognizes all standard EXPRESS construct types: