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,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).