suma 0.5.9 → 0.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54c10b8d56459f9d53cd1b5988cbcc2193675f4dffa43e115845400497faa8f9
-  data.tar.gz: b46df0c3ef57f69e2e0e5e3b7dfdf3c464189a66f372ef2a5f7a5d3a8d47b34b
+  metadata.gz: 01e0b1dd212172912b654cac481e0ce1eea1efee1275f45d4332c0a6bbb28e69
+  data.tar.gz: 54399e492be26b0a09595debdc61c256f566da28ed13ca002cae2a6eb0925b57
 SHA512:
-  metadata.gz: 51f6a6ed42abb76af7342d06e0b73c3132ddf7e65ffdb5d29c96892860fd3be534557581f6bd14b6dd15e022a8e2ac250cdb23f6ed4d68242457515b8951b415
-  data.tar.gz: c562c0691baa4b3fb708b94dd5853014a18e4bad0cd8527cbf7922a7273ebd982a5239ea13914c0d60f279e2ceae9b534a43a58ff42b339c7dd5114f7e5be576
+  metadata.gz: 9fb0aebf85233af1df6162efb518605bd7ab01c7396e7af6012144fd05c74a135ba7d2833b7bb633fa45c755e067d6799569412df0b21458b33d2730a5081a3a
+  data.tar.gz: d9836497a01e7711aece5c76534ecfa4e7e0876bfd414aab783ada288b1906e07a3f3b6994d17085f294b79a827c16ecb61bab7cf305a823b9527933e5aa7f1c

data/.rubocop_todo.yml

@@ -116,9 +116,11 @@ Lint/UnusedMethodArgument:
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
     - 'bin/benchmark_corpus'
     - 'lib/suma/worker_pool.rb'
     - 'spec/suma/reproducibility_spec.rb'
+    - 'spec/suma/cli/build_integration_spec.rb'
     - 'lib/suma/cli/resolve.rb'
     - 'lib/suma/urn_resolver.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
@@ -155,6 +157,8 @@ Metrics/BlockLength:
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
+    - 'lib/suma/corpus_graph.rb'
     - 'lib/suma/worker_pool.rb'
     - 'lib/suma/urn_resolver.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
@@ -172,6 +176,8 @@ Metrics/CyclomaticComplexity:
 # Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Exclude:
+    - 'lib/suma/artifact_server.rb'
+    - 'lib/suma/gcr_package.rb'
     - 'bin/benchmark_corpus'
     - 'lib/suma/cli/build.rb'
     - 'lib/suma/worker_pool.rb'
@@ -204,6 +210,7 @@ Metrics/MethodLength:
 # Configuration parameters: Max, CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
     - 'lib/suma/processor.rb'
     - 'lib/suma/express_schema.rb'
     - 'lib/suma/term_extractor.rb'
@@ -216,6 +223,7 @@ Metrics/ParameterLists:
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
     - 'lib/suma/worker_pool.rb'
     - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure_image.rb'
@@ -259,6 +267,16 @@ RSpec/ContextWording:
 # Configuration parameters: Max, CountAsOne.
 RSpec/ExampleLength:
   Exclude:
+    - 'spec/suma/site_build_spec.rb'
+    - 'spec/suma/output_canonicalizer_spec.rb'
+    - 'spec/suma/anchor_validator_spec.rb'
+    - 'spec/suma/translation_ingester_spec.rb'
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
+    - 'spec/suma/schema_manifest_generator_spec.rb'
+    - 'spec/suma/schema_naming_spec.rb'
+    - 'spec/suma/cli/build_integration_spec.rb'
+    - 'spec/suma/artifact_server_spec.rb'
+    - 'spec/suma/gcr_package_spec.rb'
     - 'spec/suma/schema_cache_spec.rb'
     - 'spec/suma/worker_pool_spec.rb'
     - 'spec/suma/schema_collection_rebuild_targets_spec.rb'
@@ -338,6 +356,11 @@ RSpec/MessageSpies:
 # Configuration parameters: Max.
 RSpec/MultipleExpectations:
   Exclude:
