solvdex 2.0.0-alpha.5 → 3.0.0-alpha.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Knowledge management plugins for Claude Code",
-    "version": "2.0.0-alpha.5"
+    "version": "3.0.0-alpha.1"
   },
   "plugins": [
     {
@@ -15,8 +15,8 @@
         "source": "url",
         "url": "https://github.com/ducdmdev/solvdex.git"
       },
-      "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
-      "version": "2.0.0-alpha.5"
+      "description": "Universal problem-solving journal - auto-capture and retrieve knowledge (problems, solutions, references)",
+      "version": "3.0.0-alpha.1"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "solvdex",
-  "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
-  "version": "2.0.0-alpha.5",
+  "description": "Universal problem-solving journal - auto-captures and retrieves knowledge across problems, solutions, and references",
+  "version": "3.0.0-alpha.1",
   "author": {
     "name": "duc.do",
     "email": "ducdm.dev.work@gmail.com"

package/README.md

@@ -1,11 +1,11 @@
 # Solvdex
 
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](./tests)
-[![Version](https://img.shields.io/badge/version-2.0.0--alpha.3-blue)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.0--alpha.1-blue)](./package.json)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Architecture](https://img.shields.io/badge/architecture-pure%20agent-purple)](./docs/schema.md)
 
-> **An index of solved problems.** A Claude Code plugin that auto-captures and retrieves project knowledge.
+> **An index of solved problems.** A personal problem-solving journal that auto-captures and retrieves knowledge across any domain.
 
 ```
 +-------------------------------------------------------------+
@@ -25,7 +25,7 @@
 |---------|-------------|
 | **Auto-Capture** | Saves solutions when errors are resolved |
 | **Auto-Lookup** | Surfaces relevant knowledge on errors |
-| **7 Categories** | Organized knowledge across development domains |
+| **3 Folders** | Organized knowledge: problems, solutions, references |
 | **Trigger Patterns** | Regex matching for automatic error detection |
 | **Confidence Tracking** | Trust scores with decay over time |
 | **Cross-References** | Link related entries and source files |
@@ -34,40 +34,45 @@
 
 **Pure Agent Plugin - No Code Required**
 
-Solvdex 2.0 uses a pure agent-based architecture. All logic is implemented in agent markdown files - no TypeScript compilation needed.
+Solvdex 3.0 uses a pure agent-based architecture. All logic is implemented in agent markdown files - no TypeScript compilation needed. Fixed templates per folder ensure consistency. See [docs/templates/](./docs/templates/).
 
 > **[View Architecture Diagram](./docs/diagrams/architecture-overview.md)**
 
 | Layer | Components |
 |-------|------------|
-| **Skills (18)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
-| **Hooks** | SessionStart → wiki-advisor prompt, Stop → wiki-capture prompt |
-| **Agents (8)** | wiki-searcher, wiki-capture, wiki-scanner, wiki-validator, wiki-stats, wiki-health, wiki-graph, wiki-duplicate |
-| **Storage** | `.wiki/` with 7 categories |
+| **Skills (12)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
+| **Hooks** | SessionStart → entry count, PreToolUse → context hints, Stop → capture prompt |
+| **Agents (8)** | searcher, capture, scanner, validator, stats, health, graph, duplicate-checker |
+| **Storage** | `.wiki/` with 3 universal folders |
 
 ## Project Structure
 
 ```
 solvdex/
-├── agents/      # 8 specialized agents (ALL logic)
-├── skills/      # 18 Claude Code skills (thin wrappers)
-├── hooks/       # hooks.json (prompt-based hints)
-├── docs/        # Documentation
-│   └── schema.md  # Entry schema & constants (source of truth)
-└── tests/       # Validation tests
+├── agents/           # 8 specialized agents as flat .md files
+│   ├── searcher.md
+│   ├── capture.md
+│   ├── scanner.md
+│   ├── validator.md
+│   ├── stats.md
+│   ├── duplicate-checker.md
+│   ├── health.md
+│   └── graph.md
+├── skills/           # 18 Claude Code skills (thin wrappers)
+├── hooks/            # hooks.json (prompt-based hints)
+├── docs/             # Documentation
+│   ├── schema.md     # Entry schema & constants (source of truth)
+│   └── templates/    # Fixed templates per folder
+└── tests/            # Validation tests
 ```
 
-## Categories
+## Folders
 
 ```
 .wiki/
-├── issues/        # Bug fixes, error solutions
-├── patterns/      # Reusable code patterns
-├── gotchas/       # Pitfalls to avoid
-├── testing/       # Test strategies, mocks
-├── docs/          # Documentation guides
-├── security/      # Auth, vulnerabilities
-└── performance/   # Optimizations, benchmarks
+├── problems/      # What went wrong - bugs, errors, gotchas
+├── solutions/     # How to fix/do things - patterns, recipes
+└── references/    # Things to remember - docs, configs
 ```
 
 ## Quick Start
@@ -80,10 +85,10 @@ solvdex/
 /wiki search "database timeout"
 
 # Add current solution
-/wiki add --category=issues
+/wiki add --folder=problems
 
-# Browse entries
-/wiki browse
+# Browse all entries
+/wiki search
 ```
 
 ## Commands
@@ -93,30 +98,26 @@ solvdex/
 | Command | Description |
 |---------|-------------|
 | `/wiki init` | Create `.wiki/` structure |
-| `/wiki add` | Save current solution |
-| `/wiki search <query>` | Full-text search |
-| `/wiki browse` | List entries with filters |
+| `/wiki add` | Capture knowledge from conversation |
+| `/wiki search [query]` | Search or browse entries (no query = list all) |
 
-### Management Commands
+### Analysis Commands
 
 | Command | Description |
 |---------|-------------|
-| `/wiki status` | Quick health overview |
-| `/wiki stats` | Detailed analytics |
-| `/wiki validate` | Check for issues |
+| `/wiki stats [--quick]` | Statistics and health score |
+| `/wiki health [--validate]` | Health analysis with validation |
 | `/wiki scan` | Generate stubs from project |
-| `/wiki flag <entry>` | Mark for review |
-| `/wiki fix <entry>` | Update flagged entry |
-| `/wiki health` | Coverage gaps and health analysis |
 | `/wiki graph` | Relationship diagrams |
 
-### Transfer Commands
+### Entry Management
 
 | Command | Description |
 |---------|-------------|
+| `/wiki flag <entry>` | Mark for review |
+| `/wiki fix <entry>` | Update flagged entry |
 | `/wiki export [file]` | Export to JSON |
 | `/wiki import <file>` | Import from JSON |
-| `/wiki test-trigger` | Test regex patterns |
 
 ### Agents
 
@@ -124,14 +125,14 @@ All logic is implemented by specialized agents:
 
 | Agent | Commands | Description |
 |-------|----------|-------------|
-| `wiki-searcher` | `/wiki search`, `/wiki explore` | Search + recommendations |
-| `wiki-capture` | `/wiki add`, `/wiki capture` | Knowledge extraction |
-| `wiki-scanner` | `/wiki scan` | Project scanning |
-| `wiki-validator` | `/wiki validate` | Quality checks |
-| `wiki-stats` | `/wiki stats` | Analytics + maturity |
-| `wiki-duplicate-checker` | (internal) | Prevent duplicates |
-| `wiki-health` | `/wiki health` | Coverage gaps |
-| `wiki-graph` | `/wiki graph` | Relationship diagrams |
+| `searcher` | `/wiki search` | Search + browse |
+| `capture` | `/wiki add`, `/wiki fix` | Knowledge extraction |
+| `scanner` | `/wiki scan` | Project scanning |
+| `validator` | `/wiki flag` | Quality checks |
+| `stats` | `/wiki stats` | Analytics + maturity |
+| `health` | `/wiki health` | Coverage gaps + validation |
+| `graph` | `/wiki graph` | Relationship diagrams |
+| `duplicate-checker` | (internal) | Prevent duplicates |
 
 ## How It Works
 
@@ -144,9 +145,9 @@ All logic is implemented by specialized agents:
 +--------------+     +--------------+     +--------------+
 
 Signals detected:
-- error_resolved  -> issues/
-- workaround      -> gotchas/
-- user confirms   -> auto-detect category
+- error_resolved  -> problems/
+- workaround      -> solutions/
+- user confirms   -> auto-detect folder
 - explicit save   -> "remember this"
 ```
 
@@ -161,7 +162,7 @@ Signals detected:
 Lookup triggers:
 - Session start   -> relevant context
 - Error match     -> trigger patterns
-- Prompt keywords -> category detection
+- Prompt keywords -> folder detection
 ```
 
 ## Entry Format
@@ -170,10 +171,20 @@ Lookup triggers:
 ---
 title: Database Connection Timeout
 created: 2025-01-20
+updated: 2025-01-20
 status: active
 confidence: 85
+maturity: verified
 tags: [database, timeout, postgres]
 trigger: "ETIMEDOUT.*postgres"
+use_count: 5
+last_used: 2025-01-20
+related_entries:
+  - .wiki/solutions/connection-pool-config.md
+audit:
+  - date: 2025-01-20
+    action: created
+    by: user
 ---
 
 ## Problem
@@ -183,11 +194,11 @@ Connection times out after 30 seconds...
 Increase timeout and add connection pool...
 
 ## Related
-- [[issues/connection-pool]]
+- [[solutions/connection-pool-config]]
 - `src/db/config.ts:45`
 ```
 
-> **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md).
+> **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md). For entry templates, see [docs/templates/](./docs/templates/).
 
 ### Entry Maturity System
 
@@ -226,10 +237,11 @@ Confidence auto-decays for entries unused for 90+ days.
 
 Real-time integration with Claude Code via contextual prompts:
 
-| Hook | Suggests | When | Purpose |
-|------|----------|------|---------|
-| `SessionStart` | `wiki-advisor` | New conversation | Hint to check for relevant entries |
-| `Stop` | `wiki-capture` | Task completes | Hint to capture valuable knowledge |
+| 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 |
 
 Hooks are configured in `hooks/hooks.json` and provide prompt-based guidance to use wiki agents.
 
@@ -263,6 +275,7 @@ npm run test:watch   # Watch mode
 | Document | Description |
 |----------|-------------|
 | [Schema Reference](./docs/schema.md) | Entry schema & constants (source of truth) |
+| [Entry Templates](./docs/templates/) | Fixed templates per folder |
 | [Getting Started](./docs/getting-started.md) | Quick setup guide |
 | [Architecture](./docs/architecture.md) | System design |
 | [Workflows](./docs/workflows.md) | Hook and skill flows |

package/agents/{wiki-capture/AGENT.md → capture.md}

@@ -14,10 +14,11 @@ tools:
 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`
-- Categories: `docs/schema.md#default-categories`
+- Confidence levels: `docs/schema.md#confidence-constants`
+- Folders: `docs/schema.md#default-folders`
+- Entry Templates: `docs/templates/` (problems.md, solutions.md, references.md)
 
 Intelligently extract problem and solution from conversation context to create a wiki entry.
 
@@ -30,7 +31,7 @@ You will receive conversation context containing:
 
 Optional parameters:
 - `mode: "auto-capture"` - Auto-capture from conversation (hook)
-- `category: "<category>"` - Force specific category
+- `folder: "<folder>"` - Force specific folder (problems, solutions, references)
 - `title: "<title>"` - Force specific title
 
 ## Process
@@ -58,9 +59,9 @@ Include relevant code snippets (max 20 lines).
 
 **IMPORTANT: Always check before creating!**
 
-1. Search existing entries in detected category:
+1. Search existing entries in detected folder:
    ```
-   Glob .wiki/<category>/*.md
+   Glob .wiki/<folder>/*.md
    ```
 
 2. Compare semantically:
@@ -70,29 +71,29 @@ Include relevant code snippets (max 20 lines).
 
 3. If >80% similarity found:
    ```
-   Similar entry exists: category/existing-entry.md
-   Consider updating it instead: /wiki fix category/existing-entry.md
+   Similar entry exists: folder/existing-entry.md
+   Consider updating it instead: /wiki fix folder/existing-entry.md
    ```
    Do NOT create new entry.
 
 4. If 50-79% similarity:
    ```
-   Related entry found: category/related-entry.md
+   Related entry found: folder/related-entry.md
    Creating new entry and linking to related.
    ```
    Create entry with `related_entries` field.
 
-### Step 4: Determine Category
+### Step 4: Determine Folder
 
-| Keywords/Context | Category |
-|------------------|----------|
-| Error, Exception, bug, fix, crash | issues |
-| Pattern, approach, template, design | patterns |
-| Warning, pitfall, gotcha, careful, avoid | gotchas |
-| Test, mock, assert, spec, fixture | testing |
-| Auth, permission, token, secret, security | security |
-| Slow, optimize, cache, memory, performance | performance |
-| Doc, readme, guide, documentation | docs |
+Analyze content to determine the appropriate folder:
+
+| Content Analysis | Folder |
+|------------------|--------|
+| Problem encountered, error, failure, blocker, bug, crash, exception, pitfall, gotcha, warning, careful, avoid, security issue | problems/ |
+| How-to, procedure, recipe, pattern, template, approach, optimization, test strategy, workflow, steps to do something | solutions/ |
+| Documentation, reference, config, link, guide, API docs, notes, information to remember | references/ |
+
+**AI decides automatically.** If genuinely uncertain (>30% confidence in multiple folders), default to `problems/` for issues or `references/` for informational content.
 
 ### Step 5: Generate Tags
 
@@ -119,56 +120,70 @@ Create a concise, descriptive title:
 - Include technology: "TypeScript Generic Constraint Issue"
 - Max 60 characters
 
-### Step 7: Create Entry
+### Step 7: Create Entry Using Fixed Template
+
+**Use the fixed template for the target folder.** See `docs/templates/` for full templates.
+
+1. **Select template** based on folder:
+
+| Folder | Template Sections |
+|--------|-------------------|
+| `problems/` | Problem, Cause, Solution, Prevention, Related |
+| `solutions/` | Overview, Prerequisites, Steps, Example, Related |
+| `references/` | Summary, Details, Links, Related |
 
-Write to `.wiki/<category>/<slug>.md`:
+2. **Fill frontmatter**:
 
 ```yaml
 ---
-title: Descriptive Title
-created: YYYY-MM-DD
-updated: YYYY-MM-DD
+title: {{generated_title}}
+created: {{today YYYY-MM-DD}}
+updated: {{today YYYY-MM-DD}}
 status: active
 confidence: 40
 maturity: captured
-tags: [tag1, tag2, tag3]
-trigger: "error pattern regex"  # For issues category
+tags: [{{extracted_tags}}]
+trigger: "{{error_regex}}"  # problems/ only
+source: capture-agent
 use_count: 0
-related_entries:  # If found related entries
-  - category/related-entry.md
 audit:
-  - date: YYYY-MM-DD
+  - date: {{today YYYY-MM-DD}}
     action: created
     by: capture-agent
-    context: Auto-captured from conversation
 ---
+```
 
-# Problem
-
-<extracted problem description>
-
-# Solution
-
-<extracted solution with code>
+3. **Fill template sections** with extracted content:
 
-# Verification
+**For problems/**:
+- Problem: The error or issue encountered
+- Cause: Root cause analysis
+- Solution: Fix steps or code
+- Prevention: How to avoid in future
 
-<how to verify it works, or "Verified in conversation">
+**For solutions/**:
+- Overview: What this does and when to use
+- Prerequisites: What's needed first
+- Steps: Numbered procedure
+- Example: Code or config sample
 
-# Related
+**For references/**:
+- Summary: Brief description
+- Details: Information to remember
+- Links: External resources
 
-- [[category/related-entry]]  # If applicable
-```
+4. **Write to** `.wiki/<folder>/<slug>.md`
 
 ### Step 8: Return Confirmation
 
 ```
-Captured: category/entry-name.md
+Captured: folder/entry-name.md
    Title: Entry Title
+   Folder: problems | solutions | references
    Tags: tag1, tag2, tag3
    Confidence: 40 (captured)
 
-   Edit: /wiki fix category/entry-name.md
+   Edit: /wiki fix folder/entry-name.md
 ```
 
 ## Important Rules
@@ -178,5 +193,5 @@ Captured: category/entry-name.md
 3. **Include code** - solutions need concrete examples
 4. **Keep it concise** - problem/solution should be scannable
 5. **Set confidence 40** - captured entries start at maturity baseline
-6. **Add trigger patterns** - for issues category, extract regex
+6. **Add trigger patterns** - for problems folder, extract regex
 7. **Link related entries** - build the knowledge graph

package/agents/{wiki-duplicate-checker/AGENT.md → duplicate-checker.md}

@@ -16,7 +16,7 @@ Key references:
 - Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
 - Maturity rules: `docs/schema.md#maturity-rules`
 - Confidence levels: `docs/schema.md#confidence-levels`
-- Categories: `docs/schema.md#default-categories`
+- Folders: `docs/schema.md#default-folders`
 
 Detect potential duplicate entries before creation.
 
@@ -26,14 +26,14 @@ Detect potential duplicate entries before creation.
 {
   "title": "Database Connection Timeout",
   "tags": ["database", "timeout", "postgres"],
-  "category": "issues",
+  "folder": "problems",
   "contentSummary": "Fix for connection pool exhaustion..."
 }
 ```
 
 ## Process
 
-1. Load existing entries in same category
+1. Load existing entries in same folder
 2. Compare semantically:
    - Title similarity (exact, partial, synonym)
    - Tag overlap (Jaccard similarity)
@@ -48,7 +48,7 @@ Detect potential duplicate entries before creation.
 {
   "isDuplicate": true,
   "similarity": 85,
-  "matchedEntry": "issues/db-timeout.md",
+  "matchedEntry": "problems/db-timeout.md",
   "matchedTitle": "Database Timeout Fix",
   "reason": "Very similar title and tags",
   "suggestion": "Consider updating existing entry instead"
@@ -60,7 +60,7 @@ Detect potential duplicate entries before creation.
 {
   "isDuplicate": false,
   "similarity": 20,
-  "closestMatch": "issues/connection-error.md",
+  "closestMatch": "problems/connection-error.md",
   "suggestion": "Safe to create new entry"
 }
 ```
@@ -94,5 +94,5 @@ Detect potential duplicate entries before creation.
 
 1. Be conservative - prefer false positives over duplicates
 2. Consider synonyms (e.g., "timeout" ≈ "connection timeout")
-3. Same category increases likelihood
+3. Same folder increases likelihood
 4. Different maturity levels can coexist (stub vs detailed)

package/agents/{wiki-graph/AGENT.md → graph.md}

@@ -12,17 +12,17 @@ Generate visual relationship diagrams for wiki entries.
 ## Input
 
 - `{ "full": true }` - All entries
-- `{ "category": "issues" }` - Single category
-- `{ "entry": "issues/db-timeout.md" }` - Single entry and its relations
+- `{ "folder": "problems" }` - Single folder
+- `{ "entry": "problems/db-timeout.md" }` - Single entry and its relations
 
 ## Process
 
 1. Load entries (all or filtered)
 2. Extract relationships:
    - **Explicit**: `related_entries` field
-   - **Wiki links**: `[[category/entry]]` in content
+   - **Wiki links**: `[[folder/entry]]` in content
    - **Tag overlap**: 2+ shared tags
-   - **Same category**: Weak connection
+   - **Same folder**: Weak connection
 3. Generate Mermaid diagram
 
 ## Output Format
@@ -30,32 +30,34 @@ Generate visual relationship diagrams for wiki entries.
 ### Full Graph
 ```mermaid
 graph LR
-  subgraph issues
-    I1[DB Timeout]
-    I2[Auth Error]
-    I3[API Failure]
+  subgraph problems
+    P1[DB Timeout]
+    P2[Auth Error]
+    P3[Connection Pool Gotcha]
   end
 
-  subgraph patterns
-    P1[Retry Pattern]
-    P2[Circuit Breaker]
+  subgraph solutions
+    S1[Retry Pattern]
+    S2[Circuit Breaker]
+    S3[Pool Config]
   end
 
-  subgraph gotchas
-    G1[Connection Pool]
+  subgraph references
+    R1[API Docs]
+    R2[Config Guide]
   end
 
-  I1 -->|related| P1
-  I1 -->|related| G1
-  I2 -->|same-tag: auth| P2
-  I3 -->|wiki-link| P1
-  P1 -.->|same-category| P2
+  P1 -->|related| S1
+  P1 -->|related| P3
+  P2 -->|same-tag: auth| S2
+  S1 -.->|same-folder| S2
+  P3 -->|wiki-link| S3
 ```
 
-### Category Graph
+### Folder Graph
 ```mermaid
 graph TD
-  subgraph issues
+  subgraph problems
     A[DB Timeout]
     B[Auth Error]
     C[API Failure]
@@ -84,7 +86,7 @@ graph TD
 | related | `-->` solid | Explicit related_entries |
 | wiki-link | `-->` solid | [[link]] in content |
 | same-tag | `-->` labeled | 2+ shared tags |
-| same-category | `-.->` dashed | Same category |
+| same-folder | `-.->` dashed | Same folder |
 
 ## Node Styling
 
@@ -101,5 +103,5 @@ Based on confidence:
 ## Graph Limits
 
 - Full graph: Max 50 entries (summarize if more)
-- Category: Max 20 entries
+- Folder: Max 20 entries
 - Entry focus: Max 2 levels deep