mission-control/static/js/panels/guides.js

// guides.js — Anfänger-Guide (v6): praktische Tutorials/Workflows + kompakte Konzepte.

import { $ } from "../core/ui.js";

const TUTORIALS = [
  ["Dein erster Workflow — in 3 Schritten", `
    <ol class="tut-steps">
      <li><b>Modell holen:</b> Tab <b>Cookbook</b> → wähle deinen Anwendungsfall (z.B. „Coden") →
        <b>Komplettes Setup installieren</b>. Der Download läuft im Tab <b>Aktivität</b>.</li>
      <li><b>Verbinden:</b> Tab <b>Verbinden</b> → Basis-URL kopieren → in deinem Tool (z.B. OpenCode)
        als „OpenAI-kompatibel" einfügen. <b>Verbindung testen</b> bestätigt, dass es läuft.</li>
      <li><b>Arbeiten:</b> Im Tool das Modell (z.B. <code>coder</code>) wählen und loslegen. Das passende
        Modell wird <b>automatisch geladen</b> — du musst nichts starten.</li>
    </ol>`],
  ["Wie leere ich den Kontext? Machen die Tools das selbst?", `
    <p><b>Kurz: meistens ja, automatisch.</b> Der Kontext (das „Gedächtnis") gilt pro Unterhaltung.
    Startest du im Tool einen <b>neuen Chat / eine neue Session</b>, ist der Kontext wieder leer —
    das Tool verwaltet das Fenster für dich.</p>
    <p>Du musst nur selten eingreifen: wird ein Gespräch sehr lang, fang einen neuen an. <b>Wichtig:</b>
    „Grafikspeicher leeren" (Tab Server) ist etwas anderes — das wirft das <i>Modell</i> aus dem Speicher,
    nicht den Gesprächsverlauf.</p>`],
  ["Was passiert, wenn der Kontext volläuft?", `
    <p>Ist das Kontextfenster voll, passiert je nach Tool eins von dreien: das Modell <b>vergisst den
    Anfang</b> (älteste Nachrichten fallen raus), das Tool <b>kürzt automatisch</b>, oder du bekommst
    einen Fehler wie „context length exceeded".</p>
    <p><b>So gehst du vor:</b></p>
    <ol class="tut-steps">
      <li><b>Neuen Chat starten</b> — der einfachste Reset, Kontext ist wieder leer.</li>
      <li><b>Zusammenfassen lassen:</b> „Fasse unseren Stand kurz zusammen", dann im neuen Chat einfügen.</li>
      <li><b>Kontext vergrößern:</b> Tab <b>Modelle</b> → <b>Konfigurieren</b> → wir zeigen das Optimum
        für deine Hardware (mehr Kontext = mehr Speicherbedarf).</li>
    </ol>`],
  ["Was ist ein Agent — und wann brauche ich einen?", `
    <p>Ein nacktes Modell <b>schreibt nur Text zurück</b>. Ein <b>Agent</b> ist ein Programm drumherum,
    das das Modell <b>handeln</b> lässt: Dateien lesen und ändern, Befehle ausführen, im Web suchen —
    Schritt für Schritt in einer Schleife, bis die Aufgabe erledigt ist.</p>
    <p><b>Bild dazu:</b> Reiner Chat = du fragst einen Experten und tippst seine Antwort selbst ab.
    Agent = der Experte sitzt an deinem PC und <i>macht es selbst</i> — du schaust zu und bestätigst.</p>
    <p><b>Wann lohnt sich was?</b></p>
    <ul class="tut-steps" style="list-style:disc">
      <li><b>Fragen, Texte, Erklärungen, Brainstorming</b> → <u>kein</u> Agent nötig, eine Chat-Oberfläche
        wie <b>OpenWebUI</b> reicht völlig.</li>
      <li><b>Coden über mehrere Dateien, Befehle ausführen, recherchieren + umsetzen, automatisieren</b>
        → <b>Agent</b> (OpenCode, Cline, Continue).</li>
    </ul>
    <p><b>So arbeitest du damit:</b> Du beschreibst ein <b>Ziel</b> in Worten („baue Feature X", „finde den
    Bug in dieser Datei"). Der Agent macht sich einen Plan und arbeitet ihn ab; heikle Schritte bestätigst
    du. Lass ihn am besten in einem <b>Projektordner mit Git</b> arbeiten — dann ist jede Änderung
    nachvollziehbar und rückgängig zu machen.</p>
    <p><b>Gut zu wissen:</b> Diese Agenten <b>laufen lokal auf deinem PC</b> und reden mit deinem lokalen
    Modell. Du brauchst <b>keinen</b> Cloud-Dienst — die „empfohlenen Tools" im Tab <b>Verbinden</b> SIND
    die Agenten.</p>`],
  ["Was sind Skills — und wie installiere ich sie?", `
    <p>Ein <b>Skill</b> ist <b>verpacktes Können</b>: eine kurze Anleitung (oft + ein paar Hilfsskripte),
    die dem Agenten beibringt, eine <b>wiederkehrende Aufgabe</b> jedes Mal so zu erledigen, wie <i>du</i>
    es willst. Stell es dir wie ein Rezept oder eine Arbeitsanweisung vor, die der Agent liest, sobald sie passt.</p>
    <p><b>Skill vs. MCP — nicht verwechseln:</b> <b>MCP</b> gibt dem Agenten <b>neue Werkzeuge</b> (Aktionen,
    z.B. „auf eine Datenbank zugreifen"). <b>Skills</b> geben ihm <b>Know-how</b> (wie er etwas <i>gut</i> macht)
    mit den Werkzeugen, die er schon hat. Kurz: <b>Werkzeuge = MCP, Anleitungen = Skills.</b></p>
    <p><b>Wofür gut?</b></p>
    <ul class="tut-steps" style="list-style:disc">
      <li><b>Einheitlichkeit:</b> „Commit-Nachrichten immer in diesem Format", „unsere Komponenten sehen so aus".</li>
      <li><b>Wiederholung sparen:</b> du musst denselben Kontext nicht jedes Mal neu erklären.</li>
      <li><b>Wissen festhalten:</b> „so testen wir", „so wird ein Changelog geschrieben", Fach-Workflows.</li>
    </ul>
    <p><b>In deinen Tools heißt das konkret:</b></p>
    <ul class="tut-steps" style="list-style:disc">
      <li><b>OpenCode:</b> Projektregeln in einer <code>AGENTS.md</code> + eigene Befehle (Commands).</li>
      <li><b>Cline:</b> Regeln als <code>.clinerules</code> + „Workflows".</li>
      <li><b>Continue:</b> „Rules" + „Prompts".</li>
      <li><b>Offener Standard „Agent Skills":</b> ein Ordner mit einer <code>SKILL.md</code> (Beschreibung +
        Anleitung, optional Skripte) — zunehmend von mehreren Tools unterstützt.</li>
    </ul>
    <p><b>Installieren = meist nur eine Datei/einen Ordner ablegen</b> (kein Build, kein Neustart-Zauber):</p>
    <ol class="tut-steps">
      <li><b>Pro Projekt:</b> die Datei in den Projektordner legen (z.B. <code>AGENTS.md</code>,
        <code>.clinerules/</code>) — gilt nur für dieses Projekt.</li>
      <li><b>Global:</b> in den Konfig-Ordner des Tools — gilt überall. Das Tool liest es beim nächsten Start.</li>
    </ol>
    <p><b>Beste Quellen:</b> zuerst die <b>Doku deines Tools</b> (OpenCode/Cline/Continue) — am verlässlichsten.
    Dann <b>„awesome"-Listen auf GitHub</b> (z.B. <i>awesome-claude-skills</i>, <i>awesome-mcp-servers</i>) und
    die <b>quelloffenen Anthropic-Skills</b> als Vorlagen, um das Format zu lernen.</p>
    <p class="hint" style="margin-top:10px"><b>Für lokale Modelle wichtig:</b> Skills sind nur Text-Anleitungen
    und funktionieren mit <i>jedem</i> Modell — aber kleinere lokale Modelle befolgen komplexe Skills weniger
    zuverlässig als große. Halte sie <b>kurz, klar und konkret</b>.</p>`],
  ["MCP — deinem Agenten echte Werkzeuge geben", `
    <p><b>MCP</b> (Model Context Protocol) ist ein einheitlicher „Stecker", über den ein Agent zusätzliche
    <b>Werkzeuge</b> bekommt: das Web durchsuchen, Dateien lesen, eine Datenbank abfragen, GitHub bedienen …
    Ohne MCP kann das Modell nur reden; mit MCP kann es <b>etwas tun</b>.</p>
    <p><b>So nutzt du es:</b> Du fügst in deinem Agenten einen „MCP-Server" hinzu (eine kleine Zeile in der
    Konfiguration je Werkzeug). Danach entscheidet der Agent selbst, wann er das Werkzeug einsetzt.</p>
    <ul class="tut-steps" style="list-style:disc">
      <li><b>Unterstützt:</b> Cline und Continue haben das beste MCP-Ökosystem; viele fertige Server gibt es
        auf GitHub (Suchbegriff <i>awesome-mcp-servers</i>).</li>
      <li><b>Faustregel:</b> Fehlt dem Agenten eine <b>Fähigkeit</b> (z.B. Web-Zugriff) → MCP. Soll er etwas
        nur <b>besser/einheitlicher machen</b> → Skill.</li>
    </ul>`],
  ["Auto-Swap — wie das Laden funktioniert", `
    <p>llama-swap lädt automatisch das Modell, das gerade angefragt wird, und entlädt es nach einer
    Leerlaufzeit wieder (oder wenn du ein anderes anfragst). <b>Es läuft immer nur eines gleichzeitig.</b></p>
    <p>Heißt für dich: Du richtest beliebig viele Modelle ein und wählst im Tool einfach das passende —
    das Laden/Entladen passiert im Hintergrund, ohne dass du etwas tun musst.</p>`],
  ["Die empfohlenen Tools optimal nutzen", `
    <ul class="tut-steps" style="list-style:disc">
      <li><b>OpenCode:</b> Autonomes Coden im Terminal/Editor — ideal für „bau mir Feature X".</li>
      <li><b>Cline:</b> Dasselbe als VS-Code-Erweiterung, mit Bestätigung vor jeder Aktion.</li>
      <li><b>OpenWebUI:</b> Klassische Chat-Oberfläche für Fragen/Texte.</li>
    </ul>
    <p><b>Tipp:</b> starkes Modell (<code>coder</code>) für schwere Aufgaben, schnelles
    (<code>coder-fast</code>) für simple — du wählst es einfach im Tool aus.</p>`],
];

