@cleocode/cleo 2026.3.7 → 2026.3.11

package/README.md

@@ -1,4 +1,4 @@
-<p align="center">
+<p alis|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.3.11-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.3.10-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2025.3.10-|gn="center">
   <img src="docs/images/banner.png" alt="CLEO banner" width="900">
 </p>
 
@@ -11,7 +11,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/License-BSL%201.1-blue" alt="License: Business Source License 1.1">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-2026.2.9-blue.svg" alt="Version"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-2025.3.10-blue.svg" alt="Version"></a>
   <a href="docs/mintlify/developer/specifications/LLM-AGENT-FIRST.mdx"><img src="https://img.shields.io/badge/design-LLM--Agent--First-purple.svg" alt="LLM-Agent-First"></a>
   <a href="tests/"><img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests"></a>
 </p>
@@ -98,8 +98,8 @@ CLEO is composed of four interdependent systems:
 
 | State | What It Means |
 |------|----------------|
-| **Shipped** | TypeScript CLI + MCP server, SQLite storage (`tasks.db`), atomic operations, four-layer anti-hallucination, RCASD-IVTR+C lifecycle gates, session management, vectorless RAG (5 discovery methods), LAFS envelopes |
-| **Gated** | Dedicated `brain.db` (FTS5, vector, PageIndex), `nexus.db` (cross-project graph), knowledge graph with version chains, agent profiles, federated queries |
+| **Shipped** | TypeScript CLI + MCP server, SQLite storage (`tasks.db` + `brain.db`), atomic operations, four-layer anti-hallucination, RCASD-IVTR+C lifecycle gates, session management, 3-layer BRAIN retrieval (`brain.search/timeline/fetch`), BRAIN observe writes, NEXUS dispatch domain wiring (12 operations), LAFS envelopes |
+| **In Progress / Planned** | Embedding generation + vector similarity pipeline (`T5158`/`T5159`), PageIndex traversal/query API (`T5161`), reasoning/session integration (`T5153`), `nexus.db` migration from JSON registry, full claude-mem automation retirement hooks (`T5145`) |
 
 ### MCP Server
 
@@ -142,7 +142,7 @@ Or if installed globally (`npm install -g @cleocode/cleo`):
 
 Supports: Claude Code, Claude Desktop, Cursor, Gemini CLI, Kimi, Antigravity, Windsurf, Goose, OpenCode, VS Code, Zed, Codex
 
-- Canonical MCP contract: [`docs/mintlify/specs/MCP-SERVER-SPECIFICATION.md`](docs/mintlify/specs/MCP-SERVER-SPECIFICATION.md)
+- Canonical MCP contract: [`docs/specs/MCP-SERVER-SPECIFICATION.md`](docs/specs/MCP-SERVER-SPECIFICATION.md)
 - MCP source: [`src/mcp/`](src/mcp/) (gateways, domains, engine)
 - Operation matrix: `src/mcp/gateways/query.ts` and `src/mcp/gateways/mutate.ts`
 
@@ -153,7 +153,7 @@ Your AI agent gets two tools: `cleo_query` (read) and `cleo_mutate` (write). Eac
 ```bash
 # Read operations (never changes anything)
 cleo_query  domain=tasks   operation=find   params={"query": "auth"}
-cleo_query  domain=system  operation=dash
+cleo_query  domain=admin  operation=dash
 cleo_query  domain=tasks   operation=next
 
 # Write operations (creates or modifies data)
@@ -162,15 +162,15 @@ cleo_mutate domain=tasks   operation=complete params={"taskId": "T1234", "notes"
 cleo_mutate domain=issues  operation=add.bug  params={"title": "...", "body": "...", "dryRun": true}
 ```
 
-10 canonical domains, 177 operations (97 query + 80 mutate) across tasks, sessions, memory, check, pipeline, orchestration, tools, admin, nexus, and sharing. See the [MCP Usage Guide](docs/guides/mcp-usage-guide.mdx) for beginner-friendly walkthroughs.
+10 canonical domains, 198 operations (110 query + 88 mutate) across tasks, sessions, memory, check, pipeline, orchestration, tools, admin, nexus, and sharing. See the [MCP Usage Guide](docs/guides/mcp-usage-guide.mdx) for beginner-friendly walkthroughs.
 
 ### Source of Truth Hierarchy
 
 1. [`docs/concepts/vision.md`](docs/concepts/vision.md) - immutable product vision
