Top-tier upgrade: Architecture primer, Migration guide, Gotchas/FAQ, themed README, contributor tooling

[OnlyTerp]

Summary

Second pass toward "THE BEST GUIDE ON GITHUB." Builds on #3 with primer/navigation/tooling work: three new flagship parts, a full README hero rebuild, and a CI-backed contribution workflow so the guide stays clean as it grows.

Type of change

• New part (x3)
• Correction to existing parts
• Tooling / CI / meta

What's new

Primers & references (new parts)

• Part 25 — Architecture Overview (v4.0+) — 15-minute primer mapping the five components (gateway, agent runtime, memory layer, skills, surfaces) with a mermaid diagram and a request-flow sequence diagram. Version timeline table so readers can tell which era a piece of advice belongs to.
• Part 26 — Migration Guide — opinionated upgrade paths: v3.x → v4.0 → v2026.3.31-beta.1 → v2026.4.x → v2026.4.15-beta.1. Each path has a breaking-change list, steps, known-bad gotchas, and a rollback plan. "Before you upgrade" snapshot script at the top.
• Part 27 — Gotchas & FAQ — symptom-indexed troubleshooting ("memory search returns nothing", "gateway keeps restarting", "compaction crashes in a loop", etc.) with cause → fix tables. FAQ section for newcomer questions.

README rebuild

• Badges row (version, parts, license, PRs-welcome)
• Who This Is For section (four reader archetypes → where to start)
• Start Here (in this order) — Part 25 → Part 14 → Part 17 → Part 27
• What You Get numbers table (context size, search latency, compaction crash rate, token reduction, audit-trail coverage)
• What Changed In This Release — highlights for the 2026.4.15-beta.1 refresh
• How The Pieces Fit Together mermaid diagram
• Navigate By Goal table (9 goals → starting points), plus the original numeric TOC regrouped into themed sections (Speed / Memory / Orchestration / Knowledge Graph / Hardening / Observability)

Part 16 deprecation

• Clear ⚠️ DEPRECATED banner at the top pointing to Part 22 (memory-core built-in dreaming)
• Kept as archival reference; noted it won't be updated for new versions
• Fixed broken footer link to a non-existent part17-coordinator-protocol.md

Contributor tooling

• CONTRIBUTING.md — what to contribute / what not to / style / how to run checks locally
• Issue templates: Correction, Gap, Version bump; config.yml routes OpenClaw bug reports to the upstream repo and steers questions to Part 27 first
• pull_request_template.md with a review checklist
• .github/workflows/docs-quality.yml — runs markdownlint-cli2 + lychee (internal link check) on every push / PR
• .markdownlint.jsonc tuned for prose; disables the rules that fight opinionated writing, keeps correctness rules
• Fixed one real MD001 heading-increment issue in Part 10

Checks

• Local markdownlint-cli2 "**/*.md" → 0 errors
• Local internal-link scan (python glob over all ./*.md refs) → all clean
• Lychee will run in CI for full internal link check

Flagged items (reviewer sanity-check, same as PR #3)

These are informed guesses based on our discussion, not direct reads of the OpenClaw 2026.4.15-beta.1 schema. Correct me and I'll re-stamp:

1. Config keys carried over from Refresh guide for OpenClaw 2026.4.15-beta.1 (ClawHub, Task Brain, 4.15 fixes) #3 (memorySearch.provider: "copilot", agents.defaults.experimental.localModelLean, semantic categories read-only.* / execution.* / write.* / control-plane.*, openclaw secrets reload, openclaw tasks list/show/audit).
2. Part 25 data-flow sequence diagram — describes a plausible spawn flow (main → spawn → worker → tool → approval → back up the chain). If Task Brain records differently, I'll adjust.
3. Part 26 rollback snippet — I suggested a generic npm install -g openclaw@... pin. Replace with the actual install method recommended by OpenClaw docs if different (brew tap, binary, cargo, etc.).
4. "March CVE wave" reference in Part 26 & Part 25 — kept from PR Refresh guide for OpenClaw 2026.4.15-beta.1 (ClawHub, Task Brain, 4.15 fixes) #3's Part 24. If the real post-mortem has a different name or date range, I'll update.
5. Endorsed skill names / upstream URL in issue config — https://github.com/openclaw/openclaw/issues is my best guess for the upstream OpenClaw repo. Update if the real org/repo is different.

Sources / context

• Builds directly on Refresh guide for OpenClaw 2026.4.15-beta.1 (ClawHub, Task Brain, 4.15 fixes) #3 (merged 2026-04-16)
• Follows the style guide in the newly-added CONTRIBUTING.md

Link to Devin session: https://app.devin.ai/sessions/df6f8c16f82e448b915735660ed94fb7
Requested by: @OnlyTerp

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review finding addressed in 926-ish: the truncated #part-5-orchestration anchor (also present in the pre-existing part24-task-brain-control-plane.md from PR #3) is now updated to the full GitHub slug #part-5-orchestration-stop-doing-everything-yourself in both parts.

Side note for the @OnlyTerp: lychee's include_fragments = false and markdownlint's disabled MD051 are deliberate — GitHub's slug generation disagrees with both tools' parsers on emoji-prefixed and colon-containing headings, which would have made CI a false-positive factory. We rely on manual audits + Devin Review for fragment-level catches like this one.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 6 additional findings in Devin Review.

[devin-ai-integration]

🟡 Inconsistent UI name: "Control UI" vs "Canvas UI" for the same component

This PR introduces two different names for the same browser UI component. Part 25 (part25-architecture-overview.md:95) authoritatively defines it as "Canvas UI", and Part 26 uses "Canvas UI" consistently (part26-migration-guide.md:115,120,157). However, Part 10's new Copilot section calls it "Control UI", and the README also uses "Control UI" in three new passages (README.md:822, README.md:1194, README.md:1457). All of these references are new in this PR (confirmed: "Control UI" does not exist on master). A reader following Part 25's architecture primer will look for "Canvas UI" and not find it when reading Part 10 or the README checklist sections, and vice versa.

(Refers to line 42)

---

Was this helpful? React with 👍 or 👎 to provide feedback.