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

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+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: 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.

.github/ISSUE_TEMPLATE/correction.md

@@ -0,0 +1,21 @@
+---
+name: Correction
+about: Something in the guide is wrong or outdated
+title: "[Correction] <part number and short description>"
+labels: correction
+---
+
+**Which part?**
+Part N — ...
+
+**What's wrong?**
+Quote the current text, or link to the specific line.
+
+**What's the correct version?**
+What should it say instead?
+
+**Source**
+Release notes, config schema, your own testing — whatever backs up the correction.
+
+**OpenClaw version you're on**
+e.g. `2026.4.15-beta.1`

.github/ISSUE_TEMPLATE/gap.md

@@ -0,0 +1,18 @@
+---
+name: Gap
+about: The guide doesn't cover something that it should
+title: "[Gap] <topic>"
+labels: gap
+---
+
+**What's missing?**
+One-sentence summary.
+
+**Where does it belong?**
+Existing part to expand, or case for a new part?
+
+**Why does it matter?**
+Who hits this and when? Rough shape of the problem.
+
+**What do you already know about it?**
+Any existing notes, release info, or external write-ups you can share.

.github/ISSUE_TEMPLATE/version-bump.md

@@ -0,0 +1,21 @@
+---
+name: Version bump
+about: A new OpenClaw version shipped and the guide needs updating
+title: "[Version] <version number>"
+labels: version-bump
+---
+
+**New OpenClaw version**
+e.g. `2026.5.0`
+
+**Release notes**
+Link.
+
+**Material changes that affect the guide**
+Bullet list. For each item, call out:
+- Which existing part needs updating (or "new part needed")
+- Whether it's breaking, deprecating, or additive
+- Anything the migration guide ([Part 26](../../part26-migration-guide.md)) needs to capture
+
+**Volunteering to send the PR?**
+Yes/no. If yes, link the branch when you push it.

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+<!-- Thanks for contributing. Delete sections that don't apply. -->
+
+## Summary
+<!-- One paragraph: what does this PR change and why? -->
+
+## Type of change
+- [ ] Correction to an existing part
+- [ ] Version bump (OpenClaw version)
+- [ ] New part
+- [ ] Benchmark / data addition
+- [ ] Tooling / CI / meta
+
+## Review checklist
+- [ ] Added or updated cross-links from the README TOC and any related parts
+- [ ] Sources / release notes linked in the PR description (not inline as footnotes)
+- [ ] Ran `markdownlint-cli2` and `lychee --offline` locally (CI will also run these)
+- [ ] No speculation presented as fact — any uncertainty is called out in the PR description
+
+## Notes / flagged items
+<!-- Anything you're not 100% sure about that a reviewer should sanity-check. -->

.github/workflows/docs-quality.yml

@@ -0,0 +1,35 @@
+name: docs-quality
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+permissions:
+  contents: read
+
+jobs:
+  markdownlint:
+    name: markdownlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          globs: "**/*.md"
+
+  linkcheck:
+    name: link check (internal only)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --offline
+            --no-progress
+            --verbose
+            '**/*.md'
+          fail: true

.markdownlint.jsonc

