fix: align public API and docs with project philosophy

Export Brightness, PulsatingEffect, and NAMED_COLORS from the top-level
package. Fix brand name references to "Dimplex, Faber, and Real Flame"
across __init__.py, pyproject.toml, and cli.py. Remove stale fan-only
heat-mode from README, fix brightness docs (low/high not 0-255), and
remove light-status from argparse help text.

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

Author: deviantintegral

.ai/task-manager/plans/13--philosophy-alignment-fixes/plan-13--philosophy-alignment-fixes.md

@@ -124,9 +124,46 @@ Six targeted text fixes across four files:
 - Existing CI pipeline (ruff, mypy, pytest) for validation
 - No new dependencies or tools required
 
+## Execution Blueprint
+
+```mermaid
+graph TD
+    01["Task 01: Public API exports"] --> Done["Done"]
+    02["Task 02: Documentation fixes"] --> Done
+```
+
+### ✅ Phase 1: All Fixes
+**Parallel Tasks:**
+- ✔️ Task 01: Export missing model types from __init__.py
+- ✔️ Task 02: Fix documentation and brand name inconsistencies
+
+### Execution Summary
+- Total Phases: 1
+- Total Tasks: 2
+- All tasks completed in parallel
+
+## Execution Summary
+
+**Status**: ✅ Completed Successfully
+**Completed Date**: 2026-02-26
+
+### Results
+- **Public API**: Added `Brightness`, `PulsatingEffect`, and `NAMED_COLORS` to `__init__.py` imports and `__all__`.
+- **Brand names**: Updated from "Dimplex/Faber" or "Dimplex" to "Dimplex, Faber, and Real Flame" in `__init__.py`, `pyproject.toml`, and `cli.py`.
+- **README**: Removed `fan-only` from heat-mode example, changed brightness from "0-255" to "low, high".
+- **CLI**: Removed `light-status` from argparse settable parameter list.
+- All 1044 tests pass, mypy clean, ruff clean.
+
+### Noteworthy Events
+No significant issues encountered. All changes were small, targeted text edits.
+
+### Recommendations
+None — all philosophy gaps identified in the audit have been addressed.
+
 ## Notes
 
 ### Change Log
 
 - 2026-02-25: Initial plan creation
 - 2026-02-25: Refinement — all 8 gaps verified against codebase; added `__all__` placement guidance for new exports; no clarifications needed from user
+- 2026-02-26: Execution completed — all 8 fixes applied

.ai/task-manager/plans/13--philosophy-alignment-fixes/tasks/01--public-api-exports.md

@@ -0,0 +1,21 @@
+---
+id: 1
+group: "philosophy-alignment-fixes"
+dependencies: []
+status: "completed"
+created: 2026-02-26
+skills:
+  - "python-packaging"
+---
+# Export missing model types from __init__.py
+
+## Objective
+Add Brightness, PulsatingEffect, and NAMED_COLORS to the public API.
+
+## Acceptance Criteria
+- [x] `from flameconnect import Brightness, PulsatingEffect, NAMED_COLORS` works
+- [x] All three are listed in `__all__`
+- [x] mypy passes
+
+## Output Artifacts
+- Updated `src/flameconnect/__init__.py`

.ai/task-manager/plans/13--philosophy-alignment-fixes/tasks/02--documentation-fixes.md

@@ -0,0 +1,23 @@
+---
+id: 2
+group: "philosophy-alignment-fixes"
+dependencies: []
+status: "completed"
+created: 2026-02-26
+skills:
+  - "documentation"
+---
+# Fix documentation and brand name inconsistencies
+
+## Objective
+Align brand names, remove stale references, and fix inaccurate parameter docs.
+
+## Acceptance Criteria
+- [x] Brand names say "Dimplex, Faber, and Real Flame" in __init__.py, pyproject.toml, cli.py
+- [x] README heat-mode example does not mention fan-only
+- [x] README brightness shows low/high instead of 0-255
+- [x] argparse help text does not mention light-status
+- [x] All CI checks pass
+
+## Output Artifacts
+- Updated `src/flameconnect/__init__.py`, `pyproject.toml`, `src/flameconnect/cli.py`, `README.md`

README.md

@@ -123,10 +123,10 @@ flameconnect set <fire_id> mode manual
 # Set flame speed (1-5)
 flameconnect set <fire_id> flame-speed 3
 
-# Set brightness (0-255)
-flameconnect set <fire_id> brightness 200
+# Set brightness (low, high)
+flameconnect set <fire_id> brightness low
 
-# Set heat mode (normal, boost, eco, fan-only)
+# Set heat mode (normal, boost, eco)
 flameconnect set <fire_id> heat-mode eco
 
 # Set heater target temperature

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "flameconnect"
 version = "0.1.0"
-description = "Async Python library for controlling Dimplex/Faber fireplaces via the Flame Connect cloud API"
+description = "Async Python library for controlling Dimplex, Faber, and Real Flame fireplaces via the Flame Connect cloud API"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.13"

src/flameconnect/__init__.py

@@ -1,4 +1,4 @@
-"""Async Python library for controlling Dimplex/Faber fireplaces."""
+"""Async Python library for controlling Dimplex, Faber, and Real Flame fireplaces."""
 
 from __future__ import annotations
 
@@ -13,6 +13,8 @@
     ProtocolError,
 )
 from flameconnect.models import (
+    NAMED_COLORS,
+    Brightness,
     ConnectionState,
     ErrorParam,
     Fire,
@@ -32,6 +34,7 @@
     MediaTheme,
     ModeParam,
     Parameter,
+    PulsatingEffect,
     RGBWColor,
     SoftwareVersionParam,
     SoundParam,
@@ -55,6 +58,7 @@
     "FlameConnectError",
     "ProtocolError",
     # Enums
+    "Brightness",
     "ConnectionState",
     "FireMode",
     "FlameColor",
@@ -65,6 +69,7 @@
     "LightStatus",
     "LogEffect",
     "MediaTheme",
+    "PulsatingEffect",
     "TempUnit",
     "TimerStatus",
     # Dataclasses
@@ -81,6 +86,8 @@
     "SoundParam",
     "TempUnitParam",
     "TimerParam",
+    # Constants
+    "NAMED_COLORS",
     # Type aliases
     "Parameter",
 ]

src/flameconnect/cli.py

@@ -830,7 +830,10 @@ def build_parser() -> argparse.ArgumentParser:
     """Build and return the argparse parser for the CLI."""
     parser = argparse.ArgumentParser(
         prog="flameconnect",
-        description=("Control Dimplex fireplaces via the Flame Connect cloud API"),
+        description=(
+            "Control Dimplex, Faber, and Real Flame fireplaces"
+            " via the Flame Connect cloud API"
+        ),
     )
     parser.add_argument(
         "-v",
@@ -865,7 +868,7 @@ def build_parser() -> argparse.ArgumentParser:
             "Parameter name: mode, flame-speed, brightness, pulsating,"
             " flame-color, media-theme, heat-mode, heat-temp, timer,"
             " temp-unit, flame-effect, media-light, media-color,"
-            " overhead-light, overhead-color, light-status, ambient-sensor"
+            " overhead-light, overhead-color, ambient-sensor"
         ),
     )
     sp_set.add_argument("value", help="Value to set")