readmes and mds plus fixed ruff

README.md

@@ -0,0 +1,89 @@
+DME.md << 'EOF'
+# ForeignThon
+
+Write Python in any human language. ForeignThon transpiles `.es.py`, `.ta.py` (and more) files into standard Python — keywords, builtins, exceptions, all of it.
+
+```python
+# hola.es.py
+definir saludar(nombre):
+    retornar f"Hola, {nombre}!"
+
+para i en rango(3):
+    imprimir(saludar(f"mundo {i}"))
+```
+
+```bash
+fpy run hola.es.py
+# Hola, mundo 0!
+# Hola, mundo 1!
+# Hola, mundo 2!
+```
+
+## Installation
+
+```bash
+pip install foreignthon
+pip install foreignthon-es   # Spanish
+pip install foreignthon-ta   # Tamil
+```
+
+## Usage
+
+```bash
+fpy run script.es.py            # transpile and run
+fpy compile script.es.py        # output a .compiled.py file
+fpy check script.es.py          # validate without running
+fpy pack mylang.json            # validate a language pack
+```
+
+### Language override
+
+```python
+# foreignthon: es
+# ^ overrides the file extension
+```
+
+Or via CLI flag:
+
+```bash
+fpy run script.py --lang es
+```
+
+## Errors
+
+Errors are shown in your language first, English below:
+[ES] ErrorDeDivisionCero: Error: división por cero
+[EN] ZeroDivisionError: division by zero
+
+## Language Packs
+
+A language pack is a JSON file + a tiny Python wrapper published as `foreignthon-xx` on PyPI.
+See `packages/langs/es/` for the reference implementation.
+
+The JSON covers:
+- **keywords** — `si → if`, `para → for`, `definir → def` …
+- **builtins** — `imprimir → print`, `rango → range` …
+- **exceptions** — `ErrorDeValor → ValueError` …
+- **error_messages** — bilingual error output
+- **stdlib** — `matematicas → math` …
+
+Validate your pack before publishing:
+
+```bash
+fpy pack mylang.json
+```
+
+## Development
+
+```bash
+git clone <your-repo>
+cd foreignthon
+python -m venv .venv && source .venv/bin/activate
+pip install -e "packages/foreignthon[dev]"
+pip install -e packages/langs/es
+pytest packages/foreignthon/tests/ -v
+```
+
+## License
+
+GPL