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

AGENTS.md

@@ -125,6 +125,33 @@ Reactions are lightweight social signals. Humans use them constantly — they sa
 
 Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
 
+## Git Workflow
+
+- Commit frequently in small, meaningful checkpoints.
+- Use Conventional Commits format: `type(scope): summary`.
+- Create a feature branch when work is non-trivial, multi-step, or risky.
+- Keep `main` stable; merge focused changes back after verification.
+- Before commit, quickly check staged diff and avoid committing secrets/runtime noise.
+
+### OpenClaw upstream workflow (required for core code changes)
+
+- Treat `external/openclaw-upstream/` as the source repo for OpenClaw codebase work.
+- Do **not** rely on editing installed dist files under `~/.npm-global/.../dist` as the long-term fix path.
+- For OpenClaw code changes:
+  1. `cd external/openclaw-upstream`
+  2. `git fetch --all --prune && git checkout main && git pull --ff-only`
+  3. Create a focused branch (`fix/...`, `feat/...`, `chore/...`)
+  4. Implement in `src/` and add/adjust tests
+  5. Run relevant tests before commit
+  6. Commit, push branch, and open PR
+- If an emergency local dist hotfix is unavoidable, also:
+  - capture an idempotent patch script in `scripts/`
+  - document rollback/update behavior
+  - follow up with an upstream PR ASAP
+- Keep local OpenClaw runtime current:
+  - check status with `openclaw update status`
+  - prefer `scripts/openclaw-update-safe.sh` for updates when local compatibility patches exist
+
 **🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
 
 **📝 Platform Formatting:**