+    - 'spec/suma/site_build_spec.rb'
+    - 'spec/suma/output_canonicalizer_spec.rb'
+    - 'spec/suma/cli/build_integration_spec.rb'
+    - 'spec/suma/artifact_server_spec.rb'
+    - 'spec/suma/gcr_package_spec.rb'
     - 'spec/suma/schema_cache_spec.rb'
     - 'spec/suma/worker_pool_spec.rb'
     - 'spec/suma/reproducibility_spec.rb'
@@ -400,11 +423,13 @@ RSpec/NestedGroups:
 RSpec/DescribeClass:
   Exclude:
     - 'spec/suma/reproducibility_spec.rb'
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
 
 RSpec/SpecFilePathFormat:
   Exclude:
     - '**/spec/routing/**/*'
     - 'spec/suma/cli/expressir_spec.rb'
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
 
 # Offense count: 1
 RSpec/StubbedMock:
@@ -415,6 +440,8 @@ RSpec/StubbedMock:
 # Configuration parameters: Max.
 RSpec/MultipleMemoizedHelpers:
   Exclude:
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
+    - 'spec/suma/gcr_package_spec.rb'
     - 'spec/suma/provenance_spec.rb'
     - 'spec/suma/worker_pool_spec.rb'
     - 'spec/suma/schema_cache_spec.rb'

data/CLAUDE.md

@@ -37,11 +37,15 @@ exe/suma reformat PATH                                  # Reformat EXP files (us
 exe/suma generate-schemas METANORMA_YAML SCHEMAS_YAML  # Generate schema manifest from site manifest
 exe/suma extract-terms SCHEMA_YAML GLOSSARIST_DIR -u URN   # Extract EXPRESS entity concepts to Glossarist v3 format
 exe/suma extract-terms ... --edition 3 --language-codes fra deu  # Provenance + linked localizations
+exe/suma ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE [-o OUT]  # Overlay translated localized-concept content onto extracted concepts
 exe/suma resolve URN --manifest SCHEMAS_YAML --concepts DIR --register register.yaml -o OUT  # Emit canonical JSON + HTML
 exe/suma resolve --all --manifest SCHEMAS_YAML --concepts DIR --register register.yaml -o OUT  # Emit every URN artifact
+exe/suma package-gcr CONCEPTS_DIR --register register.yaml --shortname ID --version V --title T --description D -o OUT  # Package concepts into a .gcr archive
+exe/suma serve ARTIFACTS_DIR --port 2113  # Serve resolved URN artifacts with Accept negotiation
 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
 exe/suma validate closure SCHEMAS_MANIFEST [DOCUMENTS_PATH]  # Referential closure: every reference resolves (exit 1 on violations)
+exe/suma validate anchors SCHEMA_DOCS_PATH              # Rendered docs: every xref and in-page link resolves (exit 1 on dead links)
 ```
 
 ## Schema profiles
@@ -51,8 +55,10 @@ identifiers and paths map to types (`ExpressSchema::Type`), how
 identifiers become display names (`SchemaNaming`), and the ordered
 register categories (`SchemaCategory`). Registered profiles: `iso10303`
 (default; STEP conventions incl. `/applications/` → application
-protocol) and `generic` (no STEP conventions). The CLI takes
-`--profile` on `export`, `extract-terms`, and `generate-register`.
+protocol), `generic` (no STEP conventions), and `ifc` (buildingSMART
+IFC editions: standalone classification, `IFC4`-style edition names via
+`/\Aifc\d+(x\d+)*\z/`). The CLI takes `--profile` on `export`,
+`extract-terms`, and `generate-register`.
 
 ## ISO 10303 AP publications
 
@@ -81,10 +87,12 @@ per-publication parent section.
 - **`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
