@ekzs/cli 0.3.0 → 0.3.3

package/README.md

@@ -8,17 +8,43 @@ Runs **in your repo** with Composer 2.5 Fast. Edits files directly.
 
 ```bash
 npm install -g @ekzs/cli
-# or from this monorepo:
-npm run build --prefix packages/cli
+```
+
+Clean install (~15 packages) — BYOK with OpenAI, Anthropic, DeepSeek, etc. Keys via `ekz providers`.
+
+**Cursor provider only** (optional — pulls native deps + npm deprecation noise from `@cursor/sdk`):
+
+```bash
+npm install -g @cursor/sdk
+```
+
+Or install both at once:
+
+```bash
+npm install -g @ekzs/cli @cursor/sdk
 ```
 
 ## Setup (BYOK)
 
-Configure your LLM API keys once — stored in `~/.ekz/providers.json` (not in `.env`):
+First run:
 
 ```bash
-ekz providers
-# or inside the REPL: /providers
+ekz setup
+# aliases: ekz configurar · ekz 设置
+```
+
+Wizard steps: **language** → **your name** → **Configurar provedor** (or offline).
+
+Stored in `~/.ekz/config.json` (name, locale) and `~/.ekz/providers.json` (API keys).
+
+Without a provider, `ekz` shows:
+
+```
+Setup required · Configuração necessária · 需要设置
+
+  pt: Corre `ekz setup` ou `ekz --offline`
+  en: Run `ekz setup` or `ekz --offline`
+  zh: 运行 `ekz setup` 或 `ekz --offline`
 ```
 
 Supported providers: **Cursor**, **OpenAI**, **Anthropic**, **DeepSeek**, **Kimi**, **Groq**, **Mistral**, **Google Gemini**, **Ollama**.

package/dist/commands/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/commands/ask.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAA0B,MAAM,kBAAkB,CAAC;AAyC1E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,mDAAmD;AACnD,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA0B1E;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,iBAO9D;AAgDD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,iBA2DA;AAED,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM/E"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/commands/ask.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAA0B,MAAM,kBAAkB,CAAC;AAyC1E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,mDAAmD;AACnD,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA0B1E;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,iBAO9D;AAgDD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,iBAwEA;AAED,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM/E"}

package/dist/commands/ask.js

@@ -5,6 +5,7 @@ import { parseLocale, uiStrings } from "../lib/locale.js";
 import { parseMode } from "../lib/mode.js";
 import { fail, heading, info, ok } from "../lib/output.js";
 import { loadPreferences, savePreferences } from "../lib/preferences.js";
+import { ensureAgentReady, offlineModelLabel } from "../lib/onboarding.js";
 import { executeByokAskTurn } from "../lib/providers/chat.js";
 import { executeCursorAskTurn } from "../lib/providers/cursor-runner.js";
 import { isCursorProvider, requireActiveCredentials, ProviderSetupError, } from "../lib/providers/credentials.js";
