@precisionutilityguild/liquid-shadow 1.0.7 → 1.0.10

package/dist/skills/shadow_crystallize/SKILL.md

@@ -3,39 +3,25 @@ name: crystallize
 description: Compress a mission's intent logs into a dense crystal summary for token-efficient briefings. Use when a mission has accumulated many raw logs, when briefings are too verbose, or when the user asks about log compression, crystallization, or context reduction.
 ---
 
-# Intent Log Crystallization
+# Crystallize
 
-Compress raw intent logs into a single crystal summary node. The crystal replaces verbose raw logs in briefings, reducing token usage while preserving the mission's key decisions, context, and consequences.
+Compress raw intent logs into a crystal so briefings stay useful instead of noisy.
 
-## When to Crystallize
+## Core calls
 
-- A mission has **10+ raw intent logs** and briefings are getting verbose.
-- Mid-mission, before requesting a detailed briefing — keeps `atmosphere` altitude lean.
-- Before synthesis (optional) — produces cleaner ADRs from compressed input.
-- The briefing at `atmosphere` altitude already prefers crystals over raw logs (`findByMissionPreferCrystal`), so crystallizing makes those briefings significantly leaner.
+- Mission-level compression: `shadow_ops_crystallize({ repoPath, missionId })`
+- Verify the result: `shadow_ops_briefing({ repoPath, scope: "mission", missionId, altitude: "atmosphere" })`
+- Cross-mission theme compression: `shadow_ops_crystallize_theme({ repoPath, theme, missionIds?, limit? })`
 
-## Workflow
+## When to use it
 
-1. **Crystallize**: `shadow_ops_crystallize` (missionId, repoPath) — Compresses all raw logs into one crystal node. Raw logs are marked as `absorbed`.
-2. **Verify**: `shadow_ops_briefing` (scope: "mission", missionId, altitude: "atmosphere", repoPath) — Crystal should appear in `recent_activity` instead of raw logs.
-
-## Precise Tooling
-
-| Action           | Atomic Tool                                    | Usage                                   |
-| :--------------- | :--------------------------------------------- | :-------------------------------------- |
-| **Crystallize**  | `shadow_ops_crystallize`                       | missionId, repoPath — compress raw logs |
-| **Check Status** | `shadow_ops_briefing` (altitude: "atmosphere") | Verify crystal appears in activity      |
-| **Full Logs**    | `shadow_ops_briefing` (altitude: "ground")     | Still shows raw logs if needed          |
-
-## What the Crystal Contains
-
-- Mission name and ID
-- Count of compressed logs and symbols
-- Log types present (decision, fix, discovery, blocker)
-- Structured breakdown: decisions, context, consequences, recommendations
+- A mission has many raw logs and `atmosphere` briefings are getting bloated.
+- You want cleaner synthesis input before closing a mission.
+- You want to surface repeating patterns across missions with `theme`.
 
 ## Notes
 
 - Crystallization is **idempotent**: if no new raw logs exist, it reports `already_crystallized`.
-- New logs added after crystallization remain as raw until the next crystallize call.
-- Raw logs are **not deleted** — they're marked as absorbed. `ground` altitude still shows them.
+- Raw logs are not deleted; they are marked as absorbed.
+- New logs stay raw until the next crystallize call.
+- `shadow_ops_crystallize_theme` takes `theme`, not `query`.

package/dist/skills/shadow_mission/SKILL.md

@@ -1,53 +1,39 @@
 ---
 name: mission
-description: Define the objective, strategy, and success criteria for a new development mission. Use when planning strategic initiatives, creating missions, setting up development goals, or when the user asks about mission planning, strategic alignment, or outcome contracts.
+description: Define the objective, strategy, and success criteria for a mission. Use when planning new work, shaping initiatives, writing outcome contracts, or aligning a task before execution starts.
 ---
 
-# Mission Strategy & Setup
+# Mission
 
-Define the objective, strategy, and success criteria for a new mission. This workflow is for **Strategic Alignment and Planning**.
+This skill is for planning. It stops at "ready to execute."
 
-> **IMPORTANT**: This workflow stops at the "Ready to Execute" state. For implementation and automated execution, use **/continue**.
+## Start
 
