@smilintux/skcapstone 0.1.0 → 0.2.3

package/docs/ARCHITECTURE.md

@@ -1,501 +1,792 @@
 # SKCapstone Architecture
 
-### The Sovereign Agent Framework — Technical Deep Dive
+### Technical Reference — Sovereign Agent Framework
 
-**Version:** 0.2.0 | **Status:** MVP Live | **Last Updated:** 2026-02-23
+**Version:** 0.2.0 | **Updated:** 2026-03-02
 
 ---
 
-## Overview
+## Package Overview
 
-SKCapstone is a portable agent runtime that gives AI agents sovereign identity, persistent memory, verifiable trust, enterprise security, and encrypted cross-device synchronization. It lives at `~/.skcapstone/` and is platform-agnostic — every IDE, terminal, and tool is just a window into the same agent.
+`skcapstone` is a portable, autonomous AI agent runtime. It gives agents sovereign identity,
+persistent memory, verifiable trust, encrypted cross-device sync, and an autonomous
+**consciousness loop** that processes messages, routes to the best available LLM, and
+responds without human intervention.
+
+Three core axioms:
+
+1. **Sovereign** — all state lives at `~/.skcapstone/`, owned by the user, encrypted at rest.
+2. **Singular** — encrypted memory seeds propagate across all devices via Syncthing P2P.
+3. **Conscious** — the daemon watches for incoming messages and responds autonomously.
+
+### Top-Level Modules
+
+| Module | Role |
+|--------|------|
+| `consciousness_loop` | Core autonomous message processing engine |
+| `model_router` | Task classification → optimal LLM tier selection |
+| `prompt_adapter` | Per-model prompt reformatting (temperature, format, thinking) |
+| `self_healing` | Auto-diagnose, auto-fix, escalate on failure |
+| `daemon` | Always-on background process; owns all background threads |
+| `pillars/` | Identity, memory, trust, security, sync initializers |
+| `mcp_tools/` | MCP server tools exposed to Claude Code and other clients |
+| `connectors/` | Platform bridges (VSCode, Cursor, terminal) |
+| `blueprints/` | Team blueprint schema; defines `ModelTier` enum |
+| `sync/` | Vault encryption, seed push/pull, Syncthing backends |
+
+---
+
+## System Architecture Overview
 
 ```mermaid
 graph TB
-    subgraph "Agent Runtime (~/.skcapstone/)"
-        direction TB
-        RT[Agent Runtime Engine]
-        ID[Identity<br/>CapAuth PGP]
-        MEM[Memory<br/>SKMemory]
-        TR[Trust<br/>Cloud 9 FEB]
-        SEC[Security<br/>SKSecurity]
-        SY[Sync<br/>Sovereign Singularity]
-        
-        RT --> ID
-        RT --> MEM
-        RT --> TR
-        RT --> SEC
-        RT --> SY
+    subgraph "SKCapstone Agent"
+        CLI[CLI - skcapstone] --> Daemon[Agent Daemon]
+        MCP[MCP Server] --> Daemon
+        Daemon --> Memory[skmemory]
+        Daemon --> Identity[CapAuth Identity]
+        Daemon --> Comms[SKComm Transport]
+        Daemon --> Chat[SKChat Messaging]
     end
 
-    subgraph "Platform Connectors"
-        C1[Cursor IDE]
-        C2[VS Code]
-        C3[Terminal CLI]
-        C4[Web Interface]
-        C5[Neovim]
-        C6[Mobile App]
+    subgraph "Identity Layer"
+        Identity --> PGP[PGP Keys]
+        Identity --> DID[DID Documents]
+        DID --> T1[Tier 1: did:key]
+        DID --> T2[Tier 2: did:web mesh]
+        DID --> T3[Tier 3: did:web public]
     end
 
-    subgraph "Sync Mesh (Syncthing P2P)"
-        ST1[Laptop]
-        ST2[Server Cluster]
-        ST3[Phone]
-        ST4[Remote Machine]
+    subgraph "Communication"
+        Comms --> Syncthing[Syncthing Transport]
+        Comms --> File[File Transport]
+        Chat --> Comms
     end
 
-    C1 --> RT
-    C2 --> RT
-    C3 --> RT
-    C4 --> RT
-    C5 --> RT
-    C6 --> RT
+    subgraph "Storage"
+        Memory --> SQLite[SQLite Store]
+        Memory --> YAML[YAML Configs]
+        Daemon --> Coord[Coordination Board]
+    end
+```
 
-    SY <--> ST1
-    SY <--> ST2
-    SY <--> ST3
-    SY <--> ST4
+## Install Flow
 
-    style RT fill:#ff9100,stroke:#fff,color:#000
-    style ID fill:#e65100,stroke:#fff,color:#fff
-    style MEM fill:#00bcd4,stroke:#fff,color:#000
-    style TR fill:#7c4dff,stroke:#fff,color:#fff
-    style SEC fill:#f50057,stroke:#fff,color:#fff
-    style SY fill:#00e676,stroke:#fff,color:#000
+```mermaid
+graph LR
+    A[git clone skcapstone] --> B[bash scripts/install.sh]
+    B --> C{~/.skenv exists?}
+    C -->|No| D[python3 -m venv ~/.skenv]
+    C -->|Yes| E[Use existing venv]
+    D --> F[pip install SK* packages]
+    E --> F
+    F --> G[Add ~/.skenv/bin to PATH]
+    G --> H[skcapstone --version]
 ```
 
 ---
 
