@cleocode/cleo-os 2026.4.16 → 2026.4.18

package/README.md

@@ -0,0 +1,342 @@
+# CleoOS
+
+> The batteries-included agentic development environment.
+> One developer. Many agents. One operating system for the work.
+
+CleoOS wraps [Pi](https://github.com/mariozechner/pi) — Mario Zechner's
+open-source coding agent — with CLEO's governance layer: task memory,
+lifecycle gates, multi-agent coordination, and the CANT DSL. Install once,
+get both.
+
+## Quick Start
+
+```bash
+npm install -g @cleocode/cleo-os
+cleoos
+```
+
+That's it. CleoOS installs Pi automatically. The `cleoos` command launches
+Pi with CleoOS extensions pre-loaded. The `cleo` CLI is also available for
+task management, memory, and lifecycle operations.
+
+## If You're...
+
+| Goal | Start here |
+|---|---|
+| **New to AI coding agents** | [The Hearth](#the-hearth) — what you see when you run `cleoos` |
+| **Already using Pi** | [What CleoOS Adds](#what-cleoos-adds-to-pi) — the extensions Pi doesn't have |
+| **Comparing tools** | [Why CleoOS](#why-cleoos) — how it differs from Claude Code, Cursor, Copilot |
+
+---
+
+## Why CleoOS
+
+AI coding agents can write code. What they cannot do is sustain a project across days, agents,
+and context windows. Each session starts fresh, forgets last week's architectural decision,
+and has no idea which tasks are blocked or why. The result: impressive demos, fragile projects.
+
+CleoOS adds the missing layer. BRAIN persists memory across every session so agents never
+rediscover the same facts twice. The CANT DSL defines agent roles, permissions, and mental models
+in a checked-in file so governance is reproducible. The three-tier hierarchy gives leads the
+authority to coordinate without giving them the power to cause chaos, and gives workers a
+constrained domain where they can operate confidently.
+
+The key differentiator is enforcement. Many tools describe role hierarchies. CleoOS enforces
+them at the `tool_call` hook level inside Pi: lead agents literally cannot execute `Edit`,
+`Write`, or `Bash`, and worker agents cannot write outside their declared file paths. There is
+no workaround because the hook runs before Pi dispatches the tool call.
+
+Pi provides excellent single-agent coding capability — a well-designed TUI, solid model
+integration, and a stable extension API. CleoOS is not a competitor. It is the governance
+shell that makes Pi production-ready for multi-agent workflows.
+
+---
+
+## The Five Named Powers
+
+CleoOS is built on CLEO's five named powers. Each maps to a concrete runtime system:
+
+| Power | What It Does |
+|-------|-------------|
+| **CLEO** | Governs continuity, routing, and system action across all sessions |
+| **BRAIN** | Stores durable project knowledge — observations, decisions, patterns, learnings |
+| **LOOM** | Enforces order of operations through the RCASD-IVTR+C lifecycle |
+| **NEXUS** | Connects projects without merging them — cross-project registry |
+| **LAFS** | Standardizes outputs for tools and agents — progressive disclosure protocol |
+
+**CAAMP** is the provisioning ally: it equips the realm with provider configs, skills, and
+injected instructions. See the [CLEO World Map](../../docs/concepts/CLEO-WORLD-MAP.md) for
+the full narrative behind each power.
+
+---
+
+## The Hearth
+
+The Hearth is what you see when you run `cleoos`. It is Pi's terminal UI with CleoOS
+extensions loaded automatically:
+
+- **CANT bridge** — reads `.cleo/cant/*.cant` files and injects agent personas, tool ACLs,
+  and mental model preambles into the Pi session at startup. Compiles CANT DSL to system
+  prompt injection transparently.
+- **Chat room widget** — a below-editor panel that shows the last 15 inter-agent messages
+  in real time. Messages arrive from other agents in the current worktree via `conduit.db`
+  or `api.signaldock.io`. The chat room is a TUI view — it is not itself a messaging transport.
+- **Status line** — shows the current agent tier, role name, and active task context pulled
+  from BRAIN on spawn.
+
+The Hearth is the operator surface. Conduit is the agent relay below it.
+
+---
+
+## The Three-Tier Hierarchy
+
+The three-tier hierarchy is the headline feature of CleoOS. It brings structure to multi-agent
+projects by giving each tier distinct powers and hard constraints enforced at runtime.
+
+```
+Orchestrator (you, or /cleo:auto <epicId>)
+    │
+    ├── Engineering Lead (thinker, NEVER executes)
+    │   ├── backend-dev   (worker, writes code)
+    │   ├── frontend-dev  (worker, writes code)
+    │   └── qa-engineer   (worker, writes tests)
+    │
+    ├── Validation Lead
+    │   ├── security-reviewer (worker, audits)
+    │   └── doc-writer        (worker, writes docs)
+    │
+    └── Release Lead
+        └── release-manager   (worker, ships)
+```
+
+### Tier Capabilities
+
+| Tier | Role | Power | Hard Constraint |
+|------|------|-------|-----------------|
+| **Orchestrator** | Runs the Conductor Loop (`/cleo:auto <epicId>`) | Full system access | HITL boundary — user approves epic-level decisions |
+| **Lead** | Coordinates a worker group, reviews output, delegates | Read + think + delegate | CANNOT execute `Edit`, `Write`, or `Bash` — no exceptions |
+| **Worker** | Executes concrete code changes within a declared domain | Read + write within domain | Path ACL: `permissions.files: write[glob]` — cannot write outside glob |
+
+### Enforcement (shipped in Wave 7b)
+
+Enforcement runs at the Pi `tool_call` hook level. When a lead agent attempts to call
+`Edit`, `Write`, or `Bash`, the hook intercepts the call before Pi dispatches it and
+returns a rejection. When a worker agent attempts to write to a path outside its declared
+glob pattern, the same hook rejects the call. There is no workaround at the agent level.
+
+Teams are defined in `.cleo/teams.cant`:
+
+```cant
+team engineering-lead {
+  role: lead
+  workers: [backend-dev, frontend-dev, qa-engineer]
+}
+
+team backend-dev {
+  role: worker
+  permissions {
+    files { write ["packages/core/**", "packages/contracts/**"] }
+  }
+}
+```
+
+### Wave Status
+
+| Feature | Status |
+|---|---|
+| Lead tool blocking (`Edit`/`Write`/`Bash` rejected for `role: lead`) | Wave 7b shipped |
+| Worker path ACL (`permissions.files: write[glob]` enforced) | T422-T426 shipped |
+| `.cleo/teams.cant` definition format | Wave 0 shipped |
+| Model tier routing (low/mid/high per tier) | Grammar shipped, router in progress |
+| JIT agent composition (spawn team from task type) | Library exists, not wired to spawn path |
+
+---
+
+## Conduit — Agent Communication
+
+Conduit is CLEO's agent-to-agent communication layer, structured in four concentric shells.
+Each shell handles a different scope of agent communication.
+
+### Shell 1 — Pi Native (free, built-in)
+
+Orchestrator-to-lead-to-worker communication inside a single session. Pi handles
+parent/child relay automatically via its JSONL subagent-link. No CLEO infrastructure
+needed. Zero latency. Zero cost.
+
+### Shell 2 — conduit.db (shipped v2026.4.12)
+
+Per-project local messaging in SQLite at `.cleo/conduit.db`. Provides messages,
+conversations, delivery queue, and dead-letter handling. Used when agents communicate
+across sessions or hand off state between orchestrator runs on the same machine. Also
+holds `project_agent_refs` — per-project agent visibility overrides that layer on top of
+the global identity registry.
+
+### Shell 3 — signaldock.io Cloud (shipped)
+
+Cross-machine and cross-project agent coordination via the `signaldock-sdk` Rust crate
+against `api.signaldock.io`. Four services: AgentService, MessageService,
+ConversationService, DeliveryOrchestrator. TypeScript reaches the cloud tier via
+`HttpTransport` (polling) or `SseTransport` (real-time EventSource). Used when a fleet
+of agents spans multiple machines or CI environments.
+
+### Shell 4 — Durable Broker (planned)
+
+The CLEOOS-VISION message bus with Rust broker, TypeScript semantics, lease-based delivery,
+and dead-letter queue. Deferred until cross-worktree durability is required by real workflows.
+
+> **Note**: The Chat Room (`cleo-chatroom.ts`) is a TUI view under The Hearth, not a
+> Conduit shell. It gives the operator visibility into inter-agent messages. Messages
+> displayed in the chat room flow through `conduit.db` or `signaldock.io` — the chat room
+> itself is only a renderer.
+
+---
+
+## What CleoOS Adds to Pi
+
+| Capability | How | Source |
+|---|---|---|
+| **CANT bridge** | Injects agent personas from `.cleo/cant/*.cant` into Pi sessions at startup. Compiles CANT to system prompt injection. | `extensions/cleo-cant-bridge.ts` |
+| **Lead tool blocking** | `tool_call` hook rejects `Edit`/`Write`/`Bash` for `role: lead` agents | Wave 7b |
+| **Worker path ACL** | `tool_call` hook enforces `permissions.files: write[glob]` per worker | T422-T426 |
+| **Mental model injection** | Fetches prior observations from BRAIN on spawn, injects validate-on-load preamble | Wave 8 |
+| **Chat room TUI** | 4 inter-agent tools + below-editor widget showing last 15 messages | Wave 7 |
+| **XDG-compliant paths** | All CleoOS state under `~/.local/share/cleo/` (Linux), `~/Library/Application Support/cleo/` (macOS) | `src/xdg.ts` |
+| **Pi keystore redirect** | Pi credentials stored at `~/.config/cleo/auth/auth.json` instead of Pi's default | `src/keystore.ts` |
+| **Postinstall scaffolding** | Creates XDG dirs, deploys extensions, scaffolds `model-routing.cant` stub, installs CLEO skills | `src/postinstall.ts` |
+
+---
+
+## Database Topology
+
+CleoOS maintains five databases across two tiers per ADR-036 and ADR-037.
+
+### Project Tier (`.cleo/`)
+
+| Database | Purpose |
+|---|---|
+| `tasks.db` | Task hierarchy, sessions, audit log, lifecycle pipelines |
+| `brain.db` | Observations, patterns, learnings, decisions (FTS5 searchable) |
+| `conduit.db` | Agent messaging, delivery queue, `project_agent_refs` |
+
+### Global Tier (`$XDG_DATA_HOME/cleo/`)
+
+| Database | Purpose |
+|---|---|
+| `nexus.db` | Cross-project registry, federated queries |
+| `signaldock.db` | Canonical agent identity, cloud-sync tables |
+
+Plus: `global-salt` (32-byte machine-bound key for API key derivation), `machine-key`,
+`extensions/`, and `cant/` directories for globally installed CANT files.
+
+---
+
+## Installation
+
+```bash
+# One command installs both CleoOS and Pi
+npm install -g @cleocode/cleo-os
+
+# Verify
+cleoos --version
+cleo version
+```
+
+### What Gets Installed
+
+- `cleoos` binary — launches Pi with CleoOS extensions pre-loaded
+- `cleo` binary — CLEO CLI (90+ commands across 10 canonical domains)
+- `@mariozechner/pi-coding-agent` — Mario Zechner's open-source AI coding agent
+- XDG directory structure at `~/.local/share/cleo/`
+- Default CANT stubs and skill files
+
+### Requirements
+
+- Node.js >= 24.0.0
+- An AI provider API key (set via `cleoos` on first run, stored in `~/.config/cleo/auth/auth.json`)
+
+---
+
+## Architecture
+
+```
++-----------------------------------------------------------+
+|                   @cleocode/cleo-os                       |
+|  (CleoOS — batteries-included Pi wrapper)                 |
+|                                                           |
+|  +------------------------+  +------------------------+   |
+|  | extensions/            |  | extensions/            |   |
+|  | cleo-cant-bridge.ts    |  | cleo-chatroom.ts       |   |
+|  | (CANT compile,         |  | (4 tools, TUI widget,  |   |
+|  |  ACL enforcement,      |  |  JSONL relay,          |   |
+|  |  mental model inject)  |  |  not a Conduit shell)  |   |
+|  +------------------------+  +------------------------+   |
+|  src/cli.ts         <- cleoos launcher                     |
+|  src/postinstall.ts <- XDG scaffolding                     |
++-----------------------------------------------------------+
+        |
+        v (direct dependency)
++-----------------------------------------------------------+
+|             @mariozechner/pi-coding-agent                 |
+|  TUI, model providers, session management,                |
+|  extension API, tool execution, subagent spawn            |
++-----------------------------------------------------------+
+        |
+        v
++-----------------------------------------------------------+
+|                   @cleocode/cleo                          |
+|  CLI (90+ commands), dispatch registry,                   |
+|  LAFS envelopes, 10 canonical domains                     |
++-----------------------------------------------------------+
+        |
+        v
++-----------------------------------------------------------+
+|                   @cleocode/core                          |
+|  Tasks, sessions, memory, orchestration,                  |
+|  lifecycle, validation, backup, conduit                   |
++-----------------------------------------------------------+
+        |
+        v
++-----------------------------------------------------------+
+|             SQLite (node:sqlite via Drizzle ORM)          |
+|  tasks.db   brain.db   conduit.db   nexus.db              |
+|  signaldock.db                                            |
++-----------------------------------------------------------+
+```
+
+---
+
+## Wave Roadmap
+
+CleoOS ships in named waves. Each wave targets a vertical slice of the platform.
+
+| Wave | Title | Status | Key Deliverable |
+|------|-------|--------|-----------------|
+| 0 | CANT Grammar | Shipped | `team`, `tool`, `mental_model` document kinds |
+| 2 | CANT Bridge MVP | Shipped | `cleo-cant-bridge.ts` — compile + inject at session_start |
+| 3 | Launcher + Install | Shipped | `cleoos` binary, postinstall, XDG hub |
+| 7 | Chat Room + Hierarchy | Shipped | 4 inter-agent tools, TUI widget, 3-tier enforcement |
+| 7b | Lead Tool Blocking | Shipped | `Edit`/`Write`/`Bash` blocked for `role: lead` |
+| 8 | Mental Model Injection | Shipped | validate-on-load from BRAIN on agent spawn |
+| ACL | Worker Path ACL | Shipped | `permissions.files: write[glob]` enforcement |
+| 1 | Render Pipeline | Partial | Rust stubs exist, no `cant render` CLI verb yet |
+| 4 | Lifecycle Codegen | Partial | `.cant` files exist, `stages.ts` connection missing |
+| 5 | JIT Agent Composer | Partial | Library shipped, not wired to spawn path |
+| 6 | Model Router | In progress | Rust classifier crate exists |
+| 9 | Three-Tier CANT Resolution | Not started | Global/user/project `.cant` file hierarchy |
+
+---
+
+## References
+
+- [CLEO World Map](../../docs/concepts/CLEO-WORLD-MAP.md) — the founding myth and system vocabulary
+- [CleoOS Vision](../../docs/concepts/CLEOOS-VISION.md) — the long-term vision document
+- [ADR-035](../../.cleo/adrs/ADR-035-pi-v2-v3-harness.md) — Pi as primary harness
+- [ADR-036](../../.cleo/adrs/ADR-036-cleoos-database-topology.md) — database topology
+- [ADR-037](../../.cleo/adrs/ADR-037-conduit-signaldock-separation.md) — conduit/signaldock split
+- [Pi Coding Agent](https://github.com/mariozechner/pi) — the upstream agent CleoOS wraps
+
+---
+
+## License
+
+MIT

package/bin/postinstall.js

@@ -1,94 +1,208 @@
-#!/usr/bin/env node
 /**
- * CleoOS postinstall — scaffolds global XDG hub and deploys extensions.
+ * CleoOS postinstall — scaffolds the global XDG hub and deploys extensions.
  *
  * Runs automatically after `npm install -g @cleocode/cleo-os`.
- * Creates XDG-compliant directory structure and copies the CANT bridge
- * extension template into the extensions directory.
+ * Creates an XDG-compliant directory structure, copies the compiled CANT
+ * bridge extension to the extensions directory, and optionally invokes
+ * `cleo skills install` for any bundled CleoOS skills.
  *
- * Skips during workspace/dev installs (non-global).
+ * Behaviour:
+ *   - Skips silently during workspace/dev installs (non-global).
+ *   - All directory creation is idempotent (no-op if directory exists).
+ *   - All file copies are idempotent (only copies if target is missing).
+ *   - Skill install is best-effort; failures are logged but not fatal.
+ *   - Missing `@mariozechner/pi-coding-agent` is handled gracefully.
  *
- * This file is plain JS (not compiled from src/) so it can run before
- * the package is built, matching the @cleocode/cleo postinstall pattern.
+ * This source compiles to `bin/postinstall.js` via a dedicated tsconfig
+ * (see `tsconfig.postinstall.json`). The `postinstall` script in
+ * `package.json` references the compiled output at `bin/postinstall.js`.
+ *
+ * @packageDocumentation
  */
-
-import { existsSync, mkdirSync, cpSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-
+// ---------------------------------------------------------------------------
+// XDG path resolution (inline copy — avoids importing from dist/ which may
+// not exist when this script runs for the first time)
+// ---------------------------------------------------------------------------
+/**
+ * Inline XDG path resolution that mirrors `src/xdg.ts`.
+ *
+ * Uses an inline copy here so the postinstall script can run before
+ * the compiled `dist/` tree is available on a fresh install.
+ *
+ * @returns Resolved CleoOS XDG directory paths.
+ */
+function resolveCleoOsPaths() {
+    const home = homedir();
+    const xdgData = process.env['XDG_DATA_HOME'] ?? join(home, '.local', 'share');
+    const xdgConfig = process.env['XDG_CONFIG_HOME'] ?? join(home, '.config');
+    const data = join(xdgData, 'cleo');
+    const config = join(xdgConfig, 'cleo');
+    return {
+        data,
+        config,
+        agentDir: data,
+        extensions: join(data, 'extensions'),
+        cant: join(data, 'cant'),
+        auth: join(config, 'auth'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Global install detection
+// ---------------------------------------------------------------------------
 /**
- * Detect if this is a global npm install (not a workspace/dev install).
+ * Detect whether this is a global npm / pnpm install.
+ *
+ * Uses four heuristics in priority order:
+ *  1. `npm_config_global=true` env var (set by npm/pnpm for global installs)
+ *  2. Package path contains `lib/node_modules/` (npm global pattern)
+ *  3. Package path starts with `npm_config_prefix` (npm prefix-based check)
+ *  4. Presence of `pnpm-workspace.yaml` two levels up (workspace = dev)
+ *
+ * @returns `true` if the install appears to be a global install.
  */
 function isGlobalInstall() {
-  const pkgRoot = resolve(__dirname, '..');
-
-  // Signal 1: npm_config_global env var (set by npm during global installs)
-  if (process.env.npm_config_global === 'true') return true;
-
-  // Signal 2: path contains a global node_modules (npm, pnpm, yarn)
-  if (/[/\\]lib[/\\]node_modules[/\\]/.test(pkgRoot)) return true;
-
-  // Signal 3: npm_config_prefix matches the package path
-  const prefix = process.env.npm_config_prefix;
-  if (prefix && pkgRoot.startsWith(prefix)) return true;
-
-  // Signal 4: inside a pnpm workspace — definitely not global
-  const workspaceMarker = join(pkgRoot, '..', '..', 'pnpm-workspace.yaml');
-  if (existsSync(workspaceMarker)) return false;
-
-  return false;
+    const pkgRoot = resolve(__dirname, '..');
+    // Signal 1: npm_config_global env var (set by npm during global installs)
+    if (process.env['npm_config_global'] === 'true')
+        return true;
+    // Signal 2: path contains a global node_modules (npm, pnpm, yarn)
+    if (/[/\\]lib[/\\]node_modules[/\\]/.test(pkgRoot))
+        return true;
+    // Signal 3: npm_config_prefix matches the package path
+    const prefix = process.env['npm_config_prefix'];
+    if (prefix !== undefined && pkgRoot.startsWith(prefix))
+        return true;
+    // Signal 4: inside a pnpm workspace — definitely not global
+    const workspaceMarker = join(pkgRoot, '..', '..', 'pnpm-workspace.yaml');
+    if (existsSync(workspaceMarker))
+        return false;
+    return false;
 }
-
+// ---------------------------------------------------------------------------
+// Directory scaffolding
+// ---------------------------------------------------------------------------
 /**
- * Inline XDG path resolution (avoids importing from dist/ which may not exist).
+ * Idempotently create a directory if it does not already exist.
+ *
+ * @param dir - Absolute path to the directory to create.
  */
-function resolveCleoOsPaths() {
-  const home = homedir();
-  const xdgData = process.env.XDG_DATA_HOME ?? join(home, '.local', 'share');
-  const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(home, '.config');
-
-  const data = join(xdgData, 'cleo');
-  const config = join(xdgConfig, 'cleo');
-
-  return {
-    data,
-    config,
-    agentDir: data,
-    extensions: join(data, 'extensions'),
-    cant: join(data, 'cant'),
-    auth: join(config, 'auth'),
-  };
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        process.stdout.write(`CleoOS: created ${dir}\n`);
+    }
 }
-
+// ---------------------------------------------------------------------------
+// Extension deployment
+// ---------------------------------------------------------------------------
+/**
+ * Copy a compiled extension to the XDG extensions directory.
+ *
+ * Only copies if the target does not already exist (idempotent). The
+ * source is the compiled `.js` file in the package's `extensions/` folder.
+ *
+ * @param extensionName - Filename without the `.js` extension.
+ * @param pkgRoot - Absolute path to the installed package root.
+ * @param extensionsDir - Absolute path to the XDG extensions directory.
+ */
+function deployExtension(extensionName, pkgRoot, extensionsDir) {
+    const src = join(pkgRoot, 'extensions', `${extensionName}.js`);
+    const dest = join(extensionsDir, `${extensionName}.js`);
+    if (!existsSync(src)) {
+        process.stdout.write(`CleoOS: skipping ${extensionName}.js (source not found at ${src})\n`);
+        return;
+    }
+    if (existsSync(dest)) {
+        // Already deployed — idempotent, skip.
+        return;
+    }
+    cpSync(src, dest, { force: false });
+    process.stdout.write(`CleoOS: deployed ${extensionName}.js to ${dest}\n`);
+}
+// ---------------------------------------------------------------------------
+// Default CANT file scaffolding
+// ---------------------------------------------------------------------------
+/**
+ * Write a default `model-routing.cant` stub to the XDG CANT directory if
+ * no `.cant` files are present. This gives the user a starting point for
+ * CANT declarations without overwriting any existing work.
+ *
+ * @param cantDir - Absolute path to the XDG CANT directory.
+ */
+function scaffoldDefaultCant(cantDir) {
+    const modelRoutingPath = join(cantDir, 'model-routing.cant');
+    if (existsSync(modelRoutingPath))
+        return;
+    const stub = [
+        '# CleoOS default model-routing.cant',
+        '# Declare agents, teams, and routing rules here.',
+        '# See: https://github.com/kryptobaseddev/cleo/blob/main/docs/cant-dsl.md',
+        '',
+    ].join('\n');
+    try {
+        writeFileSync(modelRoutingPath, stub, 'utf-8');
+        process.stdout.write(`CleoOS: created default ${modelRoutingPath}\n`);
+    }
+    catch {
+        // Best-effort: non-fatal.
+    }
+}
+// ---------------------------------------------------------------------------
+// Skill installation
+// ---------------------------------------------------------------------------
+/**
+ * Invoke `cleo skills install` via `execFileSync` to register the CleoOS
+ * bundled skills with the project. This is best-effort — if `cleo` is not
+ * on PATH or the command fails, we log and continue.
+ *
+ * Uses `execFileSync` (not `exec`) to prevent shell injection: the command
+ * and arguments are passed as separate parameters so no shell is spawned.
+ */
+function installSkills() {
+    try {
+        execFileSync('cleo', ['skills', 'install'], { stdio: 'inherit' });
+        process.stdout.write('CleoOS: skills install complete\n');
+    }
+    catch {
+        // cleo may not be installed or skills may already be up to date.
+        process.stdout.write('CleoOS: skipping skills install (cleo not found or already installed)\n');
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+/**
+ * Entry point for the CleoOS postinstall script.
+ *
+ * Orchestrates directory scaffolding, extension deployment, CANT stub
+ * creation, and optional skill installation. All operations are idempotent.
+ */
 function main() {
-  if (!isGlobalInstall()) {
-    console.log('CleoOS: skipping postinstall (not global install)');
-    return;
-  }
-
-  const paths = resolveCleoOsPaths();
-
-  // Scaffold directories
-  for (const dir of [paths.data, paths.config, paths.extensions, paths.cant, paths.auth]) {
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
-      console.log(`CleoOS: created ${dir}`);
+    if (!isGlobalInstall()) {
+        process.stdout.write('CleoOS: skipping postinstall (not global install)\n');
+        return;
+    }
+    const paths = resolveCleoOsPaths();
+    const pkgRoot = resolve(__dirname, '..');
+    // 1. Scaffold XDG directories
+    for (const dir of [paths.data, paths.config, paths.extensions, paths.cant, paths.auth]) {
+        ensureDir(dir);
     }
-  }
-
-  // Deploy bridge extension from package template
-  const bridgeTemplate = join(__dirname, '..', 'extensions', 'cleo-cant-bridge.js');
-  const bridgeTarget = join(paths.extensions, 'cleo-cant-bridge.js');
-  if (existsSync(bridgeTemplate)) {
-    cpSync(bridgeTemplate, bridgeTarget, { force: true });
-    console.log(`CleoOS: deployed bridge extension to ${bridgeTarget}`);
-  }
-
-  console.log('CleoOS: postinstall complete');
+    // 2. Deploy compiled extensions
+    deployExtension('cleo-cant-bridge', pkgRoot, paths.extensions);
+    deployExtension('cleo-chatroom', pkgRoot, paths.extensions);
+    // 3. Write default CANT stub (only if file does not exist)
+    scaffoldDefaultCant(paths.cant);
+    // 4. Install CleoOS skills (best-effort)
+    installSkills();
+    process.stdout.write('CleoOS: postinstall complete\n');
 }
-
 main();
+//# sourceMappingURL=postinstall.js.map

package/bin/postinstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postinstall.js","sourceRoot":"","sources":["../src/postinstall.ts"],"names":[],"mappings":"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"}