@precisionutilityguild/liquid-shadow 1.0.4 → 1.0.5

package/dist/skills/shadow_synthesize/SKILL.md

@@ -0,0 +1,47 @@
+---
+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
+
+Distill mission logs into an Architectural Decision Record (ADR) and persist it to the Shadow Engine.
+
+> **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).
+
+## Workflow
+
+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.
+
+## 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.               |
+
+_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."

package/dist/skills/shadow_trace_impact/SKILL.md

@@ -0,0 +1,55 @@
+---
+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

package/dist/skills/shadow_understand/SKILL.md

@@ -0,0 +1,51 @@
+---
+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.
+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.
+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 |
+
+_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.

package/dist/skills/shadow_workspace/SKILL.md

@@ -0,0 +1,30 @@
+---
+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
+
+Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine.
+
+## 🚀 Workflow
+
+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).
+
+## 🛠 Precise Tooling
+
+| 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 }`           |
+
+_Note: Use fused search after `shadow_workspace_fuse` to look up concepts across all repositories simultaneously._
+
+## 🛠 Tooling Strategy
+
+Use **`shadow_workspace_fuse`** early in multi-repo sessions to unlock "X-Ray" vision across boundaries.

package/dist/web-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.4",
+  "version": "1.0.5",
   "toolsByPrefix": {
     "RECON": {
       "subcommands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@precisionutilityguild/liquid-shadow",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Tactical Repository Intelligence Operative - Liquid Shadow Ecosystem",
   "homepage": "https://liquidshadow.pugcorp.online/",
   "repository": {
@@ -12,7 +12,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "type": "module",
   "main": "dist/index.js",

package/skills/shadow_audit/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: audit
+description: Perform codebase health audits to identify dead code, circular dependencies, and technical debt. Use when auditing code quality, finding unused code, detecting circular dependencies, or when the user asks about codebase health, technical debt, or code cleanup.
+---
+
+# Codebase Audit
+
+Comprehensive health audit using Shadow analyze toolkit.
+
+## 🚀 Workflow
+
+1. **Session Context**: `shadow_ops_context` (repoPath) — **ONE CALL** for hologram + chronicle + briefing. Get architecture baseline.
+2. **Dead Code Detection**: `shadow_analyze_debt` (mode: "dead-code", limit: 100, includeTests: false, repoPath) — Unused exports.
+3. **Circular Dependencies**: `shadow_analyze_debt` (mode: "circular-deps", limit: 20, repoPath) — Import cycles.
+4. **Layer Integrity** (optional): `shadow_recon_topography` (repoPath) — Detailed layer analysis if hologram summary isn't enough.
+5. **Log Findings**: `shadow_ops_log` (missionId, type: "discovery", content, repoPath).
+6. **Create Cleanup Mission** (optional): `shadow_ops_plan` (name: "Codebase Cleanup", templateId: "refactoring", templateVars, repoPath).
+
+## 🛠 Precise Tooling
+
+| Audit Target         | Atomic Tool                                                                            |
+| :------------------- | :------------------------------------------------------------------------------------- |
+| **Session Start** 🚀 | `shadow_ops_context` (repoPath) — **START HERE** for baseline                          |
+| **Architecture**     | `shadow_recon_hologram` (repoPath) — if you need standalone                            |
+| **Dead Code**        | `shadow_analyze_debt` (mode: "dead-code", limit: 100, **confidenceThreshold: "high"**) |
+| **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     |
+
+## 💡 Intelligence Options
+
+- **`shadow_analyze_debt` confidence levels**: Use `confidenceThreshold: "high"` for likely dead code, `"medium"` for possibly intentional (test fixtures, etc.), `"all"` for everything.
+- **`shadow_analyze_debt` exclusion filters**: Use `excludePatterns`, `includeMigrations: false`, `includeFixtures: false` to reduce noise.
+- **`shadow_search_config` with `showUsage: true`**: Cross-references config vars with code to show usage counts and identify orphaned vars (defined but never used).
+
+## 🔍 Health Criteria
+
+- **Critical Issues**: Circular deps in core logic, >50 dead exports, orphaned env vars with secrets
+- **Warning Signs**: Layer violations (Test → Logic), >20 dead exports, >10 orphaned configs
+- **Good Health**: Clean layers, <10 dead exports, no circular deps, all configs in use

package/skills/shadow_chronicle/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: chronicle
+description: Retrieve and analyze the repository's narrative archive as recorded in Git-native memory. Use when you need to understand historical decisions, catch up on repository progress, review recently completed missions, or when the user asks for a project history, changelog, or chronological overview of architectural changes.
+---
+
+# Repository Chronicle
+
+Retrieve narrative archive from Git-native memory.
+
+## 🚀 Workflow
+
+1. **Recent History**: `shadow_ops_chronicle` (limit: 10, format: "markdown", repoPath) — Last 10 entries.
+2. **Time-Filtered**:
+   - `shadow_ops_chronicle` (since: <unix>, limit: 20, repoPath)
+   - `shadow_ops_chronicle` (until: <unix>, limit: 20, repoPath)
+3. **Structured Data**: `shadow_ops_chronicle` (format: "json", limit: 50, repoPath) — For processing.
+4. **Paginated**: `shadow_ops_chronicle` (limit: 10, offset: 10, repoPath) — Second page.
+
+## 🛠 Precise Tooling
+
+| Chronicle Query       | Atomic Tool                                                       |
+| :-------------------- | :---------------------------------------------------------------- |
+| **Recent (Markdown)** | `shadow_ops_chronicle` (limit: 10, format: "markdown")            |
+| **Time Range**        | `shadow_ops_chronicle` (since: <unix>, until: <unix>) |
+| **JSON Data**         | `shadow_ops_chronicle` (format: "json", limit: 50)                |
+| **Pagination**        | `shadow_ops_chronicle` (limit: 10, offset: 10)                    |
+
+## Output Formats
+
+- **`format: "markdown"`** (default): Human-readable narrative feed with missions grouped as Strategic Initiatives and Standalone Episodes
+- **`format: "json"`**: Structured data for programmatic analysis (includes missionId, steps, timestamps, ADRs)
+
+## Use Cases
+
+- **Onboarding**: Read last 10 entries to catch up
+- **Release Notes**: Get completed missions since last release
+- **ADR Review**: Extract all architectural decisions
+- **Progress Reports**: Show what's been done this week
+
+**Note:** Chronicle reads from Git Notes, so it's persistent across branches and clones.

package/skills/shadow_continue/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: continue
+description: Get briefing, pick one mission from next_work_candidates, then work that mission to completion with all remaining steps in one run. Use when continuing work on missions, executing mission steps, or when the user asks to continue work, finish a mission, or proceed with development tasks.
+---
+
+**In one sentence:** Get briefing (+ optional trace), pick **one mission** from **next_work_candidates** (ranked by relevance), then work that mission to completion — all remaining steps in one run. Update and log as you go. No status reports; when you're done with that mission, it's done.
+
+---
+
+## 1. Context
+
+- **Option A (one shot):** `shadow_ops_context` (repoPath) → returns hologram + chronicle(5) + **briefing** (counts, **next_work_candidates** ranked by relevance). Use when you want architecture + history + backlog in one call at the start of /continue.
+- **Option B:** `shadow_ops_briefing` (scope: "project", repoPath) → **next_work_candidates** (relevance-ranked), hierarchy, analytics.
+  - Use **altitude** to control output density: `orbit` (~200 tokens, counts + candidates only), `atmosphere` (default, strategy + crystals), `ground` (raw logs + working set + collisions).
+- `shadow_sync_trace` (repoPath) only if you care about external changes. Otherwise skip.
+
+## 2. Pick one mission
+
+- **`next_work_candidates`** are ranked by the MissionRelevanceScorer (recency × 0.4 + activity × 0.3 + status × 0.2 + blockers × 0.1). Higher score = more relevant.
+- Choose the top-ranked candidate. Prefer in-progress over planned. Parent-only missions (umbrellas) are already filtered out.
+
+## 3. Work the whole mission
+
+- For that mission, run through **all remaining steps** (not just one):
+  - **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).
+- **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.
+
+## 🛠 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                 |
+
+_Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
+
+## 4. Don't
+
+- Don't do one step and stop — /continue is "finish a mission," not "do one step."
+- Don't call `shadow_ops_synthesize` after completing — it's automatic on `status: "completed"`.
+- Don't long status reports. Don't ask "what should I work on?" unless a real tie. Don't auto-commit.
+
+---
+
+**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_*`.

