docs(run-a-node): dig-node control panel user guide (cache/LRU, pairing, live status)

docs/run-a-node/control-panel.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 8
+title: The dig-node Control Panel
+description: "Manage your local dig-node from the DIG Chrome extension's Control Panel: reserved .dig cache space and LRU eviction, upstream, hosted stores, sync, peers, live status, and pairing the control token."
+keywords:
+  - dig-node control panel
+  - dig cache
+  - LRU eviction
+  - reserved cache space
+  - control token pairing
+  - hosted stores
+  - node sync
+  - node peers
+tags:
+  - dig-node
+  - browser
+  - dig-rpc
+---
+
+# The dig-node Control Panel
+
+The DIG Chrome extension includes a **Control Panel** for your local dig-node. From it you can see the node's live status, decide how much disk space to reserve for cached content, and — after a one-time pairing step — manage the node's upstream, the stores it hosts, its sync, and its peers. No command line required for everyday use.
+
+The Control Panel is the extension's built-in equivalent of the DIG Browser's node-management screen: it talks to the node running on your own machine, so everything stays local.
+
+## Open it
+
+1. Open the extension.
+2. Go to the **Network** tab and choose **Control**. (The compact popup shows a summary; use **Open control panel** to see every section full-screen.)
+
+The panel detects the node automatically:
+
+- **Node running** → you see the management view.
+- **No node found** → you see a short page on how to install one. Browsing still works — content reads fall back to the public network; a node is only needed for the management view below.
+
+## Live status
+
+At the top, a live indicator shows whether your node is **Connected**, **Connecting**, or **Disconnected**, along with its address and version. It updates on its own — start or stop the node and the indicator flips within a few seconds, with no need to reopen the panel or refresh.
+
+## Reserve disk space for cached content (cache & LRU)
+
+Your node keeps a local cache of the content it has fetched, so repeat visits are instant and you help serve that content. The cache has a **reserved size** — a cap on how much disk it may use. When the cache grows past the cap, the node automatically removes the **least-recently-used** items first (an "LRU" policy), so the space you reserve is never exceeded and the content you actually use stays cached.
+
+This section is available immediately — it needs no pairing.
+
+**See how much is used.** A bar shows used space against the reserved cap, plus a few live figures: how many items are cached, their total size, how much has been evicted since the node started, and the cache hit/miss counts.
+
+**Set the reserved cap.** Enter a new size and apply it. The minimum is 64 MiB; a smaller value is raised to that floor. Lowering the cap below what's currently used triggers eviction of the oldest items until usage fits.
+
+**Review and remove cached items.** The cached list shows each item with its size, when it was last used, and its **eviction order** (position `0` is the next item that would be removed). You can:
+
+- **Evict one item** — remove a single cached item now.
+- **Clear all** — empty the cache entirely.
+
+Removing items only frees local disk; anything you visit again is simply re-fetched.
+
+:::tip
+Give the cache as much room as you can spare on a machine you browse from often — a larger reserve means fewer re-fetches and more content served locally. On a space-constrained machine, set a smaller reserve; LRU keeps the most useful items and drops the rest.
+:::
+
+## Manage the node (pairing required)
+
+The remaining sections change the node's configuration, so they require your explicit permission. Because the extension runs in the browser's sandbox, it cannot read the node's local permission file directly — instead you **pair** it once. Pairing grants the extension its own scoped, revocable credential; it never exposes the node's master key, and it can only be approved from the computer running the node.
+
+### Pair the extension with your node
+
+1. In the Control Panel, choose **Pair**. The extension shows a **6-digit code** and a pairing id.
+2. On the computer running the node, in a terminal, run `dig-node pair` to list pending requests (or `dig-node pair approve <pairing-id>` directly).
+3. Confirm the code shown in the terminal **matches** the code in the extension, then approve. This match is your safeguard: it ensures you approve *this* extension and nothing else.
+4. The Control Panel switches to the paired state automatically. The credential is stored only by the extension.
+
+The pairing code **expires after a few minutes**; if yours does before you approve it, choose **Pair** again for a fresh one.
+
+To stop using the credential, choose **Unpair** in the panel (this forgets it locally). To revoke it on the node itself, run `dig-node pair revoke <token-id>` on that computer — the panel returns to the unpaired state on its next action.
+
+:::note
+Pairing is only needed for the management sections below. Live status and the cache/LRU controls above work without it.
+:::
+
+### Upstream
+
+View the upstream the node fetches from, and set a different one. A changed upstream takes effect the next time the node starts.
+
+### Hosted stores
+
+See the stores your node holds and pins, pin a new store (so the node keeps and serves it), unpin one, and check any store's status. Pinning a specific version pre-fetches it so it's ready to serve.
+
+### Sync
+
+See whether authenticated whole-store sync is available and, for a specific version, trigger a sync so the node fetches and caches it.
+
+### Peers
+
+See your node's peer-network status — its connection to the relay for reachability behind a home router, and the peers it is connected to.
+
+## Related
+
+- [Manage your node](./manage.md) — the `control.*` admin actions and how the browser drives them
+- [Point a consumer at your node](./point-a-consumer.md) — set the extension, browser, or CLI to use your node
+- [Configure dig-node](./configure.md) — ports, the cache cap, and the upstream