@@ -13,7 +14,6 @@ import { redactText } from "../lib/redact.js";
 import { askWithPlaceholder, formatInputPrompt } from "../lib/ui/prompt.js";
 import { inputPlaceholder } from "../lib/ui/splash.js";
 function deterministicAnswer(question, ctx, locale) {
-    const p = providersCommandLabels(locale);
     const lines = ["## Ekz assistant (offline)", "", question, ""];
     if (ctx.doctor.issues.length) {
         lines.push("### Issues", ...ctx.doctor.issues.map((i) => `- ${i}`), "");
@@ -21,7 +21,7 @@ function deterministicAnswer(question, ctx, locale) {
     if (ctx.scan.length) {
         lines.push("### Scan", ...ctx.scan.slice(0, 8).map((f) => `- \`${f.file}:${f.line}\` · ${f.message}`), "");
     }
-    lines.push("### Next steps", `- Run \`${p.cli}\` or \`${p.repl}\` and paste your LLM API key (BYOK)`, "- Or run `ekz --mode agent` with your provider configured");
+    lines.push("### Next steps", "- Run `ekz setup` to configure language, name, and provider", "- Or `ekz --offline` for doctor/scan only");
     return lines.join("\n");
 }
 /** Q&A via BYOK provider (no local file edits). */
@@ -94,10 +94,23 @@ function handleAskMeta(line, locale) {
 export async function runInteractiveAsk(opts) {
     const prefs = loadPreferences(opts.cwd, opts.locale, "ask");
     let currentLocale = prefs.locale;
+    let askOffline = Boolean(opts.offline);
+    try {
+        const ready = await ensureAgentReady({
+            locale: currentLocale,
+            offlineFlag: opts.offline,
+        });
+        askOffline = ready.offline || askOffline;
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        return;
+    }
     printWelcome({
         cwd: opts.cwd,
         locale: currentLocale,
         mode: "ask",
+        model: askOffline ? offlineModelLabel(currentLocale) : undefined,
     });
     let turn = 0;
     while (true) {
@@ -134,7 +147,7 @@ export async function runInteractiveAsk(opts) {
         await executeAskTurn({
             cwd: opts.cwd,
             question: line,
-            offline: opts.offline,
+            offline: askOffline,
             quiet: true,
             locale: currentLocale,
         });

package/dist/commands/local-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-agent.d.ts","sourceRoot":"","sources":["../../src/commands/local-agent.ts"],"names":[],"mappings":"AAWA,OAAO,EAAsC,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAsBlF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAkPF,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,iBAuG1D;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAAC,iBAwE9F"}
+{"version":3,"file":"local-agent.d.ts","sourceRoot":"","sources":["../../src/commands/local-agent.ts"],"names":[],"mappings":"AAWA,OAAO,EAAsC,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAsBlF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA2PF,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,iBA0I1D;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAAC,iBAmG9F"}

package/dist/commands/local-agent.js

@@ -1,10 +1,10 @@
 import { resolve } from "path";
-import { Agent, CursorAgentError } from "@cursor/sdk";
 import { executeAskTurn } from "../commands/ask.js";
 import { runDoctor } from "../commands/doctor.js";
 import { runScan } from "../commands/scan.js";
 import { inputPlaceholder, printHelp, printLangSwitch, printModeSwitch, printWelcome } from "../lib/banner.js";
 import { loadProjectEnv } from "../lib/env.js";
+import { ensureAgentReady, offlineAgentHint, offlineModelLabel } from "../lib/onboarding.js";
 import { resolveReplMetaCommand, isProvidersMetaCommand } from "../lib/commands-i18n.js";
 import { buildAgentPrompt, buildBootstrapContext } from "../lib/context.js";
 import { resolveComposerModel } from "../lib/composer-model.js";
@@ -12,29 +12,31 @@ import { parseLocale, uiStrings } from "../lib/locale.js";
 import { modeRequiresCursorAgent, parseMode } from "../lib/mode.js";
 import { loadPreferences, savePreferences } from "../lib/preferences.js";
 import { runByokAgentTurn, usesCursorSdk } from "../lib/providers/agent-runner.js";
+import { CursorSdkMissingError, loadCursorSdk } from "../lib/providers/cursor-sdk.js";
 import { disposeAgent, streamRun } from "../lib/providers/cursor-runner.js";
-import { getProviderDefinition } from "../lib/providers/catalog.js";
-import { requireActiveCredentials, } from "../lib/providers/credentials.js";
+import { resolveActiveCredentials, resolveCredentialsWithOverride, } from "../lib/providers/credentials.js";
 import { runProvidersInteractive, formatActiveProviderLabel } from "../lib/providers/ui.js";
-import { maskApiKey } from "../lib/providers/store.js";
 import { clearSession, getSessionByIndex, loadSession, persistSession, saveNamedSession, } from "../lib/session.js";
 import { fail, info, ok, warn } from "../lib/output.js";
 import { turnDivider } from "../lib/theme.js";
 import { askWithPlaceholder, formatInputPrompt } from "../lib/ui/prompt.js";
-function resolveAgentCredentials(override, locale = "pt") {
-    if (override?.trim()) {
-        const def = getProviderDefinition("cursor");
-        if (!def)
-            throw new Error("Cursor provider missing from catalog.");
-        return {
-            id: "cursor",
-            definition: def,
-            apiKey: override.trim(),
-            model: resolveComposerModel().id,
-            maskedKey: maskApiKey(override.trim()),
-        };
+async function prepareAgentSession(opts, prefs) {
+    try {
+        const ready = await ensureAgentReady({
+            locale: prefs.locale,
+            offlineFlag: opts.askOffline,
+            apiKey: opts.apiKey,
+        });
+        return { offline: ready.offline, creds: ready.creds };
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return null;
     }
-    return requireActiveCredentials(locale);
+}
+function resolveAgentCredentials(override, locale = "pt") {
+    return resolveCredentialsWithOverride(override, locale);
 }
 function resolveCursorModel(creds) {
     return resolveComposerModel(process.env, creds.model);
@@ -53,12 +55,12 @@ async function runAgentTurn(options) {
         const ctx = await buildBootstrapContext(options.cwd);
         const prompt = buildAgentPrompt(options.task, ctx, options.locale);
         try {
-            await streamRun(options.cursorAgent, prompt);
+            await streamRun(options.cursorAgent, prompt, options.locale);
             console.log("\n");
             return { cursorAgent: options.cursorAgent, ok: true };
         }
         catch (err) {
-            if (err instanceof CursorAgentError) {
+            if (err instanceof Error && err.name === "CursorAgentError") {
                 fail(err.message);
                 return { cursorAgent: options.cursorAgent, ok: false };
             }
@@ -77,6 +79,7 @@ async function runAgentTurn(options) {
 async function createOrResumeAgent(opts, locale = "pt") {
     const cwd = resolve(opts.cwd);
     const creds = resolveAgentCredentials(opts.apiKey, locale);
+    const { Agent } = await loadCursorSdk(locale);
     const apiKey = creds.apiKey;
     const model = resolveCursorModel(creds);
     const usePlan = opts.mode === "plan" || Boolean(opts.plan);
@@ -195,6 +198,7 @@ async function resumeAgentInRepl(cwd, current, agentId, locale, apiKeyOverride)
                 ? "恢复会话仅适用于 Cursor provider。"
                 : "Resume session is Cursor-only.");
     }
+    const { Agent } = await loadCursorSdk(locale);
     const model = resolveCursorModel(creds);
     const agent = await Agent.resume(agentId, {
         apiKey: creds.apiKey,
@@ -210,24 +214,24 @@ export async function runLocalAgent(opts) {
     loadProjectEnv(cwd);
     const prefs = loadPreferences(cwd, opts.locale, opts.mode, opts.plan);
     const mode = prefs.mode;
-    const providerLabel = formatActiveProviderLabel(prefs.locale);
+    const session = await prepareAgentSession(opts, prefs);
+    if (!session)
+        return;
+    const { offline, creds: sessionCreds } = session;
+    const askOffline = offline || Boolean(opts.askOffline);
+    const providerLabel = askOffline
+        ? offlineModelLabel(prefs.locale)
+        : sessionCreds
+            ? formatActiveProviderLabel(prefs.locale)
+            : formatActiveProviderLabel(prefs.locale);
     if (mode === "ask") {
-        let askCreds;
-        try {
-            askCreds = resolveAgentCredentials(opts.apiKey, prefs.locale);
-        }
-        catch (err) {
-            fail(err instanceof Error ? err.message : String(err));
-            process.exitCode = 1;
-            return;
-        }
         printWelcome({ cwd, locale: prefs.locale, mode: "ask", model: providerLabel });
         if (opts.task.trim()) {
             info(`${uiStrings(prefs.locale).workingOn}: ${opts.task.slice(0, 120)}${opts.task.length > 120 ? "…" : ""}\n`);
             await executeAskTurn({
                 cwd,
                 question: opts.task.trim(),
-                offline: opts.askOffline,
+                offline: askOffline,
                 quiet: true,
                 locale: prefs.locale,
             });
@@ -240,23 +244,54 @@ export async function runLocalAgent(opts) {
                 locale: prefs.locale,
                 mode: "ask",
                 apiKey: opts.apiKey,
-                askOffline: opts.askOffline,
-                creds: askCreds,
+                askOffline,
+                creds: sessionCreds,
+                offline: askOffline,
+            });
+        }
+        return;
+    }
+    if (askOffline) {
+        printWelcome({ cwd, locale: prefs.locale, mode, model: providerLabel });
+        savePreferences(cwd, { mode });
+        if (opts.task.trim()) {
+            info(`${uiStrings(prefs.locale).workingOn}: ${opts.task.slice(0, 120)}${opts.task.length > 120 ? "…" : ""}\n`);
+            warn(offlineAgentHint(prefs.locale));
+        }
+        if (opts.interactive !== false) {
+            await runRepl({
+                agent: null,
+                cwd,
+                locale: prefs.locale,
+                mode,
+                apiKey: opts.apiKey,
+                askOffline: true,
+                creds: null,
+                offline: true,
             });
         }
         return;
     }
+    if (!sessionCreds) {
+        fail(offlineAgentHint(prefs.locale));
+        process.exitCode = 1;
+        return;
+    }
     let agent = null;
     let resumed = false;
-    let creds;
+    const creds = sessionCreds;
     try {
-        creds = resolveAgentCredentials(opts.apiKey, prefs.locale);
         if (usesCursorSdk(creds)) {
             ({ agent, resumed } = await createOrResumeAgent({ ...opts, mode }, prefs.locale));
         }
     }
     catch (err) {
-        if (err instanceof CursorAgentError) {
+        if (err instanceof CursorSdkMissingError) {
+            fail(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        if (err instanceof Error && err.name === "CursorAgentError") {
             fail(`Agent startup failed: ${err.message}`);
             process.exitCode = 1;
             return;
@@ -298,8 +333,9 @@ export async function runLocalAgent(opts) {
                 locale: prefs.locale,
                 mode,
                 apiKey: opts.apiKey,
-                askOffline: opts.askOffline,
+                askOffline,
                 creds,
+                offline: false,
             });
         }
         else {
@@ -316,17 +352,15 @@ export async function runInteractiveAgent(opts) {
     loadProjectEnv(cwd);
     const prefs = loadPreferences(cwd, opts.locale, opts.mode, opts.plan);
     const mode = prefs.mode;
-    const providerLabel = formatActiveProviderLabel(prefs.locale);
+    const session = await prepareAgentSession({ ...opts, task: "" }, prefs);
+    if (!session)
+        return;
+    const { offline, creds: sessionCreds } = session;
+    const askOffline = offline || Boolean(opts.askOffline);
+    const providerLabel = askOffline
+        ? offlineModelLabel(prefs.locale)
+        : formatActiveProviderLabel(prefs.locale);
     if (mode === "ask") {
-        let creds;
-        try {
-            creds = resolveAgentCredentials(opts.apiKey, prefs.locale);
-        }
-        catch (err) {
-            fail(err instanceof Error ? err.message : String(err));
-            process.exitCode = 1;
-            return;
-        }
         printWelcome({ cwd, locale: prefs.locale, mode: "ask", model: providerLabel });
         await runRepl({
             agent: null,
@@ -334,22 +368,47 @@ export async function runInteractiveAgent(opts) {
             locale: prefs.locale,
             mode: "ask",
             apiKey: opts.apiKey,
-            askOffline: opts.askOffline,
-            creds,
+            askOffline,
+            creds: sessionCreds,
+            offline: askOffline,
         });
         return;
     }
+    if (askOffline) {
+        printWelcome({ cwd, locale: prefs.locale, mode, model: providerLabel });
+        savePreferences(cwd, { mode });
+        await runRepl({
+            agent: null,
+            cwd,
+            locale: prefs.locale,
+            mode,
+            apiKey: opts.apiKey,
+            askOffline: true,
+            creds: null,
+            offline: true,
+        });
+        return;
+    }
+    if (!sessionCreds) {
+        fail(offlineAgentHint(prefs.locale));
+        process.exitCode = 1;
+        return;
+    }
     let agent = null;
     let resumed = false;
-    let creds;
+    const creds = sessionCreds;
     try {
-        creds = resolveAgentCredentials(opts.apiKey, prefs.locale);
         if (usesCursorSdk(creds)) {
             ({ agent, resumed } = await createOrResumeAgent({ ...opts, task: "", mode }, prefs.locale));
         }
     }
     catch (err) {
-        if (err instanceof CursorAgentError) {
+        if (err instanceof CursorSdkMissingError) {
+            fail(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        if (err instanceof Error && err.name === "CursorAgentError") {
             fail(`Agent startup failed: ${err.message}`);
             process.exitCode = 1;
             return;
@@ -376,8 +435,9 @@ export async function runInteractiveAgent(opts) {
             locale: prefs.locale,
             mode,
             apiKey: opts.apiKey,
-            askOffline: opts.askOffline,
+            askOffline,
             creds,
+            offline: false,
         });
     }
     finally {
@@ -390,16 +450,31 @@ async function runRepl(opts) {
     let currentMode = opts.mode;
     let currentAgent = opts.agent;
     let currentCreds = opts.creds;
+    let currentOffline = opts.offline;
     let turn = 0;
     const t = () => uiStrings(currentLocale);
     const resolveCreds = () => {
+        if (currentOffline) {
+            try {
+                const live = resolveActiveCredentials();
+                if (live) {
+                    currentOffline = false;
+                    currentCreds = live;
+                    return live;
+                }
+            }
+            catch {
+                /* stay offline */
+            }
+            return null;
+        }
         try {
             currentCreds = resolveAgentCredentials(opts.apiKey, currentLocale);
+            return currentCreds;
         }
         catch {
-            /* keep previous */
+            return currentCreds;
         }
-        return currentCreds;
     };
     while (true) {
         const line = (await askWithPlaceholder({
@@ -410,7 +485,11 @@ async function runRepl(opts) {
             break;
         if (isProvidersMetaCommand(line.trim().split(/\s+/)[0] ?? "")) {
             await runProvidersInteractive(currentLocale);
-            resolveCreds();
+            const live = resolveActiveCredentials();
+            if (live) {
+                currentOffline = false;
+                currentCreds = live;
+            }
             continue;
         }
         const meta = handleMetaCommand(line, currentLocale, opts.cwd, currentMode);
@@ -432,7 +511,7 @@ async function runRepl(opts) {
                 }
                 else {
                     const creds = resolveCreds();
-                    if (usesCursorSdk(creds)) {
+                    if (creds && usesCursorSdk(creds)) {
                         currentAgent = await recreateAgentForMode(opts.cwd, currentAgent, currentMode, opts.apiKey, currentLocale);
                     }
                     else if (currentAgent) {
@@ -447,7 +526,8 @@ async function runRepl(opts) {
             continue;
         }
         if (meta?.kind === "resume") {
-            if (currentMode === "ask" || !usesCursorSdk(resolveCreds())) {
+            const resumeCreds = resolveCreds();
+            if (currentMode === "ask" || !resumeCreds || !usesCursorSdk(resumeCreds)) {
                 warn(currentLocale === "pt"
                     ? "Sessões guardadas só com provider Cursor."
                     : currentLocale === "zh"
@@ -468,7 +548,8 @@ async function runRepl(opts) {
             continue;
         }
         if (meta?.kind === "save") {
-            if (!currentAgent || !usesCursorSdk(resolveCreds())) {
+            const saveCreds = resolveCreds();
+            if (!currentAgent || !saveCreds || !usesCursorSdk(saveCreds)) {
                 warn(currentLocale === "pt"
                     ? "Guardar sessão só com provider Cursor."
                     : currentLocale === "zh"
@@ -492,7 +573,7 @@ async function runRepl(opts) {
             await executeAskTurn({
                 cwd: opts.cwd,
                 question: line,
-                offline: opts.askOffline,
+                offline: currentOffline || Boolean(opts.askOffline),
                 quiet: true,
                 locale: currentLocale,
             });
@@ -500,7 +581,12 @@ async function runRepl(opts) {
             turn++;
             continue;
         }
-        const creds = resolveCreds();
+        if (currentOffline || !resolveCreds()) {
+            warn(offlineAgentHint(currentLocale));
+            turn++;
+            continue;
+        }
+        const creds = currentCreds;
         if (usesCursorSdk(creds) && !currentAgent) {
             fail(currentLocale === "pt" ? "Sem agente Cursor activo." : "No active Cursor agent.");
             continue;

package/dist/commands/setup.d.ts

@@ -0,0 +1,5 @@
+export declare function runSetupCommand(opts: {
+    locale?: string;
+    force?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/commands/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAEA,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,iBAE/E"}

package/dist/commands/setup.js

@@ -0,0 +1,4 @@
+import { runSetupWizard } from "../lib/onboarding.js";
+export async function runSetupCommand(opts) {
+    await runSetupWizard(opts);
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { runFixCommand } from "./commands/agent.js";
 import { runHealth } from "./commands/health.js";
 import { runScan } from "./commands/scan.js";
 import { runProvidersCommand } from "./commands/providers.js";
+import { runSetupCommand } from "./commands/setup.js";
 import { runWebhookTest } from "./commands/webhook.js";
 const SUBCOMMANDS = new Set([
     "doctor",
@@ -21,6 +22,7 @@ const SUBCOMMANDS = new Set([
     "fix",
     "ask",
     "providers",
+    "setup",
 ]);
 /** Bare `ekz` or `ekz "natural language task"` → agent. Resolves PT/zh CLI aliases. */
 function normalizeArgv(argv) {
@@ -134,6 +136,20 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("setup")
+    .alias("configurar")
+    .description("First-run setup — language, name, provider or offline")
+    .option("-l, --lang <code>", "Skip language pick: pt, en, or zh")
+    .action(async (opts) => {
+    try {
+        await runSetupCommand({ locale: opts.lang });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+    }
+});
 program
     .command("providers")
     .alias("provedores")

package/dist/lib/commands-i18n.d.ts

@@ -6,9 +6,9 @@ export type ProvidersCommandLabels = {
     replAliases: string[];
 };
 export declare function providersCommandLabels(locale: EkzLocale): ProvidersCommandLabels;
-export declare function providersSetupHint(locale: EkzLocale): string;
+export declare function providersSetupHint(_locale?: EkzLocale): string;
 export declare function isProvidersMetaCommand(token: string): boolean;
-export type CliCommandId = "doctor" | "health" | "scan" | "webhook" | "agent" | "fix" | "ask" | "providers";
+export type CliCommandId = "doctor" | "health" | "scan" | "webhook" | "agent" | "fix" | "ask" | "providers" | "setup";
 export declare function resolveCliSubcommand(token: string): string;
 export declare function isKnownSubcommand(token: string): boolean;
 export declare const SPLASH_TOOLS: Record<EkzLocale, Array<{

package/dist/lib/commands-i18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands-i18n.d.ts","sourceRoot":"","sources":["../../src/lib/commands-i18n.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,sBAAsB,CAuBhF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAS5D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,SAAS,GACT,OAAO,GACP,KAAK,GACL,KAAK,GACL,WAAW,CAAC;AAoDhB,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAC/B,SAAS,EACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCxC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGlG;AAED,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAE/D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAU9D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAIxD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAQxF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAMvF;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCpD,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI5D"}
+{"version":3,"file":"commands-i18n.d.ts","sourceRoot":"","sources":["../../src/lib/commands-i18n.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,sBAAsB,CAuBhF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,MAAM,CAE9D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,SAAS,GACT,OAAO,GACP,KAAK,GACL,KAAK,GACL,WAAW,GACX,OAAO,CAAC;AA2DZ,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAC/B,SAAS,EACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCxC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGlG;AAED,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAE/D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAgB9D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAIxD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAQxF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAMvF;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCpD,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI5D"}

package/dist/lib/commands-i18n.js

@@ -1,3 +1,4 @@
+import { formatSetupRequiredMessage } from "./setup-messages.js";
 export function providersCommandLabels(locale) {
     if (locale === "pt") {
         return {
@@ -22,15 +23,8 @@ export function providersCommandLabels(locale) {
         replAliases: ["/provider"],
     };
 }
-export function providersSetupHint(locale) {
-    const labels = providersCommandLabels(locale);
-    if (locale === "pt") {
-        return `Nenhum provider activo. Corre \`${labels.cli}\` ou \`${labels.repl}\` e cola a tua API key.`;
-    }
-    if (locale === "zh") {
-        return `未配置 provider。运行 \`${labels.cli}\` 或 \`${labels.repl}\` 并粘贴 API key。`;
-    }
-    return `No active provider. Run \`${labels.cli}\` or \`${labels.repl}\` and paste your API key.`;
+export function providersSetupHint(_locale) {
+    return formatSetupRequiredMessage();
 }
 export function isProvidersMetaCommand(token) {
     return resolveReplMetaCommand(token) === "providers";
@@ -44,6 +38,7 @@ const EN_SUBCOMMANDS = new Set([
     "fix",
     "ask",
     "providers",
+    "setup",
 ]);
 /** Map localized CLI tokens (and English) to canonical subcommand ids. */
 const CLI_ALIASES = {
@@ -76,6 +71,12 @@ const CLI_ALIASES = {
     供应商: "providers",
     提供商: "providers",
     模型: "providers",
+    setup: "setup",
+    configurar: "setup",
+    configuracao: "setup",
+    "configuração": "setup",
+    设置: "setup",
+    配置: "setup",
     诊断: "doctor",
     凭证: "health",
     扫描: "scan",
@@ -104,6 +105,7 @@ export const SPLASH_TOOLS = {
         { label: "agente", hint: "agent" },
         { label: "perguntar", hint: "ask" },
         { label: "provedores", hint: "BYOK" },
+        { label: "setup", hint: "configurar" },
     ],
     en: [
         { label: "doctor" },
@@ -114,6 +116,7 @@ export const SPLASH_TOOLS = {
         { label: "agent" },
         { label: "ask" },
         { label: "providers", hint: "BYOK" },
+        { label: "setup" },
     ],
     zh: [
         { label: "诊断", hint: "doctor" },
@@ -124,6 +127,7 @@ export const SPLASH_TOOLS = {
         { label: "代理", hint: "agent" },
         { label: "问答", hint: "ask" },
         { label: "供应商", hint: "BYOK" },
+        { label: "设置", hint: "setup" },
     ],
 };
 export function formatSplashTool(locale, tool) {
@@ -137,14 +141,19 @@ export function formatCliToolsSummary(locale) {
 }
 export function splashSessionLines(locale) {
     const p = providersCommandLabels(locale);
+    const setupLine = locale === "pt"
+        ? "ekz setup · ekz configurar"
+        : locale === "zh"
+            ? "ekz setup · ekz 设置"
+            : "ekz setup";
     const providersLine = `${p.repl} · ${p.cli}`;
     if (locale === "pt") {
-        return [providersLine, "/guardar <nome>", "/retomar · /retomar 2", "ekz --resume", "ekz --fresh"];
+        return [setupLine, providersLine, "/guardar <nome>", "/retomar · /retomar 2", "ekz --resume", "ekz --fresh"];
     }
     if (locale === "zh") {
-        return [providersLine, "/保存 <名称>", "/恢复 · /恢复 2", "ekz --resume", "ekz --fresh"];
+        return [setupLine, providersLine, "/保存 <名称>", "/恢复 · /恢复 2", "ekz --resume", "ekz --fresh"];
     }
-    return [providersLine, "/save <name>", "/resume · /resume 2", "ekz --resume", "ekz --fresh"];
+    return [setupLine, providersLine, "/save <name>", "/resume · /resume 2", "ekz --resume", "ekz --fresh"];
 }
 export function splashHelpHint(locale) {
     if (locale === "pt")

package/dist/lib/global-config.d.ts

@@ -0,0 +1,19 @@
+import type { EkzLocale } from "./locale.js";
+export type EkzGlobalConfig = {
+    locale?: EkzLocale;
+    userName?: string;
+    /** User chose offline mode (no LLM provider). */
+    offline?: boolean;
+    setupComplete?: boolean;
+};
+export declare function globalConfigPath(): string;
+export declare function loadGlobalConfig(): EkzGlobalConfig;
+export declare function saveGlobalConfig(patch: Partial<EkzGlobalConfig>): void;
+export declare function getGlobalLocale(): EkzLocale | undefined;
+export declare function getGlobalUserName(): string | undefined;
+export declare function isGlobalOffline(): boolean;
+export declare function setGlobalOffline(offline: boolean): void;
+export declare function clearGlobalOffline(): void;
+export declare function isSetupComplete(): boolean;
+export declare function markSetupComplete(): void;
+//# sourceMappingURL=global-config.d.ts.map

package/dist/lib/global-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-config.d.ts","sourceRoot":"","sources":["../../src/lib/global-config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAMF,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,gBAAgB,IAAI,eAAe,CAQlD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,QAI/D;AAED,wBAAgB,eAAe,IAAI,SAAS,GAAG,SAAS,CAGvD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,QAEhD;AAED,wBAAgB,kBAAkB,SAGjC;AAED,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,wBAAgB,iBAAiB,SAEhC"}

package/dist/lib/global-config.js

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const EKZ_HOME = join(homedir(), ".ekz");
+const CONFIG_PATH = join(EKZ_HOME, "config.json");
+function ensureEkzHome() {
+    if (!existsSync(EKZ_HOME))
+        mkdirSync(EKZ_HOME, { recursive: true, mode: 0o700 });
+}
+export function globalConfigPath() {
+    return CONFIG_PATH;
+}
+export function loadGlobalConfig() {
+    ensureEkzHome();
+    if (!existsSync(CONFIG_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveGlobalConfig(patch) {
+    ensureEkzHome();
+    const next = { ...loadGlobalConfig(), ...patch };
+    writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+}
+export function getGlobalLocale() {
+    const l = loadGlobalConfig().locale;
+    return l === "pt" || l === "en" || l === "zh" ? l : undefined;
+}
+export function getGlobalUserName() {
+    return loadGlobalConfig().userName?.trim() || undefined;
+}
+export function isGlobalOffline() {
+    return loadGlobalConfig().offline === true;
+}
+export function setGlobalOffline(offline) {
+    saveGlobalConfig({ offline, setupComplete: true });
+}
+export function clearGlobalOffline() {
+    const cfg = loadGlobalConfig();
+    if (cfg.offline)
+        saveGlobalConfig({ offline: false });
+}
+export function isSetupComplete() {
+    return loadGlobalConfig().setupComplete === true;
+}
+export function markSetupComplete() {
+    saveGlobalConfig({ setupComplete: true });
+}

package/dist/lib/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/lib/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAGtD,KAAK,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAatD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,CA4HzF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,QAezE"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/lib/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAGtD,KAAK,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAatD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,CA+HzF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,QAezE"}

package/dist/lib/help.js

@@ -44,6 +44,7 @@ export function buildHelpSections(locale, currentMode) {
         ? [
             "Escreve perguntas ou tarefas em linguagem natural.",
             `${p.repl} · ${p.cli} (BYOK)`,
+            "ekz setup · ekz configurar",
             "/ajuda · /help",
             "/modo agente|plan|ask · /mode agent|plan|ask",
             "/idioma pt · /lang pt|en|zh",
@@ -55,6 +56,7 @@ export function buildHelpSections(locale, currentMode) {
             ? [
                 "用自然语言提问或描述任务。",
                 `${p.repl} · ${p.cli} (BYOK)`,
+                "ekz setup · ekz 设置",
                 "/帮助 · /help · /ajuda",
                 "/模式 代理|plan|ask · /mode agent|plan|ask",
                 "/语言 pt · /lang pt|en|zh",
@@ -65,6 +67,7 @@ export function buildHelpSections(locale, currentMode) {
             : [
                 "Type questions or tasks in natural language.",
                 `${p.repl} · ${p.cli} (BYOK)`,
+                "ekz setup",
                 "/help · /ajuda · /帮助",
                 "/mode agent|plan|ask",
                 "/lang pt · /lang en · /lang zh",

package/dist/lib/locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/lib/locale.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAInD,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAIlD,CAAC;AAEF,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAOnE;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,CAE3F;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAgB7D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS;;;;;;;;;;;;;;;;;;;sBAqBnB,MAAM;;;;;;;;;;EA4H7B"}
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/lib/locale.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAInD,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAIlD,CAAC;AAEF,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAOnE;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,CAE3F;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAgB7D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS;;;;;;;;;;;;;;;;;;;sBAqBnB,MAAM;;;;;;;;;;EA4H7B"}

package/dist/lib/locale.js

@@ -1,3 +1,4 @@
+import { getGlobalLocale } from "./global-config.js";
 export const LOCALE_LABELS = {
     pt: "Português (Angola)",
     en: "English",
@@ -22,7 +23,7 @@ export function parseLocale(input) {
 }
 /** Default: Portuguese (Angola). Override with EKZ_LANG or --lang. */
 export function resolveLocale(explicit, saved) {
-    return parseLocale(explicit) ?? parseLocale(process.env.EKZ_LANG) ?? saved ?? "pt";
+    return parseLocale(explicit) ?? parseLocale(process.env.EKZ_LANG) ?? saved ?? getGlobalLocale() ?? "pt";
 }
 export function languageInstruction(locale) {
     if (locale === "pt") {

package/dist/lib/onboarding.d.ts

@@ -0,0 +1,20 @@
+import { type EkzLocale } from "./locale.js";
+import { type ResolvedCredentials } from "./providers/credentials.js";
+export type AgentReadyState = {
+    offline: boolean;
+    creds: ResolvedCredentials | null;
+};
+export declare function offlineModelLabel(locale: EkzLocale): string;
+/** Full first-run wizard: language → name → provider/offline. */
+export declare function runSetupWizard(opts?: {
+    locale?: string;
+    force?: boolean;
+}): Promise<void>;
+/** Ensures the agent can start — provider, offline, or throws setup hint. */
+export declare function ensureAgentReady(options: {
+    locale: EkzLocale;
+    offlineFlag?: boolean;
+    apiKey?: string;
+}): Promise<AgentReadyState>;
+export declare function offlineAgentHint(locale: EkzLocale): string;
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/lib/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/lib/onboarding.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,aAAa,CAAC;AAG1D,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,4BAA4B,CAAC;AAyBpC,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACnC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAI3D;AAoFD,iEAAiE;AACjE,wBAAsB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,iBA6B/E;AAED,6EAA6E;AAC7E,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,MAAM,EAAE,SAAS,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgB3B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAQ1D"}

package/dist/lib/onboarding.js

@@ -0,0 +1,129 @@
+import readline from "readline";
+import { providersCommandLabels } from "./commands-i18n.js";
+import { markSetupComplete, saveGlobalConfig, setGlobalOffline, clearGlobalOffline, isGlobalOffline, } from "./global-config.js";
+import { parseLocale } from "./locale.js";
+import { formatSetupRequiredMessage } from "./setup-messages.js";
+import { info, ok } from "./output.js";
+import { ProviderSetupError, resolveActiveCredentials, resolveCredentialsWithOverride, } from "./providers/credentials.js";
+import { runProvidersInteractive } from "./providers/ui.js";
+import { c, muted } from "./theme.js";
+function t(locale, pt, en, zh) {
+    if (locale === "pt")
+        return pt;
+    if (locale === "zh")
+        return zh;
+    return en;
+}
+async function askLine(prompt) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function hasProvider(apiKey) {
+    if (apiKey?.trim())
+        return true;
+    return Boolean(resolveActiveCredentials());
+}
+export function offlineModelLabel(locale) {
+    if (locale === "pt")
+        return "offline · doctor/scan";
+    if (locale === "zh")
+        return "离线 · 诊断/扫描";
+    return "offline · doctor/scan";
+}
+async function pickLanguage() {
+    console.log("");
+    console.log(`  ${c.bold}Ekz Connect — Setup${c.reset}`);
+    console.log("");
+    console.log(`  ${muted("Choose language · Escolhe idioma · 选择语言")}`);
+    console.log("");
+    console.log(`  ${c.bold}1.${c.reset} Português`);
+    console.log(`  ${c.bold}2.${c.reset} English`);
+    console.log(`  ${c.bold}3.${c.reset} 中文`);
+    console.log("");
+    const choice = (await askLine("  [1/2/3]: ")).toLowerCase();
+    if (choice === "2" || choice === "en" || choice === "english")
+        return "en";
+    if (choice === "3" || choice === "zh" || choice === "中文")
+        return "zh";
+    return "pt";
+}
+async function askUserName(locale) {
+    console.log("");
+    const prompt = t(locale, "Como devo te chamar? ", "What should we call you? (first name): ", "怎么称呼您？(名字): ");
+    const name = await askLine(`  ${prompt}`);
+    if (!name)
+        return t(locale, "Developer", "Developer", "开发者");
+    return name.split(/\s+/)[0] ?? name;
+}
+async function providerStep(locale) {
+    const p = providersCommandLabels(locale);
+    console.log("");
+    console.log(`  ${muted(t(locale, "LLM (BYOK) — opcional agora", "LLM (BYOK) — optional for now", "LLM (BYOK) — 可选"))}`);
+    console.log("");
+    console.log(`  ${c.bold}1.${c.reset} ${t(locale, "Configurar provedor", "Configure provider", "配置 provider")}`);
+    console.log(`     ${muted(t(locale, p.cli, p.cli, p.cli))}`);
+    console.log("");
+    console.log(`  ${c.bold}2.${c.reset} ${t(locale, "Continuar offline", "Continue offline", "离线模式")}`);
+    console.log(`     ${muted(t(locale, "doctor · scan · sem AI", "doctor · scan · no AI", "诊断 · 扫描 · 无 AI"))}`);
+    console.log("");
+    console.log(`  ${muted("Enter · skip")}`);
+    console.log("");
+    const choice = (await askLine(t(locale, "  Escolha [1/2/Enter]: ", "  Choice [1/2/Enter]: ", "  选择 [1/2/Enter]: "))).toLowerCase();
+    if (choice === "2" || choice === "offline" || choice === "离线") {
+        setGlobalOffline(true);
+        ok(t(locale, "Modo offline activo.", "Offline mode enabled.", "已启用离线模式。"));
+        return "offline";
+    }
+    if (choice === "1" || choice === "p" || choice === "providers" || choice === "provedores" || choice === "供应商") {
+        await runProvidersInteractive(locale);
+        if (resolveActiveCredentials()) {
+            clearGlobalOffline();
+            ok(t(locale, "Provedor configurado.", "Provider configured.", "Provider 已配置。"));
+            return "configured";
+        }
+        info(t(locale, "Provedor não configurado.", "No provider configured.", "未配置 provider。"));
+        return "skip";
+    }
+    return "skip";
+}
+/** Full first-run wizard: language → name → provider/offline. */
+export async function runSetupWizard(opts) {
+    if (!process.stdin.isTTY) {
+        console.error(formatSetupRequiredMessage());
+        process.exitCode = 1;
+        return;
+    }
+    let locale = parseLocale(opts?.locale) ?? (await pickLanguage());
+    saveGlobalConfig({ locale });
+    const userName = await askUserName(locale);
+    saveGlobalConfig({ userName });
+    ok(t(locale, `Olá ${userName}!`, `Hello ${userName}!`, `你好 ${userName}!`));
+    await providerStep(locale);
+    markSetupComplete();
+    console.log("");
+    ok(t(locale, "Setup concluído. Corre `ekz` para começar.", "Setup complete. Run `ekz` to start.", "设置完成。运行 `ekz` 开始。"));
+}
+/** Ensures the agent can start — provider, offline, or throws setup hint. */
+export async function ensureAgentReady(options) {
+    const { locale, offlineFlag, apiKey } = options;
+    if (offlineFlag || isGlobalOffline()) {
+        return { offline: true, creds: null };
+    }
+    if (hasProvider(apiKey)) {
+        clearGlobalOffline();
+        if (apiKey?.trim()) {
+            return { offline: false, creds: resolveCredentialsWithOverride(apiKey, locale) };
+        }
+        return { offline: false, creds: resolveActiveCredentials() };
+    }
+    throw new ProviderSetupError(formatSetupRequiredMessage());
+}
+export function offlineAgentHint(locale) {
+    const p = providersCommandLabels(locale);
+    return t(locale, `Modo offline — sem AI. Usa \`ekz setup\`, ${p.repl}, /diagnóstico ou /analisar.`, `Offline mode — no AI. Use \`ekz setup\`, ${p.repl}, /doctor, or /scan.`, `离线模式 — 无 AI。使用 \`ekz setup\`、${p.repl}、/诊断 或 /扫描。`);
+}

package/dist/lib/providers/credentials.d.ts

@@ -1,4 +1,5 @@
 import { type ProviderDefinition, type ProviderId } from "./catalog.js";
+import type { EkzLocale } from "../locale.js";
 import { type StoredProvider } from "./store.js";
 export type ResolvedCredentials = {
     id: ProviderId;
@@ -23,4 +24,5 @@ export declare function getActiveProviderId(): ProviderId | undefined;
 export declare function resolveActiveCredentials(): ResolvedCredentials | null;
 export declare function requireActiveCredentials(locale?: "pt" | "en" | "zh"): ResolvedCredentials;
 export declare function isCursorProvider(creds: ResolvedCredentials): boolean;
+export declare function resolveCredentialsWithOverride(override?: string, locale?: EkzLocale): ResolvedCredentials;
 //# sourceMappingURL=credentials.d.ts.map

package/dist/lib/providers/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1F,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,UAAU,CAAC;IACf,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,gBAAgB,IAAI,WAAW,EAAE,CAYhD;AAED,wBAAgB,mBAAmB,IAAI,UAAU,GAAG,SAAS,CAE5D;AAED,wBAAgB,wBAAwB,IAAI,mBAAmB,GAAG,IAAI,CAgBrE;AAED,wBAAgB,wBAAwB,CAAC,MAAM,GAAE,IAAI,GAAG,IAAI,GAAG,IAAW,GAAG,mBAAmB,CAI/F;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEpE"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGjH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,UAAU,CAAC;IACf,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,gBAAgB,IAAI,WAAW,EAAE,CAYhD;AAED,wBAAgB,mBAAmB,IAAI,UAAU,GAAG,SAAS,CAE5D;AAED,wBAAgB,wBAAwB,IAAI,mBAAmB,GAAG,IAAI,CAgBrE;AAED,wBAAgB,wBAAwB,CAAC,MAAM,GAAE,IAAI,GAAG,IAAI,GAAG,IAAW,GAAG,mBAAmB,CAI/F;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEpE;AAED,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,GAAE,SAAgB,GACvB,mBAAmB,CAarB"}

package/dist/lib/providers/credentials.js

@@ -1,5 +1,6 @@
-import { PROVIDER_CATALOG } from "./catalog.js";
-import { providersSetupHint } from "../commands-i18n.js";
+import { PROVIDER_CATALOG, getProviderDefinition } from "./catalog.js";
+import { formatSetupRequiredMessage } from "../setup-messages.js";
+import { resolveComposerModel } from "../composer-model.js";
 import { loadProvidersFile, maskApiKey, resolveBaseUrl, resolveModel, } from "./store.js";
 export class ProviderSetupError extends Error {
     constructor(message) {
@@ -47,8 +48,23 @@ export function requireActiveCredentials(locale = "en") {
     const creds = resolveActiveCredentials();
     if (creds)
         return creds;
-    throw new ProviderSetupError(providersSetupHint(locale));
+    throw new ProviderSetupError(formatSetupRequiredMessage());
 }
 export function isCursorProvider(creds) {
     return creds.definition.kind === "cursor";
 }
+export function resolveCredentialsWithOverride(override, locale = "en") {
+    if (override?.trim()) {
+        const def = getProviderDefinition("cursor");
+        if (!def)
+            throw new Error("Cursor provider missing from catalog.");
+        return {
+            id: "cursor",
+            definition: def,
+            apiKey: override.trim(),
+            model: resolveComposerModel().id,
+            maskedKey: maskApiKey(override.trim()),
+        };
+    }
+    return requireActiveCredentials(locale);
+}

package/dist/lib/providers/cursor-runner.d.ts

@@ -1,8 +1,8 @@
-import { type SDKAgent } from "@cursor/sdk";
 import { type EkzLocale } from "../locale.js";
+import { type SDKAgent } from "./cursor-sdk.js";
 import { type ResolvedCredentials } from "./credentials.js";
 declare function disposeAgent(agent: SDKAgent): Promise<void>;
-declare function streamRun(agent: SDKAgent, prompt: string): Promise<void>;
+declare function streamRun(agent: SDKAgent, prompt: string, locale: EkzLocale): Promise<void>;
 export declare function executeCursorAskTurn(options: {
     cwd: string;
     question: string;

package/dist/lib/providers/cursor-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/cursor-runner.ts"],"names":[],"mappings":"AACA,OAAO,EAA2C,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIrF,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,iBAAe,YAAY,CAAC,KAAK,EAAE,QAAQ,iBAI1C;AAED,iBAAe,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCvE;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,SAAS,CAAC;CACnB,GAAG,OAAO,CAAC,OAAO,CAAC,CAkCnB;AAED,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"cursor-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/cursor-runner.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,cAAc,CAAC;AAInE,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,iBAAe,YAAY,CAAC,KAAK,EAAE,QAAQ,iBAI1C;AAED,iBAAe,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC1F;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,SAAS,CAAC;CACnB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmCnB;AAED,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/lib/providers/cursor-runner.js

@@ -1,11 +1,11 @@
 import { resolve } from "path";
-import { Agent, AgentBusyError, CursorAgentError } from "@cursor/sdk";
 import { buildBootstrapContext } from "../context.js";
 import { resolveComposerModel } from "../composer-model.js";
-import { fail } from "../output.js";
-import { toolDone, toolError, toolRunning } from "../theme.js";
 import { languageInstruction } from "../locale.js";
+import { fail } from "../output.js";
 import { agentScopeBlock } from "../scope.js";
+import { toolDone, toolError, toolRunning } from "../theme.js";
+import { loadCursorSdk } from "./cursor-sdk.js";
 async function disposeAgent(agent) {
     const disposer = agent[Symbol.asyncDispose];
     if (typeof disposer === "function")
@@ -13,7 +13,8 @@ async function disposeAgent(agent) {
     else
         agent.close();
 }
-async function streamRun(agent, prompt) {
+async function streamRun(agent, prompt, locale) {
+    const { AgentBusyError, CursorAgentError } = await loadCursorSdk(locale);
     const sendOptions = {
         onDelta: ({ update }) => {
             if (update.type === "text-delta" && update.text)
@@ -52,6 +53,7 @@ export async function executeCursorAskTurn(options) {
     const cwd = resolve(options.cwd);
     const ctx = await buildBootstrapContext(cwd);
     const model = resolveComposerModel(process.env, options.creds.model);
+    const { Agent } = await loadCursorSdk(options.locale);
     const prompt = `${agentScopeBlock(options.locale)}
 
 ${languageInstruction(options.locale)}
@@ -71,7 +73,7 @@ ${options.question}`;
             model: { id: model.id, params: model.params },
             local: { cwd, settingSources: ["project"] },
         });
-        await streamRun(agent, prompt);
+        await streamRun(agent, prompt, options.locale);
         console.log("");
         return true;
     }

package/dist/lib/providers/cursor-sdk.d.ts

@@ -0,0 +1,8 @@
+import type { EkzLocale } from "../locale.js";
+export declare class CursorSdkMissingError extends Error {
+    constructor(locale?: EkzLocale);
+}
+type CursorSdkModule = typeof import("@cursor/sdk");
+export declare function loadCursorSdk(locale?: EkzLocale): Promise<CursorSdkModule>;
+export type { SDKAgent } from "@cursor/sdk";
+//# sourceMappingURL=cursor-sdk.d.ts.map

package/dist/lib/providers/cursor-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-sdk.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/cursor-sdk.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,GAAE,SAAgB;CAWrC;AAED,KAAK,eAAe,GAAG,cAAc,aAAa,CAAC,CAAC;AAIpD,wBAAsB,aAAa,CAAC,MAAM,GAAE,SAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAQtF;AAED,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/providers/cursor-sdk.js

@@ -0,0 +1,25 @@
+import { providersCommandLabels } from "../commands-i18n.js";
+export class CursorSdkMissingError extends Error {
+    constructor(locale = "en") {
+        const p = providersCommandLabels(locale);
+        const msg = locale === "pt"
+            ? `Provider Cursor requer @cursor/sdk. Instala: npm install -g @cursor/sdk\nOu usa outro provider em ${p.repl}.`
+            : locale === "zh"
+                ? `Cursor provider 需要 @cursor/sdk。安装: npm install -g @cursor/sdk\n或在 ${p.repl} 选择其他 provider。`
+                : `Cursor provider requires @cursor/sdk. Run: npm install -g @cursor/sdk\nOr pick another provider via ${p.repl}.`;
+        super(msg);
+        this.name = "CursorSdkMissingError";
+    }
+}
+let cached = null;
+export async function loadCursorSdk(locale = "en") {
+    if (cached)
+        return cached;
+    try {
+        cached = await import("@cursor/sdk");
+        return cached;
+    }
+    catch {
+        throw new CursorSdkMissingError(locale);
+    }
+}

package/dist/lib/providers/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,cAAc,CAAC;AAEtE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACxD,CAAC;AAWF,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,iBAAiB,IAAI,aAAa,CAcjD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,QAQpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,QAKtE;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,QAOlD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,QAO/C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAG5E;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAG1F"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,cAAc,CAAC;AAGtE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACxD,CAAC;AAWF,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,iBAAiB,IAAI,aAAa,CAcjD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,QAQpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,QAOtE;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,QAOlD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,QAO/C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAG5E;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAG1F"}

package/dist/lib/providers/store.js

@@ -2,6 +2,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "f
 import { homedir } from "os";
 import { join } from "path";
 import { getProviderDefinition } from "./catalog.js";
+import { clearGlobalOffline, markSetupComplete } from "../global-config.js";
 const EKZ_HOME = join(homedir(), ".ekz");
 const PROVIDERS_PATH = join(EKZ_HOME, "providers.json");
 function ensureEkzHome() {
@@ -53,6 +54,8 @@ export function setStoredProvider(id, entry) {
     if (!file.active)
         file.active = id;
     saveProvidersFile(file);
+    clearGlobalOffline();
+    markSetupComplete();
 }
 export function removeStoredProvider(id) {
     const file = loadProvidersFile();

package/dist/lib/setup-messages.d.ts

@@ -0,0 +1,4 @@
+/** Shown when agent needs provider but setup was not run (all locales). */
+export declare function formatSetupRequiredMessage(): string;
+export declare function providersSetupHint(_locale?: string): string;
+//# sourceMappingURL=setup-messages.d.ts.map

package/dist/lib/setup-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-messages.d.ts","sourceRoot":"","sources":["../../src/lib/setup-messages.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wBAAgB,0BAA0B,IAAI,MAAM,CAQnD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/lib/setup-messages.js

@@ -0,0 +1,13 @@
+/** Shown when agent needs provider but setup was not run (all locales). */
+export function formatSetupRequiredMessage() {
+    return [
+        "Setup required · Configuração necessária · 需要设置",
+        "",
+        "  pt: Corre `ekz setup` ou `ekz --offline`",
+        "  en: Run `ekz setup` or `ekz --offline`",
+        "  zh: 运行 `ekz setup` 或 `ekz --offline`",
+    ].join("\n");
+}
+export function providersSetupHint(_locale) {
+    return formatSetupRequiredMessage();
+}

package/dist/lib/ui/splash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"splash.d.ts","sourceRoot":"","sources":["../../../src/lib/ui/splash.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,cAAc,CAAC;AACzD,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAMvD,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AA2GF,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAQtD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAG1D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,SAAI,GAAG,MAAM,CAIrE"}
+{"version":3,"file":"splash.d.ts","sourceRoot":"","sources":["../../../src/lib/ui/splash.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,cAAc,CAAC;AACzD,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAMvD,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AA6GF,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAQtD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAG1D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,SAAI,GAAG,MAAM,CAIrE"}

package/dist/lib/ui/splash.js

@@ -4,6 +4,7 @@ import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { formatSplashTool, splashHelpHint, splashSectionTitle, SPLASH_TOOLS, splashSessionLines, welcomeMessage, } from "../commands-i18n.js";
+import { getGlobalUserName } from "../global-config.js";
 import { uiStrings } from "../locale.js";
 import { MODE_LABELS } from "../mode.js";
 import { detectShellEnvironment, shellLabel } from "../shell.js";
@@ -24,6 +25,9 @@ function packageVersion() {
     }
 }
 function displayName() {
+    const fromConfig = getGlobalUserName();
+    if (fromConfig)
+        return fromConfig.split(/\s+/)[0] ?? fromConfig;
     const fromEnv = process.env.EKZ_USER_NAME?.trim();
     if (fromEnv)
         return fromEnv.split(/\s+/)[0] ?? fromEnv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekzs/cli",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "CLI agent for e-Kwanza v2.4 — health checks, code scan, webhook tests, AI assistance",
   "type": "module",
   "bin": {
@@ -17,12 +17,20 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@cursor/sdk": "^1.0.13",
     "@ekzs/connect": "^0.1.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.7"
   },
+  "peerDependencies": {
+    "@cursor/sdk": "^1.0.13"
+  },
+  "peerDependenciesMeta": {
+    "@cursor/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@cursor/sdk": "^1.0.13",
     "@types/node": "^20",
     "typescript": "^5"
   },