cognitive-kit 1.0.0-alpha.2 → 1.0.0-alpha.4

package/docs/guides/antigravity-integration.md

@@ -0,0 +1,348 @@
+# Antigravity Integration Guide
+
+Integrate `cognitive-kit` (31+ MCP tools) into the **Antigravity AI Agent** framework to extend its cognitive capabilities — reasoning, research, planning, security, knowledge, agency orchestration, and adaptive pipelines.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│            ANTIGRAVITY AI AGENT               │
+│  .gemini/GEMINI.md  ←  Agent Rules            │
+│  C4IRS+S Roles     ←  Reasoning Cycles        │
+│  AR-Tier Personas  ←  Domain Specialization   │
+│                                               │
+│  ┌──────────────────────────────────────┐    │
+│  │        MCP CLIENT (built-in)         │    │
+│  └──────────┬───────────────────────────┘    │
+└─────────────┼────────────────────────────────┘
+              │ MCP stdio/SSE
+              ▼
+┌──────────────────────────────────────────────┐
+│             COGNITIVE KIT (MCP Server)        │
+│                                              │
+│  31 tools: cognitive_reason, cognitive_plan, │
+│  security_gate, ethics_audit, agency_execute, │
+│  guardian_status, skill_forge, federation...  │
+│                                              │
+│  Guardian Gate → Sovereignty + Firewall      │
+│  Agency Orch.  → Adaptive pipelines           │
+│  Skill Forging → Pattern → Skills            │
+│  Federation   → Multi-kit                    │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start (VS Code)
+
+### 1. Install the Kit
+
+```bash
+npm install -g cognitive-kit
+```
+
+### 2. Configure MCP in VS Code
+
+Create `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "cognitive-kit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_HOST_ID": "antigravity-${workspaceFolderBasename}",
+        "KIT_HOST_NAME": "${workspaceFolderBasename}",
+        "KIT_SOVEREIGN_KEY": ""
+      }
+    }
+  }
+}
+```
+
+### 3. Restart VS Code
+
+The kit's 31 tools appear in the MCP tool list. Antigravity can now invoke them via C4IRS cycles.
+
+---
+
+## Persona-to-Tool Mapping
+
+Map C4IRS+S roles and AR-tier personas to cognitive-kit tools for precise capability delegation.
+
+| C4IRS Role | AR Persona | cognitive-kit Tools |
+|------------|------------|-------------------|
+| **`[C]` Command** | AR-100 Architect | `cognitive_plan`, `cognitive_reason`, `consensus_engine` |
+| **`[C]` Control** | AR-200 Engineer | `execution_flow`, `swarm_orchestrator`, `subagent_protocol` |
+| **`[C]` Communications** | AR-300 Artisan | `cognitive_create`, `sentiment_adapter`, `context_synth` |
+| **`[I]` Intelligence** | AR-400 Oracle | `cognitive_research`, `knowledge_evolve`, `memory_vam` |
+| **`[R]` Reconnaissance** | AR-400 Oracle | `code_archaeologist`, `context_synth`, `threat_mapper` |
+| **`[S]` Surveillance** | AR-500 Operator | `guardian_status`, `state_guardian`, `integrity_ledger` |
+| **`[S]` Sovereignty** | AR-100 Architect | `guardian_freeze`, `guardian_unfreeze`, `integrity_ledger` |
+
+---
+
+## C4IRS Workflow Integration
+
+### `[C]` Command — Strategic Planning
+
+Instead of manual reasoning, delegate to the agency pipeline:
+
+```
+Antigravity: "Plan the authentication microservice"
+  → calls agency_execute(objective: "Design auth service", mode: "adaptive")
+  → Kit selects phases: [delimit, research, architect, security, validate]
+  → Kit assigns agents: [Strategist, Analyst, Architect, Guardian, Validator]
+  → Returns: mission plan with 5 phases, synergy score, sovereignty seal
+```
+
+### `[I]` Intelligence — Deep Research
+
+Use multi-perspective research:
+
+```
+Antigravity: "Research vector database options"
+  → calls cognitive_research(topic: "vector databases 2026", depth: "deep")
+  → Returns: analysis from architect, guardian, executor, strategic perspectives
+```
+
+### `[R]` Reconnaissance — Codebase Analysis
+
+Analyze project structure:
+
+```
+Antigravity: "Analyze the src/ directory structure"
+  → calls fs_list(path: "src")
+  → calls code_archaeologist(code: "<file content>", mode: "full")
+  → calls knowledge_evolve(knowledgeBase: "<analysis>", mode: "gap")
+```
+
+### `[S]` Surveillance — System Health
+
+Monitor the kit's operational state:
+
+```
+Antigravity: "Check system health"
+  → calls guardian_status()
+  → Returns: tool metrics, error rate, firewall stats, sovereignty chain
+```
+
+---
+
+## Prompt Injection (`.gemini/GEMINI.md`)
+
+Add these rules to your `.gemini/GEMINI.md` to enable cognitive-kit awareness:
+
+```markdown
+## 🧠 Cognitive Kit Integration (MCP)
+
+You have access to the Cognitive Kit MCP server with 31+ tools.
+
+### Available Tool Categories
+
+| Category | Tools | Use Case |
+|----------|-------|----------|
+| **Cognitive** | reason, research, plan, create, reflect | Core reasoning & analysis |
+| **Security** | gate, ethics, ledger, threat, redteam, blast | Security audits & threat modeling |
+| **Knowledge** | vam, evolve, synth | Memory & knowledge operations |
+| **Analysis** | code, sentiment, consensus, flow | Code review & process analysis |
+| **Agency** | swarm, meta, subagent, execute | Multi-agent orchestration |
+| **Guardian** | status, freeze, unfreeze | System monitoring & control |
+| **Federation** | status, connect, execute, disconnect | Multi-kit communication |
+| **Forge** | skill_forge, skill_list_forged | Auto-generate skills |
+
+### C4IRS Tool Delegation
+
+- Use `agency_execute` for complex multi-step tasks (replaces manual iteration)
+- Use `cognitive_reason` for logical analysis (replaces chain-of-thought)
+- Use `consensus_engine` for architectural decisions (replaces manual deliberation)
+- Use `threat_mapper` for risk assessment (replaces STRIDE manual analysis)
+- Use `guardian_status` before ANY destructive operation
+
+### Execution Protocol
+
+1. Before any action, call `guardian_status` to verify system health
+2. For complex tasks, call `agency_execute` with mode: "adaptive"
+3. For analysis, delegate to the appropriate cognitive tool
+4. After execution, call `integrity_ledger` to seal the operation
+5. Call `guardian_status` to verify post-operation state
+```
+
+---
+
+## Antigravity Autorun Configuration
+
+Update your `.antigravity-autorun.njk` to start the kit automatically:
+
+```njk
+# Antigravity Autorun Configuration
+# Auto-enables CDP: true
+# Run always: true
+
+# Start Cognitive Kit MCP Server
+npx cognitive-kit &
+sleep 2
+echo "Cognitive Kit ready — 31 tools available"
+
+{% set languages = ["python", "go", "typescript"] %}
+{% for lang in languages %}
+- Enable {{ lang }} usage: true
+{% endfor %}
+```
+
+---
+
+## Using cognitive-kit as a Library (Embedded Mode)
+
+For deeper integration, embed cognitive-kit directly into Antigravity's runtime:
+
+```javascript
+// antigravity-cognitive.js
+import { CognitiveKit, FileSystemAdapter } from 'cognitive-kit';
+
+const kit = new CognitiveKit({
+  host: new FileSystemAdapter(process.cwd(), { allowWrite: true }),
+  storage: { type: 'sqlite', path: './.cognitive-kit.db' },
+  transport: { type: 'direct' }, // in-process, no MCP needed
+  sovereignty: {
+    hostId: 'antigravity-' + process.env.KIT_HOST_ID,
+    hostName: 'Antigravity Agent',
+  },
+});
+
+await kit.initialize();
+
+export default {
+  // Expose tools to Antigravity's reasoning engine
+  reason: (problem) => kit['toolRegistry'].execute('cognitive_reason', { problem }),
+  research: (topic) => kit['toolRegistry'].execute('cognitive_research', { topic }),
+  plan: (objective) => kit.executeAgency(objective, { mode: 'adaptive' }),
+  gate: (payload) => kit.guardian.guardianGate.executeTool('security_gate', { payload }, ctx),
+  status: () => kit.guardian.stateGuardian.getMetrics(),
+};
+```
+
+---
+
+## Federation: Antigravity + Other Systems
+
+Connect Antigravity to other kit instances (databases, CI/CD, etc.):
+
+```
+Antigravity (VS Code)
+  │ federation_connect("http://db-kit:4200")
+  │
+  ├── pg_schema → Explore database structure
+  ├── cognitive_reason → Analyze schema relationships
+  └── knowledge_evolve → Identify knowledge gaps
+```
+
+```json
+{
+  "servers": {
+    "cognitive-kit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_FEDERATION_PEERS": "http://localhost:4200"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tool Reference by Antigravity Workflow
+
+### W-201 Deep Research
+```
+cognitive_research(topic, depth: "deep", perspectives: "architect,guardian,executor,strategic")
+knowledge_evolve(knowledgeBase: "<findings>", mode: "gap")
+context_synth(sources: "<findings>", mode: "summarize")
+```
+
+### W-202 Chain Actions
+```
+agency_execute(objective, mode: "sequential")
+execution_flow(process, granularity: "fine")
+subagent_protocol(task, mode: "supervised")
+```
+
+### W-203 Semantic Embeddings
+```
+memory_vam(action: "search", query, namespace: "knowledge")
+knowledge_evolve(knowledgeBase: "<results>", mode: "connect")
+```
+
+### W-204 Context Orchestration
+```
+context_synth(sources: "<contexts>", mode: "merge")
+memory_vam(action: "store", content: "<synthesized>", namespace: "context")
+```
+
+### W-205 Criteria Enforcement
+```
+ethics_audit(subject: "<decision>")
+consensus_engine(proposal: "<decision>", model: "weighted")
+integrity_ledger(action: "create", payload: "<decision>")
+```
+
+---
+
+## Example: Antigravity + cognitive-kit Session
+
+```
+User: "Design and implement a secure file upload service"
+
+Antigravity:
+  [C] Command → agency_execute(objective: "Design file upload service", mode: "adaptive")
+  ← Returns: 6-phase plan [delimit, research, architect, security, validate, execute]
+
+  [I] Intelligence → cognitive_research(topic: "secure file upload patterns 2026", depth: "deep")
+  ← Returns: multi-perspective analysis
+
+  [C] Control → execution_flow(process: "Implement upload endpoint", granularity: "fine")
+  ← Returns: 8-step execution plan with dependencies
+
+  [S] Surveillance → security_gate(payload: "<implementation code>")
+  ← Returns: PASSED (no violations)
+
+  [S] Sovereignty → integrity_ledger(action: "create", payload: "Upload service v1 deployed")
+  ← Returns: signed ledger entry with seal
+
+  → Emits: Sovereign Audit Trace with completion status
+```
+
+---
+
+## Requirements
+
+- Node.js ≥ 20
+- VS Code (or any MCP-compatible editor)
+- `npx cognitive-kit` (auto-installs on first run)
+- `.vscode/mcp.json` configured (see Quick Start)
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| "Tool not found" | Ensure cognitive-kit is running (`npx cognitive-kit`) |
+| Connection refused | Restart VS Code after adding `mcp.json` |
+| Firewall blocked | Check `guardian_status` for blocked operations |
+| Federation timeout | Verify peer URL and port are correct |
+
+---
+
+## Related
+
+- [VS Code Integration Guide](./vscode-integration.md)
+- [Cursor Integration Guide](./cursor-integration.md)
+- [Claude Desktop Integration Guide](./claude-desktop-integration.md)
+- [Federation Multi-Kit Example](../examples/federation.md)
+- [Cognitive Kit README](../../README.md)

package/docs/guides/claude-desktop-integration.md

@@ -0,0 +1,71 @@
+# Claude Desktop Integration Guide
+
+Connect Cognitive Kit to Claude Desktop as an MCP tool server.
+
+## Setup
+
+### 1. Install the Kit
+
+```bash
+npm install -g cognitive-kit
+```
+
+### 2. Configure Claude Desktop
+
+Edit `claude_desktop_config.json` (located at `~/Library/Application Support/Claude/` on macOS, `%APPDATA%/Claude/` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "cognitive-kit": {
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_HOST_ID": "claude-desktop",
+        "KIT_HOST_NAME": "Claude Desktop",
+        "KIT_SOVEREIGN_KEY": ""
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+The kit's 31 tools become available to Claude.
+
+## Using with Claude
+
+Claude can now invoke cognitive tools directly in conversation:
+
+```
+User: "Analyze this business strategy using multiple frameworks"
+Claude: [calls cognitive_research, ethics_audit, consensus_engine]
+```
+
+### Example Prompts
+
+**Strategic Planning:**
+```
+Use agency_execute to plan the Q2 product roadmap
+with mode: "sequential" and include all 8 phases
+```
+
+**Code Review:**
+```
+Run code_archaeologist on my project's main module
+and then apply cognitive_reason to identify improvements
+```
+
+**Security Assessment:**
+```
+Execute threat_mapper on our architecture,
+then red_team for adversarial simulation,
+then guardian_status to verify protections
+```
+
+## Notes
+
+- Claude Desktop passes tool results back to the conversation
+- The kit runs as a child process — Claude handles lifecycle
+- Use `guardian_freeze` if you need to pause operations

package/docs/guides/cursor-integration.md

@@ -0,0 +1,64 @@
+# Cursor Integration Guide
+
+Connect Cognitive Kit to Cursor AI editor via MCP.
+
+## Setup
+
+### 1. Configure MCP in Cursor
+
+1. Open Cursor Settings
+2. Navigate to **Features → MCP**
+3. Click **+ Add New MCP Server**
+
+```
+Name: cognitive-kit
+Type: command
+Command: npx cognitive-kit
+```
+
+4. Add environment variables (optional):
+
+| Variable | Value |
+|----------|-------|
+| `KIT_HOST_ID` | `cursor-my-project` |
+| `KIT_HOST_NAME` | `My Project` |
+| `KIT_SOVEREIGN_KEY` | *(optional)* |
+
+### 2. Verify
+
+Run any tool from Cursor's MCP panel:
+
+```
+cognitive_reason({ problem: "Why is this function failing?" })
+```
+
+## Available Commands
+
+Via Cursor's AI chat:
+
+```
+Analyze this code using cognitive_reason:
+[code block]
+```
+
+```
+Plan the implementation using cognitive_plan:
+[requirements]
+```
+
+```
+Check for security issues using security_gate:
+[code/config]
+```
+
+```
+Research this topic using cognitive_research:
+[topic]
+```
+
+## Tips
+
+- Use `agency_execute` for complex multi-step tasks
+- Use `guardian_status` to monitor system health
+- Use `code_archaeologist` for codebase analysis
+- Use `consensus_engine` for architectural decisions

package/docs/guides/vscode-integration.md

@@ -0,0 +1,80 @@
+# VS Code Integration Guide
+
+Connect Cognitive Kit to VS Code via MCP for inline reasoning, code analysis, planning, and security auditing.
+
+## Setup
+
+### 1. Install the Kit
+
+```bash
+npm install -g cognitive-kit
+```
+
+### 2. Configure MCP
+
+Create or edit `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "cognitive-kit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_HOST_ID": "vscode-${workspaceFolderBasename}",
+        "KIT_HOST_NAME": "${workspaceFolderBasename}"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart VS Code
+
+The kit starts automatically. You can now use all 31 tools from the VS Code MCP interface.
+
+## VS Code Extension
+
+Alternatively, install the VS Code extension (if published):
+
+```bash
+code --install-extension cognitive-kit-vscode
+```
+
+The extension provides:
+
+- **`Cognitive Kit: Analyze Selection`** — Runs reasoning on selected code/text
+- **`Cognitive Kit: Reflect on Workspace`** — Meta-reflection on project state
+- **`Cognitive Kit: Show Status`** — Guardian metrics and tool counts
+
+## Example Workflows
+
+### Code Review
+
+1. Select a block of code
+2. Run `Cognitive Kit: Analyze Selection`
+3. The kit applies `cognitive_reason` for logical analysis
+4. Results appear in a new editor panel
+
+### Security Audit
+
+Via MCP, call:
+
+```
+security_gate(payload: "the code to inspect")
+ethics_audit(subject: "implementation decision")
+threat_mapper(systemDescription: "architecture overview")
+```
+
+### Project Planning
+
+```
+agency_execute(objective: "Design authentication module", mode: "adaptive")
+```
+
+## Requirements
+
+- VS Code ≥ 1.96
+- Node.js ≥ 20
+- Internet for first `npx` run

