@precisionutilityguild/liquid-shadow 1.0.5 → 1.0.6

package/dist/logic/domain/embeddings/worker.js

@@ -1 +1 @@
-import{parentPort as c,workerData as h}from"worker_threads";import m from"pino";var y={10:"TRACE",20:"DEBUG",30:"INFO",40:"WARN",50:"ERROR",60:"FATAL"},M=m({level:process.env.LOG_LEVEL||"warn",base:{service:"liquid-shadow"},formatters:{level(t,e){return{level:t,severity:y[e]??"INFO"}}},transport:{target:"pino-pretty",options:{colorize:!0,translateTime:"HH:MM:ss",destination:2,levelKey:"severity",messageKey:"message"}}}),o=M;var u=process.env.EMBEDDING_MODEL??"Xenova/all-MiniLM-L6-v2",a=process.env.EMBEDDING_DTYPE??"fp32",i=null;async function E(){return i||(i=await import("@xenova/transformers"),i.env.cacheDir=h?.cacheDir||"./.cache",i.env.allowLocalModels=!0),i}var l=null;function p(t=!1){let e=(a||"").toLowerCase(),r={};return a&&(r.dtype=a),t?(r.quantized=!1,r):(e==="fp32"||e==="fp16"||e==="float32"||e==="float16"?r.quantized=!1:e.startsWith("q")&&(r.quantized=!0),r)}async function b(){let{pipeline:t}=await E(),e=p(!1);try{l=await t("feature-extraction",u,e)}catch(r){let n=r?.message||"";if(!(n.includes("/onnx/model_quantized.onnx")||n.includes("model_quantized.onnx")))throw r;o.warn({model:u,dtype:a},"Quantized ONNX artifact missing, retrying with unquantized ONNX"),l=await t("feature-extraction",u,p(!0))}}async function w(t){if(t.length===0)return[];try{let e=await l(t,{pooling:"mean",normalize:!0}),[r,n]=e.dims,s=[];for(let d=0;d<r;d++){let g=d*n,f=g+n;s.push(Array.from(e.data.slice(g,f)))}return s}catch(e){o.error({err:e,batchSize:t.length},"Vectorized batch embedding failed, falling back to sequential");let r=[];for(let n of t){if(!n||n.trim().length===0){r.push(null);continue}try{let s=await l(n,{pooling:"mean",normalize:!0});r.push(Array.from(s.data))}catch{r.push(null)}}return r}}async function v(t){if(t.type==="shutdown"&&process.exit(0),t.type==="embed")try{let e=await w(t.texts),r={type:"result",id:t.id,embeddings:e};c?.postMessage(r)}catch(e){let r={type:"error",id:t.id,error:e instanceof Error?e.message:String(e)};c?.postMessage(r)}}async function z(){await b();let t={type:"ready"};c?.postMessage(t),c?.on("message",e=>{v(e).catch(r=>{o.error({error:r},"Worker error")})})}z().catch(t=>{o.error({error:t},"Failed to initialize embedding worker"),process.exit(1)});
+import{parentPort as c,workerData as E}from"worker_threads";import g from"os";import y from"pino";var M={10:"TRACE",20:"DEBUG",30:"INFO",40:"WARN",50:"ERROR",60:"FATAL"},h=y({level:process.env.LOG_LEVEL||"warn",base:{service:"liquid-shadow"},formatters:{level(e,r){return{level:e,severity:M[r]??"INFO"}}},transport:{target:"pino-pretty",options:{colorize:!0,translateTime:"HH:MM:ss",destination:2,levelKey:"severity",messageKey:"message"}}}),o=h;try{g.setPriority(g.constants.priority.PRIORITY_BELOW_NORMAL)}catch{}var u=process.env.EMBEDDING_MODEL??"Xenova/all-MiniLM-L6-v2",a=process.env.EMBEDDING_DTYPE??"fp32",s=null;async function w(){if(!s){s=await import("@xenova/transformers"),s.env.cacheDir=E?.cacheDir||"./.cache",s.env.allowLocalModels=!0;let{ONNX:e}=s;if(e?.InferenceSession?.create){let r=e.InferenceSession.create.bind(e.InferenceSession);e.InferenceSession.create=(t,n={})=>r(t,{...n,intraOpNumThreads:2,extra:{"session.intra_op.allow_spinning":"0","session.force_spinning_stop":"1","ep.dynamic.workload_type":"Efficient",...n.extra??{}}})}}return s}var l=null;function f(e=!1){let r=(a||"").toLowerCase(),t={};return a&&(t.dtype=a),e?(t.quantized=!1,t):(r==="fp32"||r==="fp16"||r==="float32"||r==="float16"?t.quantized=!1:r.startsWith("q")&&(t.quantized=!0),t)}async function b(){let{pipeline:e}=await w(),r=f(!1);try{l=await e("feature-extraction",u,r)}catch(t){let n=t?.message||"";if(!(n.includes("/onnx/model_quantized.onnx")||n.includes("model_quantized.onnx")))throw t;o.warn({model:u,dtype:a},"Quantized ONNX artifact missing, retrying with unquantized ONNX"),l=await e("feature-extraction",u,f(!0))}}async function v(e){if(e.length===0)return[];try{let r=await l(e,{pooling:"mean",normalize:!0}),[t,n]=r.dims,i=[];for(let d=0;d<t;d++){let p=d*n,m=p+n;i.push(Array.from(r.data.slice(p,m)))}return i}catch(r){o.error({err:r,batchSize:e.length},"Vectorized batch embedding failed, falling back to sequential");let t=[];for(let n of e){if(!n||n.trim().length===0){t.push(null);continue}try{let i=await l(n,{pooling:"mean",normalize:!0});t.push(Array.from(i.data))}catch{t.push(null)}}return t}}async function R(e){if(e.type==="shutdown"&&process.exit(0),e.type==="embed")try{let r=await v(e.texts),t={type:"result",id:e.id,embeddings:r};c?.postMessage(t)}catch(r){let t={type:"error",id:e.id,error:r instanceof Error?r.message:String(r)};c?.postMessage(t)}}async function z(){await b();let e={type:"ready"};c?.postMessage(e),c?.on("message",r=>{R(r).catch(t=>{o.error({error:t},"Worker error")})})}z().catch(e=>{o.error({error:e},"Failed to initialize embedding worker"),process.exit(1)});

