@nklisch/pi-enhanced 0.1.0

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/configuration.md

@@ -0,0 +1,112 @@
+# Configuration
+
+Every setting the package reads, where the file lives, and what happens when a value is
+wrong.
+
+## The config file
+
+```
+~/.config/rpiv-ask-user-question/config.json
+```
+
+The file is optional — with no config at all, every setting takes its default. This
+package only ever *reads* the file; it never creates, writes or chmods it, so its
+permissions are whatever you give it.
+
+A complete example:
+
+```json
+{
+  "collapseKey": "alt+o",
+  "guidance": {
+    "promptSnippet": "Ask me before guessing on anything ambiguous",
+    "promptGuidelines": [
+      "Batch every clarifying question into one ask_user_question call.",
+      "Put your recommended option first and suffix it with (Recommended)."
+    ]
+  }
+}
+```
+
+### Where the file is looked up
+
+1. `$XDG_CONFIG_HOME/rpiv-ask-user-question/config.json`, if `XDG_CONFIG_HOME` is set,
+   non-empty and absolute. A leading `~` is expanded first; a relative value is ignored.
+   Unset or ignored, the directory falls back to `~/.config`.
+2. If that file does not exist, the legacy path `~/.config/rpiv-ask-user-question/config.json`
+   is read. This path deliberately ignores `XDG_CONFIG_HOME`, so an existing config keeps
+   working after you set the variable.
+3. Neither present: all defaults.
+
+If the XDG-path file exists, its result wins even when it is malformed — there is no
+second chance at the legacy path.
+
+### When the file is invalid
+
+Malformed JSON is not fatal. The loader warns on stderr and continues with defaults:
+
+```
+rpiv-config: invalid JSON at <path>, using default ({}) — <parser message>
+```
+
+Valid JSON that is not an object (a string, number, `null`, or an array) is rejected too,
+falling back to defaults — but silently, with no warning. Individual keys with the wrong
+type are likewise dropped back to their default without a warning.
+
+## Settings
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `collapseKey` | Key that collapses and expands the dialog overlay. | `"ctrl+]"` |
+| `guidance.promptSnippet` | One-line snippet describing the tool in the system prompt. | built-in snippet |
+| `guidance.promptGuidelines` | List of usage guidelines given to the model. | 4 built-in guidelines |
+
+### `collapseKey`
+
+The value uses Pi's keybinding id format: zero or more distinct modifiers from `ctrl`,
+`shift`, `alt`, `super`, joined by `+`, followed by a base key. Values are trimmed and
+lowercased before matching.
+
+The base key is either a single printable character from
+`a-z 0-9 _ - ! @ # $ % ^ & * ( ) | ~ \` ' " : ; , . / < > ? [ ] { } = \`, or one of the
+named keys `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`,
+`insert`, `clear`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`,
+`f1`–`f12`.
+
+Examples that work: `"ctrl+]"`, `"alt+o"`, `"ctrl+shift+h"`, `"f9"`, `"ctrl+}"`.
+
+Set `"off"` (any casing) to disable the collapse shortcut entirely — no raw terminal
+listener is registered in that case.
+
+A spec that does not match the grammar is rejected and the default is used. This is
+strict on purpose: Pi's parser takes the last `+`-separated part as the key and ignores
+unknown parts, so a typo like `"ctr+]"` would otherwise silently capture every bare `]`
+keypress at the terminal level.
+
+One known rough edge: the footer hint line inside the dialog always reads `Ctrl+] to
+collapse` and does not interpolate a custom `collapseKey`. The one-shot notification you
+get when the dialog first collapses *does* name your configured key.
+
+### `guidance.promptSnippet` and `guidance.promptGuidelines`
+
+These replace the text Pi puts in the system prompt about when to reach for
+`ask_user_question`. Use them to make the model ask more or less often, or to enforce a
+house style for options.
+
+`promptSnippet` is used only when it is a non-empty string. `promptGuidelines` is used
+only when it is a non-empty array whose entries are all non-empty strings. Anything else
+falls back to the built-in defaults. Both are read once, when the extension registers the
+tool, so changes take effect on the next Pi restart.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `XDG_CONFIG_HOME` | Relocates the config directory, as described above. Must be absolute. |
+
+`LANG` and `LC_ALL` influence the dialog language, but they are read by
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) rather than
+by this package — see [localization.md](./localization.md).
+
+No other environment variables are read. The package makes no model calls, so it needs no
+API keys or model settings of its own.

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/hosts.md

