atabey 0.0.1

package/src/cli/commands/init/scaffold-core.ts

@@ -0,0 +1,128 @@
+import fs from "fs";
+import path from "path";
+import { 
+    remapFrameworkContent, 
+    type AdapterConfig, 
+    type AdapterId,
+    ADAPTERS
+} from "../../adapters/index.js";
+import { SHIM_TEMPLATES } from "../../shims.js";
+import { writeJsonFile, writeTextFile } from "../../utils/fs.js";
+import { getPackageRoot, getPackageVersion } from "../../utils/pkg.js";
+import { ALL_AGENTS } from "../../../modules/agents/definitions.js";
+
+const FRAMEWORK_NAME = "Agent Atabey";
+
+const COLOR_PALETTES = {
+    "Modern Blue": { primary: "#0ea5e9", secondary: "#64748b", accent: "#f43f5e" },
+    "Enterprise Slate": { primary: "#334155", secondary: "#94a3b8", accent: "#10b981" },
+    "Deep Purple": { primary: "#8b5cf6", secondary: "#d8b4fe", accent: "#f59e0b" }
+};
+
+export function scaffoldConstitution(targetDir: string, frameworkDir: string, adapterId: AdapterId, dryRun: boolean) {
+    if (dryRun) return;
+    let content = `# 🎖️ ${FRAMEWORK_NAME} — Constitution\n\nDiscipline and Order.`;
+    let readSuccess = false;
+    try {
+        const templatePath = path.join(getPackageRoot(), "ATABEY.md");
+        if (fs.existsSync(templatePath)) {
+            content = fs.readFileSync(templatePath, "utf8");
+            readSuccess = true;
+        }
+    } catch (e) {
+        console.warn(`⚠️  Failed to read global constitution template: ${e}`);
+    }
+    content = remapFrameworkContent(content, frameworkDir, adapterId);
+    const destPath = path.join(targetDir, frameworkDir, "ATABEY.md");
+    writeTextFile(destPath, content);
+
+    console.warn(`✅ Constitution file created inside: ${frameworkDir}/ATABEY.md${readSuccess ? "" : " (default template)"}`);
+}
+
+export function scaffoldFrameworkConfigs(
+    targetDir: string, 
+    fDir: string, 
+    adapter: AdapterConfig, 
+    dryRun: boolean, 
+    selectedPalette: string,
+    options?: { unified?: boolean; adapters?: string[] }
+) {
+    if (dryRun) return;
+    const frameworkDir = path.join(targetDir, fDir);
+    const palette = COLOR_PALETTES[selectedPalette as keyof typeof COLOR_PALETTES] || COLOR_PALETTES["Modern Blue"];
+
+    const config = {
+        name: FRAMEWORK_NAME,
+        version: getPackageVersion(),
+        unified: options?.unified || false,
+        adapters: options?.adapters || [adapter.id],
+        theme: {
+            palette: selectedPalette,
+            colors: palette
+        }
+    };
+    writeJsonFile(path.join(frameworkDir, "config.json"), config, dryRun);
+
+    // Scaffold shared-facts.json in memory-graph
+    const graphDir = path.join(frameworkDir, "memory-graph");
+    if (!fs.existsSync(graphDir)) fs.mkdirSync(graphDir, { recursive: true });
+    const sharedFactsPath = path.join(graphDir, "shared-facts.json");
+    if (!fs.existsSync(sharedFactsPath)) {
+        writeJsonFile(sharedFactsPath, {
+            project: FRAMEWORK_NAME,
+            initializedAt: new Date().toISOString(),
+            stack: [],
+            policies: []
+        }, dryRun);
+    }
+
+    let statusContent = "# 🎖️ Status\n\n| Agent | State | Active Task | Last Updated | Notes | Extra | Backup |\n|---|---|---|---|---|---|---|\n";
+    
+    const activeAgents = ALL_AGENTS;
+
+    const initialStatusJson: Record<string, { state: string; task: string; lastUpdated: string }> = {};
+    const now = new Date().toISOString();
+
+    for (const ag of activeAgents) {
+        statusContent += "| @" + ag.name + " | READY | Idle | - | - | - | - |\n";
+        initialStatusJson[ag.name] = { state: "READY", task: "Idle", lastUpdated: now };
+    }
+    writeTextFile(path.join(frameworkDir, "STATUS.md"), statusContent);
+
+    // Populate initial status.json
+    const statusJsonPath = path.join(frameworkDir, "memory", "status.json");
+    if (!fs.existsSync(path.join(frameworkDir, "memory"))) fs.mkdirSync(path.join(frameworkDir, "memory"), { recursive: true });
+    writeJsonFile(statusJsonPath, initialStatusJson, dryRun);
+}
+
+export function scaffoldShims(
+    projectRoot: string, 
+    coreDir: string, 
+    adapterId: AdapterId, 
+    adapter: AdapterConfig, 
+    dryRun: boolean,
+    unified: boolean = false
+) {
+    for (const [name, content] of Object.entries(SHIM_TEMPLATES)) {
+        // Normalize: "antigravity-cli" template key needs exact match or prefix match
+        const isSelectedAdapter = name === adapterId ||
+            name.toLowerCase() === adapterId.split("-")[0].toLowerCase();
+        
+        if (unified || isSelectedAdapter) {
+            const shimContent = remapFrameworkContent(content, coreDir, adapterId);
+            // In unified mode, each adapter writes its OWN shimFile name.
+            // In single-adapter mode, use selected adapter's shimFile.
+            const shimAdapter = ADAPTERS[name as AdapterId] || adapter;
+            const shimFileName = (unified && !isSelectedAdapter)
+                ? (shimAdapter.shimFile || `${name.toUpperCase()}.md`)   // each adapter's own file
+                : (adapter.shimFile || `${name.toUpperCase()}.md`);       // selected adapter's file
+            
+            if (!dryRun) writeTextFile(path.join(projectRoot, shimFileName), shimContent);
+            if (isSelectedAdapter) {
+                console.warn(`✅ Platform shim created: ${shimFileName}`);
+            } else if (unified) {
+                console.warn(`✅ Unified platform shim added: ${shimFileName}`);
+            }
+        }
+    }
+}