@@ -0,0 +1,56 @@
+{
+  // Config for markdownlint-cli2 — prose guide, permissive by design.
+  // We keep rules that catch real correctness problems (heading levels, etc.)
+  // and disable the ones that fight an opinionated writing style.
+  "default": true,
+
+  // --- Style rules we deliberately turn off ---
+
+  // Line length — prose, hard-wrap hurts readability.
+  "MD013": false,
+
+  // Inline HTML is fine (we use <sub>, <br/>, details/summary).
+  "MD033": false,
+
+  // Bare URLs in tables / inline.
+  "MD034": false,
+
+  // Emphasis-as-heading is part of the voice.
+  "MD036": false,
+
+  // Trailing punctuation in headings is allowed ("Stop Being Slow.").
+  "MD026": false,
+
+  // Don't require language on every fence — ASCII art blocks.
+  "MD040": false,
+
+  // Allow blanks inside block quotes for multi-paragraph callouts.
+  "MD028": false,
+
+  // Allow duplicate headings at different levels / siblings.
+  "MD024": { "siblings_only": true },
+
+  // First line doesn't have to be a top-level heading (badges first).
+  "MD041": false,
+
+  // Table column style — allow mixed alignment; we use it deliberately.
+  "MD060": false,
+
+  // --- Blank-line rules: relaxed so templates and nested tables don't break CI ---
+
+  // Blank line around headings / fences / tables.
+  "MD022": false,
+  "MD031": false,
+  "MD032": false,
+  "MD058": false,
+
+  // Multiple consecutive blank lines — keep tight, but 2 is fine in block quotes.
+  "MD012": { "maximum": 2 },
+
+  // Trailing newline at EOF — nice-to-have, not worth failing CI on legacy files.
+  "MD047": false,
+
+  // Anchor fragment validation disagrees with GitHub's slug behaviour for
+  // headings with emojis and colons. We link-check with lychee instead.
+  "MD051": false
+}

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thanks for wanting to make the guide better. This is a living document — OpenClaw moves fast, and the only way the guide stays accurate is if people file corrections when they spot something off.
+
+## What to Contribute
+
+**Corrections to existing parts.** If you read something that's wrong, outdated, or confusing, fix it. Short PRs with a clear "this was wrong, this is right" explanation in the description are the easiest to review.
+
+**Version bumps.** When a new OpenClaw version ships with something material (a new config key, a deprecated feature, a new CVE fix), open a PR that:
+
+1. Updates the version line at the top of the README.
+2. Adds a "What changed in this release" bullet in the README hero.
+3. Updates the specific part(s) that are affected.
+4. Adds a row to the migration guide ([Part 26](./part26-migration-guide.md)) if the change is non-trivial.
+
+**New parts.** High bar. A new part should cover a distinct pillar (not a subtopic of an existing part) that's both material and not going to become obsolete in the next release. Open an issue first to discuss — nothing worse than writing 1,500 words of markdown that gets rejected as out of scope.
+
+**Benchmarks.** Real numbers from a real deployment beat prose. If you measured something (search latency, compaction behavior, token reduction from Repowise, etc.), send a PR to `benchmarks/` with the methodology and results.
+
+**Diagrams.** Mermaid is cheap and renders natively on GitHub. If a section would benefit from a diagram, add one.
+
+## What Not to Contribute
+
+- **Speculation.** If you're not sure something is true, don't write it as if it is. Flag uncertainty in the PR description and leave the wording conservative.
+- **Marketing copy.** This guide exists because generic marketing docs don't help anyone. Keep claims concrete and cite your source (a release note, a config key, a measurement).
+- **Personal-blog posts masquerading as parts.** If your change is really about your specific setup, it probably belongs as an issue comment or a linked external write-up, not a new part.
+- **Emoji-heavy rewrites.** The guide uses emoji sparingly for navigation and section markers. Keep prose clean.
+
+## Style
+
+- **Terse > wordy.** Shorter paragraphs, concrete examples, no preambles.
+- **Tables for comparisons**, bulleted lists for steps, fenced code blocks for commands.
+- **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).
+
+## Running The Quality Checks Locally
+
+```bash
+# markdownlint-cli2
+npm install -g markdownlint-cli2
+markdownlint-cli2 "**/*.md" "#node_modules"
+
+# lychee (link checker)
+# macOS/Linux: cargo install lychee  OR  brew install lychee
+lychee --offline --no-progress "**/*.md"
+# drop --offline to also check external links (slower)
+```
+
+CI runs both on every PR via [.github/workflows/docs-quality.yml](./.github/workflows/docs-quality.yml). PRs must pass both checks before merging.
+
+## Opening an Issue
+
+Use [the issue templates](./.github/ISSUE_TEMPLATE/). Summary:
+
+- **Correction** — "This claim in Part X is wrong/outdated."
+- **Gap** — "Part X doesn't cover Y, which matters because Z."
+- **Version bump** — "OpenClaw vN shipped; here's what needs updating."
+- **Question** — before opening, read [Part 27 — Gotchas & FAQ](./part27-gotchas-and-faq.md) first.
+
+## License
+
+Contributions are licensed under the same [MIT license](./LICENSE) as the rest of the guide. Don't send code or content you can't relicense.
+
+## A Note On Tone
+
+The guide has an opinionated voice — short sentences, clear claims, visible frustration with things that shouldn't be this hard. Feel free to write in that register. But stay kind to other contributors in review comments. We're all here to make the guide better.