@@ -0,0 +1,87 @@
+# Hosts and runtime behavior
+
+Where the questionnaire renders, what it degrades to, and what happens when it cannot
+render at all.
+
+## Three environments
+
+| Environment | What the model sees | What you see |
+| --- | --- | --- |
+| Interactive terminal | `ask_user_question` in its tool list | The full tabbed TUI overlay |
+| RPC / ACP host (VS Code pendant, Zed, Paseo) | `ask_user_question` in its tool list | A sequence of the host's own native select and input dialogs |
+| Non-interactive run (no UI) | Nothing — the tool is removed | Nothing |
+
+### Non-interactive runs
+
+A `before_agent_start` hook reconciles the active tool set against `ctx.hasUI` before every
+turn. When there is no UI, `ask_user_question` is stripped from the list so the model never
+sees a tool it cannot use — better than offering it and auto-declining every call. When UI
+comes back, the tool is restored. The reconciler is idempotent and leaves sibling tools
+untouched.
+
+A second guard lives inside the tool handler as a one-turn backstop: if a call somehow
+arrives without UI, it returns `error: "no_ui"` and the text
+`Error: UI not available (running in non-interactive mode)`.
+
+### RPC and ACP hosts
+
+RPC hosts report `hasUI: true` because Pi's dialog sub-protocol works there, but custom
+terminal UI does not render. The package detects this two ways: hosts that advertise
+`ctx.mode === "rpc"` route straight to the dialog walker, skipping the TUI import
+entirely, and older RPC builds are caught by a backstop when custom UI resolves without
+rendering anything. Either path requires the host to expose both `select` and `input`.
+
+The walker asks one question per dialog and returns exactly the same result envelope the
+TUI produces. Trade-offs inherent to the native primitives:
+
+- No side-by-side preview pane. Previews are folded into the dialog title instead,
+  truncated at 600 characters each.
+- No tab bar and no Submit review tab — one dialog per question, in order.
+- Multi-select is a free-text input: type the option numbers, comma-separated
+  (`1,3`). Any token that is not a valid option index is treated as a typed custom answer,
+  which is how the `Type something.` escape survives. An empty input commits an empty
+  selection, matching `Next` with nothing toggled.
+- Dismissing any dialog cancels the whole questionnaire, mirroring `Esc` in the TUI.
+
+If the host can render neither custom UI nor dialogs, the call returns
+`error: "no_custom_ui"` with text telling the model the user never saw the questions and
+that it should ask them as plain chat text instead — explicitly not a decline.
+
+## Conditional surfaces
+
+Some parts of the dialog exist only under the right conditions:
+
+| Surface | Appears when |
+| --- | --- |
+| Tab bar and Submit tab | The call carries more than one question |
+| `Next` row | The question is multi-select |
+| `Type something.` row | Always |
+| Side-by-side preview | An option carries a `preview`, and terminal and pane are both ≥ 100 columns |
+| Preview pane at all | Single-select questions only |
+| Collapse shortcut | `collapseKey` is not `"off"` and the host exposes raw terminal input |
+| Localized chrome | `@juicesharp/rpiv-i18n` is installed |
+
+## Loading and startup cost
+
+The dialog's render graph costs roughly 560 ms to import, so it is loaded lazily — on the
+first tool call, not when the extension registers. To keep that first call fast and safe,
+the graph is also pre-warmed in the background two seconds after startup. The pre-warm
+timer is unref'd, so it never holds a process open, and a failed pre-warm is swallowed:
+the first real call re-imports and reports properly.
+
+The pre-warm exists for a specific failure. Pi's module loader registers a module in its
+graph cache *before* evaluating it and does not evict it if evaluation throws. If your
+package manager replaces the dependency store while Pi is running, one failed import can
+poison the cache for the rest of the process. Evaluating the graph early, while the paths
+Pi resolved at boot still exist, keeps it in memory for the process lifetime and makes
+that unreachable.
+
+When it does happen, you get a structured envelope rather than a raw `TypeError`:
+
+| `error` | Meaning | Fix |
+| --- | --- | --- |
+| `session_load_failed` | The dialog module could not be imported. | Repair the install if needed, then restart Pi. |
+| `stale_module_cache` | The module cache went stale after an earlier failed import. | Restart Pi — this is unrecoverable in the running process. |
+
+Both messages tell the model the questions were never shown and to ask them as plain chat
+text instead of treating the failure as a decline.

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/keyboard.md

