Skip to content

Commit 343e83c

Browse files
OnlyTerpdevin-ai-integration[bot]
OnlyTerp
and
devin-ai-integration[bot]
authored
Merge pull request #4 from OnlyTerp/devin/1776395316-toptier-upgrade
* Top-tier upgrade: arch overview, migration guide, gotchas+FAQ, themed README, contrib tooling - NEW Part 25: Architecture Overview (v4.0+) — 15-min primer with mermaid diagram - NEW Part 26: Migration Guide — opinionated v3 → v4 → 4.15-beta.1 upgrade paths + rollback plans - NEW Part 27: Gotchas & FAQ — symptom-indexed troubleshooting - Deprecate Part 16 (custom autoDream) with clear banner pointing to Part 22 - Revamp README: badges, Who-This-Is-For, Start-Here, numbers table, themed navigation, mermaid arch diagram, theme-grouped TOC - Add CONTRIBUTING.md + issue templates (correction/gap/version-bump) + PR template - Add GitHub Action for markdownlint + lychee internal link check - Add .markdownlint.jsonc config tuned for a prose guide - Fix MD001 heading-increment in Part 10 - Fix broken link in Part 16 footer Co-Authored-By: Rob <onerobby@gmail.com> * Fix lychee-detected broken links in CI - Correct relative path in .github/ISSUE_TEMPLATE/version-bump.md (../../ not ../) - Drop broken file link to scripts/qwen_embed_server_v3.py in Part 10; describe as local install path - Add lychee.toml to exclude templates/ (placeholder user-vault paths) and ephemeral URL patterns Co-Authored-By: Rob <onerobby@gmail.com> * Fix broken README anchor in Part 24 & Part 25 cross-links Devin Review flagged: #part-5-orchestration → #part-5-orchestration-stop-doing-everything-yourself (GitHub renders full heading text as the slug; the truncated form silently lands at README top) Co-Authored-By: Rob <onerobby@gmail.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2 parents a25f184 + 7392e83 commit 343e83c

16 files changed

Lines changed: 930 additions & 43 deletions

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Question about OpenClaw itself (not the guide)
4+
url: https://github.com/openclaw/openclaw/issues
5+
about: For OpenClaw bugs, feature requests, or usage questions, open an issue on the OpenClaw repo instead.
6+
- name: Read the FAQ first
7+
url: https://github.com/OnlyTerp/openclaw-optimization-guide/blob/master/part27-gotchas-and-faq.md
8+
about: Most questions are already answered in Part 27 — Gotchas & FAQ.

‎.github/ISSUE_TEMPLATE/correction.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
name: Correction
3+
about: Something in the guide is wrong or outdated
4+
title: "[Correction] <part number and short description>"
5+
labels: correction
6+
---
7+
8+
**Which part?**
9+
Part N — ...
10+
11+
**What's wrong?**
12+
Quote the current text, or link to the specific line.
13+
14+
**What's the correct version?**
15+
What should it say instead?
16+
17+
**Source**
18+
Release notes, config schema, your own testing — whatever backs up the correction.
19+
20+
**OpenClaw version you're on**
21+
e.g. `2026.4.15-beta.1`

‎.github/ISSUE_TEMPLATE/gap.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
name: Gap
3+
about: The guide doesn't cover something that it should
4+
title: "[Gap] <topic>"
5+
labels: gap
6+
---
7+
8+
**What's missing?**
9+
One-sentence summary.
10+
11+
**Where does it belong?**
12+
Existing part to expand, or case for a new part?
13+
14+
**Why does it matter?**
15+
Who hits this and when? Rough shape of the problem.
16+
17+
**What do you already know about it?**
18+
Any existing notes, release info, or external write-ups you can share.

‎.github/ISSUE_TEMPLATE/version-bump.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
name: Version bump
3+
about: A new OpenClaw version shipped and the guide needs updating
4+
title: "[Version] <version number>"
5+
labels: version-bump
6+
---
7+
8+
**New OpenClaw version**
9+
e.g. `2026.5.0`
10+
11+
**Release notes**
12+
Link.
13+
14+
**Material changes that affect the guide**
15+
Bullet list. For each item, call out:
16+
- Which existing part needs updating (or "new part needed")
17+
- Whether it's breaking, deprecating, or additive
18+
- Anything the migration guide ([Part 26](../../part26-migration-guide.md)) needs to capture
19+
20+
**Volunteering to send the PR?**
21+
Yes/no. If yes, link the branch when you push it.

‎.github/pull_request_template.md‎

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

