docs: absorb documentation PR sweep

docs/reference/secret-placeholder-conventions.md

@@ -0,0 +1,33 @@
+---
+summary: "Secret-scanner-safe placeholder conventions for docs and examples"
+read_when:
+  - Writing docs that include tokens, API keys, or credential snippets
+  - Updating examples that may be scanned by secret-detection tooling
+title: "Secret Placeholder Conventions"
+---
+
+# Secret placeholder conventions
+
+Use placeholders that are human-readable but do not resemble real secrets.
+
+## Recommended style
+
+- Prefer descriptive values like `example-openai-key-not-real` or `example-discord-bot-token`.
+- For shell snippets, prefer `${OPENAI_API_KEY}` over inline token-like strings.
+- Keep examples obviously fake and scoped to purpose (provider, channel, auth type).
+
+## Avoid these patterns in docs
+
+- Private key sentinels such as `-----BEGIN PRIVATE KEY-----`.
+- Prefixes that resemble live credentials, for example `sk-...`, `xoxb-...`, `AKIA...`.
+- Realistic-looking bearer tokens copied from runtime logs.
+
+## Example
+
+```bash
+# Good
+export OPENAI_API_KEY="example-openai-key-not-real"
+
+# Better (when the doc is about env wiring)
+export OPENAI_API_KEY="${OPENAI_API_KEY}"
+```

docs/reference/token-use.md

@@ -26,6 +26,10 @@ OpenClaw assembles its own system prompt on every run. It includes:
 
 See the full breakdown in [System Prompt](/concepts/system-prompt).
 
+When documenting credentials or auth snippets, use the
+[Secret Placeholder Conventions](/reference/secret-placeholder-conventions) to
+avoid secret-scanner false positives in docs-only changes.
+
 ## What counts in the context window
 
 Everything the model receives counts toward the context limit: