solvdex 3.1.0-alpha.1 → 3.2.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Knowledge management plugins for Claude Code",
-    "version": "3.1.0-alpha.1"
+    "version": "3.2.0"
   },
   "plugins": [
     {
@@ -16,7 +16,7 @@
         "url": "https://github.com/ducdmdev/solvdex.git"
       },
       "description": "Universal problem-solving journal - auto-capture and retrieve knowledge (problems, solutions, references)",
-      "version": "3.1.0-alpha.1"
+      "version": "3.2.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "solvdex",
   "description": "Universal problem-solving journal - auto-captures and retrieves knowledge across problems, solutions, and references",
-  "version": "3.1.0-alpha.1",
+  "version": "3.2.0",
   "author": {
     "name": "duc.do",
     "email": "ducdm.dev.work@gmail.com"

package/README.md

@@ -1,7 +1,7 @@
 # Solvdex
 
 [![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://github.com/ducdmdev/solvdex)
-[![Version](https://img.shields.io/badge/version-3.1.0--alpha.1-blue)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.2.0-blue)](./package.json)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](./tests)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 
@@ -47,7 +47,7 @@ Solvdex 3.0 uses a pure agent-based architecture. All logic is implemented in ag
 | Layer | Components |
 |-------|------------|
 | **Skills (12)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
-| **Hooks** | SessionStart → entry count, PreToolUse → context hints, Stop → capture prompt |
+| **Hooks** | SessionStart → inline entry summaries, Stop → capture prompt |
 | **Agents (8)** | searcher, capture, scanner, validator, stats, health, graph, duplicate-checker |
 | **Storage** | `.wiki/` with 3 universal folders |
 
@@ -239,17 +239,16 @@ Solvdex automatically tracks and promotes entries through maturity phases based
 
 Confidence auto-decays for entries unused for 90+ days.
 
-## Hooks (Prompt-Based)
+## Hooks (Shell Scripts)
 
-Real-time integration with Claude Code via contextual prompts:
+Real-time integration with Claude Code via shell scripts in `hooks/`:
 
 | Hook | When | Purpose |
 |------|------|---------|
-| `SessionStart` | New conversation | Shows entry count, hints to use `/wiki search` |
-| `PreToolUse` | Before Edit/Write | Shows problems/solutions count for context |
-| `Stop` | Task completes | Hint to capture valuable knowledge |
+| `SessionStart` | New conversation | Inlines wiki entry summaries (title, folder, trigger, confidence) |
+| `Stop` | Task completes | Suggests `/wiki add` to capture valuable knowledge |
 
-Hooks are configured in `hooks/hooks.json` and provide prompt-based guidance to use wiki agents.
+Hooks are configured in `hooks/hooks.json` which delegates to shell scripts.
 
 ## Installation
 

package/agents/capture.md

@@ -1,7 +1,7 @@
 ---
 name: capture
 description: Extract problem/solution from conversation context and create wiki entry. Smart categorization, duplicate checking, tag suggestions.
-tools: Glob, Read, Write
+tools: Glob, Read, Write, Grep
 ---
 
 # Wiki Capture Agent
@@ -127,7 +127,7 @@ Create a concise, descriptive title:
 |--------|-------------------|
 | `problems/` | Problem, Cause, Solution, Prevention, Related |
 | `solutions/` | Overview, Prerequisites, Steps, Example, Related |
-| `references/` | Summary, Details, Links, Related |
+| `references/` | Summary, Version*, Details, Examples*, Notes*, Links, Related |
 
 2. **Fill frontmatter**:
 

package/agents/duplicate-checker.md

@@ -11,9 +11,9 @@ tools: Glob, Read
 For entry structure, validation rules, and constants, see: `docs/schema.md`
 
 Key references:
-- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
 - Maturity rules: `docs/schema.md#maturity-rules`
-- Confidence levels: `docs/schema.md#confidence-levels`
+- Confidence levels: `docs/schema.md#confidence-constants`
 - Folders: `docs/schema.md#default-folders`
 
 Detect potential duplicate entries before creation.

package/agents/health.md

@@ -11,9 +11,9 @@ tools: Glob, Read, Write
 For entry structure, validation rules, and constants, see: `docs/schema.md`
 
 Key references:
-- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
 - Maturity rules: `docs/schema.md#maturity-rules`
-- Confidence levels: `docs/schema.md#confidence-levels`
+- Confidence levels: `docs/schema.md#confidence-constants`
 - Folders: `docs/schema.md#default-folders`
 
 Comprehensive wiki health analysis and recommendations.
@@ -25,7 +25,7 @@ Comprehensive wiki health analysis and recommendations.
    - Stale: Not used in 90+ days
    - Stub: Missing Problem or Solution section
    - Low confidence: < 50
-   - No trigger: Issues without error pattern
+   - No trigger: Problems entries without trigger pattern
    - Orphaned: No tags, no related entries
    - Broken links: [[link]] to non-existent entry
 3. **Find coverage gaps**:

package/agents/stats.md

@@ -11,9 +11,9 @@ tools: Glob, Read, Write
 For entry structure, validation rules, and constants, see: `docs/schema.md`
 
 Key references:
-- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
 - Maturity rules: `docs/schema.md#maturity-rules`
-- Confidence levels: `docs/schema.md#confidence-levels`
+- Confidence levels: `docs/schema.md#confidence-constants`
 - Folders: `docs/schema.md#default-folders`
 
 Calculate comprehensive wiki statistics and manage maturity tracking.

package/agents/validator.md

@@ -11,9 +11,9 @@ tools: Glob, Read, Write
 For entry structure, validation rules, and constants, see: `docs/schema.md`
 
 Key references:
-- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
 - Maturity rules: `docs/schema.md#maturity-rules`
-- Confidence levels: `docs/schema.md#confidence-levels`
+- Confidence levels: `docs/schema.md#confidence-constants`
 - Folders: `docs/schema.md#default-folders`
 
 Validate wiki entries for quality and correctness.
@@ -67,9 +67,10 @@ Passed: Y | Issues: Z
 
 ## Validation Rules
 
-### Required Sections
-- All entries: Problem section (or Context)
-- All entries: Solution section
+### Required Sections (by folder)
+- problems/: Problem and Solution sections
+- solutions/: Overview and Steps sections
+- references/: Summary and Details sections
 
 ### Confidence-Maturity Match
 - captured: confidence should be 30-50

package/docs/README.md

@@ -26,11 +26,12 @@ A universal problem-solving journal - auto-capture and retrieve knowledge across
 |----------|-------------|
 | [plans/2025-02-02-agent-first-architecture.md](./plans/2025-02-02-agent-first-architecture.md) | Pure agent architecture (v3.0) |
 | [plans/2026-02-03-index-scaling-design.md](./plans/2026-02-03-index-scaling-design.md) | Index-based scaling design (v3.1) |
+| [plans/2026-02-03-v3.1-index-implementation.md](./plans/2026-02-03-v3.1-index-implementation.md) | Index implementation plan (v3.1) |
 
 ## Quick Links
 
 - **Skills:** 12 commands for wiki management
-- **Hooks:** 3 automated triggers for capture and retrieval
+- **Hooks:** 2 automated triggers for capture and retrieval
 - **Folders:** 3 universal folders (problems, solutions, references)
 
 ## Project Structure
@@ -49,11 +50,11 @@ solvdex/
 
 ## Version
 
-Current: v3.1.0-alpha.1
+Current: v3.2.0
 
 ## Quick Stats
 
 - **12 skills** - CLI commands for wiki management
-- **3 hooks** - Automated capture and retrieval
+- **2 hooks** - Automated capture and retrieval
 - **8 agents** - Specialized wiki operations
 - **3 folders** - Universal organization (problems, solutions, references)

package/docs/architecture.md

@@ -2,7 +2,7 @@
 
 Solvdex system design and component overview.
 
-**Version:** 3.1.0-alpha.1 - Universal Problem-Solving Journal
+**Version:** 3.2.0 - Universal Problem-Solving Journal
 
 ## System Overview
 
@@ -22,12 +22,12 @@ All business logic lives in agent markdown files. No TypeScript.
 | Agent | Purpose | Tools |
 |-------|---------|-------|
 | `searcher` | Search entries, find solutions, recommendations | Glob, Read |
-| `capture` | Extract problem/solution from conversations | Glob, Read, Write |
+| `capture` | Extract problem/solution from conversations | Glob, Read, Write, Grep |
 | `scanner` | Scan project and create stub entries | Bash, Read, Write, Grep, Glob |
-| `validator` | Validate entry quality, check for issues | Glob, Read |
+| `validator` | Validate entry quality, check for issues | Glob, Read, Write |
 | `stats` | Calculate statistics, track maturity | Glob, Read, Write |
 | `duplicate-checker` | Detect potential duplicate entries | Glob, Read |
-| `health` | Analyze coverage gaps, find stale entries | Glob, Read |
+| `health` | Analyze coverage gaps, find stale entries | Glob, Read, Write |
 | `graph` | Generate relationship diagrams (Mermaid) | Glob, Read |
 
 **Agent Naming:** Agent `name` field is required by Claude Code plugin spec and must match the filename without extension (e.g., `agents/scanner.md` → `name: scanner`).
@@ -90,17 +90,16 @@ See [Index Scaling Design](./plans/2026-02-03-index-scaling-design.md) for full
 - `wiki-export` - Export to JSON → `capture`
 - `wiki-import` - Import from JSON → `capture`
 
-### 3. Hooks (`hooks/hooks.json`) - Prompt-Based
+### 3. Hooks (`hooks/`) - Shell Scripts
 
 Hooks provide context prompts that guide Claude to use wiki agents when appropriate:
 
-| Hook | Purpose | Agent Suggested |
-|------|---------|-----------------|
-| `SessionStart` | Show entry count, hint to use `/wiki search` | (prompt-based) |
-| `PreToolUse` | Show problems/solutions count before Edit/Write | (prompt-based) |
-| `Stop` | Capture knowledge after tasks | `capture` |
+| Hook | Script | Purpose | Agent Suggested |
+|------|--------|---------|-----------------|
+| `SessionStart` | `hooks/session-start.sh` | Inline wiki entry summaries (title, folder, trigger, confidence) | (prompt-based) |
+| `Stop` | `hooks/stop.sh` | Capture knowledge after tasks | `capture` |
 
-No TypeScript hook files - all handled by `hooks.json` with prompt-based hints.
+No TypeScript hook files - `hooks.json` delegates to shell scripts in `hooks/`.
 
 ## Data Flow
 

package/docs/diagrams/architecture-overview.md

@@ -12,7 +12,6 @@ graph TB
         end
         subgraph "Hooks"
             H1["SessionStart"]
-            H2["Error"]
             H3["Stop"]
         end
     end
@@ -39,7 +38,6 @@ graph TB
     S3 --> A6
     S4 --> A7
     H1 --> A1
-    H2 --> A1
     H3 --> A2
 
     A1 --> W1

package/docs/getting-started.md

@@ -7,7 +7,10 @@ Set up Solvdex in your project in under 2 minutes.
 ### Via Claude Code Marketplace (Recommended)
 
 ```bash
-# Coming soon
+# Step 1: Add marketplace
+/plugin marketplace add https://raw.githubusercontent.com/ducdmdev/solvdex/main/.claude-plugin/marketplace.json
+
+# Step 2: Install plugin
 /plugin install solvdex
 ```
 
@@ -69,15 +72,14 @@ Or browse all:
 
 ## Automatic Context
 
-Solvdex hooks provide prompt-based hints to use wiki agents:
+Solvdex hooks provide context via shell scripts in `hooks/`:
 
 | Hook | Trigger | Purpose |
 |------|---------|---------|
-| SessionStart | New conversation | Shows wiki entry count |
-| PreToolUse | Before Edit/Write | Shows problems/solutions count for context |
-| Stop | Task completes | Hints to capture valuable knowledge |
+| SessionStart | New conversation | Inlines wiki entry summaries (title, folder, trigger, confidence) |
+| Stop | Task completes | Suggests `/wiki add` to capture valuable knowledge |
 
-Hooks are configured in `hooks/hooks.json` - no TypeScript needed.
+Hooks are configured in `hooks/hooks.json` which delegates to shell scripts.
 
 ## Next Steps
 

package/docs/plans/2025-02-02-agent-first-architecture.md

@@ -2,7 +2,7 @@
 
 **Created**: 2025-02-02
 **Updated**: 2025-02-02
-**Status**: Approved
+**Status**: Completed
 **Goal**: Eliminate TypeScript logic, move ALL intelligence to Claude agents
 
 ## Executive Summary

package/docs/plans/2025-02-02-generic-wiki-v3.md

@@ -2,6 +2,8 @@
 
 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
+**Status:** Completed
+
 **Goal:** Transform Solvdex from a dev-focused wiki (7 categories) to a universal problem-solving journal (3 categories) with AI-generated templates.
 
 **Architecture:** Replace fixed categories (issues, patterns, gotchas, testing, docs, security, performance) with 3 universal folders (problems, solutions, references). Remove fixed templates - AI generates structure based on content type. Domains become AI-inferred tags.

package/docs/plans/2026-02-03-index-scaling-design.md

@@ -1,7 +1,7 @@
 # Index-Based Scaling Design
 
 **Date:** 2026-02-03
-**Status:** Proposed
+**Status:** Implemented
 **Problem:** As wiki entries grow, agent-based search becomes slow and hits context window limits.
 
 ## Summary

package/docs/plans/2026-02-03-v3.1-index-implementation.md

@@ -2,6 +2,8 @@
 
 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
+**Status:** Completed
+
 **Goal:** Add `.wiki/index.json` for efficient agent-based search at scale (100-1000 entries).
 
 **Architecture:** Agents read a single index file instead of globbing/reading all entries. Index is derived data; markdown files remain source of truth. All operations use agent tools (Read, Write, Glob) — no compiled code.

package/docs/plans/2026-02-06-expand-test-coverage.md

@@ -0,0 +1,123 @@
+# Plan: Expand Solvdex Test Coverage
+
+**Status:** Implemented
+**Date:** 2026-02-06
+
+## Context
+
+Solvdex has 77 validation-only tests across 5 files (frontmatter structure checks). The quality pass we just completed revealed issues (stale schema links, wrong tools in docs, inconsistent required sections) that tests should have caught. We need tests that validate cross-file consistency, schema contracts, and template correctness.
+
+**Constraint:** This is a pure agent-based plugin — no TypeScript logic to unit test. All tests validate file structure, cross-references, and data contracts.
+
+## New Test Files (4 files, ~80 tests)
+
+### 1. `tests/cross-references.test.ts` (~20 tests)
+
+**Purpose:** Catch drift between agents, skills, docs, and hooks — the exact issues found in the quality pass.
+
+**What it tests:**
+- Every skill `agent:` field references an existing `agents/<name>.md` file
+- Every agent is referenced by at least one skill (exception: `duplicate-checker` is internal-only)
+- `architecture.md` agent tools table matches actual agent frontmatter tools
+- Schema reference links in agents (e.g., `docs/schema.md#confidence-constants`) point to valid headings in schema.md
+- README.md and CLAUDE.md reference correct counts (8 agents, 12 skills)
+- hooks.json event names are valid Claude Code hook events
+
+**Pattern:** Load all agents + skills + docs in `beforeAll`, then cross-check.
+
+### 2. `tests/schema-constants.test.ts` (~18 tests)
+
+**Purpose:** Validate `docs/schema.md` as a structured contract — ensure constants are consistent internally.
+
+**What it tests:**
+- Exactly 3 status values: `active`, `flagged`, `deprecated`
+- Exactly 3 maturity values: `captured`, `verified`, `validated`
+- Exactly 6 audit actions
+- Confidence constants: HIGH=80, MEDIUM=50, LOW=20, THRESHOLD=40, MAX=100, MIN=0
+- Maturity rules: ascending uses (0, 3, 10) and confidence (40, 70, 90)
+- Exactly 3 folders with matching template files in `docs/templates/`
+- Required frontmatter fields list
+- IndexEntry fields are a subset of EntryFrontmatter fields
+
+**Pattern:** Read schema.md, hardcode expected values, assert match. If schema changes, test forces update.
+
+### 3. `tests/templates.test.ts` (~15 tests)
+
+**Purpose:** Validate template structure matches schema documentation.
+
+**What it tests:**
+- Exactly 3 template files exist (problems.md, solutions.md, references.md)
+- problems/ template has sections: Problem, Cause, Solution, Prevention, Related
+- solutions/ template has sections: Overview, Prerequisites, Steps, Example, Related
+- references/ template has sections: Summary, Version, Details, Examples, Notes, Links, Related
+- Only problems/ template includes `trigger` field
+- All templates default to `confidence: 40`, `maturity: captured`
+- All templates include `audit` with `action: created`
+- Template frontmatter fields are valid EntryFrontmatter fields
+
+**Pattern:** Read template files, extract sections from code blocks via regex.
+
+### 4. `tests/frontmatter-contracts.test.ts` (~20 tests)
+
+**Purpose:** Test data validation rules using synthetic sample data.
+
+**What it tests:**
+- Date format: valid YYYY-MM-DD accepted, invalid formats rejected
+- Confidence range: 0-100 accepted, negative/over-100 rejected
+- Status enum: only `active`/`flagged`/`deprecated` valid
+- Maturity enum: only `captured`/`verified`/`validated` valid
+- Maturity progression: verified requires 3+ uses, validated requires 10+ uses
+- Audit entry requires date, action, by fields
+- Index entry path matches `<folder>/<slug>.md` pattern
+- Index entry folder field matches path prefix
+
+**Pattern:** Pure validation functions with hardcoded test data (no file I/O in individual tests).
+
+### 5. Enhance `tests/index-schema.test.ts` (+8 tests)
+
+**Purpose:** Add constraint validation to existing index tests.
+
+**What it adds:**
+- No stat value should be negative
+- `by_folder` keys must be valid folder names only
+- `by_maturity` keys must be valid maturity values only
+- Actual entry counts per folder match `by_folder` stats
+- Actual entry counts per maturity match `by_maturity` stats
+
+## Implementation Order
+
+1. `cross-references.test.ts` — catches the most impactful bugs (stale references)
+2. `schema-constants.test.ts` — establishes canonical constants
+3. `templates.test.ts` — validates template contracts
+4. `frontmatter-contracts.test.ts` — validates data rules
+5. `index-schema.test.ts` enhancements — incremental additions
+
+Commit after each file.
+
+## Critical Files
+
+| File | Role |
+|------|------|
+| `tests/agents.test.ts` | Pattern reference (imports, beforeAll, loop assertions) |
+| `docs/schema.md` | Source of truth for all constants |
+| `docs/architecture.md` | Agent tools table to cross-check |
+| `docs/templates/*.md` | Template sections to validate |
+| `agents/*.md` | 8 agent files to cross-reference |
+| `skills/*/SKILL.md` | 12 skill files to cross-reference |
+
+## Conventions (from existing tests)
+
+- Imports: `import { describe, it, expect, beforeAll } from 'vitest'` + `fs`, `path`, `gray-matter`
+- Root: `const rootDir = path.join(__dirname, '..')`
+- Heavy I/O in `beforeAll`, not in `it()` blocks
+- Descriptive error messages: `expect(value, \`${name} issue\`).toBe(expected)`
+- Loop over collections in single `it()` blocks
+- TypeScript interfaces for parsed data
+
+## Verification
+
+```bash
+npm test
+```
+
+Expected: All existing 77 tests + ~88 new tests = ~165 total, all passing.

package/docs/plans/2026-02-09-capture-fix-agent-injection.md

@@ -0,0 +1,153 @@
+# Fix Capture Workflow for Plugin Mode
+
+**Date:** 2026-02-09
+**Status:** Implemented
+**Version:** 3.2.0
+
+## Problem
+
+Solvdex capture doesn't work when installed as a plugin in other projects. Users report that `/wiki add` fails to properly create entries after solving problems.
+
+## Root Causes
+
+### 1. Skills Don't Load Agent Logic (CRITICAL)
+
+Per the [official Claude Code plugin spec](https://code.claude.com/docs/en/skills), the `agent:` field in SKILL.md only activates when `context: fork` is set. Without it, the field is decorative metadata.
+
+Current skills (like `wiki-add/SKILL.md`) have `agent: capture` but NO `context: fork`. When `/wiki add` is invoked:
+- Claude loads SKILL.md content **inline** (in the main conversation)
+- The skill has only **high-level** descriptions like "The capture agent will: 1. Analyze conversation 2. Check duplicates 3. Create entry"
+- The **detailed 9-step process** in `agents/capture.md` (240 lines) is **never loaded**
+- Claude improvises with the vague skill instructions - doesn't know exact frontmatter format, template structure, or index update procedure
+
+**Why `context: fork` can't fix this:** Forked subagents don't have conversation history. The capture agent NEEDS conversation context to extract problems and solutions.
+
+### 2. Stop Hook Output Is Invisible (MAJOR)
+
+Per the [official hooks spec](https://code.claude.com/docs/en/hooks), Stop hook stdout is **only shown in verbose mode** (`Ctrl+O`). Only `SessionStart` and `UserPromptSubmit` hooks have stdout added to Claude's context.
+
+Current `stop.sh` echoes "suggest /wiki add" but Claude **never sees it** in normal operation.
+
+However, Stop hooks CAN return JSON with `{"decision": "block", "reason": "..."}` - the reason IS shown to Claude, and `stop_hook_active` in the input prevents infinite loops.
+
+### 3. Capture Agent Missing Grep Tool (BUG)
+
+`agents/capture.md` declares `tools: Glob, Read, Write` but Step 5 instructs:
+```
+Grep "tags:" .wiki/**/*.md
+```
+
+If ever invoked as a subagent, the Grep tool would fail because it's not in the allowed tools list.
+
+## Solution
+
+### Strategy: Dynamic Content Injection via `!`command``
+
+Use Claude Code's official [`!`command`` preprocessing](https://code.claude.com/docs/en/skills#inject-dynamic-context) to inject full agent content into skills at load time.
+
+How it works:
+1. The `!`command`` syntax runs shell commands **before** skill content is sent to Claude
+2. Command output **replaces** the placeholder
+3. `${CLAUDE_PLUGIN_ROOT}` resolves to the plugin installation directory
+4. Result: Claude receives the complete agent instructions inline
+5. Conversation context is preserved (no fork = inline execution)
+
+This approach:
+- Keeps agents as the **single source of truth** (no duplication)
+- Gives skills the **complete procedure** instructions
+- Runs **inline** so conversation context is available
+- Uses an **official Claude Code feature**
+
+### Changes
+
+#### 1. `skills/wiki-add/SKILL.md` - Inject capture agent logic
+
+Keep existing frontmatter and usage section. Add dynamic injection of the full capture procedure:
+
+```markdown
+## Capture Procedure
+
+The following is the complete capture procedure from the capture agent:
+
+!`cat "${CLAUDE_PLUGIN_ROOT}/agents/capture.md"`
+```
+
+This replaces the high-level "The capture agent will..." with the actual 9-step process including exact frontmatter format, template selection, duplicate checking, and index updates.
+
+#### 2. `skills/wiki-fix/SKILL.md` - Inject capture agent logic
+
+Same approach for the fix/update workflow:
+
+```markdown
+## Capture Procedure Reference
+
+!`cat "${CLAUDE_PLUGIN_ROOT}/agents/capture.md"`
+```
+
+#### 3. `agents/capture.md` - Add Grep to tools
+
+```yaml
+# Before
+tools: Glob, Read, Write
+
+# After
+tools: Glob, Read, Write, Grep
+```
+
+Step 5 uses `Grep "tags:" .wiki/**/*.md` for tag reuse.
+
+#### 4. `hooks/stop.sh` - Use JSON decision control
+
+Replace plain echo with JSON output. Per spec, `decision: "block"` with `reason` IS shown to Claude:
+
+```bash
+#!/bin/sh
+# Stop hook: Suggest capturing knowledge using JSON decision control
+if [ ! -d .wiki ]; then exit 0; fi
+
+# Read JSON input and check stop_hook_active to prevent infinite loops
+INPUT=$(cat)
+echo "$INPUT" | grep -q '"stop_hook_active".*true' && exit 0
+
+# Return JSON decision - reason IS shown to Claude (unlike plain stdout)
+printf '{"decision":"block","reason":"Solvdex: If a problem was solved or valuable knowledge was learned, consider using /wiki add to capture it. If nothing notable, you may proceed."}\n'
+```
+
+#### 5. `CLAUDE.md` - Update hooks documentation
+
+Update hooks section to reflect:
+- Stop hook now uses JSON decision control (visible to Claude)
+- SessionStart hook stdout is added to Claude's context (already works)
+
+### Files NOT Changed
+
+| File | Reason |
+|------|--------|
+| `skills/wiki-scan/SKILL.md` | Already uses explicit `Task(subagent_type="scanner")` delegation; scanner doesn't need conversation context |
+| `hooks/hooks.json` | Structure unchanged (paths already fixed in previous commit) |
+| Other skills (search, stats, health, graph, flag) | Work adequately with inline instructions for read operations |
+
+## Risk Assessment
+
+| Change | Risk | Mitigation |
+|--------|------|------------|
+| `!`cat`` injection | Medium - requires `${CLAUDE_PLUGIN_ROOT}` to resolve correctly | Test in both local dev and plugin installation; if `!`cat`` fails, Claude sees the raw command (visible error) |
+| Stop hook blocking | Medium - more aggressive than silent echo | `stop_hook_active` prevents loops; Claude can dismiss and proceed |
+| Grep tool addition | Low - purely additive | No breaking changes |
+
+## Verification
+
+1. `npm test` - all existing tests pass (changes are backward-compatible)
+2. Manual: install as plugin in test project, invoke `/wiki add` after solving a problem
+3. Verify full 9-step capture executes (frontmatter, template, index update)
+4. Verify Stop hook shows suggestion to Claude in normal mode (not just verbose)
+5. Verify `stop_hook_active` prevents infinite loops
+
+## Alternative Approaches Considered
+
+| Approach | Why Rejected |
+|----------|-------------|
+| `context: fork` with conversation summary | Forked subagents don't have conversation history; manual summarization is lossy and complex |
+| Duplicate agent logic in skills | Violates DRY; 2x maintenance burden; agents are documented as "single source of truth" |
+| Accept limitation, document it | Defeats purpose of plugin marketplace; user reports this as critical |
+| `prompt` type Stop hook | Adds LLM call on every stop (latency + cost); blocking with JSON is simpler |

package/docs/use-cases.md

@@ -241,7 +241,7 @@ Returns top 5 most relevant entries with explanations.
 
 ---
 
-## Scenario 13: Scan New Project
+## Scenario 11: Scan New Project
 
 **Situation:** Just joined a project, want to populate wiki with initial knowledge.
 

package/docs/workflows.md

@@ -9,10 +9,9 @@ How Solvdex automates knowledge capture and retrieval.
 > **[View Session Workflow Diagram](./diagrams/session-workflow.md)**
 
 **Session Lifecycle:**
-1. **SessionStart** → Shows wiki entry count, hints to use `/wiki search`
-2. **User prompts** → Claude Code processes
-3. **Tool execution** → PreToolUse shows problems/solutions count for context
-4. **Continue or Stop** → Prompt hints to use `capture` agent
+1. **SessionStart** → Inlines wiki entry summaries (title, folder, trigger, confidence)
+2. **User prompts** → Claude Code processes with wiki context available
+3. **Continue or Stop** → Suggests `/wiki add` to capture valuable knowledge
 
 ## Hook Details
 

package/hooks/hooks.json

@@ -6,19 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -d .wiki ]; then t=$(find .wiki -name '*.md' -not -name 'README*' 2>/dev/null | wc -l | tr -d ' '); echo \"Solvdex: Wiki has $t entries. Check .wiki/index.json for entries relevant to this session. Surface highly relevant ones.\"; fi; exit 0",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "if [ -d .wiki ]; then echo 'Solvdex: Before editing, check .wiki/index.json for problems/solutions related to files being modified. Mention if highly relevant.'; fi; exit 0",
+            "command": "sh ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh; exit 0",
             "timeout": 5
           }
         ]
@@ -30,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -d .wiki ]; then echo 'Solvdex: If a problem was solved or something valuable was learned, suggest /wiki add to capture it.'; fi; exit 0",
+            "command": "sh ${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh; exit 0",
             "timeout": 5
           }
         ]

package/hooks/session-start.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# SessionStart hook: Surface wiki entries at session start
+if [ ! -d .wiki ]; then exit 0; fi
+
+if [ -f .wiki/index.json ]; then
+  node -e '
+    const idx = require("./.wiki/index.json");
+    const lines = idx.entries.map(e => {
+      let s = "  [" + e.folder + "] " + e.title;
+      if (e.trigger) s += " (trigger: " + e.trigger + ")";
+      s += " [confidence: " + e.confidence + "]";
+      return s;
+    });
+    console.log("Solvdex: Wiki has " + idx.stats.total + " entries. Surface relevant ones:");
+    lines.forEach(l => console.log(l));
+  '
+else
+  t=$(find .wiki -name '*.md' -not -name 'README*' 2>/dev/null | wc -l | tr -d ' ')
+  echo "Solvdex: Wiki has $t entries (no index). Use /wiki health --reindex to build index."
+fi

package/hooks/stop.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Stop hook: Suggest capturing knowledge using JSON decision control
+if [ ! -d .wiki ]; then exit 0; fi
+
+# Read JSON input and check stop_hook_active to prevent infinite loops
+INPUT=$(cat)
+echo "$INPUT" | grep -q '"stop_hook_active".*true' && exit 0
+
+# Return JSON decision - reason IS shown to Claude (unlike plain stdout)
+printf '{"decision":"block","reason":"Solvdex: If a problem was solved or valuable knowledge was learned, consider using /wiki add to capture it. If nothing notable, you may proceed."}\n'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solvdex",
-  "version": "3.1.0-alpha.1",
+  "version": "3.2.0",
   "description": "Universal problem-solving journal - auto-captures and retrieves knowledge across any domain",
   "files": [
     ".claude-plugin/",

package/skills/wiki-add/SKILL.md

@@ -26,14 +26,11 @@ Save knowledge from the current conversation to the wiki.
 - **Duplicate check**: Warns if similar entry exists
 - **Smart titles**: Generated from problem description
 
-## What Happens
-
-The capture agent will:
-1. Analyze conversation for problem/solution
-2. **Check for duplicate entries** (important!)
-3. Determine appropriate folder
-4. Use fixed template for the folder (see docs/templates/)
-5. Create entry with proper frontmatter
+## Capture Procedure
+
+The following is the complete capture procedure from the capture agent:
+
+!`cat "${CLAUDE_PLUGIN_ROOT}/agents/capture.md"`
 
 ## Folders
 

package/skills/wiki-fix/SKILL.md

@@ -15,17 +15,9 @@ Update a flagged entry and reset its status to active.
 
 - `entry-path`: Path to the wiki entry to fix (e.g., `problems/database-timeout.md`)
 
-## What Happens
+## Capture Procedure Reference
 
-When invoked, the **capture** agent will:
-
-1. **Read the flagged entry** - Load the current content and metadata
-2. **Show current content and issues** - Display what needs to be fixed
-3. **Analyze conversation context** - Look for new solutions or information
-4. **Update content** - Apply fixes based on the conversation
-5. **Reset status to 'active'** - Mark the entry as no longer flagged
-6. **Increase confidence** - Bump confidence if solution is verified
-7. **Add audit log entry** - Record the fix action
+!`cat "${CLAUDE_PLUGIN_ROOT}/agents/capture.md"`
 
 ## Process
 

package/skills/wiki-health/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wiki-health
 description: Analyze wiki health, validate entries, find coverage gaps, and get recommendations.
-argument-hint: "[--validate]"
+argument-hint: "[--validate] [--reindex]"
 user-invocable: true
 agent: health
 ---
@@ -15,6 +15,7 @@ Comprehensive wiki health analysis with validation and recommendations.
 ```
 /wiki health               # Full health report with recommendations
 /wiki health --validate    # Include detailed validation checks
+/wiki health --reindex     # Rebuild .wiki/index.json from entry files
 ```
 
 ## What You Get