docs: tea-Einrichtung fuer ein frisches Geraet beschreiben

Die Doku stellte fest, tea sei installiert - was auf jedem anderen Geraet falsch ist und dazu fuehrt, dass saemtliche Kommandos darunter fehlschlagen, ohne dass der Grund dabeisteht. Mit dem noetigen Token-Scope, damit gleich klar ist, warum Wartungs-API und Organisations-Repos nicht funktionieren.
docs: Einstiegspunkt fuer neue Sitzungen in AGENTS.md
2026-08-28 12:57:26 +02:00 · 2026-08-28 12:56:07 +02:00 · 2026-08-28 10:57:17 +02:00
13 changed files with 506 additions and 62 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -9,9 +9,8 @@
 # Dioxus build output
 /dist

+# Node (tailwind toolchain)
+node_modules/
+
 # IDE
 /.idea
-
-# dx erzeugt diese Datei bei jedem vollen Build neu, auch ohne Eingabedatei
-# und ohne dass sie noch verlinkt waere. Lokales Nebenprodukt, kein Quellcode.
-assets/tailwind.css
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -264,6 +264,22 @@ The initial UI rendered by the component on the client must be identical to the
 * Use the `use_server_future` hook instead of `use_resource`. It runs the future on the server, serializes the result, and sends it to the client, ensuring the client has the data immediately for its first render.
 * Any code that relies on browser-specific APIs (like accessing `localStorage`) must be run *after* hydration. Place this code inside a `use_effect` hook.

+## Woran gerade gearbeitet wird
+
+**Bevor du irgendetwas anderes tust:** Laufende Vorhaben liegen als *Wayfinder-Map* im
+Issue-Tracker, nicht in diesem Repo. Die offene Map findest du mit
+
+```bash
+tea issues ls --labels wayfinder:map --state open
+```
+
+Lies ihren Beschreibungstext (Destination, Notes, Decisions so far) **und ihren letzten
+Kommentar** — dort steht der Arbeitsstand samt Einstiegspunkt. Erst danach lohnt der Blick
+in den Code.
+
+Ist keine Map offen, gibt es kein laufendes Planungsvorhaben; dann gilt die normale
+Auftragslage aus dem Gespräch.
+
 ## Agent skills

 ### Issue tracker
--- a/README.md
+++ b/README.md
@@ -1,32 +1,51 @@
-# DioNotes Client
+# Development

