docs/getting-started.md

@@ -1 +1,135 @@
 # Getting Started
+
+## Requirements
+
+- Python 3.9 or later
+- A language pack (`pip install foreignthon-xx`)
+
+---
+
+## Installation
+
+```bash
+pip install foreignthon
+```
+
+For global CLI access across projects, use `pipx`:
+
+```bash
+pipx install foreignthon
+```
+
+---
+
+## Create a project
+
+```bash
+fpy new myproject --lang <code>
+cd myproject
+```
+
+This scaffolds:
+
+```
+myproject/
+├── .foreignthon.toml   # project config
+├── .gitignore
+├── README.md
+└── src/
+    └── main.<lang>.py  # hello world in your language
+```
+
+The `.foreignthon.toml` stores your language and any local pack overrides:
+
+```toml
+[foreignthon]
+lang = "es"
+# custom_pack = "custom.json"
+```
+
+---
+
+## File naming
+
+ForeignThon detects the language from the file extension:
+
+```
+script.es.py   →  Spanish
+script.ta.py   →  Tamil
+script.fr.py   →  French
+```
+
+You can also declare the language at the top of the file:
+
+```python
+# foreignthon: es
+```
+
+Or override it at runtime:
+
+```bash
+fpy run script.py --lang es
+```
+
+---
+
+## Run
+
+```bash
+fpy run src/main.es.py
+```
+
+---
+
+## Compile
+
+```bash
+fpy compile src/main.es.py
+# → src/main.compiled.py
+```
+
+```bash
+fpy compile src/main.es.py -o dist/
+# → dist/main.compiled.py
+```
+
+The compiled file is standard Python. Commit it alongside your source — anyone can run it without ForeignThon installed.
+
+---
+
+## Validate
+
+```bash
+fpy check src/main.es.py
+# ✓ main.es.py looks good.
+```
+
+Checks syntax without running — useful in CI.
+
+---
+
+## Errors
+
+When something goes wrong, ForeignThon shows the error in your language first, then English:
+
+```
+[ES] ErrorDeDivisionCero: Error división por cero
+[EN] ZeroDivisionError: division by zero
+     File "src/main.es.py", line 8
+```
+
+Tracebacks point to your original source file, not any intermediate.
+
+---
+
+## Variable names
+
+Variable names are completely optional — English names work alongside foreign keywords with no issues. Only keywords and builtins are ever swapped.
+
+---
+
+## Next steps
+
+- [CLI Reference](cli-reference.md) — all commands and flags
+- [Language Packs](language-packs/index.md) — available languages
+- [Custom Packs](custom-packs.md) — extend or override a pack locally

docs/index.md

@@ -1 +1,42 @@
 # ForeignThon
+
+Write Python in any human language.
+
+ForeignThon is a transpiler that converts `.xx.py` files into standard Python — keywords, builtins, and exceptions all translated into your language. The compiled output runs anywhere without ForeignThon installed.
+
+---
+
+## How it works
+
+```
+source.es.py  →  fpy  →  source.compiled.py  →  Python
+```
+
+ForeignThon uses Python's `tokenize` module to swap `NAME` tokens. Strings, comments, and f-strings are never touched. The result is identical, valid Python.
+
+---
+
+## Install
+
+```bash
+pip install foreignthon
+pip install foreignthon-es   # or any other language pack
+```
+
+---
+
+## At a glance
+
+| Feature | Description |
+|---|---|
+| Transpiler | Tokenizer-based, safe, unicode-aware |
+| File format | `.xx.py` where `xx` is the language code |
+| Errors | Shown in your language first, English below |
+| Postfix syntax | `@@` operator for SOV languages |
+| Custom packs | Local JSON override, no PyPI needed |
+| CLI | `fpy run`, `fpy compile`, `fpy decompile`, `fpy new` |
+
+---
+
+[Get started →](getting-started.md){ .md-button .md-button--primary }
+[CLI Reference →](cli-reference.md){ .md-button }