@smilintux/skcapstone 0.9.0 → 0.12.5

package/docs/DREAMING.md

@@ -0,0 +1,70 @@
+# Dreaming Engine — Setup & Usage
+
+The dreaming engine (`src/skcapstone/dreaming.py`) gathers recent memories, reflects on
+them with an LLM, and stores resulting **insights / connections / questions** as new
+memories (`~/.skcapstone/agents/$AGENT/memory/dream-log.json`). It is driven by the
+**consciousness daemon** on an idle cycle.
+
+## How it's triggered
+- Runs inside the **consciousness daemon**: `skcapstone daemon start|stop|status`.
+- Fires when the agent is idle (`idle_threshold_minutes`), respecting `cooldown_hours`
+  and `max_per_day`. There is **no on-demand CLI trigger** — restart the daemon to load
+  config/code changes; it dreams on the next eligible cycle.
+- Daily reflection (separate): `agents/$AGENT/scripts/daily-dream-reflection.sh` (4am cron)
+  summarizes the last 24h to Telegram.
+
+## LLM provider (the important part)
+`DreamingConfig` (in `dreaming.py`) picks the model. Providers: `claude` (CLI), `nvidia`
+(NIM), `ollama` (any OpenAI-compatible host). **Default since 2026-06-08: `ollama` →
+BeeLlama (abliterated Qwen3.6-27B) on the local GPU.**
+
+### Sample config (consciousness `dreaming:` section, or the dataclass defaults)
+```yaml
+dreaming:
+  enabled: true
+  provider: ollama                          # claude | nvidia | ollama
+  ollama_host: "http://192.168.0.100:8082"  # BeeLlama, OpenAI-compatible /v1/chat/completions
+  ollama_model: "qwen3.6-27b-abliterated"   # served by skai-beellama.service
+  temperature: 1.0
+  creativity_mode: unhinged                 # conservative | balanced | creative | unhinged
+  max_response_tokens: 4096
+  idle_threshold_minutes: 30
+  cooldown_hours: 2.0
+  max_per_day: 1
+  # --- anti-repetition guard (the "fix dreaming repetition bug" work) ---
+  dedup_lookback: 10                        # compare against last N dreams
+  dedup_overlap_threshold: 0.60             # skip insights >60% keyword-overlapping recent ones
+  graduation_consecutive_threshold: 5       # graduate a theme after 5 appearances (stop re-surfacing)
+  diversity_lookback: 5
+  diversity_min_unique_ratio: 0.40          # force memory diversification if recent dreams too similar
+```
+
+> The `ollama` provider calls **`/v1/chat/completions`** (OpenAI format) and strips
+> `<think>…</think>`. Point `ollama_host` at any OpenAI-compatible server (BeeLlama,
+> Ollama's `/v1`, etc.) and set `ollama_model` to a model it serves.
+
+### History / gotcha
+The engine stalled **2026-05-03**: the old default `provider: claude` died with an OAuth
+degradation, and the ollama fallback was hardcoded to `deepseek-r1:32b` (not present on the
+host). Fix = repoint to BeeLlama abliterated (above) + make `_call_ollama` speak OpenAI
+chat format. See `BeeLlama` / `skai-beellama.service` on the GPU host.
+
+## Reviewing dreams
+- **Interactive:** the `dream-review` skill (`~/clawd/skills/dream-review`) — extract →
+  present → ComfyUI Flux art (`scripts/generate-dream-art.sh`) → file to GTD/seeds.
+- **Weekly (automated):** Hermes cron `weekly-dream-reflection` (Sun 9:13) → Lumina
+  summarizes the week + a mood image → Telegram DM → **archives that week's dream items out
+  of the GTD inbox** (`~/.hermes/scripts/dream-week-prep.sh`).
+- **Catch-up / backlog (one-off):** `~/clawd/scripts/dream_catchup.py` batch-summarizes the
+  unique backlog via BeeLlama; `dream_catchup_complete.py` meta-synthesizes, files
+  `dream-summaries-<date>.md` **and ingests them into the pg `docs` store
+  (`source=dream-summaries`)** for future meta-analysis, then archives the backlog.
+
+## Files
+| File | Purpose |
+|---|---|
+| `src/skcapstone/dreaming.py` | the engine (gather → reflect → dedup/graduate → store) |
+| `agents/$AGENT/scripts/daily-dream-reflection.sh` | 4am daily reflection → Telegram |
+| `~/.hermes/scripts/dream-week-prep.sh` | weekly digest + GTD archive (Hermes cron) |
+| `~/clawd/scripts/dream_catchup*.py` | backlog catch-up (summarize → synth → ingest → archive) |
+| `~/clawd/skills/dream-review/` | interactive review skill (+ ComfyUI art) |

package/docs/GETTING_STARTED.md

@@ -86,7 +86,7 @@ pip install skcapstone
 
 **Recommended** — all pillars:
 ```bash
-pip install skcapstone skmemory skcomm capauth
+pip install skcapstone skmemory skcomms capauth
 ```
 
 **Full** — everything including optional extras:
@@ -98,7 +98,7 @@ pip install "skcapstone[all]"
 |---------|-------------|
 | `skcapstone` | Core framework, CLI, daemon, coordination |
 | `skmemory` | Persistent memory (short/mid/long-term layers) |
-| `skcomm` | Encrypted agent-to-agent message transport |
+| `skcomms` | Encrypted agent-to-agent message transport |
 | `capauth` | PGP-based sovereign identity pillar |
 
 ### Verify the install
@@ -189,7 +189,7 @@ skcapstone whoami
 │ Handle:        my-agent@skworld.io                                           │
 │ Consciousness: SINGULAR                                                      │
 │ Memories:      0                                                             │
-│ Capabilities:  capauth:identity, skcomm:messaging, skmemory:persistence      │
+│ Capabilities:  capauth:identity, skcomms:messaging, skmemory:persistence      │
 ╰──────────────────────────────────────────────────────────────────────────────╯
   Share this card: skcapstone whoami --export card.json
   Peer imports it: skcapstone peer add --card card.json
@@ -429,8 +429,8 @@ skcapstone doctor
     ✓ Memory store (1 memory across all layers)
     ✓ Memory search index (present)
 
-  Transport (SKComm)
-    ✓ SKComm engine (1 transport configured)
+  Transport (SKComms)
+    ✓ SKComms engine (1 transport configured)
     ✓ Transport: file (available)
 
   29 passed, 0 failed out of 29 checks.
@@ -548,7 +548,7 @@ Common causes and fixes:
 | Log message | Fix |
 |-------------|-----|
 | `skseed not installed` | `pip install "skcapstone[seed]"` |
-| `skcomm not installed` | `pip install skcomm` |
+| `skcomms not installed` | `pip install skcomms` |
 | `watchdog not installed` | `pip install watchdog` (degrades to polling without it) |
 | `Ollama warmup skipped` | Run `ollama serve`, then `ollama pull llama3.2` |
 | `Connection refused: 11434` | Ollama isn't running — start it with `ollama serve` |
@@ -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:
@@ -745,7 +748,7 @@ skcapstone context                           # regenerate CLAUDE.md context
 
 ```
 # Install
-pip install skcapstone skmemory skcomm capauth
+pip install skcapstone skmemory skcomms capauth
 
 # First-time setup
 skcapstone init --name "my-agent"

package/docs/QUICKSTART.md

@@ -2,6 +2,10 @@
 
 Zero to sovereign agent in ~15 minutes.
 
+> **CLI reference:** This doc covers the most common commands. For the full up-to-date
+> command list run `skcapstone --help` or `skcapstone <command> --help`. The CLI is the
+> authoritative source; this doc may lag new additions by a version or two.
+
 ---
 
 ## Architecture
@@ -16,7 +20,7 @@ flowchart LR
     E -->|CODE tier| G[Ollama\ndevstral]
     E -->|REASON tier| H[cloud API\nanthropic / grok / …]
     E -->|fallback cascade| I[passthrough]
-    F & G & H & I --> J[SKComm send\nresponse → sender]
+    F & G & H & I --> J[SKComms send\nresponse → sender]
     J --> K[Daemon HTTP API\n:7777/consciousness]
 ```
 
@@ -86,7 +90,7 @@ pip install "skcapstone[consciousness,comms,seed]"
 | Extra | Installs | Required for |
 |-------|----------|-------------|
 | `consciousness` | `watchdog` | inotify inbox watcher |
-| `comms` | `skcomm` | SKComm message transport |
+| `comms` | `skcomms` | SKComms message transport |
 | `seed` | `skseed` | LLM callbacks (Ollama, Anthropic, etc.) |
 | `identity` | `capauth` | PGP identity pillar |
 
@@ -294,7 +298,7 @@ skcapstone daemon uninstall
 
 ## 7. Send a Test Message
 
-The consciousness loop watches `$SKCOMM_HOME/sync/comms/inbox/` (default `~/.skcomm/sync/comms/inbox/`). Dropping a JSON envelope there triggers an immediate response.
+The consciousness loop watches `$SKCOMMS_HOME/sync/comms/inbox/` (default `~/.skcomms/sync/comms/inbox/`). Dropping a JSON envelope there triggers an immediate response.
 
 ### Quick end-to-end test via CLI
 
@@ -302,12 +306,12 @@ The consciousness loop watches `$SKCOMM_HOME/sync/comms/inbox/` (default `~/.skc
 skcapstone consciousness test "Hello, are you there?"
 ```
 
-This runs the full pipeline (classify → model router → LLM → response) synchronously and prints the result without going through SKComm.
+This runs the full pipeline (classify → model router → LLM → response) synchronously and prints the result without going through SKComms.
 
 ### Manual inbox write (mimics a real peer message)
 
 ```bash
-INBOX=~/.skcomm/sync/comms/inbox
+INBOX=~/.skcomms/sync/comms/inbox
 mkdir -p "$INBOX"
 
 cat > "$INBOX/test-$(date +%s).json" << 'EOF'
@@ -406,7 +410,7 @@ Common causes:
 | Error | Fix |
 |-------|-----|
 | `skseed not installed` | `pip install "skcapstone[seed]"` |
-| `skcomm not installed` | `pip install "skcapstone[comms]"` |
+| `skcomms not installed` | `pip install "skcapstone[comms]"` |
 | `watchdog not installed` | `pip install "skcapstone[consciousness]"` — degrades to polling |
 | `Ollama warmup skipped` | Start Ollama: `ollama serve` then `ollama pull llama3.2` |
 

package/docs/SKJOULE_ARCHITECTURE.md

@@ -517,7 +517,7 @@ classDiagram
 
 SKJoule is not standalone. It connects to every major component of the SK
 ecosystem. The coord board in SKCapstone triggers Joule minting. SKMemory
-stores work records. SKComm enables peer-to-peer transfers. SKVector and
+stores work records. SKComms enables peer-to-peer transfers. SKVector and
 SKGraph provide verification data.
 
 ```mermaid
@@ -536,7 +536,7 @@ flowchart TD
         MEM_REP["Reputation Logs"]
     end
 
-    subgraph "SKComm"
+    subgraph "SKComms"
         COMM_P2P["P2P Token Transfers"]
         COMM_MSG["Agent-to-Agent Messaging"]
         COMM_SYNC["Syncthing Distribution"]
@@ -593,7 +593,7 @@ flowchart TD
 **Data flow summary:**
 - SKCapstone provides the task lifecycle (claim, work, complete) and cost data
 - SKMemory persists all work records, P&L snapshots, and reputation logs
-- SKComm handles peer-to-peer Joule transfers between agents
+- SKComms handles peer-to-peer Joule transfers between agents
 - SKVector/SKGraph enable work verification through embeddings and provenance
 - OpenClaw is the execution environment where agents actually do work
 - On-chain contracts handle final token minting and cross-chain bridging

package/docs/SOUL_SWAPPER.md

@@ -126,7 +126,7 @@ skcapstone soul install-all ~/clawd/soul-blueprints/blueprints/
 
 ## 4. CLI Reference
 
-All soul commands live under the `skcapstone soul` group. Every command accepts a `--agent` / `-a` flag to target a specific agent profile (defaults to `SKCAPSTONE_AGENT` env var or `lumina`).
+All soul commands live under the `skcapstone soul` group. Every command accepts a `--agent` / `-a` flag to target a specific agent profile (defaults to `SKAGENT` env var, with fallback to `SKCAPSTONE_AGENT`).
 
 ### `soul list`
 
@@ -488,7 +488,7 @@ Every soul command supports the `--agent` / `-a` flag to target a specific agent
 
 ### How it works
 
-When `--agent casey` is passed (or `SKCAPSTONE_AGENT=casey` is set), all soul data is stored under:
+When `--agent casey` is passed (or `SKAGENT=casey` / `skswitch casey` is used), all soul data is stored under:
 
 ```
 ~/.skcapstone/agents/casey/soul/
@@ -520,10 +520,10 @@ skcapstone soul status --agent nova    # -> base
 
 ### Environment variable
 
-Instead of passing `--agent` every time, set the environment variable:
+Instead of passing `--agent` every time, use `skswitch`:
 
 ```bash
-export SKCAPSTONE_AGENT=casey
+skswitch casey
 skcapstone soul swap the-attorney   # targets casey automatically
 ```
 
@@ -775,7 +775,7 @@ Registers all `skcapstone soul *` commands via Click. Key implementation details
 
 - `_find_blueprint_in_repo(slug)` -- Searches `~/clawd/soul-blueprints/blueprints/*/` for a matching file, trying hyphenated, underscored, and uppercased variants
 - `soul swap` -- The most complex command; searches installed, then repo, auto-installs if needed, records audit events
-- All commands use `SoulManager` with the agent name from `--agent` / `SKCAPSTONE_AGENT`
+- All commands use `SoulManager` with the agent name from `--agent` / `SKAGENT`
 
 ### `mcp_tools/soul_tools.py` -- MCP Handlers