docs(workflow): require upstream repo + branch/update hygiene

scripts/openclaw-upstream-workflow.md

@@ -0,0 +1,53 @@
+# OpenClaw Upstream Workflow
+
+Use this whenever modifying OpenClaw itself.
+
+## Source of truth
+
+- Upstream working clone: `external/openclaw-upstream/`
+- Install path (`~/.npm-global/lib/node_modules/openclaw/dist`) is runtime output, not long-term source.
+
+## Standard flow
+
+```bash
+cd external/openclaw-upstream
+git fetch --all --prune
+git checkout main
+git pull --ff-only
+git checkout -b fix/<short-topic>
+```
+
+Then:
+1. Implement in `src/` (and docs/tests as needed).
+2. Run targeted tests first; run broader suite if change touches shared paths.
+3. Commit with Conventional Commit format.
+4. Push branch and open PR.
+
+## Branch naming
+
+- `fix/...` for bugfixes
+- `feat/...` for new behavior
+- `chore/...` for maintenance
+- keep names short and specific (`fix/tui-hide-internal-runtime-context`)
+
+## Update hygiene
+
+- Check runtime version: `openclaw update status`
+- If local compatibility patch exists, update with:
+
+```bash
+scripts/openclaw-update-safe.sh
+```
+
+- After runtime update, re-sync upstream clone before new changes:
+
+```bash
+cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --ff-only
+```
+
+## Emergency dist hotfix policy
+
+If a dist-file hotfix is unavoidable:
+- keep it scripted (`scripts/...`), idempotent, and reversible
+- document it (`patches/.../README.md`)
+- land the proper upstream source fix and PR as soon as possible