-## Workflow
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. If needed, expand with:
+   - `shadow_recon_topography({ repoPath })`
+   - `shadow_ops_briefing({ repoPath, scope: "project", altitude: "ground" })`
+   - `shadow_ops_chronicle({ repoPath, limit: 10 })`
+3. Reuse prior intelligence when available:
+   - `shadow_ops_handoff_read({ repoPath, missionId?, kind?, query? })`
+   - `shadow_ops_crystallize_theme({ repoPath, theme, missionIds? })`
 
-1.  **Session Context**: `shadow_ops_context` (repoPath) — **ONE CALL** for hologram + chronicle(5) + briefing (with relevance-ranked `next_work_candidates`). Check existing candidates and recent decisions before creating new work.
-2.  **Optional Expanded Context** (only if needed):
-    - `shadow_recon_topography` (repoPath) — Detailed layer breakdown to align goal with architecture.
-    - `shadow_ops_chronicle` (limit: 10, repoPath) — More historical ADRs if 5 isn't enough.
-    - `shadow_ops_briefing` (scope: "project", altitude: "ground", repoPath) — Full detail with analytics, collisions, and working sets.
-3.  **Strategic Plan**: `shadow_ops_plan` (name, goal, outcomeContract, ...).
-    - **Strategy DAG**: Define logical steps and verification rules.
-    - **Initiative vs Mission**: Decide if this is a parent (Initiative) or a leaf (Mission). Parent missions auto-complete via cascade when all children finish.
-4.  **Alignment**: Present the plan to the user. Do not begin execution until the user approves the strategy.
+## Create the mission
 
-## Precise Tooling
+Use `shadow_ops_plan` with the fields that matter:
 
-| 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.          |
+- `name`: short, concrete title
+- `goal`: what changes and why
+- `outcomeContract`: binary success test
+- `strategy`: JSON step graph when the work has multiple stages
+- `workingSet`: expected files or directories
+- `templateId`: `refactoring`, `feature`, or `bug-fix`
+- `parentId`: when this mission belongs under an initiative
 
-_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._
+## Planning rules
 
-## Briefing Altitude Levels
-
-- **`orbit`** (~200 tokens): Counts + relevance-ranked candidates only. Use for quick checks.
-- **`atmosphere`** (default): Strategy graphs, crystal summaries, hierarchy, analytics.
-- **`ground`** (full): Raw logs, working sets, collision analysis, ancestor activity.
-
-## Intent Logging (Strategic Quality)
-
-Capture the "Why" and "How" during the planning phase to ensure the final ADR has architectural depth.
-
-- **Decision Logs**: Capture why a specific strategy or library was chosen.
-- **Discovery Logs**: Record insights found during initial reconnaissance.
-
-**Hand-off**: Once the mission is planned and logged, the setup phase is over. Execute via `/continue`.
+- Prefer a leaf mission when one deliverable can be completed in one run.
+- Use a parent initiative only when the work is intentionally split into child missions.
+- Keep `outcomeContract` verifiable. "Looks good" is not a contract.
+- If API or event boundaries matter, use `shadow_analyze_mesh({ repoPath, topic, type? })` with a concrete route or topic fragment.
+- Present the plan for approval before execution. Use `/continue` for the actual implementation pass.

package/dist/skills/shadow_onboard/SKILL.md

@@ -1,39 +1,30 @@
 ---
 name: onboard
-description: Initialize and analyze a new repository for deep intelligence by building semantic index, syncing state, activating git hooks, and establishing missions. Use when onboarding to a new repository, initializing Shadow Engine, setting up git hooks, or when the user asks about repository setup, initialization, or first-time configuration.
+description: Initialize and analyze a repository for Shadow workflows. Use when onboarding a repo, bootstrapping indexes and hooks, checking intelligence health, or preparing the first mission.
 ---
 
