From ac247f63db3e3513a5da9752421a8b81fb89a86b Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Sat, 28 Mar 2026 02:07:39 +0000
Subject: [PATCH] docs: restore README.md lost in Floor Raise campaign

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.adoc |   5 --
 README.md   | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+), 5 deletions(-)
 delete mode 100644 README.adoc
 create mode 100644 README.md

diff --git a/README.adoc b/README.adoc
deleted file mode 100644
index 9a2b3a2..0000000
--- a/README.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-= polyglot-formalisms-elixir
-:toc: preamble
-:icons: font
-
-
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a9e3473
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+# PolyglotFormalisms.Elixir
+
+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
+
+Add this package to your `mix.exs` dependencies:
+
+```elixir
+def deps do
+  [
+    {:polyglot_formalisms, "~> 0.2.0"}
+  ]
+end
+```
+
+## Usage
+
+```elixir
+alias PolyglotFormalisms.{Arithmetic, Comparison, Logical}
+
+# Arithmetic
+sum = Arithmetic.add(2.0, 3.0)
+product = Arithmetic.multiply(4.0, 5.0)
+
+# Comparison
+is_less = Comparison.less_than(2.0, 3.0)
+is_equal = Comparison.equal(5.0, 5.0)
+
+# Logical
+both_true = Logical.logical_and(true, true)
+either_true = Logical.logical_or(false, true)
+negated = Logical.logical_not(false)
+```
+
+## Mathematical Properties
+
+All implementations preserve the mathematical properties defined in the PolyglotFormalisms specification:
+
+### 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
+
+This implementation follows BEAM/Erlang 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
+
+Run the test suite:
+
+```bash
+mix test
+```
+
+Run tests with documentation tests:
+
+```bash
+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
+
+Generate documentation:
+
+```bash
+mix docs
+```
+
+## License
+
+PMPL-1.0-or-later (Polymathematical Meta-Public License / Palimpsest License)
+
+## Related Projects
+
+- [PolyglotFormalisms.jl](https://github.com/hyperpolymath/PolyglotFormalisms.jl) - Julia reference implementation
+- [alib-for-rescript](https://github.com/hyperpolymath/alib-for-rescript) - ReScript implementation
+- [polyglot_formalisms_gleam](https://github.com/hyperpolymath/polyglot_formalisms_gleam) - Gleam implementation
+
+
+## Architecture
+
+See [TOPOLOGY.md](TOPOLOGY.md) for a visual architecture map and completion dashboard.