@cernion/openclaw-energy-tools-sidecar 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the Cernion Energy Tools Sidecar for OpenClaw are documented here.
 
+## 0.1.2 - 2026-06-30
+
+- Repositions the package and README around discoverable energy use cases:
+  MaStR assets, grid context, Redispatch, ZNP, §14a/§14d, Knowledge RAG,
+  process intake, and read-only operational APIs.
+- Adds package keywords and a Sidecar positioning note for ClawHub/npm
+  discoverability and follow-up documentation work.
+
 ## 0.1.1 - 2026-06-25
 
 - Adds required ClawHub code-plugin metadata:

package/README.md

@@ -1,17 +1,100 @@
 # Cernion Energy Tools Sidecar for OpenClaw
 
-Dedicated OpenClaw tool plugin for Cernion Energy Tools.
-
-Cernion Energy Tools is a Swiss Army Knife for energy questions: it combines
-asset inventories, MaStR evidence, grid context, regulatory/procedural
-knowledge, process intake, and read-only operational APIs into one fachliche
-evidence layer. The Sidecar makes that layer available inside OpenClaw so an
-energy-domain assistant can answer with Cernion-backed facts instead of generic
-model memory.
-
-The plugin is the ideal fachliche companion for people working in the energy
-sector: grid planning, asset-MDM, Redispatch, Zielnetzplanung, §14a/§14d,
-market communication, storage/PV/load siting, and operational readiness checks.
+Cernion-backed energy evidence tools for OpenClaw agents: MaStR assets, grid
+context, Redispatch, Zielnetzplanung (ZNP), §14a/§14d EnWG, regulatory
+Knowledge RAG, process intake, and read-only operational APIs.
+
+Most users will not search for a "Cernion Sidecar" directly. They usually have
+an energy-domain question and need an agent that can work with evidence instead
+of generic model memory. This plugin is the bridge: OpenClaw provides the agent
+runtime, conversation, tool orchestration, and final answer synthesis; Cernion
+Energy Tools provides the fachliche energy layer, policies, evidence semantics,
+and read-only execution plans.
+
+Use it when an OpenClaw assistant should answer questions such as:
+
+- "Welche PV-Anlagen, Speicher oder Lasten gibt es in dieser Gemeinde?"
+- "Welche Redispatch-, §14a-, §14d- oder ZNP-Pruefschritte sind relevant?"
+- "Welche Netzbereiche wirken fuer PV, BESS, HPC-Laden oder Waermepumpen kritisch?"
+- "Welche MaStR-, OSM-, Marktpartner-, Last-, CO2- oder Betriebsdaten stuetzen diese Aussage?"
+- "Welche Cernion-Faehigkeit oder API sollte fuer diese Energiefrage genutzt werden?"
+- "Kann ein Prozess vorbereitet werden, ohne ihn schon auszufuehren?"
+
+## Who This Is For
+
+- Stadtwerke, Verteilnetzbetreiber, Energieberater, Asset-MDM-Teams, grid
+  planning teams, Redispatch teams, market-communication teams, and software
+  teams building energy-domain assistants.
+- OpenClaw users who want a local/private assistant to use Cernion data and
+  policies without copying tokens, business logic, or raw operational context
+  into prompts.
+- Cernion users who want a conversational agent surface without moving Cernion's
+  capability routing, policy gates, or source-of-truth semantics into OpenClaw.
+
+## How OpenClaw And Cernion Work Together
+
+| Layer | Responsibility |
+| --- | --- |
+| OpenClaw | Agent runtime, user conversation, memory/workspace instructions, model choice, tool orchestration, answer synthesis, and human-readable explanation. |
+| This Sidecar | Host-side plugin configuration, secret loading, Cernion tool discovery, request validation, token scrubbing, read-only REST plan proxying, and boundary enforcement. |
+| Cernion Energy Tools | Energy-domain capabilities, MaStR and grid evidence, Knowledge RAG, Evidence Router, process-intake policy, capability manifests, and read-only operational APIs. |
+
+This split is the product value: OpenClaw can become an energy assistant without
+learning Cernion internals, while Cernion remains the authority for policies,
+evidence semantics, and which operations are safe.
+
+## Example Prompts
+
+```text
+Mich wuerde interessieren, ob die Gemeinde Meckesheim bereits so viel Erzeugungskapazitaet hat, dass sie sich unter idealen Bedingungen selbst versorgen koennte. Wenn nicht, wie viel Solar muesste zugebaut werden?
+```
+
+```text
+Welche Pflichten ergeben sich aus §14a EnWG fuer einen Verteilnetzbetreiber, und welche Cernion-Evidenz sollte ich fuer einen konkreten Fall pruefen?
+```
+
+```text
+Ich plane 20 MWp PV, 10 MW / 20 MWh Speicher, 30 HPC-Ladepunkte, 800 Waermepumpen und 1.500 Wallboxen in Sinsheim. Welche Spannungsebenen und Netzbereiche koennten kritisch werden, und welche Evidenz fehlt?
+```
+
+```text
+Welche Cernion-Capability passt zu einer Redispatch-Asset-Register-Pruefung, und kann OpenClaw den passenden read-only REST-Plan ausfuehren?
+```
+
+## Capabilities At A Glance
+
+- Regulatory and procedural knowledge: EnWG, §14a/§14d, BNetzA guidance,
+  internal procedures, roles, obligations, and job-help context through Cernion
+  Knowledge RAG.
+- Asset and market evidence: MaStR-backed PV, storage, load, market-partner,
+  and operational evidence through read-only Cernion APIs.
+- Grid context: OSM-visible substations, transformers, lines, voltage-level
+  hints, and topology metrics for ZNP, Netzanschluss, PV/BESS/HPC siting, fNAV,
+  and planning hypotheses.
+- Evidence routing: Cernion recommends the safe read-only endpoint and result
+  semantics; OpenClaw executes through this Sidecar and synthesizes the answer.
+- Capability resolution: OpenClaw can resolve Cernion capability and operation
+  manifests instead of hard-coding domain routing.
+- Process intake: OpenClaw can prepare a pending process receipt through a
+  separate token boundary without executing or resolving the process.
+
+## Install From ClawHub
+
+```bash
+openclaw plugins install clawhub:@cernion/openclaw-energy-tools-sidecar
+```
+
+Then configure the Cernion base URL and a read-only token:
+
+```bash
+export CERNION_BASE_URL="https://cernion.example"
+export CERNION_READONLY_TOKEN_FILE="$HOME/.config/cernion/readonly-token"
+```
+
+See [docker/README.md](docker/README.md) for a browser-based demo container
+that starts OpenClaw with this plugin preinstalled.
+
+## Cernion Sidecar Contract
 
 The plugin consumes the Cernion Sidecar contract implemented by Cernion Energy Tools:
 