‎.github/workflows/docs-quality.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: docs-quality
2+
3+
on:
4+
push:
5+
branches: [master, main]
6+
pull_request:
7+
branches: [master, main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
markdownlint:
14+
name: markdownlint
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: DavidAnson/markdownlint-cli2-action@v19
19+
with:
20+
globs: "**/*.md"
21+
22+
linkcheck:
23+
name: link check (internal only)
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
- name: Run lychee
28+
uses: lycheeverse/lychee-action@v2
29+
with:
30+
args: >-
31+
--offline
32+
--no-progress
33+
--verbose
34+
'**/*.md'
35+
fail: true

‎.markdownlint.jsonc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
{
2+
// Config for markdownlint-cli2 — prose guide, permissive by design.
3+
// We keep rules that catch real correctness problems (heading levels, etc.)
4+
// and disable the ones that fight an opinionated writing style.
5+
"default": true,
6+
7+
// --- Style rules we deliberately turn off ---
8+
9+
// Line length — prose, hard-wrap hurts readability.
10+
"MD013": false,
11+
12+
// Inline HTML is fine (we use <sub>, <br/>, details/summary).
13+
"MD033": false,
14+
15+
// Bare URLs in tables / inline.
16+
"MD034": false,
17+
18+
// Emphasis-as-heading is part of the voice.
19+
"MD036": false,
20+
21+
// Trailing punctuation in headings is allowed ("Stop Being Slow.").
22+
"MD026": false,
23+
24+
// Don't require language on every fence — ASCII art blocks.
25+
"MD040": false,
26+
27+
// Allow blanks inside block quotes for multi-paragraph callouts.
28+
"MD028": false,
29+
30+
// Allow duplicate headings at different levels / siblings.
31+
"MD024": { "siblings_only": true },
32+
33+
// First line doesn't have to be a top-level heading (badges first).
34+
"MD041": false,
35+
36+
// Table column style — allow mixed alignment; we use it deliberately.
37+
"MD060": false,
38+
39+
// --- Blank-line rules: relaxed so templates and nested tables don't break CI ---
40+
41+
// Blank line around headings / fences / tables.
42+
"MD022": false,
43+
"MD031": false,
44+
"MD032": false,
45+
"MD058": false,
46+
47+
// Multiple consecutive blank lines — keep tight, but 2 is fine in block quotes.
48+
"MD012": { "maximum": 2 },
49+
50+
// Trailing newline at EOF — nice-to-have, not worth failing CI on legacy files.
51+
"MD047": false,
52+
53+
// Anchor fragment validation disagrees with GitHub's slug behaviour for
54+
// headings with emojis and colons. We link-check with lychee instead.
55+
"MD051": false
56+
}

‎CONTRIBUTING.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Contributing
2+
3+
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.
4+
5+
## What to Contribute
6+
7+
**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.
8+
9+
**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:
10+
11+
1. Updates the version line at the top of the README.
12+
2. Adds a "What changed in this release" bullet in the README hero.
13+
3. Updates the specific part(s) that are affected.
14+
4. Adds a row to the migration guide ([Part 26](./part26-migration-guide.md)) if the change is non-trivial.
15+
16+
**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.
17+
18+
**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.
19+
20+
**Diagrams.** Mermaid is cheap and renders natively on GitHub. If a section would benefit from a diagram, add one.
21+
22+
## What Not to Contribute
23+
24+
- **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.
25+
- **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).
26+
- **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.
27+
- **Emoji-heavy rewrites.** The guide uses emoji sparingly for navigation and section markers. Keep prose clean.
28+
29+
## Style
30+
31+
- **Terse > wordy.** Shorter paragraphs, concrete examples, no preambles.
32+
- **Tables for comparisons**, bulleted lists for steps, fenced code blocks for commands.
33+
- **Links > inline duplication.** If something is already covered in another part, link to it.
34+
- **Cross-link new parts** from the relevant existing parts and the README TOC.
35+
- **Consistent heading levels.** Each part starts with `# Part N: Title`, major sections are `##`, subsections `###`.
36+
- **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).
37+
38+
## Running The Quality Checks Locally
39+
40+
```bash
41+
# markdownlint-cli2
42+
npm install -g markdownlint-cli2
43+
markdownlint-cli2 "**/*.md" "#node_modules"
44+
45+
# lychee (link checker)
46+
# macOS/Linux: cargo install lychee OR brew install lychee
47+
lychee --offline --no-progress "**/*.md"
48+
# drop --offline to also check external links (slower)
49+
```
50+
51+
CI runs both on every PR via [.github/workflows/docs-quality.yml](./.github/workflows/docs-quality.yml). PRs must pass both checks before merging.
52+
53+
## Opening an Issue
54+
55+
Use [the issue templates](./.github/ISSUE_TEMPLATE/). Summary:
56+
57+
- **Correction** — "This claim in Part X is wrong/outdated."
58+
- **Gap** — "Part X doesn't cover Y, which matters because Z."
59+
- **Version bump** — "OpenClaw vN shipped; here's what needs updating."
60+
- **Question** — before opening, read [Part 27 — Gotchas & FAQ](./part27-gotchas-and-faq.md) first.
61+
62+
## License
63+
64+
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.
65+
66+
## A Note On Tone
67+
68+
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.

0 commit comments

Comments
 (0)