+- **`TranslationIngester`** — T5 translation ingestion: overlays a YAML sequence of localized-concept entries (keyed by `concept_id` or localized UUID) onto extracted concepts through the Glossarist/lutaml-model framework. Entry fields win; omitted fields keep the source-language content; a new language is created with the same UUIDv5 convention as the linked localizations, and the persisted localization "id" is preserved (Glossarist parses it as `#id`, not `#uuid`)
 - **`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)
+- **`SchemaTemplate::Plain` / `SchemaTemplate::Document`** — pure renderers for the AsciiDoc body fed to Metanorma (no I/O, no schema knowledge). Both render the schema through `formatted_hyperlinked_adoc` (live cross-references) under the shared `Anchors` block, which emits one `[[id]]` per linkable element — schema-qualified ids plus bare `entity.attribute` pairs, matching Expressir's two xref forms. `Plain` produces HTML+XML for top-level schemas; `Document` produces XML-only for schemas-only entries. `validate anchors` verifies zero dead links in rendered docs
+- **`AnchorValidator`** — T4 dead-link gate: for every rendered `doc_*.adoc` + `doc_*.html`, each `<<target,...>>` xref must have an anchor in the HTML (unresolved xrefs are silently dropped by the renderer) and every in-page `href="#..."` must hit an id; cross-document xrefs are out of scope. `validate anchors SCHEMA_DOCS_PATH` exits 1 on violations
+- **`SchemaCompiler`** — orchestrates one schema's compilation: writes adoc + config, invokes `Metanorma::Compile`. Templates are injected via the constructor (composition over inheritance). A render key over adoc, config, schema source, and `Provenance.render_toolchain` is stored in `.suma-render-key` beside the outputs; an unchanged key with the requested outputs present reuses them without invoking Metanorma
 - **`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`** — pure data model (lutaml-model attributes + YAML mappings) for one node of a Metanorma collection manifest. No imperative methods
@@ -97,9 +105,13 @@ per-publication parent section.
 - **`OwlProjection`** — S2 formal semantics: projects a parsed corpus into OWL/Turtle. Entities → `owl:Class`; `SUBTYPE OF` → `rdfs:subClassOf`; SELECT → `owl:unionOf`; enums → `owl:oneOf` named individuals; simple type aliases → `rdfs:Datatype`; explicit/derived/inverse attributes → object/datatype properties attached through named `owl:Restriction` nodes (cardinality from optionality and aggregate bounds); WHERE rules and DERIVE/INVERSE clauses → annotated (`rdfs:comment`) constraints. IRIs come from `Urn` (`<base>:tech:<schema>.<element>`), per-schema ontologies declare `owl:imports` for their `USE FROM`/`REFERENCE` targets, and the corpus ontology imports every schema. `#validate` checks materialization, property declarations, orphan classes, and superclass acyclicity. Output contains no blank nodes, so projections are deterministic and golden-comparable
 - **`SchemaCache`** — content-addressed on-disk store for generated `.exp` output and parsed Expressir repositories. Keys compose source bytes with the Expressir version (plus Suma/Marshal versions for parsed entries), so a hit is equivalent to a fresh build. Enabled by `SUMA_SCHEMA_CACHE_DIR`; hit/miss counters expose parse reuse. **`NullCache`** is the disabled-mode null object
 - **`BuildPlan`** — incremental-build decision: hashes every schema source, diffs against the persisted state, and expands changed schemas to their transitive dependents through `CorpusGraph`. State defaults to `plain_schemas/.suma-build-state.json`; `SchemaCollection#rebuild_targets` is the build-facing query
+- **`SiteBuild`** — T3 site freshness: keys every source file under the site root (excluding generated trees, render copies, and the Relaton cache) plus the render toolchain, records the key and produced files in `_site/.suma-site-build.json`, and lets `Processor` skip the collection render when nothing changed. Generated per-document artifacts (`document*.xml*`, `*_index.html`, `*.err.html`, `*.log.txt`, temp files) are never treated as inputs
+- **`OutputCanonicalizer`** — T3 determinism: Metanorma assigns random UUIDs to manifest nodes without identifiers and stamps rendered documents with a random 8-letter root type. This pass rewrites those to position-derived UUIDv5s and a fixed marker in the emitted manifest and root XML, while preserving UUIDs that occur in source YAML, so identical builds are byte-identical
 - **`WorkerPool`** — bounded worker pool for independent per-schema work. Schema export runs in the pool (`build --jobs N`); Metanorma document compilation stays sequential and composes with `StagedCollectionBuilder`'s process isolation
 - **`UrnResolver`** — S4 dereferenceable identity: resolves `tech:` schema/element URNs from a manifest, `term:` concept URNs from Glossarist documents, and the dataset URN from `register.yaml`; emits canonical JSON plus a static HTML document per URN at a path derived from the URN itself. Every URN the register emits resolves against the artifact set
