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`.
@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "timonwong.shellcheck",
+    "redhat.vscode-yaml",
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "esbenp.prettier-vscode"
+  ]
+}
@@ -0,0 +1,44 @@
+{
+  "editor.formatOnSave": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "files.eol": "\n",
+
+  "[shellscript]": {
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true
+  },
+  "[yaml]": {
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true
+  },
+  "[python]": {
+    "editor.tabSize": 4,
+    "editor.insertSpaces": true
+  },
+  "[markdown]": {
+    "editor.wordWrap": "on",
+    "editor.quickSuggestions": {
+      "comments": "off",
+      "strings": "off",
+      "other": "off"
+    }
+  },
+
+  "files.associations": {
+    "*.tpl": "nginx"
+  },
+
+  "yaml.validate": true,
+  "yaml.format.enable": true,
+
+  "shellcheck.enable": true,
+  "shellcheck.run": "onType",
+
+  "python.analysis.typeCheckingMode": "basic",
+  "python.analysis.autoImportCompletions": true,
+
+  "search.exclude": {
+    "**/__pycache__": true
+  }
+}
@@ -0,0 +1,108 @@
+# Repository Guidelines
+
+## Project Scope
+
+This repository builds the **OpenClaw Assistant (DEV)** Home Assistant add-on.
+The add-on packages OpenClaw + nginx + ttyd and manages startup/configuration glue.
+
+## Architecture at a Glance
+
+- Add-on root metadata/docs:
+  - `README.md`
+  - `DOCS.md`
+  - `SECURITY.md`
+  - `repository.yaml`
+- Runtime implementation (all add-on behavior lives here):
+  - `openclaw_assistant_dev/run.sh` (PID 1 orchestrator)
+  - `openclaw_assistant_dev/oc_config_helper.py` (safe JSON config edits)
+  - `openclaw_assistant_dev/render_nginx.py` (template rendering)
+  - `openclaw_assistant_dev/nginx.conf.tpl`
+  - `openclaw_assistant_dev/landing.html.tpl`
+  - `openclaw_assistant_dev/config.yaml` (HA options + schema)
+  - `openclaw_assistant_dev/translations/*.yaml` (all locale UI strings)
+  - `openclaw_assistant_dev/Dockerfile`
+  - `openclaw_assistant_dev/CHANGELOG.md`
+
+## Core Rules
+
+- Fix root causes, not symptoms.
+- Keep edits surgical; do not refactor unrelated code.
+- Never introduce insecure defaults.
+- Never log secrets or auth tokens.
+- Keep behavior backward-compatible unless the change explicitly requires a migration.
+
+## Add-on Config Coupling Rules (Critical)
+
+When adding/changing any add-on option, update **all** of the following in one change:
+
+1. `openclaw_assistant_dev/config.yaml`
+   - `options:` default
+   - `schema:` validation entry
+   - comments/help text
+2. `openclaw_assistant_dev/translations/en.yaml`
+3. `openclaw_assistant_dev/translations/bg.yaml`
+4. `openclaw_assistant_dev/translations/de.yaml`
+5. `openclaw_assistant_dev/translations/es.yaml`
+6. `openclaw_assistant_dev/translations/pl.yaml`
+7. `openclaw_assistant_dev/translations/pt-BR.yaml`
+8. `DOCS.md` configuration reference / troubleshooting if user-facing
+9. `openclaw_assistant_dev/CHANGELOG.md`
+
+If any of these are skipped, the UX becomes inconsistent in HA.
+
+## Runtime Safety Rules
+
+- `run.sh` runs with `set -euo pipefail`; avoid constructs that fail unexpectedly under `set -e`.
+- Validate all user-provided values from `/data/options.json` before injecting into shell/nginx/openclaw config.
+- Keep `run.sh` idempotent on restart (multiple starts must not corrupt state).
+- Treat `/config/` as persistent state; never wipe user data unless explicitly requested.
+
+## Gateway/Auth/Security Rules
+
+- OpenClaw v2026.2.22+ redacts sensitive values in `openclaw config get`.
+  - For token retrieval guidance, prefer: `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json`.
+- `trusted-proxy` mode may reject direct local CLI WS calls (`trusted_proxy_user_missing`); document this clearly instead of hiding it.
+- For `lan_https` certificate logic, keep SAN generation deterministic and regeneration-triggered on SAN/IP changes.
+
+## Template Coupling Rules
+
+- If adding placeholders in `landing.html.tpl` or `nginx.conf.tpl`, update `render_nginx.py` in the same change.
+- If landing-page guidance changes (commands/errors), sync corresponding troubleshooting text in `DOCS.md`.
+
+## Versioning and Changelog
+
+- User-visible changes should update:
+  - `openclaw_assistant_dev/CHANGELOG.md`
+  - `openclaw_assistant_dev/config.yaml` version
+- Keep changelog entries user-facing and action-oriented.
+
+## Coding Style
+
+- Shell: POSIX-friendly Bash, explicit quoting, descriptive variable names.
+- Python: small focused helpers, explicit error handling, no hidden side effects.
+- YAML/Markdown: preserve existing style and structure.
+- Avoid adding dependencies unless necessary.
+
+## Validation Checklist (Run After Relevant Changes)
+
+From repo root:
+
+```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
+```
+
+For option changes:
+- verify `config.yaml` option + schema + all translations exist
+- verify `DOCS.md` matches current behavior
+
+For startup/auth/proxy/cert changes:
+- verify log messages remain clear and actionable
+- verify `landing.html.tpl` instructions match actual commands
+
+## Commit Scope
+
+- Group related changes only.
+- Do not include unrelated formatting churn.
+- Do not edit generated/cache folders (`__pycache__`, temporary outputs).
@@ -0,0 +1 @@
+AGENTS.md