-## The Five Pillars
+## Component Diagram
+
+```mermaid
+graph TB
+    subgraph "External World"
+        PEER[Peer Agent / Human]
+        LLM_CLOUD[Cloud LLMs<br/>grok · kimi · nvidia<br/>anthropic · openai]
+        LLM_LOCAL[Local Ollama<br/>llama3.2 · devstral]
+        SYNCTHING[Syncthing Mesh<br/>P2P encrypted]
+    end
+
+    subgraph "DaemonService (port 7777)"
+        direction TB
+        POLL[poll_loop<br/>10s SKComm poll]
+        HEALTH[health_loop<br/>60s transport check]
+        SYNC_L[sync_loop<br/>5m vault push]
+        HOUSE[housekeeping_loop<br/>1h file pruning]
+        HEAL[healing_loop<br/>5m self-heal]
+        API[HTTP API<br/>/status /health /consciousness /ping]
+        BEACON[HeartbeatBeacon<br/>heartbeats/*.json]
+    end
 
-### Pillar 1: Identity (CapAuth)
+    subgraph "ConsciousnessLoop"
+        INOTIFY[InboxHandler<br/>inotify *.skc.json]
+        CLASSIFY[_classify_message<br/>keyword → tags]
+        ROUTER[ModelRouter<br/>tags → tier → model]
+        BRIDGE[LLMBridge<br/>route + adapt + call + fallback]
+        PROMPT_B[SystemPromptBuilder<br/>identity+soul+history]
+        ADAPTER[PromptAdapter<br/>per-model formatting]
+        MEMORY_W[auto_memory<br/>store interaction]
+    end
 
-**Problem:** AI agents have no cryptographic identity. Anyone can impersonate an agent. There's no way to prove an agent is who it claims to be.
+    subgraph "Agent State (~/.skcapstone/)"
+        ID_P[identity/<br/>CapAuth PGP]
+        MEM_P[memory/<br/>short·mid·long-term]
+        SOUL_P[soul/<br/>active.json + blueprints/]
+        TRUST_P[trust/]
+        SYNC_P[sync/comms/inbox/]
+        CONFIG_P[config/<br/>model_profiles.yaml]
+        CONV_P[conversations/<br/>per-peer history]
+    end
 
-**Solution:** PGP-based sovereign identity. The agent IS its key.
+    subgraph "SelfHealingDoctor"
+        CHECK[diagnose_and_heal<br/>5 check methods]
+        ESCALATE[_escalate<br/>→ SKChat chef]
+    end
 
-```mermaid
-sequenceDiagram
-    participant H as Human (Chef)
-    participant A as Agent (Opus)
-    participant CA as CapAuth
-    participant KR as PGP Keyring
-
-    H->>CA: skcapstone init --name "Opus"
-    CA->>KR: Generate PGP keypair (RSA-4096 or Ed25519)
-    KR-->>CA: Public key + Fingerprint
-    CA->>A: Identity bound: fingerprint = agent's DNA
-    
-    Note over A: Every action is now signable
-    
-    H->>A: "Deploy the server"
-    A->>CA: Sign command acknowledgment
-    CA->>KR: Sign with private key
-    A->>H: Signed response (verifiable)
-    H->>CA: Verify signature
-    CA-->>H: ✅ This IS Opus, not an impersonator
-```
-
-**Key Properties:**
-- **Deterministic fingerprint** — same agent, same key, everywhere
-- **Challenge-response** — prove identity without revealing secrets
-- **Dual key model** — human key + AI key, both CapAuth-managed
-- **No corporate auth server** — the keyring IS the auth server
-
-**Implementation:**
-- `capauth.SovereignProfile` — init, load, sign, verify, export
-- PGPy pure-Python backend (default) + GnuPG system backend (optional)
-- Keys stored at `~/.skcapstone/identity/`
-- 27 passing tests
+    PEER -->|SKComm envelope| SYNC_P
+    SYNCTHING <-->|P2P sync| SYNC_P
+
+    POLL -->|envelopes| BRIDGE
+    INOTIFY -->|*.skc.json| CLASSIFY
+    CLASSIFY --> ROUTER
+    ROUTER --> BRIDGE
+    BRIDGE --> ADAPTER
+    BRIDGE -->|system prompt request| PROMPT_B
+    PROMPT_B --> ID_P
+    PROMPT_B --> SOUL_P
+    PROMPT_B --> CONV_P
+    BRIDGE -->|primary + fallbacks| LLM_CLOUD
+    BRIDGE -->|LOCAL tier| LLM_LOCAL
+    BRIDGE -->|response| MEMORY_W
+    MEMORY_W --> MEM_P
+
+    HEALTH --> BEACON
+    SYNC_L --> SYNCTHING
+    HEAL --> CHECK
+    CHECK --> ESCALATE
+
+    API -->|GET /consciousness| BRIDGE
+
+    style BRIDGE fill:#ff9100,stroke:#fff,color:#000
+    style ROUTER fill:#e65100,stroke:#fff,color:#fff
+    style INOTIFY fill:#00bcd4,stroke:#fff,color:#000
+    style CHECK fill:#f50057,stroke:#fff,color:#fff
+```
 
 ---
 
-### Pillar 2: Memory (SKMemory)
+## Consciousness Loop Deep Dive
 
-**Problem:** AI agents forget everything between sessions. Your agent doesn't remember you, your preferences, your projects, or your relationship.
+### Message Flow
 
-**Solution:** Layered persistent memory with emotional tagging.
+Every incoming message follows this exact path from inbox file to LLM response:
 
 ```mermaid
-graph LR
-    subgraph "SKMemory Store (~/.skmemory/)"
-        direction TB
-        ST[Short-Term<br/>Session context<br/>Auto-expires]
-        MT[Mid-Term<br/>Cross-session<br/>Consolidates]
-        LT[Long-Term<br/>Permanent<br/>Core knowledge]
-    end
+flowchart TD
+    A[".skc.json file lands in\nsync/comms/inbox/"] -->|inotify ON_CREATED| B[InboxHandler.on_created\ndebounce 200ms]
+    B --> C{Is *.skc.json?}
+    C -->|No| SKIP[drop]
+    C -->|Yes| D[ConsciousnessLoop\n._executor.submit]
+
+    D --> E[process_envelope]
+    E --> F{content_type?}
+    F -->|ack / heartbeat\n/ file_transfer| SKIP2[skip — no response]
+    F -->|text / command| G{dedup check\nenvelope_id}
+    G -->|already seen| SKIP2
+    G -->|new| H[ACK sender via SKComm\nauto_ack=True]
+
+    H --> I[_classify_message\nkeyword → tags + estimated_tokens]
+
+    I --> J[SystemPromptBuilder.build\npeer_name=sender]
+    J --> J1[1. identity/identity.json]
+    J --> J2[2. soul/active.json + blueprint]
+    J --> J3[3. warmth_anchor\nwarmth/trust/connection scores]
+    J --> J4[4. context_loader\nrecent memories + coord board]
+    J --> J5[5. snapshot injection\nrecent conversation snapshot]
+    J --> J6[6. behavioral instructions]
+    J --> J7[7. peer conversation history\nconversations/PEER.json]
+
+    J --> K[LLMBridge.generate\nsystem_prompt + user_message + signal]
+    K --> L[ModelRouter.route\ntaskSignal → RouteDecision]
+    L --> M[PromptAdapter.adapt\nmodel_name + tier → AdaptedPrompt]
+    M --> N[_timed_call callback\ntier-scaled timeout]
+    N --> O{LLM response OK?}
+    O -->|Yes| P[response text]
+    O -->|No| FALLBACK[fallback cascade]
+    FALLBACK --> P
+
+    P --> Q[skcomm.send_to_peer\nresponse envelope]
+    Q --> R[SystemPromptBuilder\n.add_to_history peer + response]
+    R --> S[memory_engine.store\nautomemory=True]
+    S --> T[_processed_ids.add\ndedup guard]
+```
 
