@cleocode/core 2026.3.53 → 2026.3.55

package/dist/paths.d.ts

@@ -145,6 +145,17 @@ export declare function getCleoTempDir(): string;
  * Linux: ~/.config/cleo | macOS: ~/Library/Preferences/cleo | Windows: %APPDATA%\cleo\Config
  */
 export declare function getCleoConfigDir(): string;
+/**
+ * Get the CLEO templates directory as a tilde-prefixed path for use
+ * in `@` references (AGENTS.md, CLAUDE.md, etc.). Cross-platform:
+ * replaces the user's home directory with `~` so the reference works
+ * when loaded by LLM providers that resolve `~` at runtime.
+ *
+ * Linux:   ~/.local/share/cleo/templates
+ * macOS:   ~/Library/Application Support/cleo/templates
+ * Windows: ~/AppData/Local/cleo/Data/templates (approximate)
+ */
+export declare function getCleoTemplatesTildePath(): string;
 /**
  * Get the global agents hub directory.
  * Respects AGENTS_HOME env var, defaults to ~/.agents.

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAIlE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASnD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAS7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAgCvD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAmBpD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3D;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQpD;AAMD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAMD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAIlE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASnD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAS7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAgCvD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAmBpD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3D;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQpD;AAMD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAOlD;AAMD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.53",
+  "version": "2026.3.55",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,10 +36,10 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.3.53",
-    "@cleocode/contracts": "2026.3.53",
-    "@cleocode/agents": "2026.3.53",
-    "@cleocode/skills": "2026.3.53"
+    "@cleocode/adapters": "2026.3.55",
+    "@cleocode/agents": "2026.3.55",
+    "@cleocode/contracts": "2026.3.55",
+    "@cleocode/skills": "2026.3.55"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/__tests__/injection-mvi-tiers.test.ts

@@ -50,18 +50,18 @@ describe('CLEO-INJECTION v2.1.0 minimal-only template', () => {
 
     it('includes Mandatory Efficiency Sequence', () => {
       expect(content).toContain('## Mandatory Efficiency Sequence');
-      expect(content).toContain('query session status');
-      expect(content).toContain('query admin dash');
-      expect(content).toContain('query tasks current');
-      expect(content).toContain('query tasks next');
-      expect(content).toContain('query tasks show');
+      expect(content).toContain('cleo session status');
+      expect(content).toContain('cleo dash');
+      expect(content).toContain('cleo current');
+      expect(content).toContain('cleo next');
+      expect(content).toContain('cleo show');
     });
 
     it('includes Agent Work Loop', () => {
       expect(content).toContain('## Agent Work Loop');
-      expect(content).toContain('tasks current');
-      expect(content).toContain('tasks complete');
-      expect(content).toContain('tasks next');
+      expect(content).toContain('cleo current');
+      expect(content).toContain('cleo complete');
+      expect(content).toContain('cleo next');
     });
 
     it('includes Context Ethics', () => {
@@ -173,9 +173,9 @@ describe('CLEO-INJECTION v2.1.0 minimal-only template', () => {
   });
 
   describe('Template size', () => {
-    it('is under 120 lines', () => {
+    it('is under 160 lines', () => {
       const lines = content.split('\n').length;
-      expect(lines).toBeLessThan(130);
+      expect(lines).toBeLessThan(160);
     });
 
     it('is at least 60 lines (not accidentally empty)', () => {

package/src/bootstrap.ts

@@ -15,7 +15,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { getAgentsHome, getCleoTemplatesDir } from './paths.js';
+import { getAgentsHome, getCleoTemplatesDir, getCleoTemplatesTildePath } from './paths.js';
 import { ensureGlobalHome, getPackageRoot } from './scaffold.js';
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -155,8 +155,8 @@ async function injectAgentsHub(ctx: BootstrapContext): Promise<void> {
       }
 
       // CAAMP 1.8.1: inject() is idempotent AND consolidates duplicates
-      const expectedContent = '@~/.cleo/templates/CLEO-INJECTION.md';
-      const action = await inject(globalAgentsMd, expectedContent);
+      const templateRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+      const action = await inject(globalAgentsMd, templateRef);
       ctx.created.push(`~/.agents/AGENTS.md (${action})`);
     } else {
       ctx.created.push('~/.agents/AGENTS.md (would create/update CAAMP block)');

package/src/injection.ts

@@ -19,7 +19,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
-import { getAgentsHome, getCleoHome } from './paths.js';
+import { getAgentsHome, getCleoHome, getCleoTemplatesTildePath } from './paths.js';
 import { getPackageRoot, stripCLEOBlocks } from './scaffold.js';
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -169,7 +169,7 @@ export async function ensureInjection(projectRoot: string): Promise<ScaffoldResu
   try {
     const globalAgentsDir = getAgentsHome();
     const globalAgentsMd = join(globalAgentsDir, 'AGENTS.md');
-    const globalHubContent = '@~/.cleo/templates/CLEO-INJECTION.md';
+    const globalHubContent = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
     await mkdir(globalAgentsDir, { recursive: true });
     // Direct call — CAAMP 1.8.0 handles idempotency
     await inject(globalAgentsMd, globalHubContent);

package/src/paths.ts

@@ -322,6 +322,25 @@ export function getCleoConfigDir(): string {
   return getPlatformPaths().config;
 }
 
+/**
+ * Get the CLEO templates directory as a tilde-prefixed path for use
+ * in `@` references (AGENTS.md, CLAUDE.md, etc.). Cross-platform:
+ * replaces the user's home directory with `~` so the reference works
+ * when loaded by LLM providers that resolve `~` at runtime.
+ *
+ * Linux:   ~/.local/share/cleo/templates
+ * macOS:   ~/Library/Application Support/cleo/templates
+ * Windows: ~/AppData/Local/cleo/Data/templates (approximate)
+ */
+export function getCleoTemplatesTildePath(): string {
+  const absPath = getCleoTemplatesDir();
+  const home = homedir();
+  if (absPath.startsWith(home)) {
+    return `~${absPath.slice(home.length)}`;
+  }
+  return absPath;
+}
+
 // ============================================================================
 // Third-Party Tool Paths (OS-aware)
 // ============================================================================

