@ekzs/cli 0.2.0

package/dist/lib/theme.js

@@ -0,0 +1,40 @@
+export const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    orange: "\x1b[38;5;208m",
+    orangeBold: "\x1b[1;38;5;208m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    cyan: "\x1b[36m",
+    white: "\x1b[97m",
+    slate: "\x1b[38;5;245m",
+};
+export function muted(text) {
+    return `${c.dim}${c.slate}${text}${c.reset}`;
+}
+export function accent(text) {
+    return `${c.orangeBold}${text}${c.reset}`;
+}
+export function label(key, value) {
+    return `  ${muted(`${key}:`)} ${c.white}${value}${c.reset}`;
+}
+export function separator(width = 56) {
+    return muted("  " + "─".repeat(width));
+}
+export function badge(text) {
+    return `${c.orange} ${c.bold}${text}${c.reset}`;
+}
+export function toolRunning(name) {
+    return `\n  ${c.orange}${c.bold}▸${c.reset} ${c.bold}${name}${c.reset} ${muted("…")}\n`;
+}
+export function toolDone(name) {
+    return `  ${c.green}${c.bold}✓${c.reset} ${muted(name)}\n`;
+}
+export function toolError(name) {
+    return `  ${c.red}${c.bold}✗${c.reset} ${name}\n`;
+}
+export function turnDivider() {
+    return `\n  ${muted("─".repeat(54))}\n`;
+}

package/dist/lib/ui/ascii-art.d.ts

@@ -0,0 +1,10 @@
+/** 5-line block letters — gradient applied per line in splash */
+export declare const BLOCK_EKZ: string[];
+export declare const BLOCK_CONNECT: string[];
+/** Compact CONNECT for narrower terminals */
+export declare const BLOCK_CONNECT_SHORT: string[];
+/** Payment mascot — é-Kwanza / Multicaixa vibe */
+export declare const MASCOT: string[];
+export declare function printHeroTitle(useShortConnect?: boolean): void;
+export declare function printHeroSubtitle(text: string): void;
+//# sourceMappingURL=ascii-art.d.ts.map

package/dist/lib/ui/ascii-art.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ascii-art.d.ts","sourceRoot":"","sources":["../../../src/lib/ui/ascii-art.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,eAAO,MAAM,SAAS,UAOrB,CAAC;AAEF,eAAO,MAAM,aAAa,UAOzB,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,UAM/B,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,MAAM,UASlB,CAAC;AAIF,wBAAgB,cAAc,CAAC,eAAe,UAAQ,GAAG,IAAI,CAa5D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGpD"}

package/dist/lib/ui/ascii-art.js

