From dfe31f1291f573741749c278148e23b648a7648e Mon Sep 17 00:00:00 2001
From: Christian-Manuel Butzke <chris@fruwe.com>
Date: Thu, 18 Jun 2026 16:09:43 +0900
Subject: [PATCH] docs: refresh README for v4.2/v4.3 (recommended-source flow;
 AI/dev moved)

---
 README.md | 65 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 36 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 822db87..8cb5a64 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,53 @@
 # eve-packages-linux
 
-First-party **eve** packages for Linux instances — everything that runs **after**
-SSH is reachable: remote desktops (VNC, ThinLinc, Waypipe), full desktop
-environments (GNOME / KDE / XFCE, plus headless variants), dev toolchains
-(`dev-toolchain`, `docker`, `vscode`), and AI coding tools (`claude`, `codex-cli`,
-`goose`, `hermes`, `opencode`).
-
-These 18 packages are the **ubuntu-only** set extracted out of the eve core repo
-in v4.0 Phase 3. Each declares `supports: {os_families: [ubuntu]}` (several also
-constrain `arches`), and eve never offers a package to an incompatible instance.
-"Linux" is an organizational grouping, **not** a compatibility claim: the precise
-distribution/version support lives in each manifest's `supports` + `install`
-block. (The dual-OS packages — discord, nomachine, rdp, rustdesk, splashtop,
-steam, sunshine, xpra — are split linux/windows separately and live elsewhere.)
-
-## Consumption
-
-Pull this catalog into an eve checkout alongside the core:
-
-```
-eve pull github.com/fruwehq/eve-packages-linux
+First-party **eve** packages for Linux (Ubuntu) instances — content that runs
+**after** the instance is manageable over SSH: remote desktops & access
+(`vnc`, `rdp`, `rustdesk`, `nomachine`, `splashtop`, `thinlinc`, `waypipe`,
+`xpra`, `sunshine`), full desktop environments (GNOME / KDE / XFCE, plus headless
+variants), and `docker`, `steam`, `discord`, `macos-desktop-theme`.
+
+Each package declares `supports: {os_families: [ubuntu]}` (several also constrain
+`arches`); eve never offers a package to an incompatible instance. "Linux" is an
+organizational grouping, **not** a compatibility claim — the precise support
+lives in each manifest's `supports` + `install` block. The Windows halves of the
+dual-OS tools (discord, nomachine, rdp, rustdesk, splashtop, steam, sunshine,
+xpra) live in
+[eve-packages-windows](https://github.com/fruwehq/eve-packages-windows).
+
+> **AI agents and developer tooling** (`claude`, `codex-cli`, `goose`, `hermes`,
+> `opencode`, `dev-toolchain`, `vscode`) moved to
+> **[eve-plugins-ai](https://github.com/fruwehq/eve-plugins-ai)** (v4.2).
+
+## Use it
+
+This is an external plugin source — nothing is bundled in eve core:
+
+```sh
+eve plugin source add --recommended eve-packages-linux
+eve pull
 ```
 
-`eve pull` drops each `<id>/` package under `plugins/packages/` so eve discovers
-it like any built-in. You do **not** clone this repo manually or vendor anything.
+(or add it from the eve TUI's plugin screen — press `g`). It's in eve's
+recommended-source catalog. Pair it with
+[eve-providers](https://github.com/fruwehq/eve-providers) (providers + OS
+identity), and optionally eve-plugins-ai.
 
 ## How packages run
 
 Every package is self-contained CONTENT — a manifest (`eve-plugin.yaml`) plus a
-`commands/` and `provision/` tree. None of them ship their own entrypoint:
-every command's `exec: scripts/package-plugin` resolves to the **core generic
-dispatcher** at the consuming eve checkout's repo root
-(`scripts/package-plugin`, which stays in eve). So a package is pure data — it
-extracts verbatim and runs against whatever eve version you've checked out.
+`commands/` and `provision/` tree. None ship their own entrypoint: each command's
+`exec: scripts/package-plugin` resolves to the **core generic dispatcher** at the
+consuming eve checkout (`scripts/package-plugin`, which stays in eve). A package
+is pure data — it materializes verbatim and runs against whatever eve version you
+have. See [package-anatomy](https://github.com/fruwehq/eve/blob/main/docs/package-anatomy.md).
 
 ## Layout
 
 ```
 <id>/
   eve-plugin.yaml        # manifest: supports, install steps, command execs
-  commands/ubuntu/       # per-OS command shims (status, down)
-  provision/ubuntu/      # per-OS provisioning scripts run by the dispatcher
+  commands/ubuntu/       # host-side command shims (status, down)
+  provision/ubuntu/      # guest-side provisioning scripts run by the dispatcher
 ```
 
 ## Conformance