suma 0.2.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e6db67576d42aaaed54f90f72960ad405774d4084be5f7c0e8f1b277ebbbd50
-  data.tar.gz: ed5cdf3967496436950306f0edcf553751bb3da06c4e4582a014b8e7610e6d35
+  metadata.gz: 304c4c7a2ec03c83604a127370259b022e0102d303c4951c2d730d3681d3ad39
+  data.tar.gz: b8d9bcd807ea0aadb4f038dd58823d829d495827e4785316cb7c715e79b512cb
 SHA512:
-  metadata.gz: 0e4e8fe19fb5b9ec7c8023258e55a8ed100c98bb4ee271898562eeed13d5e1646d09c673e0053f2271827c8413408d5cb9295e94cc39d298be7161d33a0805c2
-  data.tar.gz: 8110684a885977266204dace36b4b5bb8a88113c1b410aa78c19d8ad4c58c2a49858f14f9495e433414d43b0bd13716a49e47eb8ef7724ee34306826a215ff15
+  metadata.gz: 21977b339cd0a16936940c50de766ba2130f3dc46df7965db1de04360a65c1d685e1b59786e9a49548d0e79f1d20befcf732a66482b6e8b8793a547bd557d28e
+  data.tar.gz: bd1122e6d73a9a22b3a3830c7cf654c909a541e7c332808349b15bb469f772338ad7a84a25590f1c8d13b46b84d8399673fa2f43f16f5d943e0e1f8e2469a08a

data/.gitignore

@@ -11,4 +11,10 @@
 .rspec_status
 .rubocop-https---*-yml
 .ruby-version
