move docs to docs/ folder, rewrite readme and contributing

docs/getting-started.md

@@ -0,0 +1,80 @@
+# Getting Started
+
+## Installation
+
+```bash
+pip install foreignthon
+pip install foreignthon-es   # add Spanish
+pip install foreignthon-ta   # add Tamil
+```
+
+For CLI use across projects, prefer pipx:
+
+```bash
+pipx install foreignthon
+```
+
+## Writing a file
+
+Name your file `script.<lang>.py` — the extension tells ForeignThon which language pack to use.
+
+```python
+# script.es.py
+definir sumar(a, b):
+    retornar a + b
+
+para i en rango(5):
+    imprimir(sumar(i, 1))
+```
+
+## Running
+
+```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
+```
+
+## Overriding the language
+
+Via shebang comment at the top of the file:
+
+```python
+# foreignthon: es
+```
+
+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
+File "script.es.py", line 3
+
+## Variable names
+
+Variable names are optional — you can use English or your language freely:
+
+```python
+# both work fine in the same file
+definir calculate(anchura, altura):
+    area = anchura * altura
+    retornar area
+```
+
+## Local dev setup
+
+```bash
+git clone <repo>
+cd foreignthon
+python -m venv .venv && source .venv/bin/activate
+pip install -e "packages/foreignthon[dev]"
+pip install -e packages/langs/es
+pip install -e packages/langs/ta
+pytest packages/foreignthon/tests/ -v
+```