-- **`Provenance`** — S5 build provenance: sha256 of every input and output (files or directory trees) plus Ruby/Expressir/Suma toolchain versions, written as canonical JSON by `build --provenance FILE`. `Provenance.verify` recomputes the digests independently; `build --sign minisign|sigstore` (with `--sign-key` where needed) optionally signs the manifest, and `bin/release_provenance` signs keylessly with cosign in the release workflow (`SUMA_PROVENANCE_SIGN`)
+- **`ArtifactServer`** — T2 development server for the resolved artifact tree (`serve DIRECTORY`): dependency-free TCP responder negotiating JSON vs HTML by the Accept header at URN-derived paths; production hosting maps the same paths statically
+- **`GcrPackage`** — T2 packaging (`package-gcr`): bundles extracted concepts into a GCR archive for the Glossarist Vocabulary Browser — `metadata.yaml` (identity, statistics, schema_version), `register.yaml`, and `concepts/` in the browser's canonical flat format (`termid`, `term`, `{lang}` blocks). Standard variant only; `created_at` is injectable for byte-reproducible archives
+- **`Provenance`** — S5 build provenance: sha256 of every input and output (files or directory trees) plus Ruby/Expressir/Suma toolchain versions, written as canonical JSON by `build --provenance FILE`. `Provenance.verify` recomputes the digests independently and reports unrecorded files under the recorded output roots (`_site`, `schema_docs`, `plain_schemas`); explicit exclusions cover build metadata such as the site state file and staged store. `build --sign minisign|sigstore` (with `--sign-key` where needed) optionally signs the manifest, and `bin/release_provenance` signs keylessly with cosign in the release workflow (`SUMA_PROVENANCE_SIGN`). `Provenance.render_toolchain` keys rendered-document reuse
 - **`LinkValidator`** — validates EXPRESS cross-reference links against a `SchemaIndex`; returns `LinkValidationResult` structs for unresolved links
 
 ### CLI structure

data/README.adoc

@@ -49,10 +49,13 @@ $ suma
   suma convert-jsdai XML_FILE IMAGE_FILE OUTPUT_DIR                   # Convert JSDAI XML and image files to SVG and EXP
   suma export *FILES -o OUTPUT                                        # Export EXPRESS schemas or project them to OWL
   suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract entity concepts to Glossarist v3
+  suma ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE [-o OUT]    # Overlay translated content onto extracted concepts
   suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH             # Generate hierarchical register.yaml
   suma generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE  # Generate a schema manifest from a site manifest
   suma reformat EXPRESS_FILE_PATH                                     # Reformat EXPRESS files
   suma resolve [URN] --manifest=MANIFEST -o OUTPUT                    # Emit canonical JSON + HTML for URNs
+  suma package-gcr CONCEPTS_DIR --register=REGISTER -o OUTPUT         # Package concepts into a .gcr archive
+  suma serve DIRECTORY                                                # Serve resolved artifacts (Accept negotiation)
   suma validate SUBCOMMAND ...ARGS                                    # Validate express documents
 ----
 
@@ -85,6 +88,20 @@ Options:
 The generated `schemas-*.yaml` file name is derived from the input file name
 with the word `metanorma` replaced with `schemas`.
 
+Repeated builds reuse work and are reproducible: a schema document is rendered
+again only when its adoc, schema config, schema source, or the rendering
+toolchain changed, and the collection render is skipped entirely when no site
+input changed (state: `_site/.suma-site-build.json`). Metanorma's random
+manifest identifiers and per-document type markers are canonicalized, so two
+identical builds produce byte-identical output. A provenance manifest covers
+`schema_docs`, `plain_schemas`, and `_site`, and verification reports files
+that appeared under those roots without being recorded (build metadata such as
+the site state file is excluded explicitly).
+
+Top-level schema documents render with live cross-reference links: every
+`schema.entity` and `entity.attribute` reference Expressir emits becomes an
+in-page link, and `suma validate anchors` verifies that no link is dead.
+
 [example]
 ====
 .To compile SRL subset test collection
