expressir 2.1.29 → 2.1.31

data/README.adoc

@@ -81,6 +81,7 @@ Commands:
   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 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 +98,10 @@ 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
 
 === Clean schema
 
@@ -124,29 +126,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.
@@ -745,8 +854,8 @@ The import command:
 
 When the output file already exists:
 
-* **Same version**: Replaces the existing edition with that version
-* **New version**: Adds a new edition to the file
+* **Same version**: Replaces the existing version with that version
+* **New version**: Adds a new version to the file
 
 This allows you to build up a complete change history incrementally across
 multiple schema versions.
@@ -816,14 +925,14 @@ This creates a single YAML file tracking changes across all three versions:
 [source,yaml]
 ----
 schema: action_schema
-editions:
-- version: '2'
+versions:
+- version: 2
   description: Changes from eengine comparison
   additions: [...]
-- version: '3'
+- version: 3
   description: Changes from eengine comparison
   additions: [...]
-- version: '4'
+- version: 4
   description: Changes from eengine comparison
   additions: [...]
 ----
@@ -1026,9 +1135,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 +1155,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 +1205,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 +1579,7 @@ end
 schema_paths = manifest.schemas.map(&:path)
 ----
 
-===== Programmatically
+==== Creating manifests
 
 Create a new schema manifest programmatically:
 
@@ -1117,32 +1602,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 +1615,7 @@ manifest.to_file("output_schemas.yml")
 manifest.save_to_path("/path/to/output/")
 ----
 
-===== Concatenating manifests
+==== Concatenating manifests
 
 Combine multiple manifests:
 
@@ -1171,7 +1631,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 +1656,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 +1770,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 +1791,7 @@ expressir coverage schemas.yml --format json --exclude=TYPE:SELECT
 
 
 
-== Working with EXPRESS Changes
+== EXPRESS Changes
 
 === General
 
@@ -1236,7 +1803,7 @@ The Changes module enables:
 
 * Loading and saving schema change records from/to YAML files
 * Programmatic creation and manipulation of change records
-* Smart edition handling (replace same version, add new version)
+* Smart version handling (replace same version, add new version)
 * Support for all change types: additions, modifications, deletions
 * Support for mapping changes in ARM/MIM schemas
 * Programmatic import from Express Engine comparison XML files
@@ -1278,7 +1845,7 @@ change_schema = Expressir::Commands::ChangesImportEengine.from_xml(
 )
 
 # Use the SchemaChange object
-change_schema.editions.first.additions.each do |item|
+change_schema.versions.first.additions.each do |item|
   puts "#{item.type}: #{item.name}"
   puts "  interfaced_items: #{item.interfaced_items}" if item.interfaced_items
 end
@@ -1287,9 +1854,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 +1872,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 +1894,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 +1912,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 +1929,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
@@ -1392,8 +1959,8 @@ This will be converted to EXPRESS Changes YAML as:
 [source,yaml]
 ----
 schema: aic_csg
-editions:
-- version: '2'
+versions:
+- version: 2
   description: Changes from eengine comparison
   additions:
   - type: USE_FROM
@@ -1425,7 +1992,7 @@ end
 ----
 
 
-==== Supported change types
+=== Supported change types
 
 The import command recognizes all standard EXPRESS construct types:
 
@@ -1453,14 +2020,14 @@ change_schema = Expressir::Changes::SchemaChange.from_file("schema.changes.yaml"
 # Access schema name
 puts "Schema: #{change_schema.schema}"
 
-# Iterate through change editions
-change_schema.editions.each do |edition|
-  puts "Version #{edition.version}: #{edition.description}"
+# Iterate through change versions
+change_schema.versions.each do |version|
+  puts "Version #{version.version}: #{version.description}"
 
   # Access changes by type
-  puts "  Additions: #{edition.additions.size}" if edition.additions
-  puts "  Modifications: #{edition.modifications.size}" if edition.modifications
-  puts "  Deletions: #{edition.deletions.size}" if edition.deletions
+  puts "  Additions: #{version.additions.size}" if version.additions
+  puts "  Modifications: #{version.modifications.size}" if version.modifications
+  puts "  Deletions: #{version.deletions.size}" if version.deletions
 end
 ----
 
@@ -1485,14 +2052,14 @@ modified_function = Expressir::Changes::ItemChange.new(
   description: "Updated parameters"
 )
 
-# Add a change edition
+# Add a change version
 changes = {
   additions: [new_entity],
   modifications: [modified_function],
   deletions: []
 }
 
-change_schema.add_or_update_edition(
+change_schema.add_or_update_version(
   "2",
   "Added new entity and modified function",
   changes
@@ -1504,10 +2071,10 @@ change_schema.to_file("my_schema.changes.yaml")
 
 === Updating existing change files
 
-The `add_or_update_edition` method provides smart handling:
+The `add_or_update_version` method provides smart handling:
 
-* **Same version**: Replaces the existing edition
-* **Different version**: Adds a new edition
+* **Same version**: Replaces the existing version
+* **Different version**: Adds a new version
 
 [source,ruby]
 ----
@@ -1520,10 +2087,10 @@ changes = {
     Expressir::Changes::ItemChange.new(type: "TYPE", name: "updated_type")
   ]
 }
-change_schema.add_or_update_edition("3", "Modified type definition", changes)
+change_schema.add_or_update_version("3", "Modified type definition", changes)
 
 # Or replace existing version
-change_schema.add_or_update_edition("2", "Revised description", changes)
+change_schema.add_or_update_version("2", "Revised description", changes)
 
 # Save changes
 change_schema.to_file("schema.changes.yaml")
@@ -1547,9 +2114,9 @@ item = Expressir::Changes::ItemChange.new(
 )
 ----
 
-=== Change edition fields
+=== Change version fields
 
-Change editions support categorizing changes into:
+Change versions support categorizing changes into:
 
 `additions`:: New elements added to the schema
 `modifications`:: Existing elements that were modified
@@ -1559,7 +2126,7 @@ Change editions support categorizing changes into:
 
 [source,ruby]
 ----
-edition = Expressir::Changes::EditionChange.new(
+version = Expressir::Changes::VersionChange.new(
   version: "2",
   description: "Added support for new functionality",
   additions: [item1, item2],
@@ -1586,8 +2153,8 @@ mapping_change = Expressir::Changes::MappingChange.new(
 ----
 ---
 schema: support_resource_schema
-editions:
-- version: '2'
+versions:
+- version: 2
   description: |-
     The definitions of the following EXPRESS entity data types were modified:
 
@@ -1600,7 +2167,7 @@ editions:
   modifications:
   - type: FUNCTION
     name: bag_to_set
-- version: '4'
+- version: 4
   description: |-
     Added support for external element references.
   additions: