Give the docs one home, one checker, and a tree that matches the site

[ewowi]

The documentation had the rules in one page, a second copy of them in two others, and no shape a reader could navigate. This branch gives the prose a single home, a checker that enforces it, and a folder tree that matches the published site.

350 files, but the reviewable part is small. 115 deletions and 103 renames account for most of it, which is why the diff is +3,200 / −14,460. Roughly 146,000 words removed.

The standards, and what enforces them

docs/contributing/documentation-standards.md is new: who reads a page, one tone of voice, the principles that bear on prose, then rules narrowing from the statement to the sentence to the word. coding-standards.md keeps pointers where its prose sections were, and gains one rule: prefer naming over commenting, with both sides cited.

Three things now hold it in place:

• Diátaxis, followed as written. Every page is a tutorial, how-to, reference or explanation, and the test for a page is the cell it sits in.
• Vale, seven rules as YAML under .vale/styles/projectMM/, replacing the hand-rolled checker's table. It runs on every PR and annotates errors on added lines.
• --strict on the docs build, in CI and at the commit gate. A dead link fails the build. It caught 251 during the restructure, each fixed.

The folder tree is the type

Pages sat flat at the site root while the folders that existed carried mixed meanings: reference/ held hardware pages while the nav's "Reference" section held two unrelated ones. Each page now lives in the folder naming its type, and the nav follows the tree:

docs/
  index.md · gettingstarted.md   entry only
  tutorials/ · how-to/ · explanation/ · reference/
  contributing/ · legal/         outside the grid
  moonmodules/ · work/ · friend-repos/

Nav labels stay reader-facing ("Understanding projectMM", not "Explanation") because the type is a writer's tool. Published URLs changed and are not redirected; the MIGRATING entry lists every move.

Folder landing pages renamed README.md → index.md, the MkDocs convention. Source-directory READMEs (mooncloud/, mooninstaller/, moonlive/) keep their name, which is what every code host renders.

The architecture is nine pages

architecture.md was one 15,000-word page. It is now nine under explanation/architecture/, one per Moon part, each opening with what the part is and how the page is laid out, with Mermaid diagrams replacing the ASCII ones. MoonLight's pipeline diagram draws Layouts as shared geometry read at prepare time rather than a pipeline stage, which is what the code does.

CLAUDE.md drops 5,143 → 3,130 words, with the gate tables redrawn as Mermaid flowcharts carrying role emoji. The README drops 3,486 → 2,008 and gains a section per Moon part, each linking both its architecture page and its user docs.

What was deleted, and how it was checked

The ADR folder, all 17 records. Each decision was already stated as current behavior elsewhere, so the ADR was the copy left behind. Two rules had no other home and moved into the architecture pages.

91 shipped plans, whose content the code, the tests and the merged PR carry. The check was inverted rather than trusted: does any sentence's vocabulary appear nowhere else in the repo, across all PR bodies plus every doc and source file? 18 sentences survived out of 131,562 words, and all 18 named code that no longer exists.

docs/history/ retired, its lessons and inventories moved under docs/work/past/.

Reviewer findings

The Reviewer ran over the full branch diff. Three fixed, two left as decisions:

• repo_health.py read a path that no longer existed. Guarded by if exists(), so it degraded to lessons_lines: 0 rather than erroring, and that zero was already committed to the KPI file. Fixed; it reads 518.
• Fourteen files linked ](README.md) for a sibling renamed to index.md. The out-of-docs hook matched the bare string and rewrote them to projectMM's root README, so they resolved to the wrong document with no error and a green build.
• ~20 stale doc paths in src/, moondeck/, CMakeLists.txt, mkdocs.yml and esp32/, left by the earlier docs/history/ and docs/backlog/ retirements.
• Open: whether work/future/ should inherit the old docs/backlog/ prose exemption, and whether two MoonLive module pages should be on the nav.

Verification

