docs: add narrative guides for public workflows (closes #92)

[Faerkeren]

Issue validity

Valid and actionable. Issue #92 correctly identifies a real gap: the docs site has only a quick-start home page and mkdocstrings-generated reference stubs, with no narrative guidance for the public workflows users actually need to navigate (lifecycle, listeners, reconnect, service routing, custom domains, per-domain usage).

One sub-claim in the issue is stale: the "currently broken custom-domain example" in docs/index.md was already repaired in PR #88 (docs: fix invalid custom-domain quick-start example), which also added a regression test (tests/test_plugins.py::test_docs_custom_domain_example_runs) that runs the snippet against an isolated registry. The example is functional; this PR only restructures it for clarity while keeping that regression test green.

Fix

Adds a new Guides section to the documentation, surfaced in mkdocs.yml nav:

Workflow guides

• guides/lifecycle.md — async context manager, state priming sequence, lazy entity creation, manual connect()/close(), errors during connect.
• guides/sync-wrapper.md — SyncHAClient threading model, construction, close() requirements, listeners on the sync wrapper, when not to use it.
• guides/listeners.md — both listener tiers, the three granular categories (state value / transition / attribute), why granular > raw, removal semantics, non-entity events via EventBus.
• guides/reconnect.md — what survives reconnect automatically, timing guarantees, in-flight call behavior, common patterns (asyncio.Event waits, UI degradation).
• guides/service-routing.md — clear "advanced use only" framing per the issue, explains prefer="ws"|"rest"|"auto", lists the three legitimate reasons to use raw services.call(), anti-patterns.
• guides/custom-domains.md — in-process registration with the register-before-construct ordering pitfall called out, listener decorators on custom entities, collection-level DomainAccessor subclasses, event routing, entry-point publishing, load_plugins=False opt-out.

Per-domain workflow guides (guides/domains/)

• light, switch, climate, cover, media_player, scene, timer, sensor — each covers reading state, common actions, granular listener decorators, and 2-3 typical patterns. All examples use intent-specific domain methods (e.g. light.set_brightness(200)), per the project's design philosophy.

Reference cleanup

• Expanded the three stub pages flagged by the issue (reference/core/events.md, reference/core/services.md, reference/core/plugins.md) with one-paragraph introductions that cross-link to the new guides above the mkdocstrings block.

Home page

• Reframed the prefer="ws"|"rest"|"auto" bullet as advanced usage and added a "Next steps" section pointing at the guides.
• Restructured the custom-domain example into two fenced code blocks (registration first, async usage second). The registration block remains executable for the existing docs-example regression test.

Tests / checks run

All green on Python 3.11:

$ python -m pytest tests/ --cov=haclient --cov-report=term-missing --cov-fail-under=95
329 passed in 53.13s
Required test coverage of 95% reached. Total coverage: 97.19%

$ ruff check src tests
All checks passed!

$ ruff format --check src tests
60 files already formatted

$ mypy src
Success: no issues found in 38 source files

$ python -m mkdocs build --strict
INFO    -  Documentation built in 4.88 seconds

mkdocs build --strict confirms every internal link in the new guides resolves and the expanded nav is well-formed.