@smilintux/skcapstone 0.10.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` |
@@ -748,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
 

package/docs/hammertime-audit.md

@@ -0,0 +1,402 @@
+# hammerTime Audit — Backport Analysis
+
+**Date:** 2026-04-09  
+**Auditor:** Opus (Claude Code subagent)  
+**Source repo:** https://skgit.skstack01.douno.it/smilinTux/hammerTime  
+**Target repos:** skmemory, skcapstone
+
+---
+
+## File Tree Summary
+
+Top-level structure (code-relevant):
+
+```
+scripts/              # All Python pipeline scripts (~55 files)
+  context_bridge_lib.py   # 2,800+ line unified retrieval library (THE core)
+  context-bridge.py       # thin wrapper → main()
+  issue-pack.py           # thin wrapper → main(mode_override="issue-pack")
+  decompose.py            # L3 decomposition engine
+  pipeline.py             # 5-layer orchestrator
+  import-qdrant-v2.py     # L4 vector embed + Qdrant upsert
+  import-falkordb-v2.py   # L5 graph import
+  corpus_release.py       # corpus release/alias/promotion model
+  distributed-worker.py   # multi-GPU SSH coordinator
+  rebuild-stores.py       # full/incremental corpus rebuild
+  research-synthesis.py   # synthesis + filing-ready packet builder
+  corpus-guardian.py      # health validation daemon
+  manage-decomposed.py    # decomposed artifact state manager
+  case_facts.py           # case-fact loader (incident/problem/profile)
+  ...47 other scripts
+.cursor/skills/       # 37+ skill definitions (trigger-mapped)
+json/decomposed/      # L3 output: slug.json per artifact
+json/state/           # corpus release state machine files
+json/releases/        # release manifests (dev/uat/prod)
+json/schemas/         # JSON schemas
+incidents/            # Case workspace (problem → incident → artifacts)
+knowledge/            # Primary corpus (markdown)
+templates/            # Filing templates
+profiles/             # Person/company YAML profiles
+models/bge-legal-v1/  # Sovereign embedding model (local)
+```
+
+Key infrastructure:
+- **Qdrant** at `skvector.nativeassetmanagement.com` (collection: `hammertime-v3`, 1024-dim cosine, `bge-legal-v1`)
+- **FalkorDB** at `skgraph.nativeassetmanagement.com:6381` (graph: `hammertime-v2`)
+- **7-node GPU cluster** (chiap01–chiap08 + chiwk12) running Ollama with bge-legal-v1
+- **Embedding model**: `chefboyrave21/bge-legal-v1` (1024-dim, sovereign HuggingFace model)
+
+---
+
+## Key Patterns Found
+
+### L3 Decomposition
+
+**Script:** `scripts/decompose.py` (standalone) + `skmemory.decompose.decompose_content` (shared library)
+
+hammerTime's decomposition is domain-specialized for legal documents but structurally similar to skmemory's `decompose_content`. Key differences:
+
+**hammerTime extras skmemory lacks:**
+1. **6 citation regex types**: UCC sections, UCC forms (UCC-1/3), CFR, USC, case citations (Smith v. Jones, 123 F.2d 456), Public Law, IRS forms — skmemory has a simpler generic citation extractor
+2. **Trust type extraction**: 9 named trust forms (Express, Constructive, Resulting, Statutory, etc.)
+3. **Maritime/Admiralty extraction**: dedicated regex for maritime lien patterns
+4. **Legal principle extraction**: 25 named principles (Holder in Due Course, Quantum Meruit, etc.)
+5. **Agency/court extraction**: 20+ named agencies (IRS, Fed Reserve, CFPB, OCC, etc.)
+6. **Claim confidence scoring**: chunks marked `high/medium/low` based on claim indicator phrases
+7. **Section-title tracking per chunk**: exact heading ancestry embedded in each chunk
+8. **CHUNK_TARGET = 900 chars / 450 tokens** (calibrated for bge-legal-v1's 512-token hard limit)
+9. **Relationship extraction**: 6 rel types: CITES, CONTRADICTS, SUPERSEDES, REQUIRES, DEFINES, ESTABLISHES
+10. **`secondary` / `form` document-type classification** via title term matching
+
+**Output schema** (`json/decomposed/{slug}.json`):
+```json
+{
+  "source_file": "knowledge/irs/example.md",
+  "decomposed_at": "2026-04-05T14:21:09Z",
+  "frontmatter": {},
+  "stats": { "chunks": 2, "claims": 12, "citations": 4, "entities": 11, "relationships": 54 },
+  "chunks": [{ "chunk_id": "...", "parent_doc": "...", "chunk_index": 0, "total_chunks": 2,
+               "section_title": "...", "text": "..." }],
+  "claims": [{ "claim_id": "...", "text": "...", "line": 15, "category": "irs", "confidence": "high" }],
+  "citations": [{ "citation_id": "...", "raw_text": "UCC 3-301", "parsed_type": "ucc",
+                  "section": "3-301", "source_file": "...", "line": 22 }],
+  "entities": [{ "entity_id": "...", "name": "IRS", "type": "Agency", "context": "..." }],
+  "relationships": [{ "relationship_id": "...", "source_entity": "...",
+                      "relationship_type": "DEFINES", "target_entity": "...", "evidence_text": "..." }]
+}
+```
+
+**Comparison to skmemory:** skmemory's `DecompositionResult` has chunks/citations/entities/claims but lacks: typed citation parsing, relationship extraction, confidence scoring, and entity-type taxonomy.
+
+---
+
+### Context Bridge (context_bridge_lib.py)
+
+This is the most important file for backporting. It is a ~2,800-line retrieval fusion library that merges skmemory + hammertime corpus into a single ranked result set.
+
+**Architecture of `build_context()`:**
+1. **Pivot extraction** — calls `skmemory.decompose.decompose_content(task)` to extract entities, citations, claims from the user's query
+2. **Memory loading** — `_load_memory_context()` runs: `store.load_context()`, `store.search()`, `store.novelty_search()`, `store.build_session_brief()`, and memory graph pivots (`store.graph.search_by_entity()`, `store.graph.search_by_citation()`, `store.graph.related_claims_by_entity()`)
+3. **Corpus search** — `_search_corpus()` runs query embedding → Qdrant → result grouping by parent doc
+4. **Jurisdiction overlay** — `_jurisdiction_overlay_hits()` does keyword-based scoring against a local pre-built index of all decomposed JSON (no live Qdrant needed)
+5. **Suggestions** — `_derive_connections()` counts entity/citation/claim co-occurrence across corpus hits to surface emergent pivots
+6. **Ranking** — `_build_ranked_candidates()` computes hybrid score:
+   ```
+   hybrid_score = base_score
+                + authority_weight(tier) × 0.5
+                + state_boost (0–0.22)
+                + domain_boost (−0.18 to +0.28)
+                + quality_boost (−0.18 to +0.28)
+                + pivot_count × 0.04 (capped at 0.18)
+                − 0.24 if weak_authority_reason
+   ```
+7. **Contradiction detection** — `_detect_contradictions()` checks top-10 results for claim conflicts (negation term asymmetry + shared citations/entities) — emits `contradiction_type`, `severity`, `shared_citations`
+8. **Contradiction penalty** — weak-authority items involved in contradictions get −0.08 × count penalty
+9. **Dedup** — by `(source_type, origin_path)` key
+
+**Three research modes:**
+- `balanced` — default, filters generic secondary material unless state/pivot hits
+- `primary-authority-first` — aggressively suppresses generic secondary if `<2 practical terms`
+- `allow-secondary` — keeps everything (AmJur/VSOF style)
+
+**Caching layers:**
+1. Query embedding cache (SHA256 key, JSON file, LRU 256 entries)
+2. Corpus result cache (SHA256 key including collection+URL+state, JSON file, configurable TTL, LRU 128 entries)
+3. Jurisdiction overlay index (snapshot-hash-based invalidation, JSON file)
+4. Session-level Qdrant client cache (dict keyed on URL+key+timeout)
+
+---
+
+### Issue Pack / Authority Ranking
+
+`issue-pack.py` calls `main(mode_override="issue-pack")` which adds extra sections beyond `build_context()`:
+
+1. **`filing_ready` section** — infers filing type from task terms (claim_of_exemption, motion_to_vacate, objection_or_hearing_request, notice_or_affidavit), builds draft skeletons with:
+   - Section prompts per filing type
+   - Evidence checklist
+   - `draft_markdown` — ready-to-edit filing scaffold
+   - `timeline_checkpoints` — deadline-sensitive procedural steps
+   - `confidence` score per skeleton
+2. **`reference_bank`** — separate bucket for secondary-tier results, surfaced without displacing primary authorities
+3. **`fact_gaps`** — structured questions across 4 profiles: enforcement_instrument, timing_and_service, asset_and_funds_profile, attack_paths — cross-checked against ranked results
+4. **`procedural_timeline`** — inferred checkpoints (judgment posture, enforcement trigger, objection window, attack path) with high/medium urgency
+5. **Draft bundle writing** — full packet materialized to disk: `preferred-draft.md`, `EXHIBIT-INDEX.md`, `SUBMISSION-CHECKLIST.md`, `FILING-PLAN.md`, `SERVICE-PACKET.md`, `HEARING-PACKET.md`, `CALENDAR.md`, `PREFERRED-PATH.md`, `NEXT-ACTIONS.md`, `packet-progress.json`
+
+**Key struct for skmemory backport consideration:** the `reference_bank` pattern — separating primary action authorities from secondary reference material. skmemory's `search()` currently returns a flat ranked list with no tier-aware split.
+
+---
+
+### Graph Edge Model (FalkorDB via import-falkordb-v2.py)
+
+**Node labels (15):**
+```
+Template, Process, CaseStrategy, Knowledge, Skill, Profile, Entity, Case, 
+TemplateChain, Phase, Step, Incident, Judge,
+[Lumina additions:] Statute, Principle, Filing, Court, Agency
+```
+
+**Relationship types (18):**
+```
+[v1:] HAS_PHASE, HAS_STEP, USES_TEMPLATE, REFERENCES, RELATED_TO, INCLUDES, PRESIDED_BY, CHAIN_LINK, TAGGED
+[Lumina additions:] CITES, CONTRADICTS, SUPERSEDES, REQUIRES, DEFINES, ESTABLISHES, EFFECTIVE_DATE, AMENDED_BY, REPEALED_BY
+```
+
+**Entity type mapping** (from decomposed JSON → graph label):
+```python
+ENTITY_TYPE_MAP = {
+    "statute": "Statute", "law": "Statute", "usc": "Statute", "cfr": "Statute",
+    "principle": "Principle", "filing": "Filing", "court": "Court", "agency": "Agency",
+    "process": "Process", "template": "Template", "knowledge": "Knowledge",
+    "entity": "Entity", "person": "Profile", "company": "Entity", "skill": "Skill",
+}
+```
+
+**Unique key per label** (for MERGE deduplication):
+```python
+{ "Statute": "name", "Principle": "name", "Filing": "filing_id", "Court": "name",
+  "Agency": "name", "Memory": "memory_id", ... }
+```
+
+**Cross-reference pass:** after node import, scans skills/knowledge files for path references to build edges. Also scans all knowledge/*.md for USC/CFR citation patterns → auto-creates Statute nodes + CITES edges.
+
+**skmemory comparison:** skmemory has `graph_queries.py` but currently only stores Memory nodes, not typed Statute/Principle/Court/Agency nodes. The CITES/CONTRADICTS/SUPERSEDES/DEFINES relationship vocabulary is entirely absent from skmemory's graph layer.
+
+---
+
+### Services/Workers
+
+**`distributed-worker.py`** — Multi-GPU SSH coordinator:
+- Reads `gpu-inventory.json` (7 nodes, VRAM weights: 16GB RTX 4080, 8GB RX 7600 ×2, 6GB RTX 3060, 8GB RTX 2080S, 12GB RTX 5070 Ti, 4GB Radeon 780M)
+- Splits work in proportion to VRAM capacity
+- SSHes into remote nodes, runs `worker-embed.py` per batch
+- All nodes share NFS at `/mnt/cloud/onedrive/` — no file transfer needed
+- Results upsert directly to Qdrant from each node
+- Coordinator runs FalkorDB graph import centrally after embedding completes
+
+**`corpus-guardian.py`** — Health validation daemon:
+- `validate-env --target uat --deep` — validates release manifest, collection health, graph health, source drift
+- `check-envs --targets dev,uat,prod --deep` — validates all env aliases in one pass
+- Installed via `install-corpus-automation.sh` as systemd user timers
+
+**`corpus_release.py`** — Release/alias state machine:
+- Three-tier: `dev` (mutable), `uat` (frozen candidate), `prod` (live)
+- `active_runtime()` → resolves current vector_collection + graph_name from runtime aliases
+- `promote_release()` → updates alias to point a target (dev/uat/prod) at a specific release
+- Processing state tracking: SHA256 content hashes, mtime, per-document last_release_id
+- `diff_source_index()` → detects new/changed/deleted docs since last state snapshot
+
+**`cron/hammertime-corpus.crontab.example`** — Suggested crontab for incremental corpus updates
+
+---
+
+### Skills (37+ defined)
+
+All skills are `.md` files in `.cursor/skills/` — trigger phrases map to skill invocations. Key skills:
+
+| Skill | Purpose |
+|-------|---------|
+| `sovereign-ingestion-pipeline.md` | Master SIP reference — all 5 layers, commands, schemas |
+| `ingest-files.md` | L2 — convert raw docs to markdown + JSON artifacts |
+| `ingest-guide.md` | Ingest a complete guide document |
+| `ingest-telegram.md` | Import Telegram chat exports |
+| `research-query.md` | Run context-bridge / issue-pack queries |
+| `analyze-document.md` | Single-document analysis |
+| `generate-document.md` | Legal document generation from templates |
+| `manage-incidents.md` | ITIL-style incident lifecycle for legal cases |
+| `manage-correspondence.md` | Track filings/letters/responses |
+| `sync-knowledge.md` | Sync knowledge base across devices |
+| `study-archive.md` | Archive and index study materials |
+| `docx-to-md/` | DOCX → markdown conversion (with script) |
+| `pdf-to-image/` | PDF → page images (with script) |
+| `pptx-to-md/` | PPTX → markdown conversion (with script) |
+
+**skcapstone relevance:** The skill system maps closely to skcapstone's own skills directory at `~/clawd/skills/`. The trigger-phrase-to-skill mapping and the SKILL.md metadata pattern are worth adopting for skill discoverability.
+
+---
+
+## Recommended Backports (Prioritized)
+
+### 1. HIGH: Jurisdiction/Context Overlay Index → skmemory
+
+**What:** `_build_overlay_index()` and `_jurisdiction_overlay_hits()` in `context_bridge_lib.py`
+
+**What it does:** Builds a local JSON index from all decomposed artifacts containing each artifact's claims, citations, entities, sections, and a pre-built `search_blob`. This enables sub-millisecond keyword/state-based retrieval WITHOUT a live vector query — pure JSON scan. Falls back to this when Qdrant is slow/offline, and merges results with live semantic search.
+
+**Why it matters for skmemory:** skmemory has no equivalent offline search. All retrieval hits skmemory's store (SQLite or vector). An overlay index of memory decompositions would let agents get fast, deterministic hits on known high-value memories before the expensive embedding path.
+
+**Implementation path:**
+- Add `build_overlay_index()` to `skmemory/store.py` or a new `skmemory/overlay.py`
+- Cache at `~/.skcapstone/agents/{agent}/memory/overlay-index.json`
+- Invalidate when memory file count or newest mtime changes (current snapshot pattern)
+- Expose via `skmemory search --overlay` or as a fast pre-filter in `MemoryStore.search()`
+
+---
+
+### 2. HIGH: Hybrid Scoring with Authority Weights → skmemory + context_bridge_lib port
+
+**What:** `_build_ranked_candidates()` + `_quality_adjustment()` + `_detect_contradictions()` in `context_bridge_lib.py`
+
+**What it does:** Computes a `hybrid_score` that merges semantic similarity with: authority tier weight, state-specificity boost, domain relevance boost, pivot alignment bonus, and weak-authority penalty. Detects contradictions between top results and applies penalties.
+
+**skmemory current state:** `authority_weight()` and `infer_authority_tier()` exist in `skmemory/retrieval.py` but are only used for metadata preparation — they do NOT feed back into ranking scores in `MemoryStore.search()`.
+
+**Why it matters:** skmemory's search returns results ranked purely by semantic similarity. hammerTime's hybrid scoring demonstrably promotes actionable primary-authority results and demotes speculative secondary material. This is directly applicable to non-legal memory contexts: skmemory memories already have authority_tier metadata — it just isn't used for ranking.
+
+**Implementation path:**
+- Add `hybrid_score()` function to `skmemory/retrieval.py`
+- Accept: `base_score`, `authority_tier`, `pivot_matches` (entity/citation hits in query), `domain_terms`
+- Apply in `MemoryStore.search()` as a post-processing re-rank step
+- Add `_detect_contradictions()` equivalent for flagging conflicting memory results
+
+---
+
+### 3. HIGH: Corpus Release / Processing State Machine → skcapstone
+
+**What:** `corpus_release.py` — the full dev/uat/prod release lifecycle for vector+graph stores
+
+**What it does:** Tracks per-document SHA256 hashes and mtimes, diffs against previous state, manages runtime aliases (which Qdrant collection + FalkorDB graph are currently "live" per environment), writes release manifests, validates health, and allows promoting releases between tiers without rebuilding.
+
+**Why it matters for skcapstone:** skmemory has no concept of corpus release state. Every rebuild wipes and recreates. When `hammertime-v3` grows to thousands of points, incremental state tracking becomes critical. skcapstone also manages multi-agent deployments where different agents may need different corpus versions (dev/uat/prod).
+
+**Implementation path:**
+- Port `corpus_release.py` as `skcapstone/src/skcapstone/corpus_release.py`
+- Integrate with `skmemory` so each agent's Qdrant collection has an aliased runtime name
+- Add `skcapstone corpus release` and `skcapstone corpus promote` CLI commands
+- Store release state at `~/.skcapstone/corpus/{agent}/state/`
+
+---
+
+### 4. MEDIUM: Typed Citation Extraction → skmemory/decompose.py
+
+**What:** The 9 citation regex types in `decompose.py` (UCC, CFR, USC, case citations, Public Law, IRS forms, trust types, maritime, legal principles)
+
+**Why it matters:** skmemory's `_extract_citations()` uses simpler patterns. If SK agents are going to use hammertime-v3 in recall_collections, the same citation normalization should be shared so citations extracted during memory storage match citations extracted during corpus query pivot extraction.
+
+**Implementation path:**
+- Extract citation regexes into `skmemory/citation_patterns.py`
+- Update `skmemory/decompose.py` `_extract_citations()` to use shared patterns
+- hammerTime already calls `skmemory.decompose.decompose_content()` for pivot extraction — the shared library already exists, it just needs richer patterns
+
+---
+
+### 5. MEDIUM: Query Expansion + Stale Cache Fallback → skmemory
+
+**What:** `_expand_query()` (domain-aware query expansion) + stale cache fallback in `_search_corpus()`
+
+**What it does:** When a query contains enforcement/exemption terms, appends related terms ("writ of execution", "judgment debtor", etc.) to the embedding query. When Qdrant fails mid-query, falls back to last cached result for that exact query (keyed by SHA256 of query+collection+state).
+
+**Why it matters:** skmemory has no query expansion and no graceful degradation when the vector backend is unavailable. Both patterns would improve skmemory's recall and reliability.
+
+---
+
+### 6. MEDIUM: Graph Relationship Vocabulary → skmemory/graph_queries.py
+
+**What:** CITES, CONTRADICTS, SUPERSEDES, REQUIRES, DEFINES, ESTABLISHES, EFFECTIVE_DATE, AMENDED_BY, REPEALED_BY relationships in FalkorDB
+
+**Why it matters:** skmemory's graph layer currently uses RELATED_TO as the primary edge type. Adding typed edges would enable structured queries like "which memories CONTRADICT this one" or "which memories SUPERSEDE that prior belief" — directly useful for emotional continuity (FEBs that supersede old beliefs) and knowledge evolution tracking.
+
+**Implementation path:**
+- Add typed relationship support to `skmemory/graph_queries.py`
+- Expose `store.graph.search_related_claims_by_type(entity, rel_type)` 
+- Use relationship type when saving FEB memories that explicitly contradict or update prior beliefs
+
+---
+
+### 7. MEDIUM: Draft Bundle / Packet Pattern → skcapstone coordination
+
+**What:** The filing-ready draft bundle: preferred-draft, exhibit index, submission checklist, filing plan, service/hearing packet, calendar, preferred-path, next-actions, packet-progress.json
+
+**Why it matters:** This is structurally equivalent to skcapstone's coordination task/project pattern. The hammerTime "packet" is a self-contained action workspace that survives across sessions. skcapstone's `~/.skcapstone/coordination/tasks/` does something similar but less structured. The packet-progress.json with status fields (preferred_draft_status, service_status, hearing_status, filing_status) maps directly to task state management.
+
+---
+
+### 8. LOW: Distributed Worker Pattern → skcapstone swarm
+
+**What:** `distributed-worker.py` — VRAM-weighted work distribution across SSH nodes
+
+**Why it matters:** When skmemory or hammerTime corpus needs to be re-embedded across a large document set, the 7-GPU cluster pattern (VRAM-proportional batching, SSH dispatch, NFS shared storage) could be reused. The `gpu-inventory.json` file already exists as shared infrastructure.
+
+**Implementation path:** Low priority because skmemory embeddings are per-memory-file (small), not bulk corpus runs. Relevant only if skmemory gains a sovereign embedding model.
+
+---
+
+### 9. LOW: Corpus Guardian / Health Daemon → skcapstone monitoring
+
+**What:** `corpus-guardian.py` validates collection health, graph health, source drift, and alias correctness
+
+**Why it matters:** skcapstone has no health monitoring for Qdrant or FalkorDB. If these services are used by multiple agents, a guardian daemon would catch drift (source changed but corpus not rebuilt) and surface it proactively.
+
+---
+
+## recall_collections Recommendation
+
+`hammertime-v3` (Qdrant at `skvector.nativeassetmanagement.com`, 1024-dim, bge-legal-v1) should be added to `recall_collections` for:
+
+| Agent | Justification |
+|-------|---------------|
+| **lumina** | Primary orchestrator — needs legal corpus access for case-related dispatches |
+| **architect** | Handles system design that may intersect legal/compliance domains |
+| **scholar** | Research-focused agent — direct benefit from legal corpus retrieval |
+| **coder** | Lower priority but useful for regulatory/compliance code generation |
+
+**Configuration note:** The bge-legal-v1 model is 1024-dim while the default skmemory collection uses a different embedding model. Recall from `hammertime-v3` requires either:
+1. Using the same bge-legal-v1 model for query embedding (requires the local model at `models/bge-legal-v1/` or via Ollama), OR
+2. Adding a separate recall path in `context_bridge_lib.py` that hammerTime already implements
+
+The cleanest path: add `hammertime-v3` as a read-only recall collection that only `context-bridge.py` / `issue-pack.py` queries, surfacing results back into skmemory's context system through the bridge interface that already exists in `context_bridge_lib.py`.
+
+**Do NOT** route skmemory's standard search to hammertime-v3 directly — the embedding dimensions don't match skmemory's default model.
+
+---
+
+## Dependencies hammerTime Uses That skmemory/skcapstone Should Adopt
+
+| Library | hammerTime Use | skcapstone/skmemory Status | Recommendation |
+|---------|---------------|--------------------------|----------------|
+| `sentence-transformers` | L4 embedding (bge-legal-v1 via SentenceTransformer) | Used in skmemory | Already adopted |
+| `qdrant-client` | Vector store (hammertime-v3) | Used in skmemory | Already adopted |
+| `redis` (FalkorDB) | Graph DB via GRAPH.QUERY commands | Not in skmemory | Add for graph layer if FalkorDB adopted |
+| `falkordb` | Newer FalkorDB Python client | Not in skmemory | Optional — redis path works |
+| `concurrent.futures` | ThreadPoolExecutor for Qdrant query timeout | Not systematically used | Add for retrieval deadline enforcement |
+| `yaml` | YAML frontmatter in profiles | Already in skcapstone | Already adopted |
+
+**No new mandatory dependencies** are required for the highest-priority backports (overlay index, hybrid scoring). They use only stdlib + existing skmemory internals.
+
+---
+
+## Architecture Note: What hammerTime Does Differently From skmemory
+
+| Concern | skmemory | hammerTime |
+|---------|----------|------------|
+| Storage unit | `Memory` object (agent-personal) | Document chunk (corpus-shared) |
+| Embedding dimensions | Variable (default model) | 1024 (bge-legal-v1 sovereign) |
+| Graph node | Generic `Memory` node | 15 typed nodes (Statute, Court, Agency, etc.) |
+| Graph relationships | RELATED_TO primarily | 18 typed rels including CITES, CONTRADICTS, SUPERSEDES |
+| Retrieval | Semantic similarity only | Hybrid: semantic + overlay + authority weight + state boost |
+| Authority ranking | Metadata only (not used in ranking) | Fully integrated into hybrid_score |
+| Contradiction detection | None | Top-10 cross-check + penalty |
+| Release lifecycle | None (rebuild = wipe) | dev/uat/prod alias model with SHA256 drift tracking |
+| Query caching | None | Two-level: embedding LRU + corpus result TTL + stale fallback |
+| Offline mode | None | Jurisdiction overlay (pure JSON, no live vector needed) |
+
+The two systems are **complementary, not redundant**. hammerTime is the document corpus for legal knowledge; skmemory is the agent's personal experiential memory. The `context_bridge_lib.py` is the correct integration point — it already merges both. The backport work is about lifting hammerTime's superior retrieval patterns (hybrid scoring, caching, overlay index) into skmemory so the memory side is equally capable when the bridge merges results.