@@ -210,6 +227,19 @@ $ suma validate closure SCHEMAS_MANIFEST [DOCUMENTS_PATH] [--format terminal|jso
 When `DOCUMENTS_PATH` is given, documentation-layer link failures are merged
 into the same report.
 
+==== Anchors subcommand
+
+The `anchors` subcommand checks rendered schema documents for dead links:
+every Expressir cross-reference (`<<schema.entity,...>>`,
+`<<entity.attribute,...>>`) emitted in a compiled `doc_*.adoc` must have a
+matching anchor in its rendered `doc_*.html`, and every in-page `href` must
+point at an existing id. It exits non-zero on violations.
+
+[source,sh]
+----
+$ suma validate anchors SCHEMA_DOCS_PATH
+----
+
 
 === Generate schemas command
 
@@ -337,6 +367,37 @@ $ bundle exec suma extract-terms schemas-activity-modules.yml terms_output
 ----
 ====
 
+=== Ingest translations command
+
+The `suma ingest-translations` command overlays translated content onto
+extracted concepts. A translations file is a YAML sequence of
+localized-concept documents, each keyed by concept id (or localized
+UUID) and carrying the fields to apply:
+
+[source,yaml]
+----
+- concept_id: example_schema.part
+  data:
+    language_code: fra
+    terms:
+      - designation: pièce
+        type: expression
+        normative_status: preferred
+    definition:
+      - content: "Composant d'un assemblage."
+----
+
+Every field the entry provides replaces that localization's field; every
+field it omits keeps the source-language content (a language absent from
+the extracted concepts is created with the same stable UUID convention
+the linked localizations use). Updated concepts are written in place, or
+to `--output` when given.
+
+[source,sh]
+----
+$ suma ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE [-o OUTPUT_DIR]
+----
+
 
 === Generate register command
 
@@ -695,6 +756,7 @@ names, and the ordered register categories. Registered profiles:
 
 `iso10303`:: Default; STEP conventions including `/applications/` classifying as an application protocol
 `generic`:: No STEP conventions (one category for every schema)
+`ifc`:: buildingSMART IFC editions: one standalone schema per edition (`ifc4`, `ifc4x3`, ...), edition names preserved uppercase (`IFC4`, `IFC4X3`), Ifc-prefixed declarations, one `Other Schemas` register category
 
 An AP publication is a lead schema bundled with the module and resource
 schemas it USEs. `--publication SCHEMA_ID` computes the transitive
@@ -727,6 +789,45 @@ $ suma export --format owl --corpus --urn urn:iso:std:iso:10303:-2:ed-2:en \
     -o OUTPUT schemas.yaml
 ----
 
+=== Package concepts for the Vocabulary Browser
+
+The `package-gcr` command bundles extracted concepts into a GCR
+(Glossarist Concept Repository) archive — the sealed distribution format
+consumed by the Glossarist Vocabulary Browser:
+
+[source,sh]
+----
+$ suma package-gcr CONCEPTS_DIR --register register.yaml \
+    --shortname my-dataset --version 1.0.0 \
+    --title "My Dataset" --description "Concepts from my corpus" \
+    -o OUT
+----
+
+The archive contains `metadata.yaml` (identity, statistics), the original
+`register.yaml`, and `concepts/` in the browser's canonical flat format
+(`termid`, `term`, one block per language). Both a versioned
+(`{shortname}-{version}.gcr`) and an unversioned (`{shortname}.gcr`)
+archive are written. Pass `--created-at` to pin the package timestamp for
+byte-reproducible archives. Point the browser's `datasets.yml` at the
+published archive (or at the concepts directory in development via
+`localPath`).
+
+=== Serve resolved artifacts
+
+`suma serve` serves a `resolve --all` artifact tree at its URN-derived
+paths, returning JSON or HTML according to the request's `Accept`
+header:
+
+[source,sh]
+----
+$ suma serve OUT --port 2113
+$ curl -H "Accept: application/json" \
+    http://localhost:2113/urn/iso/std/iso/10303/-2/ed-2/en/tech/action_schema.action
+----
+
+Production hosting maps the same paths statically; no application server
+is required.
+
 === Resolve URNs command
 
 The `resolve` command turns URNs into static, dereferenceable artifacts: a

data/lib/suma/anchor_validator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Suma
+  # Validates that every cross-reference a rendered schema document emits
+  # resolves inside it. The Expressir hyperlinked source emits xref macros
+  # (`<<schema.entity,...>>`, `<<entity.attribute,...>>`); when a target is
+  # missing, the renderer silently drops the link, so the check is done on
+  # the source macros against the anchors present in the rendered HTML —
+  # plus the reverse check that every in-page href hits an existing id.
+  class AnchorValidator
+    XREF_PATTERN = /<<([^,>]+)(?:,[^>]*)?>>/
+    ID_PATTERN = /id="([^"]+)"/
+    FRAGMENT_PATTERN = /href="#([^"]+)"/
+
+    # @param directory [String] tree of compiled schema docs (doc_*.adoc
+    #   with their rendered doc_*.html)
+    def initialize(directory)
+      @directory = directory
+    end
+
+    # @return [Array<LinkValidationResult>] dead links (empty = valid)
+    def validate
+      Dir.glob(File.join(@directory, "**", "doc_*.adoc"))
+        .flat_map { |adoc| validate_document(adoc) }
+    end
+
+    private
+
+    def validate_document(adoc)
+      html = adoc.sub(/\.adoc\z/, ".html")
+      return [missing_html(adoc, html)] unless File.file?(html)
+
+      content = File.read(adoc)
+      ids, fragments = rendered_digests(html)
+
+      xref_violations(adoc, content, ids, fragments) +
+        fragment_violations(html, ids)
+    end
+
+    def rendered_digests(html)
+      rendered = File.read(html)
+      [rendered.scan(ID_PATTERN).flatten.uniq,
+       rendered.scan(FRAGMENT_PATTERN).flatten.uniq]
+    end
+
+    def xref_violations(adoc, content, ids, fragments)
+      content.scan(XREF_PATTERN).flatten.uniq.filter_map do |target|
+        next if cross_document?(target) || resolved?(target, ids, fragments)
+
+        LinkValidationResult.new(
+          file: adoc, line: nil, link: target,
+          reason: "cross-reference has no anchor in the rendered document"
+        )
+      end
+    end
+
+    def fragment_violations(html, ids)
+      File.read(html).scan(FRAGMENT_PATTERN).flatten.uniq.filter_map do |frag|
+        next if ids.include?(frag)
+
+        LinkValidationResult.new(
+          file: html, line: nil, link: "##{frag}",
+          reason: "in-page link points at no anchor in the document"
+        )
+      end
+    end
+
+    # Xrefs that cross documents (Asciidoctor `path.adoc#anchor` syntax)
+    # resolve against other pages and are out of scope here.
+    def cross_document?(target)
+      target.include?("/") || target.include?("#")
+    end
+
+    def resolved?(target, ids, fragments)
+      ids.include?(target) || fragments.include?(target)
+    end
+
+    def missing_html(adoc, html)
+      LinkValidationResult.new(
+        file: adoc, line: nil, link: html,
+        reason: "no rendered HTML next to the adoc source"
+      )
+    end
+  end
+end