Strict docs build 0 warnings. Prose clean over the branch diff. check_specs 126/126, taglines agree, platform boundary and hot-path pass. Desktop build zero warnings, 1,938 unit cases / 123,412 assertions, 24 scenarios, host tests 170 Python + JS. GCC skipped (CI green), ESP32 and Improv skipped (no board, and the branch does not touch that path).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ab20f4a7-b776-4cd2-81df-6d488cb4ef34

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[MoonModules]

@coderabbitai, can you review the modified (38) and added (5) file of commit 5e3fff7

No need to review deleted (112) or moved files (77)

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

commit="5e3fff795af41e9ad016166b83e35d1710d76f27"

echo "== Commit metadata =="
git show -s --format='commit=%H%nparents=%P%nsubject=%s' "$commit"

echo
echo "== Changed files by status =="
git diff-tree --no-commit-id --name-status -r -M -C "$commit"

echo
echo "== Requested files: added and modified =="
git diff-tree --no-commit-id --name-status -r -M -C "$commit" \
  | awk '$1 == "A" || $1 == "M" {print}'

echo
echo "== Requested-files diff stat =="
parent="$(git rev-parse "${commit}^")"
git diff --stat "$parent" "$commit" -- \
  $(git diff-tree --no-commit-id --name-status -r -M -C "$commit" \
    | awk '$1 == "A" || $1 == "M" {print $2}')

Length of output: 26720

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

commit="5e3fff795af41e9ad016166b83e35d1710d76f27"
parent="$(git rev-parse "${commit}^")"
mapfile -t requested < <(
  git diff-tree --no-commit-id --name-status -r -M -C "$commit" |
  awk '$1 == "A" || $1 == "M" {print $2}'
)

echo "== Full diffs for the 43 requested files =="
git diff --no-ext-diff --unified=35 "$parent" "$commit" -- "${requested[@]}"

echo
echo "== Current non-deleted references to legacy documentation paths =="
rg -n -i -C2 \
  '(docs/)?backlog/|docs/history/plans/|/backlog/|/history/plans/' \
  -g '!docs/backlog/**' -g '!docs/history/plans/**' -g '!**/.git/**' . || true

echo
echo "== Changed validation-script context =="
for file in moondeck/check/check_prose.py moondeck/check/repo_health.py moondeck/rename/rename_to_moonlight.py; do
  echo "--- $file ---"
  ast-grep outline "$file" --items all
done

echo
echo "== MkDocs navigation and work-folder documentation =="
sed -n '/^nav:/,/^[^[:space:]-].*:/p' mkdocs.yml
for file in docs/work/future/README.md docs/work/present/README.md docs/work/past/README.md docs/work/past/plans/README.md; do
  echo "--- $file ---"
  cat -n "$file"
done

echo
echo "== Markdown links in requested documentation that resolve to missing local files =="
python3 - "${requested[@]}" <<'PY'
import pathlib, re, sys
files = [pathlib.Path(p) for p in sys.argv[1:] if p.endswith(".md")]
link = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
for path in files:
    text = path.read_text(encoding="utf-8")
    for target in link.findall(text):
        target = target.strip("<>")
        if target.startswith(("#", "http://", "https://", "mailto:", "tel:")):
            continue
        target = target.split("#", 1)[0].split("?", 1)[0]
        if not target:
            continue
        resolved = (path.parent / target).resolve()
        if not resolved.exists():
            print(f"{path}: missing target {target}")
PY

Length of output: 2338

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

commit="5e3fff795af41e9ad016166b83e35d1710d76f27"
parent="$(git rev-parse "${commit}^")"
requested_file="$(mktemp)"
trap 'rm -f "$requested_file"' EXIT

git diff-tree --no-commit-id --name-status -r -M -C "$commit" |
  awk '$1 == "A" || $1 == "M" {print $2}' > "$requested_file"

echo "== Full diffs for the 43 requested files =="
git diff --no-ext-diff --unified=35 "$parent" "$commit" -- $(cat "$requested_file")

