relaton 3.0.0.pre.alpha.17 → 3.0.0.pre.alpha.19

data/lib/relaton/omg/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-omg is a Ruby gem that searches and fetches standards from The Object Management Group (OMG) at https://www.omg.org. It is part of the larger Relaton family of bibliographic data gems (v2.0.0-alpha.1).
+
+## Commands
+
+- **Run all tests:** `bundle exec rspec`
+- **Run a single test:** `bundle exec rspec spec/relaton/omg/item_spec.rb`
+- **Lint:** `bundle exec rubocop` (follows Ribose OSS style guide)
+- **Lint with autofix:** `bundle exec rubocop -a`
+- **Install deps:** `bundle install`
+
+## Architecture
+
+### Module structure
+
+All source lives under `lib/relaton/omg/`. The main entry point is `lib/relaton/omg.rb` which loads everything under the `Relaton::Omg` module namespace.
+
+### Class hierarchy
+
+The gem extends `relaton-bib` (~> 2.0.0-alpha.1), the core Relaton bibliographic data library:
+
+- `Relaton::Omg::Item` < `Bib::Item` — base item class, uses `Omg::ItemData` model (subclass of `Bib::ItemData`)
+- `Relaton::Omg::Ext` < `Bib::Ext` — overrides `get_schema_version` to return the OMG model version
+- `Relaton::Omg::Bibitem` < `Item` — includes `Bib::BibitemShared`, for `<bibitem>` XML
+- `Relaton::Omg::Bibdata` < `Item` — includes `Bib::BibdataShared`, for `<bibdata>` XML
+- `Relaton::Omg::Docidentifier` < `Bib::Docidentifier` — the document id, backed by `Pubid::Omg`; `Item` declares it, so XML and YAML deserialization produce it too
+- `Relaton::Omg::Processor` < `Core::Processor` — relaton-core integration, delegates to `Bibliography`, `Bibitem`, `Item`
+- `Relaton::Omg::Bibliography` — fetches standards via `Scraper`
+- `Relaton::Omg::Scraper` — scrapes https://www.omg.org/spec for bibliographic data
+
+### References are parsed with pubid
+
+OMG uses `Pubid::Omg` and no hand regex. The flavor historically had no index
+and no data repository (the BSI and CEN shape: parse the reference, and back
+the document id with pubid). That changed: **relaton-data-omg** now crawls
+www.omg.org/spec and serves the machine index on Pages (the relaton#206
+contract), and `Relaton::Omg::INDEXFILE = "index-v2"` names it — the gem-side
+consumer flip (reading the machine index in `Bibliography` the way the other
+flavors do) is the follow-up; retrieval still scrapes live.
+
+The grammar is `OMG <ACRONYM>[ <VERSION>][<sep><PART>]`, where `<sep>` is a
+space, or a slash after a version. The version can carry a beta label (`2.5 beta`,
+`2.0 beta 1`). The part is a volume or a format name (`Superstructure`, `PDF`).
+
+- **`get` takes a String or a `Pubid::Omg::Identifier`** (the parse that
+  `Relaton::Db` routed with, relaton#205). `Scraper.scrape_page` parses only a
+  String, and the log keys print `ref.to_s`.
+- **An unrecognized reference raises.** `Scraper.scrape_page` lets
+  `Pubid::Errors::ParseError` propagate, so
+  `OMG Model Driven Architecture Guide rev. 2.0` raises and does not show as
+  "Not found". Only the transport errors are rescued, by name.
+- **The request URL is the acronym and the version, and nothing else.**
+  `get_doc` builds `https://www.omg.org/spec/<ACRONYM>/<VERSION>`, with each
+  space of the version turned into `/` (`1.0 beta 2` becomes `1.0/beta/2`). The
+  part stays out of the URL: `fetch_link` uses it to find the part's PDF link
+  on the version page, and `fetch_title` appends it. The cassettes replay only
+  while the URL does not change.
+- **The docid version comes from the page, not from the query.** That is why
+  `get "OMG AMI4CCM"` answers `OMG AMI4CCM 1.1`. `fetch_docid` and the History
+  ids of `fetch_relation` are rendered by
+  `Pubid::Omg::Identifiers::Specification`, not by parsing a joined string.
+- **pubid renders one separator.** `OMG DDS 1.4/PDF` renders back as
+  `OMG DDS 1.4 PDF`. Both spellings name the same document, and one rendering
+  keeps `==` and `matches?` true between them. If you echo a caller's
+  reference, echo the string, not `pubid.to_s`.
+- **Known limit.** OMG's URL spelling `Beta2` (label and number joined) parses
+  as a part, not a version. It round-trips, so nothing is lost.
+- **The acronym is the URL segment, verbatim.** 30 of the 270 acronyms in the
+  OMG catalog carry a hyphen, a slash, a plus, or start in lower case
+  (`DDS-XTypes`, `EDMC-FIBO/BE`, `VSIPL++`, `smartant`). pubid PR #376 accepts
+  all 270. A slash **before** the version belongs to the acronym
+  (`OMG EDMC-FIBO/BE 1.1` fetches `spec/EDMC-FIBO/BE/1.1`); a slash **after**
+  the version separates the part. So `OMG UML/Superstructure` is the acronym
+  `UML/Superstructure`; write the part behind a space. With pubid `ce2f75ef`
+  (PR #372) those 30 raised, and the migration waited for #376. Fix a grammar
+  gap in pubid; do not split the acronym in the flavor.
+
+`Docidentifier` parses its `content` on the data side and rescues the parse, so
+a value that is not an OMG identifier stays verbatim with a nil `pubid`. Its
+mutators:
+
+- `remove_date!` drops the **version**. OMG identifiers carry no date, and the
+  version is the discriminator, as IALA maps `remove_date!` onto its edition.
+  So `to_most_recent_reference` turns `OMG AMI4CCM 1.0` into `OMG AMI4CCM`.
+- `remove_part!` drops the part: `OMG UML 2.1.1 Superstructure` becomes
+  `OMG UML 2.1.1`.
+- `to_all_parts!` is the inherited no-op. An OMG part is a name, not a numbered
+  part, so there is no "all parts" form.
+
+The processor sets `@pubid_flavor = :Omg`. That changes nothing today:
+`Pubid::Omg.prefixes` is `["OMG"]`, the same as `@prefix`.
+
+### Publication date comes from JSON-LD, not the visible text
+
+`Scraper#pub_date` reads the `publicationDate` value out of the page's
+`application/ld+json` block, not the `<dt>Publication Date:</dt>` text. Two
+reasons, both verified against cassettes:
+
+- **Locale.** The OMG server renders the month name in its own locale, and
+  Cloudflare caches that variant. A response can carry `Content-Language: zh-CN`
+  with an otherwise English page (`<html lang="en">`) and a `<dd>七月 2007</dd>`,
+  which made `Date.parse` raise `Date::Error`. The request already sends
+  `Accept-Language: en-us,en;q=0.5`; the CDN answers `Vary: accept-encoding`
+  only, so it does not vary on language and no request header can prevent this.
+- **Precision.** The visible text is a lossy render of the same value:
+  `2013-03-31` prints as "March 2013". Parsing the text rounded every OMG date
+  down to day 01.
+
+The `<dd>` text stays as a fallback for a page with no JSON-LD, and a month name
+it cannot parse logs a warning instead of raising.
+`spec/omg/relaton/omg/scraper_spec.rb` guards all three paths with
+`spec/omg/fixtures/localized_date.html`. Do not "simplify" the parser back to
+the `<dd>` text.
+
+### Serialization formats
+
+Items can be serialized to/from YAML and XML. Tests verify round-trip fidelity for all three classes. XML output is validated against RELAX NG schemas in `grammars/`.
+
+### Test patterns
+
+- RSpec with `expect` syntax (monkey patching disabled)
+- `equivalent-xml` for XML comparison
+- `ruby-jing` for RELAX NG schema validation against `grammars/relaton-omg-compile.rng`
+- VCR cassettes in `spec/vcr_cassettes/` for HTTP interaction recording
+- Fixtures in `spec/fixtures/` (YAML and XML reference files)
+- Tests follow a round-trip pattern: load fixture → parse → serialize → compare to fixture
+
+## Style
+
+- Ruby >= 3.1.0
+- Rubocop inherits from Ribose OSS guide with `rubocop-rails` required but Rails cops disabled
+- OMG document reference format: `OMG {ACRONYM}[ {VERSION}][ {PART}]` (e.g., `OMG AMI4CCM 1.0`, `OMG UML 2.1.1 Superstructure`)

data/lib/relaton/omg/README.adoc

@@ -0,0 +1,101 @@
+= Relaton::Omg
+
+RelatonOmg is a Ruby gem that searches and fetches standards from https://www.omg.org[The Object Management Group (OMG)].
+
+The standards are scraped from https://www.omg.org/spec
+
+== Usage
+
+=== Search document
+
+Reference format is `OMG + {ACRONYM} + {VERSION}`
+
+- `ACRONYM` is an acronym from the list of specs https://www.omg.org/spec/#all
+- `VERSION` (optional) if omitted then the latest version is fetched
+
+[source,ruby]
+----
+require 'relaton/omg'
+=> true
+
+item = Relaton::Omg::Bibliography.get 'OMG AMI4CCM 1.0'
+[relaton-omg] INFO: (OMG AMI4CCM 1.0) Fetching from www.omg.org ...
+[relaton-omg] INFO: (OMG AMI4CCM 1.0) Found: `OMG AMI4CCM 1.0`
+=> #<Relaton::Bib::ItemData:0x0000000128bf7650
+...
+
+# Return nil if the document doesn't exist.
+Relaton::Omg::Bibliography.get 'OMG 1111'
+[relaton-omg] INFO: (OMG 1111) Fetching from www.omg.org ...
+[relaton-omg] INFO: (OMG 1111) Not found.
+=> nil
+----
+
+=== Serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="OMGAMI4CCM10" schema-version="v1.4.1">
+      <fetched>2026-02-27</fetched>
+      <title language="en" script="Latn" type="main">Asynchronous Method Invocation for CCM</title>
+      <uri type="src">https://www.omg.org/spec/AMI4CCM/1.0/About-AMI4CCM</uri>
+      <uri type="pdf">https://www.omg.org/spec/AMI4CCM/1.0/PDF</uri>
+      <docidentifier type="OMG" primary="true">OMG AMI4CCM 1.0</docidentifier>
+      ...
+    </bibitem>"
+
+item.to_xml bibdata: true
+=>  "<bibdata schema-version="v1.4.1">
+      <fetched>2026-02-27</fetched>
+      <title language="en" script="Latn" type="main">Asynchronous Method Invocation for CCM</title>
+      <uri type="src">https://www.omg.org/spec/AMI4CCM/1.0/About-AMI4CCM</uri>
+      <uri type="pdf">https://www.omg.org/spec/AMI4CCM/1.0/PDF</uri>
+      <docidentifier type="OMG" primary="true">OMG AMI4CCM 1.0</docidentifier>
+      ...
+    </bibdata>"
+----
+
+=== Typed links
+
+OMG documents may have `src` and `pdf` link source types.
+
+[source,ruby]
+----
+item.source[0].type
+=> "src"
+
+item.source[0].content
+=> "https://www.omg.org/spec/AMI4CCM/1.0/About-AMI4CCM"
+----
+
+=== Create bibliographic item from XML
+
+[source,ruby]
+----
+xml = File.read 'spec/fixtures/omg_ami4ccm_1_0.xml', encoding: 'UTF-8'
+item = Relaton::Omg::Bibitem.from_xml xml
+=> #<Relaton::Bib::ItemData:0x00000001248f8c00
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+yaml = File.read 'spec/fixtures/omg_ami4ccm_1_0.yaml', encoding: 'UTF-8'
+item = Relaton::Omg::Item.from_yaml yaml
+=> #<Relaton::Bib::ItemData:0x000000012813b180
+...
+----
+
+=== Logging
+
+RelatonOmg uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-omg.
+
+== License
+
+The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT License].

data/lib/relaton/plateau/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-plateau is a Ruby gem for retrieving and managing bibliographic metadata for Project PLATEAU (Japanese 3D city model standards published by MLIT). It is part of the Relaton ecosystem of bibliographic gems.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/relaton/plateau/bibitem_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/plateau/bibitem_spec.rb:15
+
+# Lint
+bundle exec rake rubocop
+
+# Default rake task (runs specs)
+bundle exec rake
+```
+
+## Architecture
+
+All code lives in `lib/relaton/plateau/`. The gem uses LutaML::Model::Serializable for data modeling with automatic XML/YAML serialization.
+
+### Models
+- **Item** (`item.rb`) — base Plateau item extending `Bib::Item`, declares `model ItemData` and adds `ext` attribute
+- **ItemData** (`item_data.rb`) — data class extending `Bib::ItemData`, returned by `Item.from_xml`, `Item.from_yaml`, and `Bibliography.get`
+- **Bibitem** (`bibitem.rb`) — bibliographic item variant (includes `Bib::BibitemShared`)
+- **Bibdata** (`bibdata.rb`) — bibliographic data variant (includes `Bib::BibdataShared`)
+- **Ext** (`ext.rb`) — extension element: doctype, subdoctype, flavor, editorialgroup, stagename, filesize, etc.
+- **Doctype** (`doctype.rb`) — extends `Bib::Doctype`, valid values: `handbook`, `technical-report`, `annex`
+
+### Retrieval & Data Fetching
+- **Bibliography** (`bibliography.rb`) — module with `get(code)` for index-based document retrieval, returns `ItemData`
+- **HitCollection** / **Hit** — search the relaton-data-plateau index and fetch YAML documents
+- **DataFetcher** (`data_fetcher.rb`) — extends `Core::DataFetcher`, scrapes MLIT JSON APIs for handbooks and technical reports
+- **Parser** / **HandbookParser** / **TechnicalReportParser** — parse JSON into `ItemData` objects
+- **Processor** (`processor.rb`) — standard Relaton processor plugin (`get`, `from_xml`, `from_yaml`, `fetch_data`, `grammar_hash`)
+
+### Serialization Methods
+- `bib.to_xml` — XML (bibitem format)
+- `Item.to_yaml(bib)` — YAML (class method)
+- `bib.to_rfcxml` — BibXML/RFC XML
+- `Item.from_xml(xml)` — parse XML into `ItemData`
+- `Item.from_yaml(yaml)` — parse YAML into `ItemData`
+
+### Data Sources
+- Handbooks: `https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/handbooks.json`
+- Technical Reports: `https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/technical-reports.json`
+- Pre-fetched index: `https://raw.githubusercontent.com/relaton/relaton-data-plateau/v2/` (`HitCollection::ENDPOINT`)
+
+### Pubid-backed index (index-v2)
+
+The index is **pubid-structured** (`_type: pubid:plateau:*` rows), mirroring
+NIST/CIE. The producer and the consumer `Relaton::Index.find_or_create` call
+sites (`data_fetcher.rb`, `hit_collection.rb`) pass
+`pubid_class: ::Pubid::Plateau::Identifier`, and `INDEXFILE = "index-v2"`.
+`processor.rb#remove_index_file` passes `url: true` and `file:` only: the delete
+never reads the index (see `lib/relaton/index/CLAUDE.md`).
+
+**Ids are pubid-canonical.** The parsers emit the form `Pubid::Plateau.parse`
+accepts, which also matches the MLIT source:
+- Handbook: `PLATEAU Handbook #NN 第X.Y版` (Japanese edition label — the parser
+  keeps the source `第X.Y版`; the Latinized `#edition` is retained only for the
+  structured `Bib::Edition`/`ext` fields).
+- Technical Report: `PLATEAU Technical Report #NN` (**no edition** — pubid TRs
+  carry none; the document still has a `1.0` `Bib::Edition`).
+- Sub-numbers use a hyphen (`#46-1`), not the source underscore (`#46_1`).
+
+`DataFetcher#save_document` parses the canonical id via `#pubid` (a round-trip
+guard: `from_hash(to_hash) == to_hash`) and stores the `Pubid::Plateau::Identifier`
+object; unparseable ids are warned and skipped (defensive — the parser already
+emits canonical, so nothing is expected to skip).
+
+**Search accepts both forms.** `HitCollection#find` parses the query via `#ref`
+(`Pubid::Plateau.parse`, memoized; an unparseable query **raises**
+`Pubid::Errors::ParseError`; `Bibliography.get` rescues transport errors only,
+as `Relaton::RequestError`, and `Hit#item` raises that same error on a
+non-200) and matches on **pubid objects**, mirroring the
+other pubid flavors: an exact edition uses `index.search(ref, exact: true)`
+(pubid `==` compares type + number + annex + edition); a family query
+(`ref.edition.nil?` — an edition-less handbook, or any Technical Report) uses
+the default subset match `ref === row`, where the omitted edition matches any
+value. pubid declares `annex` strict for PLATEAU (pubid#408), so
+`PLATEAU Handbook #03` does not reach the annex `#03-1`;
+`hit_collection_spec.rb` pins that against the index fixture. This keeps the
+family-vs-exact decision and the match on the *same* parsed identifier (no raw
+`@ref` regex). Canonical (`第1.0版`), edition-less (`#00`), and **legacy Latin**
+(`#00 1.0`) references all resolve — `Pubid::Plateau` normalizes Latin input to
+the canonical id (metanorma/pubid #269; needs the pubid `main` pin). No
+relaton-side Latin shim exists by design.
+
+`EDITION_SUFFIX` is **not** used for matching; it lives only in `#to_all_editions`,
+which strips the edition off the fetched document's `Bib::Docidentifier`/docnumber
+**strings** (relaton-bib content, not pubid) to build the family record — it
+matches both Japanese and Latin suffixes so it works against the current (Latin)
+VCR-cassette documents and future canonical ones.
+
+### Schema Validation
+RNG grammar files in `grammars/` define the XML schema. Tests validate fixtures against `relaton-plateau-compile.rng` using the `ruby-jing` gem.
+
+## Testing
+
+- **Index fixture:** `spec/fixtures/index-v2.zip` (pubid-backed, `_type: pubid:plateau:*` rows) is pre-loaded into the `Relaton::Index` pool in `before(:suite)` via a `Relaton::Index::Type` built with `::Pubid::Plateau::Identifier` (configured in `spec/support/webmock.rb`, mirroring NIST/CIE). Run `rake spec:update_index` to refresh from relaton-data-plateau.
+- RSpec with `expect` syntax (no monkey-patching)
+- VCR cassettes record HTTP interactions (in `spec/fixtures/vcr_cassettes/`)
+- `equivalent-xml` for XML comparison assertions
+- `jing` matcher for RNG schema validation
+- SimpleCov for code coverage
+
+## Key Conventions
+
+- Document identifiers are pubid-canonical: `PLATEAU Handbook #XX 第Y.Z版` (Japanese edition) or `PLATEAU Technical Report #XX` (no edition); sub-numbers use a hyphen (`#XX-N`). See "Pubid-backed index" above.
+- The gem supports multi-format serialization: XML, YAML, BibXML (RFC XML)
+- RuboCop follows Ribose OSS style guide; target Ruby version is 3.0
+- The `ext` element in XML/YAML carries PLATEAU-specific metadata (doctype, flavor, editorialgroup, etc.)

data/lib/relaton/plateau/README.adoc

@@ -0,0 +1,139 @@
+= Relaton::Plateau: retrieve Project PLATEAU Standards for bibliographic use using the ItemData model
+
+RelatonPlateau is a Ruby gem that implements the https://github.com/relaton/relaton-model-plateau[ItemData model].
+
+You can use it to retrieve metadata of Plateau Standards from the GitHub repository, and access such metadata through the `Relaton::Plateau::ItemData` object.
+
+== Usage
+
+=== Fetching
+
+==== Fetching Technical Reports
+
+[source,ruby]
+----
+require "relaton/plateau"
+
+Relaton::Plateau::Bibliography.get("PLATEAU Technical Report #00")
+[relaton-plateau] INFO: (PLATEAU Technical Report #00) Fetching ...
+[relaton-plateau] INFO: (PLATEAU Technical Report #00) Found `PLATEAU Technical Report #00 1.0`
+=> #<Relaton::Plateau::ItemData:0x00000001236204e8
+...
+----
+
+==== Fetching Handbooks unversioned
+
+[source,ruby]
+----
+Relaton::Plateau::Bibliography.get("PLATEAU Handbook #00")
+[relaton-plateau] INFO: (PLATEAU Handbook #00) Fetching ...
+[relaton-plateau] INFO: (PLATEAU Handbook #00) Found `PLATEAU Handbook #00`
+=> #<Relaton::Plateau::ItemData:0x00000001242bd200
+...
+----
+
+==== Fetching Handbooks versioned
+
+[source,ruby]
+----
+bib = Relaton::Plateau::Bibliography.get("PLATEAU Handbook #00 1.0")
+[relaton-plateau] INFO: (PLATEAU Handbook #00 1.0) Fetching ...
+[relaton-plateau] INFO: (PLATEAU Handbook #00 1.0) Found `PLATEAU Handbook #00 1.0`
+=> #<Relaton::Plateau::ItemData:0x0000000124157320
+...
+----
+
+=== Serializing
+
+==== XML
+
+[source,ruby]
+----
+puts bib.to_xml
+=> "<bibitem id="PLATEAUHandbook0010" type="standard" schema-version="v1.4.1">
+      <title language="en" script="Latn" type="main">PLATEAU Guidebook</title>
+      <uri type="pdf">https://www.mlit.go.jp/plateau/file/libraries/doc/plateau_doc_0000_ver01.pdf</uri>
+      <docidentifier type="PLATEAU" primary="true">PLATEAU Handbook #00 1.0</docidentifier>
+      ...
+    </bibitem>"
+
+puts bib.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.4.1">
+      <title language="en" script="Latn" type="main">PLATEAU Guidebook</title>
+      <uri type="pdf">https://www.mlit.go.jp/plateau/file/libraries/doc/plateau_doc_0000_ver01.pdf</uri>
+      <docidentifier type="PLATEAU" primary="true">PLATEAU Handbook #00 1.0</docidentifier>
+      ...
+      <ext schema-version="v0.0.2">
+        <doctype>handbook</doctype>
+        <flavor>plateau</flavor>
+        <structuredidentifier type="Handbook">
+          <agency>PLATEAU</agency>
+          <docnumber>00</docnumber>
+          <edition>1.0</edition>
+        </structuredidentifier>
+        <filesize>18381880</filesize>
+      </ext>
+    </bibdata>"
+----
+
+==== YAML
+
+[source,ruby]
+----
+bib.to_yaml
+=> "---
+    id: PLATEAUHandbook0010
+    type: standard
+    schema_version: v1.4.1
+    ..."
+----
+
+=== Create from XML
+
+[source,ruby]
+----
+Relaton::Plateau::Item.from_xml File.read("spec/fixtures/handbook.xml")
+=> #<Relaton::Plateau::ItemData:0x0000000123b99118
+...
+----
+
+=== Create from YAML
+
+[source,ruby]
+----
+Relaton::Plateau::Item.from_yaml File.read("spec/fixtures/item.yaml")
+=> #<Relaton::Plateau::ItemData:0x00000001209fd208
+...
+----
+
+=== Fetching data
+
+Two datasets are available for fetching: `plateau-handbooks` and `plateau-technical-reports`. The format can be `xml`, `yaml`, or `bibxml`.
+
+[source,ruby]
+----
+require "relaton/plateau/data_fetcher"
+
+Relaton::Plateau::DataFetcher.fetch("plateau-handbooks", output: "dir", format: "xml")
+Started at: 2026-03-02 15:36:03 -0500
+Stopped at: 2026-03-02 15:36:04 -0500
+Done in: 1 sec.
+----
+
+== Logging
+
+RelatonPlateau uses https://github.com/relaton/relaton-logger[relaton-logger] for logging. By default, it logs to STDERR. To change the log level and output, use `Relaton.logger_pool` and `Relaton.logger`.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To update the index test fixture (used by tests), run `rake spec:update_index`. This downloads the latest `index-v2.zip` from the https://github.com/relaton/relaton-data-plateau[relaton-data-plateau] repository.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-plateau
+
+== License
+
+The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT license].

data/lib/relaton/sdo/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+Dev notes for `Relaton::Sdo` — the SDO organization & logo store.
+
+## What this is
+
+A **non-flavor** component that answers metanorma#346 (central logo store) and
+its sister relaton-db#132 (map abbreviation → organisation name/translation).
+It is **not** a bibliographic flavor: it has **no processor**, **no
+`Db::Registry` entry**, and is not reachable from `Db#fetch`. It is a standalone
+top-level store, exposed through `Relaton.organization`.
+
+This deliberately honors the scope decision in `lib/relaton/db/CLAUDE.md`
+("org metadata … kept out of the processors"): nothing here touches a processor.
+The user's choice was to still surface it from the `relaton` gem itself (one
+`require`, one entry point) as a **lazily-autoloaded** component — referencing
+`Relaton::Sdo` or calling `Relaton.organization` is what loads it.
+
+## Public API
+
+```ruby
+org = Relaton.organization("ISO")   # case-insensitive; nil if unknown
+org.name                            # default (untranslated) name
+org.name("fr")                      # translation, or nil
+org.name(language: "fr")            # same, via the language: keyword
+org.logo_query(format:, size:, style:)  # all args optional → matching Logo list
+org.logo(format:, size:, style:)        # one Logo: nil if 0, the match if 1,
+                                        # raises Sdo::Error if the filter is ambiguous
+logo.content    # raw binary (lazy HTTP GET of logo.url, memoized)
+logo.data_uri   # "data:<mime>;base64,…"
+logo.save               # write to a filename derived from the URL; returns path
+logo.save("/path.eps")  # write to a custom path
+```
+
+## Data model & retrieval flow
+
+`Store` (singleton) lazily builds an index from a single **`index.yaml`**
+manifest served by the `relaton-data-sdo` data repo, and memoizes it (`reset!`
+drops the memo — used by specs). Shape:
+
+```yaml
+organizations:
+  ISO:
+    name:
+      - content: International Organization for Standardization   # default
+      - { language: fr, content: Organisation internationale de normalisation }
+    logo:
+      - { style: default, format: eps, size: 700x300, url: "https://…/iso.eps" }
+      - { style: red, format: svg, url: "https://…/red.svg",
+          applicability: "stage>=60" }   # opaque text; the store never interprets it
+```
+
+- **`style`** is the primary discriminator for multiple logos per org (e.g.
+  `default`, `red`, `grey`, `iso_1972`, `white_paper_2022`, BIPM `si_aspect_full`).
+- **`applicability`** (year/stage/doctype/cover-color rules) is carried through
+  verbatim and exposed; **selection is the consumer's job** (metanorma), not the
+  store's.
+
+`Config` (`Relaton::Sdo.configuration`) holds the index `url`, the cache
+`storage_dir` (default `~/.relaton/sdo`), the `storage` backend (defaults to
+`Relaton::Index::FileStorage`; swappable, e.g. S3), and the `ttl` (24 h).
+`Fetcher.fetch_index` serves a fresh on-disk copy within the TTL, re-downloads
+otherwise, and falls back to a stale cache if the network fails. A URL with no
+scheme (or `file://`) is read straight off disk — handy for fixtures/specs. Logo
+binaries are fetched on demand and memoized on the `Logo` (no disk cache yet).
+
+## Tests
+
+`spec/sdo/` is a self-contained suite (auto-discovered by `rake spec`). It uses
+WebMock to stub the index and logo URLs, points `storage_dir` at a fresh
+`Dir.mktmpdir` per example, and resets the store between examples. It
+`require "relaton"` because the public entry point (`Relaton.organization`)
+lives in the root entry file, which the shared spec_helper does not load.
+
+## Scope / not yet done
+
+- The real `relaton-data-sdo` data repo (assets + build GHA) — see
+  `HANDOFFS/relaton__relaton-data-sdo.md`. Until it publishes, `Config#url`
+  points at its (future) raw `index.yaml`.
+- No structured interpretation of `applicability`; no on-disk cache of logo
+  binaries; no writeback/authoring.

data/lib/relaton/un/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-un is a Ruby gem that provides bibliographic data models for UN documents, part of the Relaton family of gems. It extends `relaton-bib` with UN-specific metadata using the LutaML-Model serialization framework. Currently on the `lutaml-integration` branch undergoing a major migration from the old `RelatonUn` namespace to `Relaton::Un`.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests (also the default rake task)
+bundle exec rake spec
+
+# Run a specific test file
+bundle exec rspec spec/relaton/un/bibitem_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/un/bibitem_spec.rb:7
+
+# Lint
+bundle exec rubocop
+
+# Interactive console with gem loaded
+bin/console
+```
+
+## Architecture
+
+### Flavor Model Pattern
+
+The gem follows the Relaton flavor pattern: base classes from `relaton-bib` (`Bib::Item`) are extended with a flavor-specific `Ext` class containing UN-specific metadata.
+
+```
+Bib::ItemData (from relaton-bib)
+  └── Relaton::Un::ItemData    # UN flavor identity, enables NamespaceHelper#namespace → Relaton::Un
+
+Bib::Item (from relaton-bib)
+  └── Relaton::Un::Item        # model ItemData; adds Ext attribute
+        ├── Relaton::Un::Bibitem   # includes Bib::BibitemShared (for <bibitem> XML)
+        └── Relaton::Un::Bibdata   # includes Bib::BibdataShared (for <bibdata> XML)
+```
+
+### Lookup
+
+`Bibliography.get` takes a String (`UN TRADE/CEFACT/2004/32`, the `UN ` token
+optional) or a parsed `Pubid::Un::Identifier`, which renders the document
+symbol without the token (`TRADE/CEFACT/2004/32`) — the form the UN data
+itself writes. Either becomes the symbol the search matches (`document_symbol`).
+`Relaton::Db` routes UN by the `UN ` prefix (`Registry#route` falls back to
+`class_by_ref`): `Pubid::Un` renders the symbol without the token, so a
+`UN …` reference is not an exact parse. A symbol without the token
+(`TRADE/CEFACT/2004/32`) is not routed at all — no flavor claims it — and
+raises `Relaton::UnknownReferenceError`. `Pubid::Un` also parses a bare DOI
+exactly (`10.6028/NIST.IR.8245`), but UN does not claim it (`10.` is a DOI
+prefix), so it does not route to UN either.
+
+### Key Classes (all in `lib/relaton/un/`)
+
+- **ItemData** — extends `Bib::ItemData`; the UN-specific data container used by `Item` via `model ItemData`
+- **Item** — extends `Bib::Item`, adds `ext` attribute of type `Ext`
+- **Bibitem / Bibdata** — extend Item with shared mixins for two XML serialization formats
+- **Ext** — UN-specific metadata: `doctype`, `distribution`, `session`, `submissionlanguage`, `job_number`; extends `Bib::Ext`
+- **Session** — session metadata (number, date, item numbers/names, collaborator, agenda_id)
+- **Doctype** — restricts document types to: recommendation, plenary, addendum, communication, corrigendum, reissue, agenda, budgetary, sec-gen-notes, expert-report, resolution
+
+### LutaML-Model Serialization
+
+All model classes use `Lutaml::Model::Serializable`. XML mappings are defined in `xml do` blocks:
+- `map_attribute` for XML attributes (e.g., `schema-version` → `schema_version`)
+- `map_element` for XML elements (e.g., `session-date` → `session_date`)
+- `collection: true` for array attributes
+- `values: [...]` for restricted string values
+
+### Schema Validation
+
+RelaxNG grammars in `grammars/` validate XML output. The compiled schema is `grammars/relaton-un-compile.rng`. Tests use `ruby-jing` for validation.
+
+### Testing Approach
+
+Tests are round-trip serialization tests: load a fixture, serialize to XML/YAML, compare against the original fixture. Bibitem and Bibdata specs also validate XML against the RelaxNG schema. Fixtures live in `spec/fixtures/`.
+
+## Dependencies
+
+- **relaton-bib** (~> 2.0.0-alpha.1) — base bibliographic model with LutaML-Model integration
+- **faraday** — HTTP client
+- **ruby-jing** (dev) — RelaxNG schema validation in tests
+- **equivalent-xml** (dev) — XML comparison in tests