gencow 0.1.7 → 0.1.8

package/bin/gencow.mjs

@@ -1185,16 +1185,16 @@ ${BOLD}Dev commands:${RESET}
   ${GREEN}mcp${RESET}              Start MCP server for AI agent integration ${DIM}(stdio)${RESET}
 
 ${BOLD}BaaS commands (login required):${RESET}
-  ${GREEN}login${RESET}            Login to Gencow Platform
+  ${GREEN}login${RESET}            Login to Gencow Platform ${DIM}(browser → token)${RESET}
   ${GREEN}logout${RESET}           Clear credentials
-  ${GREEN}dev:remote${RESET}       Watch gencow/ + auto-deploy on change ${DIM}(like npx convex dev)${RESET}
-  ${GREEN}app list${RESET}         List your apps
-  ${GREEN}app create <name>${RESET} Create a new app (provisions Bun process)
-  ${GREEN}app delete <name>${RESET} Delete an app
-  ${GREEN}app status <name>${RESET} Show app status
-  ${GREEN}remote:deploy${RESET}    Bundle gencow/ and deploy to platform (one-shot)
-  ${GREEN}logs${RESET}             Show recent logs ${DIM}(--follow for live streaming)${RESET}
-  ${GREEN}platform${RESET}         Start the Control Plane server (port 4000)
+  ${GREEN}whoami${RESET}           Show current user info
+  ${GREEN}deploy${RESET}           Bundle gencow/ and deploy to platform
+                     ${DIM}--prod  Deploy to production (confirmation required)${RESET}
+                     ${DIM}--name, -n  Specify app name${RESET}
+  ${GREEN}env list${RESET}         List remote env vars ${DIM}(--prod for production)${RESET}
+  ${GREEN}env set K=V${RESET}      Set remote env var
+  ${GREEN}env unset KEY${RESET}    Remove remote env var
+  ${GREEN}env push${RESET}         Push local .env to remote
 
 ${BOLD}Production:${RESET}
   ${GREEN}deploy${RESET}           Build Docker image + start production stack