package/skills/shadow_crystallize/SKILL.md

@@ -0,0 +1,41 @@
+---
+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
+
+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.
+
+## When to Crystallize
+
+- 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.
+
+## Workflow
+
+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
+
+## 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.

package/skills/shadow_mission/SKILL.md

@@ -0,0 +1,50 @@
+---
+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.
+---
+
+# Mission Strategy & Setup
+
+Define the objective, strategy, and success criteria for a new mission. This workflow is for **Strategic Alignment and Planning**.
+
+> **IMPORTANT**: This workflow stops at the "Ready to Execute" state. For implementation and automated execution, use **/continue**.
+
+## Workflow
+
+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.
+
+## 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.                        |
+
+_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._
+
+## 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`.

package/skills/shadow_onboard/SKILL.md

@@ -0,0 +1,35 @@
+---
+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.
+---
+
+# 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.
+6.  **Hooks Activation**: `shadow_env_hooks` (action: "install", repoPath).
+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")                           |
+
+_Note: Always use absolute paths for `repoPath`. Call `shadow_recon_hologram` immediately after init for instant architectural context._

package/skills/shadow_research/SKILL.md

@@ -0,0 +1,34 @@
+---
+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.
+---
+
+# External Research
+
+High-signal research for external dependencies.
+
+## 🚀 Workflow
+
+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).
+
+## 🛠 Precise Tooling
+
+| 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)                                 |
+
+## 💡 Intelligence Options
+
+- **`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._

package/skills/shadow_sync/SKILL.md

@@ -0,0 +1,18 @@
+---
+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
+
+**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.
+
+## When to run sync manually
+
+| 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)                                    |
+
+**Note:** `trace` does index + ghost analysis + NanoRepair + lifecycle + mission re-hydration. Hooks run it on commit/checkout/merge.

package/skills/shadow_synthesize/SKILL.md

@@ -0,0 +1,47 @@
+---
+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
+
+Distill mission logs into an Architectural Decision Record (ADR) and persist it to the Shadow Engine.
+
+> **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).
+
+## Workflow
+
+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.
+
+## 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.               |
+
+_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."