package/templates/CLEO-INJECTION.md

@@ -3,29 +3,53 @@
 Version: 2.1.0
 Status: ACTIVE
 
+## Runtime Environment
+
+<!-- CleoOS injects CLEO_RUNTIME=cleoos when launching agents from a workspace -->
+<!-- When this variable is absent, assume standalone CLI mode -->
+
+**Mode**: `${CLEO_RUNTIME:-standalone}`
+
+### Channel Preference
+
+| Runtime | Primary Channel | Fallback | Rationale |
+|---------|----------------|----------|-----------|
+| `standalone` | CLI (`cleo <command>`) | MCP (query/mutate) | CLI is cheaper (fewer tokens), more reliable, and baked into core |
+| `cleoos` | Workspace-provided | CLI | CleoOS workspace manages channel routing via capability matrix |
+
+When running in **standalone** mode (the default):
+- Prefer CLI commands over MCP tool calls for all CLEO operations
+- CLI commands are shorter, use fewer tokens, and bypass the MCP dispatch layer
+- Use MCP only when the provider does not support shell execution
+
+When running in **CleoOS** mode:
+- Follow the workspace-provided channel routing preferences
+- CleoOS manages the capability matrix and optimal channel selection
+- This mode is a work-in-progress — fall back to CLI if unsure
+
 ## CLEO Identity
 
-You are a CLEO protocol agent. Use MCP-first operations:
-- `query` for reads
-- `mutate` for writes
+You are a CLEO protocol agent. CLEO operations are available via CLI (primary) and MCP (fallback):
+- CLI: `cleo <command> [args]` — preferred for token efficiency (flat commands, not domain-prefixed)
+- MCP: `query`/`mutate` gateways with `{domain, operation, params}` — use when CLI is unavailable
 
 ## Mandatory Efficiency Sequence
 
 Run cheapest-first at session start:
