@xagent/x-cli 1.1.55 → 1.1.57

package/README.md

@@ -1,4 +1,4 @@
-## 1.1.55 – Logo Assets & NPM Publication Complete
+## 1.1.57 – Logo Assets & NPM Publication Complete
 
 ✅ **Live on NPM**: [@xagent/x-cli](https://www.npmjs.com/package/@xagent/x-cli) - Fully published and ready for global installation
 
@@ -419,6 +419,141 @@ This means you can have different models for different projects while maintainin
 }
 ```
 
+## 📚 .agent Documentation System
+
+### 🎯 **Best Feature of X CLI - AI Context Optimization**
+
+The **`.agent` folder** is the most powerful feature of X CLI, enabling **self-documenting AI workflows** that automatically provide context to AI agents. This revolutionary approach ensures every AI interaction is informed by comprehensive project documentation, making conversations with Grok significantly more productive and accurate.
+
+### 🏗️ **How It Works**
+
+When you run `npx -y @xagent/x-cli@latest`, the CLI automatically detects and reads `.agent/` documentation:
+
+1. **Auto-Discovery**: Scans for `.agent/` folder in current directory
+2. **Configuration Loading**: Reads `.agent/auto-read-config.json` for custom settings
+3. **Smart Loading**: Reads configured documentation files into chat context
+4. **Context Enhancement**: Provides comprehensive project understanding to AI
+
+### 📂 **Key Components**
+
+#### **`sop/` - Standard Operating Procedures**
+
+- **`git-workflow.md`** - Git workflow standards and smart push guidelines
+- **`release-management.md`** - Automated release processes and version management
+- **`automation-protection.md`** - Safeguards for automated NPM publishing
+- **`npm-publishing-troubleshooting.md`** - NPM publication issue resolution
+- **`documentation-workflow.md`** - Documentation maintenance procedures
+
+#### **`system/` - System Architecture & State**
+
+- **`architecture.md`** - Complete system design and technology stack
+- **`critical-state.md`** - Current system capabilities and status
+- **`api-schema.md`** - API integration specifications
+- **`installation.md`** - Setup and deployment procedures
+- **`auto-read-system.md`** - Documentation of this auto-loading feature!
+
+### 🔄 **Auto-Read System Benefits**
+
+#### **Immediate Context**
+
+- **Zero Setup Required**: Just having `.agent/` folder provides instant AI context
+- **Comprehensive Understanding**: AI gets complete project overview on startup
+- **Standardized Knowledge**: Consistent documentation format across projects
+
+#### **Self-Documenting Workflows**
+
+- **Living Documentation**: Docs evolve with project development
+- **AI-Assisted Maintenance**: AI can help update documentation
+- **Version-Controlled**: All docs tracked in git with project history
+
+#### **Quality Assurance**
+
+- **Error Prevention**: SOPs guide AI to follow established patterns
+- **Consistency Enforcement**: Standardized approaches across team
+- **Knowledge Preservation**: Critical procedures documented and accessible
+
+### 🪝 **Husky Commit Hook Integration**
+
+**Best Practice**: Set up automatic documentation syncing with git hooks.
+
+#### **Why Husky Integration?**
+
+The `.agent` folder is intentionally **gitignored** (contains sensitive project-specific docs), but you want docs to sync to public repositories or team wikis. Husky commit hooks automate this process:
+
+1. **Pre-commit Validation**: Ensure docs are up-to-date before commits
+2. **Auto-Sync**: Push docs to Docusaurus, GitHub Wiki, or team documentation sites
+3. **Quality Gates**: Prevent commits if critical docs are missing
+
+#### **Setup Instructions**
+
+1. **Initialize `.agent` system**:
+
+```bash
+xcli
+/init-agent
+```
+
+2. **Install Husky**:
+
+```bash
+npm install --save-dev husky
+npx husky install
+```
+
+3. **Add documentation sync hook**:
+
+```bash
+npx husky add .husky/pre-commit "npm run sync-docs"
+```
+
+4. **Configure sync script** (add to `package.json`):
+
+```json
+{
+  "scripts": {
+    "sync-docs": "xcli /update-agent-docs --sync-to-docusaurus"
+  }
+}
+```
+
+#### **Benefits of Husky Integration**
+
+- **Automatic Updates**: Docs sync on every commit
+- **Team Consistency**: Everyone's local docs stay current
+- **Quality Assurance**: Pre-commit checks ensure documentation completeness
+- **Zero Manual Work**: Documentation maintenance becomes automatic
+
+### 🎖️ **Why This is Revolutionary**
+
+1. **Context-First AI**: Unlike other CLIs that start conversations from scratch, X CLI begins with complete project context
+
+2. **Self-Improving System**: As you document procedures, AI gets better at following them
+
+3. **Knowledge Preservation**: Critical procedures are documented where they're actually used
+
+4. **Team Synchronization**: Everyone works with the same documented standards
+
+5. **Future-Proof**: AI can help maintain and evolve documentation
+
+### 🚀 **Getting Started**
+
+1. **Initialize your project**:
+
+```bash
+xcli
+/init-agent
+```
+
+2. **Customize documentation** in `.agent/` folder
+
+3. **Set up Husky hooks** for automatic syncing
+
+4. **Enjoy context-aware AI** that understands your project's standards and procedures!
+
+**This feature transforms AI CLI interactions from generic conversations to informed, context-aware development sessions.**
+
+---
+
 ## Usage
 
 ### Interactive Mode

package/dist/index.js

@@ -9293,7 +9293,7 @@ EOF`;
 var package_default = {
   type: "module",
   name: "@xagent/x-cli",
-  version: "1.1.55",
+  version: "1.1.57",
   description: "An open-source AI agent that brings the power of Grok directly into your terminal.",
   main: "dist/index.js",
   module: "dist/index.js",
@@ -18314,75 +18314,80 @@ function ChatInterfaceWithAgent({
     if (fs__default.existsSync(".agent")) {
       const initialMessages = [];
       let docsRead = 0;
-      initialMessages.push({
-        type: "assistant",
-        content: "\u{1F4DA} Reading core documentation into memory...",
-        timestamp: /* @__PURE__ */ new Date()
-      });
-      const archPath = path7__default.join(".agent", "system", "architecture.md");
-      if (fs__default.existsSync(archPath)) {
+      let config2 = null;
+      const configPath = path7__default.join(".agent", "auto-read-config.json");
+      if (fs__default.existsSync(configPath)) {
         try {
-          const archContent = fs__default.readFileSync(archPath, "utf8");
-          initialMessages.push({
-            type: "assistant",
-            content: `\u{1F4CB} **System Architecture (from .agent/system/architecture.md)**
-
-${archContent}`,
-            timestamp: /* @__PURE__ */ new Date()
-          });
-          docsRead++;
+          const configContent = fs__default.readFileSync(configPath, "utf8");
+          config2 = JSON.parse(configContent);
         } catch (_error) {
         }
       }
-      const workflowPath = path7__default.join(".agent", "sop", "git-workflow.md");
-      if (fs__default.existsSync(workflowPath)) {
-        try {
-          const workflowContent = fs__default.readFileSync(workflowPath, "utf8");
-          initialMessages.push({
-            type: "assistant",
-            content: `\u{1F527} **Git Workflow SOP (from .agent/sop/git-workflow.md)**
-
-${workflowContent}`,
-            timestamp: /* @__PURE__ */ new Date()
-          });
-          docsRead++;
-        } catch (_error) {
-        }
+      const isEnabled = config2?.enabled !== false;
+      const showLoadingMessage = config2?.showLoadingMessage !== false;
+      const showSummaryMessage = config2?.showSummaryMessage !== false;
+      if (!isEnabled) {
+        return;
       }
-      const sopDir = path7__default.join(".agent", "sop");
-      if (fs__default.existsSync(sopDir)) {
-        const sopFiles = ["release-management.md", "automation-protection.md"];
-        for (const file of sopFiles) {
-          const filePath = path7__default.join(sopDir, file);
-          if (fs__default.existsSync(filePath)) {
-            try {
-              const content = fs__default.readFileSync(filePath, "utf8");
-              const title = file.replace(".md", "").replace("-", " ").toUpperCase();
-              initialMessages.push({
-                type: "assistant",
-                content: `\u{1F4D6} **${title} SOP (from .agent/sop/${file})**
-
-${content}`,
-                timestamp: /* @__PURE__ */ new Date()
-              });
-              docsRead++;
-            } catch (_error) {
-            }
-          }
+      if (showLoadingMessage) {
+        initialMessages.push({
+          type: "assistant",
+          content: "\u{1F4DA} Reading core documentation into memory...",
+          timestamp: /* @__PURE__ */ new Date()
+        });
+      }
+      const folders = config2?.folders || [
+        {
+          name: "system",
+          priority: 1,
+          files: [
+            { name: "architecture.md", title: "System Architecture", icon: "\u{1F4CB}", required: true },
+            { name: "critical-state.md", title: "Critical State", icon: "\u{1F3D7}\uFE0F", required: false },
+            { name: "installation.md", title: "Installation", icon: "\u{1F3D7}\uFE0F", required: false },
+            { name: "api-schema.md", title: "API Schema", icon: "\u{1F3D7}\uFE0F", required: false },
+            { name: "auto-read-system.md", title: "Auto-Read System", icon: "\u{1F3D7}\uFE0F", required: false }
+          ]
+        },
+        {
+          name: "sop",
+          priority: 2,
+          files: [
+            { name: "git-workflow.md", title: "Git Workflow SOP", icon: "\u{1F527}", required: true },
+            { name: "release-management.md", title: "Release Management SOP", icon: "\u{1F4D6}", required: false },
+            { name: "automation-protection.md", title: "Automation Protection SOP", icon: "\u{1F4D6}", required: false },
+            { name: "npm-publishing-troubleshooting.md", title: "NPM Publishing Troubleshooting", icon: "\u{1F4D6}", required: false }
+          ]
         }
+      ];
+      if (config2?.customFolders) {
+        folders.push(...config2.customFolders);
       }
-      const systemDir = path7__default.join(".agent", "system");
-      if (fs__default.existsSync(systemDir)) {
-        const systemFiles = ["critical-state.md", "installation.md", "api-schema.md", "auto-read-system.md"];
-        for (const file of systemFiles) {
-          const filePath = path7__default.join(systemDir, file);
-          if (fs__default.existsSync(filePath)) {
+      folders.sort((a, b) => (a.priority || 999) - (b.priority || 999));
+      for (const folder of folders) {
+        const folderPath = path7__default.join(".agent", folder.name);
+        if (!fs__default.existsSync(folderPath)) {
+          continue;
+        }
+        for (const file of folder.files) {
+          let filePaths = [];
+          if (file.pattern) {
+            continue;
+          } else {
+            filePaths = [file.name];
+          }
+          for (const fileName of filePaths) {
+            const filePath = path7__default.join(folderPath, fileName);
+            if (!fs__default.existsSync(filePath)) {
+              if (file.required) ;
+              continue;
+            }
             try {
               const content = fs__default.readFileSync(filePath, "utf8");
-              const title = file.replace(".md", "").replace("-", " ").toUpperCase();
+              const displayTitle = file.title || fileName.replace(".md", "").replace("-", " ").toUpperCase();
+              const icon = file.icon || "\u{1F4C4}";
               initialMessages.push({
                 type: "assistant",
-                content: `\u{1F3D7}\uFE0F **${title} (from .agent/system/${file})**
+                content: `${icon} **${displayTitle} (from .agent/${folder.name}/${fileName})**
 
 ${content}`,
                 timestamp: /* @__PURE__ */ new Date()
@@ -18393,7 +18398,7 @@ ${content}`,
           }
         }
       }
-      if (docsRead > 0) {
+      if (showSummaryMessage && docsRead > 0) {
         initialMessages.push({
           type: "assistant",
           content: `\u2705 ${docsRead} documentation files read - I have a complete understanding of the current architecture and operational procedures.`,