package/mcp.json

@@ -0,0 +1,50 @@
+{
+  "servers": {
+    "cognitive-kit": {
+      "name": "Cognitive Kit",
+      "description": "Pluggable cognitive layer — 31+ MCP tools for reasoning, research, planning, creativity, security, knowledge, analysis, agency orchestration, and adaptive pipelines",
+      "type": "stdio",
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_HOST_ID": "${workspaceFolderBasename}",
+        "KIT_HOST_NAME": "${workspaceFolderBasename}",
+        "KIT_SOVEREIGN_KEY": ""
+      },
+      "icon": "🧠",
+      "tools": [
+        "cognitive_reason",
+        "cognitive_research",
+        "cognitive_plan",
+        "cognitive_create",
+        "cognitive_reflect",
+        "security_gate",
+        "ethics_audit",
+        "integrity_ledger",
+        "threat_mapper",
+        "red_team",
+        "blast_radius",
+        "guardian_status",
+        "guardian_freeze",
+        "guardian_unfreeze",
+        "memory_vam",
+        "knowledge_evolve",
+        "context_synth",
+        "code_archaeologist",
+        "sentiment_adapter",
+        "consensus_engine",
+        "execution_flow",
+        "swarm_orchestrator",
+        "meta_orchestrator",
+        "subagent_protocol",
+        "agency_execute",
+        "skill_forge",
+        "skill_list_forged",
+        "federation_status",
+        "federation_connect",
+        "federation_execute",
+        "federation_disconnect"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-kit",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Pluggable cognitive layer — port of GCS v15.3 as an embeddable MCP cognitive kit. Provides reasoning, research, planning, creativity, reflection, security, knowledge, analysis, agency orchestration, and adaptive pipelines via MCP protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,11 +19,14 @@
     }
   },
   "bin": {
-    "cognitive-kit": "./dist/cli.js"
+    "cognitive-kit": "./cli.mjs"
   },
   "files": [
     "dist",
     "types",
+    "docs",
+    "cli.mjs",
+    "mcp.json",
     "README.md",
     "LICENSE"
   ],
@@ -33,7 +36,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc --watch -p tsconfig.json",
-    "test": "node --experimental-vm-modules --test dist/tests/",
+    "test": "node tests/mcp-test-all.mjs && node tests/guardian-test.mjs && node tests/forge-test.mjs && node tests/federation-test.mjs",
     "start": "node dist/cli.js",
     "prepublishOnly": "npm run build"
   },
@@ -42,13 +45,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/GaboBase/TODO-Cognitive.git",
-    "directory": "packages/cognitive-kit"
+    "url": "https://github.com/GaboBase/cognitive-kit.git"
   },
   "bugs": {
-    "url": "https://github.com/GaboBase/TODO-Cognitive/issues"
+    "url": "https://github.com/GaboBase/cognitive-kit/issues"
   },
-  "homepage": "https://github.com/GaboBase/TODO-Cognitive/tree/main/packages/cognitive-kit",
+  "homepage": "https://github.com/GaboBase/cognitive-kit",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -75,8 +77,12 @@
   "dependencies": {
     "sql.js": "^1.11.0"
   },
+  "optionalDependencies": {
+    "pg": "^8.14.0"
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/pg": "^8.20.0",
     "typescript": "^5.8.2"
   }
 }