feat(project): initialize ZUGFeRD service with pyproject.toml and directory structure

.sisyphus/notepads/zugferd-service/decisions.md

@@ -0,0 +1,29 @@
+# Decisions - zugferd-service
+
+This file accumulates architectural and design decisions during execution.
+
+## [2026-02-04T18:12:44.864Z] Session Start
+Planning decisions from Prometheus session.
+
+## Tech Stack
+- Python 3.11+
+- FastAPI for REST API
+- Pydantic for data validation
+- pytest for testing
+- factur-x library for ZUGFeRD extraction
+- pypdf for PDF text extraction
+
+## Scope Lock
+- NO authentication (stateless service)
+- NO database
+- NO caching
+- NO rate limiting
+- 10MB file size limit
+- 0.01 EUR tolerance for calculations
+
+## Validation Rules
+- pflichtfelder: Required fields check
+- betraege: Amount calculations check
+- ustid: VAT ID format check (no online validation)
+- pdf_abgleich: XML vs PDF text comparison
+

.sisyphus/notepads/zugferd-service/issues.md

@@ -0,0 +1,7 @@
+# Issues - zugferd-service
+
+This file accumulates problems, errors, and gotchas during execution.
+
+## [2026-02-04T18:12:44.864Z] Session Start
+Initial session started. No issues yet.
+

.sisyphus/notepads/zugferd-service/learnings.md

@@ -0,0 +1,44 @@
+# Learnings - zugferd-service
+
+This file accumulates conventions, patterns, and learnings during execution.
+
+## [2026-02-04T18:12:44.864Z] Session Start
+Initial session for ZUGFeRD-Service implementation.
+
+## Framework Decisions
+- FastAPI (user preference)
+- Pydantic v2+ for data models
+- pytest with pytest-asyncio for testing
+- hatchling for build system
+
+## Packaging Decisions
+- pyproject.toml (modern Python packaging)
+- Docker multi-stage build
+- Nix flake-based packaging with buildPythonApplication
+
+## Testing Decisions
+- TDD (test-first) approach
+- All acceptance criteria must be verifiable without human intervention
+
+
+## [2026-02-04T19:14:00.000Z] Task 1: Project Scaffold
+
+### hatchling Configuration Pattern
+- For src-layout projects, MUST add `[tool.hatch.build.targets.wheel]` section
+- Without this, hatchling cannot determine which files to ship
+- Config: `packages = ["src"]` to specify src directory
+
+### Nix Environment Considerations
+- Nix store is read-only, standard pip install fails
+- Use temporary venv for verification: `python -m venv /tmp/test_env`
+- Install to venv, verify imports, then cleanup
+
+### Entry Point Documentation
+- Functions referenced in `[project.scripts]` MUST have docstrings
+- These are public API entry points (CLI commands)
+- Example: `zugferd-service = "src.main:run"` -> run() needs docstring
+
+### Module Docstring Convention
+- Module-level docstrings: minimal, one line, describe purpose
+- Entry point function docstrings: Args/Returns style for CLI documentation
+- Both necessary for scaffolding clarity

.sisyphus/notepads/zugferd-service/problems.md

@@ -0,0 +1,7 @@
+# Problems - zugferd-service
+
+This file accumulates unresolved blockers.
+
+## [2026-02-04T18:12:44.864Z] Session Start
+No unresolved problems at this time.
+