@contentful/experience-design-system-cli 2.36.2-dev-build-dc6fb2aa.0 → 2.36.2-dev-build-c4497102.0

package/dist/index.js

@@ -167,10 +167,23 @@ var init_use_terminal_width = __esm({
   }
 });
 
+// packages/experience-design-system-cli/src/tui/control-hints.tsx
+import { Text } from "ink";
+import { jsx } from "react/jsx-runtime";
+function ControlHints({ hints }) {
+  return /* @__PURE__ */ jsx(Text, { color: PALETTE.muted, children: hints.map((hint) => `${hint.keys} ${hint.label}`).join(" \xB7 ") });
+}
+var init_control_hints = __esm({
+  "packages/experience-design-system-cli/src/tui/control-hints.tsx"() {
+    "use strict";
+    init_home_theme();
+  }
+});
+
 // packages/experience-design-system-cli/src/tui/home/home.tsx
 import { useEffect as useEffect2, useState as useState2 } from "react";
-import { Box, Text, useApp, useInput } from "ink";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Box, Text as Text2, useApp, useInput } from "ink";
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function upgradeItemDisplay(upgradeCheck) {
   if (upgradeCheck?.status === "update-available") {
     return { label: `Upgrade Version (v${upgradeCheck.latest} available)`, color: PALETTE.success };
@@ -213,27 +226,27 @@ function HomeScreen({ onNavigate }) {
   });
   if (tooNarrow) {
     return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-      /* @__PURE__ */ jsx(Text, { bold: true, color: PALETTE.warning, children: "Terminal too small" }),
-      /* @__PURE__ */ jsx(Text, { color: PALETTE.muted, children: "Press q to quit, make your terminal full screen, then run experiences import again." })
+      /* @__PURE__ */ jsx2(Text2, { bold: true, color: PALETTE.warning, children: "Terminal too small" }),
+      /* @__PURE__ */ jsx2(Text2, { color: PALETTE.muted, children: "Press q to quit, make your terminal full screen, then run experiences import again." })
     ] });
   }
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
     /* @__PURE__ */ jsxs(Box, { flexDirection: "column", alignItems: "center", children: [
-      /* @__PURE__ */ jsx(Text, { bold: true, color: PALETTE.heading, children: HEADING }),
-      /* @__PURE__ */ jsx(Text, { children: brandBar(HEADING.length).map((segment, i) => /* @__PURE__ */ jsx(Text, { color: segment.color, children: segment.text }, i)) }),
-      /* @__PURE__ */ jsx(Text, { color: PALETTE.muted, children: SUBTITLE }),
-      /* @__PURE__ */ jsxs(Text, { color: PALETTE.muted, children: [
+      /* @__PURE__ */ jsx2(Text2, { bold: true, color: PALETTE.heading, children: HEADING }),
+      /* @__PURE__ */ jsx2(Text2, { children: brandBar(HEADING.length).map((segment, i) => /* @__PURE__ */ jsx2(Text2, { color: segment.color, children: segment.text }, i)) }),
+      /* @__PURE__ */ jsx2(Text2, { color: PALETTE.muted, children: SUBTITLE }),
+      /* @__PURE__ */ jsxs(Text2, { color: PALETTE.muted, children: [
         "v",
         VERSION
       ] })
     ] }),
-    /* @__PURE__ */ jsx(Box, { marginTop: 1, justifyContent: "center", children: /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: START_ITEMS.map((item, i) => {
+    /* @__PURE__ */ jsx2(Box, { marginTop: 1, justifyContent: "center", children: /* @__PURE__ */ jsx2(Box, { flexDirection: "column", children: START_ITEMS.map((item, i) => {
       const focused = i === focusIdx;
       const isUpgradeItem = item.screen === "upgrade";
       const display = isUpgradeItem ? upgradeItemDisplay(upgradeCheck) : { label: item.label };
       const dimmed = isUpgradeItem && upgradeDisabled;
       return /* @__PURE__ */ jsxs(
-        Text,
+        Text2,
         {
           bold: focused && !dimmed,
           dimColor: dimmed,
@@ -246,7 +259,16 @@ function HomeScreen({ onNavigate }) {
         item.label
       );
     }) }) }),
-    /* @__PURE__ */ jsx(Box, { marginTop: 1, justifyContent: "center", children: /* @__PURE__ */ jsx(Text, { color: PALETTE.muted, children: "\u2191/\u2193 move \xB7 \u23CE select \xB7 q quit" }) })
+    /* @__PURE__ */ jsx2(Box, { marginTop: 1, justifyContent: "center", children: /* @__PURE__ */ jsx2(
+      ControlHints,
+      {
+        hints: [
+          { keys: "\u2191/\u2193", label: "move" },
+          { keys: "\u23CE", label: "select" },
+          { keys: "q", label: "quit" }
+        ]
+      }
+    ) })
   ] });
 }
 var VERSION, HEADING, SUBTITLE, MIN_TERMINAL_WIDTH, START_ITEMS;
@@ -256,6 +278,7 @@ var init_home = __esm({
     init_home_theme();
     init_version();
     init_use_terminal_width();
+    init_control_hints();
     VERSION = readPackageVersion();
     HEADING = "Contentful Experiences";
     SUBTITLE = "Let's import your design system into Contentful";
@@ -270,8 +293,8 @@ var init_home = __esm({
 });
 
 // packages/experience-design-system-cli/src/tui/import/PageContainer.tsx
-import { Box as Box2, Text as Text2, useInput as useInput2 } from "ink";
-import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+import { Box as Box2, Text as Text3, useInput as useInput2 } from "ink";
+import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
 function ImportScreen({ exitCode, onDone }) {
   useInput2((input, key) => {
     if (key.return || key.escape || input === "q") {
@@ -280,14 +303,14 @@ function ImportScreen({ exitCode, onDone }) {
   });
   const isSuccess = exitCode === 0;
   return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx2(Text2, { bold: true, children: "Import" }),
-    /* @__PURE__ */ jsx2(Text2, { children: " " }),
-    isSuccess ? /* @__PURE__ */ jsx2(Text2, { color: PALETTE.success, children: "\u2713 Import complete" }) : /* @__PURE__ */ jsxs2(Text2, { color: PALETTE.error, children: [
+    /* @__PURE__ */ jsx3(Text3, { bold: true, children: "Import" }),
+    /* @__PURE__ */ jsx3(Text3, { children: " " }),
+    isSuccess ? /* @__PURE__ */ jsx3(Text3, { color: PALETTE.success, children: "\u2713 Import complete" }) : /* @__PURE__ */ jsxs2(Text3, { color: PALETTE.error, children: [
       "\u2717 Import failed: process exited with code ",
       exitCode ?? "unknown"
     ] }),
-    /* @__PURE__ */ jsx2(Text2, { children: " " }),
-    /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: "[Enter] Back to Start" })
+    /* @__PURE__ */ jsx3(Text3, { children: " " }),
+    /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "[Enter] Back to Start" })
   ] });
 }
 var init_PageContainer = __esm({
@@ -333,9 +356,9 @@ var init_controls = __esm({
 
 // packages/experience-design-system-cli/src/tui/import/steps/01-welcome/screen.tsx
 import { useState as useState3 } from "react";
-import { Box as Box3, Text as Text3 } from "ink";
+import { Box as Box3, Text as Text4 } from "ink";
 import TextInput from "ink-text-input";
-import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
 function WelcomeScreen({ onContinue, onQuit, initialPath = "" }) {
   const [projectPath, setProjectPath] = useState3(initialPath);
   useWelcomeControls(projectPath, onQuit);
@@ -344,25 +367,25 @@ function WelcomeScreen({ onContinue, onQuit, initialPath = "" }) {
     if (path) onContinue(path);
   };
   return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx3(Text3, { bold: true, color: PALETTE.success, children: "\u{1F44B} Hey! Let's import your design system into Contentful." }),
-    /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "I'll walk you through 5 steps to get your components into Contentful ExO." }),
+    /* @__PURE__ */ jsx4(Text4, { bold: true, color: PALETTE.success, children: "\u{1F44B} Hey! Let's import your design system into Contentful." }),
+    /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "I'll walk you through 5 steps to get your components into Contentful ExO." }),
     /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", marginTop: 1, children: [
-      /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: RULE }),
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: RULE }),
       OVERVIEW.map((item) => /* @__PURE__ */ jsxs3(Box3, { gap: 1, children: [
-        /* @__PURE__ */ jsx3(Text3, { bold: true, children: item.label }),
-        /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: item.description })
+        /* @__PURE__ */ jsx4(Text4, { bold: true, children: item.label }),
+        /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: item.description })
       ] }, item.label)),