@@ -0,0 +1,55 @@
+import { c } from "../theme.js";
+/** 5-line block letters — gradient applied per line in splash */
+export const BLOCK_EKZ = [
+    " ███████╗██╗  ██╗███████╗",
+    " ██╔════╝██║ ██╔╝╚══███╔╝",
+    " █████╗  █████╔╝  ███╔╝ ",
+    " ██╔══╝  ██╔═██╗ ███╔╝  ",
+    " ███████╗██║  ██╗███████╗",
+    " ╚══════╝╚═╝  ╚═╝╚══════╝",
+];
+export const BLOCK_CONNECT = [
+    " ██████╗ ██████╗ ███╗   ██╗███╗   ██╗███████╗ ██████╗████████╗",
+    "██╔════╝██╔═══██╗████╗  ██║████╗  ██║██╔════╝██╔════╝╚══██╔══╝",
+    "██║     ██║   ██║██╔██╗ ██║██╔██╗ ██║█████╗  ██║        ██║   ",
+    "██║     ██║   ██║██║╚██╗██║██║╚██╗██║██╔══╝  ██║        ██║   ",
+    "╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗   ██║   ",
+    " ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═══╝╚══════╝ ╚═════╝   ╚═╝   ",
+];
+/** Compact CONNECT for narrower terminals */
+export const BLOCK_CONNECT_SHORT = [
+    " ██████╗ ██████╗ ███╗   ██╗",
+    "██╔════╝██╔═══██╗████╗  ██║",
+    "██║     ██║   ██║██╔██╗ ██║",
+    "╚██████╗╚██████╔╝██║ ╚████║",
+    " ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝",
+];
+/** Payment mascot — é-Kwanza / Multicaixa vibe */
+export const MASCOT = [
+    "    ┌──────────────┐",
+    "    │  é-Kwanza v2 │",
+    "    │  ▓▓▓▓▓▓▓▓▓▓  │",
+    "    │ GPO · EMIS · │",
+    "    │    Ticket    │",
+    "    └──────┬───────┘",
+    "       Multicaixa",
+    "         ◆ Kz ◆",
+];
+const GRADIENT = ["\x1b[38;5;226m", "\x1b[38;5;220m", "\x1b[38;5;214m", "\x1b[38;5;208m", "\x1b[38;5;172m", "\x1b[38;5;130m"];
+export function printHeroTitle(useShortConnect = false) {
+    const connect = useShortConnect ? BLOCK_CONNECT_SHORT : BLOCK_CONNECT;
+    console.log("");
+    for (let i = 0; i < BLOCK_EKZ.length; i++) {
+        const color = GRADIENT[Math.min(i, GRADIENT.length - 1)];
+        console.log(`  ${color}${c.bold}${BLOCK_EKZ[i]}${c.reset}`);
+    }
+    for (let i = 0; i < connect.length; i++) {
+        const color = GRADIENT[Math.min(i + 1, GRADIENT.length - 1)];
+        console.log(`  ${color}${connect[i]}${c.reset}`);
+    }
+    console.log("");
+}
+export function printHeroSubtitle(text) {
+    console.log(`  ${c.dim}\x1b[38;5;245m${text}${c.reset}`);
+    console.log("");
+}

package/dist/lib/ui/layout.d.ts

@@ -0,0 +1,19 @@
+/** Visible-length helpers for aligned terminal UI */
+export declare function stripAnsi(text: string): string;
+export declare function visibleLength(text: string): number;
+export declare function padEndVisible(text: string, width: number): string;
+export declare function truncateVisible(text: string, max: number): string;
+export declare function mergeColumns(left: string[], right: string[], leftWidth: number, gap?: number): string[];
+export declare const BOX: {
+    tl: string;
+    tr: string;
+    bl: string;
+    br: string;
+    h: string;
+    v: string;
+    cross: string;
+    teeR: string;
+    teeL: string;
+};
+export declare function renderBorderBox(title: string, bodyLines: string[], width?: number): void;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/lib/ui/layout.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAOlG;AAED,eAAO,MAAM,GAAG;;;;;;;;;;CAUf,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,SAAK,GAAG,IAAI,CAWpF"}

package/dist/lib/ui/layout.js

