@ekzs/cli 0.3.0 → 0.3.4

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,7 +11,9 @@ 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";
+import { packageVersion } from "./lib/version.js";
 const SUBCOMMANDS = new Set([
     "doctor",
     "health",
@@ -21,6 +23,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) {
@@ -38,7 +41,7 @@ const program = new Command();
 program
     .name("ekz")
     .description("EKZ CONNECT — e-Kwanza v2.4 coding agent by Alberto Moisés")
-    .version("0.3.0");
+    .version(packageVersion());
 program
     .command("doctor")
     .description("Validate .env and run live credential checks (free)")
@@ -134,6 +137,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"}