diff --git a/README.md b/README.md
index 1ceec9e..6b7fbed 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,126 @@
-# foreignthon-ta 
+# foreignthon-ta
 
-Tamil language pack for ForeignThon.
+Tamil language pack for [ForeignThon](https://foreignthon.keshavanand.net/) — write Python in தமிழ்.
+
+---
 
 ## Install
 
 ```bash
-pip install foreignthon foreignthon-ta 
+pip install foreignthon foreignthon-ta
 ```
 
-## Usage
+---
 
-```py 
-fpy run main.ta.py
+## Example
+
+**`fizzbuzz.ta.py`**
+
+```python
+நிரல்பாகம் fizzbuzz(n):
+    ஆக i உள்ளே வரம்பு(1, n + 1):
+        i % 15 == 0 @@ஆனால்:
+            பதிப்பி("FizzBuzz")
+        i % 3 == 0 @@இல்லைஆனால்:
+            பதிப்பி("Fizz")
+        i % 5 == 0 @@இல்லைஆனால்:
+            பதிப்பி("Buzz")
+        மற்றபடி:
+            பதிப்பி(i)
+
+fizzbuzz(20)
 ```
 
-## What's translated
+This uses Tamil's natural SOV word order — the condition comes first, then the keyword with `@@`. See [Postfix Syntax](https://foreignthon.keshavanand.net/postfix-syntax/) for details.
 
-- **Keywords** — {keywords}
-- **Builtins** — {builtins}
-- **Exceptions** — {exceptions}
-- **Stdlib** — {stdlib}
+Compiles to standard Python:
 
-{postfix_section}
+```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)
+
+fizzbuzz(20)
+```
+
+---
+
+## Keyword reference
+
+| Python | தமிழ் |
+|---|---|
+| `if` | `ஆனால்` |
+| `else` | `மற்றபடி` |
+| `elif` | `இல்லைஆனால்` |
+| `for` | `ஆக` |
+| `while` | `வரை` |
+| `def` | `நிரல்பாகம்` |
+| `class` | `கோப்பு` |
+| `return` | `பின்கோடு` |
+| `import` | `இறக்கு` |
+| `True` | `உண்மை` |
+| `False` | `பொய்` |
+| `None` | `ஒன்றுமில்லை` |
+| `print` | `பதிப்பி` |
+| `input` | `உள்ளீடு` |
+| `len` | `நீளம்` |
+| `range` | `வரம்பு` |
+
+Full mapping: [`ta.json`](https://git.keshavanand.net/foreign-thon/foreignthon-ta/raw/branch/main/src/foreignthon_ta/ta.json)
+
+---
+
+## Postfix syntax
+
+Tamil is SOV — the condition naturally comes before the keyword. The `@@` operator lets you write it that way:
+
+```python
+# prefix style (also valid)
+ஆனால் x > 0:
+    பதிப்பி(x)
+
+# postfix style — natural Tamil order
+x > 0 @@ஆனால்:
+    பதிப்பி(x)
+```
+
+Both compile identically. Decompile standard Python with postfix output:
+
+```bash
+fpy decompile script.py --lang ta --postfix
+```
+
+---
+
+## Start a project
+
+```bash
+fpy new myproject --lang ta
+cd myproject
+fpy run src/main.ta.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
-
+GPL v3