-# Repository Onboarding
-
-Initialize and analyze a new repository for deep intelligence.
-
-## Workflow
-
-1.  **Semantic Init**: `shadow_recon_onboard` (repoPath) — **Only run once** per repo to build the baseline. Auto-populates the hologram.
-2.  **Read Hologram**: `shadow_recon_hologram` (repoPath) — Get instant architectural context (~1300 tokens: topography + gravity zones).
-3.  **Unified Sync**: `shadow_sync_trace` (repoPath) — **The One-Stop Shop**. Performs indexing + ghost analysis + mission re-hydration.
-4.  **Active Briefing**: `shadow_ops_briefing` (scope: "project", altitude: "atmosphere", repoPath) — Resumes the shared backlog with relevance-ranked candidates.
-    - Use `altitude: "orbit"` for a lean overview (~200 tokens), or `altitude: "ground"` for full detail.
-5.  **Architectural Deep Dive** (optional):
-    - `shadow_recon_topography` (repoPath) — View layers (Entry/Logic/Data/Utility/Test).
-    - `shadow_ops_chronicle` (limit: 5, repoPath) — Narrative feed.
-    - `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")                                               |
-| **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. `shadow_env_hooks` now installs both post-commit and post-checkout hooks — branch switches will auto-reindex in background via Ember daemon._
+# Onboard
+
+Use this skill when a repository needs its first Shadow pass or when a fresh clone needs to be made operational.
+
+## Core workflow
+
+1. `shadow_recon_onboard({ repoPath })`
+2. `shadow_recon_hologram({ repoPath, compact: true })`
+3. `shadow_sync_trace({ repoPath })`
+4. `shadow_ops_health({ repoPath })`
+5. `shadow_ops_context({ repoPath, compact: true })`
+
+## Useful follow-ups
+
+- `shadow_recon_topography({ repoPath })` for layer breakdown.
+- `shadow_ops_chronicle({ repoPath, limit: 5 })` for recent decisions.
+- `shadow_env_diagnose({ repoPath })` for hooks, index, and daemon health.
+- `shadow_env_hooks({ repoPath, action: "install", enableAutoRefresh: true, enableSymbolHealing: true })`
+- `shadow_ops_plan({ repoPath, name, goal, outcomeContract? })` for the first mission.
+
+## Rules
+
+- Always use an absolute `repoPath`.
+- `shadow_recon_onboard` is the baseline bootstrap; `shadow_sync_trace` is the normal follow-up maintenance pass.
+- Do not call `shadow_analyze_mesh` without a concrete `topic`.

package/dist/skills/shadow_research/SKILL.md

@@ -1,34 +1,26 @@
 ---
 name: research
-description: Conduct high-signal research for external dependencies by combining local context, web search, and Context7 documentation. Use when researching libraries, checking integration examples, verifying versions, or when the user asks about external dependencies, library documentation, or integration patterns.
+description: Research external dependencies without losing local context. Use when checking library usage, verifying versions, finding integration examples, or comparing official documentation against what the repo already does.
 ---
 
-# External Research
+# Research
 
-High-signal research for external dependencies.
+Start local, then verify externally.
 
-## 🚀 Workflow
+## Local first
 
-1. **Local Context**: `shadow_search_concept` (query: "library name", repoPath). Find existing integration examples.
-2. **Web Search**: Use the `WebSearch` tool for official docs and latest versions.
-3. **Deep Intel (Context7)**: resolve-library-id, query-docs (server: user-context7).
-4. **Integration Check**: `shadow_inspect_file` (filePath, detailLevel: "signatures", repoPath).
-5. **Log Findings**: `shadow_ops_log` (type: "discovery", content, repoPath).
+- `shadow_search_concept({ repoPath, query, compact: true })` for existing patterns.
+- `shadow_search_path({ repoPath, query, ranked: true })` for likely integration files.
+- `shadow_search_config({ repoPath, key?, query?, showUsage: true })` for env and config hooks.
+- `shadow_analyze_deps({ repoPath, filePath, direction: "imports" | "imported_by" })` to see how the dependency sits in the graph.
+- `shadow_inspect_file({ repoPath, filePath, detailLevel: "signatures" })` for a quick local API read.
 
-## 🛠 Precise Tooling
+## External verification
 
-| Discovery Layer    | Atomic Tool                                                                 |
-| :----------------- | :-------------------------------------------------------------------------- |
-| **Local Usage**    | `shadow_search_concept` (query, **compact: true** for broad search)         |
-| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted with layers |
-| **Config Check**   | `shadow_search_config` (key, **showUsage: true**) — with usage counts       |
-| **External Docs**  | context7 tools (user-context7)                                              |
-| **Relational**     | `shadow_analyze_deps` (filePath, direction)                                 |
+- Use the host model's documentation or web tools to read official vendor docs and primary sources.
+- Check the exact installed version in `package.json`, lockfiles, or existing imports before trusting examples.
+- Prefer official docs over blogs, and repo-local patterns over generic snippets.
 
-## 💡 Intelligence Options
+## Closeout
 
-- **`shadow_search_concept` with `compact: true`**: Returns file paths + scores without snippets (~60% token savings). Use for broad exploration.
-- **`shadow_search_path` with `ranked: true`**: Results sorted by gravity (high-import files first) with layer classification. Reveals architecturally important files.
-- **`shadow_search_config` with `showUsage: true`**: Shows usage counts per config var and identifies orphaned vars (defined but never used in code).
-
-_Note: Always check `package.json` for the exact version before querying Context7 to ensure documentation alignment._
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, filePath? })` when the research affects an ongoing mission.

