docs(readme): rewrite as a beginner landing page, and cut v2.0.0

[blyatiful1]

The README was 500 lines of prose that opened with three ways to rescue a broken desktop. Someone who has never used Linux or GitHub met a wall of text and a rescue plan before they learned what the app was.

I looked at how projects aimed at people with little Linux/GitHub experience write their front page — Pi-hole, Extension Manager, Warehouse, Linutil, ML4W, Bluefin, WhiteSur, ProtonUp-Qt — and the patterns they share: one-line value proposition and a picture first; badges; short scannable feature lists instead of paragraphs; the simplest install path first with alternatives collapsed; progressive disclosure via <details>; "recommended" labels; a visible place to ask for help; uninstall documented next to install.

What changed

• Hero first. Title, one-line description, four badges, the Home screenshot, then a Ctrl+Z / gtheme rescue tip callout and a one-line table of contents.
• "What is it?" now includes a "this was written for you if" list and an explicit "you do not need an account, an admin password, or any knowledge of Linux or GitHub".
• "What it can change" is a ten-row scannable table replacing several screens of prose.
• "Why it's safe to try" is its own section near the top — it is the reason to try the app at all — ending with the same honest limit about third-party add-ons.
• Install is five numbered steps under "The easy way (recommended)". The requirements table, the Arch route, the developer route, and the "why there is no curl | bash" explanation are folded into <details>.
• New "Your first five minutes" — apply a Look, look at it, press Ctrl+Z.
• The fifteen-page tour keeps every screenshot and every word, grouped into four collapsible sections instead of one long scroll.
• Questions people ask are collapsible, plus a new one: "Do I need to know anything about Linux, the terminal, or GitHub?"
• New "Getting help" — Discussions, issues, glossary, start-here, security.
• Uninstall documents ./install.sh --uninstall rather than asking people to delete files by hand.
• Cross-document links in GLOSSARY.md and docs/start-here.md follow the renamed anchors.

No claim changed: every fact, number, guarantee and honest limit is the one that was already there.

Release prep for v2.0.0

• __version__ drops the .dev0.
• The metainfo release becomes type="stable", dated today.
• The changelog entry is no longer marked unreleased, and gained a Documentation section.

Pushing the v2.0.0 tag is what runs .github/workflows/release.yml, builds the wheel and publishes the GitHub release — that is the one remaining step after this merges.

Checklist

• python -m pytest -q passes — not run here: this container has no PyGObject or pytest, so CI is the first place the suite runs. The changes are documentation plus a version string, a metainfo date and the changelog.
• python -m gtheme validate all passes — same reason.
• For theme PRs: no themes changed.

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: de231ca5-65e2-4cd8-a955-8e798e86beae

---

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.}

[blyatiful1]

Both checks are red here, and neither failure belongs to this PR: main (b9e60c9, this PR's merge base) fails identically, and this diff is README/CHANGELOG/GLOSSARY/start-here prose plus a version string, a metainfo date and a changelog heading. No fix PR exists yet to port in, so I am not pushing anything for these — a docs PR is the wrong place to reshape CI, and the re-run would be spent confirming a deterministic failure the base branch already reproduces.

ruff + unit tests — ruff passes; pytest dies during collection:

tests/unit/test_applyrunner.py:22: from gtheme.ui.applyrunner import ApplyRunner
tests/unit/test_window.py:33:     from gi.repository import Adw, Gtk
E   ModuleNotFoundError: No module named 'gi'
Interrupted: 2 errors during collection — 22 skipped, 77 deselected, 2 errors

Both modules carry pytestmark = pytest.mark.gtk, but a marker deselects after import, so -m "not gtk" never gets the chance. The reason gi is missing at all is the venv: the job apt-installs python3-gi, which lands in /usr/lib/python3/dist-packages for the runner's own /usr/bin/python3, then builds the venv from actions/setup-python's interpreter — whose --system-site-packages points at the tool-cache tree, not dist-packages. The 22 skips in that same line are the Gio-backed core tests skipping themselves for the same reason, so the tier is proving much less than it looks.

Proposed patch (untested — I have no runner to prove it on):

-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
...
       - name: Install gtheme
         run: |
-          python -m venv --system-site-packages .venv
+          /usr/bin/python3 -m venv --system-site-packages .venv

ubuntu-latest's own python3 is 3.12, which satisfies requires-python. Worth adding a collect_ignore guard in tests/conftest.py for when gi is genuinely absent, so a missing binding degrades to skips instead of a collection abort.

GTK/libadwaita tests (Arch container) — the same 10 failures on this head and on main, all about what a bare archlinux:latest container is missing rather than about any code:

• ValueError: Namespace GnomeDesktop not available ×3 — gnome-desktop is not in the pacman -S list.
• BackendError: schema 'org.gnome.shell' / 'org.gnome.mutter' / 'org.gnome.settings-daemon.plugins.color' is not installed ×3 — no gsettings-desktop-schemas / mutter / gnome-shell schemas in the container.
• AssertionError: the real machine's catalogue must offer at least one picture — no gnome-backgrounds.
• AttributeError: 'ActionRow' object has no attribute 'set_value' and two reset-button assertions — these look like real API/behaviour questions rather than packaging, and want a proper look.

That job needs a decision about how much of a GNOME install the container should carry, which is more than a README PR should be making.

Both of these also block the v2.0.0 release: release.yml runs the same pytest -q -m "not gtk and not sandbox" in its "Test before shipping" step, on the same setup-python venv, so tagging v2.0.0 today fails before it builds the wheel. Happy to open a dedicated CI PR for the first one — say the word.

---

Generated by Claude Code