@@ -1211,8 +1211,488 @@ ${BOLD}Examples:${RESET}
 `);
     },
 
-    // ── login ──────────────────────────────────────────
-    // ── mcp ──────────────────────────────────────────────
+    // ── login — Device Auth 패턴 ──────────────────────────
+    async login() {
+        log(`\n${BOLD}${CYAN}Gencow Login${RESET}\n`);
+
+        const platformUrl = process.env.GENCOW_PLATFORM_URL || "https://gencow.dev";
+        info(`Platform: ${platformUrl}`);
+
+        // 1. auth-start → 인증 코드 생성
+        info("인증 코드 요청 중...");
+        let authData;
+        try {
+            const res = await fetch(`${platformUrl}/platform/cli/auth-start`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+            });
+            if (!res.ok) throw new Error(`HTTP ${res.status}`);
+            authData = await res.json();
+        } catch (e) {
+            error(`Platform 서버 연결 실패: ${e.message}`);
+            error(`Platform URL: ${platformUrl}`);
+            error(`서버가 실행 중인지 확인하세요.`);
+            process.exit(1);
+        }
+
+        log("");
+        log(`  ${BOLD}인증 코드: ${CYAN}${authData.code}${RESET}`);
+        log("");
+        info(`브라우저에서 로그인하세요:`);
+        log(`  ${CYAN}${authData.url}${RESET}`);
+        log("");
+
+        // 2. 브라우저 오픈
+        try {
+            const { exec } = await import("child_process");
+            const openCmd = process.platform === "darwin" ? "open" :
+                process.platform === "win32" ? "start" : "xdg-open";
+            exec(`${openCmd} "${authData.url}"`);
+        } catch {
+            warn("브라우저를 자동으로 열 수 없습니다. 위 URL을 직접 열어주세요.");
+        }
+
+        // 3. 폴링 — 2초마다 인증 완료 확인
+        info("로그인 대기 중...");
+        const POLL_INTERVAL = 2000;
+        const MAX_POLLS = 150; // 10분 내 5분 = 150회
+
+        for (let i = 0; i < MAX_POLLS; i++) {
+            await new Promise(r => setTimeout(r, POLL_INTERVAL));
+
+            try {
+                const res = await fetch(`${platformUrl}/platform/cli/auth-poll`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ code: authData.code }),
+                });
+                const data = await res.json();
+
+                if (data.status === "completed") {
+                    // 4. 토큰 저장
+                    saveCreds({
+                        apiKey: data.token,
+                        userId: data.userId,
+                        platformUrl,
+                        loginAt: new Date().toISOString(),
+                    });
+
+                    log("");
+                    success(`로그인 완료!`);
+                    info(`토큰 저장됨: ${DIM}~/.gencow/credentials.json${RESET}`);
+                    log("");
+                    return;
+                }
+
+                if (data.status === "expired") {
+                    error("인증 코드가 만료되었습니다. 다시 시도하세요: gencow login");
+                    process.exit(1);
+                }
+
+                // pending — 계속 폴링
+                process.stdout.write(".");
+            } catch {
+                // 네트워크 오류 — 재시도
+                process.stdout.write("x");
+            }
+        }
+
+        error("\n타임아웃. 다시 시도하세요: gencow login");
+        process.exit(1);
+    },
+
+    // ── logout ────────────────────────────────────────────
+    async logout() {
+        try {
+            unlinkSync(CREDS_PATH);
+            success("로그아웃 완료. 자격 증명이 삭제되었습니다.");
+        } catch {
+            info("이미 로그아웃 상태입니다.");
+        }
+    },
+
+    // ── whoami ────────────────────────────────────────────
+    async whoami() {
+        const creds = loadCreds();
+        if (!creds?.apiKey) {
+            error("로그인하지 않았습니다.");
+            info("실행: gencow login");
+            return;
+        }
+
+        try {
+            const res = await fetch(`${creds.platformUrl}/platform/me`, {
+                headers: { "Authorization": `Bearer ${creds.apiKey}` },
+            });
+
+            if (!res.ok) {
+                error("토큰이 만료되었거나 유효하지 않습니다.");
+                info("실행: gencow login");
+                return;
+            }
+
+            const data = await res.json();
+            log(`\n${BOLD}${CYAN}Gencow CLI${RESET}\n`);
+            info(`User ID:  ${data.userId}`);
+            info(`Platform: ${creds.platformUrl}`);
+            info(`Token:    ${creds.apiKey.slice(0, 10)}...${creds.apiKey.slice(-4)}`);
+            info(`Expires:  ${new Date(data.expiresAt).toLocaleString()}`);
+            log("");
+        } catch (e) {
+            error(`서버 연결 실패: ${e.message}`);
+        }
+    },
+
+    // ── deploy ────────────────────────────────────────────
+    async deploy(...deployArgs) {
+        const creds = requireCreds();
+
+        // gencow.json 또는 gencow.config.ts에서 앱 이름 확인
+        let appName = null;
+        let envTarget = "dev";
+
+        for (let i = 0; i < deployArgs.length; i++) {
+            const a = deployArgs[i];
+            if (a === "--prod") envTarget = "prod";
+            else if (a === "--name" || a === "-n") appName = deployArgs[++i];
+            else if (!a.startsWith("-")) appName = a;
+        }
+
+        // gencow.json에서 앱 이름 로드
+        const gencowJsonPath = resolve(process.cwd(), "gencow.json");
+        if (!appName && existsSync(gencowJsonPath)) {
+            const gencowJson = JSON.parse(readFileSync(gencowJsonPath, "utf8"));
+            appName = gencowJson.appName;
+        }
+
+        if (!appName) {
+            // gencow.config.ts에서 프로젝트 이름 추출 시도
+            const configPath = resolve(process.cwd(), "gencow.config.ts");
+            if (existsSync(configPath)) {
+                const content = readFileSync(configPath, "utf8");
+                const match = content.match(/name:\s*["']([^"']+)["']/);
+                if (match) appName = match[1];
+            }
+        }
+
+        if (!appName) {
+            // 디렉토리 이름을 앱 이름으로 사용
+            appName = basename(process.cwd());
+        }
+
+        log(`\n${BOLD}${CYAN}Gencow Deploy${RESET}\n`);
+        info(`앱:    ${appName}`);
+        info(`환경:  ${envTarget}`);
+        info(`포맷:  tar.gz`);
+        log("");
+
+        // 프로덕션 배포 확인
+        if (envTarget === "prod") {
+            const { createInterface } = await import("readline");
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await new Promise(resolve => {
+                rl.question(`  ${YELLOW}⚠${RESET} 프로덕션 배포를 진행하시겠습니까? (y/N) `, resolve);
+            });
+            rl.close();
+            if (answer.toLowerCase() !== "y") {
+                info("배포 취소됨.");
+                return;
+            }
+        }
+
+        // 1. tar.gz 패키징
+        info("프로젝트 패키징 중...");
+        const { execSync: exec } = await import("child_process");
+        const tmpBundle = resolve(process.cwd(), ".gencow", "deploy-bundle.tar.gz");
+        mkdirSync(dirname(tmpBundle), { recursive: true });
+
+        // gencow/ 폴더 + package.json + .env (있으면) 패키징
+        const filesToPack = ["gencow/", "package.json"];
+        if (existsSync(resolve(process.cwd(), "bun.lockb"))) filesToPack.push("bun.lockb");
+        if (existsSync(resolve(process.cwd(), "package-lock.json"))) filesToPack.push("package-lock.json");
+        if (existsSync(resolve(process.cwd(), "tsconfig.json"))) filesToPack.push("tsconfig.json");
+
+        // gencow/ 디렉토리 존재 확인
+        if (!existsSync(resolve(process.cwd(), "gencow"))) {
+            error("gencow/ 디렉토리가 없습니다. Gencow 프로젝트 루트에서 실행하세요.");
+            process.exit(1);
+        }
+
+        try {
+            exec(`tar -czf "${tmpBundle}" ${filesToPack.join(" ")}`, { cwd: process.cwd() });
+        } catch (e) {
+            error(`패키징 실패: ${e.message}`);
+            process.exit(1);
+        }
+
+        const bundleSize = statSync(tmpBundle).size;
+        success(`번들 생성: ${(bundleSize / 1024).toFixed(1)} KB`);
+
+        // 2. 앱 생성 or 확인
+        info("앱 상태 확인 중...");
+        const checkRes = await platformFetch(creds, `/platform/apps/${appName}/deploy`, { method: "HEAD" }).catch(() => null);
+
+        // 앱이 없으면 먼저 생성 (RPC mutation 호출)
+        // Note: deploy API는 앱이 이미 존재해야 함
+        // 여기서는 일단 deploy 시도 — 404면 앱 생성 후 재시도
+
+        // 3. 업로드
+        info("배포 중...");
+        const bundleBuffer = readFileSync(tmpBundle);
+
+        const deployRes = await fetch(
+            `${creds.platformUrl}/platform/apps/${appName}/deploy?env=${envTarget}`,
+            {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${creds.apiKey}`,
+                    "Content-Type": "application/octet-stream",
+                },
+                body: bundleBuffer,
+            }
+        );
+
+        // 임시 파일 정리
+        try { unlinkSync(tmpBundle); } catch { }
+
+        if (!deployRes.ok) {
+            const errData = await deployRes.json().catch(() => ({}));
+
+            // 앱이 없으면 생성 후 재시도
+            if (deployRes.status === 404) {
+                warn(`앱 "${appName}"이 아직 없습니다. 생성합니다...`);
+
+                const createRes = await fetch(`${creds.platformUrl}/api/mutation`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Authorization": `Bearer ${creds.apiKey}`,
+                    },
+                    body: JSON.stringify({ name: "apps.create", args: { name: appName } }),
+                });
+
+                if (!createRes.ok) {
+                    const createErr = await createRes.json().catch(() => ({}));
+                    error(`앱 생성 실패: ${createErr.error || createRes.statusText}`);
+                    process.exit(1);
+                }
+
+                success(`앱 "${appName}" 생성 완료. 프로비저닝 대기 중...`);
+                await new Promise(r => setTimeout(r, 3000));
+
+                // 재배포
+                info("재배포 시도...");
+                // tar.gz를 다시 만들어야 함 (위에서 삭제했으므로)
+                exec(`tar -czf "${tmpBundle}" ${filesToPack.join(" ")}`, { cwd: process.cwd() });
+                const retryBuffer = readFileSync(tmpBundle);
+                const retryRes = await fetch(
+                    `${creds.platformUrl}/platform/apps/${appName}/deploy?env=${envTarget}`,
+                    {
+                        method: "POST",
+                        headers: {
+                            "Authorization": `Bearer ${creds.apiKey}`,
+                            "Content-Type": "application/octet-stream",
+                        },
+                        body: retryBuffer,
+                    }
+                );
+                try { unlinkSync(tmpBundle); } catch { }
+
+                if (!retryRes.ok) {
+                    const retryErr = await retryRes.json().catch(() => ({}));
+                    error(`배포 실패: ${retryErr.error || retryRes.statusText}`);
+                    process.exit(1);
+                }
+
+                const retryData = await retryRes.json();
+                log("");
+                success(`배포 완료!`);
+                info(`URL:   ${retryData.url}`);
+                info(`Hash:  ${retryData.bundleHash}`);
+                log("");
+                return;
+            }
+
+            error(`배포 실패: ${errData.error || deployRes.statusText}`);
+            process.exit(1);
+        }
+
+        const deployData = await deployRes.json();
+
+        log("");
+        success(`배포 완료!`);
+        info(`URL:   ${deployData.url}`);
+        info(`Hash:  ${deployData.bundleHash}`);
+        if (deployData.deployId) info(`ID:    ${deployData.deployId}`);
+        log("");
+
+        // gencow.json 업데이트 (앱 이름 저장)
+        if (!existsSync(gencowJsonPath)) {
+            writeFileSync(gencowJsonPath, JSON.stringify({
+                appName,
+                platformUrl: creds.platformUrl,
+            }, null, 2));
+            info(`${DIM}gencow.json 생성됨${RESET}`);
+        }
+    },
+
+    // ── env ───────────────────────────────────────────────
+    async env(...envArgs) {
+        const creds = requireCreds();
+        const subCmd = envArgs[0] || "list";
+        const restArgs = envArgs.slice(1);
+
+        // 앱 이름 결정
+        let appName = null;
+        let envTarget = "dev";
+
+        for (let i = 0; i < restArgs.length; i++) {
+            if (restArgs[i] === "--app" || restArgs[i] === "-a") appName = restArgs[++i];
+            if (restArgs[i] === "--prod") envTarget = "prod";
+        }
+
+        if (!appName) {
+            const gencowJsonPath = resolve(process.cwd(), "gencow.json");
+            if (existsSync(gencowJsonPath)) {
+                const gencowJson = JSON.parse(readFileSync(gencowJsonPath, "utf8"));
+                appName = gencowJson.appName;
+            }
+        }
+
+        if (!appName) {
+            appName = basename(process.cwd());
+        }
+
+        switch (subCmd) {
+            case "list":
+            case "ls": {
+                const res = await fetch(
+                    `${creds.platformUrl}/platform/apps/${appName}/env?env=${envTarget}`,
+                    { headers: { "Authorization": `Bearer ${creds.apiKey}` } }
+                );
+                if (!res.ok) {
+                    error(`환경변수 조회 실패: ${(await res.json().catch(() => ({}))).error || res.statusText}`);
+                    return;
+                }
+                const vars = await res.json();
+                log(`\n${BOLD}${CYAN}환경변수${RESET} — ${appName} (${envTarget})\n`);
+                if (vars.length === 0) {
+                    info("설정된 환경변수가 없습니다.");
+                } else {
+                    for (const v of vars) {
+                        log(`  ${v.key}`);
+                    }
+                }
+                log("");
+                break;
+            }
+
+            case "set": {
+                // gencow env set KEY=VALUE [KEY2=VALUE2...]
+                const kvPairs = restArgs.filter(a => a.includes("=") && !a.startsWith("-"));
+                if (kvPairs.length === 0) {
+                    error("사용법: gencow env set KEY=VALUE [KEY2=VALUE2...]");
+                    return;
+                }
+
+                for (const kv of kvPairs) {
+                    const [key, ...valueParts] = kv.split("=");
+                    const value = valueParts.join("=");
+
+                    const res = await fetch(
+                        `${creds.platformUrl}/platform/apps/${appName}/env`,
+                        {
+                            method: "POST",
+                            headers: {
+                                "Authorization": `Bearer ${creds.apiKey}`,
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify({ key, value, env: envTarget }),
+                        }
+                    );
+
+                    if (res.ok) {
+                        success(`${key} 설정 완료 (${envTarget})`);
+                    } else {
+                        error(`${key} 설정 실패`);
+                    }
+                }
+                break;
+            }
+
+            case "unset":
+            case "remove": {
+                const keys = restArgs.filter(a => !a.startsWith("-"));
+                if (keys.length === 0) {
+                    error("사용법: gencow env unset KEY [KEY2...]");
+                    return;
+                }
+
+                for (const key of keys) {
+                    const res = await fetch(
+                        `${creds.platformUrl}/platform/apps/${appName}/env/${key}?env=${envTarget}`,
+                        {
+                            method: "DELETE",
+                            headers: { "Authorization": `Bearer ${creds.apiKey}` },
+                        }
+                    );
+
+                    if (res.ok) {
+                        success(`${key} 삭제 완료`);
+                    } else {
+                        error(`${key} 삭제 실패`);
+                    }
+                }
+                break;
+            }
+
+            case "push": {
+                // 로컬 .env 파일 → 리모트 일괄 push
+                const envFile = resolve(process.cwd(), envTarget === "prod" ? ".env.production" : ".env");
+                if (!existsSync(envFile)) {
+                    error(`${envFile} 파일을 찾을 수 없습니다.`);
+                    return;
+                }
+
+                const envContent = readFileSync(envFile, "utf8");
+                const vars = {};
+                for (const line of envContent.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed.startsWith("#")) continue;
+                    const [key, ...valueParts] = trimmed.split("=");
+                    if (key) vars[key.trim()] = valueParts.join("=").trim();
+                }
+
+                const count = Object.keys(vars).length;
+                info(`${count}개 환경변수를 ${appName} (${envTarget})에 push합니다...`);
+
+                const res = await fetch(
+                    `${creds.platformUrl}/platform/apps/${appName}/env/bulk`,
+                    {
+                        method: "PUT",
+                        headers: {
+                            "Authorization": `Bearer ${creds.apiKey}`,
+                            "Content-Type": "application/json",
+                        },
+                        body: JSON.stringify({ vars, env: envTarget }),
+                    }
+                );
+
+                if (res.ok) {
+                    success(`${count}개 환경변수 push 완료`);
+                } else {
+                    error(`push 실패: ${(await res.json().catch(() => ({}))).error}`);
+                }
+                break;
+            }
+
+            default:
+                error(`알 수 없는 하위 명령: ${subCmd}`);
+                info("사용법: gencow env [list|set|unset|push] ...");
+        }
+    },
+
+
     async mcp(...mcpArgs) {
         let port = "5456";
         for (let i = 0; i < mcpArgs.length; i++) {
@@ -1667,15 +2147,19 @@ ${BOLD}${CYAN}Gencow Dev Remote${RESET}
             log(`\n${BOLD}${CYAN}gencow add${RESET} — Add components to your project\n`);
             log(`${BOLD}Usage:${RESET}  gencow add <component...>\n`);
             log(`${BOLD}Available components:${RESET}`);
-            log(`  ${GREEN}AI${RESET}         Vercel AI SDK wrapper ${DIM}(chat, stream, embed)${RESET}`);
-            log(`  ${GREEN}Tools${RESET}      AI Tool Calling with ctx integration`);
-            log(`  ${GREEN}RAG${RESET}        Document ingestion + semantic search`);
-            log(`  ${GREEN}Memory${RESET}     Agent memory ${DIM}(episodic/semantic/procedural)${RESET}`);
-            log(`  ${GREEN}Analytics${RESET}  LLM call tracking ${DIM}(tokens, cost, latency)${RESET}`);
+            log(`  ${GREEN}AI${RESET}          Vercel AI SDK wrapper ${DIM}(chat, stream, embed, agent, retry)${RESET}`);
+            log(`  ${GREEN}Tools${RESET}       AI Tool Calling with ctx integration`);
+            log(`  ${GREEN}RAG${RESET}         Document ingestion + semantic search + Q&A`);
+            log(`  ${GREEN}Reranker${RESET}    LLM-powered search result reranking`);
+            log(`  ${GREEN}Guardrails${RESET}  Input/output safety filters`);
+            log(`  ${GREEN}Prompts${RESET}     Reusable prompt templates`);
+            log(`  ${GREEN}Parsers${RESET}     PDF/HTML/CSV file parsing`);
+            log(`  ${GREEN}Memory${RESET}      Agent memory ${DIM}(episodic/semantic/procedural)${RESET}`);
+            log(`  ${GREEN}Analytics${RESET}   LLM call tracking ${DIM}(coming soon)${RESET}`);
             log(`\n${BOLD}Examples:${RESET}`);
             log(`  ${DIM}gencow add AI${RESET}`);
-            log(`  ${DIM}gencow add AI RAG Tools${RESET}`);
-            log(`  ${DIM}gencow add Memory${RESET}\n`);
+            log(`  ${DIM}gencow add AI RAG Reranker${RESET}`);
+            log(`  ${DIM}gencow add Guardrails Prompts${RESET}\n`);
             return;
         }
 
@@ -1750,6 +2234,63 @@ ${BOLD}${CYAN}Gencow Dev Remote${RESET}
                 notReady: true,
                 guide: [],
             },
