promptdock 1.0.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prompt Dock, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -53,10 +53,29 @@ Install options: `-g/--global` (per-user dir), `--target <tool>`, `--dir <path>`
 | `kimi` | `.kimi/skills/<slug>/` | `~/.kimi/skills/<slug>/` | experimental |
 | `openai` (OpenAI/GPT) | `.openai/skills/<slug>/` | `~/.openai/skills/<slug>/` | experimental |
 
-Tools detected in your project (or home dir with `-g`) float to the top of the
-picker and are preselected. `--dir <path>` installs anywhere. After installing,
-**restart/reopen the tool** — most agents only scan skills at session start
-(Claude Code: start a *new* session, then type `/<slug>`).
+Interactively, `install` asks **two** questions:
+
+1. **Which tool** — tools already set up (in either scope) float to the top,
+   tagged with where they were found; the first is preselected.
+2. **This directory or your user account** — shown as the two real destination
+   paths, preselecting whichever scope the tool is already set up in.
+
+Both prompts (and every confirm) are **arrow-key driven**: `↑`/`↓` to move
+(`j`/`k` and `^p`/`^n` work too), `Enter` or `Space` to select, `Esc` to cancel
+(`Ctrl-C` exits `130`, the shell convention). Yes/No confirms also take **`y`
+and `n` directly** — they commit immediately, never fall through to a default.
+**Typing a number still works** — it moves the highlight as you type, `Enter`
+confirms, `Backspace` edits. A pipe or CI session never prompts at all (pass
+`--target`/`--dir` + `-y`); a terminal without raw-mode/ANSI support
+(`TERM=dumb`) gets the plain numbered reader.
+
+Shortcuts: `-g` answers question 2 up front (per-user install, no prompt);
+`--target <tool>` answers question 1; `--dir <path>` answers both and installs
+anywhere. `-y` and non-interactive sessions never prompt and stay
+**project-local** unless `-g` is passed.
+
+After installing, **restart/reopen the tool** — most agents only scan skills at
+session start (Claude Code: start a *new* session, then type `/<slug>`).
 
 ## CI / non-interactive use
 
@@ -107,6 +126,7 @@ path is re-validated before any write; a failed check aborts **all-or-nothing**
 | 4 | integrity (sha mismatch, unsafe manifest path, receipt schema) |
 | 5 | filesystem (permissions, disk space, non-empty directory) |
 | 6 | network |
+| 130 | interrupted (`Ctrl-C` during an interactive prompt; `Esc` — a deliberate in-UI cancel — exits 1) |
 
 Every named error links `https://promptdock.ai/docs/cli/errors#<code>`.
 
@@ -118,3 +138,16 @@ Every named error links `https://promptdock.ai/docs/cli/errors#<code>`.
   Review is a screening step, not a warranty — read what you install.
 - Skills are plain files on your machine after install; premium gates access,
   not copying.