docs/run-a-node/index.md

@@ -71,6 +71,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Configure dig-node](./configure.md) — ports, listeners, cache cap, upstream
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digstore serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
+- [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `digstore` on its own (publishing, not serving)
 

docs/run-a-node/manage.md

@@ -41,6 +41,7 @@ Open it from the **Control Pane button in the toolbar** (next to the wallet and
 
 ## Related
 
+- [The dig-node Control Panel](./control-panel.md) — manage the node from the extension: reserved cache + LRU, upstream, hosted stores, sync, peers, pairing
 - [Configure dig-node](./configure.md) — ports, cache cap, upstream
 - [Node conformance](../rpc/conformance.md) — the public serving contract (distinct from control.*)
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digstore serve` + dig:// clone/pull/push

i18n/de/docusaurus-plugin-content-docs/current/run-a-node/control-panel.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 8
+title: Das dig-node Bedienfeld
+description: "Verwalte deinen lokalen dig-node über das Bedienfeld der DIG Chrome extension: reservierter .dig-Cache-Speicherplatz und LRU-Verdrängung, vorgelagerte Quelle, gehostete Stores, Synchronisierung, Peers, Live-Status und die Kopplung des Kontroll-Tokens."
+keywords:
+  - dig-node Bedienfeld
+  - dig-Cache
+  - LRU-Verdrängung
+  - reservierter Cache-Speicherplatz
+  - Kopplung des Kontroll-Tokens
+  - gehostete Stores
+  - Node-Synchronisierung
+  - Node-Peers
+tags:
+  - dig-node
+  - browser
+  - dig-rpc
+---
+
+# Das dig-node Bedienfeld
+
+Die DIG Chrome extension enthält ein **Bedienfeld** für deinen lokalen dig-node. Darin siehst du den Live-Status des Nodes, legst fest, wie viel Speicherplatz für zwischengespeicherte Inhalte reserviert werden soll, und verwaltest — nach einem einmaligen Kopplungsschritt — die vorgelagerte Quelle des Nodes, die von ihm gehosteten Stores, seine Synchronisierung und seine Peers. Für die alltägliche Nutzung ist keine Kommandozeile nötig.
+
+Das Bedienfeld ist das in die Erweiterung eingebaute Gegenstück zum Node-Verwaltungsbildschirm des DIG Browser: Es spricht mit dem Node, der auf deinem eigenen Rechner läuft, sodass alles lokal bleibt.
+
+## Öffnen
+
+1. Öffne die Erweiterung.
+2. Gehe zum Tab **Network** (Netzwerk) und wähle **Control** (Steuerung). (Das kompakte Popup zeigt nur eine Zusammenfassung; nutze **Bedienfeld öffnen**, um jeden Bereich im Vollbild zu sehen.)
+
+Das Bedienfeld erkennt den Node automatisch:
+
+- **Node läuft** → du siehst die Verwaltungsansicht.
+- **Kein Node gefunden** → du siehst eine kurze Seite dazu, wie man einen installiert. Das Browsen funktioniert weiterhin normal — Inhaltszugriffe weichen dann auf das öffentliche Netzwerk aus; ein Node wird nur für die unten beschriebene Verwaltungsansicht benötigt.
+
+## Live-Status
+
+Oben zeigt eine Live-Anzeige, ob dein Node **Verbunden**, **Verbindet** oder **Getrennt** ist, zusammen mit seiner Adresse und Version. Sie aktualisiert sich von selbst — starte oder stoppe den Node, und die Anzeige wechselt binnen weniger Sekunden, ohne dass du das Bedienfeld neu öffnen oder die Seite neu laden musst.
+
+## Speicherplatz für zwischengespeicherte Inhalte reservieren (Cache & LRU)
+
+Dein Node hält einen lokalen Cache der von ihm abgerufenen Inhalte vor, sodass wiederholte Zugriffe sofort erfolgen und du mithilfst, diese Inhalte auszuliefern. Der Cache hat eine **reservierte Größe** — eine Obergrenze dafür, wie viel Speicherplatz er nutzen darf. Wächst der Cache über diese Grenze hinaus, entfernt der Node automatisch zuerst die **am längsten nicht genutzten** Einträge (eine „LRU"-Richtlinie), sodass der von dir reservierte Platz nie überschritten wird und die Inhalte, die du tatsächlich nutzt, im Cache bleiben.
+
+Dieser Bereich ist sofort verfügbar — er erfordert keine Kopplung.
+
+**Nutzung ansehen.** Ein Balken zeigt den genutzten Speicherplatz im Verhältnis zur reservierten Obergrenze, dazu einige Live-Werte: wie viele Einträge im Cache sind, ihre Gesamtgröße, wie viel seit dem Start des Nodes verdrängt wurde, sowie die Zahl der Cache-Treffer/-Fehlschläge.
+
+**Reservierte Obergrenze festlegen.** Gib eine neue Größe ein und wende sie an. Das Minimum ist **64 MiB**; ein kleinerer Wert wird auf diese Untergrenze angehoben. Senkst du die Obergrenze unter die aktuelle Nutzung, löst das die Verdrängung der ältesten Einträge aus, bis die Nutzung wieder passt.
+
+**Zwischengespeicherte Einträge ansehen und entfernen.** Die Liste der zwischengespeicherten Einträge zeigt zu jedem Eintrag seine Größe, wann er zuletzt genutzt wurde, und seine **Verdrängungsreihenfolge** (Position `0` ist der Eintrag, der als Nächstes entfernt würde). Du kannst:
+
+- **Einen Eintrag verdrängen** — einen einzelnen zwischengespeicherten Eintrag sofort entfernen.
+- **Alles leeren** — den Cache vollständig leeren.
+
+Das Entfernen von Einträgen gibt nur lokalen Speicherplatz frei; alles, was du erneut besuchst, wird einfach erneut abgerufen.
+
+:::tip
+Gib dem Cache so viel Platz wie möglich auf einem Rechner, von dem aus du häufig browst — eine größere Reservierung bedeutet weniger erneute Abrufe und mehr lokal ausgelieferte Inhalte. Auf einem Rechner mit begrenztem Speicherplatz solltest du eine kleinere Reservierung festlegen; LRU behält die nützlichsten Einträge und verwirft den Rest.
+:::
+
+## Den Node verwalten (Kopplung erforderlich)
+
+Die übrigen Bereiche ändern die Konfiguration des Nodes und erfordern daher deine ausdrückliche Erlaubnis. Da die Erweiterung in der Sandbox des Browsers läuft, kann sie die lokale Berechtigungsdatei des Nodes nicht direkt lesen — stattdessen **koppelst** du sie einmalig. Die Kopplung gewährt der Erweiterung ein eigenes, im Umfang begrenztes und widerrufbares Zugangsdatum; sie legt nie den Master-Key des Nodes offen, und sie kann nur auf dem Rechner genehmigt werden, auf dem der Node läuft.
+
+### Die Erweiterung mit deinem Node koppeln
+
+1. Wähle im Bedienfeld **Koppeln**. Die Erweiterung zeigt einen **6-stelligen Code** und eine Kopplungs-ID an.
+2. Führe auf dem Rechner, auf dem der Node läuft, in einem Terminal `dig-node pair` aus, um ausstehende Anfragen aufzulisten (oder direkt `dig-node pair approve <pairing-id>`).
+3. Bestätige, dass der im Terminal angezeigte Code mit dem Code in der Erweiterung **übereinstimmt**, und genehmige dann. Dieser Abgleich ist deine Absicherung: Er stellt sicher, dass du *genau diese* Erweiterung genehmigst und keine andere.
+4. Das Bedienfeld wechselt automatisch in den gekoppelten Zustand. Die Zugangsdaten werden nur von der Erweiterung gespeichert.
+
+Der Kopplungscode **läuft nach wenigen Minuten ab**; läuft deiner ab, bevor du ihn genehmigst, wähle einfach erneut **Koppeln** für einen neuen.
+
+Um die Zugangsdaten nicht mehr zu verwenden, wähle im Bedienfeld **Entkoppeln** (das vergisst sie nur lokal). Um sie am Node selbst zu widerrufen, führe auf diesem Rechner `dig-node pair revoke <token-id>` aus — das Bedienfeld kehrt bei seiner nächsten Aktion in den ungekoppelten Zustand zurück.
+
+:::note
+Die Kopplung wird nur für die Verwaltungsbereiche unten benötigt. Der Live-Status und die Cache-/LRU-Steuerung oben funktionieren auch ohne sie.
+:::
+
+### Vorgelagerte Quelle
+
+Sieh dir die vorgelagerte Quelle an, von der der Node Inhalte abruft, und lege eine andere fest. Eine geänderte vorgelagerte Quelle wird beim nächsten Start des Nodes wirksam.
+
+### Gehostete Stores
+
+Sieh dir die Stores an, die dein Node vorhält und anpinnt, pinne einen neuen Store an (damit der Node ihn vorhält und ausliefert), löse das Anpinnen eines anderen und prüfe den Status jedes beliebigen Stores. Das Anpinnen einer bestimmten Version ruft sie vorab ab, sodass sie sofort ausgeliefert werden kann.
+
+### Synchronisierung
+
+Sieh, ob eine authentifizierte Synchronisierung des gesamten Stores verfügbar ist, und löse für eine bestimmte Version eine Synchronisierung aus, sodass der Node sie abruft und zwischenspeichert.
+
+### Peers
+
+Sieh dir den Status des Peer-Netzwerks deines Nodes an — seine Verbindung zum Relay für Erreichbarkeit hinter einem heimischen Router sowie die Peers, mit denen er verbunden ist.
+
+## Siehe auch
+
+- [Verwalte deinen Node](./manage.md) — die administrativen `control.*`-Aktionen und wie der Browser sie ansteuert
+- [Einen Client auf deinen Node zeigen lassen](./point-a-consumer.md) — Erweiterung, Browser oder CLI so einstellen, dass sie deinen Node nutzen
+- [dig-node konfigurieren](./configure.md) — Ports, die Cache-Obergrenze und die vorgelagerte Quelle

i18n/de/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -71,6 +71,7 @@ Du brauchst keinen Node. Hol dir den **[DIG Browser ↗](https://github.com/DIG-
 - [dig-node konfigurieren](./configure.md) — Ports, Listener, Cache-Obergrenze, Upstream
 - [Einen Remote-Origin selbst hosten](../rpc/dig-remote.md) — `digstore serve` + dig://-Clone/Pull/Push
 - [Deinen Node verwalten](./manage.md) — die control.*-Admin-RPCs + die My-Node-UI
+- [Das Control Panel](./control-panel.md) — betreibe deinen Node komplett aus der DIG-Erweiterung: Live-Status, reservierter Cache-Speicher (LRU) und — nach dem Pairing — Upstream/gehostete Stores/Sync/Peers
 - [Die öffentliche Netzwerk-RPC nutzen](../rpc/public-network-rpc.md) — die dig RPC, die dein Node spricht, und den Betrieb eines Node im Netzwerk
 - [Die CLI installieren](../digstore/cli/install.md) — `digstore` für sich allein (Veröffentlichen, nicht Servieren)