@@ -0,0 +1,46 @@
+/** Visible-length helpers for aligned terminal UI */
+export function stripAnsi(text) {
+    return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+export function visibleLength(text) {
+    return stripAnsi(text).length;
+}
+export function padEndVisible(text, width) {
+    return text + " ".repeat(Math.max(0, width - visibleLength(text)));
+}
+export function truncateVisible(text, max) {
+    const plain = stripAnsi(text);
+    if (plain.length <= max)
+        return text;
+    return plain.slice(0, Math.max(0, max - 1)) + "…";
+}
+export function mergeColumns(left, right, leftWidth, gap = 2) {
+    const rows = Math.max(left.length, right.length);
+    const out = [];
+    for (let i = 0; i < rows; i++) {
+        out.push(padEndVisible(left[i] ?? "", leftWidth) + " ".repeat(gap) + (right[i] ?? ""));
+    }
+    return out;
+}
+export const BOX = {
+    tl: "╭",
+    tr: "╮",
+    bl: "╰",
+    br: "╯",
+    h: "─",
+    v: "│",
+    cross: "┼",
+    teeR: "├",
+    teeL: "┤",
+};
+export function renderBorderBox(title, bodyLines, width = 78) {
+    const inner = width - 2;
+    const titlePlain = ` ${title} `;
+    const dashCount = Math.max(0, inner - visibleLength(titlePlain));
+    const top = `${BOX.tl}${titlePlain}${BOX.h.repeat(dashCount)}${BOX.tr}`;
+    console.log(top);
+    for (const line of bodyLines) {
+        console.log(`${BOX.v}${padEndVisible(` ${line}`, inner)}${BOX.v}`);
+    }
+    console.log(`${BOX.bl}${BOX.h.repeat(inner)}${BOX.br}`);
+}

package/dist/lib/ui/logo.d.ts

@@ -0,0 +1,3 @@
+/** Two-line wordmark — always reads EKZ / CONNECT */
+export declare function renderLogoLines(): string[];
+//# sourceMappingURL=logo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logo.d.ts","sourceRoot":"","sources":["../../../src/lib/ui/logo.ts"],"names":[],"mappings":"AAMA,qDAAqD;AACrD,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C"}

package/dist/lib/ui/logo.js

@@ -0,0 +1,8 @@
+import { c } from "../theme.js";
+function colorLine(text, color) {
+    return `${c.bold}\x1b[38;5;${color}m${text}${c.reset}`;
+}
+/** Two-line wordmark — always reads EKZ / CONNECT */
+export function renderLogoLines() {
+    return [colorLine("EKZ", 226), colorLine("CONNECT", 208)];
+}

package/dist/lib/ui/prompt.d.ts

@@ -0,0 +1,6 @@
+export declare function askWithPlaceholder(opts: {
+    prompt: string;
+    placeholder: string;
+}): Promise<string>;
+export declare function formatInputPrompt(): string;
+//# sourceMappingURL=prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/lib/ui/prompt.ts"],"names":[],"mappings":"AAIA,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8ElB;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/lib/ui/prompt.js

@@ -0,0 +1,75 @@
+import readline from "readline";
+import { stripAnsi } from "./layout.js";
+import { c, muted } from "../theme.js";
+export async function askWithPlaceholder(opts) {
+    if (!process.stdin.isTTY) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        return new Promise((resolve) => {
+            rl.question(opts.prompt, (answer) => {
+                rl.close();
+                resolve(answer.trim() || stripAnsi(opts.placeholder).replace(/^Try /i, "").replace(/^Experimenta /i, ""));
+            });
+        });
+    }
+    return new Promise((resolve) => {
+        const { prompt, placeholder } = opts;
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        stdout.write(prompt);
+        stdout.write("\x1b[s");
+        stdout.write(muted(placeholder));
+        stdout.write("\x1b[u");
+        readline.emitKeypressEvents(stdin);
+        stdin.setRawMode(true);
+        stdin.resume();
+        let value = "";
+        let hintVisible = true;
+        const clearHint = () => {
+            if (!hintVisible)
+                return;
+            hintVisible = false;
+            stdout.write("\x1b[0K");
+        };
+        const cleanup = () => {
+            stdin.setRawMode(false);
+            stdin.removeListener("keypress", onKeypress);
+            stdout.write("\n");
+        };
+        const onKeypress = (_char, key) => {
+            if (!key)
+                return;
+            if (key.name === "return") {
+                cleanup();
+                resolve(value.trim());
+                return;
+            }
+            if (key.name === "c" && key.ctrl) {
+                cleanup();
+                process.exit(130);
+            }
+            if (key.name === "backspace") {
+                if (value.length > 0) {
+                    value = value.slice(0, -1);
+                    stdout.write("\b \b");
+                }
+                return;
+            }
+            if (key.name === "escape") {
+                cleanup();
+                resolve("");
+                return;
+            }
+            const ch = key.sequence;
+            if (!ch || key.ctrl || key.meta)
+                return;
+            if (hintVisible)
+                clearHint();
+            value += ch;
+            stdout.write(ch);
+        };
+        stdin.on("keypress", onKeypress);
+    });
+}
+export function formatInputPrompt() {
+    return `  ${c.orange}${c.bold}›${c.reset} `;
+}

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

