docs: update documentation structure for Docusaurus sites

Update all references to reflect two separate Docusaurus instances
(user + developer) with proper file paths and navigation management.

Changes:
- AGENTS.md: Document Docusaurus structure and file organization
- CONTRIBUTING.md: Add Docusaurus workflow guidelines
- docs/developer/docs/period-calculation-theory.md: Fix cross-reference
- docs/developer/sidebars.ts: Add recorder-optimization to navigation

Documentation organized as:
- docs/user/docs/*.md (user guides, via sidebars.ts)
- docs/developer/docs/*.md (developer guides, via sidebars.ts)
- AGENTS.md (AI patterns, conventions)

Impact: AI and contributors know where to place new documentation.

AGENTS.md

@@ -17,14 +17,18 @@ _Note: When proposing significant updates to this file, update the metadata abov
 
 When working with the codebase, Copilot MUST actively maintain consistency between this documentation and the actual code:
 
-**Scope:** "This documentation" and "this file" refer specifically to `AGENTS.md` in the repository root. This does NOT include user-facing documentation like `README.md`, `/docs/user/`, or comments in code. Those serve different purposes and are maintained separately.
+**Scope:** "This documentation" and "this file" refer specifically to `AGENTS.md` in the repository root. This does NOT include user-facing documentation like `README.md`, Docusaurus sites, or comments in code. Those serve different purposes and are maintained separately.
 
 **Documentation Organization:**
 
 -   **This file** (`AGENTS.md`): AI/Developer long-term memory, patterns, conventions
--   **`docs/user/`**: End-user guides (installation, configuration, usage examples)
--   **`docs/development/`**: Contributor guides (setup, architecture, release management)
--   **`README.md`**: Project overview with links to detailed documentation
+-   **`docs/user/`**: Docusaurus site for end-users (installation, configuration, usage examples)
+    -   Markdown files in `docs/user/docs/*.md`
+    -   Navigation managed via `docs/user/sidebars.ts`
+-   **`docs/developer/`**: Docusaurus site for contributors (architecture, development guides)
+    -   Markdown files in `docs/developer/docs/*.md`
+    -   Navigation managed via `docs/developer/sidebars.ts`
+-   **`README.md`**: Project overview with links to documentation sites
 
 **Automatic Inconsistency Detection:**
 
@@ -737,9 +741,9 @@ When debugging period calculation issues:
 4. Check relaxation warnings: INFO at 25%, WARNING at 30% indicate suboptimal config
 
 **See:**
-- **Theory documentation**: `docs/development/period-calculation-theory.md` (comprehensive mathematical analysis, conflict conditions, configuration pitfalls)
+- **Theory documentation**: `docs/developer/docs/period-calculation-theory.md` (comprehensive mathematical analysis, conflict conditions, configuration pitfalls)
 - **Implementation**: `coordinator/period_handlers/` package (core.py, relaxation.py, level_filtering.py, period_building.py)
-- **User guide**: `docs/user/period-calculation.md` (simplified user-facing explanations)
+- **User guide**: `docs/user/docs/period-calculation.md` (simplified user-facing explanations)
 
 ## Development Environment Setup
 
@@ -2067,7 +2071,7 @@ Public entry points → direct helpers (call order) → pure utilities. Prefix p
 
 **Documentation language:**
 
--   **CRITICAL**: All user-facing documentation (`README.md`, `/docs/user/`, `/docs/development/`) MUST be written in **English**
+-   **CRITICAL**: All user-facing documentation (`README.md`, `docs/user/docs/`, `docs/developer/docs/`) MUST be written in **English**
 -   **Code comments**: Always use English for code comments and docstrings
 -   **UI translations**: Multi-language support exists in `/translations/` and `/custom_translations/` (de, en, nb, nl, sv) for UI strings only
 -   **Why English-only docs**: Ensures maintainability, accessibility to global community, and consistency with Home Assistant ecosystem
@@ -2105,7 +2109,7 @@ Public entry points → direct helpers (call order) → pure utilities. Prefix p
 
 **User Documentation Quality:**
 
-When writing or updating user-facing documentation (`docs/user/`), follow these principles learned from real user feedback:
+When writing or updating user-facing documentation (`docs/user/docs/` or `docs/developer/docs/`), follow these principles learned from real user feedback:
 
 -   **Clarity over completeness**: Users want to understand concepts, not read technical specifications
     -   ✅ Good: "Relaxation automatically loosens filters until enough periods are found"
@@ -2846,3 +2850,32 @@ Only after consulting the official HA docs did we discover the correct pattern:
 -   Translations: `sensor/definitions.py` (translation_key usage)
 -   Test fixtures: `tests/conftest.py`
 -   Time handling: Any file importing `dt_util`
+
+## Recorder History Optimization
+
+**CRITICAL: Always exclude non-essential attributes from Recorder to prevent database bloat.**
+
+**Implementation:**
+- Use `_unrecorded_attributes = frozenset({...})` as **class attribute** in entity classes
+- See `sensor/core.py` and `binary_sensor/core.py` for current implementation
+
+**What to exclude:**
+1. **Descriptions/help text** - `description`, `usage_tips` (static, large)
+2. **Large nested structures** - `periods`, `data`, `*_attributes` dicts (>1KB)
+3. **Frequently changing diagnostics** - `icon_color`, `cache_age`, status strings
+4. **Static/rarely changing config** - `currency`, `resolution`, `*_id` mappings
+5. **Temporary/time-bound data** - `next_api_poll`, `last_*` timestamps
+6. **Redundant/derived data** - `price_spread`, `diff_%` (calculable from other attrs)
+
+**What to keep:**
+- `timestamp` (always), all price values, `cache_age_minutes`, `updates_today`
+- Period timing (`start`, `end`, `duration_minutes`), price statistics
+- Boolean status flags, `relaxation_active`
+
+**When adding new attributes:**
+- Will this be useful in history 1 week from now? No → Exclude
+- Can this be calculated from other attributes? Yes → Exclude
+- Is this >100 bytes and not essential? Yes → Exclude
+
+**See:** `docs/developer/docs/recorder-optimization.md` for detailed categories and impact analysis
+

CONTRIBUTING.md

@@ -122,13 +122,23 @@ Always run before committing:
 - Enrich price data before exposing to entities
 - Follow Home Assistant entity naming conventions
 
-See [Coding Guidelines](docs/development/coding-guidelines.md) for complete details.
+See [Coding Guidelines](docs/developer/docs/coding-guidelines.md) for complete details.
 
 ## Documentation
 
-- **User guides**: Place in `docs/user/` (installation, configuration, usage)
-- **Developer guides**: Place in `docs/development/` (architecture, patterns)
-- **Update translations**: When changing `translations/en.json`, update ALL language files
+Documentation is organized in two Docusaurus sites:
+
+- **User docs** (`docs/user/`): Installation, configuration, usage guides
+  - Markdown files in `docs/user/docs/*.md`
+  - Navigation via `docs/user/sidebars.ts`
+- **Developer docs** (`docs/developer/`): Architecture, patterns, contribution guides
+  - Markdown files in `docs/developer/docs/*.md`
+  - Navigation via `docs/developer/sidebars.ts`
+
+**When adding new documentation:**
+1. Place file in appropriate `docs/*/docs/` directory
+2. Add to corresponding `sidebars.ts` for navigation
+3. Update translations when changing `translations/en.json` (update ALL language files)
 
 ## Reporting Bugs
 

docs/developer/docs/period-calculation-theory.md

@@ -1095,7 +1095,7 @@ Low volatility (< 15%) means classification changes are less economically signif
 **Status:** Per-day evaluation is intentional design prioritizing mathematical correctness.
 
 **See Also:**
-- User documentation: `docs/user/period-calculation.md` → "Midnight Price Classification Changes"
+- User documentation: `docs/user/docs/period-calculation.md` → "Midnight Price Classification Changes"
 - Implementation: `coordinator/period_handlers/period_building.py` (line ~126: `ref_date = date_key`)
 - Attributes: `coordinator/period_handlers/period_statistics.py` (day volatility calculation)