package/dist/index.js

@@ -807,7 +807,7 @@ function scrubSecretValues(value, token) {
 export default defineToolPlugin({
     id: "cernion-energy-tools-sidecar",
     name: "Cernion Energy Tools Sidecar",
-    description: "Expose Cernion Energy Tools to OpenClaw through separated evidence, knowledge, process-intake, and read-only REST boundaries.",
+    description: "Give OpenClaw agents Cernion-backed energy evidence for MaStR assets, grid context, Redispatch, ZNP, §14a/§14d, Knowledge RAG, process intake, and read-only operational APIs.",
     configSchema,
     tools: (tool) => [
         tool({

package/docs/POSITIONING.md

@@ -0,0 +1,86 @@
+# Positioning OpenClaw + Cernion Energy Tools Sidecar
+
+This document captures how to explain the plugin to users who do not yet know
+that a Cernion/OpenClaw integration exists.
+
+## Core Message
+
+OpenClaw is the agent runtime. Cernion Energy Tools is the energy-domain
+evidence and policy layer. The Sidecar connects both so an assistant can answer
+energy questions with Cernion-backed evidence instead of generic model memory.
+
+Short form:
+
+```text
+Give OpenClaw agents Cernion-backed energy evidence: MaStR assets, grid context,
+Redispatch, Zielnetzplanung, §14a/§14d, Knowledge RAG, process intake, and
+read-only operational APIs.
+```
+
+## Discovery Problem
+
+The expected users usually search for their job problem, not for a "sidecar".
+They may look for:
+
+- OpenClaw energy assistant
+- MaStR assistant or MaStR evidence
+- Redispatch agent
+- Zielnetzplanung or ZNP assistant
+- §14a EnWG or §14d EnWG workflow
+- Netzanschluss, PV, BESS, HPC charging, or heat-pump grid context
+- Cernion Knowledge RAG
+- Verteilnetzbetreiber AI assistant
+- Stadtwerke agent
+- energy evidence router
+
+Documentation and marketplace copy should put those words near the top.
+
+## Audience
+
+- Stadtwerke and Verteilnetzbetreiber teams that need grounded answers across
+  MaStR, grid planning, Redispatch, regulatory duties, and operational status.
+- Energy consultants and software teams that need an agent interface over
+  Cernion capabilities without embedding Cernion tokens or business logic in
+  prompts.
+- OpenClaw users who want a local/private energy-domain assistant with tool
+  discipline, not a generic chatbot.
+
+## OpenClaw/Cernion Split
+
+| Part | What to say |
+| --- | --- |
+| OpenClaw | Conversation, model selection, workspace instructions, tool orchestration, memory, and final answer synthesis. |
+| Sidecar | Plugin configuration, token loading, request validation, token scrubbing, safe proxying, and tool surface inside OpenClaw. |
+| Cernion Energy Tools | Energy capabilities, policies, Knowledge RAG, Evidence Router, MaStR/grid/market data semantics, and read-only operational APIs. |
+
+The product promise is not "install another API wrapper". The promise is:
+OpenClaw can become a fachlich disciplined energy assistant while Cernion stays
+the source of truth for evidence, routing, and policy gates.
+
+## Documentation Improvements Already Applied
+
+- Rewrote the README opening so the first screen names the actual user problems:
+  MaStR, grid context, Redispatch, ZNP, §14a/§14d, Knowledge RAG, process
+  intake, and read-only operational APIs.
+- Added "Who This Is For", "How OpenClaw And Cernion Work Together", example
+  prompts, and capability bullets before the low-level endpoint contract.
+- Added a ClawHub install command near the top.
+- Expanded `package.json` keywords so package registries and marketplace search
+  have energy-domain terms to index.
+- Updated plugin/package descriptions away from "Dedicated sidecar" toward the
+  actual outcome.
+
+## Recommended Next Moves
+
+- Republish a patch version so ClawHub and npm show the new description and
+  keywords in their metadata.
+- Add one short demo GIF or screenshot to the README showing a real
+  Cernion-backed answer in OpenClaw Control UI.
+- Publish a short "OpenClaw energy assistant with Cernion" guide that starts
+  from one concrete use case, for example Meckesheim self-supply, §14a duties,
+  or ZNP siting for PV/BESS/HPC.
+- Link the ClawHub package from Cernion Energy Tools documentation under
+  "Agent integrations", not only from the Sidecar repository.
+- Create issue/discussion templates for three discovery paths:
+  "I have an energy question", "I have a Cernion instance", and "I want to
+  build an OpenClaw energy assistant".

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "cernion-energy-tools-sidecar",
   "name": "Cernion Energy Tools Sidecar",
-  "description": "Expose Cernion Energy Tools to OpenClaw through separated evidence, knowledge, process-intake, and read-only REST boundaries.",
-  "version": "0.1.1",
+  "description": "Give OpenClaw agents Cernion-backed energy evidence for MaStR assets, grid context, Redispatch, ZNP, §14a/§14d, Knowledge RAG, process intake, and read-only operational APIs.",
+  "version": "0.1.2",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "@cernion/openclaw-energy-tools-sidecar",
-  "version": "0.1.1",
-  "description": "Dedicated OpenClaw sidecar for Cernion Energy Tools.",
+  "version": "0.1.2",
+  "description": "Cernion energy evidence tools for OpenClaw agents: MaStR assets, grid context, Redispatch, ZNP, §14a/§14d, Knowledge RAG, and read-only operational APIs.",
+  "keywords": [
+    "openclaw",
+    "cernion",
+    "energy",
+    "energy-tools",
+    "grid-planning",
+    "netzplanung",
+    "zielnetzplanung",
+    "znp",
+    "redispatch",
+    "mastr",
+    "ma-st-r",
+    "enwg",
+    "14a",
+    "14d",
+    "photovoltaic",
+    "pv",
+    "bess",
+    "grid-context",
+    "knowledge-rag",
+    "evidence",
+    "sidecar"
+  ],
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -23,6 +46,7 @@
     "dist",
     "scripts",
     "docker",
+    "docs",
     "openclaw.plugin.json",
     "README.md",
     "CHANGELOG.md",