+            reranker: {
+                label: "Reranker",
+                deps: [],
+                files: [
+                    { src: "reranker.ts", dest: "gencow/reranker.ts" },
+                ],
+                env: {},
+                requires: ["ai"],
+                guide: [
+                    `gencow/reranker.ts 에서 reranker.rerank(), reranker.searchAndRerank() 사용 가능`,
+                    `const reranked = await reranker.rerank(query, searchResults, { topK: 5 })`,
+                    `RAG 파이프라인: await reranker.searchAndRerank(ctx, rag, query)`,
+                ],
+            },
+            guardrails: {
+                label: "Guardrails",
+                deps: [],
+                files: [
+                    { src: "guardrails.ts", dest: "gencow/guardrails.ts" },
+                ],
+                env: {},
+                requires: ["ai"],
+                guide: [
+                    `gencow/guardrails.ts 에서 guardrails.validateInput(), guardrails.validateOutput() 사용 가능`,
+                    `PII 마스킹: guardrails.validateInput(text, { maskPII: true })`,
+                    `주제 차단: guardrails.validateInput(text, { blockTopics: ["정치"] })`,
+                    `한 번에 래핑: guardrails.wrap(fn, input, inputOpts, outputOpts)`,
+                ],
+            },
+            prompts: {
+                label: "Prompt Templates",
+                deps: [],
+                files: [
+                    { src: "prompts.ts", dest: "gencow/prompts.ts" },
+                ],
+                env: {},
+                requires: [],
+                guide: [
+                    `gencow/prompts.ts 에서 definePrompt() 로 재사용 프롬프트 정의`,
+                    `내장 템플릿: ragQAPrompt, summarizePrompt, classifyPrompt`,
+                    `const filled = ragQAPrompt({ question: "...", context: "..." })`,
+                ],
+            },
+            parsers: {
+                label: "File Parsers",
+                deps: ["pdf-parse"],
+                files: [
+                    { src: "parsers.ts", dest: "gencow/parsers.ts" },
+                ],
+                env: {},
+                requires: [],
+                guide: [
+                    `gencow/parsers.ts 에서 parsers.pdf(), parsers.html(), parsers.csv() 사용 가능`,
+                    `자동 감지: await parsers.auto("file.pdf", buffer)`,
+                    `RAG 연동: await rag.ingest(ctx, "file.pdf", await parsers.pdf(buffer))`,
+                ],
+            },
         };
 
         log(`\n${BOLD}${CYAN}gencow add${RESET}\n`);