-Lokale Markdown-Notizen-App auf Basis von [Dioxus 0.7](https://dioxuslabs.com/learn/0.7), Desktop.
+Your new bare-bones project includes minimal organization with a single `main.rs` file and a few assets.

-## Entwicklung
+```
+project/
+├─ assets/ # Any assets that are used by the app should be placed here
+├─ src/
+│  ├─ main.rs # main.rs is the entry point to your application and currently contains all components for the app
+├─ Cargo.toml # The Cargo.toml file defines the dependencies and feature flags for your project
+```
+
+### Automatic Tailwind (Dioxus 0.7+)
+
+As of Dioxus 0.7, there no longer is a need to manually install tailwind. Simply `dx serve` and you're good to go!
+
+Automatic tailwind is supported by checking for a file called `tailwind.css` in your app's manifest directory (next to Cargo.toml). To customize the file, use the dioxus.toml:
+
+```toml
+[application]
+tailwind_input = "my.css"
+tailwind_output = "assets/out.css" # also customize the location of the out file!
+```
+
+### Tailwind Manual Install
+
+To use tailwind plugins or manually customize tailwind, you can can install the Tailwind CLI and use it directly.
+
+### Tailwind
+1. Install npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
+2. Install the Tailwind CSS CLI: https://tailwindcss.com/docs/installation/tailwind-cli
+3. Run the following command in the root of the project to start the Tailwind CSS compiler:

 ```bash
-dx serve                     # Desktop-App starten (Standard-Plattform)
-dx serve --platform web      # im Browser
-cargo test                   # Tests
+npx @tailwindcss/cli -i ./input.css -o ./assets/tailwind.css --watch
 ```

-## Aufbau
+### Serving Your App

-```
-assets/css/     Design-System: tokens → base → layout → components,
-                in dieser Reihenfolge in main.rs verlinkt
-src/route.rs    alle Routen in einem Routable-Enum
-src/workspace.rs
-src/components/ wiederverwendbare Bausteine (CustomLink, CustomButton, …)
-src/views/      die Bildschirme: Selector und Editor
-docs/           Konventionen für Agenten, Rechercheergebnisse
+Run the following command in the root of your project to start developing with the default platform:
+
+```bash
+dx serve
 ```

-Es gibt **kein** Tailwind und keine npm-Toolchain — das Styling liegt vollständig in
-`assets/css/` und arbeitet mit den `--dn-*`-Tokens.
+To run for a different platform, use the `--platform platform` flag. E.g.
+```bash
+dx serve --platform desktop
+```

-## Wo die Entscheidungen liegen

-Fachbegriffe stehen in [`CONTEXT.md`](CONTEXT.md). Entscheidungen werden im
-Issue-Tracker geführt statt in `docs/adr/`; eine Wayfinder-Map indexiert pro Vorhaben,
-welche Entscheidung wo begründet ist. Siehe [`docs/agents/`](docs/agents/).
--- a/assets/css/tokens.css
+++ b/assets/css/tokens.css
@@ -4,9 +4,9 @@
   Palette: Catppuccin Mocha, matching the editor's Theme::CATPPUCCIN_MOCHA
   so the editor pane and the app chrome are the same surface.

-   All tokens are prefixed --dn- to keep them in one namespace. The prefix was
-   originally defence against Tailwind v4, which publishes its own --font-*,
-   --text-* and --radius-* on :root; Tailwind is gone, the convention stays.
+   All tokens are prefixed --dn-. Tailwind v4 publishes its own --font-*,
+   --text-*, --radius-* and --leading-* on :root and tree-shakes that set as
+   utilities come and go, so an unprefixed token would collide silently.
   ========================================================================== */

 :root {
--- a/assets/tailwind.css
+++ b/assets/tailwind.css
@@ -0,0 +1,275 @@
+/*! tailwindcss v4.1.5 | MIT License | https://tailwindcss.com */
+@layer properties;
+@layer theme, base, components, utilities;
+@layer theme {
+  :root, :host {
+    --font-sans: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
+    'Noto Color Emoji';
+    --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New',
+    monospace;
+    --text-xs: 0.75rem;
+    --text-sm: 0.875rem;
+    --text-base: 1rem;
+    --text-lg: 1.125rem;
+    --text-xl: 1.25rem;
+    --leading-tight: 1.25;
+    --leading-normal: 1.5;
+    --radius-sm: 0.25rem;
+    --radius-lg: 0.5rem;
+    --default-transition-duration: 150ms;
+    --default-transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+    --default-font-family: var(--font-sans);
+    --default-mono-font-family: var(--font-mono);
+  }
+}
+@layer base {
+  *, ::after, ::before, ::backdrop, ::file-selector-button {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    border: 0 solid;
+  }
+  html, :host {
+    line-height: 1.5;
+    -webkit-text-size-adjust: 100%;
+    tab-size: 4;
+    font-family: var(--default-font-family, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji');
+    font-feature-settings: var(--default-font-feature-settings, normal);
+    font-variation-settings: var(--default-font-variation-settings, normal);
+    -webkit-tap-highlight-color: transparent;
+  }
+  hr {
+    height: 0;
+    color: inherit;
+    border-top-width: 1px;
+  }
+  abbr:where([title]) {
+    -webkit-text-decoration: underline dotted;
+    text-decoration: underline dotted;
+  }
+  h1, h2, h3, h4, h5, h6 {
+    font-size: inherit;
+    font-weight: inherit;
+  }
+  a {
+    color: inherit;
+    -webkit-text-decoration: inherit;
+    text-decoration: inherit;
+  }
+  b, strong {
+    font-weight: bolder;
+  }
+  code, kbd, samp, pre {
+    font-family: var(--default-mono-font-family, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace);
+    font-feature-settings: var(--default-mono-font-feature-settings, normal);
+    font-variation-settings: var(--default-mono-font-variation-settings, normal);
+    font-size: 1em;
+  }
+  small {
+    font-size: 80%;
+  }
+  sub, sup {
+    font-size: 75%;
+    line-height: 0;
+    position: relative;
+    vertical-align: baseline;
+  }
+  sub {
+    bottom: -0.25em;
+  }
+  sup {
+    top: -0.5em;
+  }
+  table {
+    text-indent: 0;
+    border-color: inherit;
+    border-collapse: collapse;
+  }
+  :-moz-focusring {
+    outline: auto;
+  }
+  progress {
+    vertical-align: baseline;
+  }
+  summary {
+    display: list-item;
+  }
+  ol, ul, menu {
+    list-style: none;
+  }
+  img, svg, video, canvas, audio, iframe, embed, object {
+    display: block;
+    vertical-align: middle;
+  }
+  img, video {
+    max-width: 100%;
+    height: auto;
+  }
+  button, input, select, optgroup, textarea, ::file-selector-button {
+    font: inherit;
+    font-feature-settings: inherit;
+    font-variation-settings: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    border-radius: 0;
+    background-color: transparent;
+    opacity: 1;
+  }
+  :where(select:is([multiple], [size])) optgroup {
+    font-weight: bolder;
+  }
+  :where(select:is([multiple], [size])) optgroup option {
+    padding-inline-start: 20px;
+  }
+  ::file-selector-button {
+    margin-inline-end: 4px;
+  }
+  ::placeholder {
+    opacity: 1;
+  }
+  @supports (not (-webkit-appearance: -apple-pay-button))  or (contain-intrinsic-size: 1px) {
+    ::placeholder {
+      color: currentcolor;
+      @supports (color: color-mix(in lab, red, red)) {
+        color: color-mix(in oklab, currentcolor 50%, transparent);
+      }
+    }
+  }
+  textarea {
+    resize: vertical;
+  }
+  ::-webkit-search-decoration {
+    -webkit-appearance: none;
+  }
+  ::-webkit-date-and-time-value {
+    min-height: 1lh;
+    text-align: inherit;
+  }
+  ::-webkit-datetime-edit {
+    display: inline-flex;
+  }
+  ::-webkit-datetime-edit-fields-wrapper {
+    padding: 0;
+  }
+  ::-webkit-datetime-edit, ::-webkit-datetime-edit-year-field, ::-webkit-datetime-edit-month-field, ::-webkit-datetime-edit-day-field, ::-webkit-datetime-edit-hour-field, ::-webkit-datetime-edit-minute-field, ::-webkit-datetime-edit-second-field, ::-webkit-datetime-edit-millisecond-field, ::-webkit-datetime-edit-meridiem-field {
+    padding-block: 0;
+  }
+  :-moz-ui-invalid {
+    box-shadow: none;
+  }
+  button, input:where([type='button'], [type='reset'], [type='submit']), ::file-selector-button {
+    appearance: button;
+  }
+  ::-webkit-inner-spin-button, ::-webkit-outer-spin-button {
+    height: auto;
+  }
+  [hidden]:where(:not([hidden='until-found'])) {
+    display: none !important;
+  }
+}
+@layer utilities {
+  .visible {
+    visibility: visible;
+  }
+  .relative {
+    position: relative;
+  }
+  .static {
+    position: static;
+  }
+  .container {
+    width: 100%;
+    @media (width >= 40rem) {
+      max-width: 40rem;
+    }
+    @media (width >= 48rem) {
+      max-width: 48rem;
+    }
+    @media (width >= 64rem) {
+      max-width: 64rem;
+    }
+    @media (width >= 80rem) {
+      max-width: 80rem;
+    }
+    @media (width >= 96rem) {
+      max-width: 96rem;
+    }
+  }
+  .flex {
+    display: flex;
+  }
+  .table {
+    display: table;
+  }
+  .border-collapse {
+    border-collapse: collapse;
+  }
+  .transform {
+    transform: var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,);
+  }
+  .resize {
+    resize: both;
+  }
+  .border {
+    border-style: var(--tw-border-style);
+    border-width: 1px;
+  }
+  .text-wrap {
+    text-wrap: wrap;
+  }
+  .underline {
+    text-decoration-line: underline;
+  }
+  .outline {
+    outline-style: var(--tw-outline-style);
+    outline-width: 1px;
+  }
+  .transition {
+    transition-property: color, background-color, border-color, outline-color, text-decoration-color, fill, stroke, --tw-gradient-from, --tw-gradient-via, --tw-gradient-to, opacity, box-shadow, transform, translate, scale, rotate, filter, -webkit-backdrop-filter, backdrop-filter, display, visibility, content-visibility, overlay, pointer-events;
+    transition-timing-function: var(--tw-ease, var(--default-transition-timing-function));
+    transition-duration: var(--tw-duration, var(--default-transition-duration));
+  }
+}
+@property --tw-rotate-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-y {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-z {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-y {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-border-style {
+  syntax: "*";
+  inherits: false;
+  initial-value: solid;
+}
+@property --tw-outline-style {
+  syntax: "*";
+  inherits: false;
+  initial-value: solid;
+}
+@layer properties {
+  @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+    *, ::before, ::after, ::backdrop {
+      --tw-rotate-x: initial;
+      --tw-rotate-y: initial;
+      --tw-rotate-z: initial;
+      --tw-skew-x: initial;
+      --tw-skew-y: initial;
+      --tw-border-style: solid;
+      --tw-outline-style: solid;
+    }
+  }
+}
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -4,7 +4,19 @@ Issues and specs for this repo live as **Gitea** issues at
 <https://gitlab.hive-brain.de/RDietermann/dionotes-client>.

 > The host is named `gitlab.hive-brain.de`, but the server is **Gitea 1.25.5**, not GitLab.
-> `glab` will not work. Use the [`tea`](https://gitea.com/gitea/tea) CLI (v0.15 installed).
+> `glab` will not work. Use the [`tea`](https://gitea.com/gitea/tea) CLI (developed against v0.15).
+
+**Auf einem frischen Gerät** ist `tea` erst einzurichten — ohne das schlägt jedes Kommando
+unten fehl:
+
+```bash
+tea login add --name hive --url https://gitlab.hive-brain.de --token <token>
+tea login list          # prueft, ob es sitzt
+```
+
+Der Token braucht mindestens `write:issue`, `write:repository` und `write:user`. Der hier
+verwendete hat **kein** `read:admin` und **kein** `write:organization` — Wartungs-API und
+Anlegen unter einer Organisation scheitern damit.

 Run `tea` from inside the clone — it resolves owner/repo from `git remote`. It prints
 `NOTE: no login matched this repository, falling back to login 'hive'` on every call;
@@ -61,27 +73,6 @@ Create a Gitea issue.

 Run `tea issues <index>` plus `tea comments ls <index>`.

-## Branch- und PR-Workflow
-
-Änderungen werden **nicht direkt auf `main`** committet, sondern auf einem eigenen Branch
-pro logischer Einheit — `feat/`, `fix/`, `refactor/`, `chore/`, `docs/`. Eine Einheit ist,
-was man in einem Satz begründen kann; wenn die Commit-Nachricht „und außerdem" braucht,
-sind es zwei Branches.
-
-Zurück nach `main` geht es über einen **Pull Request in Gitea**, nicht per lokalem Merge:
-
-```bash
-git push -u origin <branch>
-tea pulls create --title "..." --description "..."
-```
-
-`--description` nimmt wie bei Issues nur eine Zeichenkette; für längere Texte eine Datei
-schreiben und mit `$(cat datei)` übergeben. Bezieht sich der PR auf ein Ticket, gehört
-`Closes #<n>` in die Beschreibung, damit Gitea es beim Mergen schließt.
-
-Gemergt wird in der Weboberfläche — das Mergen ist eine Entscheidung des Menschen, nicht
-Teil der Umsetzung.
-
 ## Wayfinding operations

 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
--- a/package-lock.json
+++ b/package-lock.json
@@ -0,0 +1,18 @@
+{
+  "name": "dionotes-client",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "tailwindcss": "^4.3.3"
+      }
+    },
+    "node_modules/tailwindcss": {
+      "version": "4.3.3",
+      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.3.tgz",
+      "integrity": "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ==",
+      "license": "MIT"
+    }
+  }
+}
--- a/package.json
+++ b/package.json
@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "tailwindcss": "^4.3.3"
+  }
+}
--- a/src/main.rs
+++ b/src/main.rs
@@ -7,6 +7,8 @@ mod workspace_list;

 use dioxus::prelude::*;