-2. [`docs/mintlify/specs/PORTABLE-BRAIN-SPEC.md`](docs/mintlify/specs/PORTABLE-BRAIN-SPEC.md) - canonical normative contract
+2. [`docs/specs/PORTABLE-BRAIN-SPEC.md`](docs/specs/PORTABLE-BRAIN-SPEC.md) - canonical normative contract
 3. [`README.md`](README.md) - operational public contract
-4. [`docs/mintlify/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md`](docs/mintlify/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md) - phased execution plan
-5. [`docs/mintlify/specs/CLEO-BRAIN-SPECIFICATION.md`](docs/mintlify/specs/CLEO-BRAIN-SPECIFICATION.md) - detailed capability model
+4. [`docs/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md`](docs/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md) - phased execution plan
+5. [`docs/specs/CLEO-BRAIN-SPECIFICATION.md`](docs/specs/CLEO-BRAIN-SPECIFICATION.md) - detailed capability model
 
 ---
 
@@ -204,7 +204,7 @@ cleo list | jq '.tasks[0].id'          # Parse with jq
 # Human-readable when you need it (developer-friendly)
 cleo list --human                      # Formatted text output
 
-# Exit codes for programmatic branching (17 documented codes)
+# Exit codes for programmatic branching (82 unique codes across 13 ranges)
 cleo exists T042 --quiet && echo "Found"
 ```
 
@@ -269,36 +269,36 @@ cleo-dev env info --json
 
 ### TL;DR - Just Install It
 
-**Option 1: One-liner (Easiest)**
+**Option 1: NPM (Recommended)**
 
 ```bash
-curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
-
-# Reinstalling over existing installation? Use --force:
-curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --force
+npm install -g @cleocode/cleo
 ```
 
-**Option 2: Download and Run**
+This automatically bootstraps the global CLEO system:
+- Sets up `~/.cleo/` with templates and configuration
+- Installs MCP server to detected AI providers (Claude Code, Cursor, etc.)
+- Creates `~/.agents/AGENTS.md` hub for agent instructions
 
-<p align="center">
-  <a href="https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh">
-    <img src="https://img.shields.io/badge/Download-install.sh-brightgreen?style=for-the-badge&logo=github" alt="Download install.sh">
-  </a>
-</p>
+Then initialize in any project:
+```bash
+cd /path/to/your/project && cleo init
+```
+
+**Option 2: One-liner Bash (Legacy/Offline)**
 
-After downloading, open Terminal and run:
+For systems without npm or offline installs:
 ```bash
-# macOS/Linux: Run with bash (no chmod needed)
-bash ~/Downloads/install.sh
+curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
 ```
 
-**Option 3: From source (for contributors)**
+**Option 3: From source (Contributors)**
 
 ```bash
 git clone https://github.com/kryptobaseddev/cleo.git && cd cleo && ./installer/install.sh --dev
 ```
 
-Then initialize in your project:
+Then use `cleo-dev` for isolated development:
 ```bash
 cd /path/to/your/project && cleo-dev init
 ```
@@ -327,25 +327,43 @@ cd /path/to/your/project && cleo-dev init
 <details>
 <summary><strong>Detailed Installation Options</strong></summary>
 
-#### Download from Releases (Recommended for Users)
+#### NPM Install (Recommended for Users)
+
+The NPM package auto-bootstraps the global CLEO system on install:
+
+```bash
+# Install from npm registry
+npm install -g @cleocode/cleo
+
+# Or install specific version
+npm install -g @cleocode/cleo@2026.3.10
+```
+
+What happens during install:
+1. Creates `~/.cleo/` directory structure
+2. Installs global templates (`CLEO-INJECTION.md`)
+3. Detects AI providers and installs MCP server configs
+4. Creates `~/.agents/AGENTS.md` hub
 
-1. Go to [Releases](https://github.com/kryptobaseddev/cleo/releases/latest)
-2. Download `cleo-X.Y.Z.tar.gz`
-3. Extract and install:
-   ```bash
-   tar xzf cleo-*.tar.gz
-   cd cleo-*
-   ./installer/install.sh
-   ```
+#### Initialize in Your Project
 
-#### One-liner Install (for Developers)
+After global install, initialize each project:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/cleo/main/install.sh | bash
+cd /path/to/your/project
+cleo init
 ```
 