-Gemfile.lock
+Gemfile.lock
+
+# local planning scratch directories and files (not for commit)
+/TODO*
+
+# vendored gems (use Gemfile / Gemfile.lock elsewhere)
+/*.gem

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-11 08:57:26 UTC using RuboCop version 1.86.1.
+# on 2026-07-02 16:27:30 UTC using RuboCop version 1.87.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -16,13 +16,147 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'suma.gemspec'
 
-# Offense count: 120
+# Offense count: 35
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/schema_compiler.rb'
+    - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/svg_quality/formatters.rb'
+    - 'lib/suma/term_extractor.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/manifest_traverser_spec.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
+    - 'spec/suma/schema_comparer_spec.rb'
+    - 'spec/suma/schema_discovery_spec.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'lib/suma/schema_naming.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: IndentationWidth.
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'lib/suma/schema_template/document.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/schema_index_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'lib/suma/schema_template/document.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/schema_index_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_brackets
+Layout/FirstArrayElementIndentation:
+  Exclude:
+    - 'spec/suma/manifest_traverser_spec.rb'
+
+# Offense count: 14
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/suma/schema_compiler.rb'
+    - 'lib/suma/term_extractor.rb'
+    - 'spec/suma/manifest_traverser_spec.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 189
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineArrayBraceLayout:
+  Exclude:
+    - 'spec/suma/manifest_traverser_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'lib/suma/schema_template/document.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/schema_index_spec.rb'
+
+# Offense count: 32
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/schema_compiler.rb'
+    - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/schema_naming.rb'
+    - 'lib/suma/svg_quality/formatters.rb'
+    - 'lib/suma/term_extractor.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/manifest_traverser_spec.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
+    - 'spec/suma/schema_comparer_spec.rb'
+    - 'spec/suma/schema_discovery_spec.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
 # Offense count: 4
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -48,29 +182,31 @@ Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/suma/svg_quality.rb'
 
-# Offense count: 29
+# Offense count: 32
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
-    - 'lib/suma/cli.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
+    - 'lib/suma/cli/core.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/link_validator.rb'
+    - 'lib/suma/manifest_traverser.rb'
     - 'lib/suma/processor.rb'
-    - 'lib/suma/schema_attachment.rb'
+    - 'lib/suma/schema_collection.rb'
     - 'lib/suma/schema_comparer.rb'
-    - 'lib/suma/schema_document.rb'
+    - 'lib/suma/schema_compiler.rb'
     - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/schema_template/document.rb'
     - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
     - 'lib/suma/term_extractor.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 54
+  Max: 58
 
 # Offense count: 14
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
@@ -87,12 +223,12 @@ Metrics/CyclomaticComplexity:
     - 'lib/suma/term_extractor.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 25
+# Offense count: 31
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 59
+  Max: 63
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
@@ -150,7 +286,7 @@ RSpec/ContextWording:
   Exclude:
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 71
+# Offense count: 111
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 60
@@ -181,7 +317,7 @@ RSpec/MessageSpies:
   Exclude:
     - 'spec/suma/schema_comparer_integration_spec.rb'
 
-# Offense count: 50
+# Offense count: 87
 RSpec/MultipleExpectations:
   Max: 21
 
@@ -203,6 +339,27 @@ RSpec/StubbedMock:
   Exclude:
     - 'spec/suma/schema_comparer_integration_spec.rb'
 
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/schema_naming.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?

data/CLAUDE.md

@@ -27,7 +27,8 @@ exe/suma export -o OUTPUT_DIR schema1.yml schema2.exp  # Export schemas (YAML ma
 exe/suma compare TRIAL_SCHEMA REFERENCE_SCHEMA -v VER  # Compare schemas, generate .changes.yaml
 exe/suma reformat PATH                                  # Reformat EXP files (use -r for recursive)
 exe/suma generate-schemas METANORMA_YAML SCHEMAS_YAML  # Generate schema manifest from site manifest
-exe/suma extract-terms SCHEMA_YAML GLOSSARIST_DIR      # Extract terms to Glossarist v2 format
+exe/suma extract-terms SCHEMA_YAML GLOSSARIST_DIR -u URN   # Extract EXPRESS entity concepts to Glossarist v3 format
+exe/suma generate-register SCHEMA_YAML OUT_DIR -u URN --id ID --ref REF  # Generate hierarchical register.yaml from schema manifest
 exe/suma validate links SCHEMAS_FILE DOCS_PATH          # Validate EXPRESS cross-reference links
 ```
 
@@ -35,27 +36,50 @@ exe/suma validate links SCHEMAS_FILE DOCS_PATH          # Validate EXPRESS cross
 
 ### Core pipeline (build command)
 
-1. `Processor.run` receives a Metanorma site manifest YAML
+1. `Processor.new(...).run` receives a Metanorma site manifest YAML
 2. `SiteConfig` reads the site manifest, finds collection YAML paths
 3. `CollectionConfig` extends `Metanorma::Collection::Config` with a `CollectionManifest` that discovers `schemas.yaml` files
-4. `SchemaCollection` loads all discovered schemas via `Expressir`, exports plain `.exp` files, and compiles documentation (Metanorma `.adoc` → XML/HTML)
-5. `SchemaExporter` handles exporting schemas to a directory (with optional ZIP packaging)
+4. `ManifestTraverser` walks the manifest tree (`expand_schemas_only`, `export_schema_config`, `remove_schemas_only_sources`); `SchemaDiscovery` loads each `schemas.yaml` and builds doc sub-trees
+5. `SchemaCollection` loads all discovered schemas via `Expressir`, exports plain `.exp` files, and compiles documentation via `SchemaCompiler` + `SchemaTemplate::Plain|Document` (Metanorma `.adoc` → XML/HTML)
+6. `SchemaExporter` handles exporting schemas to a directory (with optional ZIP packaging)
 
 ### Key classes
 
-- **`ExpressSchema`** — wraps a single EXPRESS schema file; parses via `Expressir::Express::Parser`, can output plain or annotated `.exp`
-- **`SchemaAttachment`** — compiles one schema into a Metanorma `.adoc` document and renders it via `Metanorma::Compile`
-- **`SchemaDocument`** (extends `SchemaAttachment`) — adds cross-reference bookmarks and uses XML-only output
-- **`SchemaCollection`** — orchestrates processing of all schemas from a config
+- **`ExpressSchema`** — wraps a single EXPRESS schema file; parses via `Expressir::Express::Parser`, can output plain or annotated `.exp`. Includes nested `Type` module for schema classification (resource/module_arm/module_mim/business_object_model/core_model/standalone) based on ID suffixes and path segments
+- **`SchemaCategory`** — value object mapping `ExpressSchema::Type` to a register/export category (id, label, prefix, types, directory). Single source of truth for category identity across `SchemaExporter`, `SchemaNaming`, and `RegisterManifestGenerator`
+- **`Urn`** — value object encapsulating ISO URN semantics (wildcard stripping, base/alias split, leaf composition for `for_schema`/`for_term`/`for_entity`)
+- **`TermExtractor`** — extracts EXPRESS entity concepts from a schema manifest into Glossarist v3 YAML format. Generates definitions with URN cross-references, processes remarks into notes, and resolves EXPRESS xrefs to URN mentions. Assigns stable UUIDv5 identifiers
+- **`RegisterManifestGenerator`** (file: `lib/suma/register_manifest_generator.rb`) — generates a Glossarist v3 `register.yaml` with hierarchical sections from a schema manifest. Classifies schemas via `ExpressSchema::Type` (DRY), delegates naming to `SchemaNaming` (OCP), orders resources before modules. Uses the Section model's `children` field for hierarchy
+- **`SchemaNaming`** — pure module that converts EXPRESS schema IDs to human-readable display names. Strips type suffixes (`_schema`/`_arm`/`_mim`/`_bom`), title-cases with acronym preservation (AIC, AEC, BREP, 2D, 3D…), lowercases function words, appends type labels (ARM/MIM)
+- **`SchemaTemplate::Plain` / `SchemaTemplate::Document`** — pure renderers for the AsciiDoc body fed to Metanorma (no I/O, no schema knowledge). `Document` adds cross-reference anchors and produces XML-only output
+- **`SchemaCompiler`** — orchestrates one schema's compilation: writes adoc + config, invokes `Metanorma::Compile`. Templates are injected via the constructor (composition over inheritance)
+- **`SchemaCollection`** — orchestrates processing of all schemas from a config; selects `Plain` for top-level schemas and `Document` for schemas-only entries
 - **`SchemaExporter`** — standalone export of schemas from manifest or `.exp` files to a directory, with optional ZIP
-- **`CollectionManifest`** — traverses collection YAML files, builds unified `Expressir::SchemaManifest`
+- **`CollectionManifest`** — pure data model (lutaml-model attributes + YAML mappings) for one node of a Metanorma collection manifest. No imperative methods
+- **`ManifestTraverser`** — tree-walking service over a `CollectionManifest` (`find_schemas_only`, `export_schema_config`, `expand_schemas_only`, `remove_schemas_only_sources`)
+- **`SchemaDiscovery`** — schema-config I/O service on a single manifest node (`load_config` from `schemas.yaml`, `build_doc_entries`, `build_added_manifest`)
+- **`SchemaIndex`** — O(1) lookup index for schema and element names, used by `LinkValidator`
+- **`LinkValidator`** — validates EXPRESS cross-reference links against a `SchemaIndex`; returns `LinkValidationResult` structs for unresolved links
 
 ### CLI structure
 
 - `Suma::Cli::Core` (Thor subclass) — top-level CLI entrypoint
-- Subcommands delegate to `Cli::Build`, `Cli::Export`, `Cli::Compare`, `Cli::Validate`, `Cli::Reformat`, `Cli::GenerateSchemas`, `Cli::ExtractTerms`, `Cli::ConvertJsdai`
+- Subcommands delegate to `Cli::Build`, `Cli::Export`, `Cli::Compare`, `Cli::Validate`, `Cli::Reformat`, `Cli::GenerateSchemas`, `Cli::ExtractTerms`, `Cli::GenerateRegister`, `Cli::ConvertJsdai`
 - Thor extension (`ThorExt::Start`) adds `-h`/`--help` support and error formatting
 
+### Terminology extraction (extract-terms / generate-register)
+
+The `extract-terms` command reads an EXPRESS schema manifest, parses each `.exp` file via `Expressir`, and emits Glossarist v3 concept YAML with:
+- Entity definitions using URN cross-references (`{{urn:...term,entity data type}}`, `{{urn:...term,entity}}`)
+- Entity remarks processed into notes (first-sentence extraction, redundant note removal, invalid reference filtering)
+- Domain classification via `ExpressSchema::Type` (resource vs application module)
+- Section references for hierarchical grouping
+
+The `generate-register` command reads the same schema manifest and emits `register.yaml` with hierarchical sections:
+- Top-level groups: Resources (133) before Application Modules (1123)
+- Child sections use human-readable names from `SchemaNaming` (e.g. "Resource: Topology", "Module: Activity (ARM)")
+- Parent group IDs are included in concept metadata so the concept-browser can filter by group
+
 ### External dependencies
 
 - **expressir** — EXPRESS schema parsing and manifest handling
@@ -73,4 +97,6 @@ The `compare` command uses an external `eengine` binary to diff two EXPRESS sche
 - Ruby 3.0+ with `frozen_string_literal: true` in every file
 - RuboCop with performance, rake, and rspec plugins; inherits from riboseinc OSS guide
 - Some CLI files are excluded from RuboCop in `.rubocop.yml`
-- Use `Utils.log` for user-facing output (prefixes with `[suma]`)
+- Internal library code uses Ruby `autoload` (defined in the immediate parent namespace's file); no `require_relative`
+- No `send` to call private methods, no `instance_variable_set`/`get`, no `respond_to?` for type checking
+- Use `Utils.log` for user-facing output (writes to `$stderr`, prefix `[suma]`; `level: :debug` gated by `SUMA_DEBUG`)

data/Gemfile

@@ -6,9 +6,9 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon"
-gem "metanorma", github: "metanorma/metanorma", branch: "main"
-gem "metanorma-plugin-lutaml", github: "metanorma/metanorma-plugin-lutaml", branch: "main"
-gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+# gem "metanorma", github: "metanorma/metanorma", branch: "main"
+# gem "metanorma-plugin-lutaml", github: "metanorma/metanorma-plugin-lutaml", branch: "main"
+# gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
 gem "nokogiri"
 gem "openssl", "~> 3.0"
 gem "rake"

data/README.adoc

@@ -39,7 +39,8 @@ $ suma
  Commands:
   suma build METANORMA_SITE_MANIFEST                                  # Build collection specified in site manifest (`metanorma*.yml`)
   suma convert-jsdai XML_FILE IMAGE_FILE OUTPUT_DIR                   # Convert JSDAI XML and image files to SVG and EXP files
-  suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract terms from SCHEMA_MANIFEST_FILE into Glossarist v2 format
+  suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract EXPRESS entity concepts into Glossarist v3 format
+  suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH            # Generate hierarchical register.yaml from schema manifest
   suma generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE  # Generate EXPRESS schema manifest file from Metanorma site manifest
   suma help [COMMAND]                                                 # Describe available commands or one specific command
   suma reformat EXPRESS_FILE_PATH                                     # Reformat EXPRESS files
@@ -301,6 +302,61 @@ $ bundle exec suma extract-terms schemas-activity-modules.yml terms_output
 ====
 
 
+=== Generate register command
+
+The `suma generate-register` command reads an EXPRESS schema manifest and
+emits a Glossarist v3 `register.yaml` with hierarchical sections. The
+output is used by the concept browser to render a navigable sidebar of
+sections and to resolve concept cross-references.
+
+[source,sh]
+----
+$ suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH -u URN --id ID --ref REF
+----
+
+Parameters:
+
+`SCHEMA_MANIFEST_FILE`:: Path to the schema manifest (e.g., "schemas-smrl-part-2.yml")
+
+`OUTPUT_PATH`:: Directory where `register.yaml` will be written
+
+Options:
+
+`--urn`, `-u`:: Base URN prefix for the dataset (e.g. `urn:iso:std:iso:10303:-2:ed-2:en:tech:*`).
+The wildcard is stripped for the base URN and kept in `urnAliases`.
+*Required*.
+
+The URN is fully configurable — every component can be changed to match the
+dataset being exported. The general structure is:
+
+----
+urn:iso:std:iso:<part>:ed-<edition>:<lang>:tech:*
+----
+
+For example, to export edition 3 in French:
+
+----
+--urn urn:iso:std:iso:10303:-2:ed-3:fr:tech:*
+----
+
+The current ISO 10303-2 SMRL data is edition 2; use `ed-2` unless you are
+re-publishing an earlier edition.
+
+`--id`:: Dataset identifier (e.g. `iso10303-2-express`). *Required*.
+
+`--ref`:: Human-readable dataset reference label (e.g. `ISO 10303-2 EXPRESS Concepts`). *Required*.
+
+`--language_code`, `-l`:: Language code for section names (default: "eng")
+
+The generated register contains two top-level groups:
+
+* **Resources** — integrated resource schemas (path contains `schemas/resources/`)
+* **Application Modules** — ARM and MIM schemas (path contains `schemas/modules/`)
+
+Each schema gets a human-readable name via the `SchemaNaming` module
+(e.g. `topology_schema` → "Resource: Topology", `Activity_method_assignment_mim` → "Module: Activity Method Assignment (MIM)"). Acronyms (AIC, AEC, BREP, 2D, 3D) are preserved; function words (as, of, the) are lowercased per ISO title-case convention.
+
+
 === Convert JSDAI image outputs to SVG and Annotated EXPRESS
 
 The `suma convert-jsdai` command converts JSDAI EXPRESS-G diagram outputs
@@ -1009,34 +1065,31 @@ examples demonstrate common usage patterns.
 require 'suma'
 
 # Build a collection with default settings
-Suma::Processor.run(
+Suma::Processor.new(
   metanorma_yaml_path: "metanorma-srl.yml",
   schemas_all_path: "schemas-srl.yml",
   compile: true,
   output_directory: "_site"
-)
+).run
 
 # Generate schema listing without compilation
-Suma::Processor.run(
+Suma::Processor.new(
   metanorma_yaml_path: "metanorma-srl.yml",
   schemas_all_path: "schemas-srl.yml",
-  compile: false,
-  output_directory: "_site"
-)
+  compile: false
+).run
 ----
 
-=== Working with schema configurations
+=== Working with schema manifests
+
+Schema manifests are loaded via `Expressir::SchemaManifest`:
 
 [source,ruby]
 ----
 require 'suma'
 
-# Load schemas using SchemaConfig
 schemas_file_path = "schemas-srl.yml"
-schemas_config = Suma::SchemaConfig::Config.from_yaml(IO.read(schemas_file_path))
-
-# Set the initial path to resolve relative paths
-schemas_config.set_initial_path(schemas_file_path)
+schemas_config = Expressir::SchemaManifest.from_file(schemas_file_path)
 
 # Access schema information
 schemas_config.schemas.each do |schema|
@@ -1045,6 +1098,67 @@ schemas_config.schemas.each do |schema|
 end
 ----
 
+=== Extracting terms
+
+[source,ruby]
+----
+require 'suma'
+
+Suma::TermExtractor.new(
+  "schemas-smrl-part-2.yml",
+  "glossarist_output",
+  urn: "urn:iso:std:iso:10303:-2:ed-2:en:tech:*",
+).call
+----
+
+=== Generating a register.yaml
+
+[source,ruby]
+----
+require 'suma'
+
+Suma::RegisterManifestGenerator.new(
+  "schemas-smrl-part-2.yml",
+  "register_output",
+  urn: "urn:iso:std:iso:10303:-2:ed-2:en:tech:*",
+  id: "iso10303-2-express",
+  ref: "ISO 10303-2 EXPRESS Concepts",
+).generate
+----
+
+=== Architecture
+
+Suma's domain is split into MECE concerns:
+
+* **Data models** (pure): `CollectionManifest`, `ExpressSchema`
+* **Value objects** (pure): `SchemaCategory`, `Urn`
+* **Services** (single concern): `ManifestTraverser`, `SchemaDiscovery`,
+  `SchemaCompiler`, `SchemaExporter`, `SchemaIndex`, `LinkValidator`,
+  `SchemaComparer`, `SchemaManifestGenerator`, `TermExtractor`,
+  `RegisterManifestGenerator`, `Processor`
+* **Renderers** (pure, composable): `SchemaTemplate::Plain`,
+  `SchemaTemplate::Document`
+
+Key invariants:
+
+* The classifier `ExpressSchema::Type.classify(id:, path:)` is the single
+  source of truth for schema type. `SchemaCategory`, `SchemaNaming`,
+  `SchemaExporter`, and `RegisterManifestGenerator` all derive from it.
+* `Urn` owns URN semantics (wildcard stripping, base/alias split, leaf
+  composition).
+* `CollectionManifest` is a pure data model; tree walking lives in
+  `ManifestTraverser`, schema I/O lives in `SchemaDiscovery`.
+* `SchemaCompiler` orchestrates one Metanorma compilation; the adoc body
+  is injected via a `SchemaTemplate::*` renderer.
+
+Code-style rules enforced throughout `lib/suma/`:
+
+* Ruby `autoload` only — no `require_relative`
+* No `send` to call private methods
+* No `instance_variable_set` / `instance_variable_get`
+* No `respond_to?` for type checking
+* `Utils.log` writes to `$stderr`; debug level gated by `SUMA_DEBUG`
+
 
 == Copyright and license
 

data/exe/suma

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "suma/cli"
+require "suma"
 
 Suma::Cli::Core.start(ARGV)

data/lib/suma/cli/build.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../thor_ext"
 
 module Suma
   module Cli
@@ -15,10 +14,6 @@ module Suma
                                 desc: "Generate file that contains all schemas in the collection."
 
       def build(metanorma_site_manifest)
-        # Lazy-load dependencies only when this command is actually used
-        require_relative "../processor"
-        require_relative "../utils"
-
         unless File.exist?(metanorma_site_manifest)
           raise Errno::ENOENT, "Specified Metanorma site manifest file " \
                                "`#{metanorma_site_manifest}` not found."