echo
echo "== Current non-deleted references to legacy documentation paths =="
rg -n -i -C2 \
  '(docs/)?backlog/|docs/history/plans/|/backlog/|/history/plans/' \
  -g '!docs/backlog/**' -g '!docs/history/plans/**' -g '!**/.git/**' . || true

echo
echo "== Changed validation-script context =="
for file in moondeck/check/check_prose.py moondeck/check/repo_health.py moondeck/rename/rename_to_moonlight.py; do
  echo "--- $file ---"
  ast-grep outline "$file" --items all
done

echo
echo "== MkDocs navigation and work-folder documentation =="
sed -n '/^nav:/,/^[^[:space:]-].*:/p' mkdocs.yml
for file in docs/work/future/README.md docs/work/present/README.md docs/work/past/README.md docs/work/past/plans/README.md; do
  echo "--- $file ---"
  cat -n "$file"
done

echo
echo "== Markdown links in requested documentation that resolve to missing local files =="
python3 - "$requested_file" <<'PY'
import pathlib, re, sys
files = [pathlib.Path(p) for p in pathlib.Path(sys.argv[1]).read_text().splitlines() if p.endswith(".md")]
link = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
for path in files:
    for target in link.findall(path.read_text(encoding="utf-8")):
        target = target.strip("<>")
        if target.startswith(("#", "http://", "https://", "mailto:", "tel:")):
            continue
        target = target.split("#", 1)[0].split("?", 1)[0]
        if target and not (path.parent / target).exists():
            print(f"{path}: missing target {target}")
PY

Length of output: 192109

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

commit="5e3fff795af41e9ad016166b83e35d1710d76f27"
parent="$(git rev-parse "${commit}^")"

echo "== Compact diffs: documentation and configuration =="
git diff --no-ext-diff --unified=5 "$parent" "$commit" -- \
  CLAUDE.md \
  docs/MIGRATING.md docs/architecture.md docs/building.md docs/coding-standards.md \
  docs/documentation-standards.md docs/history/README.md docs/history/lessons.md \
  docs/history/shift-register-driver-analysis.md docs/moonmodules/core/system.md \
  docs/moonmodules/light/MoonLiveEffect.md docs/moonmodules/light/drivers.md \
  docs/moonmodules/light/effects.md docs/moonmodules/light/layouts.md \
  docs/moonmodules/light/modifiers.md docs/moonmodules/light/power-functions.md \
  docs/performance.md docs/reference/control-surfaces.md docs/reference/gpio-usage.md \
  docs/reference/light-fixtures.md docs/reference/mhc-wled-esp32-p4-shield.md \
  docs/testing.md docs/usecases/home-automation.md \
  docs/work/future/README.md docs/work/present/README.md docs/work/past/README.md \
  docs/work/past/plans/README.md mkdocs.yml

echo
echo "== Compact diffs: scripts, source, and tests =="
git diff --no-ext-diff --unified=5 "$parent" "$commit" -- \
  moondeck/check/check_prose.py moondeck/check/repo_health.py \
  moondeck/rename/rename_to_moonlight.py src/core/DevicePlugin.h \
  src/core/DevicesModule.h src/core/FilesystemModule.cpp \
  src/light/drivers/MoonLedDriver.h src/platform/desktop/platform_desktop.cpp \
  src/platform/esp32/platform_esp32.cpp src/platform/esp32/platform_esp32_i80.cpp \
  src/platform/esp32/platform_esp32_moon_i80.cpp src/platform/platform.h \
  test/unit/core/unit_InstallationId.cpp test/unit/light/unit_Effects_gridsweep.cpp \
  test/unit/light/unit_MoonLedDriver.cpp