+This creates only the local project structure:
+- `./.cleo/` directory with `config.json` and `tasks.db`
+- Registers project with NEXUS
+- Sets up git hooks
+- Injects CLEO references into local `AGENTS.md`
+
 #### From Source (for Contributors)
 
+For CLEO development or testing unreleased changes:
+
 ```bash
 # Clone repository
 git clone https://github.com/kryptobaseddev/cleo.git
@@ -356,38 +374,37 @@ cd cleo
 
 # Verify isolated runtime
 cleo-dev env info --json
-
-# Or install as release (copies files)
-./installer/install.sh --release
 ```
 
-`npm link` caveat: raw `npm link` follows package bin mappings and can expose `cleo`/`ct`. Use `./installer/install.sh --dev` when you need strict `cleo-dev` isolation.
-
-#### Verify Installation
+The dev channel uses:
+- Isolated commands: `cleo-dev` (no `ct` alias)
+- Isolated home: `~/.cleo-dev/`
+- Symlinks to repo for rapid iteration
 
-```bash
-cleo version
-cleo env info --json
-```
+`npm link` caveat: raw `npm link` follows package bin mappings and can expose `cleo`/`ct`. Use `./installer/install.sh --dev` when you need strict `cleo-dev` isolation.
 
-Provider alias/config utilities are managed by CAAMP.
+#### Legacy Bash Installer (Offline/Restricted Systems)
 
-#### Initialize in Your Project
+For systems without npm access:
 
 ```bash
-cd /path/to/your/project
-cleo init
+# One-liner install
+curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
+
+# Or download and run manually
+bash install.sh
 ```
 
-For contributor dev channel:
+This copies files (not symlinks) and provides the same functionality as npm install.
+
+#### Verify Installation
 
 ```bash
-cd /path/to/your/project
-cleo-dev init
+cleo version
+cleo env info --json
+cleo doctor
 ```
 
-> **Note**: The installer creates symlinks in `~/.local/bin/`, which works immediately with Claude Code and most modern shells.
-
 </details>
 
 <details>
@@ -516,7 +533,7 @@ cleo start <TAB>             # Shows pending/active task IDs
 <details>
 <summary><h2>Command Reference</h2></summary>
 
-### 48 Commands Across 5 Categories
+### 86 Commands Across 5 Categories
 
 | Category | Commands | Purpose |
 |----------|----------|---------|
@@ -772,7 +789,7 @@ cleo list --format text      # Same as --human
 
 ### Exit Codes
 
-17 documented exit codes for programmatic handling:
+82 unique exit codes across 13 ranges for programmatic handling:
 
 | Range | Purpose | Examples |
 |-------|---------|----------|
@@ -912,17 +929,17 @@ CLEO_FORMAT=json              # Force output format
 ~/.cleo/                     # Global installation
 ├── nexus.db                 # Cross-project network: registry, graph, permissions (gated)
 ├── config.json              # Global CLEO configuration
-├── skills/                  # Modular agent skills (14 skills)
+├── skills/                  # Modular agent skills (15 skills)
 │   ├── manifest.json        # Skill registry with versions
 │   ├── ct-epic-architect/   # Epic creation skill
 │   ├── ct-orchestrator/     # Workflow coordination
-│   └── ...                  # 12 more skills
+│   └── ...                  # 13 more skills
 ├── templates/               # Starter templates
 └── docs/                    # Documentation
 
 your-project/.cleo/          # Per-project instance
 ├── tasks.db                 # Project work: tasks, sessions, lifecycle, audit (SQLite)
-├── brain.db                 # Memory & cognition: observations, patterns, learnings (gated)
+├── brain.db                 # Memory & cognition: observations, patterns, learnings, decisions, links (shipped)
 ├── config.json              # Runtime settings: policies, validation, session behavior
 ├── project-info.json        # Project identity: projectHash, schema versions, health
 ├── project-context.json     # LLM agent metadata: language, framework, conventions
@@ -1030,7 +1047,7 @@ CLEO uses a **2-tier subagent architecture** for multi-agent coordination:
 
 > **Architecture Reference**: See [CLEO-SUBAGENT.md](docs/architecture/CLEO-SUBAGENT.md) for complete documentation.
 
