added cli reference

docs/cli-reference.md

@@ -1 +1,117 @@
 # CLI Reference
+
+All commands support `-h` / `--help`.
+
+---
+
+## `fpy new`
+
+Scaffold a new ForeignThon project.
+
+```bash
+fpy new <name> --lang <code>       # create in new directory
+fpy new --lang <code>              # initialize current directory (must be empty)
+fpy new <name> --lang <code> --no-git
+fpy new <name> --lang custom       # scaffold a blank language pack
+```
+
+| Flag | Description |
+|---|---|
+| `--lang`, `-l` | Language code — required |
+| `--no-git` | Skip `git init` and initial commit |
+
+!!! note "Using `--lang custom`"
+    Prompts for a language code, English name, and native name. Creates a `custom.json` with all Python keywords pre-filled as stubs and wires it up in `.foreignthon.toml` automatically.
+
+---
+
+## `fpy run`
+
+Transpile and run a source file.
+
+```bash
+fpy run script.es.py
+fpy run script.py --lang es        # override language detection
+fpy run script.es.py --keep        # also write the compiled .py to disk
+```
+
+| Flag | Description |
+|---|---|
+| `--lang`, `-l` | Override language detection |
+| `--keep` | Write `.compiled.py` alongside source after running |
+
+---
+
+## `fpy compile`
+
+Transpile to standard Python without running.
+
+```bash
+fpy compile script.es.py                 # → script.compiled.py (same directory)
+fpy compile script.es.py -o dist/        # → dist/script.compiled.py
+fpy compile script.es.py -o output.py    # → output.py
+```
+
+| Flag | Description |
+|---|---|
+| `--output`, `-o` | Output file or directory |
+
+---
+
+## `fpy decompile`
+
+Convert standard Python back to a foreign language. Keywords and builtins are translated — variable names are untouched.
+
+```bash
+fpy decompile script.py --lang es
+fpy decompile script.py --lang es --postfix
+fpy decompile script.py --lang es -o out/
+```
+
+| Flag | Description |
+|---|---|
+| `--lang`, `-l` | Target language — required |
+| `--postfix` | Rewrite conditionals to `@@` postfix style |
+| `--output`, `-o` | Output file or directory |
+
+!!! note
+    Decompile is lossy — variable names and comments are not translated back. It is useful for bootstrapping a foreign-language version of an existing Python file, not as a perfect round-trip.
+
+---
+
+## `fpy check`
+
+Validate syntax without running.
+
+```bash
+fpy check script.es.py
+# ✓ script.es.py looks good.
+# or
+# ✗ Syntax error: invalid syntax (script.es.py, line 4)
+```
+
+Exits with code `1` on failure — useful in CI pipelines.
+
+---
+
+## `fpy pack`
+
+Validate a language pack JSON file against the required schema.
+
+```bash
+fpy pack mylang.json
+# ✓ Pack 'Russian' is valid.
+# or
+# ✗ Missing sections: {'error_messages'}
+```
+
+---
+
+## Language detection order
+
+When running a file, ForeignThon resolves the language in this order:
+
+1. `--lang` flag (highest priority)
+2. Shebang comment: `# foreignthon: es`
+3. File extension: `.es.py` → `es`
+4. `.foreignthon.toml` in the project root