agentic instructions and guidelines

2026-02-25 18:13:45 +02:00
parent ab07454051
commit 615ea2f1a4
5 changed files with 218 additions and 0 deletions
@@ -0,0 +1,56 @@
+# OpenClaw Home Assistant Add-on Patterns
+
+Always reuse existing logic in `run.sh`, `oc_config_helper.py`, and `render_nginx.py`.
+Avoid duplicate implementations for config parsing, gateway patching, or template rendering.
+Respect guidelines in AGENTS.md
+
+## Stack
+
+- Home Assistant add-on (Debian Bookworm base)
+- Bash runtime orchestrator (`run.sh`)
+- Python helper scripts for config/template work
+- nginx template rendering
+- YAML config schema + 6 locale translation files
+
+## Source of Truth
+
+- Add-on options/schema: `openclaw_assistant_dev/config.yaml`
+- Runtime boot logic: `openclaw_assistant_dev/run.sh`
+- Safe OpenClaw config edits: `openclaw_assistant_dev/oc_config_helper.py`
+- nginx + landing rendering: `openclaw_assistant_dev/render_nginx.py`
+- UI text in Home Assistant: `openclaw_assistant_dev/translations/*.yaml`
+- User-facing docs: `DOCS.md`
+
+## Required Sync Rules
+
+When changing add-on options, update in the same PR:
+
+1. `config.yaml` option default + schema
+2. All translation files (`en`, `bg`, `de`, `es`, `pl`, `pt-BR`)
+3. `DOCS.md` config/troubleshooting sections
+4. `CHANGELOG.md`
+
+When changing landing/nginx placeholders:
+- Keep template keys and `render_nginx.py` replacements in sync.
+
+## Security Rules
+
+- Do not log secrets/tokens.
+- For gateway token docs/UI guidance, do not use `openclaw config get gateway.auth.token` (redacted in v2026.2.22+).
+- Prefer `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json`.
+
+## Editing Rules
+
+- Keep fixes minimal and root-cause focused.
+- Preserve backward compatibility for existing add-on options unless migration is explicit.
+- Do not change unrelated behavior while fixing one issue.
+
+## Validation Commands
+
+```sh
+bash -n openclaw_assistant_dev/run.sh
+python3 -m py_compile openclaw_assistant_dev/oc_config_helper.py
+python3 -m py_compile openclaw_assistant_dev/render_nginx.py
+```
+
+If behavior changes are user-visible, update `openclaw_assistant_dev/CHANGELOG.md`.