package/dist/skills/shadow_audit/SKILL.md

@@ -26,6 +26,9 @@ Comprehensive health audit using Shadow analyze toolkit.
 | **Circular Deps**    | `shadow_analyze_debt` (mode: "circular-deps")                                          |
 | **Layers**           | `shadow_recon_topography` — detailed breakdown if needed                               |
 | **Config Audit**     | `shadow_search_config` (kind: "Env", **showUsage: true**) — find orphaned env vars     |
+| **Event Mesh**       | `shadow_analyze_mesh` (repoPath) — audit all HTTP routes, socket events, pubsub topics |
+| **Type Integrity**   | `shadow_analyze_type_graph` (filePath, repoPath) — interface/type inheritance chains   |
+| **Theme Patterns**   | `shadow_ops_crystallize_theme` (query, repoPath) — recurring issues across missions    |
 
 ## 💡 Intelligence Options
 

package/dist/skills/shadow_continue/SKILL.md

@@ -25,22 +25,30 @@ description: Get briefing, pick one mission from next_work_candidates, then work
   - **Surgical Discovery:** `shadow_analyze_flow` (symbolName, filePath, repoPath).
   - **Execute Step**: Set in-progress → implement → `shadow_ops_track` (missionId, stepId, status: "completed", contextPivot, repoPath).
   - **Atomic Logging:** At least once per step. `shadow_ops_log` (missionId, type: "decision", content, symbolName, repoPath).
+  - **Inter-agent handoff** (multi-agent pipelines only): When handing off findings to another agent, call `shadow_ops_handoff` (missionId, role, summary, findings, repoPath) to persist a typed artifact with embedding. The receiving agent calls `shadow_ops_handoff_read` (missionId, query, repoPath) to semantically retrieve relevant prior handoffs.
 - **Seal the mission**: `shadow_ops_track` (missionId, status: "completed", repoPath).
   - This **auto-triggers**: ADR synthesis, Git Notes persistence, and cascade parent completion (if all sibling missions are also done, the parent auto-completes too).
   - No need to call `shadow_ops_synthesize` separately — it's automatic on completion.
 - **Optional — Crystallize** (for long-running missions with many logs): `shadow_ops_crystallize` (missionId, repoPath) compresses raw intent logs into a single crystal summary. Useful mid-mission to keep briefings lean.
+- **Optional — Theme Crystallize** (cross-mission patterns): `shadow_ops_crystallize_theme` (query, repoPath) clusters semantically related intent logs across ALL missions to surface recurring architectural themes. Use when you sense a pattern repeating across missions.
 
 ## 🛠 Precise Tooling
 
-| Action                 | Atomic Tool              | Example                                                  |
-| :--------------------- | :----------------------- | :------------------------------------------------------- |
-| **Context (one shot)** | `shadow_ops_context`     | repoPath — hologram + chronicle + briefing               |
-| **Briefing**           | `shadow_ops_briefing`    | scope: "project", altitude: "orbit", repoPath            |
-| **Flow Trace**         | `shadow_analyze_flow`    | symbolName: "handleRequest", filePath, repoPath          |
-| **Step Update**        | `shadow_ops_track`       | missionId: 4, stepId: "s2", status: "completed"          |
-| **Intent Log**         | `shadow_ops_log`         | missionId: 4, type: "fix", content: "..."                |
-| **Complete Mission**   | `shadow_ops_track`       | missionId: 4, status: "completed" — auto-synthesizes ADR |
-| **Crystallize**        | `shadow_ops_crystallize` | missionId: 4 — compress logs mid-mission                 |
+| Action                 | Atomic Tool                    | Example                                                          |
+| :--------------------- | :----------------------------- | :--------------------------------------------------------------- |
+| **Context (one shot)** | `shadow_ops_context`           | repoPath — hologram + chronicle + briefing                       |
+| **Briefing**           | `shadow_ops_briefing`          | scope: "project", altitude: "orbit", repoPath                    |
+| **Flow Trace**         | `shadow_analyze_flow`          | symbolName: "handleRequest", filePath, repoPath                  |
+| **Step Update**        | `shadow_ops_track`             | missionId: 4, stepId: "s2", status: "completed"                  |
+| **Intent Log**         | `shadow_ops_log`               | missionId: 4, type: "fix", content: "..."                        |
+| **Complete Mission**   | `shadow_ops_track`             | missionId: 4, status: "completed" — auto-synthesizes ADR         |
+| **Crystallize**        | `shadow_ops_crystallize`       | missionId: 4 — compress logs mid-mission                         |
+| **Theme Crystallize**  | `shadow_ops_crystallize_theme` | query: "auth patterns" — cross-mission semantic clustering       |
+| **Handoff (write)**    | `shadow_ops_handoff`           | missionId, role: "RECON", summary, findings — persist artifact   |
+| **Handoff (read)**     | `shadow_ops_handoff_read`      | missionId, query: "auth findings" — semantic retrieval           |
+| **Event Mesh**         | `shadow_analyze_mesh`          | repoPath — surface all HTTP routes, socket events, pubsub topics |
+| **Type Graph**         | `shadow_analyze_type_graph`    | filePath, repoPath — interface/type inheritance map              |
+| **Explain Diff**       | `shadow_analyze_explain_diff`  | fromCommit, toCommit, repoPath — semantic diff narrative         |
 
 _Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
 