echo
echo "== Added-line prose-rule violations under the updated checker =="
python3 - "$parent" <<'PY'
import re, subprocess, sys
base = sys.argv[1]
suffixes = (".h", ".hpp", ".c", ".cpp", ".inc", ".md", ".py", ".js", ".css", ".html", ".mle", ".mll", ".mlm")
exempt = (
    "docs/friend-repos/", "docs/work/past/", "docs/work/future/", "docs/metrics/",
    "docs/tests/", "docs/moonmodules/", "src/platform/desktop/vendor/", "src/ui/vendor/",
    "moondeck/check/check_prose.py", "docs/documentation-standards.md",
)
spelling = {
    "behaviour": "behavior", "colour": "color", "initialis": "initializ",
    "optimis": "optimiz", "recognis": "recogniz", "analyse": "analyze",
    "analysing": "analyzing", "materialis": "materializ", "normalis": "normaliz",
    "serialis": "serializ", "cancelled": "canceled", "modelling": "modeling",
    "labelled": "labeled", "centre": "center", "licence": "license", "defence": "defense",
}
diff = subprocess.run(["git", "diff", base, "--unified=0"], text=True, capture_output=True, check=True).stdout
path = None
for line in diff.splitlines():
    if line.startswith("+++ b/"):
        path = line[6:]
    elif line.startswith("+") and not line.startswith("+++") and path:
        text = line[1:]
        if path.endswith(suffixes) and not any(path == x or path.startswith(x) for x in exempt):
            issues = []
            if "\u2014" in text: issues.append("em-dash")
            lower = text.lower()
            issues += [f"{bad}->{good}" for bad, good in spelling.items() if bad in lower]
            if issues:
                print(f"{path}: {', '.join(issues)}: {text}")
PY

echo
echo "== Active legacy-path links in requested Markdown files =="
python3 - "$commit" <<'PY'
import pathlib, re, subprocess, sys, urllib.parse
commit = sys.argv[1]
raw = subprocess.run(
    ["git", "diff-tree", "--no-commit-id", "--name-status", "-r", "-M", "-C", commit],
    text=True, capture_output=True, check=True).stdout
files = [line.split("\t", 1)[1] for line in raw.splitlines()
         if line.startswith(("A\t", "M\t")) and line.endswith(".md")]
link = re.compile(r'(?<!!)\[[^\]]+\]\(([^)\s]+)')
legacy = re.compile(r'(?:^|/)(?:docs/)?(?:backlog|history/plans)(?:/|$)')
for name in files:
    path = pathlib.Path(name)
    for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        for target in link.findall(line):
            decoded = urllib.parse.unquote(target.strip("<>").split("#", 1)[0].split("?", 1)[0])
            if legacy.search(decoded):
                print(f"{name}:{lineno}: {target}")
PY

Length of output: 203900

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

commit="5e3fff795af41e9ad016166b83e35d1710d76f27"

echo "== CLAUDE.md documentation inventory at the reviewed commit =="
git show "$commit:CLAUDE.md" | nl -ba | sed -n '249,271p'

echo
echo "== History plan-archive statement at the reviewed commit =="
git show "$commit:docs/history/README.md" | nl -ba | sed -n '14,27p'

echo
echo "== Retained shipped plan files at the reviewed commit =="
git ls-tree -r --name-only "$commit" -- docs/work/past/plans \
  | awk '$0 !~ /\/README\.md$/ {count++; print} END {print "COUNT=" count}'

Length of output: 6305

---

@MoonModules I reviewed only the 38 modified files and 5 added files in commit 5e3fff795af41e9ad016166b83e35d1710d76f27.

I found two issues:

1. CLAUDE.md Lines 259-260 still link to backlog/index.html and adr/index.html. This commit removes both documentation locations. Replace these entries with the new work/future location and remove or replace the ADR entry. Otherwise, the published documentation inventory contains dead links.

2. docs/history/README.md Line 23 says plans/ holds 89 plans. The new docs/work/past/plans/ directory contains 18 retained plan files, and docs/work/past/README.md also states 18. Update the history index to match the retained archive.

The added-line prose check reported no violations.

You are interacting with an AI system.