Markdown Converter
Agent skill for markdown-converter
- **Developer Guide**: See `/development/README.md` for architecture and contribution guidelines
Sign in to like and favorite skills
/development/README.md for architecture and contribution guidelines/development/TESTING.md for test requirements and examples/development/HA_INTEGRATION_GUIDE.md for Home Assistant specific patterns (references upstream guides)/docs/ for user-facing guidesDo not create new documentation files without being explicitly asked.
Always reference upstream pywiim documentation (see "Reference Upstream Documentation" section below) instead of duplicating content.
NEVER create workarounds or fallbacks in the HA integration for missing pywiim functionality.
If pywiim is not providing something it should (like EQ capabilities, available presets, etc.):
❌ WRONG:
def _is_eq_supported(self) -> bool: # Check capabilities first if capabilities.get("supports_eq"): return True # Fallback: check if player has presets (WORKAROUND) if player.available_eq_presets: return True
✅ RIGHT:
def _is_eq_supported(self) -> bool: # pywiim MUST provide this via capabilities return capabilities.get("supports_eq", False)
If pywiim doesn't set
supports_eq correctly → FIX PYWIIM
ALWAYS reference upstream pywiim documentation guides instead of duplicating content.
CRITICAL: Before writing any code that uses pywiim, you MUST review the pywiim API and HA integration documentation.
Before writing or modifying code that uses pywiim:
/development/HA_INTEGRATION_GUIDE.md for Home Assistant integration patternsThis applies to:
player.* attributes or methodsclient.* methodsWhen working with pywiim integration patterns or API usage:
/development/HA_INTEGRATION_GUIDE.md for Home Assistant integration patternsWhen pywiim version is updated:
/development/HA_INTEGRATION_GUIDE.mdmanifest.json with the new minimum pywiim version requirementWhy:
eq-detection.md, not eq_detection.mdid field (avoid - id:)/custom_components/wiim//tests/ with proper fixtures/docs/[Device Name] message./scripts/check-before-push.sh or pytest --cov to verify everything works--no-verify unless explicitly debugging CI infrastructureCRITICAL: Codecov enforces 77.40% patch coverage (as of Dec 2025)
What is patch coverage?
What happens if patch coverage is too low?
**28.20% of diff hit (target 77.40%)**Common causes of low patch coverage:
pass, it needs a testHow to fix low patch coverage:
pytest --cov=custom_components/wiim --cov-report=term-missingExample: Join service fix (Dec 2025)
Golden Rule: If you write code, you MUST write tests. No exceptions.
CRITICAL: When pywiim library is updated, real-world tests must be run for affected functionality.
Why:
line_in vs line-in) can silently fail - device accepts command but doesn't workWhen to run real-world tests:
manifest.json or requirements.txtWhat to test:
scripts/test-automated.py with FULL_TESTS (or at minimum, test affected areas)Real-World Test Suite:
scripts/test-automated.pyCRITICAL_TESTS: Fast tests run before every release (device discovery, playback, volume, state sync)FULL_TESTS: Comprehensive tests including source selection, multiroom, EQ, etc.Practice:
Example:
line-in format) → Run test-automated.py with source_selection testCRITICAL: Do not create documentation files unless explicitly requested or needed for long-term reference.
Do NOT create "progress" or "summary" files
Only create documentation when:
Update existing files instead:
tests/README.md with test infodocs/TESTING-CONSOLIDATED.md with testing strategydocs/ARCHITECTURE.md with architecture changesdocs/DEVELOPMENT-RULES.md with new rulesUse Git for progress tracking:
pytest --cov)Documentation structure:
/docs/ - User and developer documentation (long-term reference only)/tests/README.md - Test quick reference only/development/ - Developer guidesCreate new file only if:
Update existing file if:
Examples:
TEST-SUITE-COMPLETE.md when tests/README.md existstests/README.md with new test informationCOVERAGE-PROGRESS.md for status updatespytest --cov to see coverage (no file needed)FINAL-SUMMARY.md for session summarySee
and docs/DOCUMENTATION-GUIDELINES.md
for detailed guidance.docs/DOCUMENTATION-BEST-PRACTICES.md
Always use pywiim's actual attribute names:
capabilities.get("supports_eq") (NOT "eq_supported")player.eq_presets (NOT "available_eq_presets")player.eq_presetawait player.set_eq_preset(name.lower())Device API = Source of Truth:
player.is_master, player.is_slave, player.is_solo (booleans)player.role ("master"/"slave"/"solo")await player.client.get_device_group_info()Group object = Player references for operations:
player.group.master - Player object reference to masterplayer.group.slaves - list[Player] for operationsplayer.group.all_players - list[Player] for operationsplayer_finder callback to be populated!How to check if device has slaves:
player.is_master (boolean, preferred)player.role == "master" (string alternative)len(player.group.all_players) > 1 (requires player_finder)Enable group operations:
player_finder callback when creating Playergroup.all_players❌
player.available_eq_presets - Does not exist
❌ capabilities.get("eq_supported") - Wrong key name
❌ player.group.slaves - Exists but not populated, use all_players instead
✅ player.eq_presets - Correct
✅ capabilities.get("supports_eq") - Correct
✅ player.group.all_players - Correct
ALWAYS test locally before pushing to CI.
The release workflow is designed to identify and solve issues locally, not push-and-see.
./scripts/check-before-push.sh (runs same checks as CI)
.github/workflows/tests.yaml exactly--no-verify unless explicitly debugging CI infrastructure./scripts/check-before-push.shALWAYS activate the venv first, then start Home Assistant:
# 1. Activate the Home Assistant virtual environment source /home/vscode/.local/ha-venv/bin/activate # 2. Start Home Assistant cd /workspaces/core hass -c /workspaces/core/config --open-ui
Or as a one-liner (for background execution):
cd /workspaces/core && source /home/vscode/.local/ha-venv/bin/activate && nohup hass -c /workspaces/core/config > /tmp/ha_startup.log 2>&1 &
Why this is critical:
/home/vscode/.local/ha-venv contains all required dependencies with correct versionsaiodns/pycares Python 3.13 compatibility issues)/workspaces/core/config contains symlinks to the wiim integration/workspaces/core/config/custom_components/wiim → /workspaces/wiim/custom_components/wiim~/.homeassistant - that config doesn't have the symlinkspython3 -m homeassistant - use the hass command with venv activated~ - the environment and symlinks are set up in the workspaceOptional but recommended:
# Run quick checks first (catches syntax/lint errors) cd /workspaces/wiim make pre-run
Other useful commands:
http://localhost:8123pkill -f "hass.*config"ps aux | grep -E "[h]ass.*config"curl -s -o /dev/null -w "%{http_code}" http://localhost:8123/api/ (should return 200 or 401)tail -f /tmp/ha_startup.logTo view terminal output when running in background:
/home/vscode/.cursor/projects/workspaces-core/terminals/[SHELL_ID].txttail -f /home/vscode/.cursor/projects/workspaces-core/terminals/[SHELL_ID].txtWhen to run real-world tests:
How to run real-world tests:
# 1. Ensure Home Assistant is running (see above) # Wait for HA to be ready: curl http://localhost:8123/api/ should return 200 or 401 # 2. Activate venv and run tests cd /workspaces/wiim source /home/vscode/.local/ha-venv/bin/activate # 3. Run full test suite (includes source selection) python scripts/test-automated.py --config scripts/test.config --mode full # Or run critical tests only (faster, excludes source selection) python scripts/test-automated.py --config scripts/test.config --mode critical
Test configuration:
scripts/test.config (contains HA URL and access token).gitignore for security (contains long-lived access token)echo "HA_URL=http://localhost:8123" > scripts/test.config echo "HA_TOKEN=your_long_lived_access_token" >> scripts/test.config
What the tests verify:
critical mode: Device discovery, playback controls, volume, state sync (fast, ~2 min)full mode: All critical tests + source selection, multiroom, EQ, presets, etc. (~5 min)Troubleshooting:
ps aux | grep hassscripts/test.config may be expired - create new tokenSee
for complete development setup instructions./development/README.md
If asked to remember something, update this file or the appropriate documentation immediately.