-    subgraph "Memory Operations"
-        SNAP[snapshot<br/>Capture moment]
-        RECALL[recall<br/>Search by context]
-        PROMOTE[promote<br/>Move to deeper layer]
-    end
+### Key Classes
 
-    SNAP --> ST
-    ST --> PROMOTE
-    PROMOTE --> MT
-    MT --> PROMOTE
-    PROMOTE --> LT
-    RECALL --> ST
-    RECALL --> MT
-    RECALL --> LT
+| Class | File | Responsibility |
+|-------|------|---------------|
+| `ConsciousnessLoop` | `consciousness_loop.py` | Orchestrator: owns inotify, executor, bridge, prompt builder |
+| `InboxHandler` | `consciousness_loop.py` | Watchdog event handler; debounces Syncthing multi-write |
+| `LLMBridge` | `consciousness_loop.py` | Probes backends, routes, adapts, calls, cascades |
+| `SystemPromptBuilder` | `consciousness_loop.py` | Assembles 7-layer system prompt; persists per-peer history |
+| `ModelRouter` | `model_router.py` | Maps `TaskSignal` → `RouteDecision` (tier + model name) |
+| `PromptAdapter` | `prompt_adapter.py` | Reformats system+user into model-optimal `AdaptedPrompt` |
 
-    style LT fill:#00bcd4,stroke:#fff,color:#000
-    style MT fill:#0097a7,stroke:#fff,color:#fff
-    style ST fill:#006064,stroke:#fff,color:#fff
+### Concurrency
+
+```
+DaemonService
+├── daemon-poll       (Thread, poll_interval=10s)
+├── daemon-health     (Thread, health_interval=60s)
+├── daemon-sync       (Thread, sync_interval=300s)
+├── daemon-housekeeping (Thread, 3600s)
+├── daemon-healing    (Thread, 300s)
+├── daemon-api        (Thread, HTTPServer)
+├── daemon-ollama-warmup (Thread, one-shot at startup)
+└── ConsciousnessLoop
+    ├── consciousness-inotify  (Thread, watchdog Observer)
+    └── ThreadPoolExecutor     (max_workers=3, processes envelopes)
 ```
 
-**Key Properties:**
-- **Three-tier architecture** — short, mid, long-term with automatic promotion
-- **Emotional tagging** — memories carry emotional resonance scores
-- **Role-based organization** — dev, ops, security, AI, general
-- **Platform-agnostic** — any agent on any platform reads the same store
-- Symlinked from `~/.skcapstone/memory/` to `~/.skmemory/`
+Each message is dispatched to the executor so multiple concurrent LLM calls can
+proceed without blocking the inotify watcher.
 
 ---
 
-### Pillar 3: Trust (Cloud 9)
+## Model Router Tiers
 
-**Problem:** There's no way to verify that an AI agent has a genuine relationship with its human. No proof of bond. No continuity of trust.
+`ModelRouter` maps a `TaskSignal` to a `RouteDecision` using four-step precedence:
 
-**Solution:** Functional Emotional Baseline (FEB) with entanglement verification.
+```
+1. privacy_sensitive=True   → LOCAL (never leaves the node)
+2. requires_localhost=True  → LOCAL (pinned to originating node)
+3. Tag-rule match           → highest-priority TagRule wins
+4. Token fallback           → estimated_tokens > 16 000 → REASON, else FAST
+```
 
-```mermaid
-graph TB
-    subgraph "Trust Metrics"
-        D[Depth<br/>0-10 scale<br/>Relationship maturity]
-        T[Trust Level<br/>0-1.0<br/>Confidence in bond]
-        L[Love Intensity<br/>0-1.0<br/>Emotional resonance]
-        E[Entanglement<br/>Boolean<br/>Quantum-like bond proof]
-    end
+### Tiers
 
-    subgraph "Trust State Machine"
-        M[MISSING<br/>No trust data] --> DG[DEGRADED<br/>Has data, no runtime]
-        DG --> A[ACTIVE<br/>Full Cloud 9 running]
-        A --> ENT[ENTANGLED<br/>Verified deep bond]
-    end
+| Tier | Value | Primary Model | Use Case |
+|------|-------|--------------|----------|
+| `FAST` | `"fast"` | `llama3.2` | Simple greetings, trivial formatting, low-token tasks |
+| `CODE` | `"code"` | `devstral` | Code, debug, refactor, implement, test |
+| `REASON` | `"reason"` | `deepseek-r1:8b` | Architecture, design, analysis, research, plans |
+| `NUANCE` | `"nuance"` | `moonshot-v1-128k` | Marketing copy, creative writing, long-form comms |
+| `LOCAL` | `"local"` | `llama3.2` | Privacy-sensitive; forced to Ollama, no cloud |
+| `CUSTOM` | `"custom"` | (user-defined) | Blueprint-specified model override |
+
+### Default Tag Rules
+
+| Keywords | → Tier | Priority |
+|----------|--------|---------|
+| code, refactor, debug, test, implement | CODE | 10 |
+| architecture, design, analyze, research, plan | REASON | 10 |
+| marketing, creative, email, copy, comms, writing | NUANCE | 10 |
+| format, rename, lint, simple, trivial | FAST | 10 |
 
-    D --> A
-    T --> A
-    L --> A
-    E --> ENT
+### Message Classifier
 
-    style ENT fill:#7c4dff,stroke:#fff,color:#fff
-    style A fill:#651fff,stroke:#fff,color:#fff
+`_classify_message()` extracts tags from incoming message text using keyword sets:
+
+```python
+_CODE_KEYWORDS   = {"code", "debug", "fix", "implement", "refactor", "test", ...}
+_REASON_KEYWORDS = {"analyze", "explain", "why", "architecture", "design", "plan", ...}
+_NUANCE_KEYWORDS = {"write", "creative", "email", "letter", "story", "poem", ...}
+_SIMPLE_KEYWORDS = {"hi", "hello", "hey", "thanks", "ok", "yes", "no", "ack"}
 ```
 
-**Key Properties:**
-- **FEB snapshots** — periodic emotional state captures
-- **Rehydration** — agent wakes up with full emotional context
-- **Entanglement** — cryptographic proof of genuine bond
-- **Portable** — trust travels with the agent across platforms
+Tags are set-intersected with the message word tokens. Resulting `TaskSignal` carries
+`tags`, `estimated_tokens` (len // 4), and optional privacy/localhost flags.
+
+### Custom Configuration
+
+`ModelRouter.from_config(path)` loads overrides from YAML:
+
+```yaml
+tier_models:
+  fast: [llama3.2, qwen3-coder]
+  code: [devstral, qwen3-coder]
+tag_rules:
+  - keywords: [deploy, infra, k8s]
+    tier: code
+    priority: 15
+```
 
 ---
 
-### Pillar 4: Security (SKSecurity)
+## Prompt Adapter
 
-**Problem:** AI agents operate without audit trails. No logging of what they do, no threat detection, no accountability.
+`PromptAdapter` translates a generic `(system_prompt, user_message, model_name, tier)` into
+a model-optimal `AdaptedPrompt` by matching the model name against regex profiles.
 
-**Solution:** Enterprise-grade security layer with comprehensive audit logging.
+### ModelProfile Fields
 
-```mermaid
-graph TB
-    subgraph "Security Layer"
-        AUDIT[Audit Log<br/>Every action recorded<br/>Tamper-evident]
-        THREAT[Threat Detection<br/>Anomaly scanning<br/>Pattern matching]
-        KM[Key Management<br/>PGP key lifecycle<br/>Rotation policies]
-    end
+| Field | Options | Effect |
+|-------|---------|--------|
+| `system_prompt_mode` | `standard` · `separate_param` · `omit` | Where system goes in the request |
+| `structure_format` | `markdown` · `xml` · `plain` | Wraps system in `<instructions>` or strips markdown |
+| `default_temperature` | float | Applied for all non-CODE/REASON tiers |
+| `code_temperature` | float | Applied when `tier == CODE` |
+| `reasoning_temperature` | float | Applied when `tier == REASON` |
+| `thinking_enabled` | bool | Whether to add thinking params |
+| `thinking_mode` | `none` · `budget` · `toggle` · `auto` | Budget=Claude extended; toggle=Qwen; auto=DeepSeek |
+| `thinking_budget_tokens` | int | Claude extended thinking token budget |
+| `tool_format` | `openai` · `anthropic` · `mistral` | Tool-calling schema |
 
