feat: Add docs site

.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+name: Documentation
+
+on:
+    push:
+        branches: [main]
+        paths:
+            - "site_docs/**"
+            - "zensical.toml"
+            - ".github/workflows/docs.yml"
+            - "README.md"
+            - "CHANGELOG.md"
+            - "LICENSE"
+    pull_request:
+        branches: [main]
+        paths:
+            - "site_docs/**"
+            - "zensical.toml"
+            - ".github/workflows/docs.yml"
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: "pages"
+    cancel-in-progress: false
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v5
+              with:
+                  fetch-depth: 0
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: 3.x
+
+            - name: Set up uv
+              uses: astral-sh/setup-uv@v5
+
+            - name: Install dependencies
+              run: uv pip install --system zensical
+
+            - name: Build documentation
+              run: zensical build --clean
+
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v4
+              with:
+                  path: ./site
+
+    deploy:
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        needs: build
+        runs-on: ubuntu-latest
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4

.gitignore

@@ -29,3 +29,6 @@ __pycache__/
 .vscode/
 *.swp
 *.swo
+
+# Zensical build output
+site/

feature_list.json

@@ -1,32 +1,37 @@
 {
-  "description": "RoboVac Feature List - Test cases organized by functional area",
-  "version": "1.0.0",
-  "updated": "2025-12-16",
-  "areas": [
-    {
-      "name": "vacuum_models",
-      "file": "features/vacuum_models.json",
-      "count": 12
-    },
-    {
-      "name": "core_functionality",
-      "file": "features/core_functionality.json",
-      "count": 5
-    },
-    {
-      "name": "testing",
-      "file": "features/testing.json",
-      "count": 5
+    "description": "RoboVac Feature List - Test cases organized by functional area",
+    "version": "1.0.0",
+    "updated": "2026-01-06",
+    "areas": [
+        {
+            "name": "vacuum_models",
+            "file": "features/vacuum_models.json",
+            "count": 12
+        },
+        {
+            "name": "core_functionality",
+            "file": "features/core_functionality.json",
+            "count": 5
+        },
+        {
+            "name": "testing",
+            "file": "features/testing.json",
+            "count": 5
+        },
+        {
+            "name": "documentation",
+            "file": "features/documentation.json",
+            "count": 5
+        }
+    ],
+    "summary": {
+        "total_features": 27,
+        "passing": 20,
+        "failing": 7,
+        "pass_rate": "74%",
+        "categories": {
+            "functional": 17,
+            "quality": 10
+        }
     }
-  ],
-  "summary": {
-    "total_features": 22,
-    "passing": 16,
-    "failing": 6,
-    "pass_rate": "73%",
-    "categories": {
-      "functional": 17,
-      "quality": 5
-    }
-  }
-}
+}

features/documentation.json

@@ -0,0 +1,62 @@
+[
+  {
+    "id": "DOC-001",
+    "category": "quality",
+    "area": "documentation",
+    "description": "Zensical documentation site is configured",
+    "steps": [
+      "Create zensical.toml configuration file",
+      "Configure site_name, docs_dir, and site_dir",
+      "Verify configuration is valid"
+    ],
+    "passes": true
+  },
+  {
+    "id": "DOC-002",
+    "category": "quality",
+    "area": "documentation",
+    "description": "Documentation index page exists",
+    "steps": [
+      "Create docs/index.md with project overview",
+      "Include installation instructions",
+      "Include quick start guide"
+    ],
+    "passes": true
+  },
+  {
+    "id": "DOC-003",
+    "category": "quality",
+    "area": "documentation",
+    "description": "GitHub Pages deployment workflow exists",
+    "steps": [
+      "Create .github/workflows/docs.yml",
+      "Configure GitHub Actions for Zensical build",
+      "Set up GitHub Pages deployment"
+    ],
+    "passes": true
+  },
+  {
+    "id": "DOC-004",
+    "category": "quality",
+    "area": "documentation",
+    "description": "Documentation builds successfully",
+    "steps": [
+      "Run zensical build --clean",
+      "Verify site directory is created",
+      "Check for build errors"
+    ],
+    "passes": false
+  },
+  {
+    "id": "DOC-005",
+    "category": "quality",
+    "area": "documentation",
+    "description": "Navigation structure is defined",
+    "steps": [
+      "Configure nav in zensical.toml",
+      "Verify all pages are accessible",
+      "Check navigation order"
+    ],
+    "passes": true
+  }
+]

site_docs/configuration.md