package/dist/skills/shadow_sync/SKILL.md

@@ -3,16 +3,25 @@ name: sync
 description: 'Sync index and mission state after external changes. Day-to-day: index + NanoRepair run automatically when MCP tools (search, inspect, etc.) trigger reindex. Use trace after git pull/checkout/merge (or rely on hooks); use index deep:true for full rebuild.'
 ---
 
-# Repository Synchronization
+# Sync
 
-**Day-to-day:** Index and NanoRepair run automatically when you use MCP tools (search, inspect, analyze, etc.) and a reindex occurs. No manual sync needed for edits or renames.
+Day-to-day, Shadow often reindexes on demand. Use manual sync when the repository changed outside the normal flow.
 
-## When to run sync manually
+## Prefer these calls
 
-| Situation                         | Action                                                             |
-| :-------------------------------- | :----------------------------------------------------------------- |
-| **After git pull/checkout/merge** | `shadow_sync_trace` (repoPath) — or rely on Git hooks if installed |
-| **Full rebuild (corruption)**     | `shadow_sync_index` (repoPath; use deep: true if supported)        |
-| **Repair only (rare)**            | `shadow_sync_repair` (repoPath)                                    |
+- After `pull`, `checkout`, `merge`, or large rebases:
+  - `shadow_sync_trace({ repoPath, sinceCommit?, enableContextPivot?, enableMergeSentinel? })`
+- For an explicit rebuild:
+  - `shadow_sync_index({ repoPath, deep: true })`
+- For repair only:
+  - `shadow_sync_repair({ repoPath })`
 
-**Note:** `trace` does index + ghost analysis + NanoRepair + lifecycle + mission re-hydration. Hooks run it on commit/checkout/merge.
+## Health checks
+
+- `shadow_ops_health({ repoPath })`
+- `shadow_env_diagnose({ repoPath })`
+
+## Rules
+
+- Prefer `shadow_sync_trace` over `shadow_sync_index` unless you specifically want a rebuild.
+- Use `deep: true` sparingly; it is the expensive option.

package/dist/skills/shadow_synthesize/SKILL.md

@@ -3,46 +3,24 @@ name: synthesize
 description: Distill mission logs into Architectural Decision Records (ADRs) and persist them to the Shadow Engine and Git Notes. Use when completing missions, creating ADRs, synthesizing architectural decisions, or when the user asks about decision records, mission completion, or architectural documentation.
 ---
 
-# Architectural Synthesis
+# Synthesize
 
-Distill mission logs into an Architectural Decision Record (ADR) and persist it to the Shadow Engine.
+Use this skill when a mission needs to become durable project memory.
 
-> **AUTO-PILOT ACTIVE**: Synthesis is **automatically triggered** when a mission status is set to `completed` via `shadow_ops_track`. The system handles: ADR distillation (recursive for child missions), Git Notes persistence, and **cascade parent completion** (if all siblings are done, the parent auto-completes and synthesizes too).
+## Primary path
 
-## Workflow
+- Complete the mission:
+  - `shadow_ops_track({ repoPath, missionId, status: "completed" })`
+- Verify the synthesized record:
+  - `shadow_ops_chronicle({ repoPath, limit: 5 })`
 
-1.  **Complete Mission**: `shadow_ops_track` (missionId, status: "completed", repoPath).
-    - The Shadow Engine will automatically:
-      - Distill all intent logs (recursive for child missions).
-      - Format the ADR using markdown and **Liquid Anchors**.
-      - Persist the record to SQLite and **Git Notes**.
-      - **Cascade**: If all sibling missions under the same parent are completed, the parent mission auto-completes with its own ADR synthesis.
-2.  **Verify**: Check the synthesized record via `shadow_ops_chronicle` (limit: 5, repoPath).
-3.  **Manual Synthesis**: Use `shadow_ops_synthesize` only to **re-generate** an existing record or for specific partial distillations.
-4.  **Pre-synthesis Compression** (optional): For missions with many raw logs, `shadow_ops_crystallize` (missionId, repoPath) compresses logs into a crystal summary before synthesis for cleaner ADRs.
+## Secondary tools
 