@@ -1897,7 +2438,13 @@ const COMPONENT_DOCS = {
 | :--- | :--- | :--- |
 | \`ai.chat()\` | \`function\` | 텍스트 생성 (비스트리밍) |
 | \`ai.stream()\` | \`function\` | 스트리밍 응답 |
-| \`ai.embed()\` | \`function\` | 텍스트 임베딩 (RAG/Memory용) |`,
+| \`ai.embed()\` | \`function\` | 텍스트 임베딩 (RAG/Memory용) |
+| \`ai.embedMany()\` | \`function\` | 배치 임베딩 (대용량 인제스트) |
+| \`ai.generateObject()\` | \`function\` | 구조화 JSON 출력 (Zod 스키마) |
+| \`ai.agent()\` | \`function\` | Agent Loop (multi-turn tool use) |
+| \`ai.withRetry()\` | \`function\` | 자동 재시도 + 폴백 미들웨어 |
+| \`ai.estimateTokens()\` | \`function\` | 토큰 수 추정 (간이) |
+| \`ai.trimMessages()\` | \`function\` | 메시지 토큰 예산 자르기 |`,
         usage: `\`\`\`typescript
 import { ai } from "@/gencow/ai";
 
@@ -1907,37 +2454,62 @@ const reply = await ai.chat({
     messages: [{ role: "user", content: "안녕?" }],
 });
 
-// 스트리밍
-const stream = await ai.stream({ messages: [...] });
-for await (const chunk of stream.textStream) {
-    process.stdout.write(chunk);
-}
+// Agent Loop — 도구 자동 반복 호출
+const result = await ai.agent({
+    system: "고객 지원 에이전트입니다.",
+    messages: [{ role: "user", content: "주문 ORD-123 환불해줘" }],
+    tools: defineTools(ctx, { ... }),
+    maxSteps: 5,
+});
+
+// 재시도 + 폴백
+const safe = await ai.withRetry(
+    () => ai.chat({ messages: [...] }),
+    { maxRetries: 3 }
+);
 \`\`\``,
         vibePrompt: `AI 엔진 사용법:
   import { ai } from "@/gencow/ai";
   ai.chat({ messages })       // 텍스트 생성
   ai.stream({ messages })     // 스트리밍
-  ai.embed("텍스트")           // 임베딩`,
+  ai.embed("텍스트")           // 임베딩
+  ai.embedMany(["a","b"])     // 배치 임베딩
+  ai.agent({ messages, tools, maxSteps })  // Agent Loop
+  ai.withRetry(fn, { maxRetries: 3 })      // 재시도+폴백
+  ai.estimateTokens(text)     // 토큰 추정
+  ai.trimMessages(msgs, { maxTokens: 4000 })  // 토큰 예산`,
     },
     "rag.ts": {
         title: "🔍 RAG Engine",
         table: `| Function | Type | Description |
 | :--- | :--- | :--- |
-| \`rag.ingest()\` | \`function\` | 문서 청킹 + 임베딩 저장 |
-| \`rag.search()\` | \`function\` | 시맨틱 검색 (코사인 유사도) |`,
+| \`rag.ingest()\` | \`function\` | 문서 청킹 + 임베딩 저장 (스마트 청킹, 배치 임베딩) |
+| \`rag.search()\` | \`function\` | 시맨틱 검색 (코사인 유사도, 소스 필터) |
+| \`rag.ask()\` | \`function\` | RAG Q&A (검색→컨텍스트→AI 답변) |
+| \`rag.delete()\` | \`function\` | 소스별 문서 삭제 |`,
         usage: `\`\`\`typescript
 import { rag } from "@/gencow/rag";
 
-// mutation 안에서 문서 인제스트
-await rag.ingest(ctx, "manual.pdf", documentText);
+// mutation 안에서 문서 인제스트 (스마트 청킹 자동 적용)
+await rag.ingest(ctx, "manual.pdf", documentText, { strategy: "markdown" });
 
-// query 안에서 시맨틱 검색
-const results = await rag.search(ctx, "환불 정책이 뭔가요?");
+// query 안에서 시맨틱 검색 (소스 필터 가능)
+const results = await rag.search(ctx, "환불 정책이 뭔가요?", {
+    filter: { source: "manual.pdf" },
+});
+
+// Q&A — 검색+답변 한 번에
+const { answer, sources } = await rag.ask(ctx, "환불 정책이 뭔가요?");
+
+// 문서 삭제
+await rag.delete(ctx, "old-manual.pdf");
 \`\`\``,
         vibePrompt: `RAG 엔진 사용법:
   import { rag } from "@/gencow/rag";
-  rag.ingest(ctx, source, text)   // 문서 인제스트
-  rag.search(ctx, query)          // 시맨틱 검색`,
+  rag.ingest(ctx, source, text)              // 문서 인제스트 (스마트 청킹)
+  rag.search(ctx, query, { filter })         // 시맨틱 검색
+  rag.ask(ctx, question)                     // Q&A (검색+답변)
+  rag.delete(ctx, source)                    // 문서 삭제`,
     },
     "tools.ts": {
         title: "🔧 Tool Calling",
@@ -1998,6 +2570,110 @@ const reply = await ai.chat({
         vibePrompt: `Analytics:
   ai.chat()/ai.stream() 호출 시 자동 계측됩니다.`,
     },
+    "reranker.ts": {
+        title: "🎯 Reranker",
+        table: `| Function | Type | Description |
+| :--- | :--- | :--- |
+| \`reranker.rerank()\` | \`function\` | LLM 기반 검색 결과 재정렬 |
+| \`reranker.searchAndRerank()\` | \`function\` | RAG search + rerank 통합 |`,
+        usage: `\`\`\`typescript
+import { reranker } from "@/gencow/reranker";
+import { rag } from "@/gencow/rag";
+
+// 벡터 검색 후 LLM 재정렬
+const results = await rag.search(ctx, query, { limit: 20 });
+const reranked = await reranker.rerank(query, results, { topK: 5 });
+
+// 한 번에 (search + rerank)
+const best = await reranker.searchAndRerank(ctx, rag, query);
+\`\`\``,
+        vibePrompt: `Reranker 사용법:
+  import { reranker } from "@/gencow/reranker";
+  reranker.rerank(query, docs, { topK: 5 })  // LLM 재정렬
+  reranker.searchAndRerank(ctx, rag, query)   // 통합 파이프라인`,
+    },
+    "guardrails.ts": {
+        title: "🛡️ Guardrails",
+        table: `| Function | Type | Description |
+| :--- | :--- | :--- |
+| \`guardrails.validateInput()\` | \`function\` | 입력 검증 (PII/주제/길이) |
+| \`guardrails.validateOutput()\` | \`function\` | 출력 검증 (길이/패턴/커스텀) |
+| \`guardrails.wrap()\` | \`function\` | 입력→AI→출력 한 번에 래핑 |`,
+        usage: `\`\`\`typescript
+import { guardrails } from "@/gencow/guardrails";
+
+// PII 마스킹 + 주제 차단
+const safe = await guardrails.validateInput(userMsg, {
+    maskPII: true,
+    blockTopics: ["정치", "종교"],
+});
+if (!safe.allowed) return safe.blocked;
+
+// 래핑 유틸리티
+const result = await guardrails.wrap(
+    (sanitized) => ai.chat({ messages: [{ role: "user", content: sanitized }] }),
+    userMsg,
+    { maskPII: true },
+    { maxLength: 2000 }
+);
+\`\`\``,
+        vibePrompt: `Guardrails 사용법:
+  import { guardrails } from "@/gencow/guardrails";
+  guardrails.validateInput(text, { maskPII: true })  // PII 마스킹
+  guardrails.validateInput(text, { blockTopics })     // 주제 차단
+  guardrails.wrap(fn, input, inputOpts, outputOpts)   // 한 번에 래핑`,
+    },
+    "prompts.ts": {
+        title: "📝 Prompt Templates",
+        table: `| Function | Type | Description |
+| :--- | :--- | :--- |
+| \`definePrompt()\` | \`function\` | 재사용 프롬프트 팩토리 |
+| \`ragQAPrompt\` | \`template\` | RAG Q&A 내장 프롬프트 |
+| \`summarizePrompt\` | \`template\` | 요약 내장 프롬프트 |
+| \`classifyPrompt\` | \`template\` | 분류 내장 프롬프트 |`,
+        usage: `\`\`\`typescript
+import { definePrompt, ragQAPrompt } from "@/gencow/prompts";
+
+// 내장 템플릿 사용
+const filled = ragQAPrompt({ question: "환불 정책?", context: docs });
+
+// 커스텀 프롬프트 정의
+const myPrompt = definePrompt({
+    template: "{{role}}로서 {{task}}를 수행하세요.",
+    defaults: { role: "도움이 되는 AI" },
+});
+const prompt = myPrompt({ role: "전문가", task: "코드 리뷰" });
+\`\`\``,
+        vibePrompt: `Prompt Templates 사용법:
+  import { definePrompt, ragQAPrompt } from "@/gencow/prompts";
+  definePrompt({ template, defaults })  // 재사용 프롬프트 정의
+  ragQAPrompt({ question, context })    // RAG Q&A 프롬프트`,
+    },
+    "parsers.ts": {
+        title: "📄 File Parsers",
+        table: `| Function | Type | Description |
+| :--- | :--- | :--- |
+| \`parsers.pdf()\` | \`function\` | PDF → 텍스트 추출 |
+| \`parsers.html()\` | \`function\` | HTML → 텍스트 (태그 제거) |
+| \`parsers.csv()\` | \`function\` | CSV → 행별 텍스트 |
+| \`parsers.auto()\` | \`function\` | 확장자 기반 자동 파싱 |`,
+        usage: `\`\`\`typescript
+import { parsers } from "@/gencow/parsers";
+
+// PDF 파싱 후 RAG 인제스트
+const text = await parsers.pdf(fileBuffer);
+await rag.ingest(ctx, "manual.pdf", text);
+
+// 자동 감지
+const content = await parsers.auto("report.html", htmlString);
+\`\`\``,
+        vibePrompt: `File Parsers 사용법:
+  import { parsers } from "@/gencow/parsers";
+  parsers.pdf(buffer)          // PDF → 텍스트
+  parsers.html(htmlString)     // HTML → 텍스트
+  parsers.csv(csvText)         // CSV → ["header: value", ...]
+  parsers.auto(filename, buf)  // 확장자 자동 감지`,
+    },
 };
 
 async function updateReadme(config) {