@@ -0,0 +1,37 @@
+# Configuration
+
+## Adding the Integration
+
+1. Go to **Settings** → **Devices & Services**
+2. Click **Add Integration**
+3. Search for "RoboVac"
+4. Follow the configuration wizard
+
+## Required Information
+
+You'll need the following information to configure your vacuum:
+
+- **Device ID**: Your vacuum's unique identifier
+- **Local Key**: The encryption key for local communication
+- **IP Address**: Your vacuum's local IP address
+
+## Finding Your Local Key
+
+The local key can be obtained using various methods:
+
+1. **Tuya IoT Platform**: Register as a developer and link your device
+2. **Third-party tools**: Use tools like `tuya-cli` to extract the key
+
+## Protocol Version
+
+Some vacuums require a specific protocol version:
+
+- **Protocol 3.3**: Most older models
+- **Protocol 3.4**: Newer models with enhanced security
+- **Protocol 3.5**: Latest models
+
+If you're unsure, start with 3.3 and adjust if needed.
+
+## Troubleshooting
+
+If you encounter issues, see the [Troubleshooting](troubleshooting.md) guide.

site_docs/index.md

@@ -0,0 +1,36 @@
+# RoboVac
+
+Welcome to the RoboVac documentation! RoboVac is a Home Assistant custom
+integration for Eufy RoboVac vacuum cleaners.
+
+## Features
+
+- **Local Control**: Control your vacuum without cloud dependency
+- **Multiple Models**: Support for 30+ Eufy RoboVac models
+- **Full Integration**: Start, stop, pause, return to base, and locate
+- **Status Monitoring**: Battery level, cleaning status, and error reporting
+
+## Quick Start
+
+1. Install via HACS or manually
+2. Add the integration in Home Assistant
+3. Configure your vacuum's local key and device ID
+4. Start cleaning!
+
+## Supported Models
+
+RoboVac supports a wide range of Eufy vacuum models including:
+
+- RoboVac G30 Series (T2250, T2251, T2252, T2253)
+- RoboVac L35 Hybrid (T2194)
+- RoboVac X8 Series (T2261, T2262)
+- And many more...
+
+See the full list in the [Configuration](configuration.md) section.
+
+## Getting Help
+
+- [Installation Guide](installation.md)
+- [Configuration](configuration.md)
+- [Troubleshooting](troubleshooting.md)
+- [GitHub Issues](https://github.com/damacus/robovac/issues)

site_docs/installation.md

@@ -0,0 +1,30 @@
+# Installation
+
+## Prerequisites
+
+- Home Assistant 2024.1.0 or later
+- A Eufy RoboVac with local network access
+- Your vacuum's local key and device ID
+
+## Installation via HACS (Recommended)
+
+1. Open HACS in Home Assistant
+2. Click on "Integrations"
+3. Click the three dots in the top right corner
+4. Select "Custom repositories"
+5. Add `https://github.com/damacus/robovac` as a custom repository
+6. Select "Integration" as the category
+7. Click "Add"
+8. Search for "RoboVac" and install
+
+## Manual Installation
+
+1. Download the latest release from GitHub
+2. Extract the `custom_components/robovac` folder
+3. Copy it to your Home Assistant `custom_components` directory
+4. Restart Home Assistant
+
+## Next Steps
+
+After installation, proceed to [Configuration](configuration.md) to set up
+your vacuum.

site_docs/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+## Common Issues
+
+### Vacuum Not Responding
+
+**Symptoms**: Commands are sent but the vacuum doesn't respond.
+
+**Solutions**:
+
+1. Verify the IP address is correct and reachable
+2. Check that the local key is correct
+3. Ensure the vacuum is on the same network as Home Assistant
+4. Try a different protocol version
+
+### Invalid Local Key
+
+**Symptoms**: Authentication errors in the logs.
+
+**Solutions**:
+
+1. Re-extract the local key from the Tuya platform
+2. Ensure no extra spaces or characters in the key
+3. Verify the device ID matches
+
+### Connection Timeout
+
+**Symptoms**: Timeout errors when trying to connect.
+
+**Solutions**:
+
+1. Check your network connectivity
+2. Verify the vacuum is powered on
+3. Ensure no firewall is blocking the connection
+4. Try restarting the vacuum
+
+### Wrong Protocol Version
+
+**Symptoms**: Decryption errors or garbled responses.
+
+**Solutions**:
+
+1. Try protocol version 3.4 instead of 3.3
+2. For newer models, try protocol 3.5
+3. Check the logs for specific error messages
+
+## Getting Help
+
+If you're still having issues:
+
+1. Check the [GitHub Issues](https://github.com/damacus/robovac/issues)
+2. Enable debug logging and review the logs
+3. Open a new issue with your logs and configuration

zensical.toml

@@ -0,0 +1,11 @@
+[project]
+site_name = "RoboVac Documentation"
+docs_dir = "site_docs"
+site_dir = "site"
+
+nav = [
+  "index.md",
+  "installation.md",
+  "configuration.md",
+  "troubleshooting.md"
+]