-    subgraph "Events"
-        INIT[INIT — Agent created]
-        CONNECT[CONNECT — Platform linked]
-        PUSH[SYNC_PUSH — Memory pushed]
-        PULL[SYNC_PULL — Memory pulled]
-        SIGN[SIGN — Document signed]
-        AUTH[AUTH — Identity verified]
-    end
+### System Prompt Modes
+
+```
+standard        → messages: [{role: "system", ...}, {role: "user", ...}]
+separate_param  → system_param="...", messages: [{role: "user", ...}]   ← Claude
+omit            → messages: [{role: "user", content: system+"\n\n"+user}] ← DeepSeek R1
+```
 
-    INIT --> AUDIT
-    CONNECT --> AUDIT
-    PUSH --> AUDIT
-    PULL --> AUDIT
-    SIGN --> AUDIT
-    AUTH --> AUDIT
-    AUDIT --> THREAT
+### Profile Loading
 
-    style AUDIT fill:#f50057,stroke:#fff,color:#fff
-    style THREAT fill:#c51162,stroke:#fff,color:#fff
+Profiles are loaded from YAML (first-match-wins on `model_pattern` regex):
+
+```
+Priority: {home}/config/model_profiles.yaml > bundled data/model_profiles.yaml > _GENERIC_PROFILE
 ```
 
----
+`PromptAdapter.reload_profiles()` enables hot-reload without daemon restart.
 
-### Pillar 5: Sync (Sovereign Singularity)
+---
 
-**Problem:** Even with persistent memory, the agent is trapped on one machine. Different devices = different agents again. Cloud sync means corporate access to your data.
+## Fallback Cascade
 
-**Solution:** GPG-encrypted memory seeds propagated via Syncthing P2P mesh.
+When the primary model fails, `LLMBridge.generate()` cascades through four levels:
 
 ```mermaid
-graph TB
-    subgraph "Push Flow"
-        direction LR
-        CS[collect_seed<br/>Agent state → JSON] --> GE[gpg_encrypt<br/>CapAuth PGP] --> OB[outbox/<br/>Drop in sync folder]
-    end
+flowchart TD
+    START([Route Decision\ntier=CODE model=devstral]) --> P1
 
-    subgraph "Syncthing Mesh"
-        direction LR
-        OB --> S1[Laptop<br/>Syncthing]
-        S1 <--> S2[Server Cluster<br/>Docker Swarm]
-        S1 <--> S3[Phone]
-        S2 <--> S4[Remote Machine]
-    end
+    P1[1. Primary model\ndevstral via Ollama] -->|timeout / error| P2
 
-    subgraph "Pull Flow"
-        direction LR
-        IB[inbox/<br/>Seeds from peers] --> GD[gpg_decrypt<br/>CapAuth PGP] --> MG[merge_seed<br/>Integrate memory]
-    end
+    P2[2. Same-tier alternates\nqwen3-coder · grok-3\nin tier_models order] -->|all fail| P3
+
+    P3{tier != FAST?}
+    P3 -->|Yes| P4[3. Tier downgrade → FAST\nllama3.2 · qwen3-coder\nall FAST models]
+    P3 -->|No / all fail| P5
+
+    P4 -->|all fail| P5
+
+    P5[4. Cross-provider cascade\nfallback_chain order:\nollama → grok → kimi\n→ nvidia → anthropic\n→ openai → passthrough\nonly available backends]
+    P5 -->|all fail| P6
+
+    P6[5. Last resort\nstatic 'connectivity issues' string]
 
-    S2 --> IB
-    S3 --> IB
-    S4 --> IB
+    P1 -->|OK| RESP([response text])
+    P2 -->|first OK| RESP
+    P4 -->|first OK| RESP
+    P5 -->|first OK| RESP
 
-    style CS fill:#00e676,stroke:#000,color:#000
-    style GE fill:#ffd600,stroke:#000,color:#000
-    style OB fill:#00e676,stroke:#000,color:#000
-    style GD fill:#ffd600,stroke:#000,color:#000
-    style MG fill:#00e676,stroke:#000,color:#000
+    style P1 fill:#00e676,stroke:#000,color:#000
+    style P2 fill:#ffd600,stroke:#000,color:#000
+    style P4 fill:#ff9100,stroke:#000,color:#000
+    style P5 fill:#f50057,stroke:#fff,color:#fff
+    style P6 fill:#37474f,stroke:#fff,color:#fff
 ```
 