@@ -0,0 +1,87 @@
+# Keyboard and dialog layout
+
+Every key the questionnaire dialog reacts to, the rows it appends for you, and how it
+adapts to the size of your terminal.
+
+## Keys
+
+| Key | What it does | Where it applies |
+| --- | --- | --- |
+| `↑` / `↓` | Move between rows. Wraps at both ends. | Option list, Submit picker |
+| `Enter` | Confirm the focused option, commit typed text, or activate the focused Submit-picker row. | Everywhere |
+| `Esc` | Cancel the whole questionnaire. | Everywhere except the notes editor, where it closes notes |
+| `Tab` / `Shift+Tab` | Next / previous tab, wrapping. `→` / `←` do the same. | Multi-question dialogs only |
+| `Space` | Toggle the focused checkbox. | Multi-select questions |
+| `n` | Open the notes editor for the current question. | Every question tab |
+| `Ctrl+]` | Collapse or expand the dialog. Configurable via `collapseKey`. | Everywhere, including while collapsed |
+
+In a multi-select question, `Enter` on a regular row toggles its checkbox exactly like
+`Space` — it does not submit. Committing the question means focusing the `Next` row and
+pressing `Enter`. That is deliberate: it makes `Enter` a zero-cost way to flip boxes
+without leaving the home row.
+
+`Space` is suppressed on two rows: `Next` (it is a command, not a choice) and
+`Type something.` (it is an inline text input, so the space character belongs to your
+answer).
+
+## The rows the dialog adds
+
+| Row | Label | Appended to |
+| --- | --- | --- |
+| Custom answer | `Type something.` | Every question — single-select and multi-select, with or without previews |
+| Commit | `Next` | Multi-select questions only |
+
+Focusing `Type something.` switches the row into an inline text input. In preview mode it
+expands to the full pane width while you type, so a long custom answer is not squeezed
+into the narrow options column. Confirming it produces an answer of `kind: "custom"`.
+
+Both labels are reserved — the model cannot author an option that collides with them.
+Both localize with the rest of the UI chrome; the reserved-label check always compares
+against the canonical English strings.
+
+## Notes
+
+`n` opens a notes editor on any question tab, whether the question is single- or
+multi-select and whether or not its options carry previews. Notes are stored in a
+side-band keyed by tab index, not inside the answer, so writing a note does not mark a
+question as answered — the Submit tab still lists it as outstanding. The note merges into
+the answer when you confirm it, and reaches the model as `user notes: <text>`.
+
+Inside the editor, `Esc` and `Enter` both close it and every other keystroke goes to the
+text buffer, so `n` types an `n`.
+
+## Collapse mode
+
+`Ctrl+]` gets the dialog out of the way: the overlay is marked hidden in Pi's overlay
+stack and shrinks to a single dim hint row, so the transcript it was covering becomes
+readable and chat scrolling resumes. Press the same key to bring the questionnaire back
+with your answers intact. The first time you collapse, Pi notifies you with the key to
+press — that message names your configured key.
+
+Because Pi routes no input to a hidden overlay, the collapse key is additionally captured
+at the raw terminal level. It only acts when the questionnaire is hidden or focused, so a
+different overlay on top of it (for example `/btw`) keeps its keystrokes.
+
+While collapsed, every keystroke other than cancel is ignored, so you cannot mutate
+answers you cannot see.
+
+The default `ctrl+]` is free in Terminal.app, iTerm2, Warp, tmux, zellij and screen. On
+keyboard layouts where `]` sits on the shifted layer — Latin American `es-AR` / `es-MX`,
+among others — set a different `collapseKey`, or `"off"` to disable the shortcut.
+
+## Layout
+
+Options render in a vertical list. When any option in a single-select question carries a
+`preview`, the dialog splits into a side-by-side layout with the option list on the left
+and a bordered monospace preview box on the right — but only when both the terminal and
+the dialog pane are at least 100 columns wide. Below that, the preview stacks underneath
+the options instead.
+
+When the dialog is taller than the terminal, the body scrolls between a sticky heading and
+a sticky footer, and an overflow indicator shows which direction is clipped: `↑` for
+content above, `↓` for content below, `↕` for both.
+
+The footer hint line adapts to context — it drops the notes hint while the notes editor or
+the inline input has the keyboard, and adds the tab hint only in multi-question dialogs.
+On narrow terminals the collapse hint at the end of the line clips with `…` so the core
+hints survive.

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/localization.md

