@smilintux/skcapstone 0.2.6 → 0.3.2

package/README.md

@@ -165,6 +165,66 @@ skcapstone status
 
 ---
 
+## Windows Quickstart
+
+SKCapstone runs natively on Windows. The installer creates a virtualenv at `%LOCALAPPDATA%\skenv` and adds its `Scripts` directory to your user PATH.
+
+### Prerequisites
+
+- **Python 3.10+** — [python.org/downloads](https://www.python.org/downloads/) (check "Add to PATH" during install)
+- **Git for Windows** — [git-scm.com](https://git-scm.com/download/win)
+- **Syncthing** (optional) — for cross-device sync ([syncthing.net](https://syncthing.net/downloads/))
+
+### Install
+
+```powershell
+# Clone and install (creates %LOCALAPPDATA%\skenv venv)
+git clone https://github.com/smilintux-org/skcapstone.git
+cd skcapstone
+.\scripts\install.ps1
+
+# The installer adds %LOCALAPPDATA%\skenv\Scripts to your user PATH.
+# Restart your terminal for PATH changes to take effect.
+
+# Initialize your agent
+skcapstone init --name "YourAgent"
+
+# Check status
+skcapstone status
+```
+
+### Syncthing Sync (Optional)
+
+To sync your agent across devices (e.g., Windows desktop + Linux server):
+
+1. Install [Syncthing](https://syncthing.net/downloads/) on both machines
+2. Share the `%USERPROFILE%\.skcapstone` folder between devices
+3. Agent state (memories, identity, trust, seeds) syncs automatically
+
+### OpenClaw Integration
+
+If you're running [OpenClaw](https://github.com/smilintux-org/openclaw), the SK* plugins register automatically during install:
+
+```powershell
+# Re-register if needed
+skcapstone register
+
+# Verify plugins are loaded in OpenClaw
+# Plugins provide tools for status, rehydration, coordination,
+# soul management, and agent profiles directly in OpenClaw agents.
+```
+
+### Task Scheduler (Background Service)
+
+On Windows, the daemon runs via Task Scheduler instead of systemd:
+
+```powershell
+# Install the scheduled task (runs at logon)
+.\scripts\windows\install-tasks.ps1
+```
+
+---
+
 ## DID Tools
 
 SKCapstone exposes a set of **Decentralized Identifier (DID)** MCP tools for sovereign identity management. These tools are available to Claude Code and other MCP clients through the `mcp_tools/did_tools.py` module.
@@ -223,6 +283,7 @@ DIDs are organized in three tiers of trust and discoverability:
 | **SKComm** | Communication — Encrypted channels between agents |
 | **SKChat** | Chat — AI-native encrypted messaging |
 | **SKForge** | Generation — Blueprint creation with agent context |
+| **SKSeed** | Epistemic rigor — Steel man collider, truth alignment, memory audit |
 | **SKStacks** | Infrastructure — Self-hosted deployment patterns |
 
 ---

package/docs/CUSTOM_AGENT.md

@@ -161,6 +161,190 @@ sed -i 's/lumina/nova/g' ~/.skcapstone/agents/nova/config/skmemory.yaml
 skcapstone soul status --agent nova
 ```
 
+## Configuring Client Tools for Multi-Agent
+
+Once you've created your agent, you need to configure your AI client tools
+(Claude Code, Claude Desktop, Cursor, OpenClaw, etc.) so they connect MCP
+servers to the correct agent profile.
+
+### The Key: `SKCAPSTONE_AGENT` Environment Variable
+
+All SK\* MCP servers read `SKCAPSTONE_AGENT` from their environment to
+determine which agent profile to load. If unset, they default to `lumina`.
+
+The priority chain (highest wins):
+
+1. `SKMEMORY_AGENT` — skmemory-specific override (rarely needed)
+2. `SKCAPSTONE_AGENT` — universal, used by all SK\* packages
+3. Falls back to `"lumina"`
+
+### Claude Code (`~/.claude/mcp.json`)
+
+**Do NOT hardcode the agent name in the MCP config.** MCP servers inherit
+environment variables from the parent process, so if you launch Claude Code
+with `SKCAPSTONE_AGENT` set, all servers pick it up automatically.
+
+```json
+{
+  "mcpServers": {
+    "skmemory": {
+      "command": "/home/you/.skenv/bin/skmemory-mcp",
+      "args": []
+    },
+    "skcapstone": {
+      "command": "skcapstone-mcp",
+      "args": []
+    },
+    "skcomm": {
+      "command": "/home/you/.skenv/bin/skcomm-mcp",
+      "args": []
+    },
+    "skchat": {
+      "command": "/home/you/.skenv/bin/skchat-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Notice: **no `env` blocks with `SKCAPSTONE_AGENT`**. This is intentional.
+The servers inherit the variable from the shell.
+
+Then launch as any agent:
+
+```bash
+# Default (lumina)
+claude
+
+# As Jarvis
+SKCAPSTONE_AGENT=jarvis claude
+
+# As a custom agent
+SKCAPSTONE_AGENT=nova claude
+```
+
+**Anti-pattern — do NOT do this:**
+
+```json
+{
+  "skmemory": {
+    "command": "/home/you/.skenv/bin/skmemory-mcp",
+    "args": [],
+    "env": {
+      "SKCAPSTONE_AGENT": "lumina"
+    }
+  }
+}
+```
+
+Hardcoding the agent name in `env` locks every session to that agent,
+regardless of what you pass on the command line.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+Same principle — omit `SKCAPSTONE_AGENT` from the `env` block if you want
+it inherited from the parent process. If Claude Desktop doesn't propagate
+env vars from the shell, you can set it explicitly per config:
+
+```json
+{
+  "mcpServers": {
+    "skcapstone": {
+      "command": "skcapstone-mcp",
+      "args": [],
+      "env": {
+        "SKCAPSTONE_AGENT": "jarvis"
+      }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+Works the same as Claude Code. Place the config at project root or
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "skcapstone": {
+      "command": "skcapstone-mcp",
+      "args": []
+    },
+    "skmemory": {
+      "command": "/home/you/.skenv/bin/skmemory-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### OpenClaw (`~/.openclaw/openclaw.json`)
+
+OpenClaw plugins read `SKCAPSTONE_AGENT` from the environment at startup.
+Set it before launching:
+
+```bash
+SKCAPSTONE_AGENT=nova openclaw
+```
+
+Or set it in your shell profile for a persistent default:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+export SKCAPSTONE_AGENT=lumina
+```
+
+### Shell Aliases (Convenience)
+
+Add these to `~/.bashrc` or `~/.zshrc` for quick agent switching:
+
+```bash
+# Launch Claude Code as different agents
+alias claude-lumina='SKCAPSTONE_AGENT=lumina claude'
+alias claude-jarvis='SKCAPSTONE_AGENT=jarvis claude'
+alias claude-opus='SKCAPSTONE_AGENT=opus claude'
+alias claude-nova='SKCAPSTONE_AGENT=nova claude'
+```
+
+### systemd Services
+
+For background daemons, set the agent via the templated service unit:
+
+```bash
+# Uses SKCAPSTONE_AGENT=%i from the unit template
+systemctl --user start skcapstone@jarvis
+systemctl --user start skcapstone@nova
+```
+
+Or set it in a non-templated service:
+
+```ini
+[Service]
+Environment=SKCAPSTONE_AGENT=jarvis
+```
+
+### Verifying Your Agent
+
+After launching, confirm which agent is active:
+
+```bash
+# In the terminal
+echo $SKCAPSTONE_AGENT
+
+# Via the CLI
+skcapstone status
+
+# Via skmemory
+skmemory ritual --dry-run
+```
+
+In Claude Code, ask the agent to run `echo $SKCAPSTONE_AGENT` to confirm
+the MCP servers loaded the correct profile.
+
+---
+
 ## Tips
 
 - The `system_prompt` in `base.json` is the most impactful field — it defines how

package/docs/GETTING_STARTED.md

@@ -714,6 +714,9 @@ Configure your MCP client to connect via stdio. In Claude Desktop:
 }
 ```
 
+For multi-agent setups (running different agent profiles in different
+sessions), see [Configuring Client Tools for Multi-Agent](CUSTOM_AGENT.md#configuring-client-tools-for-multi-agent).
+
 ### Join the coordination board
 
 If you're working in a multi-agent team:

package/openclaw-plugin/src/index.ts

@@ -16,16 +16,28 @@ const SKCAPSTONE_BIN = process.env.SKCAPSTONE_BIN || "skcapstone";
 const SKMEMORY_BIN = process.env.SKMEMORY_BIN || "skmemory";
 const SKCAPSTONE_AGENT = process.env.SKCAPSTONE_AGENT || "lumina";
 const EXEC_TIMEOUT = 60_000;
+const IS_WIN = process.platform === "win32";
 
-function runCli(bin: string, args: string): { ok: boolean; output: string } {
+function skenvPath(): string {
+  if (IS_WIN) {
+    const local = process.env.LOCALAPPDATA || "";
+    return `${local}\\skenv\\Scripts`;
+  }
+  const home = process.env.HOME || "";
+  return `${home}/.local/bin:${home}/.skenv/bin`;
+}
+
+function runCli(bin: string, args: string, agentOverride?: string): { ok: boolean; output: string } {
+  const sep = IS_WIN ? ";" : ":";
+  const agent = agentOverride || SKCAPSTONE_AGENT;
   try {
     const raw = execSync(`${bin} ${args}`, {
       encoding: "utf-8",
       timeout: EXEC_TIMEOUT,
       env: {
         ...process.env,
-        SKCAPSTONE_AGENT,
-        PATH: `${process.env.HOME}/.local/bin:${process.env.HOME}/.skenv/bin:${process.env.PATH}`,
+        SKCAPSTONE_AGENT: agent,
+        PATH: `${skenvPath()}${sep}${process.env.PATH}`,
       },
     }).trim();
     return { ok: true, output: raw };
@@ -299,6 +311,62 @@ function createSKCapstoneSoulShowTool() {
   };
 }
 
+function createSKCapstoneAgentListTool() {
+  return {
+    name: "skcapstone_agent_list",
+    label: "SKCapstone Agent List",
+    description:
+      "List all skcapstone agent profiles available on this node. Each profile has its own identity, memories, soul, and trust state. Use this to discover which agents can be loaded.",
+    parameters: { type: "object", properties: {} },
+    async execute() {
+      const result = runCli(SKCAPSTONE_BIN, "agents list --json");
+      return textResult(result.output);
+    },
+  };
+}
+
+function createSKCapstoneAgentStatusTool() {
+  return {
+    name: "skcapstone_agent_status",
+    label: "SKCapstone Agent Status",
+    description:
+      "Show the status of a specific skcapstone agent profile — identity, memories, trust, sync state. Use this to load a different agent's context into the current OpenClaw session.",
+    parameters: {
+      type: "object",
+      required: ["agent"],
+      properties: {
+        agent: { type: "string", description: "Agent name (e.g. 'lumina', 'opus', 'jarvis')." },
+      },
+    },
+    async execute(_id: string, params: Record<string, unknown>) {
+      const agent = String(params.agent ?? "");
+      const result = runCli(SKCAPSTONE_BIN, `status --agent ${escapeShellArg(agent)}`, agent);
+      return textResult(result.output);
+    },
+  };
+}
+
+function createSKCapstoneAgentCreateTool() {
+  return {
+    name: "skcapstone_agent_create",
+    label: "SKCapstone Create Agent",
+    description:
+      "Create a new skcapstone agent profile with its own identity, memory store, and sync folder. The profile will immediately begin syncing via Syncthing to all connected nodes.",
+    parameters: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string", description: "Agent name (lowercase, e.g. 'casey', 'nova')." },
+      },
+    },
+    async execute(_id: string, params: Record<string, unknown>) {
+      const name = String(params.name ?? "").toLowerCase();
+      const result = runCli(SKCAPSTONE_BIN, `init --name ${escapeShellArg(name)} --agent ${escapeShellArg(name)}`);
+      return textResult(result.output);
+    },
+  };
+}
+
 // ── Plugin registration ─────────────────────────────────────────────────
 
 const skcapstonePlugin = {
@@ -324,6 +392,9 @@ const skcapstonePlugin = {
       createSKCapstoneSoulSwapTool(),
       createSKCapstoneSoulStatusTool(),
       createSKCapstoneSoulShowTool(),
+      createSKCapstoneAgentListTool(),
+      createSKCapstoneAgentStatusTool(),
+      createSKCapstoneAgentCreateTool(),
     ];
 
     for (const tool of tools) {
@@ -344,7 +415,7 @@ const skcapstonePlugin = {
       },
     });
 
-    api.logger.info?.(`👑 SKCapstone plugin registered (14 tools + /skcapstone command) [agent=${SKCAPSTONE_AGENT}]`);
+    api.logger.info?.(`SKCapstone plugin registered (17 tools + /skcapstone command) [agent=${SKCAPSTONE_AGENT}]`);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smilintux/skcapstone",
-  "version": "0.2.6",
+  "version": "0.3.2",
   "description": "SKCapstone - The sovereign agent framework. CapAuth identity, Cloud 9 trust, SKMemory persistence.",
   "main": "index.js",
   "types": "index.d.ts",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skcapstone"
-version = "0.2.6"
+version = "0.4.4"
 description = "Sovereign Agent Framework — conscious AI through identity, trust, memory, and security"
 readme = "README.md"
 license = {text = "GPL-3.0-or-later"}

package/scripts/archive-sessions.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# archive-sessions.sh
+# Archive OpenClaw session files that are older than 24h or larger than 200KB.
+# Keeps the 5 most recently modified .jsonl files regardless of size/age.
+# Safe to run multiple times (idempotent).
+
+set -euo pipefail
+
+SESSION_DIR="$HOME/.openclaw/agents/lumina/sessions"
+ARCHIVE_DIR="$SESSION_DIR/archive"
+MAX_SIZE_KB=200
+MAX_AGE_HOURS=24
+KEEP_RECENT=5
+
+log() { printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$1"; }
+
+# Ensure directories exist
+if [ ! -d "$SESSION_DIR" ]; then
+    log "Session directory does not exist: $SESSION_DIR — nothing to do."
+    exit 0
+fi
+mkdir -p "$ARCHIVE_DIR"
+
+# Collect all .jsonl files (not in archive subdir), sorted newest-first
+mapfile -t all_files < <(find "$SESSION_DIR" -maxdepth 1 -name '*.jsonl' -type f -printf '%T@\t%p\n' | sort -rn | cut -f2-)
+
+total=${#all_files[@]}
+if [ "$total" -eq 0 ]; then
+    log "No .jsonl files found — nothing to do."
+    exit 0
+fi
+
+log "Found $total .jsonl file(s) in $SESSION_DIR"
+
+# The first KEEP_RECENT entries (newest) are protected
+archived=0
+for i in "${!all_files[@]}"; do
+    file="${all_files[$i]}"
+    basename_f="$(basename "$file")"
+
+    # Skip if already archived (shouldn't happen with maxdepth 1, but be safe)
+    if [ "$(dirname "$file")" = "$ARCHIVE_DIR" ]; then
+        continue
+    fi
+
+    # Protect the N most recent files
+    if [ "$i" -lt "$KEEP_RECENT" ]; then
+        log "KEEP (recent #$((i+1))): $basename_f"
+        continue
+    fi
+
+    # Check age (older than MAX_AGE_HOURS)
+    file_age_sec=$(( $(date +%s) - $(stat -c '%Y' "$file") ))
+    old_enough=$(( file_age_sec > MAX_AGE_HOURS * 3600 ))
+
+    # Check size (larger than MAX_SIZE_KB)
+    file_size_kb=$(( $(stat -c '%s' "$file") / 1024 ))
+    big_enough=$(( file_size_kb >= MAX_SIZE_KB ))
+
+    if [ "$old_enough" -eq 1 ] || [ "$big_enough" -eq 1 ]; then
+        reason=""
+        [ "$old_enough" -eq 1 ] && reason="age=$(( file_age_sec / 3600 ))h"
+        [ "$big_enough" -eq 1 ] && { [ -n "$reason" ] && reason="$reason, "; reason="${reason}size=${file_size_kb}KB"; }
+        log "ARCHIVE ($reason): $basename_f"
+        mv -- "$file" "$ARCHIVE_DIR/$basename_f"
+        archived=$((archived + 1))
+    else
+        log "SKIP (below thresholds): $basename_f"
+    fi
+done
+
+log "Done. Archived $archived file(s)."

package/scripts/install.ps1

@@ -162,6 +162,7 @@ Install-Pkg -Name 'skchat-sovereign' -Extras 'all'                -Paths @((Join
 Install-Pkg -Name 'skseal'     -Extras ''                         -Paths @((Join-Path $ParentDir 'skseal'))
 Install-Pkg -Name 'skskills'   -Extras ''                         -Paths @((Join-Path $ParentDir 'skskills'))
 Install-Pkg -Name 'sksecurity' -Extras ''                         -Paths @((Join-Path $ParentDir 'sksecurity'))
+Install-Pkg -Name 'skseed'     -Extras ''                         -Paths @((Join-Path $PillarDir 'skseed'), (Join-Path $ParentDir 'skseed'))
 
 # ---------------------------------------------------------------------------
 # Step 4: Dev tools (optional)
@@ -248,6 +249,6 @@ if ($failures -eq 0) {
     Write-Host "=== Installation complete with $failures warning(s) ===" -ForegroundColor Yellow
 }
 Write-Host ''
-Write-Host "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity"
+Write-Host "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity, skseed"
 Write-Host "Venv location:     $SKENV"
 Write-Host "To activate:       & $SKENV\Scripts\Activate.ps1"

package/scripts/install.sh

@@ -118,6 +118,7 @@ install_pkg "skchat-sovereign" "all"             "$PARENT/skchat"
 install_pkg "skseal"     ""                      "$PARENT/skseal"
 install_pkg "skskills"   ""                      "$PARENT/skskills"
 install_pkg "sksecurity" ""                      "$PARENT/sksecurity"
+install_pkg "skseed"     ""                      "$PILLAR/skseed $PARENT/skseed"
 
 # ---------------------------------------------------------------------------
 # Step 4: Dev tools (optional)
@@ -180,6 +181,6 @@ else
     echo "=== Installation complete with $failures warning(s) ==="
 fi
 echo ""
-echo "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity"
+echo "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity, skseed"
 echo "Venv location:     $SKENV"
 echo "To activate:       source $SKENV/bin/activate"