const CONCEPTS = [
  ["LLM / Modell", "Die KI selbst — versteht und schreibt Text (wie ChatGPT, nur lokal auf deinem PC). Ein Modell ist eine konkrete Datei davon, oft auf etwas spezialisiert (Code, Bilder, Chat)."],
  ["GGUF", "Das lokal lauffähige Dateiformat. Unsere Engine lädt nur GGUF — Repos ohne GGUF kann sie nicht nutzen."],
  ["Quantisierung (Q4_K_M)", "Verkleinert ein Modell (16-Bit → 4-Bit), damit es in den Speicher passt — bei kaum Qualitätsverlust. Q4_K_M ist der beliebte Sweetspot."],
  ["Kontextfenster", "Das Kurzzeitgedächtnis: wie viel Text sich das Modell gleichzeitig merkt. Größer = mehr Überblick, mehr Speicher, etwas langsamer."],
  ["Auto-Swap", "llama-swap lädt/entlädt Modelle automatisch — immer nur eins gleichzeitig. Du managst nichts."],
  ["Agent", "Ein Programm (OpenCode, Cline, Continue), das das Modell handeln lässt — Dateien lesen/ändern, Befehle ausführen, planen, im Loop bis die Aufgabe erledigt ist. Reiner Chat schreibt nur Text zurück."],
  ["MCP", "Model Context Protocol — der Anschluss, über den ein Agent zusätzliche Werkzeuge bekommt (Web, Dateien, Datenbank). MCP = Werkzeuge."],
  ["Skills", "Verpackte Anleitung für wiederkehrende Aufgaben — der Agent liest sie und macht es jedes Mal wie du willst. Skills = Anleitungen (das Gegenstück zu MCP-Werkzeugen)."],
  ["Rules / Commands", "Die konkrete Form von Skills je Tool: AGENTS.md (OpenCode), .clinerules (Cline), Rules/Prompts (Continue) — eine Datei im Projekt- oder Konfig-Ordner."],
];

function mount() {
  const c = $(".view[data-view='guides']"); if (!c) return;
  c.innerHTML = `
    <div class="pagehead"><div>
      <h1>Guide für Einsteiger</h1>
      <div class="sub">Praktische Workflows + die Local-LLM-Welt in Klartext — ohne Vorwissen.</div></div></div>

    <div class="card-h"><h3>Tutorials &amp; Workflows</h3></div>
    <div class="card" style="padding:0;overflow:hidden">
      ${TUTORIALS.map(([t, b], i) => `
        <details class="guide-acc"${i === 0 ? " open" : ""}><summary>${t}</summary>
          <div class="acc-body">${b}</div></details>`).join("")}
    </div>

    <div class="card-h" style="margin-top:8px"><h3>Konzepte kurz erklärt</h3></div>
    <div class="concept-grid">
      ${CONCEPTS.map(([term, text]) => `<div class="concept"><h4>${term}</h4><p>${text}</p></div>`).join("")}
    </div>`;
}

export default { id: "guides", mount };