-      /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: RULE })
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: RULE })
     ] }),
     /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", marginTop: 1, children: [
-      /* @__PURE__ */ jsx3(Text3, { children: "Where is your component library?" }),
+      /* @__PURE__ */ jsx4(Text4, { children: "Where is your component library?" }),
       /* @__PURE__ */ jsxs3(Box3, { gap: 1, children: [
-        /* @__PURE__ */ jsx3(Text3, { color: PALETTE.accent, children: "?" }),
-        /* @__PURE__ */ jsx3(Text3, { children: "Project path:" }),
-        /* @__PURE__ */ jsx3(TextInput, { value: projectPath, onChange: setProjectPath, onSubmit: submit })
+        /* @__PURE__ */ jsx4(Text4, { color: PALETTE.accent, children: "?" }),
+        /* @__PURE__ */ jsx4(Text4, { children: "Project path:" }),
+        /* @__PURE__ */ jsx4(TextInput, { value: projectPath, onChange: setProjectPath, onSubmit: submit })
       ] })
     ] }),
-    /* @__PURE__ */ jsx3(Box3, { marginTop: 1, gap: 3, children: WELCOME_CONTROLS.map((control) => /* @__PURE__ */ jsxs3(Text3, { dimColor: true, children: [
+    /* @__PURE__ */ jsx4(Box3, { marginTop: 1, gap: 3, children: WELCOME_CONTROLS.map((control) => /* @__PURE__ */ jsxs3(Text4, { dimColor: true, children: [
       "[",
       control.keys,
       "] ",
@@ -468,9 +491,9 @@ var init_validate_path = __esm({
 
 // packages/experience-design-system-cli/src/tui/import/steps/02-token-input/screen.tsx
 import { useState as useState4 } from "react";
-import { Box as Box4, Text as Text4 } from "ink";
+import { Box as Box4, Text as Text5 } from "ink";
 import TextInput2 from "ink-text-input";
-import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
 function TokenInputScreen({
   onConfirm,
   onSkip,
@@ -495,26 +518,26 @@ function TokenInputScreen({
     else setFailure({ error: check.error, resolvedPath: check.resolvedPath });
   };
   return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx4(Text4, { bold: true, children: "Design tokens" }),
-    /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "Point me to your raw token file (e.g. ~/design-tokens/tokens.json). You can use ~, relative, or absolute paths. Claude will map it to DTCG format." }),
+    /* @__PURE__ */ jsx5(Text5, { bold: true, children: "Design tokens" }),
+    /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: "Point me to your raw token file (e.g. ~/design-tokens/tokens.json). You can use ~, relative, or absolute paths. Claude will map it to DTCG format." }),
     /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", marginTop: 1, children: [
       /* @__PURE__ */ jsxs4(Box4, { gap: 1, children: [
-        /* @__PURE__ */ jsx4(Text4, { color: PALETTE.accent, children: "?" }),
-        /* @__PURE__ */ jsx4(Text4, { children: "Token path:" }),
-        /* @__PURE__ */ jsx4(TextInput2, { value: tokenPath, onChange: change, onSubmit: submit })
+        /* @__PURE__ */ jsx5(Text5, { color: PALETTE.accent, children: "?" }),
+        /* @__PURE__ */ jsx5(Text5, { children: "Token path:" }),
+        /* @__PURE__ */ jsx5(TextInput2, { value: tokenPath, onChange: change, onSubmit: submit })
       ] }),
       failure && /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
-        /* @__PURE__ */ jsxs4(Text4, { color: PALETTE.error, children: [
+        /* @__PURE__ */ jsxs4(Text5, { color: PALETTE.error, children: [
           "\u2717 ",
           failure.error
         ] }),
-        /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+        /* @__PURE__ */ jsxs4(Text5, { dimColor: true, children: [
           " Resolved to: ",
           failure.resolvedPath
         ] })
       ] })
     ] }),
-    /* @__PURE__ */ jsx4(Box4, { marginTop: 1, gap: 3, children: TOKEN_INPUT_CONTROLS.map((control) => /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+    /* @__PURE__ */ jsx5(Box4, { marginTop: 1, gap: 3, children: TOKEN_INPUT_CONTROLS.map((control) => /* @__PURE__ */ jsxs4(Text5, { dimColor: true, children: [
       "[",
       control.keys,
       "] ",
@@ -684,6 +707,9 @@ function generateSessionId() {
 function sessionDebugDir() {
   return join5(debugSessionsDir(), SESSION_ID);
 }
+function currentDebugSessionDir() {
+  return sessionDebugDir();
+}
 async function isDebugModeEnabled() {
   try {
     return (await readDebugModeSetting()).enabled;
@@ -801,13 +827,55 @@ var init_debug_store = __esm({
   }
 });
 
+// packages/experience-design-system-cli/src/tui/help/help-info.ts
+async function readHelpInfo() {
+  const debugMode = await readDebugModeSetting();
+  return {
+    storage: [
+      { label: "Config folder", value: configRoot() },
+      { label: "Settings file", value: configFilePath() },
+      { label: "Debug logs", value: debugSessionsDir() }
+    ],
+    troubleshooting: [
+      { label: "CLI version", value: readPackageVersion() },
+      { label: "Node", value: process.version },
+      { label: "Platform", value: `${process.platform} ${process.arch}` },
+      { label: "Debug Mode", value: debugMode.enabled ? "on" : "off" },
+      {
+        label: "This session",
+        value: debugMode.enabled ? currentDebugSessionDir() : "no logs written while Debug Mode is off"
+      }
+    ]
+  };
+}
+var init_help_info = __esm({
+  "packages/experience-design-system-cli/src/tui/help/help-info.ts"() {
+    "use strict";
+    init_config();
+    init_debug_store();
+    init_debug_mode_store();
+    init_version();
+  }
+});
+
 // packages/experience-design-system-cli/src/tui/help/PageContainer.tsx
-import { useEffect as useEffect3 } from "react";
-import { Box as Box5, Text as Text5, useInput as useInput5 } from "ink";
-import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
+import { useEffect as useEffect3, useState as useState5 } from "react";
+import { Box as Box5, Text as Text6, useInput as useInput5 } from "ink";
+import { Fragment, jsx as jsx6, jsxs as jsxs5 } from "react/jsx-runtime";
+function Section({ title, rows }) {
+  return /* @__PURE__ */ jsxs5(Box5, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx6(Text6, { bold: true, color: PALETTE.accent, children: title }),
+    rows.map((row) => /* @__PURE__ */ jsxs5(Box5, { gap: 1, children: [
+      /* @__PURE__ */ jsx6(Box5, { width: 14, flexShrink: 0, children: /* @__PURE__ */ jsx6(Text6, { dimColor: true, children: row.label }) }),
+      /* @__PURE__ */ jsx6(Text6, { children: row.value })
+    ] }, row.label))
+  ] });
+}
 function HelpScreen({ onDone }) {
+  const [info, setInfo] = useState5();
   useEffect3(() => {
     startDebugRun({ flow: "help", step: "01-help", menuOption: "Help", inputs: {} });
+    void readHelpInfo().then(setInfo);
   }, []);
   const leave = (exitMethod) => {
     void finishDebugRun({ outputs: {}, status: "success", exitMethod });
@@ -823,30 +891,43 @@ function HelpScreen({ onDone }) {
       return;
     }
   });
-  return /* @__PURE__ */ jsxs5(Box5, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx5(Text5, { bold: true, children: "Help" }),
-    /* @__PURE__ */ jsx5(Text5, { children: " " }),
-    /* @__PURE__ */ jsx5(Text5, { children: "This is a placeholder screen for v2 help content." }),
-    /* @__PURE__ */ jsx5(Text5, { children: " " }),
-    /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: "[Enter] Complete [Esc/q] Exit \u2014 both return to Start" })
+  return /* @__PURE__ */ jsxs5(Box5, { flexDirection: "column", paddingX: 2, paddingY: 1, gap: 1, children: [
+    /* @__PURE__ */ jsx6(Text6, { bold: true, children: "Help" }),
+    info ? /* @__PURE__ */ jsxs5(Fragment, { children: [
+      /* @__PURE__ */ jsx6(Section, { title: "Where things are stored", rows: info.storage }),
+      /* @__PURE__ */ jsx6(Section, { title: "Troubleshooting", rows: info.troubleshooting }),
+      /* @__PURE__ */ jsx6(Text6, { dimColor: true, children: "Hit a problem? Turn on Debug Mode in Settings, reproduce it, then share the session folder above. The CMA token is redacted from those logs." })
+    ] }) : /* @__PURE__ */ jsx6(Text6, { color: PALETTE.accent, children: "Loading..." }),
+    /* @__PURE__ */ jsx6(
+      ControlHints,
+      {
+        hints: [
+          { keys: "\u23CE", label: "done" },
+          { keys: "Esc/q", label: "back to start" }
+        ]
+      }
+    )
   ] });
 }
 var init_PageContainer2 = __esm({
   "packages/experience-design-system-cli/src/tui/help/PageContainer.tsx"() {
     "use strict";
+    init_home_theme();
     init_debug_store();
+    init_control_hints();
+    init_help_info();
   }
 });
 
 // packages/experience-design-system-cli/src/tui/settings/PageContainer.tsx
-import { useState as useState5 } from "react";
-import { Box as Box6, Text as Text6, useInput as useInput6 } from "ink";
-import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
+import { useState as useState6 } from "react";
+import { Box as Box6, Text as Text7, useInput as useInput6 } from "ink";
+import { jsx as jsx7, jsxs as jsxs6 } from "react/jsx-runtime";
 function SettingsScreen({
   onNavigate,
   onBack
 }) {
-  const [focusIdx, setFocusIdx] = useState5(0);
+  const [focusIdx, setFocusIdx] = useState6(0);
   const items = [
     { label: "Configuration", screen: "settings-configuration" },
     { label: "Opt-in Analytics", screen: "settings-opt-in-analytics" },
@@ -873,19 +954,29 @@ function SettingsScreen({
     }
   });
   return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx6(Text6, { bold: true, children: "Settings" }),
-    /* @__PURE__ */ jsx6(Text6, { children: " " }),
-    items.map((item, i) => /* @__PURE__ */ jsxs6(Text6, { color: i === focusIdx ? "cyan" : void 0, children: [
+    /* @__PURE__ */ jsx7(Text7, { bold: true, children: "Settings" }),
+    /* @__PURE__ */ jsx7(Text7, { children: " " }),
+    items.map((item, i) => /* @__PURE__ */ jsxs6(Text7, { color: i === focusIdx ? "cyan" : void 0, children: [
       i === focusIdx ? "> " : "  ",
       item.label
     ] }, item.label)),
-    /* @__PURE__ */ jsx6(Text6, { children: " " }),
-    /* @__PURE__ */ jsx6(Text6, { dimColor: true, children: "[\u2191/\u2193] Navigate [Enter] Select [Esc/q] Back to Start" })
+    /* @__PURE__ */ jsx7(Text7, { children: " " }),
+    /* @__PURE__ */ jsx7(
+      ControlHints,
+      {
+        hints: [
+          { keys: "\u2191/\u2193", label: "move" },
+          { keys: "\u23CE", label: "select" },
+          { keys: "Esc/q", label: "back" }
+        ]
+      }
+    )
   ] });
 }
 var init_PageContainer3 = __esm({
   "packages/experience-design-system-cli/src/tui/settings/PageContainer.tsx"() {
     "use strict";
+    init_control_hints();
   }
 });
 
@@ -931,10 +1022,10 @@ var init_config_store = __esm({
 });
 
 // packages/experience-design-system-cli/src/tui/settings/contentful-configuration/ContentfulConfigScreen.tsx
-import { useEffect as useEffect4, useState as useState6 } from "react";
-import { Box as Box7, Text as Text7, useInput as useInput7 } from "ink";
+import { useEffect as useEffect4, useState as useState7 } from "react";
+import { Box as Box7, Text as Text8, useInput as useInput7 } from "ink";
 import TextInput3 from "ink-text-input";
-import { Fragment, jsx as jsx7, jsxs as jsxs7 } from "react/jsx-runtime";
+import { Fragment as Fragment2, jsx as jsx8, jsxs as jsxs7 } from "react/jsx-runtime";
 function debugFields(config) {
   return {
     space_id: config?.spaceId ?? "",
@@ -946,13 +1037,13 @@ function debugFields(config) {
   };
 }
 function ConfigurationScreen({ onDone }) {
-  const [stage, setStage] = useState6("loading");
-  const [config, setConfig] = useState6(null);
-  const [activeField, setActiveField] = useState6("spaceId");
-  const [notice, setNotice] = useState6(null);
-  const [lastSaved, setLastSaved] = useState6(null);
-  const [editing, setEditing] = useState6(false);
-  const [valueBeforeEdit, setValueBeforeEdit] = useState6("");
+  const [stage, setStage] = useState7("loading");
+  const [config, setConfig] = useState7(null);
+  const [activeField, setActiveField] = useState7("spaceId");
+  const [notice, setNotice] = useState7(null);
+  const [lastSaved, setLastSaved] = useState7(null);
+  const [editing, setEditing] = useState7(false);
+  const [valueBeforeEdit, setValueBeforeEdit] = useState7("");
   useEffect4(() => {
     readCredentials().then((cfg) => {
       setConfig(cfg);
@@ -1031,25 +1122,25 @@ function ConfigurationScreen({ onDone }) {
   });
   if (stage === "loading") {
     return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-      /* @__PURE__ */ jsx7(Text7, { bold: true, children: "Configuration" }),
-      /* @__PURE__ */ jsx7(Text7, { children: " " }),
-      /* @__PURE__ */ jsx7(Text7, { color: PALETTE.accent, children: "Loading..." })
+      /* @__PURE__ */ jsx8(Text8, { bold: true, children: "Configuration" }),
+      /* @__PURE__ */ jsx8(Text8, { children: " " }),
+      /* @__PURE__ */ jsx8(Text8, { color: PALETTE.accent, children: "Loading..." })
     ] });
   }
   return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx7(Text7, { bold: true, children: "Configuration" }),
-    /* @__PURE__ */ jsx7(Text7, { children: " " }),
-    /* @__PURE__ */ jsx7(Box7, { flexDirection: "column", children: FIELD_ORDER.map((field) => {
+    /* @__PURE__ */ jsx8(Text8, { bold: true, children: "Configuration" }),
+    /* @__PURE__ */ jsx8(Text8, { children: " " }),
+    /* @__PURE__ */ jsx8(Box7, { flexDirection: "column", children: FIELD_ORDER.map((field) => {
       const isActive = activeField === field;
       const value = fieldValue(field);
       const display = field === "cmaToken" ? "\u2022".repeat(value.length) : value;
       return /* @__PURE__ */ jsxs7(Box7, { gap: 1, children: [
-        /* @__PURE__ */ jsx7(Text7, { color: isActive ? PALETTE.accent : void 0, children: isActive ? "\u276F" : " " }),
-        /* @__PURE__ */ jsxs7(Text7, { bold: isActive, children: [
+        /* @__PURE__ */ jsx8(Text8, { color: isActive ? PALETTE.accent : void 0, children: isActive ? "\u276F" : " " }),
+        /* @__PURE__ */ jsxs7(Text8, { bold: isActive, children: [
           FIELD_LABELS[field],
           ":"
         ] }),
-        isActive && editing ? /* @__PURE__ */ jsx7(
+        isActive && editing ? /* @__PURE__ */ jsx8(
           TextInput3,
           {
             value,
@@ -1057,19 +1148,35 @@ function ConfigurationScreen({ onDone }) {
             onSubmit: () => setEditing(false),
             mask: field === "cmaToken" ? "\u2022" : void 0
           }
-        ) : /* @__PURE__ */ jsx7(Text7, { children: display || /* @__PURE__ */ jsx7(Text7, { dimColor: true, children: "(empty)" }) })
+        ) : /* @__PURE__ */ jsx8(Text8, { children: display || /* @__PURE__ */ jsx8(Text8, { dimColor: true, children: "(empty)" }) })
       ] }, field);
     }) }),
-    notice && /* @__PURE__ */ jsxs7(Fragment, { children: [
-      /* @__PURE__ */ jsx7(Text7, { children: " " }),
-      /* @__PURE__ */ jsxs7(Text7, { color: notice.kind === "success" ? PALETTE.success : PALETTE.error, children: [
+    notice && /* @__PURE__ */ jsxs7(Fragment2, { children: [
+      /* @__PURE__ */ jsx8(Text8, { children: " " }),
+      /* @__PURE__ */ jsxs7(Text8, { color: notice.kind === "success" ? PALETTE.success : PALETTE.error, children: [
         notice.kind === "success" ? "\u2713" : "\u2717",
         " ",
         notice.text
       ] })
     ] }),
-    /* @__PURE__ */ jsx7(Text7, { children: " " }),
-    /* @__PURE__ */ jsx7(Text7, { dimColor: true, children: editing ? "[type] Edit \xB7 [\u2190/\u2192] Move cursor \xB7 [Enter] Done \xB7 [Esc] Cancel edit" : "[\u2191/\u2193] Switch field \xB7 [Enter] Edit \xB7 [c] Clear field \xB7 [s] Save \xB7 [Esc/q] Quit without saving" })
+    /* @__PURE__ */ jsx8(Text8, { children: " " }),
+    /* @__PURE__ */ jsx8(
+      ControlHints,
+      {
+        hints: editing ? [
+          { keys: "type", label: "edit" },
+          { keys: "\u2190/\u2192", label: "move cursor" },
+          { keys: "\u23CE", label: "done" },
+          { keys: "Esc", label: "cancel edit" }
+        ] : [
+          { keys: "\u2191/\u2193", label: "move" },
+          { keys: "\u23CE", label: "edit" },
+          { keys: "c", label: "clear" },
+          { keys: "s", label: "save" },
+          { keys: "Esc/q", label: "quit without saving" }
+        ]
+      }
+    )
   ] });
 }
 var FIELD_ORDER, FIELD_LABELS;
@@ -1079,6 +1186,7 @@ var init_ContentfulConfigScreen = __esm({
     init_home_theme();
     init_config_store();
     init_debug_store();
+    init_control_hints();
     FIELD_ORDER = [
       "spaceId",
       "environmentId",
@@ -1120,12 +1228,12 @@ var init_analytics_store = __esm({
 });
 
 // packages/experience-design-system-cli/src/tui/settings/opt-in-analytics/screen.tsx
-import { useEffect as useEffect5, useState as useState7 } from "react";
-import { Box as Box8, Text as Text8, useInput as useInput8 } from "ink";
-import { Fragment as Fragment2, jsx as jsx8, jsxs as jsxs8 } from "react/jsx-runtime";
+import { useEffect as useEffect5, useState as useState8 } from "react";
+import { Box as Box8, Text as Text9, useInput as useInput8 } from "ink";
+import { Fragment as Fragment3, jsx as jsx9, jsxs as jsxs8 } from "react/jsx-runtime";
 function OptInAnalyticsScreen({ onDone }) {
-  const [loading, setLoading] = useState7(true);
-  const [enabled, setEnabled] = useState7(true);
+  const [loading, setLoading] = useState8(true);
+  const [enabled, setEnabled] = useState8(true);
   useEffect5(() => {
     readAnalyticsSetting().then((setting) => {
       setEnabled(setting.enabled);
@@ -1154,20 +1262,28 @@ function OptInAnalyticsScreen({ onDone }) {
     }
   });
   return /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx8(Text8, { bold: true, children: "Settings \u203A Opt-in Analytics" }),
-    /* @__PURE__ */ jsx8(Text8, { children: " " }),
-    loading ? /* @__PURE__ */ jsx8(Text8, { color: PALETTE.muted, children: "Loading\u2026" }) : /* @__PURE__ */ jsxs8(Fragment2, { children: [
-      /* @__PURE__ */ jsxs8(Text8, { children: [
+    /* @__PURE__ */ jsx9(Text9, { bold: true, children: "Settings \u203A Opt-in Analytics" }),
+    /* @__PURE__ */ jsx9(Text9, { children: " " }),
+    loading ? /* @__PURE__ */ jsx9(Text9, { color: PALETTE.muted, children: "Loading\u2026" }) : /* @__PURE__ */ jsxs8(Fragment3, { children: [
+      /* @__PURE__ */ jsxs8(Text9, { children: [
         "Share anonymous usage data:",
         " ",
-        /* @__PURE__ */ jsx8(Text8, { bold: true, color: enabled ? PALETTE.success : PALETTE.muted, children: enabled ? "On" : "Off" })
+        /* @__PURE__ */ jsx9(Text9, { bold: true, color: enabled ? PALETTE.success : PALETTE.muted, children: enabled ? "On" : "Off" })
       ] }),
-      /* @__PURE__ */ jsx8(Text8, { children: " " }),
-      /* @__PURE__ */ jsx8(Text8, { dimColor: true, children: "Shares which CLI commands are used and where imports succeed or fail." }),
-      /* @__PURE__ */ jsx8(Text8, { dimColor: true, children: "Never includes source code, file paths, credentials, or authored content." })
+      /* @__PURE__ */ jsx9(Text9, { children: " " }),
+      /* @__PURE__ */ jsx9(Text9, { dimColor: true, children: "Shares which CLI commands are used and where imports succeed or fail." }),
+      /* @__PURE__ */ jsx9(Text9, { dimColor: true, children: "Never includes source code, file paths, credentials, or authored content." })
     ] }),
-    /* @__PURE__ */ jsx8(Text8, { children: " " }),
-    /* @__PURE__ */ jsx8(Text8, { dimColor: true, children: "[Enter/Space] Toggle [Esc/q] Back to Settings" })
+    /* @__PURE__ */ jsx9(Text9, { children: " " }),
+    /* @__PURE__ */ jsx9(
+      ControlHints,
+      {
+        hints: [
+          { keys: "\u23CE/Space", label: "toggle" },
+          { keys: "Esc/q", label: "back" }
+        ]
+      }
+    )
   ] });
 }
 var init_screen3 = __esm({
@@ -1176,15 +1292,16 @@ var init_screen3 = __esm({
     init_home_theme();
     init_analytics_store();
     init_debug_store();
+    init_control_hints();
   }
 });
 
 // packages/experience-design-system-cli/src/tui/upgrade/PageContainer.tsx
-import { useEffect as useEffect6, useState as useState8 } from "react";
-import { Box as Box9, Text as Text9, useInput as useInput9 } from "ink";
-import { jsx as jsx9, jsxs as jsxs9 } from "react/jsx-runtime";
+import { useEffect as useEffect6, useState as useState9 } from "react";
+import { Box as Box9, Text as Text10, useInput as useInput9 } from "ink";
+import { jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
 function UpgradeScreen({ onDone }) {
-  const [upgradeCheck, setUpgradeCheck] = useState8();
+  const [upgradeCheck, setUpgradeCheck] = useState9();
   useEffect6(() => {
     startDebugRun({
       flow: "upgrade",
@@ -1206,11 +1323,11 @@ function UpgradeScreen({ onDone }) {
     }
   });
   return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx9(Text9, { bold: true, children: "Upgrade" }),
-    /* @__PURE__ */ jsx9(Text9, { children: " " }),
+    /* @__PURE__ */ jsx10(Text10, { bold: true, children: "Upgrade" }),
+    /* @__PURE__ */ jsx10(Text10, { children: " " }),
     renderBody(upgradeCheck),
-    /* @__PURE__ */ jsx9(Text9, { children: " " }),
-    /* @__PURE__ */ jsxs9(Text9, { bold: true, color: PALETTE.accent, children: [
+    /* @__PURE__ */ jsx10(Text10, { children: " " }),
+    /* @__PURE__ */ jsxs9(Text10, { bold: true, color: PALETTE.accent, children: [
       FOCUS_MARKER,
       " Go Back"
     ] })
@@ -1218,34 +1335,34 @@ function UpgradeScreen({ onDone }) {
 }
 function renderBody(upgradeCheck) {
   if (!upgradeCheck) {
-    return /* @__PURE__ */ jsx9(Text9, { color: PALETTE.muted, children: "Checking for updates\u2026" });
+    return /* @__PURE__ */ jsx10(Text10, { color: PALETTE.muted, children: "Checking for updates\u2026" });
   }
   if (upgradeCheck.status === "error") {
-    return /* @__PURE__ */ jsx9(Text9, { color: PALETTE.warning, children: "Couldn't check for updates \u2014 check your network connection and try again." });
+    return /* @__PURE__ */ jsx10(Text10, { color: PALETTE.warning, children: "Couldn't check for updates \u2014 check your network connection and try again." });
   }
   if (upgradeCheck.status === "up-to-date") {
-    return /* @__PURE__ */ jsxs9(Text9, { color: PALETTE.success, children: [
+    return /* @__PURE__ */ jsxs9(Text10, { color: PALETTE.success, children: [
       "You're already on the latest version (v",
       upgradeCheck.current,
       ")."
     ] });
   }
   return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", children: [
-    /* @__PURE__ */ jsxs9(Text9, { color: PALETTE.muted, children: [
-      /* @__PURE__ */ jsxs9(Text9, { bold: true, color: PALETTE.success, children: [
+    /* @__PURE__ */ jsxs9(Text10, { color: PALETTE.muted, children: [
+      /* @__PURE__ */ jsxs9(Text10, { bold: true, color: PALETTE.success, children: [
         "v",
         upgradeCheck.latest
       ] }),
       " ",
       "is available (you're on ",
-      /* @__PURE__ */ jsxs9(Text9, { bold: true, children: [
+      /* @__PURE__ */ jsxs9(Text10, { bold: true, children: [
         "v",
         upgradeCheck.current
       ] }),
       "). Exit this program, cd into the root of your local clone of contentful/experience-design-system-sdk-public, then run:"
     ] }),
-    /* @__PURE__ */ jsx9(Text9, { children: " " }),
-    /* @__PURE__ */ jsx9(Box9, { flexDirection: "column", borderStyle: "round", borderColor: PALETTE.border, paddingX: 1, children: UPGRADE_COMMANDS.map((cmd) => /* @__PURE__ */ jsx9(Text9, { bold: true, children: cmd }, cmd)) })
+    /* @__PURE__ */ jsx10(Text10, { children: " " }),
+    /* @__PURE__ */ jsx10(Box9, { flexDirection: "column", borderStyle: "round", borderColor: PALETTE.border, paddingX: 1, children: UPGRADE_COMMANDS.map((cmd) => /* @__PURE__ */ jsx10(Text10, { bold: true, children: cmd }, cmd)) })
   ] });
 }
 var UPGRADE_COMMANDS;
@@ -1260,12 +1377,12 @@ var init_PageContainer4 = __esm({
 });
 
 // packages/experience-design-system-cli/src/tui/settings/debug-mode/screen.tsx
-import { useEffect as useEffect7, useState as useState9 } from "react";
-import { Box as Box10, Text as Text10, useInput as useInput10 } from "ink";
-import { jsx as jsx10, jsxs as jsxs10 } from "react/jsx-runtime";
+import { useEffect as useEffect7, useState as useState10 } from "react";
+import { Box as Box10, Text as Text11, useInput as useInput10 } from "ink";
+import { jsx as jsx11, jsxs as jsxs10 } from "react/jsx-runtime";
 function DebugModeScreen({ onDone }) {
-  const [loading, setLoading] = useState9(true);
-  const [enabled, setEnabled] = useState9(true);
+  const [loading, setLoading] = useState10(true);
+  const [enabled, setEnabled] = useState10(true);
   useEffect7(() => {
     readDebugModeSetting().then((setting) => {
       setEnabled(setting.enabled);
@@ -1294,15 +1411,23 @@ function DebugModeScreen({ onDone }) {
     }
   });
   return /* @__PURE__ */ jsxs10(Box10, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [
-    /* @__PURE__ */ jsx10(Text10, { bold: true, children: "Settings \u203A Debug Mode" }),
-    /* @__PURE__ */ jsx10(Text10, { children: " " }),
-    loading ? /* @__PURE__ */ jsx10(Text10, { color: PALETTE.muted, children: "Loading\u2026" }) : /* @__PURE__ */ jsxs10(Text10, { children: [
+    /* @__PURE__ */ jsx11(Text11, { bold: true, children: "Settings \u203A Debug Mode" }),
+    /* @__PURE__ */ jsx11(Text11, { children: " " }),
+    loading ? /* @__PURE__ */ jsx11(Text11, { color: PALETTE.muted, children: "Loading\u2026" }) : /* @__PURE__ */ jsxs10(Text11, { children: [
       "Debug logging:",
       " ",
-      /* @__PURE__ */ jsx10(Text10, { bold: true, color: enabled ? PALETTE.success : PALETTE.muted, children: enabled ? "On" : "Off" })
+      /* @__PURE__ */ jsx11(Text11, { bold: true, color: enabled ? PALETTE.success : PALETTE.muted, children: enabled ? "On" : "Off" })
     ] }),
-    /* @__PURE__ */ jsx10(Text10, { children: " " }),
-    /* @__PURE__ */ jsx10(Text10, { dimColor: true, children: "[Enter/Space] Toggle [Esc/q] Back to Settings" })
+    /* @__PURE__ */ jsx11(Text11, { children: " " }),
+    /* @__PURE__ */ jsx11(
+      ControlHints,
+      {
+        hints: [
+          { keys: "\u23CE/Space", label: "toggle" },
+          { keys: "Esc/q", label: "back" }
+        ]
+      }
+    )
   ] });
 }
 var init_screen4 = __esm({
@@ -1311,6 +1436,7 @@ var init_screen4 = __esm({
     init_home_theme();
     init_debug_mode_store();
     init_debug_store();
+    init_control_hints();
   }
 });
 
@@ -1319,14 +1445,14 @@ var app_exports = {};
 __export(app_exports, {
   runApp: () => runApp
 });
-import { useEffect as useEffect8, useState as useState10 } from "react";
-import { Fragment as Fragment3, jsx as jsx11 } from "react/jsx-runtime";
+import { useEffect as useEffect8, useState as useState11 } from "react";
+import { Fragment as Fragment4, jsx as jsx12 } from "react/jsx-runtime";
 function App({ onLaunchImport, importExitCode }) {
   const returnedFromImport = importExitCode !== void 0;
-  const [screen, setScreen] = useState10(returnedFromImport ? "import" : "start");
-  const [showImportResult, setShowImportResult] = useState10(returnedFromImport);
-  const [projectPath, setProjectPath] = useState10();
-  const [importDefaults, setImportDefaults] = useState10();
+  const [screen, setScreen] = useState11(returnedFromImport ? "import" : "start");
+  const [showImportResult, setShowImportResult] = useState11(returnedFromImport);
+  const [projectPath, setProjectPath] = useState11();
+  const [importDefaults, setImportDefaults] = useState11();
   useEffect8(() => {
     if (screen !== "import") {
       setImportDefaults(void 0);
@@ -1349,12 +1475,12 @@ function App({ onLaunchImport, importExitCode }) {
   };
   switch (screen) {
     case "import":
-      if (showImportResult) return /* @__PURE__ */ jsx11(ImportScreen, { exitCode: importExitCode, onDone: finishImportResult });
-      if (importDefaults === void 0) return /* @__PURE__ */ jsx11(Fragment3, {});
+      if (showImportResult) return /* @__PURE__ */ jsx12(ImportScreen, { exitCode: importExitCode, onDone: finishImportResult });
+      if (importDefaults === void 0) return /* @__PURE__ */ jsx12(Fragment4, {});
       if (projectPath === void 0) {
-        return /* @__PURE__ */ jsx11(WelcomeScreen, { onContinue: setProjectPath, onQuit: leaveImport, initialPath: importDefaults.componentDir });
+        return /* @__PURE__ */ jsx12(WelcomeScreen, { onContinue: setProjectPath, onQuit: leaveImport, initialPath: importDefaults.componentDir });
       }
-      return /* @__PURE__ */ jsx11(
+      return /* @__PURE__ */ jsx12(
         TokenInputScreen,
         {
           initialPath: importDefaults.tokenFile,
@@ -1364,25 +1490,25 @@ function App({ onLaunchImport, importExitCode }) {
         }
       );
     case "help":
-      return /* @__PURE__ */ jsx11(HelpScreen, { onDone: goToStart });
+      return /* @__PURE__ */ jsx12(HelpScreen, { onDone: goToStart });
     case "upgrade":
-      return /* @__PURE__ */ jsx11(UpgradeScreen, { onDone: goToStart });
+      return /* @__PURE__ */ jsx12(UpgradeScreen, { onDone: goToStart });
     case "settings":
-      return /* @__PURE__ */ jsx11(SettingsScreen, { onNavigate: setScreen, onBack: goToStart });
+      return /* @__PURE__ */ jsx12(SettingsScreen, { onNavigate: setScreen, onBack: goToStart });
     case "settings-configuration":
-      return /* @__PURE__ */ jsx11(ConfigurationScreen, { onDone: goToSettings });
+      return /* @__PURE__ */ jsx12(ConfigurationScreen, { onDone: goToSettings });
     case "settings-opt-in-analytics":
-      return /* @__PURE__ */ jsx11(OptInAnalyticsScreen, { onDone: goToSettings });
+      return /* @__PURE__ */ jsx12(OptInAnalyticsScreen, { onDone: goToSettings });
     case "settings-debug-mode":
-      return /* @__PURE__ */ jsx11(DebugModeScreen, { onDone: goToSettings });
+      return /* @__PURE__ */ jsx12(DebugModeScreen, { onDone: goToSettings });
     case "start":
-      return /* @__PURE__ */ jsx11(HomeScreen, { onNavigate: setScreen });
+      return /* @__PURE__ */ jsx12(HomeScreen, { onNavigate: setScreen });
   }
 }
 async function renderUntilImportRequestedOrExit(renderApp, importExitCode) {
   let requestedImport;
   const instance = renderApp(
-    /* @__PURE__ */ jsx11(
+    /* @__PURE__ */ jsx12(
       App,
       {
         importExitCode,