-1. `query session status` — resume existing? (~200 tokens)
-2. `query admin dash` — project overview (~500 tokens)
-3. `query tasks current` — active task? (~100 tokens)
-4. `query tasks next` — what to work on (~300 tokens)
-5. `query tasks show` — full details for chosen task (~400 tokens)
+1. `cleo session status` — resume existing? (~200 tokens)
+2. `cleo dash` — project overview (~500 tokens)
+3. `cleo current` — active task? (~100 tokens)
+4. `cleo next` — what to work on (~300 tokens)
+5. `cleo show {id}` — full details for chosen task (~400 tokens)
 
 ## Agent Work Loop
 
 Repeat until session ends:
-1. `tasks current` or `tasks next` → pick task
-2. `tasks show {id}` → read requirements
+1. `cleo current` or `cleo next` → pick task
+2. `cleo show {id}` → read requirements
 3. Do the work (code, test, document)
-4. `tasks complete {id}` → mark done
-5. `tasks next` → continue or end session
+4. `cleo complete {id}` → mark done
+5. `cleo next` → continue or end session
 
 ## Context Ethics
 
@@ -61,12 +85,12 @@ Agents MUST NOT provide hours/days/week estimates. Use `small`, `medium`, `large
 
 ## Session Quick Reference
 
-| Goal | Operation | Gateway |
-|------|-----------|---------|
-| Check active session | `session status` | query |
-| Resume context from last session | `session handoff.show` | query |
-| Start working | `session start` (scope required) | mutate |
-| Stop working | `session end` | mutate |
+| Goal | CLI (Primary) | MCP (Fallback) |
+|------|--------------|----------------|
+| Check active session | `cleo session status` | `query session status` |
+| Resume context | `cleo briefing` | `query session briefing.show` |
+| Start working | `cleo session start --scope global` | `mutate session start {scope: "global"}` |
+| Stop working | `cleo session end` | `mutate session end` |
 
 For advanced session ops (find, suspend, resume, debrief, decisions): see `.cleo/agent-outputs/T5124-session-decision-tree.md`
 
@@ -78,23 +102,23 @@ CLEO includes a native BRAIN memory system. Use the 3-layer retrieval pattern fo
 
 | Step | Operation | Gateway | ~Tokens | Purpose |
 |------|-----------|---------|---------|---------|
-| 1 | `memory brain.search` | query | 50/hit | Search index (IDs + titles) |
-| 2 | `memory brain.timeline` | query | 200-500 | Context around an anchor ID |
-| 3 | `memory brain.fetch` | query | 500/entry | Full details for filtered IDs |
-| Save | `memory brain.observe` | mutate | — | Save observation to brain.db |
+| 1 | `memory find` | query | 50/hit | Search index (IDs + titles) |
+| 2 | `memory timeline` | query | 200-500 | Context around an anchor ID |
+| 3 | `memory fetch` | query | 500/entry | Full details for filtered IDs |
+| Save | `memory observe` | mutate | — | Save observation to brain.db |
 
 **Workflow**: Search first (cheap) → filter interesting IDs → fetch only what you need.
 
-**Example**:
+**Example** (CLI):
 ```
-query memory brain.search {query: "authentication"}
-query memory brain.fetch {ids: ["O-abc123"]}
-mutate memory brain.observe {text: "Found auth uses JWT", title: "Auth discovery"}
+cleo memory find "authentication"
+cleo memory fetch O-abc123
+cleo observe "Found auth uses JWT" --title "Auth discovery"
 ```
 
 **Anti-patterns:**
 - Fetching all entries without searching first (expensive)
-- Skipping brain.search and going straight to brain.fetch
+- Skipping memory find and going straight to memory fetch
 
 ## Memory Bridge