diff --git a/README.md b/README.md
index 1cd0756..7c2bc5f 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # foreignthon-es
 
-Spanish language pack for ForeignThon.
+Spanish language pack for [ForeignThon](https://foreignthon.keshavanand.net/) — write Python in Español.
+
+---
 
 ## Install
 
@@ -8,30 +10,99 @@ Spanish language pack for ForeignThon.
 pip install foreignthon foreignthon-es
 ```
 
-## Usage
+---
 
-```py
-fpy run main.es.py
+## Example
+
+**`fizzbuzz.es.py`**
+
+```python
+def fizzbuzz(n):
+    para i en dist(1, n + 1):
+        si i % 15 == 0:
+            imprimir("FizzBuzz")
+        osi i % 3 == 0:
+            imprimir("Fizz")
+        osi i % 5 == 0:
+            imprimir("Buzz")
+        sino:
+            imprimir(i)
+
+fizzbuzz(20)
 ```
 
-## What's translated
+Compiles to standard Python:
 
-- **Keywords** — {keywords}
-- **Builtins** — {builtins}
-- **Exceptions** — {exceptions}
-- **Stdlib** — {stdlib}
+```python
+def fizzbuzz(n):
+    for i in range(1, n + 1):
+        if i % 15 == 0:
+            print("FizzBuzz")
+        elif i % 3 == 0:
+            print("Fizz")
+        elif i % 5 == 0:
+            print("Buzz")
+        else:
+            print(i)
 
-{postfix_section}
+fizzbuzz(20)
+```
+
+Run it directly:
+
+```bash
+fpy run fizzbuzz.es.py
+```
+
+---
+
+## Keyword reference
+
+| Python | Español |
+|---|---|
+| `if` | `si` |
+| `else` | `sino` |
+| `elif` | `osi` |
+| `for` | `para` |
+| `while` | `mientras` |
+| `def` | `def` |
+| `class` | `clase` |
+| `return` | `retornar` |
+| `import` | `importar` |
+| `True` | `Verda` |
+| `False` | `Falso` |
+| `None` | `Nada` |
+| `print` | `imprimir` |
+| `input` | `entrada` |
+| `len` | `lon` |
+| `range` | `dist` |
+
+Full mapping: [`src/foreignthon_es/es.json`](src/foreignthon_es/es.json)
+
+---
+
+## Start a project
+
+```bash
+fpy new myproject --lang es
+cd myproject
+fpy run src/main.es.py
+```
+
+---
 
 ## Documentation
 
-→ https://foreignthon.keshavanand.net/
+→ [foreignthon.keshavanand.net](https://foreignthon.keshavanand.net/)
+
+---
 
 ## Contributing
 
-Found a missing translation or a better keyword choice? Open an issue or PR — no core access needed.
+Found a missing translation or a better keyword choice? Open an issue or PR — no access to the core repo needed.
+
+---
 
 ## License
 
 GPL v3
-