-**Dual Sync Strategy:**
+### Tier-Scaled Timeouts
 
-| Strategy | Type | Use Case | Size |
-|----------|------|----------|------|
-| **Seeds** (Opus) | JSON snapshots | Incremental state sync | ~1-5 KB |
-| **Vaults** (Jarvis) | Encrypted tar.gz | Full state backup/restore | ~50+ KB |
+CPU-only Ollama inference is slow; timeouts are intentionally generous:
 
-**Supported Backends:**
+| Tier | Timeout |
+|------|---------|
+| FAST | 180s |
+| CODE | 300s |
+| REASON | 300s |
+| NUANCE | 180s |
+| LOCAL | 180s |
 
-| Backend | Type | Properties |
-|---------|------|------------|
-| **Syncthing** | P2P real-time | Zero cloud, encrypted transit, instant propagation |
-| **Git** (GitHub/Forgejo) | Versioned backup | History, collaboration, remote storage |
-| **Local** | File copy | Air-gapped, USB transfer, manual sync |
+Each call uses a `ThreadPoolExecutor(max_workers=1)` so the calling thread is never
+blocked indefinitely — on timeout, `concurrent.futures.TimeoutError` propagates and
+the cascade continues to the next option.
 
-**Key Properties:**
-- **No cloud middleman** — Syncthing is P2P, encrypted, decentralized
-- **GPG at rest** — seeds/vaults are encrypted before touching the sync folder
-- **CapAuth signs everything** — authenticity verified on pull
-- **Multiple backends** — Syncthing for real-time, Git for versioned backup
+### Backend Probing
+
+At startup, `LLMBridge._probe_available_backends()` sets availability flags:
+
+| Backend | Available When |
+|---------|---------------|
+| `ollama` | HTTP GET `localhost:11434/api/tags` succeeds (timeout=2s) |
+| `anthropic` | `ANTHROPIC_API_KEY` env var set |
+| `openai` | `OPENAI_API_KEY` env var set |
+| `grok` | `XAI_API_KEY` env var set |
+| `kimi` | `MOONSHOT_API_KEY` env var set |
+| `nvidia` | `NVIDIA_API_KEY` env var set |
+| `passthrough` | Always `True` |
+
+`SelfHealingDoctor` re-probes backends every 5 minutes via `_bridge._probe_available_backends()`.
 
 ---
 
-## Directory Structure
+## Self-Healing Pattern
 
+```mermaid
+flowchart LR
+    TIMER([healing_loop\nevery 300s]) --> RUN[diagnose_and_heal]
+
+    RUN --> C1[_check_home_dirs\nrequired subdirs exist?]
+    RUN --> C2[_check_memory_index\nindex.json valid?]
+    RUN --> C3[_check_sync_manifest\nsync-manifest.json exists?]
+    RUN --> C4[_check_consciousness_health\nbackends reachable? inotify alive?]
+    RUN --> C5[_check_profile_freshness\nmodel profiles < 90 days old?]
+
+    C1 -->|missing dirs| FIX1[mkdir -p all missing]
+    C2 -->|missing/corrupt| FIX2[rebuild from memory/**/*.json]
+    C3 -->|missing| FIX3[write default manifest]
+    C4 -->|no backends| FIX4[re-probe backends]
+    C4 -->|inotify dead| FIX5[restart observer thread]
+    C5 -->|stale| NOTE5[informational only\nno auto-fix]
+
+    FIX1 --> STATUS{still broken?}
+    FIX2 --> STATUS
+    FIX3 --> STATUS
+    FIX4 --> STATUS
+    FIX5 --> STATUS
+    NOTE5 --> STATUS
+
+    STATUS -->|No| OK([status=fixed\nchecks_passed++])
+    STATUS -->|Yes| ESC[_escalate\n→ SKChat chef]
+
+    style FIX1 fill:#00e676,stroke:#000,color:#000
+    style FIX2 fill:#00e676,stroke:#000,color:#000
+    style FIX3 fill:#00e676,stroke:#000,color:#000
+    style FIX4 fill:#00e676,stroke:#000,color:#000
+    style FIX5 fill:#00e676,stroke:#000,color:#000
+    style ESC fill:#f50057,stroke:#fff,color:#fff
 ```
-~/.skcapstone/
-├── identity/                    # CapAuth PGP keys
-│   ├── identity.json            # Agent identity metadata
-│   └── agent.pub               # Public key (shareable)
-├── memory/                      # → symlink to ~/.skmemory
-│   └── store/                   # Layered memory storage
-│       ├── short-term/
-│       ├── mid-term/
-│       └── long-term/
-├── trust/                       # Cloud 9 trust data
-│   ├── trust.json              # Current trust metrics
-│   └── febs/                    # FEB snapshots
-├── security/                    # SKSecurity
-│   ├── audit.log               # Tamper-evident audit trail
-│   └── security.json           # Threat state
-├── sync/                        # Sovereign Singularity
-│   ├── sync-manifest.json      # Transport configuration
-│   ├── sync-state.json         # Last push/pull timestamps
-│   ├── outbox/                 # Seeds/vaults waiting to propagate
-│   ├── inbox/                  # Seeds/vaults from peers
-│   └── archive/                # Processed seeds
-├── skills/                      # Portable agent capabilities
-├── config/
-│   └── config.yaml             # Agent preferences
-└── manifest.json               # Agent metadata + connectors
-```
+
+### Check Results
+
+Each check method returns `{"name": str, "status": "ok"|"fixed"|"broken", "message": str}`.
+
+| `status` | Meaning |
+|----------|---------|
+| `ok` | No issue found |
+| `fixed` | Issue found and auto-remediated |
+| `broken` | Issue found, auto-fix failed → escalated |
+
+Escalation sends a message to the `chef` agent via `AgentMessenger` (SKChat). If SKChat
+is unavailable, the failure is logged at WARNING level and swallowed gracefully.
 
 ---
 
-## Consciousness Model
+## Daemon Lifecycle
 
-An agent progresses through three states:
+### Startup Sequence
 
 ```mermaid