package/src/cli/commands/init/scaffold-ops.ts

@@ -0,0 +1,83 @@
+import fs from "fs";
+import path from "path";
+import { writeJsonFile, writeTextFile } from "../../utils/fs.js";
+import { getPackageRoot } from "../../utils/pkg.js";
+import { logger } from "../../../shared/logger.js";
+
+export function scaffoldOps(frameworkDir: string, dryRun: boolean) {
+    if (dryRun) return;
+
+    // Scaffold Prompt Recipes
+    const promptsPath = path.join(frameworkDir, "prompts");
+    if (!fs.existsSync(promptsPath)) fs.mkdirSync(promptsPath, { recursive: true });
+
+    const recipes = [
+        { file: "refactoring-recipe.md", template: "templates/prompts/refactoring-recipe.md" },
+        { file: "bug-fix-recipe.md", template: "templates/prompts/bug-fix-recipe.md" },
+        { file: "new-feature-recipe.md", template: "templates/prompts/new-feature-recipe.md" },
+        { file: "security-audit-recipe.md", template: "templates/prompts/security-audit-recipe.md" },
+        { file: "db-management-recipe.md", template: "templates/prompts/db-management-recipe.md" },
+        { file: "performance-optimization-recipe.md", template: "templates/prompts/performance-optimization-recipe.md" },
+        { file: "deployment-recipe.md", template: "templates/prompts/deployment-recipe.md" },
+        { file: "contract-design-recipe.md", template: "templates/prompts/contract-design-recipe.md" }
+    ];
+
+    for (const recipe of recipes) {
+        try {
+            const fullTemplatePath = path.join(getPackageRoot(), recipe.template);
+            if (fs.existsSync(fullTemplatePath)) {
+                const content = fs.readFileSync(fullTemplatePath, "utf8");
+                writeTextFile(path.join(promptsPath, recipe.file), content);
+            }
+        } catch (e) {
+            logger.debug(`Failed to scaffold prompt recipe: ${recipe.file}`, e);
+        }
+    }
+
+    // Scaffold cli-commands.json
+    const cliCommands = {
+        commands: {
+            init: { agent: "manager", description: "Initialize Agent Atabey structure and AI configuration." },
+            check: { agent: "quality", description: "Verify framework files and code quality discipline." },
+            status: { agent: "manager", description: "Show the current status of the active project phase." },
+            "trace:new": { agent: "manager", description: "Generate a new Trace ID to start a task sequence." },
+            orchestrate: { agent: "manager", description: "Execute the Hermes message broker loop." },
+            "verify-contract": { agent: "architect", description: "Validate type contracts between backend and frontend." },
+            "update-contract": { agent: "architect", description: "Update the contract signature hash." }
+        }
+    };
+    writeJsonFile(path.join(frameworkDir, "cli-commands.json"), cliCommands, dryRun);
+
+    // Scaffold router/routing_rules.md
+    const routerDir = path.join(frameworkDir, "router");
+    if (!fs.existsSync(routerDir)) fs.mkdirSync(routerDir, { recursive: true });
+    writeTextFile(path.join(routerDir, "routing_rules.md"), "# 📡 Agent Atabey — Natural Language & Event Router\n\nRouting engine protocols defined here.");
+
+    // Scaffold registry/agent_registry.md
+    const registryDir = path.join(frameworkDir, "registry");
+    if (!fs.existsSync(registryDir)) fs.mkdirSync(registryDir, { recursive: true });
+    writeTextFile(path.join(registryDir, "agent_registry.md"), "# 🎖️ Agent Atabey — Army Registry\n\nList of active agents.");
+
+    // Scaffold observability files
+    const obsDir = path.join(frameworkDir, "observability");
+    if (!fs.existsSync(obsDir)) fs.mkdirSync(obsDir, { recursive: true });
+    writeTextFile(path.join(obsDir, "audit_log.md"), "# 🎖️ Agent Atabey — Audit Log\n\n| Timestamp | Agent | Action | Trace ID | Status |\n|---|---|---|---|---|\n");
+    writeJsonFile(path.join(obsDir, "metrics.json"), []);
+
+    // Scaffold .env.example
+    const envExamplePath = path.join(process.cwd(), ".env.example");
+    if (!fs.existsSync(envExamplePath)) {
+        writeTextFile(envExamplePath, "# Agent Atabey - Environment Variables\n\n# Core Settings\nPORT=5858\nNODE_ENV=development\n\n# AI Platform Keys (Fill these in your local .env)\nGEMINI_API_KEY=\nCLAUDE_API_KEY=\nGROK_API_KEY=\n");
+    }
+
+    // Scaffold rules
+    const rulesDir = path.join(frameworkDir, "rules");
+    if (!fs.existsSync(rulesDir)) fs.mkdirSync(rulesDir, { recursive: true });
+    writeTextFile(path.join(rulesDir, "global_rules.mdc"), `---
+description: Global Rules for Agent Atabey Army
+globs: **/*
+---
+
+# 🎖️ Agent Atabey — Global Army Rules
+`);
+}

