chore(docs): convert README.md to README.adoc — adoc is estate standard

Author: hyperpolymath

README.adoc

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+
+= PolyglotFormalisms.Elixir
+:toc: preamble
+:icons: font
+
+Elixir implementation of the PolyglotFormalisms Common Library specification.
+
+== Overview
+
+This package provides Elixir implementations of fundamental operations defined
+in the PolyglotFormalisms specification, enabling semantic equivalence
+verification across multiple programming languages.
+
+== Modules
+
+=== Arithmetic
+
+* `add(a, b)` — Addition
+* `subtract(a, b)` — Subtraction
+* `multiply(a, b)` — Multiplication
+* `divide(a, b)` — Division
+* `modulo(a, b)` — Modulo (integer operation)
+
+=== Comparison
+
+* `less_than(a, b)` — Strict less than
+* `greater_than(a, b)` — Strict greater than
+* `equal(a, b)` — Equality
+* `not_equal(a, b)` — Inequality
+* `less_equal(a, b)` — Less than or equal
+* `greater_equal(a, b)` — Greater than or equal
+
+=== Logical
+
+* `logical_and(a, b)` — Logical conjunction
+* `logical_or(a, b)` — Logical disjunction
+* `logical_not(a)` — Logical negation
+
+NOTE: Function names include `logical_` prefix to avoid conflicts with Elixir's Kernel reserved keywords.
+
+== Installation
+
+[source,elixir]
+----
+def deps do
+  [
+    {:polyglot_formalisms, "~> 0.2.0"}
+  ]
+end
+----
+
+== Usage
+
+[source,elixir]
+----
+alias PolyglotFormalisms.{Arithmetic, Comparison, Logical}
+
+sum = Arithmetic.add(2.0, 3.0)
+product = Arithmetic.multiply(4.0, 5.0)
+is_less = Comparison.less_than(2.0, 3.0)
+is_equal = Comparison.equal(5.0, 5.0)
+both_true = Logical.logical_and(true, true)
+either_true = Logical.logical_or(false, true)
+negated = Logical.logical_not(false)
+----
+
+== Mathematical Properties
+
+=== Arithmetic Properties
+
+* Commutativity (for add, multiply)
+* Associativity (for add, multiply)
+* Identity elements
+* Distributivity
+
+=== Comparison Properties
+
+* Transitivity
+* Reflexivity
+* Symmetry
+* Asymmetry
+
+=== Logical Properties
+
+* Commutativity
+* Associativity
+* Distributivity
+* De Morgan's laws
+* Excluded middle
+* Non-contradiction
+
+== Behavioral Semantics
+
+=== Float Operations
+
+* Division by zero returns `Infinity` or `-Infinity`
+* NaN propagation follows IEEE 754
+* Comparison with NaN returns `false`
+
+=== Integer Operations
+
+* Modulo uses Erlang `rem` operator semantics
+* Modulo by zero raises `ArithmeticError` (BEAM behavior)
+
+=== Boolean Operations
+
+* Short-circuit evaluation for `and` and `or`
+* Eager evaluation for wrapper functions
+
+== Testing
+
+[source,bash]
+----
+mix test
+mix test --include doctest
+----
+
+== Cross-Language Verification
+
+This Elixir implementation is semantically equivalent to:
+
+* Julia implementation (PolyglotFormalisms.jl)
+* ReScript implementation (alib-for-rescript)
+* Gleam implementation (polyglot_formalisms_gleam)
+
+Formal verification proofs demonstrating semantic equivalence are available in
+the main PolyglotFormalisms specification repository.
+
+== Documentation
+
+[source,bash]
+----
+mix docs
+----
+
+== Architecture
+
+See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.
+
+== Related Projects
+
+* https://github.com/hyperpolymath/PolyglotFormalisms.jl[PolyglotFormalisms.jl] — Julia reference implementation
+* https://github.com/hyperpolymath/alib-for-rescript[alib-for-rescript] — ReScript implementation
+* https://github.com/hyperpolymath/polyglot_formalisms_gleam[polyglot_formalisms_gleam] — Gleam implementation
+
+Wondering how this works? See link:EXPLAINME.adoc[].
+
+== License
+
+SPDX-License-Identifier: PMPL-1.0-or-later +
+See link:LICENSE[LICENSE].