@a13xu/lucid 1.16.0 → 1.16.1

package/README.md

@@ -4,11 +4,11 @@
 [![npm downloads](https://img.shields.io/npm/dm/@a13xu/lucid)](https://www.npmjs.com/package/@a13xu/lucid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **MCP server for Claude Code** — persistent memory, smart code indexing, and code quality validation. Works out of the box with zero configuration.
+> **MCP server for Claude Code** — persistent memory, smart code indexing, model selection, and code quality validation. Works out of the box with zero configuration.
 
 Token-efficient memory, code indexing, and validation for Claude Code agents — backed by **SQLite + FTS5**.
 
-Stores a persistent knowledge graph (entities, relations, observations), indexes source files as compressed binary with change detection, retrieves minimal relevant context via TF-IDF or Qdrant, and validates code for LLM drift patterns. Supports TypeScript, JavaScript, Python, **Vue, Nuxt**.
+Stores a persistent knowledge graph (entities, relations, observations), indexes source files as compressed binary with change detection, retrieves minimal relevant context via TF-IDF or Qdrant, and validates code for LLM drift patterns. Supports TypeScript, JavaScript, Python, **Vue, Nuxt**. Optional **LLMLingua-2 semantic compression** reduces context tokens by 30–70% while preserving meaning.
 
 ## Install
 
@@ -45,15 +45,16 @@ Default DB path: `~/.claude/memory.db`
 ## Quick start
 
 ```
-1. "Index this project" → init_project()        → scans CLAUDE.md, package.json, src/**
-2. Write code          → sync_file(path)         → compressed + hashed + diff stored
-3. "What's relevant?"  → get_context("auth flow") → TF-IDF ranked skeletons, ~500 tokens
-4. "What changed?"     → get_recent(hours=2)      → line diffs of recent edits
-5. "Where is X used?"  → grep_code("X")           → matching lines only, ~30 tokens
-6. "What do we know?"  → recall("query")          → knowledge graph search
+1. "Index this project" → init_project()               → scans CLAUDE.md, package.json, src/**
+2. Write code           → sync_file(path)               → compressed + hashed + diff stored
+3. "What's relevant?"  → smart_context("auth flow")    → recall + code in one call, adaptive budget
+4. "What model?"       → suggest_model("refactor auth") → haiku (lookup) or sonnet (reasoning)
+5. "What changed?"     → get_recent(hours=2)            → line diffs of recent edits
+6. "Where is X used?"  → grep_code("X")                → matching lines only, ~30 tokens
+7. "What do we know?"  → recall("query")               → knowledge graph search
 ```
 
-## Tools (30)
+## Tools (37)
 
 ### Memory
 | Tool | Description |
@@ -76,8 +77,11 @@ Default DB path: `~/.claude/memory.db`
 ### Token optimization
 | Tool | Description |
 |---|---|
-| `get_context` | **Smart context retrieval.** Ranks all indexed files by TF-IDF relevance (or Qdrant vector search if `QDRANT_URL` is set), applies recency boost, returns skeletons (imports + signatures only) for large files. Respects `maxContextTokens` budget. |
+| `smart_context` | **Recommended entry point.** Combines `recall()` (knowledge graph) + `get_context()` (code files) in one call. Adaptive token budget: `simple`=2000, `moderate`=6000, `complex`=12000. Logs an experience for `reward()`/`penalize()` feedback. |
+| `suggest_model` | Classify task complexity → recommend Claude model. Returns `{ model, model_id, reasoning, context_budget }`. Simple lookups → Haiku; reasoning/code → Sonnet. Call at the start of any workflow. |
+| `get_context` | **Classic code context.** Ranks indexed files by TF-IDF (or Qdrant), applies recency boost, returns skeletons for large files. Respects `maxContextTokens` budget. |
 | `get_recent` | Return files modified in the last N hours with line-level diffs. |
+| `compress_text` | Compress any text using LLMLingua-2 semantic compression. Returns compressed text + stats (ratio, tokens saved). Model downloads ~700MB on first use. |
 
 ### Logic Guardian
 | Tool | Description |
@@ -86,11 +90,19 @@ Default DB path: `~/.claude/memory.db`
 | `check_drift` | Analyze a code snippet inline without saving to disk. |
 | `get_checklist` | Return the full 5-pass validation protocol (Logic Trace, Contract Verification, Stupid Mistakes, Integration Sanity, Explain It). |
 
+### Plans
+| Tool | Description |
+|---|---|
+| `plan_create` | Create a development plan with title, description, and tasks. Returns plan ID. |
+| `plan_list` | List all plans with status summary (total/done/in-progress tasks). |
+| `plan_get` | Get full plan details including all tasks and their status. |
+| `plan_update_task` | Update a task's status (`todo` → `in_progress` → `done`) and optionally add notes. |
+
 ### Reward system
 | Tool | Description |
 |---|---|
-| `reward` | Signal that the last `get_context()` result was helpful (+1). Rewarded files rank higher in future similar queries. |
-| `penalize` | Signal that the last `get_context()` result was unhelpful (-1). Penalized files rank lower in future queries. |
+| `reward` | Signal that the last `smart_context()`/`get_context()` result was helpful (+1). Rewarded files rank higher in future similar queries. |
+| `penalize` | Signal that the last result was unhelpful (-1). Penalized files rank lower. Accepts optional `note` to log what was missing. |
 | `show_rewards` | Show top rewarded experiences and most rewarded files. Rewards decay exponentially (half-life ~14 days). |
 
 ### Code Quality Guard
@@ -115,7 +127,31 @@ Default DB path: `~/.claude/memory.db`
 
 ## Token optimization in depth
 
-### How `get_context` works
+### How `smart_context` works (recommended)
+
+```
+query: "auth middleware"
+         ↓
+  1. recall(query)  — knowledge graph search (entities, relations)
+         ↓
+  2. TF-IDF score all indexed files against query
+     (or Qdrant top-k if QDRANT_URL is set)
+         ↓
+  3. Boost recently-modified files (+0.3 score)
+     Boost rewarded files (+0.25 score, decayed)
+         ↓
+  4. For each file within token budget:
+       file < maxTokensPerFile  → return full source
+       file > maxTokensPerFile  → return skeleton only
+                                   (imports + signatures + TODOs)
+                                   + relevant fragments around query terms
+         ↓
+  5. Optional: LLMLingua-2 compression (if enabled in config)
+         ↓
+  output: merged knowledge + code — budget: 2k/6k/12k by task_type
+```
+
+### How `get_context` works (classic)
 
 ```
 query: "auth middleware"
@@ -183,6 +219,32 @@ Or in `.mcp.json`:
 
 Falls back to TF-IDF automatically if Qdrant is unreachable.
 
+### Semantic compression (optional)
+
+LLMLingua-2 (`microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank`) identifies and drops semantically unimportant tokens before returning context to Claude — and before generating Qdrant embeddings.
+
+Enable in `lucid.config.json`:
+
+```json
+{
+  "semanticCompression": {
+    "enabled": true,
+    "ratio": 0.5,
+    "minLength": 300,
+    "applyToEmbeddings": true
+  }
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `false` | Opt-in — model downloads ~700MB on first use |
+| `ratio` | `0.5` | Fraction of tokens to keep (0.3 = keep 30%) |
+| `minLength` | `300` | Skip compression for texts shorter than this |
+| `applyToEmbeddings` | `true` | Also compress chunk text before Qdrant embedding |
+
+Model is cached in `~/.lucid/models/` after first download. Falls back to uncompressed text on any error — safe to enable unconditionally.
+
 ### Configuration (`lucid.config.json`)
 
 Create in your project root to customize behavior:
@@ -191,9 +253,13 @@ Create in your project root to customize behavior:
 {
   "whitelistDirs": ["src", "backend", "api"],
   "blacklistDirs": ["migrations", "fixtures"],
-  "maxTokensPerFile": 400,
-  "maxContextTokens": 6000,
-  "recentWindowHours": 12
+  "maxTokensPerFile": 600,
+  "maxContextTokens": 8000,
+  "recentWindowHours": 48,
+  "semanticCompression": {
+    "enabled": false,
+    "ratio": 0.5
+  }
 }
 ```
 
@@ -201,9 +267,9 @@ Create in your project root to customize behavior:
 |---|---|---|
 | `whitelistDirs` | — | Only index/return files from these dirs |
 | `blacklistDirs` | — | Extra dirs to skip (merged with built-in skips) |
-| `maxTokensPerFile` | `400` | Files above this get skeleton treatment |
-| `maxContextTokens` | `4000` | Total token budget for `get_context` |
-| `recentWindowHours` | `24` | "Recently touched" threshold |
+| `maxTokensPerFile` | `600` | Files above this get skeleton treatment |
+| `maxContextTokens` | `8000` | Total token budget for `get_context` |
+| `recentWindowHours` | `48` | "Recently touched" threshold |
 
 ## Why no vectors by default?
 
@@ -237,6 +303,63 @@ TF-IDF is fast, deterministic, and requires zero external services. Qdrant is av
 ## Relation types
 `uses` · `depends_on` · `created_by` · `part_of` · `replaced_by` · `conflicts_with` · `tested_by`
 
+## HTTP daemon & auto-sync
+
+Lucid can run as a background HTTP daemon (port 7821) for auto-syncing files without Claude's cooperation.
+
+```bash
+# Start daemon (watches for sync requests, serves REST API)
+lucid watch
+
+# With HTTP server
+lucid watch --http
+
+# Check status
+lucid status
+
+# Stop
+lucid stop
+```
+
+### REST API (when `--http` is active)
+
+| Endpoint | Description |
+|---|---|
+| `POST /sync` `{ path }` | Sync a single file |
+| `POST /sync-project` `{ directory? }` | Sync entire project |
+| `GET /context?q=<query>` | Get context via HTTP |
+| `POST /validate` `{ path }` | Validate file for drift |
+| `GET /health` | Daemon health check |
+
+### Auto-sync hook (`lucid-sync`)
+
+`init_project` installs a Claude Code `PostToolUse` hook that calls `lucid-sync` after every file write/edit. The sync binary:
+
+1. Tries HTTP sync (500ms timeout, if daemon running)
+2. Falls back to direct SQLite sync (no daemon needed)
+
+This keeps the knowledge graph current automatically — without relying on Claude remembering to call `sync_file`.
+
+## Skills enforcement
+
+Lucid ships **enforcement skills** that install globally into `~/.claude/skills/` and activate in every project:
+
+| Skill | Purpose |
+|---|---|
+| `lucid-start` | Session start — `get_recent` + `smart_context` before any coding |
+| `lucid-context` | Pre-task context loading — `suggest_model` + `smart_context` |
+| `lucid-audit` | Pre-done gate — validate + check drift before marking complete |
+| `lucid-plan` | Planning workflow |
+| `lucid-sync` | Post-edit sync reminder |
+| `lucid-webdev` | Web dev workflow with context |
+
+All skills use `<HARD-GATE>` blocks that prevent proceeding until required tools are called.
+
+Install globally:
+```bash
+init_project()   # installs skills to ~/.claude/skills/ automatically
+```
+
 ## Debugging
 
 ```bash
@@ -244,7 +367,7 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},
   | npx @a13xu/lucid
 ```
 
-In Claude Code: run `/mcp` — you should see `lucid` with 20 tools.
+In Claude Code: run `/mcp` — you should see `lucid` with 37 tools.
 
 ## Contributing
 
@@ -260,8 +383,11 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/a13xu/l
 - **Runtime:** Node.js 18+, TypeScript, ES modules
 - **MCP SDK:** `@modelcontextprotocol/sdk`
 - **Database:** `better-sqlite3` (synchronous, WAL mode)
-- **Compression:** Node.js built-in `zlib` (deflate level 9)
+- **Compression:** Node.js built-in `zlib` (deflate level 9) + LLMLingua-2 semantic compression (optional)
 - **Hashing:** SHA-256 via `crypto` (change detection)
 - **Ranking:** TF-IDF (built-in) or Qdrant (optional, via REST)
+- **Semantic compression:** `@huggingface/transformers` (ONNX Runtime, q8 quantization)
+- **HTTP daemon:** Express 5 on port 7821 (optional)
+- **File watcher:** `chokidar`
 - **Validation:** `zod`
 - **Transport:** stdio

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a13xu/lucid",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
   "type": "module",
   "bin": {

package/skills/lucid-audit/SKILL.md

@@ -1,73 +1,73 @@
----
-name: lucid-audit
-description: MANDATORY before marking any task done — runs Logic Guardian + Code Quality checks. HARD-GATE blocks completion without validation.
-argument-hint: "[file path or 'all changed files']"
----
-
-<HARD-GATE>
-You are about to say "done", "fixed", "complete", or "implemented".
-STOP. You have NOT verified the code yet.
-
-Do NOT mark any task as done, do NOT commit, do NOT say the work is complete
-until you have run BOTH validators below and fixed all 🔴 CRITICAL issues.
-
-"It looks correct" is not verification. Run the tools.
-</HARD-GATE>
-
-## When to invoke
-
-**INVOKE when:** about to say done/fixed/complete/implemented, before committing, before creating a PR
-**DO NOT INVOKE for:** read-only tasks, pure research, config changes with no logic
-
-## Steps
-
-```dot
-digraph lucid_audit {
-    "About to say done?" -> "validate_file(path)";
-    "validate_file(path)" -> "Critical issues?";
-    "Critical issues?" -> "Fix issues" [label="yes 🔴"];
-    "Fix issues" -> "validate_file(path)";
-    "Critical issues?" -> "check_code_quality(path)" [label="no ✓"];
-    "check_code_quality(path)" -> "HIGH issues?";
-    "HIGH issues?" -> "Fix if safe" [label="yes 🟠"];
-    "Fix if safe" -> "Mark done ✓";
-    "HIGH issues?" -> "Mark done ✓" [label="no ✓"];
-}
-```
-
-### 0. Get model recommendation
-```
-suggest_model(task_description="<paste the file path or description of what was written>")
-```
-Say: **"Using [model] — [reasoning]"** then proceed.
-
-### 1. Validate logic correctness
-```
-validate_file(path="<file you wrote or modified>")
-```
-Fix every 🔴 CRITICAL issue. Re-run until clean.
-
-### 2. Validate code quality
-```
-check_code_quality(path="<same file>")
-```
-Fix 🔴 HIGH severity issues. Address 🟠 MEDIUM where practical.
-
-### 3. For complex logic — get the full checklist
-```
-get_checklist()
-```
-Run all 5 mental passes before marking done.
-
-### 4. Pre-write validation (before writing to disk)
-```
-check_drift(code="<your code snippet>", language="typescript")
-```
-
-## Severity guide
-
-| Icon | Level | Action |
-|---|---|---|
-| 🔴 | Critical/High | Fix immediately — do not proceed |
-| 🟠 | Medium | Fix if the refactor is safe |
-| 🔵 | Low/Info | Note for future cleanup |
+---
+name: lucid-audit
+description: MANDATORY before marking any task done — runs Logic Guardian + Code Quality checks. HARD-GATE blocks completion without validation.
+argument-hint: "[file path or 'all changed files']"
+---
+
+<HARD-GATE>
+You are about to say "done", "fixed", "complete", or "implemented".
+STOP. You have NOT verified the code yet.
+
+Do NOT mark any task as done, do NOT commit, do NOT say the work is complete
+until you have run BOTH validators below and fixed all 🔴 CRITICAL issues.
+
+"It looks correct" is not verification. Run the tools.
+</HARD-GATE>
+
+## When to invoke
+
+**INVOKE when:** about to say done/fixed/complete/implemented, before committing, before creating a PR
+**DO NOT INVOKE for:** read-only tasks, pure research, config changes with no logic
+
+## Steps
+
+```dot
+digraph lucid_audit {
+    "About to say done?" -> "validate_file(path)";
+    "validate_file(path)" -> "Critical issues?";
+    "Critical issues?" -> "Fix issues" [label="yes 🔴"];
+    "Fix issues" -> "validate_file(path)";
+    "Critical issues?" -> "check_code_quality(path)" [label="no ✓"];
+    "check_code_quality(path)" -> "HIGH issues?";
+    "HIGH issues?" -> "Fix if safe" [label="yes 🟠"];
+    "Fix if safe" -> "Mark done ✓";
+    "HIGH issues?" -> "Mark done ✓" [label="no ✓"];
+}
+```
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the file path or description of what was written>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
+### 1. Validate logic correctness
+```
+validate_file(path="<file you wrote or modified>")
+```
+Fix every 🔴 CRITICAL issue. Re-run until clean.
+
+### 2. Validate code quality
+```
+check_code_quality(path="<same file>")
+```
+Fix 🔴 HIGH severity issues. Address 🟠 MEDIUM where practical.
+
+### 3. For complex logic — get the full checklist
+```
+get_checklist()
+```
+Run all 5 mental passes before marking done.
+
+### 4. Pre-write validation (before writing to disk)
+```
+check_drift(code="<your code snippet>", language="typescript")
+```
+
+## Severity guide
+
+| Icon | Level | Action |
+|---|---|---|
+| 🔴 | Critical/High | Fix immediately — do not proceed |
+| 🟠 | Medium | Fix if the refactor is safe |
+| 🔵 | Low/Info | Note for future cleanup |

package/skills/lucid-context/SKILL.md

@@ -1,69 +1,69 @@
----
-name: lucid-context
-description: Use BEFORE starting any coding task — retrieves relevant context via smart_context (code + knowledge graph). HARD-GATE: do not read files manually before calling smart_context.
-argument-hint: "[what you are working on]"
----
-
-<HARD-GATE>
-Do NOT open any source file, read any code, or start implementation
-until you have called smart_context and reviewed the result.
-Reading files manually when Lucid is available wastes tokens and misses context.
-</HARD-GATE>
-
-## When to invoke this skill
-
-**INVOKE when:** about to work on a feature, fix a bug, understand a module, or any coding task
-**DO NOT INVOKE for:** pure conversation, reading docs, non-code questions
-
-## Steps
-
-```dot
-digraph lucid_context {
-    "Describe task" -> "suggest_model";
-    "suggest_model" -> "call smart_context";
-    "call smart_context" -> "Result relevant?";
-    "Result relevant?" -> "call reward()" [label="yes"];
-    "Result relevant?" -> "call penalize()" [label="no — note what was missing"];
-    "reward()" -> "Start coding";
-    "penalize()" -> "Start coding";
-}
-```
-
-### 0. Get model recommendation
-```
-suggest_model(task_description="<concise description of what you are working on>")
-```
-Say: **"Using [model] — [reasoning]"**
-
-### 1. Call smart_context
-```
-smart_context(query="<concise description of what you are working on>", task_type="moderate")
-```
-
-Use `dirs` to narrow scope and `task_type` to adjust budget:
-```
-smart_context(query="...", dirs=["src/api"], task_type="simple")
-```
-
-### 2. Review results and give feedback
-
-| Result quality | Action |
-|---|---|
-| Included the files you needed | `reward()` |
-| Missed important files you had to find manually | `penalize(note="missed: src/path/file.ts")` |
-| Partially useful | no action |
-
-### 3. Supplement if needed
-
-```
-grep_code(pattern="functionName")          # locate specific usages
-get_recent(hours=2)                        # after git pull — see what changed
-recall(query="<topic>")                    # search accumulated knowledge
-```
-
-### 4. After finishing — sync
-
-After every Write/Edit:
-```
-sync_file(path="<modified file>")
-```
+---
+name: lucid-context
+description: Use BEFORE starting any coding task — retrieves relevant context via smart_context (code + knowledge graph). HARD-GATE: do not read files manually before calling smart_context.
+argument-hint: "[what you are working on]"
+---
+
+<HARD-GATE>
+Do NOT open any source file, read any code, or start implementation
+until you have called smart_context and reviewed the result.
+Reading files manually when Lucid is available wastes tokens and misses context.
+</HARD-GATE>
+
+## When to invoke this skill
+
+**INVOKE when:** about to work on a feature, fix a bug, understand a module, or any coding task
+**DO NOT INVOKE for:** pure conversation, reading docs, non-code questions
+
+## Steps
+
+```dot
+digraph lucid_context {
+    "Describe task" -> "suggest_model";
+    "suggest_model" -> "call smart_context";
+    "call smart_context" -> "Result relevant?";
+    "Result relevant?" -> "call reward()" [label="yes"];
+    "Result relevant?" -> "call penalize()" [label="no — note what was missing"];
+    "reward()" -> "Start coding";
+    "penalize()" -> "Start coding";
+}
+```
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<concise description of what you are working on>")
+```
+Say: **"Using [model] — [reasoning]"**
+
+### 1. Call smart_context
+```
+smart_context(query="<concise description of what you are working on>", task_type="moderate")
+```
+
+Use `dirs` to narrow scope and `task_type` to adjust budget:
+```
+smart_context(query="...", dirs=["src/api"], task_type="simple")
+```
+
+### 2. Review results and give feedback
+
+| Result quality | Action |
+|---|---|
+| Included the files you needed | `reward()` |
+| Missed important files you had to find manually | `penalize(note="missed: src/path/file.ts")` |
+| Partially useful | no action |
+
+### 3. Supplement if needed
+
+```
+grep_code(pattern="functionName")          # locate specific usages
+get_recent(hours=2)                        # after git pull — see what changed
+recall(query="<topic>")                    # search accumulated knowledge
+```
+
+### 4. After finishing — sync
+
+After every Write/Edit:
+```
+sync_file(path="<modified file>")
+```

package/skills/lucid-plan/SKILL.md

@@ -1,52 +1,52 @@
----
-name: lucid-plan
-description: MANDATORY before writing code for any non-trivial feature — creates a persisted plan with tasks. HARD-GATE: no coding without a plan.
-argument-hint: "[feature or task description]"
----
-
-<HARD-GATE>
-You are about to write code for a feature or fix.
-STOP. Create a plan first. Plans survive session restarts.
-Do NOT write implementation code until a plan exists and tasks are defined.
-</HARD-GATE>
-
-## When to invoke
-
-**INVOKE when:** implementing a feature, fixing a non-trivial bug, any task with 3+ steps
-**DO NOT INVOKE for:** single-line fixes, config changes, documentation-only tasks
-
-## Steps
-
-### 0. Get model recommendation
-```
-suggest_model(task_description="<paste the user's task description>")
-```
-Say: **"Using [model] — [reasoning]"** then proceed.
-
-### 1. Create the plan
-```
-plan_create(
-  title="<short descriptive title>",
-  description="<what this accomplishes>",
-  user_story="As a <user>, I want <goal>, so that <benefit>.",
-  tasks=[
-    { title: "Task 1", description: "...", test_criteria: "How to verify it's done" },
-    { title: "Task 2", description: "...", test_criteria: "..." },
-  ]
-)
-```
-Returns a `plan_id` and task IDs (format: `planId * 100 + sequence`).
-
-### 2. Mark tasks in progress / done as you work
-```
-plan_update_task(task_id=101, status="in_progress")
-plan_update_task(task_id=101, status="done", note="Decision made: used X instead of Y")
-```
-
-### 3. Resume a session
-```
-plan_list()           # all active plans
-plan_get(plan_id=1)   # full details + task status
-```
-
-## Task statuses: `pending` → `in_progress` → `done` | `blocked`
+---
+name: lucid-plan
+description: MANDATORY before writing code for any non-trivial feature — creates a persisted plan with tasks. HARD-GATE: no coding without a plan.
+argument-hint: "[feature or task description]"
+---
+
+<HARD-GATE>
+You are about to write code for a feature or fix.
+STOP. Create a plan first. Plans survive session restarts.
+Do NOT write implementation code until a plan exists and tasks are defined.
+</HARD-GATE>
+
+## When to invoke
+
+**INVOKE when:** implementing a feature, fixing a non-trivial bug, any task with 3+ steps
+**DO NOT INVOKE for:** single-line fixes, config changes, documentation-only tasks
+
+## Steps
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the user's task description>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
+### 1. Create the plan
+```
+plan_create(
+  title="<short descriptive title>",
+  description="<what this accomplishes>",
+  user_story="As a <user>, I want <goal>, so that <benefit>.",
+  tasks=[
+    { title: "Task 1", description: "...", test_criteria: "How to verify it's done" },
+    { title: "Task 2", description: "...", test_criteria: "..." },
+  ]
+)
+```
+Returns a `plan_id` and task IDs (format: `planId * 100 + sequence`).
+
+### 2. Mark tasks in progress / done as you work
+```
+plan_update_task(task_id=101, status="in_progress")
+plan_update_task(task_id=101, status="done", note="Decision made: used X instead of Y")
+```
+
+### 3. Resume a session
+```
+plan_list()           # all active plans
+plan_get(plan_id=1)   # full details + task status
+```
+
+## Task statuses: `pending` → `in_progress` → `done` | `blocked`

package/skills/lucid-security/SKILL.md

@@ -1,41 +1,41 @@
----
-name: lucid-security
-description: Run before merging any code that handles user input, auth, or external data — security scan + drift check for injection, XSS, and credential exposure.
-argument-hint: "[file path or directory]"
----
-
-<HARD-GATE>
-Before merging code that:
-- Handles user input (forms, query params, file uploads)
-- Implements auth, tokens, sessions, or permissions
-- Calls external APIs or parses external data
-- Manages files or runs shell commands
-
-Run this skill. No exceptions.
-</HARD-GATE>
-
-## Steps
-
-### 0. Get model recommendation
-```
-suggest_model(task_description="<paste the user's task description>")
-```
-Say: **"Using [model] — [reasoning]"** then proceed.
-
-### 1. Security scan
-```
-security_scan(code="<file contents or snippet>", language="typescript", context="backend")
-```
-
-### 2. Drift check for security-sensitive snippets
-```
-check_drift(code="<auth/input-handling code>", language="typescript")
-```
-
-### 3. Fix all CRITICAL issues before merging
-
-| Severity | Action |
-|---|---|
-| 🔴 CRITICAL | Block merge — fix immediately |
-| 🟠 HIGH | Fix before merge |
-| 🔵 MEDIUM/LOW | Track, fix in follow-up |
+---
+name: lucid-security
+description: Run before merging any code that handles user input, auth, or external data — security scan + drift check for injection, XSS, and credential exposure.
+argument-hint: "[file path or directory]"
+---
+
+<HARD-GATE>
+Before merging code that:
+- Handles user input (forms, query params, file uploads)
+- Implements auth, tokens, sessions, or permissions
+- Calls external APIs or parses external data
+- Manages files or runs shell commands
+
+Run this skill. No exceptions.
+</HARD-GATE>
+
+## Steps
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the user's task description>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
+### 1. Security scan
+```
+security_scan(code="<file contents or snippet>", language="typescript", context="backend")
+```
+
+### 2. Drift check for security-sensitive snippets
+```
+check_drift(code="<auth/input-handling code>", language="typescript")
+```
+
+### 3. Fix all CRITICAL issues before merging
+
+| Severity | Action |
+|---|---|
+| 🔴 CRITICAL | Block merge — fix immediately |
+| 🟠 HIGH | Fix before merge |
+| 🔵 MEDIUM/LOW | Track, fix in follow-up |

package/skills/lucid-start/SKILL.md

@@ -1,70 +1,70 @@
----
-name: lucid-start
-description: MANDATORY at every session start and before any coding task — loads project context via Lucid before Claude reads any file or writes any code
-argument-hint: "[optional: what you are about to work on]"
----
-
-<HARD-GATE>
-You MUST complete ALL steps below BEFORE:
-- Reading any source file
-- Writing or editing any code
-- Answering any coding question
-- Creating any plan or task
-
-This is not optional. There are no exceptions. "I'll do it after" is not acceptable.
-</HARD-GATE>
-
-## Steps (all mandatory, in order)
-
-### 0. Get model recommendation
-```
-suggest_model(task_description="<paste the user's task description>")
-```
-Say: **"Using [model] — [reasoning]"** then proceed.
-
-### 1. Check what changed recently
-```
-get_recent(hours=48)
-```
-This shows files modified since your last session. Review the list.
-
-### 2. If working on a specific task — load relevant context
-```
-smart_context(query="<describe what you are about to work on>", task_type="moderate")
-```
-If the user's request involves code, call smart_context. For purely conversational exchanges with zero code involvement, this step may be omitted.
-
-### 3. Announce readiness
-Say: "✓ Lucid active — context loaded"
-
----
-
-## After EVERY file write or edit
-
-Call `sync_file` IMMEDIATELY after the tool call completes:
-```
-sync_file(path="<exact path of file you just wrote or edited>")
-```
-
-**Do this before anything else.** Before the next file. Before the next thought. Now.
-
-If you modified multiple files (refactor, git pull): call `sync_project()` instead.
-
----
-
-## Before marking any task as done
-
-Run /lucid-audit before saying "done", "fixed", "complete", or "implemented".
-
----
-
-## Trigger conditions
-
-**USE this skill:**
-- At the start of every new conversation
-- When resuming work after a break
-- When the user says "let's work on X" or similar
-
-**DO NOT USE for:**
-- Pure conversation with no code involved
-- Answering theoretical questions
+---
+name: lucid-start
+description: MANDATORY at every session start and before any coding task — loads project context via Lucid before Claude reads any file or writes any code
+argument-hint: "[optional: what you are about to work on]"
+---
+
+<HARD-GATE>
+You MUST complete ALL steps below BEFORE:
+- Reading any source file
+- Writing or editing any code
+- Answering any coding question
+- Creating any plan or task
+
+This is not optional. There are no exceptions. "I'll do it after" is not acceptable.
+</HARD-GATE>
+
+## Steps (all mandatory, in order)
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the user's task description>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
+### 1. Check what changed recently
+```
+get_recent(hours=48)
+```
+This shows files modified since your last session. Review the list.
+
+### 2. If working on a specific task — load relevant context
+```
+smart_context(query="<describe what you are about to work on>", task_type="moderate")
+```
+If the user's request involves code, call smart_context. For purely conversational exchanges with zero code involvement, this step may be omitted.
+
+### 3. Announce readiness
+Say: "✓ Lucid active — context loaded"
+
+---
+
+## After EVERY file write or edit
+
+Call `sync_file` IMMEDIATELY after the tool call completes:
+```
+sync_file(path="<exact path of file you just wrote or edited>")
+```
+
+**Do this before anything else.** Before the next file. Before the next thought. Now.
+
+If you modified multiple files (refactor, git pull): call `sync_project()` instead.
+
+---
+
+## Before marking any task as done
+
+Run /lucid-audit before saying "done", "fixed", "complete", or "implemented".
+
+---
+
+## Trigger conditions
+
+**USE this skill:**
+- At the start of every new conversation
+- When resuming work after a break
+- When the user says "let's work on X" or similar
+
+**DO NOT USE for:**
+- Pure conversation with no code involved
+- Answering theoretical questions

package/skills/lucid-webdev/SKILL.md

@@ -1,45 +1,45 @@
----
-name: lucid-webdev
-description: Use for web development tasks — generates components, pages, audits, API clients, and performance hints via Lucid's 10 web dev tools.
-argument-hint: "[what you are building: component/page/api/audit]"
----
-
-<HARD-GATE>
-Before building any web component, page, or API client from scratch:
-call the relevant generator tool first. Do not write boilerplate manually.
-</HARD-GATE>
-
-## When to invoke
-
-**INVOKE when:** building UI components, scaffolding pages, writing API clients, running accessibility/security/performance audits
-**DO NOT INVOKE for:** backend-only logic with no web layer
-
-## Steps
-
-### 0. Get model recommendation
-```
-suggest_model(task_description="<paste the user's task description>")
-```
-Say: **"Using [model] — [reasoning]"** then proceed.
-
-## Available tools
-
-| Task | Tool |
-|---|---|
-| Generate a React/Vue component | `generate_component(description, framework, styling, typescript)` |
-| Scaffold a full page | `scaffold_page(page_name, framework, sections, seo_title)` |
-| SEO meta tags | `seo_meta(title, description, keywords, page_type, url, image_url)` |
-| Accessibility audit | `accessibility_audit(code, wcag_level, framework)` |
-| API client | `api_client(endpoint, method, response_schema, auth, base_url_var)` |
-| Test scaffolding | `test_generator(code, test_framework, test_type, component_framework)` |
-| Responsive layout | `responsive_layout(description, framework, breakpoints, container)` |
-| Security scan | `security_scan(code, language, context)` |
-| Design tokens | `design_tokens(brand_name, primary_color, mood, output_format)` |
-| Performance hints | `perf_hints(code, framework, context)` |
-
-## Workflow
-
-1. Call the relevant generator/auditor tool
-2. Review output → adapt to project conventions
-3. `sync_file(path="<generated file>")` after saving
-4. Run /lucid-audit before marking done
+---
+name: lucid-webdev
+description: Use for web development tasks — generates components, pages, audits, API clients, and performance hints via Lucid's 10 web dev tools.
+argument-hint: "[what you are building: component/page/api/audit]"
+---
+
+<HARD-GATE>
+Before building any web component, page, or API client from scratch:
+call the relevant generator tool first. Do not write boilerplate manually.
+</HARD-GATE>
+
+## When to invoke
+
+**INVOKE when:** building UI components, scaffolding pages, writing API clients, running accessibility/security/performance audits
+**DO NOT INVOKE for:** backend-only logic with no web layer
+
+## Steps
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the user's task description>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
+## Available tools
+
+| Task | Tool |
+|---|---|
+| Generate a React/Vue component | `generate_component(description, framework, styling, typescript)` |
+| Scaffold a full page | `scaffold_page(page_name, framework, sections, seo_title)` |
+| SEO meta tags | `seo_meta(title, description, keywords, page_type, url, image_url)` |
+| Accessibility audit | `accessibility_audit(code, wcag_level, framework)` |
+| API client | `api_client(endpoint, method, response_schema, auth, base_url_var)` |
+| Test scaffolding | `test_generator(code, test_framework, test_type, component_framework)` |
+| Responsive layout | `responsive_layout(description, framework, breakpoints, container)` |
+| Security scan | `security_scan(code, language, context)` |
+| Design tokens | `design_tokens(brand_name, primary_color, mood, output_format)` |
+| Performance hints | `perf_hints(code, framework, context)` |
+
+## Workflow
+
+1. Call the relevant generator/auditor tool
+2. Review output → adapt to project conventions
+3. `sync_file(path="<generated file>")` after saving
+4. Run /lucid-audit before marking done