Add .gitignore and CLAUDE.md with session lessons

- Add comprehensive .gitignore for Python/HA projects
- Document mistakes and lessons learned during development

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,90 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Claude Code
+.claude/
+
+# Home Assistant
+.HA_VERSION
+home-assistant.log
+home-assistant_v2.db
+home-assistant_v2.db-shm
+home-assistant_v2.db-wal

CLAUDE.md

@@ -0,0 +1,110 @@
+# Claude Code Session Notes
+
+This file documents mistakes and lessons learned during the development of this integration.
+
+## Mistakes Made
+
+### 1. Missing `/emby` Prefix on API Endpoints
+
+**Problem:** Initially created all API endpoints without the `/emby` prefix.
+
+```python
+# Wrong
+ENDPOINT_SYSTEM_INFO = "/System/Info"
+ENDPOINT_USERS = "/Users"
+
+# Correct
+ENDPOINT_SYSTEM_INFO = "/emby/System/Info"
+ENDPOINT_USERS = "/emby/Users"
+```
+
+**Impact:** Connection to Emby server failed with "cannot connect" errors.
+
+**Lesson:** Always verify API endpoint formats against official documentation. Emby Server requires the `/emby` prefix for all API calls.
+
+---
+
+### 2. Incorrect Volume Control API Format
+
+**Problem:** Tried multiple incorrect formats for the SetVolume command before finding the correct one.
+
+```python
+# Attempt 1 - Wrong endpoint with body
+endpoint = f"/Sessions/{session_id}/Command/SetVolume"
+data = {"Arguments": {"Volume": 50}}
+
+# Attempt 2 - Wrong: query parameter
+endpoint = f"/Sessions/{session_id}/Command/SetVolume?Volume=50"
+
+# Correct format
+endpoint = f"/Sessions/{session_id}/Command"
+data = {"Name": "SetVolume", "Arguments": {"Volume": "50"}}  # Arguments as STRINGS
+```
+
+**Impact:** Volume control didn't work even though mute/unmute worked fine.
+
+**Lesson:** Emby general commands must be sent to `/Command` endpoint (not `/Command/{CommandName}`) with:
+- `Name` field containing the command name
+- `Arguments` as a dict with STRING values, not integers
+
+---
+
+### 3. NumberSelector Returns Float, Not Int
+
+**Problem:** Home Assistant's `NumberSelector` widget returns float values, but port numbers must be integers.
+
+```python
+# Wrong - port could be 8096.0
+self._port = user_input.get(CONF_PORT, DEFAULT_PORT)
+
+# Correct
+self._port = int(user_input.get(CONF_PORT, DEFAULT_PORT))
+```
+
+**Impact:** Potential type errors or malformed URLs with decimal port numbers.
+
+**Lesson:** Always explicitly convert NumberSelector values to the expected type.
+
+---
+
+### 4. Inconsistent Use of Constants
+
+**Problem:** Hardcoded endpoint paths in some methods instead of using defined constants.
+
+```python
+# Wrong - hardcoded
+endpoint = f"/Sessions/{session_id}/Playing"
+
+# Correct - using constant
+endpoint = f"{ENDPOINT_SESSIONS}/{session_id}/Playing"
+```
+
+**Impact:** When the `/emby` prefix was added to constants, hardcoded paths were missed, causing inconsistent behavior.
+
+**Lesson:** Always use constants consistently. When fixing issues, search for all occurrences of the affected strings.
+
+---
+
+### 5. Import Confusion Between Local and HA Constants
+
+**Problem:** Initially imported `CONF_HOST` and `CONF_PORT` from `homeassistant.const` in some files, while also defining them in local `const.py`.
+
+```python
+# Inconsistent imports
+from homeassistant.const import CONF_HOST, CONF_PORT  # in __init__.py
+from .const import CONF_HOST, CONF_PORT  # in config_flow.py
+```
+
+**Impact:** Potential confusion and maintenance issues, though values were identical.
+
+**Lesson:** Choose one source for constants and use it consistently across all files. For custom integrations, prefer local constants for full control.
+
+---
+
+## Best Practices Established
+
+1. **Test API endpoints with curl first** - Verify the exact request format before implementing in code
+2. **Add debug logging** - Include request URLs and response status codes for troubleshooting
+3. **Handle multiple API formats** - Some servers may respond differently; implement fallbacks when sensible
+4. **Type conversion** - Always explicitly convert UI input values to expected types
+5. **Consistent constant usage** - Define constants once and use them everywhere