data/lib/suma/artifact_server.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Suma
+  # Development server for the emitted URN artifact tree: serves the
+  # static files at their URN-derived paths, negotiating JSON vs HTML by
+  # the Accept header. Production hosting maps the same paths statically.
+  class ArtifactServer
+    DEFAULT_PORT = 2113
+
+    attr_reader :directory, :port
+
+    # @param directory [String] the resolve output directory
+    # @param port [Integer] TCP port; 0 picks an ephemeral port
+    def initialize(directory, port: DEFAULT_PORT)
+      @directory = File.expand_path(directory)
+      @port = port
+    end
+
+    # Resolve one HTTP request to a response.
+    #
+    # @param path [String] request path (with or without extension)
+    # @param accept [String, nil] Accept header value
+    # @return [Array(String, String, String)] status, content type, body
+    def call(path, accept = nil)
+      clean = path.to_s.split("?").first.to_s
+      return not_found if clean.include?("..")
+
+      clean = "/index.html" if clean.empty? || clean == "/"
+      file = artifact_file(clean, accept)
+      return not_found unless file
+
+      ["200", content_type(file), File.read(file, encoding: "utf-8")]
+    end
+
+    # Handle a single connection (one HTTP request).
+    def serve(socket)
+      request = socket.gets&.strip
+      return unless request
+
+      accept = read_headers(socket)["accept"]
+      status, type, body = call(request.split[1].to_s, accept)
+      socket.write(
+        "HTTP/1.1 #{status} #{status_name(status)}\r\n" \
+        "Content-Type: #{type}\r\nContent-Length: #{body.bytesize}\r\n" \
+        "Connection: close\r\n\r\n#{body}",
+      )
+    ensure
+      socket&.close
+    end
+
+    # Accept connections until interrupted.
+    def start
+      server = TCPServer.new("localhost", @port)
+      @port = server.addr[1]
+      Utils.log "Serving #{@directory} at http://localhost:#{@port}"
+      loop { serve(server.accept) }
+    ensure
+      server&.close
+    end
+
+    private
+
+    def read_headers(socket)
+      headers = {}
+      while (line = socket.gets) && line != "\r\n" && !line.strip.empty?
+        key, value = line.split(":", 2)
+        headers[key.strip.downcase] = value.strip if value
+      end
+      headers
+    end
+
+    def artifact_file(clean, accept)
+      base = clean.delete_prefix("/")
+      candidates = if base.end_with?(".json", ".html")
+                     [base]
+                   else
+                     wants_json = accept.to_s.include?("application/json")
+                     ["#{base}.#{wants_json ? 'json' : 'html'}"]
+                   end
+      candidates.map { |candidate| File.join(@directory, candidate) }
+        .find { |file| File.file?(file) }
+    end
+
+    def content_type(file)
+      if file.end_with?(".json")
+        "application/json"
+      else
+        "text/html; charset=utf-8"
+      end
+    end
+
+    def not_found
+      ["404", "text/plain", "not found\n"]
+    end
+
+    def status_name(status)
+      status == "200" ? "OK" : "Not Found"
+    end
+  end
+end

