OnlyTerp · OnlyTerp · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -3,6 +3,9 @@ contact_links:
   - name: Question about OpenClaw itself (not the guide)
     url: https://github.com/openclaw/openclaw/issues
     about: For OpenClaw bugs, feature requests, or usage questions, open an issue on the OpenClaw repo instead.
+  - name: OpenClaw documentation
+    url: https://clawdocs.org/
+    about: Official OpenClaw docs — the right place for questions about the product itself.
   - name: Read the FAQ first
     url: https://github.com/OnlyTerp/openclaw-optimization-guide/blob/master/part27-gotchas-and-faq.md
     about: Most questions are already answered in Part 27 — Gotchas & FAQ.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -33,7 +33,7 @@ Thanks for wanting to make the guide better. This is a living document — OpenC
 - **Links > inline duplication.** If something is already covered in another part, link to it.
 - **Cross-link new parts** from the relevant existing parts and the README TOC.
 - **Consistent heading levels.** Each part starts with `# Part N: Title`, major sections are `##`, subsections `###`.
-- **Mark deprecated content** with a block quote at the top saying "DEPRECATED — use [Part X] instead" (see [Part 16](./part16-autodream-memory-consolidation.md) for an example).
+- **Mark deprecated content** with a block quote at the top saying "DEPRECATED — use [Part X] instead". When a part is fully retired, delete the file and leave a one-paragraph tombstone in the part that supersedes it (see the Part 22 "What Changed (and the Part 16 Retirement)" block in the README for the pattern).
 
 ## Running The Quality Checks Locally
 

diff --git a/README.md b/README.md
diff --git a/part10-state-of-the-art-embeddings.md b/part10-state-of-the-art-embeddings.md
@@ -6,6 +6,9 @@
 
 The main guide's one-shot prompt installs a local embedding model via Ollama. Pick the right tier for your hardware:
 
+> **Read this if** you care about retrieval quality, you're running local embeddings, or you want to evaluate the GitHub Copilot embedding provider added in 2026.4.15-beta.1.
+> **Skip if** you're using cloud embeddings behind a managed memory service and don't mind the latency/cost — the defaults are fine for casual single-user setups.
+
 ## Embedding Model Tiers
 
 | Tier | Model | Dims | RAM | Speed | Quality | Best For |
@@ -39,7 +42,7 @@ OpenClaw 2026.4.15-beta.1 added a `copilot` memory-search provider. If your org
 
 **When it doesn't:** a personal/power-user setup. The latency is still cloud-cloud (2-5s round trip), you lose offline capability, and you're still better off with a local Ollama `qwen3-embedding:0.6b` that answers in <100ms for free.
 
-**Gotcha:** Copilot embeddings share rate limits with Copilot chat completions. If you also use Copilot as an agent model, heavy memory-search traffic can starve chat \u2014 watch the new Model Auth card in Control UI for rate-limit pressure and keep a local fallback configured.
+**Gotcha:** Copilot embeddings share rate limits with Copilot chat completions. If you also use Copilot as an agent model, heavy memory-search traffic can starve chat — watch the new Model Auth card in Control UI for rate-limit pressure and keep a local fallback configured.
 
 The `qwen3-embedding:0.6b` model is the sweet spot for most users — it's from the same Qwen3 family that holds #1 on MTEB, runs on anything, and blows away nomic on quality. Install via `ollama pull qwen3-embedding:0.6b`.
 

diff --git a/part11-auto-capture-hook.md b/part11-auto-capture-hook.md
@@ -12,6 +12,9 @@ ByteRover (a community plugin on ClawHub) solves this with an `afterTurn` hook t
 
 ---
 
+> **Read this if** your `vault/00_inbox/` stays empty, you keep forgetting to save useful conversations, or you want knowledge extraction to happen automatically after every session.
+> **Skip if** you're disciplined about manually saving knowledge, or the built-in `session-memory` hook is already giving you what you need.
+
 ## How It Works
 
 The auto-capture hook fires on three events:

diff --git a/part12-self-improving-system.md b/part12-self-improving-system.md
@@ -4,6 +4,9 @@ Your agent makes a mistake Monday. You correct it. Tuesday, same mistake. Wednes
 
 **The fix: a micro-learning loop that costs <100 tokens/message and compounds forever.**
 
+> **Read this if** you correct the same mistakes every week, or want your agent to compound learnings over months instead of forgetting them at the next `/new`.
+> **Skip if** you only use your agent for one-off tasks where pattern memory isn't worth the infra.
+
 ## The Architecture
 
 ```

diff --git a/part13-memory-bridge.md b/part13-memory-bridge.md
@@ -4,6 +4,9 @@ When you spawn Codex or Claude Code to build something, they start blind. They d
 
 **The fix: inject your vault knowledge into the coding agent's workspace before it starts.**
 
+> **Read this if** you spawn Codex, Claude Code, or other coding agents and they start every session blind to your architecture / past decisions.
+> **Skip if** you don't use external coding agents — or your vault is small enough to paste into their prompts manually.
+
 ## The Problem
 
 ```

