pi-ghost-autocomplete 0.6.0 → 0.8.0

package/README.de.md

@@ -0,0 +1,164 @@
+# pi-ghost-autocomplete
+
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
+Inline-Ghost-Text-Autovervollständigung für den [Pi Coding Agent](https://pi.dev/) (`@earendil-works/pi-coding-agent`).
+
+Während du an der Pi-Eingabe schreibst, sagt ein LLM die wahrscheinlichste
+Fortsetzung der aktuellen Zeile voraus und zeigt sie als grauen „Ghost-Text"
+rechts vom Cursor an. Drücke **Rechtspfeil** zum Akzeptieren. Der Cursor
+bewegt sich erst, wenn du das tust, das bestehende Slash-Command-Popup
+behält **Tab**, und ein langsamer oder unerreichbarer Backend deaktiviert
+sich selbstständig, statt den Chat zu spammen.
+
+**Mehrsprachig** (Session 52): Unicode-fähige Worterkennung verarbeitet
+deutsche Umlaute, französische/spanische Akzente, CJK-Schriften und
+kombinierende Zeichen. Register-basiertes Routing stellt sicher, dass
+Prosa in der jeweiligen Sprache vervollständigt wird, ohne als
+Coding-Agent-Anweisung umgedeutet zu werden.
+
+## Erste Schritte
+
+### 1. Mercury Edit 2 API-Key besorgen
+
+Der Standard-Provider ist **Mercury Edit 2** von Inception Labs — ein
+diffusionsbasiertes Modell für latenzarme Code-Vervollständigungen.
+Registriere dich unter [platform.inceptionlabs.ai](https://platform.inceptionlabs.ai),
+um einen API-Key zu erhalten.
+
+Setze die `INCEPTION_API_KEY`-Umgebungsvariable:
+
+```bash
+# ~/.bashrc oder ~/.zshrc
+export INCEPTION_API_KEY="dein-key"
+```
+
+```powershell
+# PowerShell $PROFILE
+$env:INCEPTION_API_KEY = "dein-key"
+```
+
+### 2. Erweiterung installieren
+
+```bash
+pi install npm:pi-ghost-autocomplete
+```
+
+Für nur ein einzelnes Projekt:
+
+```bash
+pi install npm:pi-ghost-autocomplete -l
+```
+
+### 3. Pi starten und ausprobieren
+
+```bash
+pi
+```
+
+Beginne an der Eingabe zu tippen. Ein grauer Ghost-Text sollte innerhalb
+von ~150 ms erscheinen. Drücke **Rechtspfeil** zum Akzeptieren oder tippe
+weiter zum Verwerfen.
+
+> **Die erste Sitzung fühlt sich „kalt" an.** Trie, Cache und Profil
+> starten leer und lernen mit der Zeit. Nach 20–30 akzeptierten
+> Vorschlägen werden häufige Präfixe aus dem lokalen Cache bedient.
+
+## Konfiguration
+
+Alle Einstellungen sind Umgebungsvariablen — keine zusätzliche
+Konfigurationsdatei nötig. Die wichtigsten:
+
+| Variable | Standard | Wirkung |
+| --- | --- | --- |
+| `PI_GHOST_DISABLED` | nicht gesetzt | Auf `1` setzen, um beim Start zu deaktivieren |
+| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`, `local`, oder `router` |
+| `INCEPTION_API_KEY` | — | API-Key für Mercury Edit |
+| `PI_GHOST_MODEL` | providerspezifisch | Modell-ID |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Token-Limit für den Chat-Zweig (Router-Modus) |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Temperatur für den Chat-Zweig |
+| `PI_GHOST_DEBOUNCE_MS` | 150 (Cloud) / 400 (Local) | Debounce vor Request |
+| `PI_GHOST_METRICS` | nicht gesetzt | Auf `1` setzen für Metriken in `.pi/ghost-autocomplete/metrics.jsonl` |
+
+> Die vollständige Variablen-Referenz findest du im
+> [englischen README](README.md#configuration).
+
+## Register-Routing
+
+Der Router-Modus teilt die Arbeit zwischen zwei Modellen auf, basierend auf
+dem **Completion-Register**:
+
+| Register | Zweig | System-Prompt |
+| --- | --- | --- |
+| `code` | **FIM** (`mercury-edit-2`) | Code/Command/Pfad-Vervollständigung |
+| `agent-message` | **Chat** (`mercury-2`) | „Setze die Nachricht an den Assistenten fort" |
+| `general-prose` | **Chat** (`mercury-2`) | „Setze den Text natürlich fort, gleiche Sprache/Stil" — **ohne** Coding-Agent-Framing |
+
+```bash
+PI_GHOST_PROVIDER=router INCEPTION_API_KEY=dein-key pi ...
+```
+
+### Mehrsprachige Unterstützung
+
+Die Intent-Erkennung und Kontext-Tokenisierung verwenden Unicode-fähige
+Wortsegmentierung (`Intl.Segmenter`) statt ASCII-Regexen. Das bedeutet:
+
+- Deutsche Umlaute (möchte, ändern, über) werden als vollständige Wörter erkannt
+- Französische/Spanische Akzente (café, función) bleiben erhalten
+- CJK-Text (Chinesisch/Japanisch/Koreanisch) erhält wörterbuchbasierte Segmentierung
+- BM25-Kontextauswahl funktioniert für nichtenglische Konversationen
+
+## Befehle
+
+| Befehl | Wirkung |
+| --- | --- |
+| `/ghost` | Aktuelle Konfiguration anzeigen |
+| `/ghost on` | Für diese Sitzung aktivieren |
+| `/ghost off` | Für diese Sitzung deaktivieren |
+
+## Metriken und Debug-Logging
+
+```bash
+PI_GHOST_METRICS=1 pi ...        # schreibt .pi/ghost-autocomplete/metrics.jsonl
+PI_GHOST_DEBUG_LOG=1 pi ...      # schreibt .pi/ghost-autocomplete/debug.jsonl
+```
+
+Metriken enthalten: Zeitstempel, Provider-Latenzen, Completion-Register,
+Ergebnis, Acceptance-Outcome und (bei `empty`) die diagnostizierte Ursache.
+Rohe Prompts/Completions werden **niemals** in die Metrik-Datei geschrieben.
+
+### Empty-Ursachen
+
+| Ursache | Bedeutung |
+| --- | --- |
+| `model-empty` | Modell lieferte leeren/Whitespace-Only-Text |
+| `token-budget-exhausted` | Budget vollständig für Reasoning verbraucht → `PI_GHOST_CHAT_MAX_TOKENS` erhöhen |
+| `sanitizer-null` | Inhalt vom Sanitizer verworfen (Echo, Dateiname in Prosa) |
+| `response-schema-error` | Response war JSON, aber nicht im erwarteten Schema |
+| `http-error` | Fehlender Key, Non-2xx, malformed JSON, Timeout |
+
+`pi-ghost-bench` zeigt eine `empty-cause`-Aufschlüsselung.
+
+## Benutzerprofil
+
+Die Erweiterung speichert ein langlebiges JSONL-Profil unter
+`.pi/ghost-autocomplete/profile.jsonl`, um Slash-Command-, Pfad- und
+Trigramm-Häufigkeiten über Sitzungen hinweg zu lernen. Das Profil speist
+drei lokale Signale:
+
+1. **Slash-Fast-Path** — `/`-Präfixe werden aus dem Gedächtnis bedient
+2. **Profile-Bias-Rerank** — Trigramm-Häufigkeit fließt in den Reranker ein
+3. **Pfad-Boost** — Häufige Pfade erhalten einen begrenzten Boost
+
+Datenschutz: Keine rohen Präfixe oder Completions werden gespeichert.
+Das Profil nutzt SHA-256-Hashes für Präfix-Lookups und sanitisierte
+n-Grams. Sensible Nachrichten werden vollständig verworfen.
+
+## Lizenz
+
+SSPL-1.0 — siehe [Lizenzdatei](LICENSE).
+
+---
+
+> Die vollständige technische Dokumentation findest du im
+> [englischen README](README.md) und in [`docs/`](docs/).

package/README.es.md

@@ -0,0 +1,66 @@
+# pi-ghost-autocomplete
+
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
+Autocompletado de texto fantasma para el [agente de codificación Pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`).
+
+Mientras escribes en el prompt de Pi, un LLM predice la continuación más
+probable de la línea actual y la muestra en gris a la derecha del cursor.
+Pulsa **Flecha derecha** para aceptar.
+
+**Multilingüe** (sesión 52): la segmentación de palabras Unicode maneja
+acentos españoles, diéresis alemanas, scripts CJK y marcas combinatorias.
+
+## Inicio rápido
+
+### 1. Obtener una clave API de Mercury Edit 2
+
+```bash
+export INCEPTION_API_KEY="tu-clave"
+```
+
+### 2. Instalar la extensión
+
+```bash
+pi install npm:pi-ghost-autocomplete
+```
+
+### 3. Iniciar Pi
+
+```bash
+pi
+```
+
+## Configuración
+
+| Variable | Predeterminado | Efecto |
+| --- | --- | --- |
+| `PI_GHOST_DISABLED` | sin definir | `1` para desactivar |
+| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`, `local`, o `router` |
+| `INCEPTION_API_KEY` | — | Clave API |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Límite de tokens (chat) |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Temperatura (chat) |
+
+> Consulta el [README en inglés](README.md#configuration) para la referencia completa.
+
+## Enrutamiento por registro
+
+| Registro | Rama | Prompt del sistema |
+| --- | --- | --- |
+| `code` | **FIM** | Completar código/comando/ruta |
+| `agent-message` | **Chat** | «Continuar el mensaje al asistente» |
+| `general-prose` | **Chat** | «Continuar el texto naturalmente, mismo idioma» |
+
+```bash
+PI_GHOST_PROVIDER=router INCEPTION_API_KEY=tu-clave pi ...
+```
+
+## Comandos
+
+| Comando | Efecto |
+| --- | --- |
+| `/ghost` | Mostrar configuración |
+| `/ghost on` | Activar para esta sesión |
+| `/ghost off` | Desactivar para esta sesión |
+
+> Documentación completa: [README en inglés](README.md) y [`docs/`](docs/).

package/README.fr.md

@@ -0,0 +1,79 @@
+# pi-ghost-autocomplete
+
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
+Auto-complétion en texte fantôme (« ghost text ») pour l'[agent de codage Pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`).
+
+Pendant que vous tapez à l'invite Pi, un LLM prédit la suite la plus probable
+de la ligne courante et l'affiche en gris à droite du curseur. Appuyez sur
+**Flèche droite** pour accepter. Le curseur ne bouge pas tant que vous ne le
+faites pas.
+
+**Multilingue** (session 52) : la segmentation des mots Unicode gère les
+accents français, les trémas allemands, les scripts CJK et les marques
+combinaison. Le routage par registre garantit que la prose est complétée
+dans la même langue.
+
+## Démarrage
+
+### 1. Obtenir une clé API Mercury Edit 2
+
+```bash
+export INCEPTION_API_KEY="votre-clé"
+```
+
+### 2. Installer l'extension
+
+```bash
+pi install npm:pi-ghost-autocomplete
+```
+
+### 3. Lancer Pi
+
+```bash
+pi
+```
+
+## Configuration
+
+| Variable | Défaut | Effet |
+| --- | --- | --- |
+| `PI_GHOST_DISABLED` | non défini | `1` pour désactiver |
+| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`, `local`, ou `router` |
+| `INCEPTION_API_KEY` | — | Clé API |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Limite de tokens (chat) |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Température (chat) |
+| `PI_GHOST_METRICS` | non défini | `1` pour les métriques |
+
+> Voir le [README anglais](README.md#configuration) pour la référence complète.
+
+## Routage par registre
+
+| Registre | Branche | Invite système |
+| --- | --- | --- |
+| `code` | **FIM** | Complétion de code/commande/chemin |
+| `agent-message` | **Chat** | « Continuez le message à l'assistant » |
+| `general-prose` | **Chat** | « Continuez le texte naturellement, même langue » |
+
+```bash
+PI_GHOST_PROVIDER=router INCEPTION_API_KEY=votre-clé pi ...
+```
+
+## Commandes
+
+| Commande | Effet |
+| --- | --- |
+| `/ghost` | Afficher la configuration |
+| `/ghost on` | Activer pour cette session |
+| `/ghost off` | Désactiver pour cette session |
+
+## Métriques
+
+```bash
+PI_GHOST_METRICS=1 pi ...
+```
+
+Les métriques incluent : latences, registre de complétion, résultat et cause
+des réponses vides (`token-budget-exhausted`, `model-empty`, etc.).
+
+> Documentation complète : [README anglais](README.md) et [`docs/`](docs/).

package/README.it.md

@@ -0,0 +1,66 @@
+# pi-ghost-autocomplete
+
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
+Auto-completamento con testo fantasma (« ghost text ») per l'[agente di codifica Pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`).
+
+Mentre digiti al prompt di Pi, un LLM predice la continuazione più probabile
+della riga corrente e la mostra in grigio a destra del cursore. Premi
+**Freccia destra** per accettare.
+
+**Multilingue** (session 52): la segmentazione delle parole Unicode gestisce
+accenti italiani, umlaut tedeschi, script CJK e segni combinanti.
+
+## Avvio rapido
+
+### 1. Ottenere una chiave API Mercury Edit 2
+
+```bash
+export INCEPTION_API_KEY="la-tua-chiave"
+```
+
+### 2. Installare l'estensione
+
+```bash
+pi install npm:pi-ghost-autocomplete
+```
+
+### 3. Avviare Pi
+
+```bash
+pi
+```
+
+## Configurazione
+
+| Variabile | Predefinito | Effetto |
+| --- | --- | --- |
+| `PI_GHOST_DISABLED` | non impostato | `1` per disattivare |
+| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`, `local`, o `router` |
+| `INCEPTION_API_KEY` | — | Chiave API |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Limite di token (chat) |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Temperatura (chat) |
+
+> Consulta il [README in inglese](README.md#configuration) per la reference completa.
+
+## Routing per registro
+
+| Registro | Ramo | Prompt di sistema |
+| --- | --- | --- |
+| `code` | **FIM** | Completare codice/comando/percorso |
+| `agent-message` | **Chat** | «Continua il messaggio all'assistente» |
+| `general-prose` | **Chat** | «Continua il testo naturalmente, stessa lingua» |
+
+```bash
+PI_GHOST_PROVIDER=router INCEPTION_API_KEY=la-tua-chiave pi ...
+```
+
+## Comandi
+
+| Comando | Effetto |
+| --- | --- |
+| `/ghost` | Mostra configurazione |
+| `/ghost on` | Attiva per questa sessione |
+| `/ghost off` | Disattiva per questa sessione |
+
+> Documentazione completa: [README in inglese](README.md) e [`docs/`](docs/).

package/README.ja.md

@@ -0,0 +1,65 @@
+# pi-ghost-autocomplete
+
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
+[Pi コーディングエージェント](https://pi.dev/)（`@earendil-works/pi-coding-agent`）用のインラインゴーストテキスト自動補完。
+
+Pi のプロンプトで入力中、LLM が現在の行の続きを予測し、カーソルの右側に
+グレーの「ゴーストテキスト」として表示します。**右矢印キー**で受け入れます。
+
+**多言語対応**（Session 52）：Unicode 対応の単語分割により、日本語・中国語・
+韓国語のスクリプト、ドイツ語のウムラウト、フランス語のアクセントを処理します。
+
+## クイックスタート
+
+### 1. Mercury Edit 2 API キーを取得
+
+```bash
+export INCEPTION_API_KEY="あなたのキー"
+```
+
+### 2. 拡張機能をインストール
+
+```bash
+pi install npm:pi-ghost-autocomplete
+```
+
+### 3. Pi を起動
+
+```bash
+pi
+```
+
+## 設定
+
+| 変数 | デフォルト | 効果 |
+| --- | --- | --- |
+| `PI_GHOST_DISABLED` | 未設定 | `1` で無効化 |
+| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`、`local`、または `router` |
+| `INCEPTION_API_KEY` | — | API キー |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | チャットのトークン上限 |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | チャットの温度 |
+
+> 完全な設定リファレンスは[英語 README](README.md#configuration) を参照してください。
+
+## レジスタルーティング
+
+| レジスタ | ブランチ | システムプロンプト |
+| --- | --- | --- |
+| `code` | **FIM** | コード/コマンド/パスの補完 |
+| `agent-message` | **チャット** | 「アシスタントへのメッセージを続ける」 |
+| `general-prose` | **チャット** | 「テキストを自然に続ける、同じ言語で」 |
+
+```bash
+PI_GHOST_PROVIDER=router INCEPTION_API_KEY=あなたのキー pi ...
+```
+
+## コマンド
+
+| コマンド | 効果 |
+| --- | --- |
+| `/ghost` | 設定を表示 |
+| `/ghost on` | このセッションで有効化 |
+| `/ghost off` | このセッションで無効化 |
+
+> 完全なドキュメント：[英語 README](README.md) と [`docs/`](docs/)。

package/README.md

@@ -1,13 +1,20 @@
 # pi-ghost-autocomplete
 
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
 Inline ghost-text autocomplete for the [Pi coding agent](https://pi.dev/) (`@earendil-works/pi-coding-agent`).
 
 While you type at the Pi prompt, an LLM predicts the most likely continuation
 of the current line and renders it as dim grey "ghost text" right of the
-cursor. Press **Right Arrow** to accept. The cursor never moves until you do,
+cursor. Press **Right Arrow** or **Tab** (when no slash popup) to accept. The cursor never moves until you do,
 the existing slash-command popup keeps **Tab**, and a slow or unreachable
 backend silently disables itself rather than spamming the chat.
 
+**Multilingual** (session 52): Unicode-aware word segmentation handles German
+umlauts, French/Spanish diacritics, CJK scripts, and combining marks.
+Register-based routing ensures general prose is completed in-language without
+being reframed as a coding-agent instruction.
+
 Four provider modes ship in the same package:
 
 | Mode | Backend | Default debounce | Default model |
@@ -65,7 +72,18 @@ pi install npm:pi-ghost-autocomplete -l   # writes to .pi/ in the current direct
 pi
 ```
 
-Start typing at the prompt. A dim ghost text should appear to the right of your cursor within ~150 ms. Press **Right Arrow** to accept it, or keep typing to dismiss it.
+Start typing at the prompt. A dim ghost text should appear to the right of your cursor within ~150 ms. Press **Right Arrow** to accept it, or keep typing to dismiss it. The first ghost of a session shows a one-shot `[→ accept]` hint.
+
+| Key | Action |
+| --- | --- |
+| **→** / **Tab** | Accept full ghost (Tab only when no slash-command popup; configure via `PI_GHOST_ACCEPT_KEYS`) |
+| **Ctrl+→** | Accept next word |
+| **Ctrl+↓** | Accept through end of line (incl. newline when present) |
+| **Alt+]** / **Alt+[** | Next / previous candidate |
+| **Esc** | Dismiss ghost |
+| Keep typing | Dismiss |
+
+Run `/ghost keys` anytime for the same cheat-sheet. Temporary mute: `/ghost snooze` (default 5m) or `/ghost snooze 30s` — wake with `/ghost on`.
 
 > **The first session feels "cold."** The trie, cache, and profile all start
 > empty, so every ghost is a fresh LLM call — slower and more generic. It gets
@@ -110,22 +128,28 @@ All knobs are environment variables — no extra config file needed:
 | Variable | Default | Effect |
 | --- | --- | --- |
 | `PI_GHOST_DISABLED` | unset | Set to `1` to disable on launch |
+| `PI_GHOST_HINTS` | on | Set to `off` (or `0`/`false`/`no`) to hide the one-shot `[→ accept]` onboarding suffix on the first ghost |
+| `PI_GHOST_ACCEPT_TAB` | on | Legacy: set to `off` so Tab never accepts (ignored when `PI_GHOST_ACCEPT_KEYS` is set) |
+| `PI_GHOST_ACCEPT_KEYS` | `right,tab` | Comma list of full-accept keys: `right`, `tab` (e.g. `right` only, or `tab,right`) |
 | `PI_GHOST_PROVIDER` | unset (Mercury Edit 2) | `cloud`, `local`, or `router` — set explicitly to switch away from Mercury Edit 2 (ignored when `PI_GHOST_RACE_PROVIDERS` is set). See [Register routing](#register-routing) for `router` |
 | `PI_GHOST_PROVIDER_NAME` | `groq` | Cloud only (`PI_GHOST_PROVIDER=cloud`): any `KnownProvider` from `pi-ai` (`groq`, `cerebras`, `openrouter`, …) |
 | `PI_GHOST_MODEL` | provider-specific | Model id, e.g. `llama-3.1-8b-instant`, `qwen2.5-coder:1.5b` |
 | `PI_GHOST_API_KEY` | env var lookup | Cloud only: explicit API key (else `pi-ai` env lookup is used) |
 | `PI_GHOST_BASE_URL` | `http://localhost:11434` | Local only: Ollama / vLLM base URL |
 | `PI_GHOST_DEBOUNCE_MS` | 150 (cloud) / 400 (local) | Inputs are debounced this long before a request is sent |
+| `PI_GHOST_DEBOUNCE_AGENT_MULT` | `1.5` | Router only: multiplier on the base debounce for `agent-message` register requests (instructions, questions). Longer pause reduces wasted API calls during deliberate typing |
+| `PI_GHOST_DEBOUNCE_PROSE_MULT` | `1.8` | Router only: multiplier on the base debounce for `general-prose` register. Free prose is the most deliberate register — the longest debounce |
 | `PI_GHOST_MAX_TOKENS` | 64 (cloud) / 48 (local) | Cap on completion tokens |
 | `PI_GHOST_RECENT` | 4 (cloud) / 2 (local) | Number of recent user/assistant messages bundled as context |
 | `PI_GHOST_MIN_CHARS` | 3 | Minimum draft length before a prediction fires |
 | `PI_GHOST_MAX_LINE` | 240 | Predictions skipped if the current line exceeds this length |
-| `PI_GHOST_TEMPERATURE` | `0` | Sampling temperature [0, 2]. `0` is best-effort deterministic; see note below |
+| `PI_GHOST_TEMPERATURE` | `0` | Sampling temperature [0, 2] for the FIM / cloud / local legs. `0` is best-effort deterministic; see note below. Does **not** affect the router chat leg — use `PI_GHOST_CHAT_TEMPERATURE` for that |
 | `PI_GHOST_MERCURY_PARALLEL_N` | `1` | Mercury FIM only: fire N parallel candidate completions for cycling. Requires `PI_GHOST_TEMPERATURE > 0` (downgrades silently to 1 at temp=0). Costs scale linearly with N |
 | `PI_GHOST_CHAT_MODEL` | `mercury-2` | Router only: chat model id for the natural-language leg (`/chat/completions`) |
 | `PI_GHOST_CHAT_BASE_URL` | = FIM base URL | Router only: override the chat leg's endpoint base (defaults to the same vendor as the FIM leg) |
 | `PI_GHOST_CHAT_API_KEY` | = Inception/FIM key | Router only: override the chat leg's API key (defaults to the FIM leg's key) |
-| `PI_GHOST_CHAT_MAX_TOKENS` | = `PI_GHOST_MAX_TOKENS` | Router only: cap on chat-leg completion tokens |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Router only: cap on chat-leg completion tokens. Independent of `PI_GHOST_MAX_TOKENS` — Mercury chat consumes budget on internal reasoning before emitting visible content, so it needs far more headroom than code-FIM. At `64` the chat leg returned `content=null` on nearly every request (session 52) |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Router only: chat-leg sampling temperature, independent of `PI_GHOST_TEMPERATURE`. Inception's `/chat/completions` supports `[0.5, 1]`; `0` is silently coerced to `0.75` server-side |
 | `PI_GHOST_CONTEXT_MAX_SCAN` | `200` | M6b: cap on the candidate pool scanned for relevance ranking |
 | `PI_GHOST_CONTEXT_MAX_SELECTED` | `8` | M6b: max number of selected context entries |
 | `PI_GHOST_CONTEXT_MAX_CHARS` | `4000` | M6b: total char budget for the selected context window |
@@ -166,12 +190,33 @@ instruction, a question. A code fill-in-the-middle model (Mercury Edit), fed
 that message, tends to complete it like *code*: it writes the solution instead
 of finishing your sentence. That's the wrong register.
 
-Router mode fixes this by splitting the work between two models by **intent**:
+Router mode fixes this by splitting the work between two models by
+**completion register** (session 52). The register is a coarse classification
+of *what kind of text* the user is composing, derived from the prompt intent
+but language-independent:
 
-| Intent | Leg | Why |
-| --- | --- | --- |
-| `command`, `path-ref`, unclassified | **FIM** (`mercury-edit-2`, `/fim/completions`) | code/command/path drafts — what a code model is good at |
-| `instruction`, `question`, `prose` | **chat** (`mercury-2`, `/chat/completions`) | finishes *your message to the agent* with a persona prompt — "continue the developer's request, don't perform it" |
+| Register | Intents | Leg | System prompt |
+| --- | --- | --- | --- |
+| `code` | `command`, `path-ref`, unclassified | **FIM** (`mercury-edit-2`) | code/command/path completion |
+| `agent-message` | `instruction`, `question` | **chat** (`mercury-2`) | "continue the user's message to an assistant, don't answer" |
+| `general-prose` | `prose` | **chat** (`mercury-2`) | "continue the text naturally, same language/voice" — NO coding-agent framing |
+
+The `general-prose` register (session 52) is the key fix for non-English and
+non-instructional text: it gets a neutral persona that preserves the draft's
+language and voice instead of reframing it as a task instruction. This means
+German, French, Spanish, and other languages are completed in-language without
+being distorted into coding-agent phrasing.
+
+### Multilingual support (session 52)
+
+Intent detection and context tokenization use Unicode-aware word segmentation
+(`Intl.Segmenter`) instead of ASCII-only regexes. This means:
+
+- German umlauts (möchte, ändern, über) count as complete words, not fragments
+- French/Spanish diacritics (café, déjà, función) are preserved
+- CJK text (Chinese/Japanese/Korean) gets dictionary-based word segmentation
+- BM25 context selection works for non-English conversations
+- No fixed English stopword list — IDF handles frequent terms per-language
 
 Both legs default to the same vendor (Inception) and the same key, so a single
 `INCEPTION_API_KEY` is enough. If the chat leg is unreachable or unconfigured,
@@ -242,11 +287,25 @@ PI_GHOST_DEBUG_LOG=1 pi ...      # writes .pi/ghost-autocomplete/debug.jsonl
 
 Metrics records include: timestamp, request id, provider latencies, completion
 mode (`deterministic` or `llm`), result (`produced`, `empty`, `rejected`,
-`aborted`, `error`), rejection reason, completion length, whether the ghost was
+`aborted`, `error`), rejection reason, completion register (`code`,
+`agent-message`, `general-prose`), completion length, whether the ghost was
 shown, and acceptance outcome (`accepted`, `dismissed`, `stale`, `expired`).
 Raw prompt text and LLM output are never written to the metrics file. Both
 files rotate at 10 MB.
 