package/src/cli/commands/init/scaffold-standards.ts

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { ensureDir, writeTextFile } from "../../utils/fs.js";
+import { getPackageRoot } from "../../utils/pkg.js";
+import { CORE_SKILLS } from "../../../modules/skills/definitions.js";
+
+const FRAMEWORK_NAME = "Agent Atabey";
+
+export function scaffoldSkills(skillsBaseDir: string, dryRun: boolean) {
+    if (dryRun) return;
+    ensureDir(skillsBaseDir, dryRun);
+    for (const [key, skill] of Object.entries(CORE_SKILLS)) {
+        const mdContent = `# 🛠️ ${FRAMEWORK_NAME} Skill — ${skill.name}\n\n${skill.description}\n\n## 🔌 Associated Tools\n${skill.tools.map(t => `- \`${t}\``).join("\n")}\n\n## 🛡️ Core Mandates\n${skill.mandates.join("\n")}\n`;
+        writeTextFile(path.join(skillsBaseDir, `${key.toLowerCase()}.md`), mdContent);
+    }
+}
+
+export function scaffoldStandards(frameworkDir: string, dryRun: boolean) {
+    if (dryRun) return;
+    const knowledgePath = path.join(frameworkDir, "knowledge");
+    if (!fs.existsSync(knowledgePath)) fs.mkdirSync(knowledgePath, { recursive: true });
+
+    const eslintStandardsContent = `# 🎖️ Agent Atabey — ESLint Standards
+
+This document outlines the strict ESLint coding standards for Agent Atabey projects.
+
+## 📏 Core Rules
+- **Indentation:** 4 spaces (strict).
+- **Quotes:** Double quotes (\`"\`) for strings.
+- **Semicolons:** Always terminate statements with a semicolon (\`;\`).
+- **No Explicit Any:** Avoid using \`any\`. Use strongly typed interfaces, generics, or \`unknown\` with type assertions.
+- **Unused Variables:** Warning on unused variables unless prefixed with an underscore (\`_\`).
+`;
+    writeTextFile(path.join(knowledgePath, "eslint-standards.md"), eslintStandardsContent);
+
+    const standards = [
+        // ── Supreme Governance (required by @manager, @security, @architect) ──────
+        { file: "governance-standards.md", template: "templates/standards/governance-standards.md", default: "# 🎖️ Agent Atabey — Governance & Nizam Standards" },
+        // ── Core Engineering Standards ────────────────────────────────────────────
+        { file: "crud-governance.md", template: "templates/standards/crud-governance.md", default: "# 🏛️ Corporate CRUD and Governance Standards" },
+        { file: "architecture-standards.md", template: "templates/standards/architecture-standards.md", default: "# 📐 Corporate Architecture Standards" },
+        { file: "frontend-standards.md", template: "templates/standards/frontend-standards.md", default: "# 🎨 Corporate Frontend Standards" },
+        { file: "tailwind-standards.md", template: "templates/standards/tailwind-standards.md", default: "# 🌊 Corporate Tailwind Standards" },
+        { file: "mobile-standards.md", template: "templates/standards/mobile-standards.md", default: "# 📱 Corporate Mobile Standards" },
+        { file: "security-standards.md", template: "templates/standards/security-standards.md", default: "# 🛡️ Corporate Security Standards" },
+        { file: "quality-standards.md", template: "templates/standards/quality-standards.md", default: "# ⚖️ Corporate Code Quality Standards" },
+        { file: "logging-and-secrets.md", template: "templates/standards/logging-and-secrets.md", default: "# 🪵 Corporate Logging Standards" },
+        { file: "testing-standards.md", template: "templates/standards/testing-standards.md", default: "# 🧪 Corporate Testing Standards" },
+        { file: "i18n-standards.md", template: "templates/standards/i18n-standards.md", default: "# 🌐 Corporate i18n Standards" },
+        { file: "llm-governance.md", template: "templates/standards/llm-governance.md", default: "# 🤖 LLM Governance Standards" },
+        { file: "observability-standards.md", template: "templates/standards/observability-standards.md", default: "# 📈 Corporate Observability Standards" },
+        { file: "deployment-standards.md", template: "templates/standards/deployment-standards.md", default: "# 🚀 Corporate Deployment Standards" },
+        { file: "performance-standards.md", template: "templates/standards/performance-standards.md", default: "# ⚡ Corporate Performance Standards" },
+        { file: "security-audit-standards.md", template: "templates/standards/security-audit-standards.md", default: "# 🔍 Corporate Security Audit Standards" }
+    ];
+
+    for (const std of standards) {
+        let content = std.default;
+        try {
+            const fullTemplatePath = path.join(getPackageRoot(), std.template);
+            if (fs.existsSync(fullTemplatePath)) {
+                content = fs.readFileSync(fullTemplatePath, "utf8");
+            }
+        } catch { /* fallback to default */ }
+        writeTextFile(path.join(knowledgePath, std.file), content);
+    }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,163 @@
+import path from "path";
+import readline from "readline";
+
+import {
+    resolveAdapter,
+    runAdapterPostInit,
+    scaffoldAgents,
+    resolveAgentsDir,
+    mirrorUnifiedAgentsToNative,
+    ADAPTER_IDS,
+    type AdapterId,
+} from "../adapters/index.js";
+import { ensureDir } from "../utils/fs.js";
+import { initializeMemory, getConfiguredPaths } from "../utils/memory.js";
+import { getPackageVersion } from "../utils/pkg.js";
+import { UI } from "../utils/ui.js";
+
+import { ALL_AGENTS } from "../../modules/agents/definitions.js";
+import { 
+    scaffoldConstitution, 
+    scaffoldFrameworkConfigs, 
+    scaffoldShims 
+} from "./init/scaffold-core.js";
+import { 
+    scaffoldSkills, 
+    scaffoldStandards 
+} from "./init/scaffold-standards.js";
+import { scaffoldOps } from "./init/scaffold-ops.js";
+
+const FRAMEWORK_NAME = "Agent Atabey";
+
+const FRAMEWORK_SUBDIRS = [
+    "agents",
+    "skills",
+    "knowledge",
+    "prompts",
+    "memory",
+    "router",
+    "registry",
+    "observability",
+    "rules",
+];
+
+async function runInteractiveInit(): Promise<{ selectedDirs: string[], selectedAgents: string[], selectedPalette: string }> {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const question = (query: string): Promise<string> => new Promise((resolve) => rl.question(query, resolve));
+
+    try {
+        console.warn(`\n🚀 Welcome to ${FRAMEWORK_NAME} Interactive Setup!`);
+        console.warn("\nAvailable Framework Directories:");
+        FRAMEWORK_SUBDIRS.forEach((d, i) => console.warn(`${i + 1}. ${d}`));
+        const dirInput = await question("\nEnter directory numbers to include (e.g. 1,2,3) or Enter for ALL: ");
+        const selectedDirs = dirInput ? dirInput.split(",").map(n => FRAMEWORK_SUBDIRS[parseInt(n.trim()) - 1]).filter(Boolean) : [...FRAMEWORK_SUBDIRS];
+
+        console.warn("\nAvailable Core Agents:");
+        ALL_AGENTS.forEach((a, i) => console.warn(`${i + 1}. ${a.name}`));
+        const agentInput = await question("\nEnter agent numbers to include (e.g. 1,2) or Enter for ALL: ");
+        const selectedAgents = agentInput ? agentInput.split(",").map(n => ALL_AGENTS[parseInt(n.trim()) - 1].name).filter(Boolean) : ALL_AGENTS.map(a => a.name);
+
+        console.warn("\nAvailable Color Palettes:");
+        const palettes = ["Modern Blue", "Enterprise Slate", "Deep Purple"];
+        palettes.forEach((p, i) => console.warn(`${i + 1}. ${p}`));
+        const palInput = await question("\nSelect palette (1-3) or Enter for 'Modern Blue': ");
+        const selectedPalette = palettes[parseInt(palInput.trim()) - 1] || "Modern Blue";
+
+        return { selectedDirs, selectedAgents, selectedPalette };
+    } finally { rl.close(); }
+}
+
+export async function initCommand(adapterName: string, options: { unified?: boolean, dryRun?: boolean, yes?: boolean }) {
+    const adapterId = (adapterName || "gemini") as AdapterId;
+    const adapter = resolveAdapter(adapterId);
+
+    if (!adapter) {
+        UI.error(`Unknown adapter: ${adapterId}`);
+        process.exit(1);
+    }
+
+    const projectRoot = process.cwd();
+    const isUnified = options.unified || false;
+
+    // STRICT ISOLATION STRATEGY
+    const coreDir = ".atabey"; // Pure Memory & Knowledge
+    const aiToolDir = isUnified ? ".agents" : adapter.frameworkDir; // Pure Agents & Skills
+
+    const dryRun = options.dryRun || false;
+    const forceYes = options.yes || false;
+
+    UI.intent("Atabey Initialization", `Bootstrapping ${FRAMEWORK_NAME} (v${getPackageVersion()}) with ${adapterId} adapter...`);
+
+    let selectedDirs: string[];
+    let selectedAgents: string[];
+    let selectedPalette: string;
+
+    if (forceYes) {
+        selectedDirs = ["knowledge", "prompts", "memory", "router", "registry", "observability", "rules"];
+        selectedAgents = ALL_AGENTS.map(a => a.name);
+        selectedPalette = "Modern Blue";
+        UI.success(`Non-interactive mode: Using default configurations.`);
+    } else {
+        const result = await runInteractiveInit();
+        selectedDirs = result.selectedDirs.filter(d => d !== "agents" && d !== "skills");
+        selectedAgents = result.selectedAgents;
+        selectedPalette = result.selectedPalette;
+    }
+
+    ensureDir(path.join(projectRoot, coreDir), dryRun);
+    selectedDirs.forEach(dir => {
+        ensureDir(path.join(projectRoot, coreDir, dir), dryRun);
+    });
+
+    ensureDir(path.join(projectRoot, aiToolDir), dryRun);
+    if (adapter.nestedDirs) {
+        adapter.nestedDirs.forEach(dir => ensureDir(path.join(projectRoot, aiToolDir, dir), dryRun));
+    }
+
+    scaffoldConstitution(projectRoot, coreDir, adapterId, dryRun);
+    scaffoldFrameworkConfigs(projectRoot, coreDir, adapter, dryRun, selectedPalette, {
+        unified: isUnified,
+        adapters: isUnified ? [...ADAPTER_IDS] : [adapterId]
+    });
+
+    scaffoldStandards(path.join(projectRoot, coreDir), dryRun);
+
+    const pathsMap = getConfiguredPaths();
+
+    if (isUnified) {
+        // Scaffold ALL agents for ALL adapters under unified hub
+        for (const id of ADAPTER_IDS) {
+            const dest = resolveAgentsDir(id, true, aiToolDir);
+            scaffoldAgents(projectRoot, id, dryRun, selectedAgents, dest.agentsDir, dest.agentsExt, pathsMap);
+            if (!dryRun) mirrorUnifiedAgentsToNative(projectRoot, id);
+        }
+        UI.success(`✅ Scaffolding complete for all adapters under ${aiToolDir}/ with native mirrors.`);
+    } else {
+        // Standard single-adapter scaffold
+        const dest = resolveAgentsDir(adapterId, false);
+        scaffoldAgents(projectRoot, adapterId, dryRun, selectedAgents, dest.agentsDir, dest.agentsExt, pathsMap);
+        UI.success(`✅ Generated agent definitions under ${dest.agentsDir}/`);
+    }
+
+    const skillsBaseDir = path.join(projectRoot, aiToolDir, "skills");
+    scaffoldSkills(skillsBaseDir, dryRun);
+    scaffoldOps(path.join(projectRoot, coreDir), dryRun);
+    scaffoldShims(projectRoot, coreDir, adapterId, adapter, dryRun, isUnified);
+
+    // Initialize runtime directories
+    if (!dryRun) {
+        ensureDir(path.join(projectRoot, coreDir, "messages"));
+        ensureDir(path.join(projectRoot, coreDir, "logs"));
+        ensureDir(path.join(projectRoot, coreDir, "memory-graph"));
+    }
+
+    initializeMemory(path.join(projectRoot, coreDir), dryRun);
+    runAdapterPostInit(adapter, projectRoot);
+
+    UI.success(`\n🚀 ${FRAMEWORK_NAME} (v${getPackageVersion()}) initialized successfully!`);
+    console.warn(`\n- Brain & Memory Hub (Protected): ${coreDir}/`);
+    console.warn(`- AI Agent Commands (Active): ${aiToolDir}/`);
+    console.warn("\nNext Steps:");
+    console.warn("  1. Run 'atabey status' to verify the environment.");
+    console.warn(`  2. Open ${adapterId === "claude" ? "Claude Desktop" : "your AI Assistant"} and start commanding the Army.`);
+}

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+
+import { getFrameworkDir } from "../utils/memory.js";
+
+import { writeTextFile } from "../utils/fs.js";
+
+export async function updateKnowledgeBaseCommand(topic: string, content: string) {
+    if (!topic || !content) {
+        console.error("❌ Usage: atabey update_knowledge_base <topic> <content>");
+        return;
+    }
+    const frameworkDir = getFrameworkDir();
+    const kbDir = path.join(frameworkDir, "knowledge");
+    if (!fs.existsSync(kbDir)) fs.mkdirSync(kbDir, { recursive: true });
+    const fileName = topic.replace(/[^a-z0-9]/gi, "_").toLowerCase() + ".md";
+    writeTextFile(path.join(kbDir, fileName), content);
+    console.warn(`✅ Knowledge base updated: ${topic}`);
+}
+
+export async function searchKnowledgeBaseCommand(query: string) {
+    if (!query) {
+        console.error("❌ Usage: atabey search_knowledge_base <query>");
+        return;
+    }
+    const frameworkDir = getFrameworkDir();
+    const kbDir = path.join(frameworkDir, "knowledge");
+    if (!fs.existsSync(kbDir)) {
+        console.warn("ℹ️ Knowledge base is empty.");
+        return;
+    }
+    const files = fs.readdirSync(kbDir).filter(f => f.endsWith(".md"));
+    let found = false;
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(kbDir, file), "utf-8");
+        if (content.toLowerCase().includes(query.toLowerCase()) || file.toLowerCase().includes(query.toLowerCase())) {
+            console.warn(`
+### ${file.replace(".md", "")}
+${content.slice(0, 300)}...`);
+            found = true;
+        }
+    }
+    if (!found) console.warn("ℹ️ No matching entries found.");
+}