-## Precise Tooling
+- `shadow_ops_synthesize({ repoPath, missionId })` only when you need to regenerate the ADR after the mission is already complete.
+- `shadow_ops_crystallize({ repoPath, missionId })` before completion if the mission has many raw logs.
+- `shadow_ops_crystallize_theme({ repoPath, theme, missionIds? })` when you want a cross-mission architectural thread.
 
-| 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.                                 |
+## Rules
 
-_Note: Synthesis consolidation includes all child missions recursively. Cascade parent completion propagates upward through the entire hierarchy._
-
-## Cascade Parent Completion
-
-When the last child mission under a parent is completed:
-
-1. Parent status is set to `completed`
-2. A system intent log records the cascade event
-3. Parent ADR is synthesized (recursive child distillation)
-4. Parent is synced to Git Notes
-5. If the parent itself has a parent, the cascade continues upward
-
-## Tooling Strategy
-
-Synthesis is the final commit of the mission's logic into the repository's permanent history. Avoid manual markdown files for ADRs; trust the **Git Notes** architecture to preserve the "Story of the Code."
+- Completion auto-triggers synthesis and parent cascade behavior.
+- Do not maintain parallel ADR markdown files unless the user explicitly wants one.

package/dist/skills/shadow_trace_impact/SKILL.md

@@ -3,53 +3,33 @@ name: trace-impact
 description: Map the blast radius of a change by analyzing impact, flow traces, cross-repo dependencies, and boundary maps. Use when analyzing change impact, assessing risk, tracing dependencies, or when the user asks about change impact, blast radius, or dependency analysis.
 ---
 
