dsh-dream-skin 0.2.5 → 0.4.0

package/README.de.md

@@ -0,0 +1,353 @@
+<p align="center">
+  <a href="./README.md">中文</a> · <a href="./README.en.md">English</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.es.md">Español</a> · <a href="./README.fr.md">Français</a> · <strong>Deutsch</strong> · <a href="./README.ru.md">Русский</a>
+</p>
+
+<div align="center">
+
+# dsh-dream-skin 🔮
+
+**Gib DeepSeek Harness ein Gesicht, das zurückhaltend, klar und von feiner Textur ist.**
+
+Natives Skinning · Wallpaper · teilbare Theme-Pakete — eine elegante Umsetzung, vollständig auf DSHs offiziellem `--dsw-*`-Token-System basierend.
+
+> **TL;DR: Dein Code-Bereich darf leise sein.**
+
+| 🎨 8 Original-Themes | 🖼️ Wallpaper + diffuses Licht | 🎯 zurückhaltender Akzent | 📦 teilbare Theme-Pakete |
+|---|---|---|---|
+
+> 1-Zeilen-Installation · rein nativ (keine Injektion, keine Installer-Patches) · übersteht DSH-Updates
+
+✨ **Design Philosophy — [eine Aussage darüber, was „premium" bedeutet](./docs/design-philosophy.md)** · mit der iOS-/Linear-Ästhetik als Basis entsteht Premium aus der Präzision des Materials und der Zurückhaltung der Farben.
+
+[中文](./README.md) · [Änderungshistorie](./CHANGELOG.md) · [Projektnotizen](./docs/PROJECT.md) · [Design Philosophy](./docs/design-philosophy.md) · [Veröffentlichungsanleitung](./docs/publishing-to-npm.md)
+
+![npm version](https://img.shields.io/npm/v/dsh-dream-skin?color=4f83f2&label=npm)
+![license](https://img.shields.io/github/license/RevolutionLA/dsh-dream-skin?color=34d399)
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+![node](https://img.shields.io/badge/node-%3E%3D18-6d9af6)
+![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.6-blueviolet)
+![plugin type](https://img.shields.io/badge/plugin-dual--face%20(dsh.bundle%2Bdsh.client)-4f83f2)
+![ci](https://img.shields.io/github/actions/workflow/status/RevolutionLA/dsh-dream-skin/ci.yml?branch=main&label=CI&color=34d399)
+![code size](https://img.shields.io/github/languages/code-size/RevolutionLA/dsh-dream-skin?color=orange)
+
+</div>
+
+## ⚡ Installation mit einer Zeile
+
+**Kopiere diesen Satz in dein DSH und es installiert alles für dich:**
+
+> Bitte installiere das Skin-Plugin dsh-dream-skin (https://github.com/RevolutionLA/dsh-dream-skin, oder das npm-Paket `dsh-dream-skin`) und sage mir dann, wie ich DSH Web neu starten kann.
+
+Lieber die CLI? Ein Befehl:
+
+```sh
+dsh plugin --profile web add dsh-dream-skin && dsh web
+```
+
+> 🚀 **Jetzt auf npm!** Bei installiertem DSH fügst du es mit einem einzigen Befehl hinzu — kein Klonen nötig.
+
+> **Eine Hommage an [Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin).** Aber der Ansatz ist anders:
+> Codex injiziert CSS über CDP in den Renderer des Desktop-Clients, während DSH eine **token-gesteuerte Web-GUI** ist,
+> die „Third-Party-Plugins, die Themes registrieren“ erstklassig unterstützt. Dieses Plugin ist daher **rein nativ** —
+> keine Injektion, keine Binär-Patches, und es bricht nicht bei Client-Updates.
+>
+> **Kein offizielles Produkt.** Nur eine Möglichkeit, deinen DeepSeek-Harness-Arbeitsbereich aufzumöbeln.
+
+---
+
+## 📸 Screenshots
+
+> Echte Screenshots, keine Mockups. Links: DSH nach dem Anwenden eines Skins; rechts: der dedizierte Bereich **Theme / Appearance** in den Einstellungen.
+
+<p align="center">
+  <img src="docs/screenshots/preview.png" alt="DSH skin preview" width="46%"/>
+  &nbsp;&nbsp;
+  <img src="docs/screenshots/settings.png" alt="Theme section in settings" width="46%"/>
+</p>
+
+---
+
+## 🏆 Warum es einen Stern verdient (im Vergleich zu Alternativen)
+
+| Funktion | Unseres | Anderes DSH-Skinning | Codex-Dream-Skin (Desktop) |
+|------|:---:|:---:|:---:|
+| Native Token-Themes — keine Injektion, keine Installer-Patches | ✅ | ✅ | ❌ (CDP-Injektion) |
+| Eigenes Wallpaper + Deckkraft/Unschärfe | ✅ | teilweise | ✅ |
+| **Theme-Paket-Import/-Export + Share-Links** | ✅ | ❌ | ✅ (Zip-Pakete) |
+| **Akzent-Override pro Benutzer** | ✅ | ❌ | teilweise |
+| **Wallpaper 2.0 (URL / Verlauf / Vorschlag pro Skin / automatisches Abdunkeln)** | ✅ | ❌ | ✅ |
+| Lokale Paketbibliothek + Favoriten + Überrasche-mich | ✅ | ❌ | teilweise |
+| Validierung + Rollback | ✅ | teilweise | ✅ |
+| **Browser-Web-GUI, nativ plattformübergreifend** | ✅ | ✅ | ❌ (braucht Desktop-App) |
+
+## ✨ Funktionen
+
+| Funktion | Beschreibung |
+|------------|-------------|
+| 🎨 **8 enthaltene Presets (Mirage)** | Sofort umschalten unter **Settings → Theme / Appearance**, hell & dunkel |
+| 🖼️ **Eigenes Wallpaper** | Lokales Bild wählen (automatisch komprimiert ≤2 MB), **Deckkraft / Unschärfe** einstellen |
+| 🔤 **Undurchsichtige Innenflächen** | Karten, Eingabefelder und Nachrichtenblasen bleiben lesbar — niemals ausgewaschen |
+| ↩️ **Standard wiederherstellen** | Mit einem Klick zurück zur integrierten Darstellung von DSH (System folgen) |
+| 💾 **Lokale Speicherung** | Skin & Wallpaper werden in `localStorage` gespeichert und überstehen ein Neuladen |
+
+## 🚀 Erweiterte Funktionen (P0)
+
+Die Abgrenzung ist inspiriert von bestehenden DSH-Skin-Projekten und der Skin-UX von Codex:
+
+| Funktion | Beschreibung |
+|------------|-------------|
+| 📦 **Theme-Paket-Format + Import/Export** | Ein `*.dsh-theme.json`-Paket = Format-Marker + Version + Manifest (id/name/author/scheme/accent/tokens). Datei importieren, mit einem Klick anwenden und einen **Share-Link** kopieren (im URL-Hash kodiert) |
+| 🌈 **Akzent pro Benutzer** | Ein eigenes Marken-Akzent über den aktiven Skin legen (`overrideTokens`-Ebene, der Skin bleibt unangetastet): **12 Preset-Farbfelder mit einem Klick**, ein Farbwähler, **Zufallsfunktion** und Zurücksetzen |
+| 🖼️ **Wallpaper 2.0** | Lokales Bild / **Bild-URL** / **Verlaufs-Presets**, mit einem **pro Skin vorgeschlagenen Verlauf** und **automatischem Abdunkeln**; **Zuletzt verwendet** (bis zu 5), um mit einem Klick zurückzuschalten |
+| 🧩 **Lokale Paketbibliothek** | Deine importierten Theme-Pakete an einem Ort; **anwenden / favorisieren / entfernen** mit einem Klick (die 8 integrierten Skins liegen in der Skin-Reihe) |
+| ✅ **Klares Auswahl-Feedback** | Beim Wechseln der Skins wird die Markierung (Häkchen/Rahmen) **sofort** aktualisiert — keine veraltete weiße Markierungsbox |
+| 🎲 **Überrasche mich** | Zufällig zu einem Theme wechseln, das sich vom aktuellen unterscheidet |
+| ⭐ **Favoriten** | Markiere deine Lieblings-Skins mit einem Stern und wechsle schnell zwischen ihnen |
+| ✅ **Validierung + Rollback** | Der Paket-Import validiert Format / erforderliche Tokens / Farbzulässigkeit; Fehler oder Entfernungen fallen sicher zurück |
+
+## ⚡ Schnellstart (3 Schritte)
+
+```sh
+# 1. installieren
+dsh plugin --profile web add dsh-dream-skin
+# 2. neu starten
+dsh web
+# 3. Settings → Theme / Appearance öffnen → Skin wählen → fertig.
+```
+
+> Installiert das veröffentlichte npm-Paket — kein Klonen nötig. Wenn `dsh plugin add` einen Workspace-Fehler meldet, hänge `-w` an.
+
+## 🧩 Was für ein Plugin ist das
+
+**Ein standardmäßiges Dual-Face-`dsh-plugin` nach dem Prinzip „Alles ist ein Plugin“ — geladen und verwendet genau wie das offizielle Paket `ui-theme`.**
+
+Das Motto von DeepSeek Harness lautet *Alles ist ein Plugin*: Modelle, Tools, Sandboxes, Sessions, UI, sogar der Agent
+Loop selbst sind Plugins. `dsh-dream-skin` liefert Skinning als npm-Paket, das **isomorph zu den offiziellen
+UI-Paketen** ist:
+
+```text
+            ┌──────────── dsh-dream-skin (standard dsh-plugin / dual-face) ─────────────┐
+            │  dsh.bundle   → cordis.patch.yml inserts the dream-skin entry  (host half)│
+            │  dsh.client   → lib/client.js (browser bundle)                (browser half)│
+            └───────────────────────────────────────────────────────────────────────────┘
+```
+
+- **Installationsbefehl = der offizielle**: `dsh plugin --profile web add dsh-dream-skin`
+- **Nutzt offizielle Erweiterungspunkte**: `ctx.theme` (Themes registrieren), `ctx.theme.overrideTokens` (Override-Ebenen),
+  `ctx.slots` (UI in einen dedizierten Bereich **Settings → Theme / Appearance** einhängen).
+- **Manifest-Vertrag entspricht den offiziellen Paketen**: `dsh.bundle` + `dsh.client` + `exports["./client"]`.
+
+Mit anderen Worten: Du installierst kein Randskript — das ist ein Standard-Skin-Plugin im offiziellen Plugin-System
+von DSH.
+
+## 🖼️ Vorschau — die Mirage-Serie
+
+> Die Vorschauen unten werden aus den **echten Tokens** jedes Skins generiert — was du siehst, ist, was du bekommst.
+
+<table>
+  <tr>
+    <td align="center"><img src="docs/previews/abyss.svg" width="220" alt="abyss"/><br/><b>abyss</b></td>
+    <td align="center"><img src="docs/previews/aurora.svg" width="220" alt="aurora"/><br/><b>aurora</b></td>
+    <td align="center"><img src="docs/previews/nebula.svg" width="220" alt="nebula"/><br/><b>nebula</b></td>
+    <td align="center"><img src="docs/previews/ember.svg" width="220" alt="ember"/><br/><b>ember</b></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="docs/previews/midnight.svg" width="220" alt="midnight"/><br/><b>midnight</b></td>
+    <td align="center"><img src="docs/previews/ivory.svg" width="220" alt="ivory"/><br/><b>ivory</b></td>
+    <td align="center"><img src="docs/previews/mist.svg" width="220" alt="mist"/><br/><b>mist</b></td>
+    <td align="center"><img src="docs/previews/rose.svg" width="220" alt="rose"/><br/><b>rose</b></td>
+  </tr>
+</table>
+
+## 🎲 Die Presets
+
+| id | scheme | vibe |
+|------|--------|------|
+| `abyss` | 🕶️ dunkel | DeepSeek tiefblauer Abgrund (Anker) |
+| `aurora` | 🌌 dunkel | Aurora-Türkisgrün |
+| `nebula` | 🪐 dunkel | kosmisches Lila |
+| `ember` | 🔥 dunkel | warmes Glut-Orange |
+| `midnight` | 🌚 dunkel | reines Schwarz (OLED) |
+| `ivory` | 📜 hell | warmes Elfenbein / Papier |
+| `mist` | 🌫️ hell | kühler Blauer Nebel |
+| `rose` | 🌸 hell | Rosarot / Blush |
+
+## 📦 Installation
+
+Wähle eine der vier Optionen und starte dann **DSH Web neu** (die aktuelle Sitzung wird unterbrochen, aber DSH-Sitzungen
+werden auf der Festplatte gespeichert und nach dem Neustart wiederhergestellt).
+
+### Option A: Von npm (veröffentlicht, **empfohlen**)
+
+```sh
+dsh plugin --profile web add dsh-dream-skin
+```
+
+### Option B: Von GitHub (an einen verifizierten Commit gebunden)
+
+```sh
+dsh plugin --profile web add 'github:RevolutionLA/dsh-dream-skin#<40-char-commit>'
+```
+
+> Die Bindung an den Commit eines Releases bedeutet, dass neue Änderungen auf `main` deine installierte Kopie niemals stillschweigend verändern.
+
+### Option C: Vom Release-Tarball (offline / ohne git)
+
+Lade `dsh-dream-skin-<version>.tgz` von der Seite [Releases](https://github.com/RevolutionLA/dsh-dream-skin/releases)
+herunter (das Paket enthält das gebaute `lib/client.js`, sodass beim Installieren kein Prepare-Skript ausgeführt wird), dann:
+
+```sh
+dsh plugin --profile web add ./dsh-dream-skin-<version>.tgz
+```
+
+### Option D: Klonen und aus dem lokalen Pfad installieren (Entwicklung)
+
+```sh
+git clone https://github.com/RevolutionLA/dsh-dream-skin.git
+cd dsh-dream-skin
+dsh plugin --profile web add .
+```
+
+> `dsh plugin` verankert relative Pfade im Verzeichnis, **in dem du den Befehl ausführst**, und installiert eine
+> Link-Abhängigkeit, die auf deinen Klon zeigt: Quelle bearbeiten, speichern, DSH neu starten — keine Neuinstallation nötig.
+
+**Neu starten und überprüfen:**
+
+```sh
+dsh web
+dsh --profile web --dump-config | grep -A2 dream-skin   # a dream-skin loader entry should appear
+```
+
+Öffne **Settings → Theme / Appearance**, um die Reihen **Skins**, **Accent**, **Wallpaper** / **Advanced Wallpaper** und **Theme Packs** zu sehen.
+
+> Das Flag `-w` (Workspace) wird bei einem einfachen `add` benötigt, weil jedes Profil eine `pnpm-workspace.yaml` mitbringt; pnpm behandelt
+> das Profilverzeichnis als Workspace-Root, daher schlägt ein einfaches `add` mit `ERR_PNPM_ADDING_TO_ROOT` fehl. Wenn dein Profil bereits
+> den Workspace nutzt, musst du es nicht wiederholen.
+
+## 🔄 Aktualisieren / Deinstallieren
+
+**Auf die neueste Version aktualisieren** (wenn aus dem npm-Release installiert):
+
+```sh
+dsh plugin --profile web update dsh-dream-skin
+dsh web   # restart to pick it up
+```
+
+> Hängst du nach einem Update an einer alten Version fest? Die Minimum-Release-Alter-Richtlinie (Supply-Chain) von pnpm kann ein
+> frisch veröffentlichtes Release zurückhalten. Führe im Profilverzeichnis aus:
+> `pnpm add dsh-dream-skin@latest --config.minimumReleaseAge=0`, um es zu erzwingen.
+
+**Deinstallieren:**
+
+```sh
+dsh plugin --profile web remove dsh-dream-skin
+dsh web   # restores the official appearance
+```
+
+## 🧩 Kompatibilität
+
+| Punkt | Wert |
+|------|-------|
+| DeepSeek Harness (`dsh`) | `0.1.0-rc.6` (peerDependencies auf `^0.1.0-rc.6` festgelegt) |
+| Node.js | `>=18` |
+| Browser | modernes Chromium / WebKit (native CSS-Variablen & `matchMedia`) |
+
+> Beim Upgraden von DSH die `peerDependencies` in `package.json` entsprechend anheben.
+
+## ⚙️ So funktioniert es
+
+Das Theme-System von DSH ist token-basiert: Die Web-Shell liefert `--dsw-*`-Design-Tokens, und `ThemeRuntime` erlaubt
+Drittanbieter-Plugins, Themes zu registrieren, die die Alias-Ebene (`--dsw-alias-*`) überschreiben. Dieses Paket ist ein
+standardmäßiges Dual-Face-Plugin:
+
+```text
+                ┌─────────────────────────────────────────────┐
+                │          dsh-dream-skin (dual-face plugin)    │
+                ├────────────────────────────┬────────────────┤
+    Host half   │  lib/index.js              │  Browser half  │
+                │  cordis.patch.yml inserts  │  lib/client.js │
+                │  dream-skin loader entry   │  __ModuleLoader__│
+                └────────────────────────────┴────────────────┘
+                             │                         │
+                     profile tree loaded      /plugins/dsh-dream-skin/client.js
+                                                          │
+        ┌────────────────────────────────┬────────────────┐
+        │                                │                │
+   ctx.theme.register(8 skins)     ctx.theme.overrideTokens(wallpaper)   ctx.slots.inject('settings.section' + 'settings.dreamSkin.item')
+```
+
+- **Host-Hälfte** (`lib/index.js`) — eine `dsh.bundle`-Patch-Ebene, die den `dream-skin`-Loader-Eintrag einfügt; `apply` ist
+  ein No-op, genau wie bei den mitgelieferten `ui-*`-Paketen.
+- **Browser-Hälfte** (`lib/client.js`):
+  1. registriert die 8 Skins über `ctx.theme.register(...)`;
+  2. stellt den gespeicherten Skin wieder her und wendet ihn mit `ctx.theme.setTheme(...)` an;
+  3. rendert das Wallpaper als festen Hintergrund mit `z-index:-1` und stapelt `ctx.theme.overrideTokens(...)`, wodurch die
+     Hauptfläche (`--dsw-alias-bg-base`) und die Seitenleiste (`--dsw-specific-sidebar-fill`) durchscheinend werden;
+  4. lauscht auf `theme/change` und färbt den Wallpaper-Wash beim Wechsel von Skin / Schema neu ein;
+  5. registriert einen dedizierten Bereich **Settings → Theme / Appearance** (`settings.section`) und hängt die fünf
+     Funktionsreihen in den Slot `settings.dreamSkin.item` ein.
+
+Jeder Skin trägt sein `colorScheme` (`light`/`dark`), das `body[data-ds-dark-theme]` steuert; die Alias-Token-Overrides
+werden von ThemePresenter von ui-layout als Inline-Custom-Properties auf `<body>` angewendet.
+
+## 💼 Hinweise zur Speicherung
+
+- Skin & Wallpaper werden in `localStorage` gespeichert (Schlüssel mit Präfix `dsh-dream-skin:`), **pro Browser**.
+- Warum nicht die Host-Einstellungen? Die Host-Einstellungs-Schnittstelle legt Browser-Clients nur eine auf die Whitelist
+  gesetzte Auswahl von Namespaces offen (`WEB_SETTINGS_NAMESPACES` in `dsh-host-apiproxy`), daher würde ein
+  Drittanbieter-Namespace mit `settings-not-exposed` antworten; das Produkt selbst hält Remote-Browser-Einstellungen
+  prozesslokal. `localStorage` entspricht dieser Grenze und übersteht Neuladen.
+
+## 🛠️ Entwicklung / Themes erweitern
+
+Das Client-Bundle ist direkt im `__ModuleLoader__`-Format geschrieben (dieselbe Form, die tsdown für die mitgelieferten
+`ui-*`-Pakete erzeugt), daher ist **kein Build-Schritt** erforderlich. `lib/client.js` darf nur Module-Table-Entitäten
+`require`n: Plattform-Seeds (`react`, `react/jsx-runtime`, …) und registrierte Client-Bundles
+(`@deepseek-ai/dsh-client-runtime/client`, …).
+
+- **Einen integrierten Skin hinzufügen**: Füge dem `SKINS`-Array in `lib/client.js` ein Objekt (`id` + `colorScheme` +
+  `tokens`) hinzu; es erscheint dann automatisch in den Einstellungen. Füge einen Schlüssel `skin.<id>` in **allen 8 Sprachwörterbüchern** (`zh`/`en`/`ja`/`ko`/`es`/`fr`/`de`/`ru`) hinzu.
+
+- **Ein Theme-Paket ausliefern (empfohlen)**: Folge [`docs/examples/sample-theme-pack.json`](./docs/examples/sample-theme-pack.json) —
+  eine `*.dsh-theme.json` ist in den Einstellungen importierbar und über einen Link teilbar, ohne Codeänderungen.
+- **Eigene Wallpaper hinzufügen**: Lege Bilder in [`wallpapers/`](./wallpapers/) ab (verbreite nur, wofür du die Rechte
+  hast) und importiere sie dann über die „Wallpaper“-Reihe von DSH.
+- **Validieren**: `npm test` (VM-Smoke-Tests, die Factory-Eval, `apply()` sowie Paket-Import/-Persistenz abdecken).
+- **Neu einfärben**: Nutze die `--dsw-alias-*`-Tokens (vollständiger Vertrag in [`docs/themes-spec.md`](./docs/themes-spec.md)).
+
+## 📌 Roadmap
+
+- [x] v0.1: 8 Themes + eigenes Wallpaper (Deckkraft / Unschärfe) + lokale Speicherung
+- [x] Theme-Paket-Format + Import / Export / Share-Link (JSON + Manifest + Validierung)
+- [x] Akzent pro Benutzer + Zufallsfunktion
+- [x] Wallpaper 2.0 (URL / Verlauf / Vorschlag pro Skin / automatisches Abdunkeln)
+- [x] Lokale Paketbibliothek + Anwenden mit einem Klick / Favoriten / Überrasche-mich
+- [x] Vollständige i18n-Texte & Doku (zh / en / ja / ko / es / fr / de / ru)
+- [ ] Online-Farb-/Theme-Vorschau-Studio (reines Frontend, Kontrastprüfung)
+- [ ] Community-Theme-Galerie (Pakete an das Repo / die Online-Galerie senden)
+- [ ] Verbesserung des ersten Paintings (FOUC)
+
+## 🤝 Mitwirken
+
+Issues und PRs sind willkommen! Bitte lies den [Contributing Guide](./CONTRIBUTING.md) und beachte den
+[Code of Conduct](./CODE_OF_CONDUCT.md).
+
+## ⭐ Das Projekt unterstützen
+
+Wenn es dir gefällt: Gib dem Repo einen Stern **⭐**, ein Daumen-hoch **👍** auf npm, oder teile es mit DSH-Freunden — das
+hilft dem Projekt, entdeckt zu werden, und hält es gepflegt. Möchtest du Themes / ein Online-Studio / mehr Skins
+beisteuern? Mach mit.
+
+## 🔒 Sicherheit
+
+Ein Sicherheitsproblem gefunden? Öffne kein öffentliches Issue — siehe die [Security Policy](./SECURITY.md).
+
+## 📄 Lizenz
+
+[MIT](./LICENSE)
+
+## 🙏 Danksagungen
+
+- Architektur- & API-Referenz: das offizielle [ui-theme](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-theme)-Client-Paket
+  von DeepSeek Harness.
+- Konzept-Hommage: [Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin).

package/README.en.md

@@ -1,23 +1,25 @@
 <p align="center">
-  <a href="./README.md">中文</a> · <strong>English</strong>
+  <a href="./README.md">中文</a> · <strong>English</strong> · <a href="./README.ja.md">日本語</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.es.md">Español</a> · <a href="./README.fr.md">Français</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.ru.md">Русский</a>
 </p>
 
 <div align="center">
 
 # dsh-dream-skin 🔮
 
-**Give DeepSeek Harness a face that breathes, feels, and belongs to you.**
+**Give DeepSeek Harness a face that's restrained, clear and textured.**
 
-Native skinning · wallpaper · shareable theme packs — a romance-engineered project built entirely on DSH's official `--dsw-*` token system.
+Native skinning · wallpaper · shareable theme packs — an elegant implementation built entirely on DSH's official `--dsw-*` token system.
 
-> **TL;DR: code with atmosphere.** ✨
+> **TL;DR: your coding space can be quiet.**
 
-| 🎨 8 original themes | 🖼️ wallpaper + opacity/blur | 🌈 one-click accent | 📦 shareable theme packs |
+| 🎨 8 original themes | 🖼️ wallpaper + diffused glow | 🎯 restrained accent | 📦 shareable theme packs |
 |---|---|---|---|
 
-> 3-line install · purely native (no injection, no installer patches) · survives DSH updates
+> 1-line install · purely native (no injection, no installer patches) · survives DSH updates
 
-[中文](./README.md) · [Changelog](./CHANGELOG.md) · [Project Notes](./docs/PROJECT.md) · [Publishing Guide](./docs/publishing-to-npm.md)
+✨ **Design Philosophy — [a statement on what "premium" means](./docs/design-philosophy.md)** · grounded in iOS / Linear aesthetics, premium comes from material precision and restrained color.
+
+[中文](./README.md) · [Changelog](./CHANGELOG.md) · [Project Notes](./docs/PROJECT.md) · [Design Philosophy](./docs/design-philosophy.md) · [Publishing Guide](./docs/publishing-to-npm.md)
 
 ![npm version](https://img.shields.io/npm/v/dsh-dream-skin?color=4f83f2&label=npm)
 ![license](https://img.shields.io/github/license/RevolutionLA/dsh-dream-skin?color=34d399)
@@ -30,10 +32,19 @@ Native skinning · wallpaper · shareable theme packs — a romance-engineered p
 
 </div>
 
-> 🚀 **Now on npm!** With DSH installed, add it in one command — no cloning needed:
-> ```sh
-> dsh plugin --profile web add dsh-dream-skin
-> ```
+## ⚡ One-line install
+
+**Copy this sentence to your DSH and it installs everything for you:**
+
+> Please install the dsh-dream-skin skin plugin (https://github.com/RevolutionLA/dsh-dream-skin, or the npm package `dsh-dream-skin`), then tell me how to restart DSH Web.
+
+Prefer the CLI? One command:
+
+```sh
+dsh plugin --profile web add dsh-dream-skin && dsh web
+```
+
+> 🚀 **Now on npm!** With DSH installed, add it in one command — no cloning needed.
 
 > **Homage to [Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin).** But the approach is different:
 > Codex injects CSS into the desktop client's renderer via CDP, whereas DSH is a **token-driven Web GUI** that ships
@@ -88,7 +99,7 @@ Differentiation inspired by existing DSH skin projects plus Codex's skin UX:
 | 📦 **Theme-pack format + import/export** | A `*.dsh-theme.json` pack = format marker + version + manifest (id/name/author/scheme/accent/tokens). Import a file, one-click apply, and copy a **share link** (encoded in the URL hash) |
 | 🌈 **Per-user Accent** | Stack a custom brand-accent over the active skin (`overrideTokens` layer, the skin untouched): **12 one-click preset swatches**, a color picker, **randomize**, and clear |
 | 🖼️ **Wallpaper 2.0** | Local image / **image URL** / **gradient presets**, with a **per-skin suggested gradient** and **auto-dim**; **Recent** (up to 5) to switch back in one click |
-| 🧩 **Local pack library** | All built-in skins + imported packs in one place; **apply / favorite** in a click |
+| 🧩 **Local pack library** | Your imported theme packs in one place; **apply / favorite / remove** in a click (the 8 built-in skins live in the Skins row) |
 | ✅ **Clear selection feedback** | Switching skins updates the checked/bordered highlight **instantly** — no stale white highlight box |
 | 🎲 **Surprise me** | Randomly switch to a theme different from the current one |
 | ⭐ **Favorites** | Star your favorite skins and switch between them fast |
@@ -163,17 +174,48 @@ system.
 
 ## 📦 Install
 
+Pick any of the four options, then **restart DSH Web** (the current session will be interrupted, but DSH sessions are
+persisted to disk and recover after restart).
+
 ### Option A: From npm (published, **recommended**)
 
 ```sh
 dsh plugin --profile web add dsh-dream-skin
 ```
 
-Then **restart** the web server:
+### Option B: From GitHub (pinned to a verified commit)
+
+```sh
+dsh plugin --profile web add 'github:RevolutionLA/dsh-dream-skin#<40-char-commit>'
+```
+
+> Pinning to the commit of a release means new `main` changes never silently alter your installed copy.
+
+### Option C: From a Release tarball (offline / no git)
+
+Download `dsh-dream-skin-<version>.tgz` from the [Releases](https://github.com/RevolutionLA/dsh-dream-skin/releases)
+page (it ships the built `lib/client.js`, so no prepare script runs on install), then:
+
+```sh
+dsh plugin --profile web add ./dsh-dream-skin-<version>.tgz
+```
+
+### Option D: Clone and install from the local path (development)
+
+```sh
+git clone https://github.com/RevolutionLA/dsh-dream-skin.git
+cd dsh-dream-skin
+dsh plugin --profile web add .
+```
+
+> `dsh plugin` anchors relative paths to the directory **you run the command in**, installing a link dependency
+> pointing at your clone: edit the source, save, restart DSH — no reinstall needed.
+
+**Restart and verify:**
 
 ```sh
-# stop the running instance, then:
 dsh web
+dsh --profile web --dump-config | grep -A2 dream-skin   # a dream-skin loader entry should appear
 ```
 
 Open **Settings → Theme / Appearance** to see the **Skins**, **Accent**, **Wallpaper** / **Advanced Wallpaper**, and **Theme Packs** rows.
@@ -182,12 +224,6 @@ Open **Settings → Theme / Appearance** to see the **Skins**, **Accent**, **Wal
 > the profile directory as a workspace root, so a bare add fails with `ERR_PNPM_ADDING_TO_ROOT`. If your profile already
 > uses the workspace, you won't need to repeat it.
 
-### Option B: From source / a local directory (developers)
-
-```sh
-dsh plugin --profile web add -w /path/to/dsh-dream-skin
-```
-
 ## 🔄 Update / Uninstall
 
 **Update to the latest** (when installed from the npm release):
@@ -236,7 +272,7 @@ plugins register themes that override the alias layer (`--dsw-alias-*`). This pa
                                                          │
         ┌────────────────────────────────┬────────────────┐
         │                                │                │
-   ctx.theme.register(8 skins)     ctx.theme.overrideTokens(wallpaper)   ctx.slots.inject('settings.general.item')
+   ctx.theme.register(8 skins)     ctx.theme.overrideTokens(wallpaper)   ctx.slots.inject('settings.section' + 'settings.dreamSkin.item')
 ```
 
 - **Host half** (`lib/index.js`) — a `dsh.bundle` patch layer inserting the `dream-skin` loader entry; `apply` is a
@@ -247,7 +283,8 @@ plugins register themes that override the alias layer (`--dsw-alias-*`). This pa
   3. renders the wallpaper as a `z-index:-1` fixed backdrop and stacks `ctx.theme.overrideTokens(...)` making the
      main canvas (`--dsw-alias-bg-base`) and sidebar (`--dsw-specific-sidebar-fill`) translucent;
   4. listens for `theme/change` and re-shades the wallpaper wash on skin / scheme switch;
-  5. mounts both rows into the `settings.general.item` slot.
+  5. registers a dedicated **Settings → Theme / Appearance** section (`settings.section`) and mounts the five
+     feature rows under the `settings.dreamSkin.item` slot.
 
 Each skin carries its `colorScheme` (`light`/`dark`), driving `body[data-ds-dark-theme]`; the alias-token overrides
 are applied as inline custom properties on `<body>` by ui-layout's ThemePresenter.
@@ -267,7 +304,8 @@ The client bundle is written directly in the `__ModuleLoader__` format (the same
 seeds (`react`, `react/jsx-runtime`, …) and registered client bundles (`@deepseek-ai/dsh-client-runtime/client`, …).
 
 - **Add a built-in skin**: append an object (`id` + `colorScheme` + `tokens`) to the `SKINS` array in `lib/client.js`;
-  it then appears in Settings automatically. Add a `skin.<id>` key to both the `zh` and `en` dictionaries.
+  it then appears in Settings automatically. Add a `skin.<id>` key to **all 8 locale dictionaries**
+  (`zh`/`en`/`ja`/`ko`/`es`/`fr`/`de`/`ru`).
 - **Ship a theme pack (recommended)**: follow [`docs/examples/sample-theme-pack.json`](./docs/examples/sample-theme-pack.json) —
   one `*.dsh-theme.json` is importable in Settings and shareable via a link, no code changes needed.
 - **Add your own wallpapers**: drop images into [`wallpapers/`](./wallpapers/) (distribute only what you have rights
@@ -282,9 +320,9 @@ seeds (`react`, `react/jsx-runtime`, …) and registered client bundles (`@deeps
 - [x] Per-user Accent + randomize
 - [x] Wallpaper 2.0 (URL / gradient / per-skin suggestion / auto-dim)
 - [x] Local pack library + one-click apply / favorites / surprise-me
+- [x] Full i18n copy & docs (zh / en / ja / ko / es / fr / de / ru)
 - [ ] Online palette / theme-preview Studio (pure frontend, contrast checker)
 - [ ] Community theme gallery (submit packs to the repo / online gallery)
-- [ ] Full i18n copy & docs (zh / en / more)
 - [ ] First-paint (FOUC) improvement
 
 ## 🤝 Contributing