+When `result` is `empty`, the diagnosed cause is recorded in `emptyReason`:
+
+| Reason | Meaning |
+| --- | --- |
+| `model-empty` | The model returned empty/whitespace-only text |
+| `token-budget-exhausted` | The provider spent its entire `max_tokens` budget on internal reasoning before emitting visible content (Mercury 2 chat). Increase `PI_GHOST_CHAT_MAX_TOKENS` |
+| `sanitizer-null` | The model returned content but the sanitizer rejected it (echo, filename-in-prose, markdown) |
+| `response-schema-error` | The response parsed as JSON but lacked the expected `choices[].message` shape |
+| `http-error` | Missing key, non-2xx, malformed JSON, fetch throw, or timeout |
+
+`pi-ghost-bench` reports an `empty-cause` breakdown so you can distinguish a
+model that declines from one that's starved for tokens.
+
 ## User profile
 
 The extension keeps a long-lived JSONL store at

package/README.pt-BR.md

@@ -0,0 +1,66 @@
+# pi-ghost-autocomplete
+
+[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)
+
+Autocompletar com texto fantasma (« ghost text ») para o [agente de codificação Pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`).
+
+Enquanto você digita no prompt do Pi, um LLM prevê a continuação mais provável
+da linha atual e a exibe em cinza à direita do cursor. Pressione **Seta para
+a direita** para aceitar.
+
+**Multilíngue** (session 52): a segmentação de palavras Unicode lida com
+acentos portugueses, trema alemão, scripts CJK e marcas combinatórias.
+
+## Início rápido
+
+### 1. Obter uma chave de API do Mercury Edit 2
+
+```bash
+export INCEPTION_API_KEY="sua-chave"
+```
+
+### 2. Instalar a extensão
+
+```bash
+pi install npm:pi-ghost-autocomplete
+```
+
+### 3. Iniciar o Pi
+
+```bash
+pi
+```
+
+## Configuração
+
+| Variável | Padrão | Efeito |
+| --- | --- | --- |
+| `PI_GHOST_DISABLED` | não definido | `1` para desativar |
+| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`, `local`, ou `router` |
+| `INCEPTION_API_KEY` | — | Chave de API |
+| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Limite de tokens (chat) |
+| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Temperatura (chat) |
+
+> Consulte o [README em inglês](README.md#configuration) para a referência completa.
+
+## Roteamento por registro
+
+| Registro | Ramo | Prompt do sistema |
+| --- | --- | --- |
+| `code` | **FIM** | Completar código/comando/caminho |
+| `agent-message` | **Chat** | «Continuar a mensagem ao assistente» |
+| `general-prose` | **Chat** | «Continuar o texto naturalmente, mesmo idioma» |
+
+```bash
+PI_GHOST_PROVIDER=router INCEPTION_API_KEY=sua-chave pi ...
+```
+
+## Comandos
+
+| Comando | Efeito |
+| --- | --- |
+| `/ghost` | Mostrar configuração |
+| `/ghost on` | Ativar para esta sessão |
+| `/ghost off` | Desativar para esta sessão |
+
+> Documentação completa: [README em inglês](README.md) e [`docs/`](docs/).