+use std::path::PathBuf;
+
 use crate::route::Route;
 use crate::workspace::Workspace;

@@ -15,6 +17,7 @@ const FAVICON: Asset = asset!("/assets/favicon.ico");
 // Linked individually rather than via @import in a single entry file: asset!()
 // only emits files it is given by name, so an @import chain would 404 at runtime.
 // Order matters — tokens, then baseline, then layout, then components.
+const TAILWIND_CSS: Asset = asset!("/assets/tailwind.css");
 const TOKENS_CSS: Asset = asset!("/assets/css/tokens.css");
 const BASE_CSS: Asset = asset!("/assets/css/base.css");
 const LAYOUT_CSS: Asset = asset!("/assets/css/layout.css");
@@ -30,9 +33,15 @@ fn App() -> Element {
    // gesetzt und in der Datei-Leiste gelesen — beide hängen unter einem
    // Outlet, durch das sich keine Props durchreichen lassen.
    use_context_provider(|| Signal::new(None::<Workspace>));
+    // Die im Editor geöffnete Notiz. Getrennt vom Workspace, weil sie sich
+    // ändert, ohne dass der Workspace wechselt.
+    use_context_provider(|| Signal::new(None::<PathBuf>));

    rsx! {
        document::Link { rel: "icon", href: FAVICON }
+        // Tailwind first: its preflight lives in @layer base, our unlayered
+        // rules win the cascade regardless, but this keeps source order honest.
+        document::Link { rel: "stylesheet", href: TAILWIND_CSS }
        document::Link { rel: "stylesheet", href: TOKENS_CSS }
        document::Link { rel: "stylesheet", href: BASE_CSS }
        document::Link { rel: "stylesheet", href: LAYOUT_CSS }
--- a/src/views/editor/dionotes_editor.rs
+++ b/src/views/editor/dionotes_editor.rs
@@ -24,14 +24,35 @@ pub fn Home() -> Element {

 #[component]
 pub fn Editor() -> Element {
+    let note = use_context::<Signal<Option<PathBuf>>>();
    let mut source = use_signal(String::new);

+    // Beim Wechsel der Notiz den Inhalt nachladen — auf einem eigenen Thread,
+    // damit eine große Datei auf langsamem Laufwerk nicht die Oberfläche hält.
+    use_effect(move || {
+        let path = note.read().clone();
+        spawn(async move {
+            let text = match path {
+                Some(path) => tokio::task::spawn_blocking(move || {
+                    std::fs::read_to_string(path).unwrap_or_default()
+                })
+                .await
+                .unwrap_or_default(),
+                None => String::new(),
+            };
+            source.set(text);
+        });
+    });
+
    rsx! {
        CodeEditor {
            class: "editor-class",
            value: source(),
            language: Language::Markdown,
            theme: Theme::CATPPUCCIN_MOCHA,
+            // TODO: Änderungen landen bisher nirgends. Speichern, Autosave und
+            // der Umgang mit ungesicherten Änderungen gehören zum
+            // Notiz-Handling und damit in den nächsten Effort.
            oninput: move |value| source.set(value),
        }
    }
@@ -119,9 +140,12 @@ fn TreeLevel(nodes: Vec<TreeNode>, expanded: Signal<HashSet<PathBuf>>, depth: us

 #[component]
 fn TreeEntry(node: TreeNode, mut expanded: Signal<HashSet<PathBuf>>, depth: usize) -> Element {
+    let mut note = use_context::<Signal<Option<PathBuf>>>();
+    let navigator = use_navigator();
    let path = node.path().to_path_buf();
    let name = node.name().to_string();
    let is_open = expanded.read().contains(&path);
+    let is_current = note.read().as_deref() == Some(path.as_path());

    match node {
        TreeNode::Folder { children, .. } => {
@@ -144,15 +168,20 @@ fn TreeEntry(node: TreeNode, mut expanded: Signal<HashSet<PathBuf>>, depth: usiz
                }
            }
        }
-        TreeNode::File { .. } => rsx! {
-            // TODO: Klick öffnet die Notiz im Editor. Gehört zum Notiz-Handling
-            // und damit in den nächsten Effort, nicht in diese Map.
-            button {
-                class: "file-selector",
-                style: "--depth: {depth}",
-                span { class: "tree-caret" }
-                "{name}"
+        TreeNode::File { .. } => {
+            let opened = path.clone();
+            rsx! {
+                button {
+                    class: if is_current { "file-selector active" } else { "file-selector" },
+                    style: "--depth: {depth}",
+                    onclick: move |_| {
+                        note.set(Some(opened.clone()));
+                        navigator.push(Route::Editor {});
+                    },
+                    span { class: "tree-caret" }
+                    "{name}"
+                }
            }
-        },
+        }
    }
 }
--- a/src/views/workspace_selector/selector.rs
+++ b/src/views/workspace_selector/selector.rs
@@ -11,6 +11,7 @@ use crate::workspace_list::WorkspaceList;
 #[component]
 pub fn Selector() -> Element {
    let mut workspace = use_context::<Signal<Option<Workspace>>>();
+    let mut note = use_context::<Signal<Option<PathBuf>>>();
    let mut list = use_signal(WorkspaceList::load);
    let navigator = use_navigator();

@@ -50,18 +51,32 @@ pub fn Selector() -> Element {
            )));
        }
        workspace.set(Some(opened));
-        navigator.push(Route::Home {});
+        // Mit Notiz direkt in den Editor, sonst auf den leeren Stand.
+        if note.read().is_some() {
+            navigator.push(Route::Editor {});
+        } else {
+            navigator.push(Route::Home {});
+        }
    };

    let mut create_at = move |root: PathBuf| match Workspace::create(root) {
-        Ok(opened) => accept(opened),
+        Ok(opened) => {
+            // Ein frischer Workspace bringt eine Kurzanleitung mit; die wird
+            // gleich angezeigt, statt den Nutzer vor eine leere Fläche zu setzen.
+            note.set(opened.welcome_note());
+            accept(opened);
+        }
        Err(err) => error.set(Some(format!("Anlegen fehlgeschlagen: {err}"))),
    };

    // Ein Klick versucht es erneut — damit ist „Stick wieder eingesteckt"
    // ohne eigenen Knopf abgedeckt.
    let mut open_entry = move |root: PathBuf| match Workspace::open(root) {
-        Ok(opened) => accept(opened),
+        Ok(opened) => {
+            // Ein bestehender Workspace öffnet ohne vorgewählte Notiz.
+            note.set(None);
+            accept(opened);
+        }
        Err(err) => error.set(Some(format!("Öffnen fehlgeschlagen: {err}"))),
    };

--- a/src/workspace.rs
+++ b/src/workspace.rs
@@ -7,6 +7,35 @@ use std::path::{Path, PathBuf};
 const MARKER_DIR: &str = ".dionotes";
 const MARKER_FILE: &str = "workspace.ron";

+/// Kurzanleitung, die ein frisch angelegter Workspace mitbekommt.
+pub const WELCOME_FILE: &str = "Willkommen.md";
+
+const WELCOME_TEXT: &str = "# Willkommen bei DioNotes
+
+Dieser Ordner ist jetzt ein **Workspace** — eine Sammlung von Notizen, die als
+gewöhnliche Markdown-Dateien nebeneinander liegen. Du kannst sie jederzeit mit
+jedem anderen Programm öffnen, sichern oder synchronisieren.
+
+## Wie es aufgebaut ist
+
+- Jede Notiz ist eine `.md`-Datei in diesem Ordner.
+- **Unterordner funktionieren.** Sie erscheinen links als aufklappbarer Baum.
+- Der versteckte Ordner `.dionotes` macht diesen Ordner zum Workspace. Dort
+  landen später auch die Einstellungen. Lösche ihn nicht — ohne ihn erkennt
+  DioNotes den Ordner nicht wieder.
+- Alles, was mit einem Punkt beginnt, bleibt in der Liste unsichtbar. Ein
+  `.git`-Ordner stört also nicht.
+
+## Gut zu wissen
+
+DioNotes liest den Ordner beim Öffnen einmal ein. Änderst du etwas von außen —
+etwa über einen Sync-Dienst —, hol dir den neuen Stand mit dem Knopf **⟳** über
+der Notizliste.
+
+Diese Datei ist eine ganz normale Notiz. Du kannst sie überschreiben oder
+löschen, sobald du sie nicht mehr brauchst.
+";
+
 /// Aktuelle Fassung des Marker-Schemas. Erhöhen, sobald Felder dazukommen,
 /// die eine ältere App nicht bloß ignorieren kann.
 const SCHEMA_VERSION: u32 = 1;
@@ -101,6 +130,12 @@ impl Workspace {
        root.join(MARKER_DIR).join(MARKER_FILE)
    }

+    /// Die Willkommensnotiz, falls dieser Workspace eine bekommen hat.
+    pub fn welcome_note(&self) -> Option<PathBuf> {
+        let path = self.root.join(WELCOME_FILE);
+        path.is_file().then_some(path)
+    }
+
    /// Ob dieser Ordner einen Marker trägt — die Frage „ist das hier überhaupt
    /// ein Workspace?". Sagt nichts darüber, ob der Marker lesbar ist.
    pub fn has_marker(root: &Path) -> bool {
@@ -133,6 +168,10 @@ impl Workspace {
        if !root.is_dir() {
            return Err(OpenError::Unreachable);
        }
+        // Zuerst prüfen: Sobald `.dionotes` angelegt ist, ist der Ordner
+        // nie mehr leer.
+        let was_empty = dir_is_empty(&root).unwrap_or(false);
+
        let marker_path = Self::marker_path(&root);
        if let Some(dir) = marker_path.parent() {
            fs::create_dir_all(dir)?;
@@ -141,6 +180,14 @@ impl Workspace {
        let text = ron::ser::to_string_pretty(&marker, ron::ser::PrettyConfig::default())
            .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
        fs::write(&marker_path, text)?;
+
+        // Nur in einen frischen Workspace. Wer einen Ordner voller Notizen
+        // importiert, will keine fremde Datei dazwischen — er kennt das
+        // Programm dann meist schon.
+        if was_empty {
+            let _ = fs::write(root.join(WELCOME_FILE), WELCOME_TEXT);
+        }
+
        Ok(Self { root })
    }
 }
@@ -179,6 +226,26 @@ mod tests {
        assert_eq!(Workspace::open(dir.clone()).expect("oeffenbar"), created);
    }

+    #[test]
+    fn a_fresh_workspace_gets_a_welcome_note() {
+        let dir = scratch("welcome-fresh");
+        let ws = Workspace::create(dir.clone()).expect("anlegbar");
+
+        let note = ws.welcome_note().expect("Willkommensnotiz vorhanden");
+        assert!(note.ends_with("Willkommen.md"));
+        assert!(fs::read_to_string(&note).unwrap().contains("Workspace"));
+    }
+
+    #[test]
+    fn an_imported_folder_gets_no_welcome_note() {
+        let dir = scratch("welcome-import");
+        fs::write(dir.join("eigene-notiz.md"), "# Meins").unwrap();
+
+        let ws = Workspace::create(dir.clone()).expect("anlegbar");
+        assert!(ws.welcome_note().is_none(), "Import darf keine fremde Datei bekommen");
+        assert!(!dir.join("Willkommen.md").exists());
+    }
+
    #[test]
    fn create_leaves_existing_files_alone() {
        let dir = scratch("create-keeps-files");
--- a/tailwind.css
+++ b/tailwind.css
@@ -0,0 +1 @@
+@import "tailwindcss";