docs: add root README, CONTRIBUTING, onboarding section, gitignore fixes

- README.md: new root README with CI badge, per-service table, quick start,
  CI pipeline table, file budget docs, and links to production endpoints
- CONTRIBUTING.md: dev environment setup, pre-commit checklist, commit
  marker reference, architecture non-negotiables, Claude Code section
- CLAUDE.md: insert First-Time Setup & Claude Code Onboarding section with
  branch guard, hook explanation, guardrail marker table, and staging rules
- REFACTOR_PLAYBOOK.md: commit existing refactor playbook doc
- .gitignore: add dist/, .turbo/, pnpm-lock.yaml, .pnpm-store/ to prevent
  SDK build artifacts from appearing as untracked files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/CLAUDE.md

@@ -12,6 +12,33 @@
 
 
 
+## First-Time Setup & Claude Code Onboarding
+
+**For humans:** Read this CLAUDE.md top to bottom before your first commit. Then read `AGENTS.<lang>.md` for the service you are working on (`AGENTS.python.md`, `AGENTS.go.md`, or `AGENTS.typescript.md`).
+
+**For Claude Code sessions — things that cause first-commit failures:**
+
+1. **Wrong branch.** Run `git branch --show-current` before touching any file. The answer must be `coolify`. If it is `main`, run `git checkout coolify` before proceeding.
+
+2. **PreToolUse hook blocks your write.** The `PreToolUse` hooks in `.claude/settings.json` will reject Write/Edit operations on any file that would push its line count past 500. This is intentional — split the file into smaller modules instead of trying to bypass the hook.
+
+3. **Missing `[guardrail-change]` marker.** The `guardrail-integrity` CI job fails if you modify a guardrail file without the marker in the commit message body. See the table below.
+
+4. **Never `git add -A` or `git add .`.** Stage files individually by path. `git add -A` risks committing `.env`, `node_modules/`, `.next/`, compiled binaries, and other artifacts that must never enter the repo.
+
+5. **LOC check before push.** After any session, run `bash scripts/check-loc.sh`. It must exit 0 before you push. The git pre-commit hook runs this automatically, but run it manually first to catch issues early.
+
+### Commit message quick reference
+
+| Marker | Required when touching |
+|--------|----------------------|
+| `[guardrail-change]` | `.claude/settings.json`, `scripts/check-loc.sh`, `scripts/githooks/pre-commit`, `.claude/rules/loc-exceptions.txt`, any `AGENTS.*.md` |
+| `[migration-approved]` | Anything under `migrations/` or `alembic/versions/` |
+
+Add the marker anywhere in the commit message body or footer — the CI job does a plain-text grep for it.
+
+---
+
 ## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)
 
 ### Zwei-Rechner-Setup + Coolify