move docs to docs/ folder, rewrite readme and contributing

docs/contributing.md

@@ -0,0 +1,63 @@
+# Contributing
+
+## Project structure
+```
+foreignthon/
+├── packages/
+│   ├── foreignthon/               # core engine + fpy CLI
+│   │   ├── src/foreignthon/
+│   │   │   ├── cli.py             # fpy commands
+│   │   │   ├── transpiler.py      # tokenizer-based transpiler + @@ pre-pass
+│   │   │   ├── pack.py            # language pack loader + entry point discovery
+│   │   │   └── errors.py          # bilingual error hook
+│   │   └── tests/
+│   └── langs/
+│       ├── es/                    # foreignthon-es (Spanish)
+│       └── ta/                    # foreignthon-ta (Tamil)
+├── docs/
+└── .gitea/workflows/
+├── ci.yml                     # runs tests + lint on every push
+└── publish.yml                # builds + publishes to PyPI on git tag
+```
+
+## How the transpiler works
+
+1. **Pre-pass** — scans for `@@keyword` postfix syntax and rewrites lines to prefix form
+2. **Tokenizer** — uses Python's `tokenize` module to swap `NAME` tokens. Strings and comments are never touched.
+3. **Runner** — compiles with the original filename so tracebacks point to your `.es.py` file, not a temp file
+
+## Setup
+
+```bash
+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
+```
+
+## Running tests
+
+```bash
+pytest packages/foreignthon/tests/ -v
+```
+
+## Linting
+
+```bash
+ruff check packages/foreignthon/src
+```
+
+## Adding a language pack
+
+See [language-packs.md](language-packs.md) for the full guide.
+
+## CI
+
+Every push to `main` runs tests and lint (non-blocking). Releases are triggered by pushing a git tag — see [releasing.md](releasing.md).
+
+## Submitting changes
+
+1. Fork the repo
+2. Create a branch
+3. Make your changes + add tests if relevant
+4. Open a pull request against `main`