data/lib/suma/cli/artifact_server_cli.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Suma
+  module Cli
+    # Serve the emitted URN artifact tree with Accept negotiation.
+    class ArtifactServerCli < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "serve DIRECTORY", "Serve resolved URN artifacts locally"
+      option :port, type: :numeric, default: ArtifactServer::DEFAULT_PORT,
+                    desc: "TCP port to listen on"
+      def serve(directory)
+        Utils.log "Ctrl-C stops the server."
+        ArtifactServer.new(directory, port: options[:port]).start
+      end
+    end
+  end
+end

data/lib/suma/cli/build.rb

@@ -33,6 +33,9 @@ module Suma
       option :sign_key, type: :string,
                         desc: "Signing key (minisign requires it; sigstore " \
                               "signs keylessly when omitted)"
+      option :no_valid, type: :boolean, default: false,
+                        desc: "Skip Metanorma document validation " \
+                              "(equivalent of metanorma --no-valid)"
 
       def build(metanorma_site_manifest)
         unless File.exist?(metanorma_site_manifest)
@@ -62,6 +65,7 @@ module Suma
           provenance_file: options[:provenance],
           sign_method: options[:sign],
           sign_key: options[:sign_key],
+          no_valid: options[:no_valid],
         ).run
       end
 

data/lib/suma/cli/core.rb

@@ -42,6 +42,8 @@ module Suma
                     desc: "Sign the provenance manifest: minisign or sigstore"
       option :sign_key, type: :string,
                         desc: "Signing key (sigstore signs keylessly when omitted)"
+      option :no_valid, type: :boolean, default: false,
+                        desc: "Skip Metanorma document validation"
       def build(_site_manifest)
         Cli::Build.start
       end
@@ -70,6 +72,8 @@ module Suma
                        desc: "Owning edition recorded on each concept"
       option :language_codes, type: :array,
                               desc: "Additional linked localization languages"
+      option :profile, type: :string, default: "iso10303",
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       def extract_terms(schema_manifest_file, glossarist_output_path)
         TermExtractor.new(
           schema_manifest_file,
@@ -78,6 +82,7 @@ module Suma
           language_code: options[:language_code],
           edition: options[:edition],
           language_codes: options[:language_codes],
+          profile: options[:profile],
         ).call
       end
 
