docs: split documentation into README / docs / dev layers

[gitcoder89431]

Refs #95. Documentation only; no runtime or plugin behavior changes.

What changed

Three layers, with progressive disclosure:

README.md                  new user: what it is, how it looks, install, where to go next
docs/README.md             manual index
  INSTALLATION.md          install, dry-run, interrupted-run recovery, update, doctor/repair,
                           disable, back to stock, uninstall, requirements
  CUSTOMIZATION.md         docked/floating bar, bar style, Hyprland window look
  PLUGINS.md               plugin inventory, Kanban, Shelf
  LAUNCHER.md KEYBINDS.md CONTROL.md   (unchanged, now cross-linked from the index)
dev/README.md + AGENTS.md  layout, how Ruixen plugs into Omarchy, dev scripts, workflow, testing

• The README now leads with Ruixen ("an integrated desktop suite for Omarchy"), not "Ruixen Shell", and says plainly it is not a replacement shell. Repo name, plugin ids, paths and IPC targets are untouched.
• Long material was moved, not rewritten: sections were copied by line range into the new files. I diffed every old README line against the new set; the only lines gone are the old gallery, the old doc-list blurbs (replaced by docs/README.md), and the stale items below.
• AGENTS.md stays at the root; it now also points at dev/README.md.

Stale facts fixed while moving

• ruixen.frame-widget no longer exists (the frame is part of ruixen.bar); removed from the inventory and from the omarchy plugin disable example (now ruixen.shelf).
• --with-launcher-keybind was documented as adding two keys; it adds four (SUPER+R, SUPER+SHIFT+R, SUPER+CTRL+SPACE, SUPER+D).
• The inventory now lists ruixen.shelf, ruixen.wallpaper, ruixen.cava, the workspaces/power/capture-status widgets, Clipboard History and the theme browser, which the old list missed.
• The doctor paragraph mentions the new clipboard-capture section.

Tests

• New tests/docs-links.sh (in run-all.sh): resolves every relative link, image src and #heading anchor in the README, docs/, dev/README.md, AGENTS.md and COMPATIBILITY.md, so a missing screenshot fails CI instead of rendering as a broken image. It caught four links I broke by moving text into docs/, which are fixed.
• tests/bar-style-mode.sh now checks the fullbar line in docs/CUSTOMIZATION.md (it moved).
• ./tests/run-all.sh green.

Media

Wired into the README from the maintainer's new preview/ files: hero = preview_0/1/2.png (one desktop in three themes); bar and notch = preview_float, preview_dock, preview_notch, plus preview_kanban; launcher = preview_launcher_files, preview_clipboard, preview_themes, preview_launcher (the palette); settings = preview_settings.

• Shelf: preview/preview_shelf.webp (or a PNG), a short loop: drag a file over the collapsed notch, the Shelf opens, drop it, the card appears. The Shelf section stays text-only until this lands.
• Image size (optional, not blocking): the new PNGs total about 10 MB, mostly the 1920x1080 ones (preview_notch 2.3 MB, preview_dock 1.6 MB, the three heroes about 1.3 MB each). Lossless recompression only saves about 5%; a WebP at quality 90 is roughly a tenth of the size. Not converted without the maintainer's say-so.
• Privacy glance (optional): preview_settings.png shows dev@NucBoxG5, preview_clipboard.png shows /home/dev/... and /tmp/shelfdemo paths, preview_launcher_files.png shows ~/REPOS/PLUGINS/.... Fine if intended.

🤖 Generated with Claude Code

https://claude.ai/code/session_0146fvp9wxQkTMN71NeS4JRu