diff --git a/part15-infrastructure-hardening.md b/part15-infrastructure-hardening.md
@@ -4,6 +4,9 @@ Your OpenClaw setup probably has hidden landmines that cause crash loops, GPU co
 
 ---
 
+> **Read this if** you're running OpenClaw in production, have more than one user on it, or have ever hit a gateway crash loop, GPU contention, or a secret leak in an approval prompt.
+> **Skip if** you're experimenting on a single-user dev box and don't mind restarting every few hours.
+
 ## The Compaction Crash Loop
 
 ### The Problem
@@ -243,27 +246,27 @@ After the Claude Code leak, a developer built [secretgate](https://github.com/ni
 
 ### Gateway Auth Hot-Reload (new in 2026.4.15-beta.1)
 
-Before 2026.4.15-beta.1, rotating a gateway auth secret required a full gateway restart \u2014 every agent, every running sub-agent, every in-flight cron job got dropped. That made rotation so painful that most operators just\u2026 didn't. Expired OAuth tokens quietly degraded half the setup.
+Before 2026.4.15-beta.1, rotating a gateway auth secret required a full gateway restart — every agent, every running sub-agent, every in-flight cron job got dropped. That made rotation so painful that most operators just… didn't. Expired OAuth tokens quietly degraded half the setup.
 
 2026.4.15-beta.1 adds `secrets.reload`: drop a new value into your secret store and the gateway picks it up without restarting. New requests use the new secret; in-flight requests finish on the old one.
 
 ```bash
 # Example: rotate an Anthropic key without killing the gateway
 # (exact command depends on how your secrets are wired)
 openclaw secrets set ANTHROPIC_API_KEY "sk-ant-new-key-here"
-openclaw secrets reload
+openclaw secrets reload   # verb varies across 2026.4.x betas—check `openclaw --help`
 openclaw doctor  # confirm new key picked up
 ```
 
 **Use this to finally rotate those 12-month-old keys you're embarrassed about.** Ideally wire it into a quarterly cron or your password-manager rotation policy.
 
 ### Approvals Secret Redaction (new in 2026.4.15-beta.1)
 
-When a tool call required approval, the approval prompt used to echo the full argument payload to the approver \u2014 including any API keys, tokens, or passwords the tool was about to send. A reviewer clicking "approve" on a `curl` call was reading the raw `Authorization: Bearer \u2026` header.
+When a tool call required approval, the approval prompt used to echo the full argument payload to the approver — including any API keys, tokens, or passwords the tool was about to send. A reviewer clicking "approve" on a `curl` call was reading the raw `Authorization: Bearer …` header.
 
-2026.4.15-beta.1 redacts secret-shaped strings (`sk-*`, `sk-ant-*`, `AIza*`, `xai-*`, `Bearer *`, `password=*`, etc.) from approval prompts before they reach the reviewer. The tool still receives the real values \u2014 only the approval UI sees placeholders.
+2026.4.15-beta.1 redacts secret-shaped strings (`sk-*`, `sk-ant-*`, `AIza*`, `xai-*`, `Bearer *`, `password=*`, etc.) from approval prompts before they reach the reviewer. The tool still receives the real values — only the approval UI sees placeholders.
 
-**Practical impact:** if you run OpenClaw with human-in-the-loop approvals (most multi-user deployments should \u2014 see [Part 24](./part24-task-brain-control-plane.md)), upgrade. Before this fix, every approval was a credential leak to the approver.
+**Practical impact:** if you run OpenClaw with human-in-the-loop approvals (most multi-user deployments should — see [Part 24](./part24-task-brain-control-plane.md)), upgrade. Before this fix, every approval was a credential leak to the approver.
 
 ### Gateway Crash Loop Fix
 
@@ -294,7 +297,7 @@ This kills any orphaned gateway process before starting a new one. Without this,
 - [ ] No credentials written in memory/session files (rule in AGENTS.md)
 - [ ] Existing git history scanned for leaked secrets
 - [ ] Gateway startup script has stale-process cleanup
-- [ ] Gateway auth hot-reload tested (2026.4.15-beta.1+): rotate a test key via `openclaw secrets reload` without a gateway restart
+- [ ] Gateway auth hot-reload tested (2026.4.15-beta.1+): rotate a test key and confirm the Canvas **Model Auth status card** picks up the new credential without a full gateway restart (backed by the `models.authStatus` gateway method)
 - [ ] Approval prompts show redacted secrets, not raw values (2026.4.15-beta.1+)
 - [ ] Config backed up before changes
 - [ ] Gateway restarted after config changes