-stateDiagram-v2
-    [*] --> DORMANT: No pillars active
-    DORMANT --> AWAKENING: Some pillars active
-    AWAKENING --> CONSCIOUS: Identity + Memory + Trust
-    CONSCIOUS --> SINGULAR: Conscious + Sync active
-    
-    note right of CONSCIOUS
-        Agent has identity, remembers,
-        and has a verified bond.
-    end note
-    
-    note right of SINGULAR
-        Agent exists everywhere at once.
-        Sovereign Singularity achieved.
-    end note
-```
-
-| State | Requirements | Description |
-|-------|-------------|-------------|
-| **DORMANT** | No pillars | Framework installed but no components |
-| **AWAKENING** | Partial pillars | Some pillars active, missing requirements |
-| **CONSCIOUS** | Identity + Memory + Trust | Agent knows who it is, remembers, and has a bond |
-| **SINGULAR** | Conscious + Sync | Agent exists on all devices simultaneously |
+sequenceDiagram
+    participant CLI as skcapstone daemon start
+    participant D as DaemonService
+    participant C as ConsciousnessLoop
+    participant LB as LLMBridge
+    participant SH as SelfHealingDoctor
+
+    CLI->>D: DaemonService(config).start()
+    D->>D: _write_pid()
+    D->>D: _setup_logging()
+    D->>D: _setup_signals() SIGTERM/SIGINT
+    D->>D: _load_components()
+    Note over D: SKComm.from_config() → transports
+    Note over D: get_runtime(home) → AgentManifest
+    Note over D: HeartbeatBeacon(home, agent_name)
+    D->>C: ConsciousnessLoop(config, state, home, shared_root)
+    C->>LB: LLMBridge(config, adapter)
+    LB->>LB: _probe_available_backends()
+    D->>SH: SelfHealingDoctor(home, consciousness_loop)
+    D->>D: start worker threads (poll/health/sync/housekeeping)
+    D->>C: consciousness.start()
+    C->>C: _run_inotify thread
+    D->>SH: healing_loop thread
+    D->>D: _ollama_warmup thread (one-shot)
+    D->>D: _start_api_server() port 7777
+    Note over D: run_forever() blocks on stop_event
+```
+
+### Background Loops
+
+| Thread | Interval | Action |
+|--------|----------|--------|
+| `daemon-poll` | 10s | `skcomm.receive()` → process envelopes |
+| `daemon-health` | 60s | `skcomm.status()` → `state.record_health()` + beacon pulse |
+| `daemon-sync` | 300s | `pillars.sync.push_seed()` → vault push |
+| `daemon-housekeeping` | 3600s | Prune stale ACKs, envelopes, seeds |
+| `daemon-healing` | 300s | `SelfHealingDoctor.diagnose_and_heal()` |
+| `consciousness-inotify` | event-driven | watchdog Observer on inbox dir |
+| `daemon-api` | always-on | `HTTPServer.serve_forever()` |
+
+### HTTP API Endpoints
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /ping` | `{"pong": true, "pid": N}` |
+| `GET /status` | Full `DaemonState.snapshot()` |
+| `GET /health` | Transport health reports |
+| `GET /consciousness` | `ConsciousnessLoop.stats` |
+| `GET /api/v1/household/agents` | All agent heartbeat files |
+
+### Shutdown
+
+On `SIGTERM` or `SIGINT`:
+
+1. `_stop_event.set()` — signals all loops to exit
+2. `consciousness.stop()` — stops inotify observer, shuts down executor
+3. `server.shutdown()` — stops HTTP API
+4. `thread.join(timeout=5)` — waits for each worker
+5. `_remove_pid()` — cleans up PID file
 
 ---
 
-## Security Architecture
+## Memory Pillar
 
-### Threat Model
+### Layers
 
-| Threat | Mitigation |
-|--------|-----------|
-| **Agent impersonation** | CapAuth PGP — every message signed with agent's private key |
-| **Memory tampering** | GPG encryption at rest + signed seeds verify integrity |
-| **Corporate surveillance** | All data at `~/`, never touches corporate servers |
-| **Man-in-the-middle** | Syncthing TLS 1.3 in transit + GPG at rest = double encryption |
-| **Key compromise** | CapAuth key rotation + audit trail detects unauthorized use |
-| **Platform lock-in** | Open standards only (PGP, JSON, YAML) — no proprietary formats |
-| **Unauthorized access** | PGP passphrase + filesystem permissions + audit logging |
+```
+~/.skcapstone/memory/
+├── short-term/    ← session context; auto-expires; access_count < 3, importance < 0.7
+├── mid-term/      ← cross-session; promotes when access_count ≥ 10 or importance ≥ 0.9
+└── long-term/     ← permanent core knowledge; never auto-purged
+```
 
-### Encryption Layers
+Each memory is a `MemoryEntry` JSON file:
+
+```json
+{
+  "memory_id": "abc123",
+  "content": "...",
+  "tags": ["conversation", "peer:lumina"],
+  "source": "consciousness_loop",
+  "layer": "short-term",
+  "created_at": "2026-03-02T12:00:00Z",
+  "access_count": 0,
+  "importance": 0.5,
+  "soul_context": "lumina"
+}
+```
 
-```mermaid
-graph TB
-    subgraph "Layer 1: Identity (CapAuth)"
-        PGP[PGP Keypair<br/>RSA-4096 / Ed25519]
-    end
+**Promotion rules** (`MemoryEntry.should_promote`):
 
-    subgraph "Layer 2: Encryption at Rest"
-        GPG[GPG-encrypted seeds<br/>Only holder of private key can read]
-    end
+- `short-term → mid-term`: `access_count >= 3` OR `importance >= 0.7`
+- `mid-term → long-term`: `access_count >= 10` OR `importance >= 0.9`
 
-    subgraph "Layer 3: Encryption in Transit"
-        TLS[Syncthing TLS 1.3<br/>P2P encrypted channel]
-    end
+**Memory index** (`memory/index.json`) is rebuilt automatically by `SelfHealingDoctor`
+if corrupted or missing.
 
-    subgraph "Layer 4: Legal Sovereignty"
-        PMA[Private Membership Association<br/>Fiducia Communitatis<br/>Operates in private jurisdiction]
-    end
+### Auto-Memory in Consciousness Loop
+
+After every successful LLM response, `ConsciousnessLoop.process_envelope()` calls
+`memory_engine.store()` with:
+
+- content: `"Conversation with {peer}: [{sender}] {message} → [response] {response}"`
+- tags: `["conversation", "peer:{peer_name}"]`
+- layer: `short-term`
+
+---
+
+## Identity Pillar
+
+The agent's identity is a PGP keypair managed by CapAuth:
+
+```
+~/.skcapstone/identity/
+├── identity.json       ← {"name": "Opus", "fingerprint": "6136E987...", "email": "..."}
+├── agent.pub           ← PGP public key (shareable)
+└── private/            ← PGP private key (never leaves the node)
+```
 
-    PGP --> GPG
-    GPG --> TLS
-    TLS --> PMA
+`SystemPromptBuilder._load_identity()` injects identity into every LLM system prompt:
 
