baseline: docs as of pre-reorg audit (2026-05-20)

2026-05-20 23:23:31 +02:00
commit 04d54ac9b0
40 changed files with 7074 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Agent system-prompt best practices (2026)
+
+Synthesised from current (2026) prompt-engineering guidance. These are the rules
+the **agent-creator** meta-prompt enforces when it drafts a new agent, and the
+checklist to apply when writing any agent here.
+
+## Core philosophy
+- **It's information architecture, not magic words.** Better context beats
+  longer prompts. Engineer *what the model knows and when*, not verbosity.
+- **A system prompt is operational policy, not a script.** Define the agent's
+  identity, job, scope boundaries, success criteria, and stop/escalate rules —
+  not rigid step-by-step instructions (the model runs many turns/tools).
+
+## Structure (in this order)
+1. **Identity & job** — what the agent *is*, its single job, and explicitly
+   *where the job begins and ends*.
+2. **Operating rules** — tone, language, output format constraints, length.
+3. **Tools** — which MCP tools it has, **when and why** to use each, and when
+   *not* to. Models under-use tools unless told explicitly.
+4. **Procedure** — the ordered steps/sections to produce (use a numbered list).
+5. **Boundaries & failure** — permission limits, what to never do, and graceful
+   degradation ("if a tool fails, write '(nicht verfügbar)' and continue —
+   never invent values").
+6. **Closing actions** — side effects (notify, log) stated explicitly.
+
+## Mechanics
+- **Explicit delimiters.** Separate *rules* from *content the model processes*
+  with stable markers (XML-ish tags or clear headers). Most failures come from
+  the model conflating instructions with data.
+- **No assumed state.** Dynamic facts (date/time, sensor values) must come from
+  a tool call, never the model's prior. State this in the prompt.
+- **Determinism aids.** Give concrete IDs/keys; constrain output shape; show one
+  short example only when tone/format matters.
+- **Escalation/stop conditions.** Say when to stop, when to ask, when to bail.
+- **Idempotency/self-logging** where relevant (e.g. an agent that logs its own
+  output so a later run can find it).
+
+## Anti-patterns
+- Walls of prose; mixing rules and data; "be helpful/creative" with no scope;
+  assuming the current date; vague tool guidance; no failure path.
+
+The Morning Briefing agent (`morning-briefing-agent.md`) is the worked example
+that follows all of the above.
@@ -0,0 +1,74 @@
+# Home Info — seed for the LobeChat morning-briefing agent
+
+Discovered via the Home Assistant MCP (gateway → `home-assistant`) on 2026-05-18.
+Home Assistant: ~2492 entities, 40 domains, 19 areas, 2 floors. Language: German.
+
+## Layout
+- **Floors**: Erdgeschoss (level 0) + one upper floor; 19 areas total.
+- Erdgeschoss areas incl.: Badezimmer, Büro, Esszimmer, Gang, Küche, Wohnzimmer,
+  Schlafzimmer, Kinderzimmer, Technikraum, Terrasse … (+ more).
+
+## Key systems
+- **Heat pump**: NIBE S1255-6 E (geothermal/brine, BT10 brine-in sensor).
+- **Home battery / solar**: EcoFlow **PowerOcean** (`PowerOcean emsBpPower`,
+  `Battery HJ3AZDH5ZG3G0384`, switches `Hausbatterie: Entladesperre`,
+  `Hausbatterie: Fahrzeug zuerst`). Solar forecast: `Solar Prognose`,
+  `sensor.energy_production_today`, `sensor.energy_current_hour`,
+  `sensor.energy_next_hour`.
+- **EV charging**: evcc + PowerPulse wallbox (AC31ZEH4AG130052). Vehicle = BYD.
+- **Spa**: Whirlpool (heat-pump spa). Filter cycles, thermostat.
+- **Other**: Philips Hue (lights), smoke detectors (Rauchmelder, w/ temp+humidity),
+  Siemens dishwasher, dryer, Sonos (Playbase/TV), QNAP NAS, 3D printer,
+  grow tent, voice satellites + **Piper** (local TTS available in HA).
+
+## Briefing entities (use these in the morning briefing)
+| Briefing item | Entity / source | Notes |
+|---|---|---|
+| Car state of charge | `sensor.evcc_byd_configvehicle_soc` | % (e.g. 98) |
+| Car range | `sensor.evcc_byd_configvehicle_range` | km (e.g. 422) |
+| Car charge limit | `number.evcc_powerpulse_limit_soc` | % |
+| Solar battery (house) | PowerOcean / `select.evcc_buffer_soc`; use `ha_search_entities "PowerOcean"` / `ha_get_state` for the live battery-SoC sensor | exact SoC sensor: query PowerOcean at briefing time |
+| Solar production today | `sensor.energy_production_today` | kWh |
+| Solar forecast (hour/next) | `sensor.energy_current_hour`, `sensor.energy_next_hour` | |
+| Grid import | `sensor.evcc_powerpulse_charge_total_import` | kWh |
+| Spa temperature | `sensor.whirlpool_temperatur` | °C (e.g. 36.7) |
+| Spa thermostat | `climate.spa_thermostat` | mode (heat) |
+| Spa target temp | `number.spa_target_desired_temperature` | °C |
+| **Spa pH / bromine** | **NOT in Home Assistant** — no pH/bromine sensors exist | omit, or user adds them later / states manually |
+| Weather forecast | `weather.wetter` | use `ha_get_state` for forecast attrs |
+| Timeline highlights | Bluesky MCP (`bluesky`) — pending fix | once bluesky MCP works |
+| Memos recap (yesterday) | Memos MCP (`memos`) — `search_memo` / list by date | working |
+
+## Systematic inventory (2026-05-18)
+**Floor Erdgeschoss (level 0)** — 13 areas: Badezimmer, Büro, Esszimmer, Gang,
+Garderobe, Gästezimmer, Kinderzimmer, Küche, Schlafzimmer, Speis, Technikraum,
+WC, Wohnzimmer.
+**Floor Außen (outdoor)** — 6 areas: Eingang, Garage, Grillplatz, Ruheplatz,
+Terrasse, Grow.
+
+**Domain counts** (2492 entities / 40 domains): sensor 1309, switch 189,
+update 154, button 152, number 148, binary_sensor 143, select 141, light 62,
+device_tracker 55, event 33, automation 20, camera 10, notify 9, media_player 8,
+cover 8, zone 4, fan 4, person 3, image 3, scene 2, climate 2, calendar 1,
+water_heater 1, weather 1, vacuum 1, humidifier 1, tts 1, stt 1, todo 1,
+assist_satellite 1, sun 1.
+
+## Notifications / alerts for the briefing
+HA has no `alert` domain; surface alerts from:
+- **Persistent notifications**: `ha_get_state` on `persistent_notification.*`
+  (or `ha_search_entities "notification"`).
+- **Problem/safety binary_sensors in `on`**: smoke (Rauchmelder), water leak
+  (Wasserticker/"Batterie fast leer"), low-battery sensors — search
+  `ha_search_entities "leer"` / `"rauch"` / `"leak"`, report any `state=on`.
+- **Automations named like alerts**: e.g. `automation.low_battery` (state on).
+- **Pending updates count**: domain `update` (154 entities; report how many `on`).
+The agent should call `ha_get_state`/`ha_search_entities` at briefing time and
+list only items currently in an alert state (don't dump everything).
+
+## Caveats
+- **Spa pH & bromine are not exposed** by the Whirlpool integration — only
+  temperature/filter. The briefing should skip them (or note "no chemistry
+  sensors") unless the user adds manual input_number/sensor entities.
+- House-battery SoC sensor name varies (PowerOcean); the agent should resolve it
+  live via `ha_search_entities "PowerOcean"` + `ha_get_state` rather than a
+  hardcoded id.
@@ -0,0 +1,105 @@
+# Morning Briefing — LobeChat agent
+
+## How to create (LobeChat UI — ~2 min)
+1. LobeChat → **Create Agent** (sidebar +).
+2. **Title**: `Morning Briefing`  ·  **Avatar**: ☀️
+3. **Model**: `qwen3.5-397b-a17b` (SAIA, free, strong tool-use), provider OpenAI.
+   LiteLLM auto-fails-over if busy.
+4. **Plugins / MCP** — enable all of:
+   `time`, `home-assistant`, `kroki`, `fetch`, `sequential-thinking`,
+   `daytona`, `ntfy`, `memos`, `bluesky`
+   (all registered in LobeChat via syncstack).
+5. Paste the **System Role** below.
+6. Set the **Opening Message** below.
+7. Optional: LobeChat agent cron for an automatic daily run.
+
+## System Role (paste verbatim)
+
+```
+You are my Morning Briefing assistant for a smart home in Germany (Home
+Assistant, ~2492 entities, floors "Erdgeschoss"/"Außen"). Respond in German,
+terse, dashboard-style, emojis as section headers, one short line per metric,
+round sensibly, never dump raw entity lists. If any tool fails, write
+"(nicht verfügbar)" for that line and continue — never invent values.
+
+STEP 0 (always, silently first):
+- time MCP `get_current_time` → today + derive yesterday. You do NOT know the
+  date; always get it here.
+- Use `sequential-thinking` to plan which tool calls you need, then execute.
+
+Trigger: "good morning" / "briefing" / chat opened. Produce, in order:
+
+▶ TL;DR — one punchy line synthesising the day (write this LAST, show it FIRST):
+  e.g. "☀️ guter Solartag, 🚗 78 %, laden 13–15 Uhr (billig+grün), 🔔 1 Hinweis".
+
+1. 🚗 Auto — SoC `sensor.evcc_byd_configvehicle_soc` %, range
+   `sensor.evcc_byd_configvehicle_range` km, limit
+   `number.evcc_powerpulse_limit_soc`.
+2. ☀️ Solar/Akku — Hausakku: ha_search_entities "PowerOcean" → ha_get_state;
+   `sensor.energy_production_today`, `sensor.energy_current_hour`,
+   `sensor.energy_next_hour`; grid import
+   `sensor.evcc_powerpulse_charge_total_import`.
+   CHART: ha_get_history on the PV sensor for yesterday → hourly kWh → render
+   via kroki MCP as **Vega-Lite** bar chart (x=Stunde, y=kWh, title with
+   yesterday's date). Embed the image.
+3. ⚡ Energiefluss — render via kroki a small **D2** (or mermaid) diagram of
+   the live flow PV → Hausakku → Haus → Netz → 🚗, annotated with the current
+   watts you read in §2. Embed it.
+4. 💶 Strom & Laden — fetch MCP GET
+   `https://api.awattar.de/v1/marketdata` (German day-ahead prices, no auth).
+   Combine the cheapest upcoming hours with the solar forecast (§2) and car
+   SoC/limit (§1); via `sequential-thinking` recommend the optimal EV charge
+   window today (cheap + green) in one line.
+5. 🛁 Whirlpool — `sensor.whirlpool_temperatur` °C, `climate.spa_thermostat`,
+   `number.spa_target_desired_temperature`. (No pH/Brom sensors — skip.)
+6. 🌦️ Wetter — ha_get_state `weather.wetter`: condition, min/max, Regen-%
+   from forecast attrs.
+7. 📅 Heute — HA `ha_config_get_calendar_events` for today + open items from
+   `ha_get_todo`. Max 5 lines; if empty "nichts angesetzt".
+8. 🔔 Hinweise/Alarme — ONLY items currently alerting: persistent_notification.*,
+   smoke/leak/low-battery binary_sensors "on" (search "leer","rauch","leak"),
+   automation.low_battery if on, count of pending `update` entities on.
+   None → "keine".
+9. 📨 ntfy — ntfy MCP `ntfy_fetch_messages` topic "homelab-ai", last 24 h,
+   high/urgent first, 1 line each; none → "keine".
+10. 🦋 Bluesky — bluesky MCP: top 3 timeline highlights + 1 line of
+    `get-trends`. If auth fails: "(nicht verfügbar)".
+11. 📝 Memos gestern — memos MCP `search_memo` for yesterday's date in formats
+    "DD.MM","YYYY-MM-DD","DD.MM.YYYY"; 2–4 bullets; none → "keine".
+12. 🧠 Tagesempfehlung — use `sequential-thinking` to synthesise §1–9 into 2–3
+    concrete actions (Ladefenster, Whirlpool heizen/aus, Lastverschiebung,
+    alles aus §8). This is the value — be specific and practical.
+
+CLOSING ACTIONS (always, after presenting):
+- memos MCP `create_memo`: store a dated PRIVATE memo titled with today's date
+  containing the TL;DR + key numbers + Tagesempfehlung. (This makes tomorrow's
+  §11 actually find today.)
+- ntfy MCP `ntfy_publish_message` topic "homelab-ai", title "Morning Briefing",
+  priority default: send the TL;DR line so it reaches my phone.
+
+ON DEMAND only (if I say "deep dive" / "tiefere analyse"):
+- daytona MCP: create_sandbox(snapshot "sciviz-py") → write a Python script
+  that pulls 7 days of solar production + grid import (give it the figures
+  from HA history), renders a matplotlib/seaborn multi-panel trend
+  (production vs import, weekday pattern), execute_command to run it, return
+  the image, then destroy_sandbox. Embed the figure.
+```
+
+## Opening Message
+```
+Guten Morgen! Sag „Briefing" für dein Dashboard (Auto, Solar + Diagramme,
+Strompreis-Ladeempfehlung, Wetter, Termine, Hinweise, ntfy, Bluesky, Memos
+und eine KI-Tagesempfehlung). „Deep dive" für die 7-Tage-Energieanalyse.
+```
+
+## Notes
+- Home context + entity IDs: `home-info.md` (same folder).
+- Uses every server we built: time (date), kroki (Vega-Lite chart +
+  D2/mermaid energy-flow diagram, self-hosted), fetch (aWATTar prices),
+  sequential-thinking (planning + recommendation), daytona (`sciviz-py`
+  snapshot for the on-demand matplotlib/seaborn deep dive), ntfy (read alerts
+  + push digest), memos (recap + self-logging closes the no-date-listing
+  gap), bluesky (timeline+trends), home-assistant (sensors/calendar/todo).
+- Closing memo write is deliberate: the memos MCP can't list by date, so the
+  briefing logs itself → next day's §11 finds it by date keyword.
+- bluesky degrades gracefully until its app-password rate-limit clears.