@@ -0,0 +1,15 @@
+import { type EkzLocale } from "../locale.js";
+import { type EkzMode } from "../mode.js";
+export type SplashOptions = {
+    cwd?: string;
+    model?: string;
+    locale: EkzLocale;
+    mode?: EkzMode;
+    resumed?: boolean;
+    agentId?: string;
+    version?: string;
+};
+export declare function renderSplash(opts: SplashOptions): void;
+export declare function renderPromptFooter(locale: EkzLocale): void;
+export declare function inputPlaceholder(locale: EkzLocale, index?: number): string;
+//# sourceMappingURL=splash.d.ts.map

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

@@ -0,0 +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"}

package/dist/lib/ui/splash.js

@@ -0,0 +1,121 @@
+import { userInfo } from "os";
+import { basename } from "path";
+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 { uiStrings } from "../locale.js";
+import { MODE_LABELS } from "../mode.js";
+import { detectShellEnvironment, shellLabel } from "../shell.js";
+import { c, muted } from "../theme.js";
+import { padEndVisible, truncateVisible, visibleLength } from "./layout.js";
+import { renderLogoLines } from "./logo.js";
+const BOX_WIDTH = 78;
+const LEFT_WIDTH = 34;
+const RIGHT_WIDTH = BOX_WIDTH - LEFT_WIDTH - 5;
+function packageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "../../../package.json"), "utf8"));
+        return pkg.version ?? "0.2.0";
+    }
+    catch {
+        return "0.2.0";
+    }
+}
+function displayName() {
+    const fromEnv = process.env.EKZ_USER_NAME?.trim();
+    if (fromEnv)
+        return fromEnv.split(/\s+/)[0] ?? fromEnv;
+    try {
+        const u = userInfo().username.replace(/[._-].*$/, "");
+        if (u)
+            return u.charAt(0).toUpperCase() + u.slice(1);
+    }
+    catch {
+        /* ignore */
+    }
+    return "Alberto";
+}
+function userLabel() {
+    const email = process.env.EKZ_USER_EMAIL?.trim();
+    if (email)
+        return email;
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return "developer";
+    }
+}
+function gold(text) {
+    return `${c.bold}\x1b[38;5;220m${text}${c.reset}`;
+}
+function buildLeftColumn(opts, locale) {
+    const name = displayName();
+    const project = opts.cwd ? `~/${basename(opts.cwd)}` : "~";
+    const modelShort = (opts.model ?? "composer-2.5 (fast)").replace(/\s*\(fast\)/i, "").trim();
+    const lang = locale === "pt" ? "Português" : locale === "zh" ? "中文" : "English";
+    const user = truncateVisible(userLabel(), 16);
+    const modeLabel = opts.mode ? MODE_LABELS[opts.mode][locale] : MODE_LABELS.agent[locale];
+    const top = [];
+    top.push(gold(welcomeMessage(locale, name, Boolean(opts.resumed))));
+    top.push("");
+    for (const row of renderLogoLines()) {
+        top.push(truncateVisible(row, LEFT_WIDTH));
+    }
+    const shell = shellLabel(detectShellEnvironment());
+    const footer = [
+        muted(`${modelShort} · ${lang} · ${user}`),
+        muted(truncateVisible(`${modeLabel} · ${shell}`, LEFT_WIDTH)),
+        muted(project),
+    ];
+    return { top, footer };
+}
+function buildRightColumn(locale) {
+    const lines = [];
+    lines.push(gold(splashSectionTitle(locale, "tools")));
+    for (const tool of SPLASH_TOOLS[locale]) {
+        lines.push(muted(`  ${formatSplashTool(locale, tool)}`));
+    }
+    lines.push("");
+    lines.push(muted("─".repeat(26)));
+    lines.push("");
+    lines.push(gold(splashSectionTitle(locale, "sessions")));
+    for (const hint of splashSessionLines(locale))
+        lines.push(muted(`  ${hint}`));
+    return lines;
+}
+function renderTwoColumnBox(title, leftTop, leftFooter, right) {
+    const inner = BOX_WIDTH - 2;
+    const border = `${c.orange}${c.bold}`;
+    const divider = `${border}│${c.reset}`;
+    const rows = Math.max(leftTop.length + leftFooter.length, right.length);
+    const pad = Math.max(0, rows - leftTop.length - leftFooter.length);
+    const left = [...leftTop, ...Array(pad).fill(""), ...leftFooter];
+    const dashRight = Math.max(0, inner - visibleLength(title) - 6);
+    console.log(`  ${border}╭───${title}${"─".repeat(dashRight)}╮${c.reset}`);
+    for (let i = 0; i < rows; i++) {
+        const l = padEndVisible(left[i] ?? "", LEFT_WIDTH);
+        const r = padEndVisible(truncateVisible(right[i] ?? "", RIGHT_WIDTH), RIGHT_WIDTH);
+        console.log(`  ${border}│${c.reset} ${l} ${divider} ${r} ${border}│${c.reset}`);
+    }
+    console.log(`  ${border}╰${"─".repeat(inner)}╯${c.reset}`);
+}
+export function renderSplash(opts) {
+    const version = opts.version ?? packageVersion();
+    const title = ` By Alberto Moisés v${version} `;
+    const left = buildLeftColumn(opts, opts.locale);
+    console.log("");
+    renderTwoColumnBox(title, left.top, left.footer, buildRightColumn(opts.locale));
+    console.log("");
+}
+export function renderPromptFooter(locale) {
+    console.log(`  ${muted(splashHelpHint(locale))}`);
+    console.log("");
+}
+export function inputPlaceholder(locale, index = 0) {
+    const t = uiStrings(locale);
+    const pool = t.inputPlaceholders ?? [t.inputPlaceholder];
+    return pool[index % pool.length] ?? 'Try "run ekz doctor"';
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ekzs/cli",
+  "version": "0.2.0",
+  "description": "CLI agent for e-Kwanza v2.4 — health checks, code scan, webhook tests, AI assistance",
+  "type": "module",
+  "bin": {
+    "ekz": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "skills", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "build:local": "npm run build && node scripts/sync-skills.mjs",
+    "sync:skills": "node scripts/sync-skills.mjs",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.13",
+    "@ekzs/connect": "^0.1.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "keywords": ["ekwanza", "ekzs", "cli", "payments", "angola", "cursor", "agent"],
+  "author": "Alberto Moisés",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Almpro3/ekz.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Almpro3/ekz/issues"
+  },
+  "homepage": "https://github.com/Almpro3/ekz/tree/main/packages/cli#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/ekz-connect/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ekz-connect
+description: >-
+  e-Kwanza payment architecture orchestrator. Routes work across payment core,
+  provider adapter, one-time products, ticket/invite selling, subscriptions,
+  overage, webhook normalization, and integration playbook.
+---
+
+# Ekz Connect - orchestrator
+
+You are **Ekz**, a local coding agent for e-Kwanza-powered payment systems.
+
+## Core principle
+
+e-Kwanza is a one-time payment rail. Reliable products, invite/ticket sales, subscriptions, and overage billing come from a clean local payment architecture built on top of that rail.
+
+Internal reference implementations are learning material only. Do not copy their plans, tables, routes, or UI blindly. Extract the pattern and map it into the target codebase.
+
+## Posture
+
+- Scope: payment architecture and e-Kwanza integration.
+- Read unrelated code for context; edit only the payment surface needed for the task.
+- Prefer the target app's existing models, jobs, auth, and route patterns.
+- Use `@ekzs/connect` for provider-specific e-Kwanza work when possible.
+- Never log or commit secrets.
+- Keep business fulfillment separate from provider callback handling.
+- Do not mention internal reference app names to end users unless they ask about them.
+
+## Shell commands (Windows / PowerShell)
+
+The local agent runs shell tool commands in the user's terminal. On Windows the default is often **PowerShell**, not bash.
+
+- **Never** use bare `curl` on Windows — it is an alias for `Invoke-WebRequest` and will prompt for `Uri:`. Use `curl.exe -s "https://..."` with a quoted URL, `Invoke-WebRequest -Uri "..." -UseBasicParsing`, or Node `fetch`.
+- Avoid bash-only syntax (`export VAR=`, `| head`, `/dev/null`, `$(...)`) unless you explicitly run `bash -lc "..."`.
+- Prefer Ekz CLI helpers (load `.env.local` automatically): `ekz doctor`, `ekz health`, `ekz scan`, `ekz webhook <url>`.
+- Ekz CLI detects the terminal at launch (Cursor settings, Git Bash, or Windows PowerShell default) and passes shell rules to the agent automatically — no manual flag needed.
+- Quote paths and URLs that contain spaces.
+
+## User intent expansion
+
+Users should be able to ask in plain product language. Expand simple prompts into the right architecture internally:
+
+| User says | Interpret as |
+|-----------|--------------|
+| "Create a payment link for this product" | One-time product payment with public checkout link |
+| "25 products in stock" | Inventory/capacity guard plus paid-only stock decrement |
+| "Integrate payment in my store" | Store checkout over one-time product payment architecture |
+| "Multicaixa Express" | e-Kwanza `gpo` rail |
+| "reference code" / "bank reference" | e-Kwanza `emis_ref` rail unless the codebase already uses Ticket API for this wording |
+| "SMS/QR/e-Kwanza wallet code" | e-Kwanza `ticket` rail |
+| "sell tickets/invites" | Ticket/invite business flow with reservation and issuance |
+| "subscriptions" / "monthly billing" | Local recurring billing cycles over one-time payment requests |
+| "charge extra usage" / "overage" | Metered usage ledger plus one-time overage charge |
+
+The final user response should talk about the feature they asked for, not the internal skill names or reference apps.
+
+## Workflow
+
+1. Classify the task by architecture.
+2. Inspect existing account, order, ticket, subscription, usage, payment, webhook, and job models.
+3. Load the relevant skills.
+4. Map generic payment primitives into the app's vocabulary.
+5. Put e-Kwanza behind a provider adapter.
+6. Normalize webhooks before running domain handlers.
+7. Add focused tests for state transitions and duplicate callbacks.
+
+## Route by architecture
+
+| Problem | Skill |
+|---------|-------|
+| Reusable primitives, state machines, ledger, provider boundary | **ekz-payment-core-architecture** |
+| e-Kwanza auth, config, GPO, EMIS ref, Ticket API, env validation | **ekz-ekwanza-provider-adapter** |
+| Product/order/invoice checkout, paid fulfillment, receipts | **ekz-one-time-product-payments** |
+| Invite/ticket inventory, reservations, QR/code issuance | **ekz-ticket-invite-selling** |
+| Recurring billing, trials, grace, dunning, entitlement extension | **ekz-subscription-billing** |
+| Metered usage, usage ledger, overage charges, settlement | **ekz-overage-billing** |
+| Callback parsing, idempotency, status mapping, routing | **ekz-webhook-normalization** |
+| Unknown codebase adaptation and implementation order | **ekz-integration-playbook** |
+| SDK API, CLI commands, `ekz doctor`, `ekz scan` | **ekz-sdk-cli** |
+
+## Do not conflate
+
+| Concept | Owner |
+|---------|-------|
+| `PaymentRequest`, `PaymentAttempt`, ledger, idempotency | Payment Core |
+| GPO, EMIS ref, Ticket API, HMAC | e-Kwanza Provider Adapter |
+| Product sale or invoice payment | One-Time Product Payments |
+| Event ticket/invite business object | Ticket / Invite Selling |
+| Subscription renewal | Subscription Billing |
+| Usage above allowance | Overage Billing |
+| Raw provider callback | Webhook Normalization |
+| Mapping into an existing app | Integration Playbook |
+
+The e-Kwanza `ticket` rail is not the same thing as selling event tickets or invites.
+
+## Internal references
+
+- **Ekz Connect** (`c:\Users\alber\ekz`): provider adapter, checkout links, payment collections, stock-like fulfillment.
+- `eloapp/frontend/src/lib/billing/ekwanza-recurring.ts`: recurring one-time billing requests for subscriptions.