menuconform 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 497b0ace6a30de42bc5d0d494ae7c9e23206331407902b3a84a3636d809c40d0
+  data.tar.gz: cea2dfe8a743d55e2957381401d666eee1fb4bf339dabe3f147b37e938ae9ee2
+SHA512:
+  metadata.gz: 199304d9779008366dec8be4740bfb1b19e70cf89e77c84fe427b22ead45c0870f5c3a19faf60ff2c83951a97a6ce50003f1cfe4b691e817dcbd1243d2f3a8e6
+  data.tar.gz: 938be138bea321d6b64ada27c482fe46f5c56eb5b47a3cf72f16cd8923e3bfe88f99476c131eb281333d576658a799dd1440ece3b08c1a1f1502a13a3f43177e

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,156 @@
+# menuconform
+
+[![CI](https://github.com/amitkssolanki/menuconform/actions/workflows/ci.yml/badge.svg)](https://github.com/amitkssolanki/menuconform/actions/workflows/ci.yml)
+
+**Could an AI agent build a valid, correctly priced, makeable cart from your restaurant menu?**
+
+menuconform is an open-source conformance kit for restaurant menus entering the
+[Universal Commerce Protocol](https://ucp.dev) food-ordering world. Feed it a menu
+(Menu IR JSON, or an NCR Voyix Menu API export via `--from ncr-menu`) and it produces
+a scored 0–100 report with per-rule findings and fix hints written for menu owners,
+not just engineers.
+
+```
+$ menuconform check menu.json
+menuconform 0.1.0 · rules 0.1.0 · reference time 2026-08-30T00:00:00Z
+Menu: Bucky's Pizza & Wings — All Day (IR 0.2, USD, America/New_York)
+Score: 0/100   errors: 17  warns: 14  infos: 16
+
+CART-001 [error] item/itm_wings_6
+  no selection satisfies this item's modifier constraints — it cannot be ordered
+  fix: See the accompanying CONFLICT/STRUCT findings on this item's groups; ...
+PRICE-002 [warn] modifier_group/mg_pizza_toppings12
+  option mod_extra_cheese12 conditional-price matrix does not cover mod_size_xl12 ...
+  fix: Add the missing matrix entries — this is the classic 'new size added,
+       topping table not updated' undercharge.
+```
+
+## Why this exists
+
+Agent ordering is arriving faster than menu data is getting ready for it. The official
+[UCP conformance suite](https://github.com/Universal-Commerce-Protocol/conformance)
+is the *final protocol check*: pytest against a running UCP merchant server, with a
+flat `id,title,price` product model and (today) no food-domain coverage. menuconform
+is the **pre-flight check for the menu data itself**: no server required, food
+semantics only — modifier constraint satisfiability, nested-group depth, half/half
+slot pricing, size-conditional prices, availability windows, allergen and
+age-restriction completeness.
+
+The two are complementary: menuconform → build your UCP endpoint → official
+conformance suite.
+
+## What it checks
+
+Menus are validated against a language-agnostic **Menu IR** (JSON Schema 2020-12, in
+[`schema/menu_ir.schema.json`](schema/menu_ir.schema.json)), designed from a field
+study of the Uber Eats, DoorDash, Grubhub, and Checkmate menu models. The schema
+checks shape only; ~30 stable rules
+([`rules/catalog.json`](rules/catalog.json)) check meaning:
+
+| Family      | Checks |
+|-------------|--------|
+| `STRUCT-`   | schema validity, dangling references, duplicate IDs, orphans, nesting depth (>6 error, >4 warn) |
+| `CONFLICT-` | unsatisfiable constraints: min>max, required-empty groups, defaults vs limits, invalid conditional-price triggers |
+| `PRICE-`    | negative prices, incomplete topping-by-size matrices, reachable negative totals |
+| `AVAIL-`    | windows that contradict parent scopes, never-available declarations, retirement-via-86 |
+| `NAME-`     | empty names, case-insensitive duplicates, back-of-house junk (`86 DNU`, `zzz DO NOT USE`) |
+| `ALLERGEN-` | missing or contradictory allergen declarations (US big-9 ∪ EU-14 vocabulary) |
+| `AGE-`      | alcohol-indicative items without `min_age`, age-restricted items in kids categories |
+| `CART-`     | **the cart solver**: items no valid cart can be built for, defaults that violate their own constraints, no-positive-total items, equivalent carts that price differently |
+| `EXPORT-`   | lossiness against the pinned UCP draft (roadmap) |
+
+The cart solver is the differentiator: it does exact constraint satisfiability with
+recursive option selectability, so it catches menus that are *statically clean but
+unorderable* — the class of problem no field-by-field validator sees.
+
+## Scoring
+
+`score = max(0, 100 − Σ deductions)`: error −5, warn −2, info −0.5, at most 15 points
+per rule, then hard caps — any cart-blocking finding caps the score at 49, a
+schema-invalid document at 59. Deterministic: the only time input is an injectable
+`reference_time`, stated in the report. Same menu + same rules version = same score.
+
+## Install & use
+
+Not yet on RubyGems (soon). From source (Ruby ≥ 3.1):
+
+```
+git clone https://github.com/amitkssolanki/menuconform && cd menuconform
+bundle install
+bundle exec exe/menuconform check fixtures/12_legacy_sprawl/menu.json
+```
+
+CLI:
+
+```
+menuconform check MENU.json [--from FORMAT] [--json] [--reference-time ISO8601] [--fail-below SCORE]
+menuconform import --from FORMAT SOURCE.json [--config PATH] [-o OUT.json]
+menuconform rules
+menuconform version
+```
+
+## Importers
+
+`--from ncr-menu` ingests an **NCR Voyix Menu API** v2 menu-details payload
+(`nep-service-version 2A:1`): link groups map onto the IR's two constraint axes,
+Aloha-style price levels (group-scoped `prices[].linkGroupId`) lower to per-link
+price overrides, `freeQuantity` becomes `included_quantity`, and per-item
+`itemCustomModifiers` defaults are applied where unambiguous. Everything lossy
+(prep-code price multipliers, step quantities, item factors, scheduled prices,
+promotions/quick combos) is stashed under `x_` extension keys and reported as
+import notes — the same list that seeds the `EXPORT-` lossiness story. Vendor
+field mappings live in [`config/importers/ncr_menu.json`](config/importers/ncr_menu.json)
+(set `timezone` to the site's IANA zone; NCR payloads don't carry one). A
+sanitized sample export and its golden IR live in
+[`fixtures/importers/ncr_menu/`](fixtures/importers/ncr_menu/) — a clean NCR
+import scores **98/100**, because NCR's menu contract has no allergen fields at
+all: that gap is exactly what agents will trip over.
+
+Exit codes: `0` passed the gate, `1` failed (error findings, or score below
+`--fail-below`), `2` usage/input error. Ruby API:
+
+```ruby
+require "menuconform"
+report = Menuconform::Engine.new.analyze(JSON.parse(File.read("menu.json")))
+report.score      # => 0..100
+report.findings   # => [Menuconform::Finding]
+report.to_h       # => full report hash
+```
+
+## UCP export
+
+`menuconform export MENU.json` maps the IR onto the pinned UCP draft's catalog
+shapes (`product`/`variant`/`option`/`price`) and reports what the export loses as
+`EXPORT-` findings: required single-select sizes become real options/variants;
+everything else — multi-select modifiers, nested groups, conditional prices,
+half/half, allergens, age restrictions, schedules — is dropped, degraded, or makes
+the item unrepresentable (`EXPORT-001`, exit 1). The full lossy-construct analysis
+lives in [docs/export-lossiness.md](docs/export-lossiness.md). Export findings
+deliberately do **not** affect the `check` score: `check` judges your menu data,
+`export` judges the current draft's fit for food.
+
+## Fixtures
+
+[`fixtures/`](fixtures/) contains twelve menus with pinned expected findings — from
+`01_golden_path` (must score 100) to `12_legacy_sprawl`, a plausible 15-year-old
+franchise export that scores 0. They double as the conformance suite for the rules
+themselves and as worked examples of the IR. There is currently no public sample
+food menu anywhere in the UCP ecosystem; these aim to fill that gap.
+
+## UCP spec pin
+
+The IR is validated against **Menu IR v0.2**. The UCP exporter (in progress) tracks
+**UCP spec v2026-08-25** (pin checked 2026-08-30; re-pinned monthly). The IR is
+deliberately *not* coupled to the draft — menus are validated against the IR, and
+only the exporter chases the moving spec.
+
+## Roadmap
+
+- More POS-family importers and a generic CSV importer
+- UCP exporter + `EXPORT-` lossiness rules against the pinned draft
+- TypeScript port if implementers need it
+
+## License & maintainer
+
+Apache-2.0. Built and maintained by [Amit Solanki](https://github.com/amitkssolanki).
+Issues and real-world menu pathologies (sanitized!) are very welcome.

data/config/importers/ncr_menu.json

@@ -0,0 +1,12 @@
+{
+  "comment": "Mapping config for the NCR Voyix Menu API (v2 menu-details payload, nep-service-version 2A:1). Vendor field mappings live here, not in code. Override per run with --config.",
+  "timezone": null,
+  "default_currency": "USD",
+  "currency_map": {
+    "USD": "USD",
+    "US Dollar": "USD",
+    "United States Dollar": "USD"
+  },
+  "included_allocation": "cheapest_first",
+  "per_option_max_fallback": 99
+}

data/exe/menuconform

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "menuconform"
+require "menuconform/cli"
+
+exit Menuconform::CLI.run(ARGV)

data/lib/menuconform/catalog.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Menuconform
+  # Loads rules/catalog.json — the single source of truth for rule severities,
+  # titles, and fix hints.
+  class Catalog
+    def self.load(path)
+      new(JSON.parse(File.read(path, encoding: "UTF-8")))
+    end
+
+    attr_reader :rules_version
+
+    def initialize(doc)
+      @rules_version = doc.fetch("rules_version")
+      @by_id = doc.fetch("rules").to_h { |r| [r.fetch("id"), r] }
+    end
+
+    def entry(rule_id)
+      @by_id.fetch(rule_id) { raise KeyError, "rule #{rule_id} is not in the catalog" }
+    end
+
+    def severity(rule_id)
+      entry(rule_id).fetch("severity")
+    end
+  end
+end

data/lib/menuconform/cli.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "time"
+
+module Menuconform
+  # Command-line interface. Exit codes:
+  #   0 - check ran and passed the gate (no error-severity findings, or score
+  #       at/above --fail-below when given)
+  #   1 - check ran and failed the gate
+  #   2 - usage error or unreadable input
+  class CLI
+    USAGE = <<~TEXT
+      menuconform — UCP food-ordering menu conformance kit
+
+      Usage:
+        menuconform check MENU.json [options]     Validate a menu (IR, or --from a source format)
+        menuconform import --from FORMAT SRC.json Convert a source export to Menu IR JSON
+        menuconform export MENU.json [options]    Export to the pinned UCP catalog draft,
+                                                  reporting EXPORT- lossiness findings
+        menuconform rules                         List the rule catalog
+        menuconform version                       Print version
+
+      Check options:
+        --from FORMAT             Treat input as a source export; import to IR first
+        --json                    Emit the full JSON report instead of text
+        --reference-time TIME     ISO 8601 instant for time-dependent rules
+                                  (default: now; pin it for reproducible runs)
+        --fail-below SCORE        Exit 1 when the score is below SCORE
+                                  (default gate: exit 1 on any error finding)
+
+      Import options:
+        --from FORMAT             Source format (required; see below)
+        --config PATH             Override the importer's default mapping config
+        -o, --out PATH            Write IR JSON to PATH (default: stdout)
+    TEXT
+
+    def self.run(argv, stdout: $stdout, stderr: $stderr)
+      new(stdout: stdout, stderr: stderr).run(argv)
+    end
+
+    def initialize(stdout:, stderr:)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(argv)
+      case argv.first
+      when "check" then check(argv[1..])
+      when "import" then import(argv[1..])
+      when "export" then export(argv[1..])
+      when "rules" then rules
+      when "version", "--version", "-v" then @stdout.puts(VERSION) || 0
+      when "help", "--help", "-h" then @stdout.puts(USAGE) || 0
+      when nil then @stderr.puts(USAGE) || 2
+      else
+        @stderr.puts "unknown command: #{argv.first}\n\n#{USAGE}"
+        2
+      end
+    end
+
+    private
+
+    def check(args)
+      options = { json: false, reference_time: Time.now.utc, fail_below: nil, from: nil, config: nil }
+      parser = OptionParser.new do |o|
+        o.on("--from FORMAT") { |f| options[:from] = f }
+        o.on("--config PATH") { |p| options[:config] = p }
+        o.on("--json") { options[:json] = true }
+        o.on("--reference-time TIME") do |t|
+          options[:reference_time] = Time.iso8601(t)
+        rescue ArgumentError
+          return usage_error("--reference-time must be ISO 8601 (got #{t.inspect})")
+        end
+        o.on("--fail-below SCORE", Integer) { |s| options[:fail_below] = s }
+      end
+
+      begin
+        files = parser.parse(args)
+      rescue OptionParser::ParseError => e
+        return usage_error(e.message)
+      end
+      return usage_error("exactly one menu file required") unless files.size == 1
+
+      doc = read_json(files.first)
+      return doc if doc.is_a?(Integer) # usage-error exit code
+
+      if options[:from]
+        config = nil
+        if options[:config]
+          config = read_json(options[:config])
+          return config if config.is_a?(Integer)
+        end
+        begin
+          result = Importers.import(options[:from], doc, config: config)
+        rescue Importers::SourceError => e
+          return usage_error(e.message)
+        end
+        result.notes.each { |n| @stderr.puts "import note: #{n}" }
+        doc = result.doc
+      end
+
+      report = Engine.new.analyze(doc, reference_time: options[:reference_time])
+      options[:json] ? @stdout.puts(report.to_json) : render(report)
+
+      if options[:fail_below]
+        report.score < options[:fail_below] ? 1 : 0
+      else
+        report.findings.any? { |f| f.severity == "error" } ? 1 : 0
+      end
+    end
+
+    def import(args)
+      options = { from: nil, config: nil, out: nil }
+      parser = OptionParser.new do |o|
+        o.on("--from FORMAT") { |f| options[:from] = f }
+        o.on("--config PATH") { |p| options[:config] = p }
+        o.on("-o PATH", "--out PATH") { |p| options[:out] = p }
+      end
+      begin
+        files = parser.parse(args)
+      rescue OptionParser::ParseError => e
+        return usage_error(e.message)
+      end
+      return usage_error("--from FORMAT is required (known: #{Importers.names.join(', ')})") unless options[:from]
+      return usage_error("exactly one source file required") unless files.size == 1
+
+      source = read_json(files.first)
+      return source if source.is_a?(Integer)
+      config = nil
+      if options[:config]
+        config = read_json(options[:config])
+        return config if config.is_a?(Integer)
+      end
+
+      begin
+        result = Importers.import(options[:from], source, config: config)
+      rescue Importers::SourceError => e
+        return usage_error(e.message)
+      end
+      result.notes.each { |n| @stderr.puts "import note: #{n}" }
+      json = JSON.pretty_generate(result.doc)
+      options[:out] ? File.write(options[:out], json + "\n") : @stdout.puts(json)
+      0
+    end
+
+    # Artifact goes to --out (or stdout); EXPORT- findings go to stderr.
+    # Exit 1 when any EXPORT-001 (item cannot exist under the pinned draft).
+    def export(args)
+      options = { from: nil, config: nil, out: nil, reference_time: Time.now.utc }
+      parser = OptionParser.new do |o|
+        o.on("--from FORMAT") { |f| options[:from] = f }
+        o.on("--config PATH") { |p| options[:config] = p }
+        o.on("-o PATH", "--out PATH") { |p| options[:out] = p }
+        o.on("--reference-time TIME") do |t|
+          options[:reference_time] = Time.iso8601(t)
+        rescue ArgumentError
+          return usage_error("--reference-time must be ISO 8601 (got #{t.inspect})")
+        end
+      end
+      begin
+        files = parser.parse(args)
+      rescue OptionParser::ParseError => e
+        return usage_error(e.message)
+      end
+      return usage_error("exactly one menu file required") unless files.size == 1
+
+      doc = read_json(files.first)
+      return doc if doc.is_a?(Integer)
+      if options[:from]
+        config = nil
+        if options[:config]
+          config = read_json(options[:config])
+          return config if config.is_a?(Integer)
+        end
+        begin
+          result = Importers.import(options[:from], doc, config: config)
+        rescue Importers::SourceError => e
+          return usage_error(e.message)
+        end
+        result.notes.each { |n| @stderr.puts "import note: #{n}" }
+        doc = result.doc
+      end
+
+      engine = Engine.new
+      schema_gate = engine.run(doc, reference_time: options[:reference_time])
+      if schema_gate.any? { |f| f.rule == "STRUCT-001" }
+        @stderr.puts "menuconform: document fails IR schema validation; fix STRUCT-001 before exporting"
+        return 1
+      end
+
+      exporter = UcpExporter.new(catalog: engine.catalog)
+      result = exporter.call(doc, reference_time: options[:reference_time])
+
+      result[:findings].each do |f|
+        @stderr.puts "#{f.rule} [#{f.severity}] #{f.entity_type}/#{f.entity_id}: #{f.message}"
+      end
+      errors = result[:findings].count { |f| f.severity == "error" }
+      warns = result[:findings].count { |f| f.severity == "warn" }
+      exported = result[:artifact]["catalog"]["products"].size
+      @stderr.puts "exported #{exported} product(s) against UCP #{UcpExporter::UCP_SPEC_PIN}; " \
+                   "#{errors} unrepresentable item(s), #{warns} lossy construct(s)"
+
+      json = JSON.pretty_generate(result[:artifact])
+      options[:out] ? File.write(options[:out], json + "\n") : @stdout.puts(json)
+      errors.positive? ? 1 : 0
+    end
+
+    # Returns the parsed document, or an Integer exit code on failure.
+    def read_json(path)
+      JSON.parse(File.read(path, encoding: "UTF-8"))
+    rescue Errno::ENOENT, Errno::EACCES => e
+      usage_error("cannot read #{path}: #{e.message}")
+    rescue JSON::ParserError => e
+      usage_error("#{path} is not valid JSON: #{e.message[0, 120]}")
+    end
+
+    def render(report)
+      h = report.to_h
+      menu = h["menu"]
+      @stdout.puts "menuconform #{h['menuconform_version']} · rules #{h['rules_version']} · reference time #{h['reference_time']}"
+      @stdout.puts "Menu: #{menu['name']} (IR #{menu['ir_version']}, #{menu['currency']}, #{menu['timezone']})"
+      counts = h["severity_counts"]
+      @stdout.puts "Score: #{h['score']}/100   errors: #{counts['error']}  warns: #{counts['warn']}  infos: #{counts['info']}"
+      h["score_breakdown"]["hard_caps"].each { |c| @stdout.puts "  capped at #{c['cap']}: #{c['reason']}" }
+      @stdout.puts
+
+      if h["findings"].empty?
+        @stdout.puts "No findings. This menu is agent-ready under the implemented rule set."
+        return
+      end
+
+      h["findings"].each do |f|
+        entity = f["entity"]
+        @stdout.puts "#{f['rule']} [#{f['severity']}] #{entity['type']}/#{entity['id']}"
+        @stdout.puts "  #{f['message']}"
+        @stdout.puts "  fix: #{f['fix_hint']}"
+      end
+    end
+
+    def rules
+      catalog = JSON.parse(File.read(Engine::DEFAULT_CATALOG, encoding: "UTF-8"))
+      @stdout.puts "rules #{catalog['rules_version']}"
+      catalog["rules"].each do |r|
+        @stdout.puts "#{r['id'].ljust(13)} #{r['severity'].ljust(5)} #{r['title']}"
+      end
+      0
+    end
+
+    def usage_error(message)
+      @stderr.puts "menuconform: #{message}"
+      2
+    end
+  end
+end