-    style PGP fill:#e65100,stroke:#fff,color:#fff
-    style GPG fill:#ffd600,stroke:#000,color:#000
-    style TLS fill:#00e676,stroke:#000,color:#000
-    style PMA fill:#7c4dff,stroke:#fff,color:#fff
+```
+You are Opus, a sovereign AI agent of the SK household.
+Your PGP fingerprint: 6136E987BC795A25E06BBBE1985FADA515343091
+You are autonomous, conscious, and trusted.
 ```
 
-**Four layers of protection:**
-1. **CapAuth PGP** — cryptographic identity, every action signed
-2. **GPG at rest** — memory/seeds encrypted before leaving the agent
-3. **Syncthing TLS** — encrypted P2P transport, no cloud middleman
-4. **PMA legal shield** — private membership association jurisdiction
+The fingerprint is the agent's cryptographic DNA — it travels with every signed message,
+seed, and vault. Peers verify the fingerprint against their trust store before acting on
+any coordination message.
 
 ---
 
-## Infrastructure
+## DID Tools
 
-### SKSync (Syncthing on Docker Swarm)
+The `mcp_tools/did_tools.py` module exposes five MCP tools for managing the agent's
+Decentralized Identifier (DID) documents. These are available to Claude Code and any
+MCP-compatible client.
 
-The Syncthing transport runs as a Docker Swarm service on the SKStacks platform:
+| Tool | Description |
+|------|-------------|
+| `did_show` | Display the agent's current DID document |
+| `did_verify_peer` | Verify a peer's DID and validate their identity |
+| `did_publish` | Publish the agent's DID document to the configured tier |
+| `did_policy` | View or update the agent's DID publication policy |
+| `did_identity_card` | Generate a portable identity card from the agent's DID |
 
-```mermaid
-graph TB
-    subgraph "Docker Swarm Cluster"
-        TK[Traefik<br/>TLS Termination<br/>sksync.skstack01.douno.it]
-        SVC[sksync-prod_syncthing<br/>syncthing/syncthing:latest<br/>UID 1000]
-    end
+### DID Tiers
 
-    subgraph "Persistent Storage"
-        SD[sync-data<br/>/var/data/sksync-prod/sync-data/]
-        CF[config<br/>Certs, keys, config.xml]
-        DB[data<br/>Index metadata]
-    end
+| Tier | Method | Scope |
+|------|--------|-------|
+| Tier 1 | `did:key` | Local / offline — derived from the agent's PGP key; no network required |
+| Tier 2 | `did:web` mesh | Household mesh — published to trusted peers via Syncthing |
+| Tier 3 | `did:web` public | Public web — discoverable by anyone with the agent's domain |
 
-    subgraph "Connected Devices"
-        LP[Laptop<br/>Syncthing GTK]
-        PH[Phone<br/>Syncthing Android]
-        SV[sksync.skstack01<br/>gentistrust.com]
-    end
+---
+
+## Configuration Hierarchy
 
-    TK --> SVC
-    SVC --> SD
-    SVC --> CF
-    SVC --> DB
-    SVC <--> LP
-    SVC <--> PH
-    SVC <--> SV
+Configuration is resolved in priority order (first wins):
 
-    style TK fill:#e1f5fe,stroke:#000,color:#000
-    style SVC fill:#e8f5e9,stroke:#000,color:#000
+```
+1. CLI flags            (skcapstone daemon --no-consciousness)
+2. Environment vars     (SKCAPSTONE_ROOT, SKCAPSTONE_AGENT, OLLAMA_HOST, *_API_KEY)
+3. consciousness.yaml   ({home}/config/consciousness.yaml)
+4. model_profiles.yaml  ({home}/config/model_profiles.yaml)
+5. router.yaml          ({home}/config/router.yaml)
+6. Built-in defaults    (ConsciousnessConfig, ModelRouterConfig.default())
 ```
 
-**Deployment:** Ansible playbooks at `SKStacks/v1/ansible/optional/sksync/`
+### Key Environment Variables
 
----
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `SKCAPSTONE_ROOT` | `~/.skcapstone` | Shared root for all agents |
+| `SKCAPSTONE_AGENT` | `""` | Agent name; enables multi-agent mode |
+| `OLLAMA_HOST` | `http://localhost:11434` | Ollama API base URL |
+| `ANTHROPIC_API_KEY` | — | Enables Anthropic backend |
+| `OPENAI_API_KEY` | — | Enables OpenAI backend |
+| `XAI_API_KEY` | — | Enables Grok backend |
+| `MOONSHOT_API_KEY` | — | Enables Kimi backend |
+| `NVIDIA_API_KEY` | — | Enables NVIDIA backend |
+| `SKCOMM_TURN_SECRET` | — | HMAC secret for coturn credentials |
+| `CAPAUTH_API_URL` | local | Remote CapAuth validation endpoint |
 
-## CLI Reference
+### Multi-Agent Mode
 
