@ekzs/cli 0.2.0 → 0.3.3

package/dist/index.js

@@ -3,12 +3,15 @@ import { bootstrapShellEnvironment } from "./lib/shell.js";
 import { Command } from "commander";
 bootstrapShellEnvironment();
 import { isKnownSubcommand, resolveCliSubcommand } from "./lib/commands-i18n.js";
+import { parseLocale } from "./lib/locale.js";
 import { runAgentCommand } from "./commands/agent.js";
 import { runAsk, runInteractiveAsk, resolveQuestion } from "./commands/ask.js";
 import { runDoctor } from "./commands/doctor.js";
 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",
@@ -18,6 +21,8 @@ const SUBCOMMANDS = new Set([
     "agent",
     "fix",
     "ask",
+    "providers",
+    "setup",
 ]);
 /** Bare `ekz` or `ekz "natural language task"` → agent. Resolves PT/zh CLI aliases. */
 function normalizeArgv(argv) {
@@ -35,7 +40,7 @@ const program = new Command();
 program
     .name("ekz")
     .description("EKZ CONNECT — e-Kwanza v2.4 coding agent by Alberto Moisés")
-    .version("0.2.0");
+    .version("0.3.0");
 program
     .command("doctor")
     .description("Validate .env and run live credential checks (free)")
@@ -78,18 +83,16 @@ program
 });
 program
     .command("agent")
-    .description("Interactive e-Kwanza agent (requires CURSOR_API_KEY for agent/plan modes)")
+    .description("Interactive e-Kwanza agent (BYOK — configure keys with `ekz providers`)")
     .argument("[task]", "Optional first task — stays interactive after (omit for REPL only)")
     .option("-C, --cwd <path>", "Project directory", process.cwd())
-    .option("--api-key <key>", "Cursor API key (or CURSOR_API_KEY env)")
+    .option("--api-key <key>", "One-off Cursor API key override (agent/plan)")
     .option("-i, --interactive", "Stay in REPL after the first task (default)", true)
     .option("--resume", "Resume last session in this repo")
     .option("--fresh", "Start a new agent session")
     .option("-m, --mode <mode>", "agent | plan | ask (default: agent)")
     .option("--plan", "Shorthand for --mode plan")
     .option("-l, --lang <code>", "Response language: pt (default), en, or zh")