-# Impact Analysis
-
-Map the blast radius of a change using the full Shadow analyze toolkit.
-
-## 🚀 Workflow
-
-1. **Session Context**: `shadow_ops_context` (repoPath) — **ONE CALL** for hologram + chronicle + briefing. Check if symbol is in gravity zones.
-2. **Impact (Blast Radius)**: `shadow_analyze_impact` (symbolName, filePath, depth: 3, repoPath) — ALL affected files.
-3. **Dependencies**:
-   - `shadow_analyze_deps` (filePath, direction: "imported_by", repoPath) — Who imports this?
-   - `shadow_analyze_deps` (filePath, direction: "imports", repoPath) — What does it import?
-4. **Flow Trace**: `shadow_analyze_flow` (symbolName, filePath, repoPath) — Execution path.
-5. **Health Check**:
-   - `shadow_analyze_debt` (mode: "circular-deps", repoPath) — Any import cycles?
-   - `shadow_analyze_debt` (mode: "dead-code", limit: 50, repoPath) — Unused exports?
-6. **Cross-Repo Check** (if multi-repo):
-   - `shadow_workspace_fuse` (repoPaths, repoPath).
-   - `shadow_search_symbol` (query, limit: 50, repoPath).
-7. **Boundary Map**: `shadow_recon_topography` (repoPath) — Layer crossing check.
-8. **Log Risk**: `shadow_ops_log` (missionId, type: "discovery", content, symbolName, repoPath).
-
-## 🛠 Precise Tooling
-
-| Impact Layer         | Atomic Tool                                                                |
-| :------------------- | :------------------------------------------------------------------------- |
-| **Session Start** 🚀 | `shadow_ops_context` (repoPath) — **START HERE** for context               |
-| **Hologram**         | `shadow_recon_hologram` (repoPath) — if you need standalone                |
-| **Blast Radius**     | `shadow_analyze_impact` (symbolName, depth: 3)                             |
-| **Dependents**       | `shadow_analyze_deps` (filePath, direction: "imported_by")                 |
-| **Dependencies**     | `shadow_analyze_deps` (filePath, direction: "imports")                     |
-| **Flow Path**        | `shadow_analyze_flow` (symbolName, filePath)                               |
-| **Circular Deps**    | `shadow_analyze_debt` (mode: "circular-deps")                              |
-| **Dead Code**        | `shadow_analyze_debt` (mode: "dead-code", **confidenceThreshold: "high"**) |
-| **File Discovery**   | `shadow_search_path` (query, **ranked: true**) — gravity-sorted            |
-| **Workspace Fuse**   | `shadow_workspace_fuse` (repoPaths, repoPath)                              |
-| **Topography**       | `shadow_recon_topography`                                                  |
-
-## 💡 Intelligence Options
-
-- **`shadow_search_path` with `ranked: true`**: Find related files sorted by gravity (high-import files first) with layer classification. Helps identify which affected files are architecturally critical.
-- **`shadow_analyze_debt` confidence levels**: Use `confidenceThreshold: "high"` to focus on likely dead code, avoiding noise from test fixtures and migrations.
-
-_Note: **Start with `shadow_ops_context`** for instant gravity zones + architectural context. Use depth higher than 3 for impact analysis only if the symbol is a fundamental primitive (e.g., RepositoryFactory)._
-
-## 🛠 Risk Classification
-
-- **Critical Risk**: Symbol in gravity zones (top 10) + >20 dependents + crosses layers
-- **High Risk**: >10 dependents OR crosses layers (e.g., Test -> Logic)
-- **Medium Risk**: 5-10 dependents within same layer
-- **Low Risk**: <5 dependents, same layer, no circular deps
+# Trace Impact
+
+Use this skill to answer "what breaks if we touch this?"
+
+## Core workflow
+
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. `shadow_analyze_impact({ repoPath, symbolName, filePath?, depth: 3 })`
+3. `shadow_analyze_deps({ repoPath, filePath, direction: "imported_by" })`
+4. `shadow_analyze_deps({ repoPath, filePath, direction: "imports" })`
+5. `shadow_analyze_flow({ repoPath, filePath, symbolName? })`
+
+## Add precision
+
+- `shadow_analyze_explain_diff({ repoPath, baseCommit?, headCommit?, staged? })` for a semantic read of an actual diff.
+- `shadow_analyze_type_graph({ repoPath, symbolName, filePath?, direction?, relationship? })` when the change is type-heavy.
+- `shadow_analyze_debt({ repoPath, mode: "circular-deps" })` for cycle risk.
+- `shadow_recon_topography({ repoPath })` for layer-crossing risk.
+- `shadow_workspace_fuse({ repoPaths, name? })` before cross-repo analysis.
+- `shadow_analyze_mesh({ repoPath, topic, includeCrossRepo: true })` when the affected boundary is a known route or event.
+
+## Closeout
+
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, symbolName?, filePath? })`
+- `shadow_ops_handoff({ repoPath, missionId?, kind: "impact_map", findings, risks?, gaps? })`
+
+## Rules
+
+- Keep `depth: 3` by default; only widen for foundational primitives.
+- `shadow_analyze_mesh` requires a concrete `topic`.

package/dist/skills/shadow_understand/SKILL.md

@@ -3,55 +3,40 @@ name: understand
 description: Find the high-signal path to understanding complex logic through intent retrieval, topological placement, relational analysis, and mechanics inspection. Use when understanding architecture, analyzing complex code, tracing logic flow, or when the user asks about how something works, architectural patterns, or code comprehension.
 ---
 
-# Architectural Understanding
-
-Find the high-signal path to understanding complex logic.
-
-## Workflow
-
-1. **Session Context (The Fast Lane)**: `shadow_ops_context` (repoPath) — **ONE CALL** returns hologram + chronicle(5) + briefing (relevance-ranked candidates).
-   - Skip to step 3 if you have what you need from context alone.
-2. **Optional Expanded Context** (only if shadow_ops_context wasn't enough):
-   - `shadow_recon_topography` (repoPath) — Detailed layer breakdown beyond hologram summary.
-   - `shadow_recon_tree` (subPath: "src/services", maxDepth: 2, repoPath) — Visual file hierarchy.
-   - `shadow_ops_briefing` (scope: "mission", missionId, altitude: "ground") — Full mission detail with raw logs, working set, collisions.
-3. **Relational Analysis (The Who)**:
-   - `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    |
-| **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._
-
-## Intelligence Options
-
-- **`shadow_search_path` with `ranked: true`**: Results sorted by gravity (high-import files first) with layer classification (Entry/Logic/Data). Use when you need to find the most architecturally important files matching a pattern.
-- **`shadow_search_concept` with `compact: true`**: Omits code snippets for ~60% token savings. Use for broad exploration before deep dives.
-- **Briefing altitude levels**: Use `orbit` for quick status, `atmosphere` for strategy + crystals, `ground` for raw logs + collisions.
-- **`shadow_ops_crystallize`**: If a mission has excessive raw logs, crystallize them first for leaner briefings.
+# Understand
+
+Use this skill to build the shortest reliable path from "what is this?" to "I can explain or change it."
+
+## Start broad
+
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. Expand only as needed:
+   - `shadow_recon_tree({ repoPath, subPath?, maxDepth? })`
+   - `shadow_recon_topography({ repoPath })`
+   - `shadow_ops_briefing({ repoPath, scope: "mission", missionId, altitude: "ground" })`
+
+## Relational analysis
+
+- `shadow_search_concept({ repoPath, query, compact: true })`
+- `shadow_search_symbol({ repoPath, query, matchMode? })`
+- `shadow_analyze_impact({ repoPath, symbolName, filePath?, depth: 3 })`
+- `shadow_analyze_deps({ repoPath, filePath, direction: "imported_by" })`
+- `shadow_analyze_type_graph({ repoPath, symbolName, filePath?, direction?, relationship? })`
+- `shadow_analyze_mesh({ repoPath, topic, type? })` when you have a concrete route or event fragment
+
+## Mechanics
+
+- `shadow_inspect_file({ repoPath, filePath, detailLevel: "signatures" })`
+- `shadow_inspect_symbol({ repoPath, symbolName, filePath?, context: "definition" | "full" })`
+- `shadow_analyze_flow({ repoPath, filePath, symbolName? })`
+- `shadow_analyze_explain_diff({ repoPath, baseCommit?, headCommit?, staged? })`
+
+## Closeout
+
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, symbolName?, filePath? })`
+
+## Rules
+
+- Start broad and narrow down; do not jump straight to full-symbol inspection unless you already know the target.
+- `shadow_analyze_type_graph` requires `symbolName`.
+- `shadow_analyze_mesh` requires `topic`.

package/dist/skills/shadow_workspace/SKILL.md

@@ -3,28 +3,28 @@ name: workspace
 description: Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine. Use when working with multiple repositories, federated search across repos, linking missions across repos, or when the user asks about workspace management, multi-repo workflows, or cross-repository dependencies.
 ---
 
-# Workspace Orchestration
+# Workspace
 
 Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine.
 
-## 🚀 Workflow
+## Core calls
 
-1. **List Workspaces**: `shadow_workspace_list` (repoPath, repoPaths).
-2. **Federated Search**: `shadow_workspace_fuse` (repoPath, repoPaths).
-3. **Link Missions**: `shadow_workspace_link` (parentRepoPath, parentMissionId, childRepoPath, childMissionId, relationship, repoPath).
-4. **Verify Graph**: `shadow_ops_graph` (missionId, depth, repoPath).
+- List active work across repos:
+  - `shadow_workspace_list({ repoPaths, status? })`
+- Build a fused search index:
+  - `shadow_workspace_fuse({ repoPaths, name? })`
+- Link missions across repos:
+  - `shadow_workspace_link({ parentRepoPath, parentMissionId, childRepoPath, childMissionId, relationship })`
+- Visualize a repo's mission graph:
+  - `shadow_ops_graph({ repoPath, missionId?, depth?, format? })`
 
-## 🛠 Precise Tooling
+## After fusion
 
-| Action        | Atomic Tool             | Example                                          |
-| :------------ | :---------------------- | :----------------------------------------------- |
-| **List**      | `shadow_workspace_list` | `{ repoPath, repoPaths: [...] }`                 |
-| **Fuse**      | `shadow_workspace_fuse` | `{ repoPath, repoPaths: [...] }`                 |
-| **Link**      | `shadow_workspace_link` | `{ parentMissionId: 1, childMissionId: 2, ... }` |
-| **Visualize** | `shadow_ops_graph`      | `{ missionId: 1, depth: 3, repoPath }`           |
+- Use the normal `shadow_search_*` and `shadow_analyze_*` tools inside the participating repos.
+- For routes and events that cross repo boundaries, use:
+  - `shadow_analyze_mesh({ repoPath, topic, includeCrossRepo: true })`
 
-_Note: Use fused search after `shadow_workspace_fuse` to look up concepts across all repositories simultaneously._
+## Rules
 
-## 🛠 Tooling Strategy
-
-Use **`shadow_workspace_fuse`** early in multi-repo sessions to unlock "X-Ray" vision across boundaries.
+- `shadow_workspace_list` and `shadow_workspace_fuse` take `repoPaths`, not `repoPath`.
+- `shadow_workspace_link` uses explicit parent and child repo paths; there is no shared `repoPath` parameter.