@@ -52,4 +60,4 @@ _Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
 
 ---
 
-**Tools:** `shadow_ops_context` (optional start), `shadow_ops_briefing`, `shadow_ops_track`, `shadow_ops_log`, `shadow_ops_crystallize`, `shadow_sync_trace`. For discovery: `shadow_search_*`, `shadow_recon_*`, `shadow_analyze_*`.
+**Tools:** `shadow_ops_context` (optional start), `shadow_ops_briefing`, `shadow_ops_track`, `shadow_ops_log`, `shadow_ops_crystallize`, `shadow_ops_crystallize_theme`, `shadow_ops_handoff`, `shadow_ops_handoff_read`, `shadow_sync_trace`. For discovery: `shadow_search_*`, `shadow_recon_*`, `shadow_analyze_*` (including `shadow_analyze_mesh`, `shadow_analyze_type_graph`, `shadow_analyze_explain_diff`).

package/dist/skills/shadow_mission/SKILL.md

@@ -23,14 +23,17 @@ Define the objective, strategy, and success criteria for a new mission. This wor
 
 ## Precise Tooling
 
-| Setup Action          | Precise Tool Call                          | Usage                                                        |
-| :-------------------- | :----------------------------------------- | :----------------------------------------------------------- |
-| **Session Start**     | `shadow_ops_context`                       | **START HERE** — hologram + chronicle + briefing in one call |
-| **Establish Plan**    | `shadow_ops_plan`                          | Create the mission and strategy.                             |
-| **Architectural Map** | `shadow_recon_topography`                  | Contextualize the target layers (if context wasn't enough).  |
-| **Detailed Briefing** | `shadow_ops_briefing` (altitude: "ground") | Full analytics, collisions, working sets.                    |
-| **Lean Briefing**     | `shadow_ops_briefing` (altitude: "orbit")  | Counts + candidates only (~200 tokens).                      |
-| **Graph View**        | `shadow_ops_graph`                         | Visualize the initiative's hierarchy.                        |
+| Setup Action          | Precise Tool Call                          | Usage                                                                                               |
+| :-------------------- | :----------------------------------------- | :-------------------------------------------------------------------------------------------------- |
+| **Session Start**     | `shadow_ops_context`                       | **START HERE** — hologram + chronicle + briefing in one call                                        |
+| **Establish Plan**    | `shadow_ops_plan`                          | Create the mission and strategy.                                                                    |
+| **Architectural Map** | `shadow_recon_topography`                  | Contextualize the target layers (if context wasn't enough).                                         |
+| **Detailed Briefing** | `shadow_ops_briefing` (altitude: "ground") | Full analytics, collisions, working sets.                                                           |
+| **Lean Briefing**     | `shadow_ops_briefing` (altitude: "orbit")  | Counts + candidates only (~200 tokens).                                                             |
+| **Graph View**        | `shadow_ops_graph`                         | Visualize the initiative's hierarchy.                                                               |
+| **Theme Patterns**    | `shadow_ops_crystallize_theme`             | Before planning: surface recurring themes across past missions to avoid repeating solved problems.  |
+| **Prior Handoffs**    | `shadow_ops_handoff_read`                  | In multi-agent contexts: retrieve typed findings from a prior RECON agent before defining strategy. |
+| **Event Mesh**        | `shadow_analyze_mesh`                      | When planning event-driven or API work: map all HTTP routes, socket events, pubsub topics.          |
 
 _Note: **Always start with `shadow_ops_context`** for instant mission landscape + architectural context. Ensure the `outcomeContract` is binary and verifiable. Parent initiatives auto-cascade on child completion — no manual closing needed._
 

package/dist/skills/shadow_onboard/SKILL.md

@@ -17,19 +17,23 @@ Initialize and analyze a new repository for deep intelligence.
 5.  **Architectural Deep Dive** (optional):
     - `shadow_recon_topography` (repoPath) — View layers (Entry/Logic/Data/Utility/Test).
     - `shadow_ops_chronicle` (limit: 5, repoPath) — Narrative feed.
-6.  **Hooks Activation**: `shadow_env_hooks` (action: "install", repoPath).
+    - `shadow_analyze_mesh` (repoPath) — If repo is event-driven: map HTTP routes, socket events, pubsub topics immediately.
+    - `shadow_env_diagnose` (repoPath) — Verify environment health: hooks installed, index state, ember daemon status.
+6.  **Hooks Activation**: `shadow_env_hooks` (action: "install", repoPath) — installs post-commit and **post-checkout** hooks. Post-checkout fires incremental reindex in background on every branch switch.
 7.  **Establish Mission**: `shadow_ops_plan` (name, goal, repoPath).
 
 ## Precise Tooling
 
-| Action            | Atomic Tool                                                      |
-| :---------------- | :--------------------------------------------------------------- |
-| **Index**         | `shadow_recon_onboard`                                           |
-| **Hologram**      | `shadow_recon_hologram` (repoPath)                               |
-| **Layers**        | `shadow_recon_topography`                                        |
-| **History**       | `shadow_ops_chronicle` (limit: 10)                               |
-| **Resume (lean)** | `shadow_ops_briefing` (scope: "project", altitude: "orbit")      |
-| **Resume (full)** | `shadow_ops_briefing` (scope: "project", altitude: "atmosphere") |
-| **Hooks**         | `shadow_env_hooks` (action: "install")                           |
+| Action            | Atomic Tool                                                                          |
+| :---------------- | :----------------------------------------------------------------------------------- |
+| **Index**         | `shadow_recon_onboard`                                                               |
+| **Hologram**      | `shadow_recon_hologram` (repoPath)                                                   |
+| **Layers**        | `shadow_recon_topography`                                                            |
+| **History**       | `shadow_ops_chronicle` (limit: 10)                                                   |
+| **Resume (lean)** | `shadow_ops_briefing` (scope: "project", altitude: "orbit")                          |
+| **Resume (full)** | `shadow_ops_briefing` (scope: "project", altitude: "atmosphere")                     |
+| **Hooks**         | `shadow_env_hooks` (action: "install")                                               |
+| **Env Health**    | `shadow_env_diagnose` (repoPath) — hooks status, index state, ember warming progress |
+| **Event Mesh**    | `shadow_analyze_mesh` (repoPath) — event-driven repos: routes + topics surface       |
 
-_Note: Always use absolute paths for `repoPath`. Call `shadow_recon_hologram` immediately after init for instant architectural context._
+_Note: Always use absolute paths for `repoPath`. Call `shadow_recon_hologram` immediately after init for instant architectural context. `shadow_env_hooks` now installs both post-commit and post-checkout hooks — branch switches will auto-reindex in background via Ember daemon._

package/dist/skills/shadow_synthesize/SKILL.md

@@ -23,12 +23,13 @@ Distill mission logs into an Architectural Decision Record (ADR) and persist it
 
 ## Precise Tooling
 
-| Action                | Atomic Tool                              | Usage                                           |
-| :-------------------- | :--------------------------------------- | :---------------------------------------------- |
-| **Complete & Seal**   | `shadow_ops_track` (status: "completed") | **Primary**. Triggers auto-synthesis + cascade. |
-| **Manual Distill**    | `shadow_ops_synthesize`                  | Re-run synthesis manually (re-gen only).        |
-| **Crystallize First** | `shadow_ops_crystallize`                 | Compress raw logs before synthesis.             |
-| **View Chronicle**    | `shadow_ops_chronicle`                   | View the combined narrative feed.               |
+| Action                | Atomic Tool                              | Usage                                                             |
+| :-------------------- | :--------------------------------------- | :---------------------------------------------------------------- |
+| **Complete & Seal**   | `shadow_ops_track` (status: "completed") | **Primary**. Triggers auto-synthesis + cascade.                   |
+| **Manual Distill**    | `shadow_ops_synthesize`                  | Re-run synthesis manually (re-gen only).                          |
+| **Crystallize First** | `shadow_ops_crystallize`                 | Compress raw logs before synthesis.                               |
+| **Theme Crystallize** | `shadow_ops_crystallize_theme`           | Cross-mission: cluster semantic themes across ALL missions' logs. |
+| **View Chronicle**    | `shadow_ops_chronicle`                   | View the combined narrative feed.                                 |
 
 _Note: Synthesis consolidation includes all child missions recursively. Cascade parent completion propagates upward through the entire hierarchy._
 

package/dist/skills/shadow_understand/SKILL.md

@@ -19,27 +19,33 @@ Find the high-signal path to understanding complex logic.
    - `shadow_analyze_impact` (symbolName, filePath, depth: 3, repoPath) — Blast radius.
    - `shadow_analyze_deps` (filePath, direction: "imported_by", repoPath) — Who depends on this?
    - `shadow_search_concept` (query, repoPath) — Semantic search.
+   - `shadow_analyze_mesh` (repoPath) — When the system is event-driven: map all HTTP routes, socket events, pubsub topics and their producers/consumers.
+   - `shadow_analyze_type_graph` (filePath, repoPath) — When understanding a type system: interface/class inheritance chains.
 4. **Mechanics (The How)**:
    - **For Logic**: `shadow_analyze_flow` (symbolName, filePath, repoPath) — Trace execution.
    - **For Objects**: `shadow_inspect_file` (filePath, detailLevel: "signatures", repoPath) — All exports.
    - **For Symbol Deep Dive**: `shadow_inspect_symbol` (symbolName, filePath, context: "full", repoPath) — With deps.
+   - **For Change History**: `shadow_analyze_explain_diff` (fromCommit, toCommit, repoPath) — Semantic narrative of what changed and why between commits.
 5. **Synthesis**: `shadow_ops_log` (missionId, type: "discovery", content, symbolName, repoPath).
 
 ## Precise Tooling
 
-| Discovery Layer    | Atomic Tool                                                                                       |
-| :----------------- | :------------------------------------------------------------------------------------------------ |
-| **Session Start**  | `shadow_ops_context` (repoPath) — **START HERE**                                                  |
-| **Hologram**       | `shadow_recon_hologram` (repoPath) — if you need standalone hologram                              |
-| **History**        | `shadow_ops_chronicle` (limit: 5) — if you need more than 5 from context                          |
-| **Layers**         | `shadow_recon_topography` — detailed breakdown                                                    |
-| **Mission Detail** | `shadow_ops_briefing` (altitude: "ground") — full logs + working set                              |
-| **Blast Radius**   | `shadow_analyze_impact` (symbolName, depth: 3)                                                    |
-| **Dependents**     | `shadow_analyze_deps` (filePath, direction: "imported_by")                                        |
-| **Flow Trace**     | `shadow_analyze_flow` (symbolName, filePath)                                                      |
-| **Structure**      | `shadow_inspect_file` (detailLevel: "signatures")                                                 |
-| **Deep Dive**      | `shadow_inspect_symbol` (context: "full")                                                         |
-| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted results with layer classification |
+| Discovery Layer    | Atomic Tool                                                                                          |
+| :----------------- | :--------------------------------------------------------------------------------------------------- |
+| **Session Start**  | `shadow_ops_context` (repoPath) — **START HERE**                                                     |
+| **Hologram**       | `shadow_recon_hologram` (repoPath) — if you need standalone hologram                                 |
+| **History**        | `shadow_ops_chronicle` (limit: 5) — if you need more than 5 from context                             |
+| **Layers**         | `shadow_recon_topography` — detailed breakdown                                                       |
+| **Mission Detail** | `shadow_ops_briefing` (altitude: "ground") — full logs + working set                                 |
+| **Blast Radius**   | `shadow_analyze_impact` (symbolName, depth: 3)                                                       |
+| **Dependents**     | `shadow_analyze_deps` (filePath, direction: "imported_by")                                           |
+| **Flow Trace**     | `shadow_analyze_flow` (symbolName, filePath)                                                         |
+| **Structure**      | `shadow_inspect_file` (detailLevel: "signatures")                                                    |
+| **Deep Dive**      | `shadow_inspect_symbol` (context: "full")                                                            |
+| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted results with layer classification    |
+| **Event Mesh**     | `shadow_analyze_mesh` (repoPath) — HTTP routes, socket events, pubsub topics + producers/consumers   |
+| **Type Graph**     | `shadow_analyze_type_graph` (filePath) — interface/class inheritance chains                          |
+| **Explain Diff**   | `shadow_analyze_explain_diff` (fromCommit, toCommit) — semantic narrative of changes between commits |
 
 _Note: **ALWAYS start with `shadow_ops_context`** for instant architectural context + history + mission state in ONE call. Use `context: "definition"` for token-efficient single symbol inspection._
 

package/dist/web-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.5",
+  "version": "1.0.6",
   "toolsByPrefix": {
     "RECON": {
       "subcommands": [
@@ -15,8 +15,11 @@
       "subcommands": [
         "debt",
         "deps",
+        "explain_diff",
         "flow",
-        "impact"
+        "impact",
+        "mesh",
+        "type_graph"
       ],
       "description": "Calculate blast radius and Strategic Risk Scoring of changing a symbol."
     },
@@ -35,12 +38,16 @@
         "chronicle",
         "context",
         "crystallize",
+        "crystallize_theme",
         "graph",
+        "handoff",
+        "handoff_read",
         "health",
         "log",
         "plan",
         "synthesize",
-        "track"
+        "track",
+        "working_set_check"
       ],
       "description": "Create a new development mission or strategic initiative with goals and strategy."
     },
@@ -57,7 +64,7 @@
         "repair",
         "trace"
       ],
-      "description": "Full lifecycle synchronization - Repairs index, analyzes changes, and re-hydrates state."
+      "description": "Full lifecycle synchronization - Repairs index, analyzes changes, and re-hydrates state. Lifecycle status mutation is opt-in via flags."
     },
     "ENV": {
       "subcommands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@precisionutilityguild/liquid-shadow",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Tactical Repository Intelligence Operative - Liquid Shadow Ecosystem",
   "homepage": "https://liquidshadow.pugcorp.online/",
   "repository": {
@@ -41,7 +41,7 @@
     "dev": "tsx src/entry/cli/index.ts",
     "mcp": "tsx src/entry/mcp/server.ts",
     "start": "node dist/entry/cli/index.js",
-    "start-mcp": "node dist/mcp/server.js",
+    "start-mcp": "node dist/entry/mcp/server.js",
     "lint": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",

package/skills/shadow_audit/SKILL.md

@@ -26,6 +26,9 @@ Comprehensive health audit using Shadow analyze toolkit.
 | **Circular Deps**    | `shadow_analyze_debt` (mode: "circular-deps")                                          |
 | **Layers**           | `shadow_recon_topography` — detailed breakdown if needed                               |
 | **Config Audit**     | `shadow_search_config` (kind: "Env", **showUsage: true**) — find orphaned env vars     |
+| **Event Mesh**       | `shadow_analyze_mesh` (repoPath) — audit all HTTP routes, socket events, pubsub topics |
+| **Type Integrity**   | `shadow_analyze_type_graph` (filePath, repoPath) — interface/type inheritance chains   |
+| **Theme Patterns**   | `shadow_ops_crystallize_theme` (query, repoPath) — recurring issues across missions    |
 
 ## 💡 Intelligence Options
 

package/skills/shadow_continue/SKILL.md

@@ -25,22 +25,30 @@ description: Get briefing, pick one mission from next_work_candidates, then work
   - **Surgical Discovery:** `shadow_analyze_flow` (symbolName, filePath, repoPath).
   - **Execute Step**: Set in-progress → implement → `shadow_ops_track` (missionId, stepId, status: "completed", contextPivot, repoPath).
   - **Atomic Logging:** At least once per step. `shadow_ops_log` (missionId, type: "decision", content, symbolName, repoPath).
+  - **Inter-agent handoff** (multi-agent pipelines only): When handing off findings to another agent, call `shadow_ops_handoff` (missionId, role, summary, findings, repoPath) to persist a typed artifact with embedding. The receiving agent calls `shadow_ops_handoff_read` (missionId, query, repoPath) to semantically retrieve relevant prior handoffs.
 - **Seal the mission**: `shadow_ops_track` (missionId, status: "completed", repoPath).
   - This **auto-triggers**: ADR synthesis, Git Notes persistence, and cascade parent completion (if all sibling missions are also done, the parent auto-completes too).
   - No need to call `shadow_ops_synthesize` separately — it's automatic on completion.
 - **Optional — Crystallize** (for long-running missions with many logs): `shadow_ops_crystallize` (missionId, repoPath) compresses raw intent logs into a single crystal summary. Useful mid-mission to keep briefings lean.
+- **Optional — Theme Crystallize** (cross-mission patterns): `shadow_ops_crystallize_theme` (query, repoPath) clusters semantically related intent logs across ALL missions to surface recurring architectural themes. Use when you sense a pattern repeating across missions.
 
 ## 🛠 Precise Tooling
 
-| Action                 | Atomic Tool              | Example                                                  |
-| :--------------------- | :----------------------- | :------------------------------------------------------- |
-| **Context (one shot)** | `shadow_ops_context`     | repoPath — hologram + chronicle + briefing               |
-| **Briefing**           | `shadow_ops_briefing`    | scope: "project", altitude: "orbit", repoPath            |
-| **Flow Trace**         | `shadow_analyze_flow`    | symbolName: "handleRequest", filePath, repoPath          |
-| **Step Update**        | `shadow_ops_track`       | missionId: 4, stepId: "s2", status: "completed"          |
-| **Intent Log**         | `shadow_ops_log`         | missionId: 4, type: "fix", content: "..."                |
-| **Complete Mission**   | `shadow_ops_track`       | missionId: 4, status: "completed" — auto-synthesizes ADR |
-| **Crystallize**        | `shadow_ops_crystallize` | missionId: 4 — compress logs mid-mission                 |
+| Action                 | Atomic Tool                    | Example                                                          |
+| :--------------------- | :----------------------------- | :--------------------------------------------------------------- |
+| **Context (one shot)** | `shadow_ops_context`           | repoPath — hologram + chronicle + briefing                       |
+| **Briefing**           | `shadow_ops_briefing`          | scope: "project", altitude: "orbit", repoPath                    |
+| **Flow Trace**         | `shadow_analyze_flow`          | symbolName: "handleRequest", filePath, repoPath                  |
+| **Step Update**        | `shadow_ops_track`             | missionId: 4, stepId: "s2", status: "completed"                  |
+| **Intent Log**         | `shadow_ops_log`               | missionId: 4, type: "fix", content: "..."                        |
+| **Complete Mission**   | `shadow_ops_track`             | missionId: 4, status: "completed" — auto-synthesizes ADR         |
+| **Crystallize**        | `shadow_ops_crystallize`       | missionId: 4 — compress logs mid-mission                         |
+| **Theme Crystallize**  | `shadow_ops_crystallize_theme` | query: "auth patterns" — cross-mission semantic clustering       |
+| **Handoff (write)**    | `shadow_ops_handoff`           | missionId, role: "RECON", summary, findings — persist artifact   |
+| **Handoff (read)**     | `shadow_ops_handoff_read`      | missionId, query: "auth findings" — semantic retrieval           |
+| **Event Mesh**         | `shadow_analyze_mesh`          | repoPath — surface all HTTP routes, socket events, pubsub topics |
+| **Type Graph**         | `shadow_analyze_type_graph`    | filePath, repoPath — interface/type inheritance map              |
+| **Explain Diff**       | `shadow_analyze_explain_diff`  | fromCommit, toCommit, repoPath — semantic diff narrative         |
 
 _Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
 
@@ -52,4 +60,4 @@ _Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
 
 ---
 
-**Tools:** `shadow_ops_context` (optional start), `shadow_ops_briefing`, `shadow_ops_track`, `shadow_ops_log`, `shadow_ops_crystallize`, `shadow_sync_trace`. For discovery: `shadow_search_*`, `shadow_recon_*`, `shadow_analyze_*`.
+**Tools:** `shadow_ops_context` (optional start), `shadow_ops_briefing`, `shadow_ops_track`, `shadow_ops_log`, `shadow_ops_crystallize`, `shadow_ops_crystallize_theme`, `shadow_ops_handoff`, `shadow_ops_handoff_read`, `shadow_sync_trace`. For discovery: `shadow_search_*`, `shadow_recon_*`, `shadow_analyze_*` (including `shadow_analyze_mesh`, `shadow_analyze_type_graph`, `shadow_analyze_explain_diff`).

package/skills/shadow_mission/SKILL.md

@@ -23,14 +23,17 @@ Define the objective, strategy, and success criteria for a new mission. This wor
 
 ## Precise Tooling
 
-| Setup Action          | Precise Tool Call                          | Usage                                                        |
-| :-------------------- | :----------------------------------------- | :----------------------------------------------------------- |
-| **Session Start**     | `shadow_ops_context`                       | **START HERE** — hologram + chronicle + briefing in one call |
-| **Establish Plan**    | `shadow_ops_plan`                          | Create the mission and strategy.                             |
-| **Architectural Map** | `shadow_recon_topography`                  | Contextualize the target layers (if context wasn't enough).  |
-| **Detailed Briefing** | `shadow_ops_briefing` (altitude: "ground") | Full analytics, collisions, working sets.                    |
-| **Lean Briefing**     | `shadow_ops_briefing` (altitude: "orbit")  | Counts + candidates only (~200 tokens).                      |
-| **Graph View**        | `shadow_ops_graph`                         | Visualize the initiative's hierarchy.                        |
+| Setup Action          | Precise Tool Call                          | Usage                                                                                               |
+| :-------------------- | :----------------------------------------- | :-------------------------------------------------------------------------------------------------- |
+| **Session Start**     | `shadow_ops_context`                       | **START HERE** — hologram + chronicle + briefing in one call                                        |
+| **Establish Plan**    | `shadow_ops_plan`                          | Create the mission and strategy.                                                                    |
+| **Architectural Map** | `shadow_recon_topography`                  | Contextualize the target layers (if context wasn't enough).                                         |
+| **Detailed Briefing** | `shadow_ops_briefing` (altitude: "ground") | Full analytics, collisions, working sets.                                                           |
+| **Lean Briefing**     | `shadow_ops_briefing` (altitude: "orbit")  | Counts + candidates only (~200 tokens).                                                             |
+| **Graph View**        | `shadow_ops_graph`                         | Visualize the initiative's hierarchy.                                                               |
+| **Theme Patterns**    | `shadow_ops_crystallize_theme`             | Before planning: surface recurring themes across past missions to avoid repeating solved problems.  |
+| **Prior Handoffs**    | `shadow_ops_handoff_read`                  | In multi-agent contexts: retrieve typed findings from a prior RECON agent before defining strategy. |
+| **Event Mesh**        | `shadow_analyze_mesh`                      | When planning event-driven or API work: map all HTTP routes, socket events, pubsub topics.          |
 
 _Note: **Always start with `shadow_ops_context`** for instant mission landscape + architectural context. Ensure the `outcomeContract` is binary and verifiable. Parent initiatives auto-cascade on child completion — no manual closing needed._
 

package/skills/shadow_onboard/SKILL.md

@@ -17,19 +17,23 @@ Initialize and analyze a new repository for deep intelligence.
 5.  **Architectural Deep Dive** (optional):
     - `shadow_recon_topography` (repoPath) — View layers (Entry/Logic/Data/Utility/Test).
     - `shadow_ops_chronicle` (limit: 5, repoPath) — Narrative feed.
-6.  **Hooks Activation**: `shadow_env_hooks` (action: "install", repoPath).
+    - `shadow_analyze_mesh` (repoPath) — If repo is event-driven: map HTTP routes, socket events, pubsub topics immediately.
+    - `shadow_env_diagnose` (repoPath) — Verify environment health: hooks installed, index state, ember daemon status.
+6.  **Hooks Activation**: `shadow_env_hooks` (action: "install", repoPath) — installs post-commit and **post-checkout** hooks. Post-checkout fires incremental reindex in background on every branch switch.
 7.  **Establish Mission**: `shadow_ops_plan` (name, goal, repoPath).
 
 ## Precise Tooling
 
-| Action            | Atomic Tool                                                      |
-| :---------------- | :--------------------------------------------------------------- |
-| **Index**         | `shadow_recon_onboard`                                           |
-| **Hologram**      | `shadow_recon_hologram` (repoPath)                               |
-| **Layers**        | `shadow_recon_topography`                                        |
-| **History**       | `shadow_ops_chronicle` (limit: 10)                               |
-| **Resume (lean)** | `shadow_ops_briefing` (scope: "project", altitude: "orbit")      |
-| **Resume (full)** | `shadow_ops_briefing` (scope: "project", altitude: "atmosphere") |
-| **Hooks**         | `shadow_env_hooks` (action: "install")                           |
+| Action            | Atomic Tool                                                                          |
+| :---------------- | :----------------------------------------------------------------------------------- |
+| **Index**         | `shadow_recon_onboard`                                                               |
+| **Hologram**      | `shadow_recon_hologram` (repoPath)                                                   |
+| **Layers**        | `shadow_recon_topography`                                                            |
+| **History**       | `shadow_ops_chronicle` (limit: 10)                                                   |
+| **Resume (lean)** | `shadow_ops_briefing` (scope: "project", altitude: "orbit")                          |
+| **Resume (full)** | `shadow_ops_briefing` (scope: "project", altitude: "atmosphere")                     |
+| **Hooks**         | `shadow_env_hooks` (action: "install")                                               |
+| **Env Health**    | `shadow_env_diagnose` (repoPath) — hooks status, index state, ember warming progress |
+| **Event Mesh**    | `shadow_analyze_mesh` (repoPath) — event-driven repos: routes + topics surface       |
 
-_Note: Always use absolute paths for `repoPath`. Call `shadow_recon_hologram` immediately after init for instant architectural context._
+_Note: Always use absolute paths for `repoPath`. Call `shadow_recon_hologram` immediately after init for instant architectural context. `shadow_env_hooks` now installs both post-commit and post-checkout hooks — branch switches will auto-reindex in background via Ember daemon._

package/skills/shadow_synthesize/SKILL.md

@@ -23,12 +23,13 @@ Distill mission logs into an Architectural Decision Record (ADR) and persist it
 
 ## Precise Tooling
 
-| Action                | Atomic Tool                              | Usage                                           |
-| :-------------------- | :--------------------------------------- | :---------------------------------------------- |
-| **Complete & Seal**   | `shadow_ops_track` (status: "completed") | **Primary**. Triggers auto-synthesis + cascade. |
-| **Manual Distill**    | `shadow_ops_synthesize`                  | Re-run synthesis manually (re-gen only).        |
-| **Crystallize First** | `shadow_ops_crystallize`                 | Compress raw logs before synthesis.             |
-| **View Chronicle**    | `shadow_ops_chronicle`                   | View the combined narrative feed.               |
+| Action                | Atomic Tool                              | Usage                                                             |
+| :-------------------- | :--------------------------------------- | :---------------------------------------------------------------- |
+| **Complete & Seal**   | `shadow_ops_track` (status: "completed") | **Primary**. Triggers auto-synthesis + cascade.                   |
+| **Manual Distill**    | `shadow_ops_synthesize`                  | Re-run synthesis manually (re-gen only).                          |
+| **Crystallize First** | `shadow_ops_crystallize`                 | Compress raw logs before synthesis.                               |
+| **Theme Crystallize** | `shadow_ops_crystallize_theme`           | Cross-mission: cluster semantic themes across ALL missions' logs. |
+| **View Chronicle**    | `shadow_ops_chronicle`                   | View the combined narrative feed.                                 |
 
 _Note: Synthesis consolidation includes all child missions recursively. Cascade parent completion propagates upward through the entire hierarchy._
 

package/skills/shadow_understand/SKILL.md

@@ -19,27 +19,33 @@ Find the high-signal path to understanding complex logic.
    - `shadow_analyze_impact` (symbolName, filePath, depth: 3, repoPath) — Blast radius.
    - `shadow_analyze_deps` (filePath, direction: "imported_by", repoPath) — Who depends on this?
    - `shadow_search_concept` (query, repoPath) — Semantic search.
+   - `shadow_analyze_mesh` (repoPath) — When the system is event-driven: map all HTTP routes, socket events, pubsub topics and their producers/consumers.
+   - `shadow_analyze_type_graph` (filePath, repoPath) — When understanding a type system: interface/class inheritance chains.
 4. **Mechanics (The How)**:
    - **For Logic**: `shadow_analyze_flow` (symbolName, filePath, repoPath) — Trace execution.
    - **For Objects**: `shadow_inspect_file` (filePath, detailLevel: "signatures", repoPath) — All exports.
    - **For Symbol Deep Dive**: `shadow_inspect_symbol` (symbolName, filePath, context: "full", repoPath) — With deps.
+   - **For Change History**: `shadow_analyze_explain_diff` (fromCommit, toCommit, repoPath) — Semantic narrative of what changed and why between commits.
 5. **Synthesis**: `shadow_ops_log` (missionId, type: "discovery", content, symbolName, repoPath).
 
 ## Precise Tooling
 
-| Discovery Layer    | Atomic Tool                                                                                       |
-| :----------------- | :------------------------------------------------------------------------------------------------ |
-| **Session Start**  | `shadow_ops_context` (repoPath) — **START HERE**                                                  |
-| **Hologram**       | `shadow_recon_hologram` (repoPath) — if you need standalone hologram                              |
-| **History**        | `shadow_ops_chronicle` (limit: 5) — if you need more than 5 from context                          |
-| **Layers**         | `shadow_recon_topography` — detailed breakdown                                                    |
-| **Mission Detail** | `shadow_ops_briefing` (altitude: "ground") — full logs + working set                              |
-| **Blast Radius**   | `shadow_analyze_impact` (symbolName, depth: 3)                                                    |
-| **Dependents**     | `shadow_analyze_deps` (filePath, direction: "imported_by")                                        |
-| **Flow Trace**     | `shadow_analyze_flow` (symbolName, filePath)                                                      |
-| **Structure**      | `shadow_inspect_file` (detailLevel: "signatures")                                                 |
-| **Deep Dive**      | `shadow_inspect_symbol` (context: "full")                                                         |
-| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted results with layer classification |
+| Discovery Layer    | Atomic Tool                                                                                          |
+| :----------------- | :--------------------------------------------------------------------------------------------------- |
+| **Session Start**  | `shadow_ops_context` (repoPath) — **START HERE**                                                     |
+| **Hologram**       | `shadow_recon_hologram` (repoPath) — if you need standalone hologram                                 |
+| **History**        | `shadow_ops_chronicle` (limit: 5) — if you need more than 5 from context                             |
+| **Layers**         | `shadow_recon_topography` — detailed breakdown                                                       |
+| **Mission Detail** | `shadow_ops_briefing` (altitude: "ground") — full logs + working set                                 |
+| **Blast Radius**   | `shadow_analyze_impact` (symbolName, depth: 3)                                                       |
+| **Dependents**     | `shadow_analyze_deps` (filePath, direction: "imported_by")                                           |
+| **Flow Trace**     | `shadow_analyze_flow` (symbolName, filePath)                                                         |
+| **Structure**      | `shadow_inspect_file` (detailLevel: "signatures")                                                    |
+| **Deep Dive**      | `shadow_inspect_symbol` (context: "full")                                                            |
+| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted results with layer classification    |
+| **Event Mesh**     | `shadow_analyze_mesh` (repoPath) — HTTP routes, socket events, pubsub topics + producers/consumers   |
+| **Type Graph**     | `shadow_analyze_type_graph` (filePath) — interface/class inheritance chains                          |
+| **Explain Diff**   | `shadow_analyze_explain_diff` (fromCommit, toCommit) — semantic narrative of changes between commits |
 
 _Note: **ALWAYS start with `shadow_ops_context`** for instant architectural context + history + mission state in ONE call. Use `context: "definition"` for token-efficient single symbol inspection._