-    .option("--ask-api-key <key>", "EKZ_AGENT_API_KEY for ask mode")
-    .option("--ask-api-url <url>", "Ekz Connect base URL for ask mode")
     .option("--offline", "Ask mode: offline answers only")
     .action(async (task, opts) => {
     try {
@@ -97,8 +100,6 @@ program
             cwd: opts.cwd,
             question: task,
             apiKey: opts.apiKey,
-            askApiKey: opts.askApiKey,
-            askApiUrl: opts.askApiUrl,
             askOffline: opts.offline,
             interactive: opts.interactive,
             resume: opts.resume,
@@ -118,15 +119,13 @@ program
     .description("Auto-audit and fix e-Kwanza integration in your repo")
     .argument("[hint]", "Optional extra context")
     .option("-C, --cwd <path>", "Project directory", process.cwd())
-    .option("--api-key <key>", "Cursor API key (or CURSOR_API_KEY env)")
+    .option("--api-key <key>", "One-off Cursor API key override (agent/plan)")
     .option("-i, --interactive", "Stay in REPL after fix pass (default)", true)
     .option("--resume", "Resume last session")
     .option("--fresh", "Start a new agent session")
     .option("-m, --mode <mode>", "agent | plan | ask (default: agent)")
     .option("--plan", "Shorthand for --mode plan")
     .option("-l, --lang <code>", "Response language: pt (default), en, or zh")
-    .option("--ask-api-key <key>", "EKZ_AGENT_API_KEY for ask mode")
-    .option("--ask-api-url <url>", "Ekz Connect base URL for ask mode")
     .option("--offline", "Ask mode: offline answers only")
     .action(async (hint, opts) => {
     try {
@@ -137,14 +136,41 @@ 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")
+    .alias("fornecedores")
+    .description("Configure LLM API keys (BYOK) — stored in ~/.ekz/providers.json")
+    .option("-l, --lang <code>", "Menu language: pt (default), en, or zh")
+    .action(async (opts) => {
+    try {
+        await runProvidersCommand({ locale: opts.lang });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+    }
+});
 program
     .command("ask")
-    .description("Remote Q&A via Ekz Connect API — no local file edits")
+    .description("BYOK Q&A — no local file edits (configure keys with `ekz providers`)")
     .argument("[question]", "Your question")
     .option("-C, --cwd <path>", "Project directory", process.cwd())
-    .option("--api-key <key>", "EKZ_AGENT_API_KEY")
-    .option("--api-url <url>", "Ekz Connect base URL")
-    .option("--offline", "Deterministic answer without API")
+    .option("--offline", "Deterministic answer without LLM")
     .option("-i, --interactive", "Stay in ask REPL after the first question", false)
     .option("-l, --lang <code>", "Response language: pt (default), en, or zh")
     .action(async (question, opts) => {
@@ -152,8 +178,6 @@ program
         if (opts.interactive && !question?.trim()) {
             await runInteractiveAsk({
                 cwd: opts.cwd,
-                apiKey: opts.apiKey,
-                apiUrl: opts.apiUrl,
                 offline: opts.offline,
                 locale: opts.lang,
             });
@@ -163,15 +187,12 @@ program
         await runAsk({
             cwd: opts.cwd,
             question: q,
-            apiKey: opts.apiKey,
-            apiUrl: opts.apiUrl,
             offline: opts.offline,
+            locale: parseLocale(opts.lang) ?? "pt",
         });
         if (opts.interactive) {
             await runInteractiveAsk({
                 cwd: opts.cwd,
-                apiKey: opts.apiKey,
-                apiUrl: opts.apiUrl,
                 offline: opts.offline,
                 locale: opts.lang,
             });

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

@@ -1,5 +1,14 @@
 import type { EkzLocale } from "./locale.js";
-export type CliCommandId = "doctor" | "health" | "scan" | "webhook" | "agent" | "fix" | "ask";
+export type ProvidersCommandLabels = {
+    cli: string;
+    repl: string;
+    cliAliases: string[];
+    replAliases: string[];
+};
+export declare function providersCommandLabels(locale: EkzLocale): ProvidersCommandLabels;
+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" | "setup";
 export declare function resolveCliSubcommand(token: string): string;
 export declare function isKnownSubcommand(token: string): boolean;
 export declare const SPLASH_TOOLS: Record<EkzLocale, Array<{
@@ -10,6 +19,8 @@ export declare function formatSplashTool(locale: EkzLocale, tool: {
     label: string;
     hint?: string;
 }): string;
+/** One-line summary of all CLI tools for help text. */
+export declare function formatCliToolsSummary(locale: EkzLocale): string;
 export declare function splashSessionLines(locale: EkzLocale): string[];
 export declare function splashHelpHint(locale: EkzLocale): string;
 export declare function welcomeMessage(locale: EkzLocale, name: string, resumed: boolean): string;

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,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,SAAS,GACT,OAAO,GACP,KAAK,GACL,KAAK,CAAC;AA0CV,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,CA6BxC,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,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAkB9D;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,CAyBpD,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,34 @@
+import { formatSetupRequiredMessage } from "./setup-messages.js";
+export function providersCommandLabels(locale) {
+    if (locale === "pt") {
+        return {
+            cli: "ekz provedores",
+            repl: "/provedores",
+            cliAliases: ["fornecedores", "providers", "chaves"],
+            replAliases: ["/fornecedores", "/providers", "/chaves"],
+        };
+    }
+    if (locale === "zh") {
+        return {
+            cli: "ekz 供应商",
+            repl: "/供应商",
+            cliAliases: ["providers", "提供商", "模型"],
+            replAliases: ["/providers", "/提供商", "/模型"],
+        };
+    }
+    return {
+        cli: "ekz providers",
+        repl: "/providers",
+        cliAliases: ["provider"],
+        replAliases: ["/provider"],
+    };
+}
+export function providersSetupHint(_locale) {
+    return formatSetupRequiredMessage();
+}
+export function isProvidersMetaCommand(token) {
+    return resolveReplMetaCommand(token) === "providers";
+}
 const EN_SUBCOMMANDS = new Set([
     "doctor",
     "health",
@@ -6,6 +37,8 @@ const EN_SUBCOMMANDS = new Set([
     "agent",
     "fix",
     "ask",
+    "providers",
+    "setup",
 ]);
 /** Map localized CLI tokens (and English) to canonical subcommand ids. */
 const CLI_ALIASES = {
@@ -29,6 +62,21 @@ const CLI_ALIASES = {
     ask: "ask",
     perguntar: "ask",
     pergunta: "ask",
+    providers: "providers",
+    provider: "providers",
+    fornecedores: "providers",
+    provedores: "providers",
+    chaves: "providers",
+    modelos: "providers",
+    供应商: "providers",
+    提供商: "providers",
+    模型: "providers",
+    setup: "setup",
+    configurar: "setup",
+    configuracao: "setup",
+    "configuração": "setup",
+    设置: "setup",
+    配置: "setup",
     诊断: "doctor",
     凭证: "health",
     扫描: "scan",
@@ -56,6 +104,8 @@ export const SPLASH_TOOLS = {
         { label: "corrigir", hint: "fix" },
         { label: "agente", hint: "agent" },
         { label: "perguntar", hint: "ask" },
+        { label: "provedores", hint: "BYOK" },
+        { label: "setup", hint: "configurar" },
     ],
     en: [
         { label: "doctor" },
@@ -65,6 +115,8 @@ export const SPLASH_TOOLS = {
         { label: "fix" },
         { label: "agent" },
         { label: "ask" },
+        { label: "providers", hint: "BYOK" },
+        { label: "setup" },
     ],
     zh: [
         { label: "诊断", hint: "doctor" },
@@ -74,31 +126,34 @@ export const SPLASH_TOOLS = {
         { label: "修复", hint: "fix" },
         { label: "代理", hint: "agent" },
         { label: "问答", hint: "ask" },
+        { label: "供应商", hint: "BYOK" },
+        { label: "设置", hint: "setup" },
     ],
 };
 export function formatSplashTool(locale, tool) {
-    if (!tool.hint || locale === "en")
+    if (!tool.hint)
         return tool.label;
     return `${tool.label} · ${tool.hint}`;
 }
+/** One-line summary of all CLI tools for help text. */
+export function formatCliToolsSummary(locale) {
+    return SPLASH_TOOLS[locale].map((t) => `ekz ${formatSplashTool(locale, t)}`).join(" · ");
+}
 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 [
-            "/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 [
-            "/保存 <名称>",
-            "/恢复 · /恢复 2",
-            "ekz --resume",
-            "ekz --fresh",
-        ];
+        return [setupLine, providersLine, "/保存 <名称>", "/恢复 · /恢复 2", "ekz --resume", "ekz --fresh"];
     }
-    return ["/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")
@@ -149,6 +204,15 @@ export const REPL_META_ALIASES = {
     save: "save",
     guardar: "save",
     保存: "save",
+    providers: "providers",
+    provider: "providers",
+    fornecedores: "providers",
+    provedores: "providers",
+    chaves: "providers",
+    modelos: "providers",
+    供应商: "providers",
+    提供商: "providers",
+    模型: "providers",
 };
 export function resolveReplMetaCommand(token) {
     const raw = token.trim().toLowerCase().replace(/^\//, "");

package/dist/lib/composer-model.d.ts

@@ -6,5 +6,5 @@ export type ComposerModelSelection = {
     }>;
     label: string;
 };
-export declare function resolveComposerModel(env?: NodeJS.ProcessEnv): ComposerModelSelection;
+export declare function resolveComposerModel(env?: NodeJS.ProcessEnv, modelOverride?: string): ComposerModelSelection;
 //# sourceMappingURL=composer-model.d.ts.map

package/dist/lib/composer-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composer-model.d.ts","sourceRoot":"","sources":["../../src/lib/composer-model.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,sBAAsB,CAkBjG"}
+{"version":3,"file":"composer-model.d.ts","sourceRoot":"","sources":["../../src/lib/composer-model.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,aAAa,CAAC,EAAE,MAAM,GACrB,sBAAsB,CAkBxB"}

package/dist/lib/composer-model.js

@@ -1,5 +1,5 @@
-export function resolveComposerModel(env = process.env) {
-    const raw = env.EKZ_AGENT_MODEL?.trim() || "composer-2.5-fast";
+export function resolveComposerModel(env = process.env, modelOverride) {
+    const raw = modelOverride?.trim() || env.EKZ_AGENT_MODEL?.trim() || "composer-2.5-fast";
     const wantFast = raw.endsWith("-fast") ||
         env.EKZ_AGENT_FAST === "true" ||
         (env.EKZ_AGENT_FAST !== "false" && raw === "composer-2.5-fast");

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

@@ -1,4 +1,4 @@
-import { SPLASH_TOOLS } from "./commands-i18n.js";
+import { formatCliToolsSummary, providersCommandLabels } from "./commands-i18n.js";
 import { MODE_LABELS } from "./mode.js";
 import { c, muted } from "./theme.js";
 function sectionTitle(locale, key) {
@@ -39,9 +39,12 @@ export function buildHelpSections(locale, currentMode) {
                 modeLine("ask"),
                 currentMode ? `Current mode: ${currentMode}` : "",
             ].filter(Boolean);
+    const p = providersCommandLabels(locale);
     const repl = locale === "pt"
         ? [
             "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",
@@ -52,6 +55,8 @@ export function buildHelpSections(locale, currentMode) {
         : locale === "zh"
             ? [
                 "用自然语言提问或描述任务。",
+                `${p.repl} · ${p.cli} (BYOK)`,
+                "ekz setup · ekz 设置",
                 "/帮助 · /help · /ajuda",
                 "/模式 代理|plan|ask · /mode agent|plan|ask",
                 "/语言 pt · /lang pt|en|zh",
@@ -61,6 +66,8 @@ 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",
@@ -68,15 +75,11 @@ export function buildHelpSections(locale, currentMode) {
                 "/doctor · /scan (quick diagnostics)",
                 "exit · quit · sair",
             ];
-    const cliTools = locale === "pt"
-        ? SPLASH_TOOLS.pt.map((t) => `ekz ${t.label} (${t.hint ?? t.label})`).join(" · ")
-        : locale === "zh"
-            ? SPLASH_TOOLS.zh.map((t) => `ekz ${t.label} (${t.hint ?? t.label})`).join(" · ")
-            : "ekz doctor · ekz health · ekz scan · ekz webhook · ekz fix · ekz agent · ekz ask";
+    const cliTools = formatCliToolsSummary(locale);
     const cli = locale === "pt"
         ? [
             "ekz · ekz agente [tarefa] · ekz corrigir [dica]",
-            "ekz perguntar [pergunta] · ekz diagnóstico · ekz credenciais",
+            "ekz perguntar [pergunta] · ekz provedores · ekz diagnóstico",
             "ekz analisar · ekz webhook <url>",
             "ekz --modo agente|plan|ask (ou --mode)",
             cliTools,
@@ -84,33 +87,34 @@ export function buildHelpSections(locale, currentMode) {
         : locale === "zh"
             ? [
                 "ekz · ekz 代理 [任务] · ekz 修复 [提示]",
-                "ekz 问答 [问题] · ekz 诊断 · ekz 凭证",
+                "ekz 问答 [问题] · ekz 供应商 · ekz 诊断",
                 "ekz 扫描 · ekz webhook <url>",
                 "ekz --mode 代理|plan|ask (或 --plan)",
                 cliTools,
             ]
             : [
                 "ekz · ekz agent [task] · ekz fix [hint]",
-                "ekz ask [question] · ekz doctor · ekz health",
+                "ekz ask [question] · ekz providers · ekz doctor",
                 "ekz scan · ekz webhook <url>",
                 "ekz --mode agent|plan|ask",
+                cliTools,
             ];
     const flags = locale === "pt"
         ? [
             "--mode agent|plan|ask · --plan (atalho para plan)",
             "--resume · --fresh · --lang pt|en|zh",
-            "-C, --cwd <path> · --api-key <chave>",
+            "-C, --cwd <path> · --api-key <key> (Cursor one-off override)",
         ]
         : locale === "zh"
             ? [
                 "--mode agent|plan|ask · --plan (plan 快捷方式)",
                 "--resume · --fresh · --lang pt|en|zh",
-                "-C, --cwd <path> · --api-key <key>",
+                "-C, --cwd <path> · --api-key <key> (Cursor one-off override)",
             ]
             : [
                 "--mode agent|plan|ask · --plan (shorthand for plan)",
                 "--resume · --fresh · --lang pt|en|zh",
-                "-C, --cwd <path> · --api-key <key>",
+                "-C, --cwd <path> · --api-key <key> (Cursor one-off override)",
             ];
     const scope = locale === "pt"
         ? ["Só integração e-Kwanza v2.4. Outras áreas do repo são só leitura."]

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"}