@@ -94,7 +99,7 @@ module Suma
       option :owner, type: :string, default: Suma::RegisterManifestGenerator::DEFAULT_OWNER,
                      desc: "Owner of the dataset (e.g. 'ISO/TC 184/SC 4')"
       option :profile, type: :string, default: "iso10303",
-                       desc: "Corpus profile (iso10303 or generic)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :year, type: :numeric,
                     desc: "Edition year for the register"
       option :supersedes, type: :string,
@@ -141,7 +146,7 @@ module Suma
                                  "USE-FROM/REFERENCE closure (manifest " \
                                  "input only)"
       option :profile, type: :string, default: "iso10303",
-                       desc: "Corpus profile (iso10303 or generic)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :format, type: :string, default: "express", banner: "FORMAT",
                       desc: "Output format: express (default) or owl"
       option :corpus, type: :boolean, default: false,
@@ -164,8 +169,7 @@ module Suma
       desc "validate SUBCOMMAND ...ARGS", "Validate express documents"
       subcommand "validate", Cli::Validate
 
-      desc "resolve [URN]", "Resolve URNs to canonical JSON + HTML artifacts"
-      # Mirrors so Core accepts the switches Cli::Resolve reparses; the
+      desc "resolve [URN]", "Resolve URNs to canonical JSON + HTML artifacts" # Mirrors so Core accepts the switches Cli::Resolve reparses; the
       # inner class owns their declarations.
       option :manifest, type: :string, required: true,
                         desc: "Schema manifest used for schema/entity URNs"
@@ -183,6 +187,48 @@ module Suma
         Cli::Resolve.start
       end
 
+      desc "package-gcr CONCEPTS_DIR",
+           "Package extracted concepts into a .gcr archive"
+      # Mirrors so Core accepts the switches Cli::PackageGcr reparses; the
+      # inner class owns their declarations.
+      option :register, type: :string, required: true,
+                        desc: "register.yaml (dataset identity)"
+      option :shortname, type: :string, required: true,
+                         desc: "Dataset id"
+      option :version, type: :string, required: true,
+                       desc: "Semver of this dataset release"
+      option :title, type: :string, required: true,
+                     desc: "Human-readable dataset title"
+      option :description, type: :string, required: true,
+                           desc: "Dataset description"
+      option :created_at, type: :string,
+                          desc: "Package timestamp (pin for reproducibility)"
+      option :output, type: :string, aliases: "-o", required: true,
+                      desc: "Output directory for the .gcr archives"
+      def package_gcr(_concepts_dir)
+        Cli::PackageGcr.start
+      end
+
+      desc "ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE",
+           "Overlay translated localized-concept content onto extracted " \
+           "Glossarist concepts"
+      # Mirrors so Core accepts the switches Cli::IngestTranslations
+      # reparses; the inner class owns their declarations.
+      option :output, type: :string, aliases: "-o",
+                      desc: "Write updated concepts here (default: " \
+                            "update CONCEPTS_DIR in place)"
+      def ingest_translations(_concepts_dir, _translations_file)
+        Cli::IngestTranslations.start
+      end
+
+      desc "serve DIRECTORY", "Serve resolved URN artifacts locally"
+      option :port, type: :numeric,
+                    default: Suma::ArtifactServer::DEFAULT_PORT,
+                    desc: "TCP port to listen on"
+      def serve(_directory)
+        Cli::ArtifactServerCli.start
+      end
+
       desc "check_svg_quality [PATH]",
            "Check SVG quality and sort by severity (critical files first)"
       option :pattern, type: :string, default: Cli::CheckSvgQuality::DEFAULT_PATTERN,

data/lib/suma/cli/export.rb

@@ -35,7 +35,7 @@ module Suma
                                  "USE-FROM/REFERENCE closure (manifest " \
                                  "input only)"
       option :profile, type: :string, default: "iso10303",
-                       desc: "Corpus profile (iso10303 or generic)"
+                       desc: "Corpus profile (iso10303, generic, or ifc)"
       option :format, type: :string, default: "express", banner: "FORMAT",
                       desc: "Output format: express (default) or owl"
       option :corpus, type: :boolean, default: false,