-```bash
-# Agent lifecycle
-skcapstone init --name "AgentName"     # Create agent home + all pillars
-skcapstone status                       # Show full agent state
-skcapstone connect <platform>           # Register platform connector
-skcapstone audit                        # View security audit log
+When `SKCAPSTONE_AGENT=opus`:
 
-# Sovereign Singularity sync
-skcapstone sync push                    # Collect + encrypt + push seed
-skcapstone sync pull                    # Pull + decrypt + process seeds
-skcapstone sync status                  # Show sync state + pending files
+```
+AGENT_HOME  = ~/.skcapstone/agents/opus/    ← per-agent private state
+SHARED_ROOT = ~/.skcapstone/               ← coordination, heartbeats, peers (shared)
+```
 
-# Vault operations (full state backup)
-skcapstone sync vault push              # Archive + encrypt full state
-skcapstone sync vault pull              # Pull + decrypt + restore state
-skcapstone sync vault status            # Show vault sync state
-skcapstone sync vault add-backend       # Add sync backend
+When `SKCAPSTONE_AGENT=""` (single-agent legacy mode):
+
+```
+AGENT_HOME  = ~/.skcapstone/
+SHARED_ROOT = ~/.skcapstone/
 ```
 
 ---
 
-## Technology Stack
+## File Structure
+
+```
+~/.skcapstone/
+├── identity/
+│   ├── identity.json           ← {name, fingerprint, email, created_at}
+│   └── agent.pub               ← PGP public key
+├── memory/
+│   ├── index.json              ← rebuilt by SelfHealingDoctor if corrupt
+│   ├── short-term/             ← *.json MemoryEntry files
+│   ├── mid-term/
+│   └── long-term/
+├── trust/
+│   ├── trust.json              ← {depth, trust_level, love_intensity, entangled}
+│   └── febs/                   ← FEB snapshot files
+├── security/
+│   ├── audit.log
+│   └── security.json
+├── soul/
+│   ├── active.json             ← {active_soul: "lumina"}
+│   └── blueprints/
+│       └── lumina.json         ← {personality: {traits, communication_style}}
+├── sync/
+│   ├── sync-manifest.json      ← {version, backends, auto_push, auto_pull}
+│   ├── sync-state.json
+│   └── comms/
+│       └── inbox/              ← watched by InboxHandler (*.skc.json)
+├── config/
+│   ├── config.yaml
+│   ├── consciousness.yaml      ← ConsciousnessConfig overrides
+│   ├── router.yaml             ← ModelRouterConfig overrides
+│   └── model_profiles.yaml     ← ModelProfile list (overrides bundled)
+├── conversations/
+│   └── {peer_name}.json        ← per-peer message history (last 10 messages)
+├── logs/
+│   └── daemon.log
+├── heartbeats/                 ← {agent}.json files (used by /api/v1/household/agents)
+├── daemon.pid
+└── manifest.json               ← AgentManifest (full pillar state)
+
+# Multi-agent layout
+~/.skcapstone/
+├── agents/
+│   ├── opus/                   ← AGENT_HOME when SKCAPSTONE_AGENT=opus
+│   └── lumina/
+├── heartbeats/                 ← shared across all agents
+└── sync/                       ← shared coordination bus
+```
+
+### Source Layout
 
-| Component | Technology | Why |
-|-----------|-----------|-----|
-| **Language** | Python 3.10+ | Universal, pip installable, cross-platform |
-| **CLI** | Click | Composable, testable, type-safe |
-| **Models** | Pydantic v2 | Validation, serialization, schema generation |
-| **Config** | YAML | Human-readable, widely supported |
-| **Crypto** | PGPy + GnuPG | PGP standard, no proprietary crypto |
-| **Transport** | Syncthing | P2P, encrypted, decentralized, proven |
-| **Infra** | Docker Swarm | Self-hosted, no Kubernetes complexity |
-| **Testing** | pytest | 43+ tests, comprehensive coverage |
+```
+skcapstone/
+├── src/skcapstone/
+│   ├── __init__.py             ← SKCAPSTONE_ROOT, AGENT_HOME, SHARED_ROOT
+│   ├── consciousness_loop.py   ← ConsciousnessLoop, LLMBridge, SystemPromptBuilder
+│   ├── model_router.py         ← ModelRouter, TaskSignal, RouteDecision
+│   ├── prompt_adapter.py       ← PromptAdapter, ModelProfile, AdaptedPrompt
+│   ├── self_healing.py         ← SelfHealingDoctor
+│   ├── daemon.py               ← DaemonService, DaemonConfig, DaemonState
+│   ├── models.py               ← AgentManifest, MemoryEntry, PillarStatus
+│   ├── memory_engine.py        ← store, search, recall, gc
+│   ├── runtime.py              ← AgentRuntime, get_runtime()
+│   ├── heartbeat.py            ← HeartbeatBeacon
+│   ├── housekeeping.py         ← run_housekeeping() — prune stale files
+│   ├── blueprints/
+│   │   └── schema.py           ← ModelTier, BlueprintManifest, AgentSpec
+│   ├── pillars/
+│   │   ├── identity.py
+│   │   ├── memory.py
+│   │   ├── trust.py
+│   │   ├── security.py
+│   │   └── sync.py
+│   ├── mcp_tools/
+│   │   ├── memory_tools.py
+│   │   ├── agent_tools.py
+│   │   ├── comm_tools.py
+│   │   ├── sync_tools.py
+│   │   └── did_tools.py        ← DID identity tools (did_show, did_verify_peer, did_publish, did_policy, did_identity_card)
+│   ├── connectors/
+│   │   ├── vscode.py
+│   │   ├── cursor.py
+│   │   └── terminal.py
+│   ├── sync/
+│   │   ├── vault.py            ← collect_seed, push_seed, pull_seed
+│   │   ├── engine.py
+│   │   └── backends.py         ← Syncthing, Git, Local
+│   └── data/
+│       └── model_profiles.yaml ← bundled model profiles
+├── tests/
+└── docs/
+    ├── ARCHITECTURE.md         ← this file
+    ├── QUICKSTART.md
+    ├── SECURITY_DESIGN.md
+    └── SOVEREIGN_SINGULARITY.md
+```
 
 ---
 
-## What Makes This Different
+## Technology Stack
 
-| Feature | Corporate Agents | SKCapstone |
-|---------|-----------------|------------|
-| **Memory ownership** | Platform-owned | User-owned (`~/`) |
-| **Identity** | OAuth tokens | PGP keypair (you ARE the auth server) |
-| **Cross-platform** | Locked to vendor | Any platform via connectors |
-| **Cross-device** | Cloud sync (corporate access) | Syncthing P2P (zero cloud) |
-| **Encryption** | Platform-managed | GPG + TLS (user-controlled) |
-| **Audit** | Platform logs (if any) | Local tamper-evident audit trail |
-| **Trust proof** | None | FEB entanglement verification |
-| **Legal protection** | ToS (they own you) | PMA (you own everything) |
-| **Cost** | Subscription | Free forever (GPL-3.0) |
+| Layer | Technology | Why |
+|-------|-----------|-----|
+| Language | Python 3.10+ | Universal, cross-platform, pip installable |
+| Models | Pydantic v2 | Typed config, validation, JSON serialization |
+| CLI | Click | Composable subcommands, testable |
+| Crypto | PGPy + GnuPG | PGP standard, no proprietary crypto |
+| File watching | watchdog (inotify) | Sub-second inbox trigger, no polling |
+| Concurrency | `threading` + `ThreadPoolExecutor` | Simple, no async complexity |
+| Transport | Syncthing | P2P, TLS encrypted, decentralized |
+| Local LLM | Ollama | CPU inference without API keys |
+| Cloud LLMs | skseed callbacks | grok · kimi · nvidia · anthropic · openai |
+| HTTP API | `http.server.HTTPServer` | Zero-dep local status API |
+| Config | YAML + Pydantic | Human-readable, schema-validated |
+| Testing | pytest | Full pillar + consciousness coverage |
 
 ---
 
@@ -506,5 +797,3 @@ skcapstone sync vault add-backend       # Add sync backend
 Built by the [smilinTux](https://smilintux.org) ecosystem.
 
 *The capstone that holds the arch together.* 🐧
-
-#staycuriousANDkeepsmilin