+
+## License
+
+[MIT](./LICENSE) © Prompt Dock, Inc.
+
+Scope: the MIT license covers **this package (`packages/cli/`) only** — the CLI
+client source published to npm. It does not cover the PromptDock service, the
+website, or the rest of the repository, which are proprietary.
+
+It also does not cover **the skills you install**. Those are third-party content
+licensed by their authors under the
+[PromptDock Terms](https://promptdock.ai/terms) — installing a skill grants you
+access to use it, not the rights this MIT license grants over the CLI itself.

package/dist/api.js

@@ -1,12 +1,41 @@
+import { DEFAULT_API_BASE } from "./config.js";
 import { CliError, EXIT, networkError } from "./errors.js";
-/** Origin of a Location header, for the "set PROMPTDOCK_API_BASE to …" hint. */
-function originOf(location) {
+/**
+ * The redirect target may only become an ACTIONABLE hint when it is trustworthy
+ * (review CRITICAL): a 3xx can come from a captive portal, hijacked DNS, or a
+ * MITM proxy, and the old hint rendered its Location verbatim as a
+ * copy-pasteable `PROMPTDOCK_API_BASE=<attacker origin>` instruction — the
+ * commit that fixed redirect-STRIPS-Authorization had introduced
+ * redirect-HANDS-OVER-Authorization. Trust rule: https only, AND the same
+ * registrable domain as the origin we were already talking to (apex↔www and
+ * sibling subdomains pass; anything else gets the STATIC default hint).
+ */
+function trustedRedirectOrigin(location, baseUrl) {
     try {
-        return new URL(location).origin;
+        const to = new URL(location);
+        if (to.protocol !== "https:")
+            return null;
+        const base = new URL(baseUrl);
+        const tail = (h) => h.split(".").slice(-2).join(".");
+        if (tail(to.hostname) !== tail(base.hostname))
+            return null;
+        return to.origin;
     }
     catch {
-        return null; // relative Location — can't name an origin, fall back to the default
+        return null; // relative/unparseable Location — never actionable
+    }
+}
+/** Strip control chars (incl. ESC) before a server-supplied string reaches the
+ *  terminal — a Location carrying ANSI sequences could rewrite what the user
+ *  sees (review find). */
+function sanitizeForTerminal(s) {
+    let out = "";
+    for (const ch of s) {
+        const c = ch.codePointAt(0) ?? 0;
+        if (c >= 0x20 && c !== 0x7f && !(c >= 0x80 && c <= 0x9f))
+            out += ch;
     }
+    return out.slice(0, 200);
 }
 export class Api {
     ctx;
@@ -53,8 +82,13 @@ export class Api {
         // ctx.fetch directly and must keep following them — storage hands out redirects.
         if (res.status >= 300 && res.status < 400) {
             const to = res.headers.get("location") ?? "(no location header)";
-            throw new CliError(`${this.baseUrl} redirected to ${to} — the API must be called on its canonical origin, because a redirect drops the request body and the login token.`, EXIT.NETWORK, {
-                hint: `set PROMPTDOCK_API_BASE to the redirect target, e.g. PROMPTDOCK_API_BASE=${originOf(to) ?? "https://www.promptdock.ai"}`,
+            throw new CliError(`${this.baseUrl} redirected to ${sanitizeForTerminal(to)} — the API must be called on its canonical origin, because a redirect drops the request body and the login token.`, EXIT.NETWORK, {
+                // An UNTRUSTED target (cross-domain / non-https — a captive portal or
+                // MITM can mint a 3xx) gets the STATIC known-good hint, never its own
+                // origin echoed back as an instruction. DEFAULT_API_BASE is imported,
+                // not re-typed: the hardcoded literal here was a second copy of the
+                // exact constant whose staleness caused the original apex outage.
+                hint: `set PROMPTDOCK_API_BASE to the canonical origin, e.g. PROMPTDOCK_API_BASE=${trustedRedirectOrigin(to, this.baseUrl) ?? DEFAULT_API_BASE}`,
                 footer: "api",
             });
         }

package/dist/auth.js

@@ -30,8 +30,14 @@ export async function deviceFlowLogin(ctx, baseUrl, opts) {
             ctx.io.out("(if the page didn't open, paste the URL into your browser)");
         }
         ctx.io.out("");
-        const deadline = ctx.now() + Math.max(1, start.expires_in) * 1000;
-        let intervalSecs = Math.max(0, Number(start.interval) || 0);
+        // Clamp through Number.isFinite (review find): a missing/renamed numeric in
+        // the start response made `deadline` NaN, and `remainMs <= 0` is FALSE for
+        // NaN — an infinite countdown spin. A malformed numeric now degrades to the
+        // protocol defaults instead of hanging the login.
+        const expiresIn = Number(start.expires_in);
+        const deadline = ctx.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 600) * 1000;
+        const interval0 = Number(start.interval);
+        let intervalSecs = Number.isFinite(interval0) && interval0 > 0 ? interval0 : 5;
         poll: for (;;) {
             if (ctx.now() >= deadline)
                 break poll; // local expiry — restart below
@@ -61,7 +67,22 @@ export async function deviceFlowLogin(ctx, baseUrl, opts) {
                     footer: "access_denied",
                 });
             }
-            break poll; // expired_token (or unknown) — restart below
+            if (verb === "expired_token")
+                break poll; // genuine expiry — restart below
+            // NOT an RFC verb (review find): the wrapper's own limiter answers this
+            // route in the app ENVELOPE ({error:{code,…}} — e.g. rate_limited when
+            // several devs share one NAT), and a 500 arrives enveloped too. Both used
+            // to collapse into "expired" → a restart → "login timed out", hiding the
+            // real cause. Surface the truth instead of calling it a timeout.
+            const env = Api.envelope(res.body);
+            if (env) {
+                const retryAfter = Number(res.headers.get("retry-after"));
+                const wait = env.code === "rate_limited" && Number.isFinite(retryAfter) && retryAfter > 0
+                    ? ` — retry in ~${Math.ceil(retryAfter)}s`
+                    : "";
+                throw new CliError(`login failed: ${env.message}${wait}`, res.status >= 500 ? EXIT.NETWORK : EXIT.DENIED, { footer: "api" });
+            }
+            break poll; // genuinely unrecognized body — restart below
         }
         clearCountdown(ctx);
         restarts += 1;

package/dist/commands/install.d.ts

@@ -1,2 +1,9 @@
 import type { CliContext } from "../context.js";
+import { type SkillRef } from "../ref.js";
 export declare function runInstall(ctx: CliContext, positionals: string[], flags: Record<string, string | boolean>): Promise<void>;
+type PickedTarget = {
+    id: string;
+    dir: string;
+};
+export declare function resolveTarget(ctx: CliContext, flags: Record<string, string | boolean>, ref: SkillRef): Promise<PickedTarget>;
+export {};

package/dist/commands/install.js

@@ -8,7 +8,7 @@ import { ensureAuth } from "../auth.js";
 import { CliError, EXIT, usageError } from "../errors.js";
 import { checkInstallResponse, performInstall } from "../installer.js";
 import { formatRef, parseSkillRef } from "../ref.js";
-import { detectTargets, nextStepLine, targetById, targetInstallDir, TARGETS, } from "../registry.js";
+import { detectionLabel, detectTargets, detectTargetsAnyScope, nextStepLine, scopeChoices, targetById, targetInstallDir, TARGETS, } from "../registry.js";
 import { readReceipt } from "../receipts.js";
 import { colors, confirm, formatBytes, promptSelect } from "../ui.js";
 import { assertInstallable } from "../verdicts.js";
@@ -102,7 +102,7 @@ export async function runInstall(ctx, positionals, flags) {
         }
         for (const line of summary)
             ctx.io.out(line);
-        const go = await confirm(ctx.io, isUpdate ? "Update?" : "Install?", true);
+        const go = await confirm(ctx.io, isUpdate ? "Update?" : "Install?", true, c);
         if (!go) {
             ctx.io.out("Cancelled — nothing installed.");
             return;
@@ -144,9 +144,47 @@ export async function runInstall(ctx, positionals, flags) {
     ctx.io.out(`${c.green("✓")} ${isUpdate ? "Updated" : "Installed"} "${resp.skill.title}" v${resp.skill.version} → ${picked.dir}`);
     ctx.io.out(nextStepLine(picked.id, resp.skill.slug));
 }
-async function resolveTarget(ctx, flags, ref) {
-    const global = flags.global === true;
+/**
+ * Project-vs-global, asked AFTER the tool is known so the two options can be
+ * shown as their real destination paths rather than an abstraction.
+ *
+ * Never prompts when the answer is already settled: `-g` IS the answer, and
+ * `-y`/non-TTY runs are contractually promptless (they keep the flag default,
+ * project-local). So the prompt appears exactly when a human is present and
+ * scope is genuinely unstated — which is where it used to be skipped silently.
+ */
+async function resolveScope(ctx, def, ref, opts) {
+    if (opts.scopeGiven || opts.yes || !ctx.io.isTTY)
+        return opts.global;
+    const { choices, preselect } = scopeChoices(def, {
+        cwd: ctx.cwd,
+        home: ctx.home,
+        slug: ref.slug,
+    });
+    // Standing in $HOME, "this project" and "global" are the SAME directory —
+    // a two-row prompt showing one path twice reads as a bug (review find).
+    // The answer is settled: skip the question.
+    if (choices[0].dir === choices[1].dir)
+        return opts.global;
+    // Display dirs ~-abbreviated: full absolute paths wrap a stock 80-col
+    // terminal, and a wrapped line desyncs the picker's in-place repaint.
+    // The RETURNED dir stays absolute — only the label is shortened.
+    const tildify = (d) => (d.startsWith(ctx.home) ? `~${d.slice(ctx.home.length)}` : d);
+    const idx = await promptSelect(ctx.io, `Install ${def.label} skill in this directory or for your user account?`, choices.map((c) => `${c.label.padEnd(14)} ${tildify(c.dir)}${c.detected ? "  (detected)" : ""}`), preselect, colors(ctx.env, ctx.io.isTTY));
+    return choices[idx].global;
+}
+// Exported for the wiring tests: the pure path maths lives in registry.ts, but
+// the ORDER and CONDITIONS of the two prompts are what regressed before (the
+// registry always supported global; this function simply never asked).
+export async function resolveTarget(ctx, flags, ref) {
+    // `-g` is an explicit answer to the scope question; its absence is NOT an
+    // answer, it just means "unstated" (which is why we now ask instead of
+    // defaulting silently to project-local).
+    const scopeGiven = flags.global === true;
+    const global = scopeGiven;
+    const yes = flags.yes === true;
     if (typeof flags.dir === "string") {
+        // An explicit path IS the scope — nothing left to ask.
         const dir = isAbsolute(flags.dir) ? flags.dir : resolvePath(ctx.cwd, flags.dir);
         return { id: "custom", dir };
     }
@@ -155,16 +193,24 @@ async function resolveTarget(ctx, flags, ref) {
         if (!def) {
             throw usageError(`unknown --target "${flags.target}"`, `known targets: ${TARGETS.map((t) => t.id).join(", ")} (or use --dir <path>)`);
         }
+        // --target picks the TOOL, not the scope: an interactive run still asks.
+        const useGlobal = await resolveScope(ctx, def, ref, { scopeGiven, global, yes });
         return {
             id: def.id,
-            dir: targetInstallDir(def, { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug }),
+            dir: targetInstallDir(def, {
+                cwd: ctx.cwd,
+                home: ctx.home,
+                global: useGlobal,
+                slug: ref.slug,
+            }),
         };
     }
-    const detected = detectTargets({ cwd: ctx.cwd, home: ctx.home, global });
     if (!ctx.io.isTTY)
         throw usageError(NON_TTY_TARGET_HINT);
-    if (flags.yes === true) {
+    if (yes) {
         // -y skips the PICKER only, and only when detection is unambiguous (D-UX11).
+        // Scope is known here (the flag), so this stays single-scope detection.
+        const detected = detectTargets({ cwd: ctx.cwd, home: ctx.home, global });
         const found = detected.filter((t) => t.detected);
         if (found.length === 1) {
             return {
@@ -176,16 +222,17 @@ async function resolveTarget(ctx, flags, ref) {
             ? "-y needs a detectable target and none was found — pass --target <tool> or --dir <path>"
             : `-y needs an unambiguous target and ${found.length} tools were detected — pass --target <tool> or --dir <path>`);
     }
-    const scopeNote = global ? " (global)" : "";
+    // Interactive: TOOL first, then SCOPE. Detection spans both scopes here
+    // because the scope is not yet chosen.
+    const detected = detectTargetsAnyScope({ cwd: ctx.cwd, home: ctx.home });
     const options = detected.map((t) => {
-        const dir = targetInstallDir(t, { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug });
-        const tags = [t.detected ? "(detected)" : null, t.experimental ? "(experimental)" : null]
+        const tags = [detectionLabel(t), t.experimental ? "(experimental)" : null]
             .filter(Boolean)
             .join(" ");
-        return `${t.label.padEnd(16)} ${dir}${tags ? `  ${tags}` : ""}`;
+        return `${t.label.padEnd(16)}${tags ? ` ${tags}` : ""}`;
     });
-    options.push("Custom path…      (type any directory)");
-    const idx = await promptSelect(ctx.io, `Where should this skill be installed?${scopeNote}`, options, 0);
+    options.push("Custom path…     (type any directory)");
+    const idx = await promptSelect(ctx.io, "Which tool is this skill for?", options, 0, colors(ctx.env, ctx.io.isTTY));
     if (idx === options.length - 1) {
         const answer = (await ctx.io.question("Directory: ")).trim();
         if (!answer)
@@ -193,9 +240,15 @@ async function resolveTarget(ctx, flags, ref) {
         return { id: "custom", dir: isAbsolute(answer) ? answer : resolvePath(ctx.cwd, answer) };
     }
     const chosen = detected[idx];
+    const useGlobal = await resolveScope(ctx, chosen, ref, { scopeGiven, global, yes });
     return {
         id: chosen.id,
-        dir: targetInstallDir(chosen, { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug }),
+        dir: targetInstallDir(chosen, {
+            cwd: ctx.cwd,
+            home: ctx.home,
+            global: useGlobal,
+            slug: ref.slug,
+        }),
     };
 }
 function dirIsNonEmpty(dir) {

package/dist/commands/lifecycle.js

@@ -70,7 +70,7 @@ export async function runUninstall(ctx, positionals, flags) {
         if (flags.yes !== true) {
             if (!ctx.io.isTTY)
                 throw usageError("confirmation needed in a non-interactive session", "re-run with -y");
-            const go = await confirm(ctx.io, `Uninstall ${receipt.ref} from ${item.dir}?`, false);
+            const go = await confirm(ctx.io, `Uninstall ${receipt.ref} from ${item.dir}?`, false, c);
             if (!go) {
                 ctx.io.out("Skipped.");
                 continue;
@@ -193,7 +193,7 @@ export async function runUpdate(ctx, positionals, flags) {
         if (flags.yes !== true) {
             if (!ctx.io.isTTY)
                 throw usageError("confirmation needed in a non-interactive session", "re-run with -y (or use --check)");
-            const go = await confirm(ctx.io, `Update ${receipt.ref} v${receipt.version} → v${toVersion}?`, true);
+            const go = await confirm(ctx.io, `Update ${receipt.ref} v${receipt.version} → v${toVersion}?`, true, c);
             if (!go) {
                 report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason: "declined" });
                 continue;

package/dist/commands/login.js

@@ -34,12 +34,41 @@ export async function runLogin(ctx, flags) {
 export async function runLogout(ctx) {
     const config = loadConfig(ctx.home);
     const had = typeof config.token === "string";
+    // REVOKE server-side FIRST (review CRITICAL: logout used to delete one copy
+    // of a 90-day sliding bearer and merely mention the Settings page — a
+    // security control named after ending a session that could not end it).
+    // Self-scoped: DELETE /cli/tokens/current kills exactly the presented token.
+    // Best-effort — offline logout must still clear local state, but a failed
+    // revoke is a WARNING, not a footnote.
+    let revoked = false;
+    if (had) {
+        try {
+            const api = new Api(ctx, resolveApiBase(ctx.env, config), config.token);
+            const res = await api.raw("DELETE", "/api/v1/cli/tokens/current");
+            revoked = res.status >= 200 && res.status < 300;
+        }
+        catch {
+            revoked = false;
+        }
+    }
     if (had) {
         delete config.token;
+        // api_base travels WITH the token (they are a pair — see config.ts): logout
+        // returns the client to the known-good default, so a hostile or stale
+        // origin set earlier does not survive the trust reset (review find).
+        delete config.api_base;
         saveConfig(ctx.home, config, ctx.platform);
     }
-    ctx.io.out(had ? "Logged out (local token removed)." : "Not logged in — nothing to remove.");
-    ctx.io.out("To invalidate the session server-side too: promptdock.ai → Settings → Account → CLI sessions → Revoke.");
+    if (!had) {
+        ctx.io.out("Not logged in — nothing to remove.");
+    }
+    else if (revoked) {
+        ctx.io.out("Logged out — the session was revoked server-side and the local token removed.");
+    }
+    else {
+        ctx.io.out("Logged out (local token removed).");
+        ctx.io.err("warning: could not revoke the session server-side (offline?). The token stays valid until it expires — revoke it at promptdock.ai → Settings → Account → CLI sessions.");
+    }
     if (ctx.env.PROMPTDOCK_TOKEN) {
         ctx.io.out("note: PROMPTDOCK_TOKEN is set in this environment and still authenticates requests.");
     }

package/dist/config.js

@@ -79,12 +79,45 @@ const trimBase = (s) => s.replace(/\/+$/, "");
 // so the token and the origin are a PAIR. Storing the token without its origin means
 // the next run sends a staging token to the default origin and 401s. The apex-pinning
 // problem that motivated the idea is handled by LEGACY_API_BASES below instead.
+/** Loopback hosts — the ONE carve-out from the TLS floor (local dev + the test
+ *  mock servers). Everything else that receives the bearer must be https. */
+function isLoopbackHost(host) {
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+/**
+ * THE TLS FLOOR (review find): every resolved base carries a 90-day bearer in
+ * an Authorization header, and nothing previously constrained the scheme — a
+ * stored `http://` origin (written once by a plaintext invocation, or by the
+ * api.ts redirect hint before it was hardened) was honoured forever, silently.
+ * Enforced on the env override AND the stored value: a config written by an
+ * older or hostile release must not survive an upgrade. Throws — a plaintext
+ * API base is a misconfiguration to fix, never something to quietly use.
+ */
+function assertSecureBase(base, source) {
+    let u;
+    try {
+        u = new URL(base);
+    }
+    catch {
+        throw new CliError(`${source === "env" ? "PROMPTDOCK_API_BASE" : "the stored api_base"} is not a valid URL: set it to an origin like https://www.promptdock.ai`, EXIT.USAGE);
+    }
+    if (u.username || u.password || u.search || u.hash) {
+        throw new CliError(`${source === "env" ? "PROMPTDOCK_API_BASE" : "the stored api_base"} must be a bare origin (no credentials, query, or fragment)`, EXIT.USAGE);
+    }
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && isLoopbackHost(u.hostname))) {
+        throw new CliError(`${source === "env" ? "PROMPTDOCK_API_BASE" : "the stored api_base"} is ${u.protocol}// — the CLI sends your login token on every request, so only https:// (or http://localhost for dev) is allowed. ` +
+            (source === "config"
+                ? "Run `promptdock logout`, then log in again against the https origin."
+                : "Set PROMPTDOCK_API_BASE to the https origin."), EXIT.USAGE);
+    }
+    return base;
+}
 export function resolveApiBase(env, config) {
     if (env.PROMPTDOCK_API_BASE)
-        return trimBase(env.PROMPTDOCK_API_BASE);
+        return assertSecureBase(trimBase(env.PROMPTDOCK_API_BASE), "env");
     const stored = typeof config.api_base === "string" ? trimBase(config.api_base) : null;
     // Drop a base a broken release pinned here; anything else the user set is honoured.
     if (stored && !LEGACY_API_BASES.has(stored))
-        return stored;
+        return assertSecureBase(stored, "config");
     return trimBase(DEFAULT_API_BASE);
 }

package/dist/context.d.ts

@@ -1,3 +1,4 @@
+import type { Key } from "./select-keys.js";
 /**
  * argv joined for the `X-Promptdock-Cli-Args` header, with bearer tokens removed.
  *
@@ -21,6 +22,24 @@ export type CliIo = {
     isTTY: boolean;
     /** readline question (TTY only — callers must gate on isTTY) */
     question: (prompt: string) => Promise<string>;
+    /**
+     * Raw keypress stream for the arrow-key picker. OPTIONAL by design: when it is
+     * absent, `promptSelect` falls back to the numbered reader built on `question`.
+     * That keeps one code path for every environment that cannot do raw mode — a
+     * piped stdin, a CI runner, a dumb terminal, and every test fake — without
+     * those callers needing to know the picker exists.
+     *
+     * Returns an unsubscribe that MUST restore the previous terminal mode.
+     */
+    rawKeys?: (onKey: (key: Key) => void) => () => void;
+    /** Live terminal dimensions — the picker clamps line width to `columns`
+     *  (wrapped lines desync the in-place repaint) and falls back to the
+     *  numbered reader when the frame exceeds `rows`. Optional: fakes and
+     *  non-TTY contexts omit it and the picker assumes 80x24. */
+    size?: () => {
+        rows: number;
+        columns: number;
+    };
 };
 export type CliContext = {
     io: CliIo;

package/dist/context.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
 import { readFileSync } from "node:fs";
 /**
  * argv joined for the `X-Promptdock-Cli-Args` header, with bearer tokens removed.
@@ -13,6 +14,12 @@ import { readFileSync } from "node:fs";
  * still needs to show that `--token` was passed.
  */
 export function redactArgs(argv) {
+    // ⚠️ COUPLING: this is a DENYLIST keyed on the flags that carry sensitive
+    // values. Any NEW value-carrying flag added to args.ts COMMAND_SPECS must be
+    // assessed here in the same change — a missed one leaks silently (the header
+    // rides every request and every proxy logs it). Current set: --token (the
+    // live bearer) and --dir (absolute local paths carry the OS username +
+    // client/project names — data the 426 remedy does not need; review find).
     return argv
         .map((a, i) => {
         if (/^pdk_/.test(a))
@@ -22,10 +29,55 @@ export function redactArgs(argv) {
             return "--token=***";
         if (argv[i - 1] === "--token")
             return "***";
+        if (/^--dir=/.test(a))
+            return "--dir=***";
+        if (argv[i - 1] === "--dir")
+            return "***";
         return a;
     })
         .join(" ");
 }
+/**
+ * Process-level terminal safety net. The picker's `finally` restores raw mode
+ * + cursor on every JS path (resolve/reject/throw, and ^C arrives as a
+ * keypress under raw mode) — but an EXTERNAL SIGTERM/SIGHUP or `kill` runs no
+ * finally: the process dies with the cursor hidden (`?25l` persists until
+ * `reset`; 4 review voices converged on this). One-shot handlers restore the
+ * terminal and re-exit with the conventional 128+signal code.
+ */
+let activeRawRelease = null;
+let terminalSafetyInstalled = false;
+function installTerminalSafety() {
+    if (terminalSafetyInstalled)
+        return;
+    terminalSafetyInstalled = true;
+    const restore = () => {
+        try {
+            activeRawRelease?.();
+        }
+        catch {
+            /* stdin already torn down */
+        }
+        try {
+            process.stdout.write("[?25h");
+        }
+        catch {
+            /* stdout already torn down */
+        }
+    };
+    // 'exit' covers process.exit() and normal termination; fatal signals with
+    // default handlers do NOT fire it, hence the explicit signal hooks.
+    process.on("exit", restore);
+    for (const [sig, code] of [
+        ["SIGTERM", 143],
+        ["SIGHUP", 129],
+    ]) {
+        process.on(sig, () => {
+            restore();
+            process.exit(code);
+        });
+    }
+}
 /** Read the package's own version (dist/ and src/ both sit one level under the root). */
 export function readOwnVersion() {
     try {
@@ -70,6 +122,54 @@ export function realContext(argv) {
                     rl.close();
                 }
             },
+            // Only offered when raw mode is genuinely available AND the terminal can
+            // render ANSI. `setRawMode` is absent whenever stdin is not a TTY (a
+            // pipe, a spawned child, CI); TERM=dumb (Emacs M-x shell, some IDE
+            // consoles) IS a pty but cannot render the escapes the picker paints —
+            // it gets the numbered reader, as the README promises (review find).
+            ...(isTTY &&
+                typeof process.stdin.setRawMode === "function" &&
+                process.env.TERM !== "dumb"
+                ? {
+                    rawKeys: (onKey) => {
+                        installTerminalSafety();
+                        const stdin = process.stdin;
+                        emitKeypressEvents(stdin);
+                        const wasRaw = stdin.isRaw === true;
+                        stdin.setRawMode(true);
+                        stdin.resume();
+                        const handler = (_s, key) => {
+                            if (key)
+                                onKey(key);
+                        };
+                        stdin.on("keypress", handler);
+                        let released = false;
+                        // Idempotent: the picker releases in a `finally`, and a second call
+                        // during process teardown must not throw on an already-closed stdin.
+                        const release = () => {
+                            if (released)
+                                return;
+                            released = true;
+                            if (activeRawRelease === release)
+                                activeRawRelease = null;
+                            stdin.off("keypress", handler);
+                            try {
+                                stdin.setRawMode(wasRaw);
+                            }
+                            catch {
+                                /* stdin already torn down */
+                            }
+                            stdin.pause();
+                        };
+                        activeRawRelease = release;
+                        return release;
+                    },
+                    size: () => ({
+                        rows: process.stdout.rows ?? 24,
+                        columns: process.stdout.columns ?? 80,
+                    }),
+                }
+                : {}),
         },
         env: process.env,
         cwd: process.cwd(),

package/dist/errors.d.ts

@@ -12,6 +12,11 @@ export declare const EXIT: {
     readonly IO: 5;
     /** couldn't reach the API */
     readonly NETWORK: 6;
+    /** Ctrl-C during an interactive picker — 128+SIGINT, the shell convention.
+     *  Raw mode swallows the real signal (it arrives as a keypress), so the CLI
+     *  exits with the code a signal death would have produced. Esc (a deliberate
+     *  in-UI cancel) stays USAGE=1. Scripts never reach pickers (TTY-only). */
+    readonly INTERRUPT: 130;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
 /** DX3: every named error footer links its docs anchor. */

package/dist/errors.js

@@ -13,6 +13,11 @@ export const EXIT = {
     IO: 5,
     /** couldn't reach the API */
     NETWORK: 6,
+    /** Ctrl-C during an interactive picker — 128+SIGINT, the shell convention.
+     *  Raw mode swallows the real signal (it arrives as a keypress), so the CLI
+     *  exits with the code a signal death would have produced. Esc (a deliberate
+     *  in-UI cancel) stays USAGE=1. Scripts never reach pickers (TTY-only). */
+    INTERRUPT: 130,
 };
 /** DX3: every named error footer links its docs anchor. */
 export function footerUrl(code) {

package/dist/generated/constants.d.ts

@@ -3,7 +3,7 @@ export declare const MAX_SKILL_TOTAL_BYTES = 5242880;
 export declare const MAX_SKILL_FILE_BYTES = 1048576;
 export declare const MAX_SKILL_IMAGES = 5;
 export declare const SKILL_REVEAL_DAILY_CAP = 15;
-export declare const CLI_MIN_VERSION = "0.1.0";
+export declare const CLI_MIN_VERSION = "1.0.1";
 export declare const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
 export declare const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
 export declare const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";

package/dist/generated/constants.js

@@ -5,7 +5,7 @@ export const MAX_SKILL_TOTAL_BYTES = 5242880;
 export const MAX_SKILL_FILE_BYTES = 1048576;
 export const MAX_SKILL_IMAGES = 5;
 export const SKILL_REVEAL_DAILY_CAP = 15;
-export const CLI_MIN_VERSION = "0.1.0";
+export const CLI_MIN_VERSION = "1.0.1";
 export const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
 export const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
 export const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";

package/dist/help.js

@@ -21,8 +21,8 @@ export function globalHelp(version) {
     help                      this map
 
   Install options
-    -g, --global              install into the tool's per-user dir instead of the project
-    --target <tool>           skip the picker (${TARGETS.map((t) => t.id).join(", ")})
+    -g, --global              install into the tool's per-user dir (skips the scope prompt)
+    --target <tool>           pick the tool (${TARGETS.map((t) => t.id).join(", ")}); scope is still asked — add -g or -y to skip
     --dir <path>              install into an explicit directory
     -y, --yes                 skip prompts (needs an unambiguous target; NEVER implies --force)
     --force                   replace a non-empty foreign directory / overwrite local edits
@@ -62,11 +62,15 @@ session stays valid until revoked in Settings → Account → CLI sessions.`,
 Shows the signed-in handle, role, and token expiry.`,
     install: `promptdock install <handle>/<slug> [-g] [--target <tool>] [--dir <path>] [-y] [--force] [--dry-run] [--json]
 
-Installs a skill. Non-interactive sessions (CI) must pass --target or --dir
-plus -y, and authenticate via PROMPTDOCK_TOKEN. -y skips the target picker
-ONLY — a non-empty foreign directory still requires --force. --dry-run
-resolves and prints the plan without installing (and without spending any
-premium-unlock slot).`,
+Installs a skill. Interactively it asks two things: which TOOL, then whether
+to install for THIS PROJECT or for your USER ACCOUNT (each shown as its real
+destination path). -g answers the second one up front; --dir answers both.
+
+Non-interactive sessions (CI) must pass --target or --dir plus -y, and
+authenticate via PROMPTDOCK_TOKEN. -y skips the prompts ONLY — a non-empty
+foreign directory still requires --force, and scope stays project-local
+unless -g is passed. --dry-run resolves and prints the plan without
+installing (and without spending any premium-unlock slot).`,
     uninstall: `promptdock uninstall <handle>/<slug> | --all [-g] [--target <tool>] [--dir <path>] [--force] [-y] [--json]
 
 Removes an installed skill using its .promptdock.json receipt — only files the

package/dist/registry.d.ts

@@ -26,6 +26,62 @@ export declare function targetInstallDir(t: TargetDef, opts: {
     global: boolean;
     slug: string;
 }): string;
+/** Is this tool set up in each scope? Path knowledge stays in this module. */
+export declare function detectScopes(t: TargetDef, opts: {
+    cwd: string;
+    home: string;
+    exists?: (p: string) => boolean;
+}): {
+    local: boolean;
+    global: boolean;
+};
+export type ScopedTarget = TargetDef & {
+    detectedLocal: boolean;
+    detectedGlobal: boolean;
+    detected: boolean;
+};
+/**
+ * Scope-agnostic detection for the interactive picker, which asks for the TOOL
+ * first and the SCOPE second — so at list time there is no single scope to
+ * probe. `detected` (either scope) drives the D-UX11 float ordering; the
+ * per-scope flags let the row say WHERE it was found, which the old
+ * one-scope-only tag could not.
+ */
+export declare function detectTargetsAnyScope(opts: {
+    cwd: string;
+    home: string;
+    exists?: (p: string) => boolean;
+}): ScopedTarget[];
+/** Where a tool was found, for the picker row ("" when nowhere). */
+export declare function detectionLabel(t: {
+    detectedLocal: boolean;
+    detectedGlobal: boolean;
+}): string;
+export type ScopeChoice = {
+    global: boolean;
+    label: string;
+    dir: string;
+    detected: boolean;
+};
+/**
+ * The two concrete destinations for a chosen tool, in prompt order (project,
+ * then global), plus the preselect index. Pure so the prompt's content is
+ * unit-testable without a TTY.
+ *
+ * Preselect prefers the scope where the tool is ALREADY set up. When it is set
+ * up in both — or in neither — it stays project-local, which is exactly what
+ * `-y` and non-TTY runs default to, so the interactive and non-interactive
+ * paths can never disagree about the same repo.
+ */
+export declare function scopeChoices(t: TargetDef, opts: {
+    cwd: string;
+    home: string;
+    slug: string;
+    exists?: (p: string) => boolean;
+}): {
+    choices: [ScopeChoice, ScopeChoice];
+    preselect: 0 | 1;
+};
 export type DetectedTarget = TargetDef & {
     detected: boolean;
 };

package/dist/registry.js

@@ -80,6 +80,71 @@ export function targetBaseDir(t, opts) {
 export function targetInstallDir(t, opts) {
     return join(targetBaseDir(t, opts), opts.slug);
 }
+/** Is this tool set up in each scope? Path knowledge stays in this module. */
+export function detectScopes(t, opts) {
+    const exists = opts.exists ?? existsSync;
+    return {
+        local: exists(join(opts.cwd, t.detectLocal)),
+        global: exists(join(opts.home, t.detectGlobal)),
+    };
+}
+/**
+ * Scope-agnostic detection for the interactive picker, which asks for the TOOL
+ * first and the SCOPE second — so at list time there is no single scope to
+ * probe. `detected` (either scope) drives the D-UX11 float ordering; the
+ * per-scope flags let the row say WHERE it was found, which the old
+ * one-scope-only tag could not.
+ */
+export function detectTargetsAnyScope(opts) {
+    const all = TARGETS.map((t) => {
+        const found = detectScopes(t, opts);
+        return {
+            ...t,
+            detectedLocal: found.local,
+            detectedGlobal: found.global,
+            detected: found.local || found.global,
+        };
+    });
+    return [...all.filter((t) => t.detected), ...all.filter((t) => !t.detected)];
+}
+/** Where a tool was found, for the picker row ("" when nowhere). */
+export function detectionLabel(t) {
+    if (t.detectedLocal && t.detectedGlobal)
+        return "(detected: project + global)";
+    if (t.detectedLocal)
+        return "(detected: project)";
+    if (t.detectedGlobal)
+        return "(detected: global)";
+    return "";
+}
+/**
+ * The two concrete destinations for a chosen tool, in prompt order (project,
+ * then global), plus the preselect index. Pure so the prompt's content is
+ * unit-testable without a TTY.
+ *
+ * Preselect prefers the scope where the tool is ALREADY set up. When it is set
+ * up in both — or in neither — it stays project-local, which is exactly what
+ * `-y` and non-TTY runs default to, so the interactive and non-interactive
+ * paths can never disagree about the same repo.
+ */
+export function scopeChoices(t, opts) {
+    const found = detectScopes(t, opts);
+    const choices = [
+        {
+            global: false,
+            label: "This directory",
+            dir: targetInstallDir(t, { ...opts, global: false }),
+            detected: found.local,
+        },
+        {
+            global: true,
+            label: "Global",
+            dir: targetInstallDir(t, { ...opts, global: true }),
+            detected: found.global,
+        },
+    ];
+    return { choices, preselect: !found.local && found.global ? 1 : 0 };
+}
 /**
  * D-UX11 ordering: detected tools float to the top (registry order preserved
  * within each group); the preselect is index 0 (first detected, else Claude).

package/dist/select-keys.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Key handling for the interactive picker, as a PURE reducer.
+ *
+ * Kept out of ui.ts on purpose: the rendering half needs a real TTY (raw mode,
+ * cursor moves) and cannot be unit-tested, but the DECISIONS — what wraps, what
+ * commits, what cancels — are the part that regresses. Pure in, pure out, so
+ * every key path is pinned by a table test with no terminal involved.
+ */
+/** The subset of node:readline's keypress event this reducer reads. */
+export type Key = {
+    name?: string;
+    sequence?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+};
+export type SelectState = {
+    /** highlighted option */
+    index: number;
+    /** digits typed so far — the "type a number" path, empty when unused */
+    buffer: string;
+};
+export type SelectResult = {
+    kind: "state";
+    state: SelectState;
+} | {
+    kind: "commit";
+    index: number;
+}
+/** `signal` marks Ctrl-C (exit 130, the 128+SIGINT convention); Esc/Ctrl-D
+ *  are deliberate in-UI cancels (exit 1). */
+ | {
+    kind: "cancel";
+    signal?: boolean;
+}
+/** a typed number that names no option — caller flashes a hint, keeps the prompt */
+ | {
+    kind: "reject";
+    state: SelectState;
+    message: string;
+};
+/**
+ * One keypress → the next state, or a terminal outcome.
+ *
+ * Both input styles stay live at once, which is the whole point: arrows move the
+ * highlight, digits ALSO move it (so typing is visible before you commit), and
+ * Enter commits whichever the user last expressed. Space commits the highlight
+ * only — it is a "this one" gesture, and treating it as a number-confirm would
+ * make a half-typed "1" + Space silently pick option 1 when the user meant 12.
+ *
+ * Digits never auto-commit. `3` in a 4-item list is unambiguous and a fancier
+ * picker would fire immediately, but the user asked to KEEP number entry, and
+ * number entry means "type it, then press Enter" — auto-firing would make a
+ * two-digit list behave differently from a one-digit list.
+ *
+ * `hotkeys` (letter → option index) commit IMMEDIATELY — the confirm path
+ * passes {y:0, n:1}. Without this, `n`+Enter at a default-Yes "Install?"
+ * committed the DEFAULT: the muscle-memory answer this CLI's own [y/N]
+ * fallback trains was silently ignored and the UI executed the opposite of
+ * what the user typed (dual-review find, PTY-proven).
+ */
+export declare function reduceSelectKey(state: SelectState, key: Key, count: number, hotkeys?: Record<string, number>): SelectResult;
+/** Footer hint. Mentions BOTH input styles — neither is discoverable otherwise.
+ *  `hotkeyLabel` (e.g. "y/n") leads when the picker has letter hotkeys. */
+export declare function selectHint(count: number, buffer: string, hotkeyLabel?: string): string;

package/dist/select-keys.js

@@ -0,0 +1,113 @@
+/**
+ * Key handling for the interactive picker, as a PURE reducer.
+ *
+ * Kept out of ui.ts on purpose: the rendering half needs a real TTY (raw mode,
+ * cursor moves) and cannot be unit-tested, but the DECISIONS — what wraps, what
+ * commits, what cancels — are the part that regresses. Pure in, pure out, so
+ * every key path is pinned by a table test with no terminal involved.
+ */
+const wrap = (i, count) => ((i % count) + count) % count;
+/**
+ * One keypress → the next state, or a terminal outcome.
+ *
+ * Both input styles stay live at once, which is the whole point: arrows move the
+ * highlight, digits ALSO move it (so typing is visible before you commit), and
+ * Enter commits whichever the user last expressed. Space commits the highlight
+ * only — it is a "this one" gesture, and treating it as a number-confirm would
+ * make a half-typed "1" + Space silently pick option 1 when the user meant 12.
+ *
+ * Digits never auto-commit. `3` in a 4-item list is unambiguous and a fancier
+ * picker would fire immediately, but the user asked to KEEP number entry, and
+ * number entry means "type it, then press Enter" — auto-firing would make a
+ * two-digit list behave differently from a one-digit list.
+ *
+ * `hotkeys` (letter → option index) commit IMMEDIATELY — the confirm path
+ * passes {y:0, n:1}. Without this, `n`+Enter at a default-Yes "Install?"
+ * committed the DEFAULT: the muscle-memory answer this CLI's own [y/N]
+ * fallback trains was silently ignored and the UI executed the opposite of
+ * what the user typed (dual-review find, PTY-proven).
+ */
+export function reduceSelectKey(state, key, count, hotkeys) {
+    const name = key.name;
+    const seq = key.sequence;
+    const keep = (s) => ({ kind: "state", state: s });
+    // Raw mode swallows SIGINT, so Ctrl-C is ours to honour or the picker hangs.
+    // It carries the `signal` mark → exit 130; Esc/^D are deliberate cancels.
+    if (key.ctrl && name === "c")
+        return { kind: "cancel", signal: true };
+    if (key.ctrl && name === "d")
+        return { kind: "cancel" };
+    if (name === "escape")
+        return { kind: "cancel" };
+    // Letter hotkeys beat every other mapping except cancel — `n` must never be
+    // read as "ignored key" while the footer implies typing works.
+    if (name && !key.ctrl && !key.meta && hotkeys && hotkeys[name] !== undefined) {
+        const idx = hotkeys[name];
+        if (idx >= 0 && idx < count)
+            return { kind: "commit", index: idx };
+    }
+    if (name === "return" || name === "enter") {
+        if (state.buffer === "")
+            return { kind: "commit", index: state.index };
+        const n = Number(state.buffer);
+        if (Number.isInteger(n) && n >= 1 && n <= count)
+            return { kind: "commit", index: n - 1 };
+        return {
+            kind: "reject",
+            state: { index: state.index, buffer: "" },
+            message: `Enter a number between 1 and ${count}.`,
+        };
+    }
+    if (name === "space") {
+        // With a live digit buffer, Space means what Enter means — validate the
+        // number. Committing the stale highlight would discard the visible buffer
+        // ("Number: 12") for a row the user never named (review find).
+        if (state.buffer !== "") {
+            const n = Number(state.buffer);
+            if (Number.isInteger(n) && n >= 1 && n <= count)
+                return { kind: "commit", index: n - 1 };
+            return {
+                kind: "reject",
+                state: { index: state.index, buffer: "" },
+                message: `Enter a number between 1 and ${count}.`,
+            };
+        }
+        return { kind: "commit", index: state.index };
+    }
+    if (name === "up" || name === "k" || (key.ctrl && name === "p"))
+        return keep({ index: wrap(state.index - 1, count), buffer: "" });
+    if (name === "down" || name === "j" || (key.ctrl && name === "n"))
+        return keep({ index: wrap(state.index + 1, count), buffer: "" });
+    if (name === "home")
+        return keep({ index: 0, buffer: "" });
+    if (name === "end")
+        return keep({ index: count - 1, buffer: "" });
+    if (name === "backspace") {
+        const buffer = state.buffer.slice(0, -1);
+        const n = Number(buffer);
+        // Re-point at whatever the shortened buffer now names; keep the highlight if it names nothing.
+        const index = buffer !== "" && n >= 1 && n <= count ? n - 1 : state.index;
+        return keep({ index, buffer });
+    }
+    if (seq !== undefined && /^[0-9]$/.test(seq)) {
+        // Bounded: 3 digits names any option a 20-row picker can hold; an unbounded
+        // buffer + full-frame repaint per digit is quadratic under a digit-spam
+        // paste (codex find). Extra digits are ignored, never mis-parsed.
+        if (state.buffer.length >= 3)
+            return keep(state);
+        // Leading zeros are dropped so "0" then "3" is 3, not a dead buffer.
+        const buffer = (state.buffer + seq).replace(/^0+(?=\d)/, "");
+        const n = Number(buffer);
+        const index = n >= 1 && n <= count ? n - 1 : state.index;
+        return keep({ index, buffer });
+    }
+    return keep(state);
+}
+/** Footer hint. Mentions BOTH input styles — neither is discoverable otherwise.
+ *  `hotkeyLabel` (e.g. "y/n") leads when the picker has letter hotkeys. */
+export function selectHint(count, buffer, hotkeyLabel) {
+    if (buffer !== "")
+        return `Number: ${buffer}   ↵ confirm · ⌫ clear · esc cancel`;
+    const hot = hotkeyLabel ? `${hotkeyLabel} · ` : "";
+    return `${hot}↑↓ move · ↵/space select · 1-${count} then ↵ · esc cancel`;
+}

package/dist/ui.d.ts

@@ -1,5 +1,6 @@
 import type { CliIo } from "./context.js";
-/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color. */
+/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color.
+ *  TERM=dumb too — a terminal that can't render ANSI gets plain text. */
 export declare function colors(env: Record<string, string | undefined>, isTTY: boolean): {
     bold: (s: string) => string;
     dim: (s: string) => string;
@@ -14,9 +15,18 @@ export declare function formatCountdown(totalSecs: number): string;
 /** ~Nh retry copy for the cap verdict (mirrors the app's premium-cap copy). */
 export declare function retryHours(retryAfterSecs: number): string;
 /**
- * Numbered-list picker (TTY only — callers gate). Returns the chosen index.
- * Enter accepts the preselected default.
+ * Picker. Arrow-key driven when the terminal can do raw mode, numbered otherwise.
+ * Returns the chosen index.
+ *
+ * BOTH input styles are live in the interactive path: ↑↓ (and j/k, ^p/^n) move,
+ * ↵/space select, and typing a number still works — it moves the highlight as you
+ * type and ↵ confirms it. The numbered path below is not a lesser fallback, it is
+ * the contract for every non-TTY caller (CI, pipes, tests) and its behaviour is
+ * unchanged: Enter alone accepts the preselect.
  */
-export declare function promptSelect(io: CliIo, title: string, options: string[], preselect: number): Promise<number>;
-/** y/N confirm (TTY only — callers gate; -y bypasses upstream). */
-export declare function confirm(io: CliIo, prompt: string, def?: boolean): Promise<boolean>;
+export declare function promptSelect(io: CliIo, title: string, options: string[], preselect: number, c?: Colors, hotkeys?: Record<string, number>, hotkeyLabel?: string): Promise<number>;
+/**
+ * Confirm. Arrow-driven Yes/No when the terminal allows, y/N text otherwise.
+ * (TTY only — callers gate; -y bypasses upstream.)
+ */
+export declare function confirm(io: CliIo, prompt: string, def?: boolean, c?: Colors): Promise<boolean>;

package/dist/ui.js

@@ -1,6 +1,9 @@
-/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color. */
+import { CliError, EXIT } from "./errors.js";
+import { reduceSelectKey, selectHint } from "./select-keys.js";
+/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color.
+ *  TERM=dumb too — a terminal that can't render ANSI gets plain text. */
 export function colors(env, isTTY) {
-    const on = isTTY && !env.NO_COLOR;
+    const on = isTTY && !env.NO_COLOR && env.TERM !== "dumb";
     const wrap = (open, close) => (s) => (on ? `${open}${s}${close}` : s);
     return {
         bold: wrap("\u001b[1m", "\u001b[22m"),
@@ -28,11 +31,31 @@ export function formatCountdown(totalSecs) {
 export function retryHours(retryAfterSecs) {
     return `~${Math.max(1, Math.ceil(retryAfterSecs / 3600))}h`;
 }
+const HIDE_CURSOR = "[?25l";
+const SHOW_CURSOR = "[?25h";
+/** Above this, cursor-up repainting fights terminal scrollback — use the numbered reader. */
+const MAX_INTERACTIVE_ROWS = 20;
+const passthrough = (s) => s;
 /**
- * Numbered-list picker (TTY only — callers gate). Returns the chosen index.
- * Enter accepts the preselected default.
+ * Picker. Arrow-key driven when the terminal can do raw mode, numbered otherwise.
+ * Returns the chosen index.
+ *
+ * BOTH input styles are live in the interactive path: ↑↓ (and j/k, ^p/^n) move,
+ * ↵/space select, and typing a number still works — it moves the highlight as you
+ * type and ↵ confirms it. The numbered path below is not a lesser fallback, it is
+ * the contract for every non-TTY caller (CI, pipes, tests) and its behaviour is
+ * unchanged: Enter alone accepts the preselect.
  */
-export async function promptSelect(io, title, options, preselect) {
+export async function promptSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel) {
+    // Height gate: the frame is title + options + hint. If it doesn't fit the
+    // terminal, `ESC[NA` clamps at the top edge and repaints mangle scrollback
+    // (an 8-row tmux pane was the review's concrete case) — the numbered reader
+    // is the honest fallback there.
+    const rows = io.size?.().rows ?? 24;
+    const fits = options.length + 2 <= rows - 1;
+    if (io.rawKeys && options.length > 0 && options.length <= MAX_INTERACTIVE_ROWS && fits) {
+        return interactiveSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel);
+    }
     io.out(title);
     options.forEach((opt, i) => {
         const marker = i === preselect ? "❯" : " ";
@@ -48,8 +71,136 @@ export async function promptSelect(io, title, options, preselect) {
         io.out(`Enter a number between 1 and ${options.length}.`);
     }
 }
-/** y/N confirm (TTY only — callers gate; -y bypasses upstream). */
-export async function confirm(io, prompt, def = false) {
+/** Clamp a PLAIN (uncolored) line to the terminal width. Load-bearing for the
+ *  in-place repaint: `ESC[NA` moves PHYSICAL rows while `painted` counts
+ *  logical lines, so one soft-wrapped line desyncs every later repaint into a
+ *  trail of stale frames (3 voices + codex converged on this; the scope
+ *  prompt's absolute paths wrap on a stock 80-col terminal). Clamping before
+ *  colorization keeps logical lines == physical rows by construction. */
+function clampLine(line, columns) {
+    const max = Math.max(8, columns - 1);
+    if (line.length <= max)
+        return line;
+    return line.slice(0, max - 1) + "…";
+}
+async function interactiveSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel) {
+    const count = options.length;
+    const bold = c?.bold ?? passthrough;
+    const cyan = c?.cyan ?? passthrough;
+    const dim = c?.dim ?? passthrough;
+    const width = String(count).length;
+    let state = { index: Math.min(Math.max(preselect, 0), count - 1), buffer: "" };
+    let notice = "";
+    let painted = 0;
+    const frame = () => {
+        // Re-read the width each paint so a mid-picker resize clamps the NEXT
+        // frame correctly (past frames are already committed to scrollback).
+        const columns = io.size?.().columns ?? 80;
+        const rows = options.map((opt, i) => {
+            const num = `${i + 1}.`.padStart(width + 1);
+            const body = clampLine(`${i === state.index ? "❯" : " "} ${num} ${opt}`, columns);
+            return i === state.index ? cyan(bold(body)) : body;
+        });
+        return [
+            clampLine(title, columns),
+            ...rows,
+            dim(clampLine(notice || selectHint(count, state.buffer, hotkeyLabel), columns)),
+        ];
+    };
+    const paint = () => {
+        // Redraw in place: jump back over the previous frame, then clear-and-rewrite
+        // each line. Clearing matters — a shorter line would otherwise leave the tail
+        // of the longer one it replaced (a stale path fragment) on screen.
+        const lines = frame();
+        let out = painted > 0 ? `[${painted}A` : "";
+        for (const line of lines)
+            out += `\r${line}\n`;
+        io.write(out);
+        painted = lines.length;
+    };
+    /** On commit, COLLAPSE the frame to one summary line ("Install? Yes") instead
+     *  of leaving the whole option list + a stale hint in scrollback (review
+     *  polish item). Clears every previously painted row, writes the summary,
+     *  and parks the cursor directly under it so the CLI's next output flows on. */
+    const collapse = (chosen) => {
+        const columns = io.size?.().columns ?? 80;
+        const summary = clampLine(`${title} ${chosen}`, columns);
+        let out = painted > 0 ? `[${painted}A` : "";
+        out += `\r${cyan(summary)}\n`;
+        for (let i = 0; i < painted - 1; i++)
+            out += ``;
+        if (painted > 1)
+            out += `[${painted - 1}A\r`;
+        io.write(out);
+        painted = 1;
+    };
+    io.write(HIDE_CURSOR);
+    // Seeded with a no-op rather than null: the executor below runs synchronously so
+    // this is always replaced before the await, and a non-nullable release means the
+    // finally can never be skipped by a narrowing accident. Leaving raw mode on is
+    // the one failure here that wrecks the user's terminal after we exit.
+    let release = () => { };
+    try {
+        return await new Promise((resolve, reject) => {
+            paint();
+            // Settled guard + immediate release: `finally` runs a microtask AFTER
+            // resolve, so keys buffered in the SAME tick (a paste like "2\n1") would
+            // otherwise keep reducing and repainting a highlight that diverges from
+            // the resolved index (codex find, verified). Settle → release NOW; the
+            // finally's idempotent release stays as the belt.
+            let settled = false;
+            const settle = () => {
+                settled = true;
+                release();
+            };
+            release = io.rawKeys((key) => {
+                if (settled)
+                    return;
+                const res = reduceSelectKey(state, key, count, hotkeys);
+                if (res.kind === "cancel") {
+                    settle();
+                    reject(res.signal
+                        ? new CliError("Interrupted.", EXIT.INTERRUPT)
+                        : new CliError("Cancelled.", EXIT.USAGE));
+                    return;
+                }
+                if (res.kind === "commit") {
+                    state = { index: res.index, buffer: "" };
+                    notice = "";
+                    collapse(options[res.index]);
+                    settle();
+                    resolve(res.index);
+                    return;
+                }
+                if (res.kind === "reject") {
+                    state = res.state;
+                    notice = res.message;
+                    paint();
+                    return;
+                }
+                state = res.state;
+                notice = "";
+                paint();
+            });
+        });
+    }
+    finally {
+        // Order matters: stop consuming keys BEFORE restoring the cursor, so a key
+        // pressed during teardown cannot repaint over the restored terminal.
+        release();
+        io.write(SHOW_CURSOR);
+    }
+}
+/**
+ * Confirm. Arrow-driven Yes/No when the terminal allows, y/N text otherwise.
+ * (TTY only — callers gate; -y bypasses upstream.)
+ */
+export async function confirm(io, prompt, def = false, c) {
+    // y/n commit IMMEDIATELY (hotkeys) — the [y/N] muscle memory this CLI's own
+    // fallback trains must never be silently ignored (dual-review find: `n`+Enter
+    // at a default-Yes confirm used to run the install against a typed no).
+    if (io.rawKeys)
+        return (await promptSelect(io, prompt, ["Yes", "No"], def ? 0 : 1, c, { y: 0, n: 1 }, "y/n")) === 0;
     const suffix = def ? "[Y/n]" : "[y/N]";
     const answer = (await io.question(`${prompt} ${suffix} `)).trim().toLowerCase();
     if (answer === "")

package/package.json

@@ -1,28 +1,46 @@
 {
   "name": "promptdock",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Install AI agent skills from PromptDock — npx promptdock@latest install <handle>/<slug>",
-  "keywords": ["promptdock", "skills", "ai", "agents", "claude", "cli"],
+  "keywords": [
+    "promptdock",
+    "skills",
+    "ai",
+    "agents",
+    "claude",
+    "cli"
+  ],
   "homepage": "https://promptdock.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/klicklabs/promptdock.ai.git",
     "directory": "packages/cli"
   },
-  "bugs": { "url": "https://promptdock.ai/docs/cli/errors" },
-  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://promptdock.ai/docs/cli/errors"
+  },
+  "license": "MIT",
   "type": "module",
-  "bin": { "promptdock": "dist/index.js" },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=18" },
+  "bin": {
+    "promptdock": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "test": "npm run typecheck && vitest run",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.test.json"
   },
   "devDependencies": {
     "@types/node": "^20",
     "typescript": "^5",
     "vitest": "^4.1.8"
-  }
+  },
+  "gitHead": "a2f9bd83dfba6c7f73a116687fede2e7b2f3c8cb"
 }