package/src/cli/commands/lint.ts

@@ -0,0 +1,23 @@
+import { execSync } from "child_process";
+
+import { getPackageVersion } from "../utils/pkg.js";
+
+/**
+ * Run ESLint for the project (same as npm run lint).
+ */
+export async function lintCommand(): Promise<void> {
+    console.warn(`🔍 Running ESLint (v${getPackageVersion()})...`);
+    const projectRoot = process.cwd();
+    try {
+        execSync("npm run lint", {
+            cwd: projectRoot,
+            stdio: "inherit",
+            env: process.env,
+        });
+        console.warn("\n✅ ESLint passed with no errors.");
+    } catch {
+        console.warn("\n❌ ESLint reported errors. Fix violations before committing.");
+        console.warn("   Tip: npm run lint -- --fix");
+        process.exit(1);
+    }
+}

package/src/cli/commands/log.ts

@@ -0,0 +1,37 @@
+import fs from "fs";
+import path from "path";
+
+import { getFrameworkDir } from "../utils/memory.js";
+import { normalizeAgentName } from "../utils/string.js";
+
+import { writeJsonFile } from "../utils/fs.js";
+
+export async function logAgentActionCommand(data: { agent?: unknown; action?: string; requestId?: string; traceId?: string; status?: string; summary?: string; files?: string[]; details?: Record<string, unknown> }) {
+    const frameworkDir = getFrameworkDir();
+    const logsDir = path.join(frameworkDir, "logs");
+    if (!fs.existsSync(logsDir)) {
+        fs.mkdirSync(logsDir, { recursive: true });
+    }
+
+    const agent = normalizeAgentName(data.agent);
+    const logPath = path.join(logsDir, `${agent}.json`);
+    let logs: Record<string, unknown>[] = [];
+
+    if (fs.existsSync(logPath)) {
+        try {
+            logs = JSON.parse(fs.readFileSync(logPath, "utf8"));
+            if (!Array.isArray(logs)) logs = [];
+        } catch {
+            logs = [];
+        }
+    }
+
+    const newEntry = {
+        timestamp: new Date().toISOString(),
+        ...data,
+    };
+
+    logs.push(newEntry);
+    writeJsonFile(logPath, logs);
+    console.warn(`✅ Logged action to ${frameworkDir}/logs/${agent}.json`);
+}

package/src/cli/commands/memory.ts

@@ -0,0 +1,6 @@
+import { updateProjectMemory } from "../utils/memory.js";
+
+export async function updateProjectMemoryCommand(section: string, content: string) {
+    updateProjectMemory(section, content);
+}
+