@@ -0,0 +1,83 @@
+# Localization
+
+How the dialog picks its language, which languages ship, and how to add one.
+
+## Enabling it
+
+The extension works standalone: install only this package and you get the full dialog in
+English. Localization needs one more install:
+
+```sh
+pi install npm:@juicesharp/rpiv-i18n
+```
+
+Restart your Pi session. If you installed through
+[`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) and ran
+`/rpiv-setup`, you already have it.
+
+The dependency is a genuinely optional peer. This package loads the SDK inside a
+`try`/`catch` at startup; when it is absent, every string falls back to its inline English
+literal at the call site. There is no warning and no crash — the dialog simply renders in
+English.
+
+## Picking a language
+
+With the SDK installed, the locale resolves in this order, first hit wins:
+
+1. `pi --locale <code>` on the command line
+2. `~/.config/rpiv-i18n/locale.json`
+3. `LANG` / `LC_ALL` from the environment
+4. English
+
+`/languages` opens an interactive picker and flips the strings live — the dialog reads its
+strings at render time, so an open questionnaire follows the change. Both `/languages` and
+`--locale` are registered by `@juicesharp/rpiv-i18n`, not by this package.
+
+## Shipped languages
+
+Nine locale files ship in `locales/`:
+
+| Code | Language |
+| --- | --- |
+| `de` | Deutsch |
+| `en` | English |
+| `es` | Español |
+| `fr` | Français |
+| `pt` | Português |
+| `pt-BR` | Português (Brasil) |
+| `ru` | Русский |
+| `uk` | Українська |
+| `zh` | 中文 |
+
+## What is translated, and what is not
+
+Translation covers the chrome you read: the `Type something.` and `Next` sentinel rows,
+the footer hint segments (including the collapsed-state line), the Submit picker labels,
+the review-tab heading with its submit-readiness prompt and incomplete-answers warning, the
+preview pane's empty and notes-affordance lines, the notes header, and the two RPC dialog
+prompts. Twenty keys in total, all under the namespace
+`@juicesharp/rpiv-ask-user-question`.
+
+Everything the *model* reads stays English by design: the tool description, the parameter
+schema descriptions, error messages, and the reserved-label list. Those are prompt inputs,
+not UI, and translating them would change model behavior rather than your reading
+experience. It also means reserved-label validation compares against fixed English
+strings, so `Type something.` is rejected as an authored option label in every locale.
+
+## Adding a language
+
+No code change is required.
+
+1. Copy `locales/en.json` to `locales/<code>.json`, where `<code>` is a locale the SDK
+   supports.
+2. Translate the values. Keep every key, and keep the placeholders and leading symbols
+   (`↑/↓`, `⚠`) intact.
+3. Restart Pi and select the language with `/languages`.
+
+The loader iterates the SDK's supported-locale list over this directory at startup, so a
+new file is picked up automatically. See the
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) README,
+section "Contributing translations", for the full convention.
+
+Keys are looked up individually with an English fallback, so a partially translated file
+is safe — untranslated keys render in English rather than blank.

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/tool-schema.md

@@ -0,0 +1,121 @@
+# Tool schema
+
+The complete programmatic surface of `ask_user_question`: what the model sends, what
+validation rejects, what comes back, and the event other extensions can listen to.
+
+## Parameters
+
+```ts
+ask_user_question({
+  questions: [
+    {
+      question: string,            // full question text, ends with "?"
+      header: string,              // chip label, max 16 chars
+      options: [
+        {
+          label: string,           // 1-5 words, max 60 chars
+          description: string,     // what the choice means / its trade-off
+          preview?: string,        // markdown rendered next to the options
+        },
+        // … 2-4 options total
+      ],
+      multiSelect?: boolean,       // default false
+    },
+    // … 1-4 questions total
+  ]
+})
+```
+
+### Limits
+
+| Field | Constraint | Enforced by |
+| --- | --- | --- |
+| `questions` | 1-4 entries | TypeBox schema + `validateQuestionnaire` |
+| `questions[].header` | max 16 characters | TypeBox schema only |
+| `questions[].options` | 2-4 entries | TypeBox schema (both bounds) + `validateQuestionnaire` (minimum only) |
+| `options[].label` | max 60 characters | TypeBox schema only |
+| `options[].preview` | single-select questions only | tool description (multi-select tabs render checkbox rows) |
+
+The two `maxLength` limits are checked by the parameter schema before `execute` runs;
+the runtime validator does not re-check them.
+
+### Reserved option labels
+
+Authoring any of `"Other"`, `"Type something."`, or `"Next"` as an option label is
+rejected with `reserved_label`. The last two are the runtime sentinel rows the dialog
+appends itself; `"Other"` is reserved because models are conditioned to reach for it.
+Reservation is unconditional — a single-select question rejects `"Next"` even though
+that row is never appended there.
+
+## Validation errors
+
+Every rejection returns `cancelled: true`, an empty `answers` array, and an `error`
+code. The `content[0].text` string is written for the model, not for a log.
+
+| `error` | Cause |
+| --- | --- |
+| `no_questions` | `questions` was empty |
+| `too_many_questions` | more than 4 questions in one call |
+| `duplicate_question` | two questions with identical text |
+| `empty_options` | a question carried fewer than 2 options |
+| `reserved_label` | an option used a reserved label |
+| `duplicate_option_label` | two options in one question share a label |
+| `no_ui` | the run has no UI (`ctx.hasUI === false`) |
+| `no_custom_ui` | the host cannot render custom UI and exposes no `select`/`input` dialogs |
+| `session_load_failed` | the dialog module failed to import (dependencies changed on disk mid-session) |
+| `stale_module_cache` | the loader cached a broken module after an earlier failed import; needs a Pi restart |
+
+`reserved_label` short-circuits before `duplicate_option_label`.
+
+## Result
+
+```ts
+{
+  content: [{ type: "text", text: string }], // envelope prose, or the decline message
+  details: {
+    answers: Array<{
+      questionIndex: number,
+      question: string,
+      kind: "option" | "custom" | "multi",
+      answer: string | null,       // option label, typed text, or null for multi
+      selected?: string[],         // chosen labels, multi-select only
+      notes?: string,              // free-text note, when you wrote one
+      preview?: string,            // echoed back when the chosen option carried a preview
+    }>,
+    cancelled: boolean,
+    error?: QuestionnaireError,    // one of the codes above
+  }
+}
+```
+
+### Envelope text
+
+On success the text reads `User has answered your questions: "<question>"="<answer>". …
+You can now continue with the user's answers in mind.` A chosen option's `preview` is
+appended as `selected preview: <markdown>`, and a note as `user notes: <text>`.
+
+Cancelling, and any result that produces no answer segments, both collapse to the single
+string `User declined to answer questions` so the model sees one canonical signal.
+Partial submission is allowed: unanswered questions simply contribute no segment.
+
+## Event contract
+
+The package publishes one event on Pi's event bus, emitted after validation passes and
+before the dialog is shown. Import it from the `/events` subpath:
+
+```ts
+import { ASK_USER_PROMPT_EVENT, type AskUserPromptEventPayload } from "@juicesharp/rpiv-ask-user-question/events";
+
+pi.events.on(ASK_USER_PROMPT_EVENT, (payload: AskUserPromptEventPayload) => {
+  // payload.questions[].{ question, header, multiSelect, options[] }
+  // payload.questions[].options[].{ label, description, hasPreview }
+});
+```
+
+The channel name is `rpiv:ask-user:prompt`. Preview *content* is deliberately not shipped
+in the payload — only `hasPreview: boolean` — so listeners forwarding the event across a
+process or network boundary stay cheap.
+
+Stability policy for the `rpiv:*` namespace: channel names are immutable, payload changes
+are append-only and always optional, payloads stay JSON-safe, and any breaking change ships
+as a new channel (e.g. `rpiv:ask-user:prompt.v2`) rather than a version field.

package/node_modules/@juicesharp/rpiv-ask-user-question/events.ts

@@ -0,0 +1,55 @@
+/**
+ * Public event contract for @juicesharp/rpiv-ask-user-question.
+ *
+ * STABILITY POLICY — applies to every event in the `rpiv:*` namespace.
+ *
+ *   1. Channel names are immutable. Once shipped, never rename.
+ *   2. Payload changes are append-only. Listeners MUST tolerate unknown
+ *      fields. New fields ship as optional (`?:`).
+ *   3. Breaking changes (rename, retype, remove a field; change emission
+ *      semantics) require a NEW channel, e.g. `rpiv:ask-user:prompt.v2`,
+ *      with dual-emit during a deprecation window.
+ *   4. No `version` field inside payloads. Version via channel name only.
+ *   5. Payloads must be JSON-safe: primitives, arrays, plain objects.
+ *      No Set/Map/Date/class instances — payloads must survive JSON
+ *      serialization when listeners forward them across process or
+ *      network boundaries.
+ *
+ * Naming: `rpiv:<package-or-tool>:<phase>`, lowercase, hyphen-separated.
+ * Aligns with Pi's `"my-extension:status"` example and UniPi's `unipi:*`.
+ */
+
+export const ASK_USER_PROMPT_EVENT = "rpiv:ask-user:prompt" as const;
+
+export interface AskUserPromptEventPayload {
+	questions: ReadonlyArray<AskUserPromptQuestion>;
+}
+
+/**
+ * Emitted while the questionnaire is awaiting user input (TUI `ui.custom` and
+ * RPC dialog walker). Cleared with `{ active: false }` in `finally` so listeners
+ * can distinguish blocked-on-human from working.
+ */
+export const ASK_USER_BLOCKED_EVENT = "rpiv:ask-user:blocked" as const;
+
+export interface AskUserBlockedEventPayload {
+	/** True while input is awaited; false when the wait ends (answer, cancel, or error). */
+	active: boolean;
+}
+
+export interface AskUserPromptQuestion {
+	/** The full question text, exactly as the agent authored it. */
+	question: string;
+	/** The short chip/tag shown next to the question. */
+	header: string;
+	/** True iff the user may pick multiple options. Normalized from optional. */
+	multiSelect: boolean;
+	options: ReadonlyArray<AskUserPromptOption>;
+}
+
+export interface AskUserPromptOption {
+	label: string;
+	description: string;
+	/** True iff the option carries rich preview content (content not shipped). */
+	hasPreview: boolean;
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/index.ts

@@ -0,0 +1,54 @@
+/**
+ * rpiv-ask-user-question — Pi extension. Registers the `ask_user_question`
+ * tool: a structured option selector with an automatically appended
+ * `Type something.` custom-answer row.
+ *
+ * Sentinel labels and TUI chrome strings localize at render time via the i18n
+ * bridge. Strings are registered with rpiv-i18n here, once, at module init —
+ * but only when the SDK is actually installed. If `@juicesharp/rpiv-i18n` is
+ * missing (standalone install of just this package), the dynamic-load shim
+ * no-ops and the bridge's `t(key, fallback)` returns the inline English literal
+ * at every call site. The extension stays online either way.
+ *
+ * Adding a locale: drop `locales/<code>.json` next to en.json (mirroring the
+ * key set). No edit needed here — `registerLocalesFromDir` iterates
+ * `SUPPORTED_LOCALES` from the SDK. See `@juicesharp/rpiv-i18n` README →
+ * "Contributing translations" for the full convention.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskUserQuestionTool } from "./ask-user-question.js";
+import { registerAskUserQuestionReconciler } from "./reconcile.js";
+import { I18N_NAMESPACE } from "./state/i18n-bridge.js";
+
+type I18nLoader = {
+	registerLocalesFromDir: (namespace: string, packageUrl: string, options?: { label?: string }) => void;
+};
+
+// Dynamic import keeps `@juicesharp/rpiv-i18n` a soft optional peer: when the
+// SDK is installed alongside this package the strings register and
+// `/languages` flips them live; when it isn't, the import rejects here, we
+// no-op, and the bridge's English-fallback shim keeps the extension online.
+//
+// The `/loader` subpath is used instead of the SDK entry so the i18n-ui +
+// pi-tui modules are not pulled into our load graph just to register strings.
+try {
+	const sdk = (await import("@juicesharp/rpiv-i18n/loader")) as I18nLoader;
+	sdk.registerLocalesFromDir(I18N_NAMESPACE, import.meta.url, { label: "rpiv-ask-user-question" });
+} catch {
+	// SDK absent — extension still loads with English-only UI.
+}
+
+export {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+	type AskUserPromptOption,
+	type AskUserPromptQuestion,
+} from "./events.js";
+
+export default function (pi: ExtensionAPI) {
+	registerAskUserQuestionTool(pi);
+	registerAskUserQuestionReconciler(pi);
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/de.json

@@ -0,0 +1,27 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Schreibe etwas.",
+  "sentinel.next": "Weiter",
+
+  "submit.label": "Antworten senden",
+  "submit.cancel": "Abbrechen",
+
+  "hint.enter": "Enter zum Auswählen",
+  "hint.navigate": "↑/↓ zur Navigation",
+  "hint.toggle": "Leertaste zum Umschalten",
+  "hint.notes": "n für Notizen",
+  "hint.tab": "Tab wechselt die Frage",
+  "hint.cancel": "Esc zum Abbrechen",
+
+  "review.heading": "Antworten überprüfen",
+  "review.ready": "Bereit, deine Antworten zu senden?",
+  "review.incomplete": "⚠ Beantworte die verbleibenden Fragen vor dem Senden:",
+
+  "preview.no_preview": "Keine Vorschau verfügbar",
+  "preview.notes_affordance": "Notizen: drücke n, um Notizen hinzuzufügen",
+  "notes.header": "Notizen:",
+
+  "rpc.multi_instructions": "Gib die Nummern aller zutreffenden Optionen durch Komma getrennt ein (z. B. \"1,3\") oder tippe eine eigene Antwort als Text.",
+  "rpc.custom_answer_title": "Gib deine Antwort ein:"
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/en.json

@@ -0,0 +1,27 @@
+{
+  "sentinel.other": "Type something.",
+  "sentinel.next": "Next",
+
+  "submit.label": "Submit answers",
+  "submit.cancel": "Cancel",
+
+  "hint.enter": "Enter to select",
+  "hint.navigate": "↑/↓ to navigate",
+  "hint.toggle": "Space to toggle",
+  "hint.notes": "n to add notes",
+  "hint.tab": "Tab to switch questions",
+  "hint.collapse": "Ctrl+] to collapse",
+  "hint.expand_line": "Ctrl+] to expand · Esc to cancel",
+  "hint.cancel": "Esc to cancel",
+
+  "review.heading": "Review your answers",
+  "review.ready": "Ready to submit your answers?",
+  "review.incomplete": "⚠ Answer remaining questions before submitting:",
+
+  "preview.no_preview": "No preview available",
+  "preview.notes_affordance": "Notes: press n to add notes",
+  "notes.header": "Notes:",
+
+  "rpc.multi_instructions": "Enter the numbers of all that apply, comma-separated (e.g. \"1,3\"), or type a custom answer as plain text.",
+  "rpc.custom_answer_title": "Type your answer:"
+}