chore(01-02): bootstrap Python 3.12 toolchain, Git LFS and package skeleton

- Pin Python 3.12.12 (.python-version) to match the ZeroGPU runtime; 3.11 and
3.13 are both invalid there
- Arm Git LFS for .vrm/.vvm/.wav/.onnx before any binary lands in the repo
- Add pyproject.toml with pytest ini options, ruff config and a dev extra
- Create src/japanese_avatar package skeleton (ui, voice, telemetry) and tests/
- Add tests/test_scaffold.py proving interpreter version, importability, config
and LFS arming
- Commit uv.lock so Space rebuilds are reproducible

.gitattributes

@@ -0,0 +1,4 @@
+*.vrm  filter=lfs diff=lfs merge=lfs -text
+*.vvm  filter=lfs diff=lfs merge=lfs -text
+*.wav  filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+node_modules/
+.env
+voicevox_runtime/
+test-results/

.python-version

@@ -0,0 +1 @@
+3.12.12

pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "japanese-learning-avatar"
+version = "0.1.0"
+description = "A lip-synced VRM avatar that speaks and hears Japanese, on a Hugging Face Space"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "gradio==6.22.0",
+    "spaces==0.51.1",
+    "huggingface_hub==1.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-playwright>=0.5",
+    "playwright>=1.48",
+    "ruff>=0.6",
+    "numpy>=1.26",
+    "requests>=2.32",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/japanese_avatar"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+addopts = "-q --strict-markers"
+markers = [
+    "deployed: requires a live Space; skipped unless --space-url is given",
+    "slow: takes more than ~10s",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+# ruff 0.16+ lints and formats Python code blocks embedded in Markdown. Planning docs,
+# research notes and design snippets are prose, not source: excluding *.md keeps the lint
+# gate about shipped Python and stops doc snippets from failing `ruff format --check`.
+extend-exclude = ["avatar/vendor", "*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.format]
+quote-style = "double"

src/japanese_avatar/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tests/test_scaffold.py

@@ -0,0 +1,34 @@
+"""Proves the toolchain works before any real code exists."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_python_version_matches_space_runtime():
+    assert sys.version_info[:2] == (3, 12), (
+        "ZeroGPU provides only Python 3.10.13 and 3.12.12; this project pins 3.12.12"
+    )
+
+
+def test_package_importable():
+    import japanese_avatar
+
+    assert japanese_avatar.__version__
+
+
+def test_ruff_and_pytest_configured():
+    import tomllib
+
+    cfg = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+    assert cfg["tool"]["ruff"]["target-version"] == "py312"
+    assert "pytest" in cfg["tool"]
+
+
+def test_lfs_armed_before_any_binary_lands():
+    """Plans 01-01 and 01-04 commit tens of megabytes. A non-LFS push of that size is rejected."""
+    for path in ("avatar/assets/tutor.vrm", "voicevox/model/zundamon.vvm", "tests/fixtures/x.wav"):
+        out = subprocess.run(
+            ["git", "check-attr", "filter", "--", path], capture_output=True, text=True, check=True
+        ).stdout
+        assert "filter: lfs" in out, f"{path} is not LFS-tracked; see .gitattributes"