-CLEO includes 14 modular skills for AI agent workflows:
+CLEO includes 15 modular skills for AI agent workflows:
 
 ### Token Injection System (v0.60.0+)
 
@@ -1045,21 +1062,17 @@ The token injection system provides validated placeholder replacement for skill
 
 Token validation prevents hallucinated or malformed values from reaching skill templates.
 
-### Orchestrator Automation (v0.60.0+)
-
-The `orchestrator_spawn_for_task()` function consolidates subagent spawning into a single call:
+### Orchestrator Automation
 
-```bash
-# Programmatic spawning (from lib/orchestrator-spawn.sh)
-source lib/orchestrator-spawn.sh
-prompt=$(orchestrator_spawn_for_task "T1234")              # Default protocol
-prompt=$(orchestrator_spawn_for_task "T1234" "ct-research-agent")  # Specific protocol
+Subagent spawning is handled via the MCP orchestration domain:
 
-# NOTE: All spawns use subagent_type: "cleo-subagent"
-# The second argument selects the protocol to inject, not a separate agent type
+```
+# Spawn a subagent for a task (via MCP)
+cleo_mutate orchestrate.spawn { taskId: "T1234" }
+cleo_mutate orchestrate.spawn { taskId: "T1234", skill: "ct-research-agent" }
 ```
 
-Automates: task validation, context loading, token injection, template rendering, and prompt generation.
+The spawn pipeline (implemented in `src/core/skills/orchestrator/spawn.ts`) automates: task validation, context loading, token injection, template rendering, and prompt generation.
 
 ### Installed Skills (Protocol Identifiers)
 
@@ -1067,20 +1080,21 @@ Automates: task validation, context loading, token injection, template rendering
 
 | Skill Protocol | Purpose |
 |----------------|---------|
-| `ct-epic-architect` | Create epics with task decomposition |
-| `ct-orchestrator` | Multi-agent workflow coordination |
+| `ct-cleo` | Core CLEO protocol and session management |
+| `ct-contribution` | Contribution workflow protocol |
+| `ct-dev-workflow` | Developer workflow automation |
 | `ct-docs-lookup` | Documentation search via Context7 |
-| `ct-docs-write` | Documentation generation |
 | `ct-docs-review` | Documentation compliance review |
+| `ct-docs-write` | Documentation generation |
+| `ct-documentor` | Documentation orchestration |
+| `ct-epic-architect` | Create epics with task decomposition |
+| `ct-grade` | Quality grading and assessment |
+| `ct-orchestrator` | Multi-agent workflow coordination |
 | `ct-research-agent` | Multi-source research protocol |
-| `ct-task-executor` | Generic task execution protocol |
+| `ct-skill-creator` | Create new skills |
 | `ct-spec-writer` | Technical specification writing |
-| `ct-test-writer-bats` | BATS test generation |
+| `ct-task-executor` | Generic task execution protocol |
 | `ct-validator` | Compliance validation |
-| `ct-skill-creator` | Create new skills |
-| `ct-skill-lookup` | Search prompts.chat skills |
-| `ct-library-implementer-bash` | Bash library creation |
-| `ct-documentor` | Documentation orchestration |
 
 ### Skills Installation
 
@@ -1176,7 +1190,7 @@ See [docs/PLUGINS.md](docs/PLUGINS.md) for extension development.
 | Problem | Solution |
 |---------|----------|
 | `command not found` | Check `~/.local/bin` in PATH, run `source ~/.bashrc` |
-| `Permission denied` | `chmod 755 ~/.cleo/scripts/*.sh` |
+| `Permission denied` | Check `~/.local/bin` permissions, ensure CLEO binaries are executable |
 | `Invalid JSON` | `cleo validate --fix` or `cleo restore` |
 | `Duplicate ID` | `cleo validate --fix` or `cleo restore` |
 | `Checksum mismatch` | `cleo validate --fix` |

package/bin/postinstall.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * NPM Postinstall Hook - Bootstrap Global CLEO System
+ * 
+ * This script runs automatically after `npm install -g @cleocode/cleo`.
+ * It bootstraps the global CLEO system:
+ *   - Creates ~/.cleo/ directory structure
+ *   - Installs global templates (CLEO-INJECTION.md)
+ *   - Sets up CAAMP provider configs
+ *   - Installs MCP server to detected providers
+ *   - Creates ~/.agents/AGENTS.md hub
+ * 
+ * This is the ONLY place global setup should happen. Project `cleo init`
+ * only creates local ./.cleo/ and registers with NEXUS.
+ * 
+ * @task T5267
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, readFile, copyFile } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Determine if we're running from npm global install or local dev
+function isNpmGlobalInstall() {
+  const execPath = process.argv[1] || '';
+  // Check if running from node_modules/@cleocode/cleo/
+  return execPath.includes('node_modules/@cleocode/cleo/') || 
+         execPath.includes('node_modules\\@cleocode\\cleo\\');
+}
+
+// Get package root
+function getPackageRoot() {
+  // When running from bin/, go up to package root
+  return resolve(__dirname, '..');
+}
+
+async function bootstrapGlobalCleo() {
+  // Only run for npm global installs, not local dev or other contexts
+  if (!isNpmGlobalInstall()) {
+    console.log('CLEO: Skipping global bootstrap (not npm global install)');
+    return;
+  }
+
+  console.log('CLEO: Bootstrapping global system...');
+
+  const cleoHome = join(homedir(), '.cleo');
+  const globalTemplatesDir = join(cleoHome, 'templates');
+  const globalAgentsDir = join(homedir(), '.agents');
+
+  // Create directories
+  await mkdir(globalTemplatesDir, { recursive: true });
+  await mkdir(globalAgentsDir, { recursive: true });
+
+  // Copy CLEO-INJECTION.md template
+  const packageRoot = getPackageRoot();
+  const templateSource = join(packageRoot, 'templates', 'CLEO-INJECTION.md');
+  const templateDest = join(globalTemplatesDir, 'CLEO-INJECTION.md');
+
+  if (existsSync(templateSource)) {
+    await copyFile(templateSource, templateDest);
+    console.log('CLEO: Installed global template (CLEO-INJECTION.md)');
+  }
+
+  // Setup CAAMP and MCP (these may fail gracefully if CAAMP isn't fully configured yet)
+  try {
+    const { getInstalledProviders, inject, buildInjectionContent } = await import('@cleocode/caamp');
+    
+    // Create ~/.agents/AGENTS.md with CLEO block
+    const globalAgentsMd = join(globalAgentsDir, 'AGENTS.md');
+    let agentsContent = '';
+    
+    if (existsSync(globalAgentsMd)) {
+      agentsContent = await readFile(globalAgentsMd, 'utf-8');
+      // Strip old CLEO blocks
+      agentsContent = agentsContent.replace(/\n?<!-- CLEO:START -->[\s\S]*?<!-- CLEO:END -->\n?/g, '');
+    }
+
+    // Inject CLEO reference
+    await inject(globalAgentsMd, '@~/.cleo/templates/CLEO-INJECTION.md');
+    console.log('CLEO: Updated ~/.agents/AGENTS.md');
+
+    // Install MCP server to detected providers
+    const providers = getInstalledProviders();
+    if (providers.length > 0) {
+      const { generateMcpServerEntry, getMcpServerName } = await import('../dist/core/mcp/index.js');
+      const { installMcpServerToAll } = await import('@cleocode/caamp');
+      
+      // Detect environment (stable/beta/dev)
+      const env = generateMcpServerEntry.length === 1 
+        ? { mode: 'stable', source: 'npm' }
+        : { mode: 'stable', source: 'npm' };
+      
+      const serverEntry = generateMcpServerEntry(env);
+      const serverName = getMcpServerName(env);
+      
+      await installMcpServerToAll(providers, serverName, serverEntry, 'global', process.cwd());
+      console.log(`CLEO: Installed MCP server to ${providers.length} provider(s)`);
+    }
+  } catch (err) {
+    // CAAMP/MCP setup is optional at install time - will be set up on first use
+    console.log('CLEO: CAAMP/MCP setup deferred (will complete on first use)');
+  }
+
+  console.log('CLEO: Global bootstrap complete!');
+  console.log('CLEO: Run "cleo init" in any project to set up local CLEO.');
+}
+
+// Run bootstrap
+bootstrapGlobalCleo().catch(err => {
+  console.error('CLEO: Bootstrap error (non-fatal):', err.message);
+  process.exit(0); // Never fail npm install
+});