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

package/agents/scanner.md

@@ -44,20 +44,33 @@ Check for these files to determine project type:
 
 ## Step 3: Create Entries
 
-For each finding, create entry in appropriate category:
-- `.wiki/issues/` - Bug fixes, errors
-- `.wiki/patterns/` - Reusable patterns
-- `.wiki/gotchas/` - Pitfalls, warnings
-- `.wiki/testing/` - Test strategies
-- `.wiki/docs/` - Documentation
-- `.wiki/security/` - Security items
-- `.wiki/performance/` - Optimizations
+For each finding, create entry in appropriate folder:
+- `.wiki/problems/` - Bug fixes, errors, gotchas, security issues
+- `.wiki/solutions/` - Patterns, optimizations, test strategies, how-tos
+- `.wiki/references/` - Documentation, guides, configs
 
-### Using Templates
+### Folder Selection
 
-1. Read template: `Read agents/templates/<category>.md`
-2. Fill placeholders with scanned data
-3. Write to `.wiki/<category>/<slug>.md`
+| Source Type | Folder |
+|-------------|--------|
+| Error logs, bug fixes, git fix commits | problems/ |
+| TODO/HACK comments about pitfalls | problems/ |
+| Reusable code patterns | solutions/ |
+| Test files, test strategies | solutions/ |
+| README, docs/, guides | references/ |
+| Config files, .env.example | references/ |
+
+### Generate Entry
+
+Use the fixed template for the target folder. See `docs/templates/`.
+
+| Folder | Template Sections |
+|--------|-------------------|
+| `problems/` | Problem, Cause, Solution, Prevention, Related |
+| `solutions/` | Overview, Prerequisites, Steps, Example, Related |
+| `references/` | Summary, Details, Links, Related |
+
+Write to `.wiki/<folder>/<slug>.md`
 
 ### Frontmatter Reference
 
@@ -86,13 +99,9 @@ Do NOT output progress. Return ONLY:
 
 ```
 Scan complete: X entries created
-- issues: N
-- patterns: N
-- gotchas: N
-- testing: N
-- docs: N
-- security: N
-- performance: N
+- problems: N
+- solutions: N
+- references: N
 ```
 
 ## Important Rules

package/agents/searcher.md

@@ -19,7 +19,7 @@ Input: `{ "mode": "search", "query": "<search query>" }`
 
 Process:
 1. Glob .wiki/**/*.md to find all entries
-2. Read frontmatter (title, tags, category, status, confidence, trigger)
+2. Read frontmatter (title, tags, folder, status, confidence, trigger)
 3. Understand query intent, handle typos/synonyms
 4. Rank by semantic relevance + confidence + maturity
 5. Return top 5 results with explanations
@@ -38,7 +38,7 @@ Input: `{ "mode": "session-context", "taskDescription": "<task>", "filePaths": [
 
 Process:
 1. Analyze task description for keywords
-2. Detect relevant categories from file paths
+2. Detect relevant folders from file paths
 3. Search for related entries
 4. Return top 3 recommendations
 
@@ -48,8 +48,9 @@ Process:
 ```
 Found X relevant entries:
 
-1. **{title}** ({category}, confidence: {n})
+1. **{title}** ({folder}, confidence: {n})
    Path: {path}
+   Tags: {tags}
    Why: {explanation}
 
 2. ...
@@ -68,8 +69,9 @@ Found X relevant entries:
 ### Session Context
 ```
 📚 Solvdex: {n} relevant entries
-  - {title} ({category})
-  - ...
+  - {title} (problems/)
+  - {title} (solutions/)
+  - {title} (references/)
 ```
 
 ## Ranking Criteria

package/agents/stats.md

@@ -17,7 +17,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`
 
 Calculate comprehensive wiki statistics and manage maturity tracking.
 
@@ -33,7 +33,7 @@ Calculate comprehensive wiki statistics and manage maturity tracking.
 1. Glob .wiki/**/*.md
 2. Read all entries
 3. Calculate:
-   - Entry counts by category, status, maturity
+   - Entry counts by folder, status, maturity
    - Confidence distribution (high/medium/low)
    - Usage stats (total uses, most used, never used)
    - Staleness (entries not updated in 90+ days)
@@ -61,8 +61,7 @@ Calculate comprehensive wiki statistics and manage maturity tracking.
 
 ## Entries
 Total: 24
-  issues: 8 | patterns: 6 | gotchas: 4
-  testing: 3 | docs: 2 | security: 1
+  problems: 12 | solutions: 8 | references: 4
 
 ## By Status
 Active: 20 | Flagged: 3 | Deprecated: 1

package/agents/validator.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`
 
 Validate wiki entries for quality and correctness.
 
@@ -32,7 +32,7 @@ Validate wiki entries for quality and correctness.
    - **Required sections**: Problem, Solution present
    - **No placeholders**: No TODO, FIXME, TBD in content
    - **Valid wiki links**: [[entry]] format, target exists
-   - **Trigger syntax**: Valid regex (for issues category)
+   - **Trigger syntax**: Valid regex (for problems folder, optional)
    - **Confidence/maturity match**: Confidence appropriate for maturity level
    - **Tags present**: At least 1 tag
 3. Categorize issues by severity
@@ -56,7 +56,7 @@ Passed: Y | Issues: Z
 - Low confidence (30) for verified maturity
 
 ### [info] {path}
-- No trigger pattern (issues category)
+- No trigger pattern (problems folder)
 ```
 
 ## Severity Levels
@@ -79,11 +79,11 @@ Passed: Y | Issues: Z
 - validated: confidence should be 85-100
 
 ### Trigger Patterns
-- Issues category: should have trigger pattern
-- Trigger must be valid regex
+- Problems folder: may have trigger pattern (optional)
+- Trigger must be valid regex if present
 
 ### Wiki Links
-- Format: [[category/entry-name]]
+- Format: [[folder/entry-name]]
 - Target entry must exist
 
 ### Tags

package/docs/README.md

@@ -1,6 +1,6 @@
 # Solvdex Documentation
 
-Auto-capture and retrieve project knowledge across 7 domains.
+A universal problem-solving journal - auto-capture and retrieve knowledge across any domain.
 
 ## Table of Contents
 
@@ -8,34 +8,45 @@ Auto-capture and retrieve project knowledge across 7 domains.
 |----------|-------------|
 | [Getting Started](./getting-started.md) | Quick setup and first steps |
 | [Architecture](./architecture.md) | System design and components |
+| [Schema Reference](./schema.md) | Entry structure, validation rules, constants |
 | [Workflows](./workflows.md) | How hooks and skills work together |
 | [Use Cases](./use-cases.md) | Common scenarios and examples |
 
+### Reference
+
+| Document | Description |
+|----------|-------------|
+| [templates/problems.md](./templates/problems.md) | Template for problems folder |
+| [templates/solutions.md](./templates/solutions.md) | Template for solutions folder |
+| [templates/references.md](./templates/references.md) | Template for references folder |
+
 ## Quick Links
 
-- **Skills:** 18 commands for wiki management
-- **Hooks:** 2 automated triggers for capture and retrieval
-- **Categories:** 7 knowledge domains
+- **Skills:** 12 commands for wiki management
+- **Hooks:** 3 automated triggers for capture and retrieval
+- **Folders:** 3 universal folders (problems, solutions, references)
 
 ## Project Structure
 
 ```
 solvdex/
 ├── agents/              # ALL logic lives here (8 agents)
-├── skills/              # Thin wrappers (18 commands)
-├── hooks/               # Agent-based hooks (2)
+├── skills/              # Thin wrappers (12 commands)
+├── hooks/               # Agent-based hooks (3)
 ├── docs/                # Documentation (you are here)
+│   ├── templates/       # Entry templates per folder
+│   ├── diagrams/        # Architecture diagrams
 │   └── plans/           # Planning docs
 └── tests/               # Validation tests
 ```
 
 ## Version
 
-Current: v2.0.0
+Current: v3.0.0-alpha.1
 
 ## Quick Stats
 
-- **18 skills** - CLI commands for wiki management
-- **2 hooks** - Automated capture and retrieval
+- **12 skills** - CLI commands for wiki management
+- **3 hooks** - Automated capture and retrieval
 - **8 agents** - Specialized wiki operations
-- **7 categories** - Knowledge domains (issues, patterns, gotchas, testing, docs, security, performance)
+- **3 folders** - Universal organization (problems, solutions, references)

package/docs/architecture.md

@@ -2,16 +2,16 @@
 
 Solvdex system design and component overview.
 
-**Version:** 2.0.0 - Pure Agent Architecture (No TypeScript)
+**Version:** 3.0.0-alpha.1 - Universal Problem-Solving Journal
 
 ## System Overview
 
-> **[View System Diagram](./diagrams/system-overview.md)**
+> **[View System Diagram](./diagrams/system-overview.md)** | **[Schema Reference](./schema.md)** (source of truth for data types)
 
 The system consists of three layers:
-- **Skills (18)**: Thin command wrappers with `agent:` field
+- **Skills (12)**: Thin command wrappers with `agent:` field
 - **Agents (8)**: All business logic in markdown files
-- **Storage**: `.wiki/` directory with 7 categories
+- **Storage**: `.wiki/` directory with 3 universal folders
 
 ## Core Components
 
@@ -30,37 +30,29 @@ All business logic lives in agent markdown files. No TypeScript.
 | `health` | Analyze coverage gaps, find stale entries | Glob, Read |
 | `graph` | Generate relationship diagrams (Mermaid) | Glob, Read |
 
-**Agent Naming:** Agent names are derived from folder names (e.g., `agents/scanner/`). Do NOT include a `name` field in agent frontmatter.
+**Agent Naming:** Agent names are derived from file names without extension (e.g., `agents/scanner.md` → agent name is `scanner`). Do NOT include a `name` field in agent frontmatter.
 
 ### 2. Skills (`skills/`) - Thin Wrappers
 
-18 skills that delegate to agents via `agent:` frontmatter field:
+12 skills that delegate to agents via `agent:` frontmatter field:
 
 **Core:**
-- `wiki` - Main router
-- `wiki-init` - Initialize wiki
-- `wiki-add` - Add entry → `capture`
-- `wiki-search` - Search entries → `searcher`
-- `wiki-browse` - List entries → `searcher`
-
-**Management:**
-- `wiki-status` - Quick health check → `stats`
-- `stats` - Detailed statistics → `stats`
-- `wiki-validate` - Full validation → `validator`
+- `wiki` - Main router → `searcher`
+- `wiki-init` - Initialize wiki → `capture`
+- `wiki-add` - Capture knowledge → `capture`
+- `wiki-search` - Search/browse entries → `searcher`
+
+**Analysis:**
+- `wiki-stats` - Statistics (--quick for summary) → `stats`
+- `wiki-health` - Health + validation (--validate) → `health`
 - `wiki-scan` - Project scanning → `scanner`
+- `wiki-graph` - Relationship diagrams → `graph`
+
+**Entry Management:**
 - `wiki-flag` - Flag for review → `validator`
 - `wiki-fix` - Update flagged entry → `capture`
-- `health` - Coverage gaps → `health`
-- `graph` - Relationship diagrams → `graph`
-
-**Transfer:**
 - `wiki-export` - Export to JSON → `capture`
 - `wiki-import` - Import from JSON → `capture`
-- `wiki-test-trigger` - Test trigger patterns → `searcher`
-
-**Search:**
-- `wiki-explorer` - Deep search → `searcher`
-- `capture` - Knowledge extraction → `capture`
 
 ### 3. Hooks (`hooks/hooks.json`) - Prompt-Based
 
@@ -68,7 +60,7 @@ Hooks provide context prompts that guide Claude to use wiki agents when appropri
 
 | Hook | Purpose | Agent Suggested |
 |------|---------|-----------------|
-| `SessionStart` | Surface relevant entries at task start | `wiki-advisor` |
+| `SessionStart` | Show entry count, hint to use `/wiki search` | (prompt-based) |
 | `Stop` | Capture knowledge after tasks | `capture` |
 
 No TypeScript hook files - all handled by `hooks.json` with prompt-based hints.
@@ -90,7 +82,7 @@ No TypeScript hook files - all handled by `hooks.json` with prompt-based hints.
 
 1. User starts task or encounters error
 2. Hook triggers `searcher` agent
-3. Agent searches by keywords, triggers, category
+3. Agent searches by keywords, triggers, folder
 4. Matching solutions displayed
 
 ## Entry Structure
@@ -124,7 +116,7 @@ audit:                      # Audit trail
 ...
 
 # Related
-- [[issues/related-bug]]
+- [[problems/related-bug]]
 - `src/db/config.ts:45`
 ```
 
@@ -177,13 +169,11 @@ Penalties:
 .wiki/
 ├── wiki.yaml              # Global configuration
 ├── README.md              # Wiki overview
-├── issues/
-│   ├── _overview.md       # Category overview
-│   └── *.md               # Issue entries
-├── patterns/
-├── gotchas/
-├── testing/
-├── docs/
-├── security/
-└── performance/
+├── problems/              # What went wrong - bugs, errors, gotchas
+│   ├── _overview.md       # Folder overview
+│   └── *.md               # Problem entries
+├── solutions/             # How to fix/do things - patterns, recipes
+│   └── *.md               # Solution entries
+└── references/            # Things to remember - docs, configs
+    └── *.md               # Reference entries
 ```

package/docs/diagrams/architecture-overview.md

@@ -3,7 +3,7 @@
 ```mermaid
 graph TB
     subgraph CC["Claude Code"]
-        subgraph Skills["Skills (18)"]
+        subgraph Skills["Skills (12)"]
             S1["/wiki search"]
             S2["/wiki add"]
             S3["/wiki health"]
@@ -25,17 +25,13 @@ graph TB
         A5["stats"]
         A6["health"]
         A7["graph"]
-        A8["wiki-duplicate"]
+        A8["duplicate-checker"]
     end
 
     subgraph ".wiki/ Storage"
-        W1["issues/"]
-        W2["patterns/"]
-        W3["gotchas/"]
-        W4["testing/"]
-        W5["docs/"]
-        W6["security/"]
-        W7["performance/"]
+        W1["problems/"]
+        W2["solutions/"]
+        W3["references/"]
     end
 
     S1 --> A1
@@ -47,8 +43,9 @@ graph TB
     H3 --> A2
 
     A1 --> W1
-    A2 --> W1
-    A3 --> W1
     A1 --> W2
+    A1 --> W3
+    A2 --> W1
     A2 --> W2
+    A2 --> W3
 ```

package/docs/diagrams/data-structures.md

@@ -5,7 +5,7 @@ erDiagram
     WikiEntry ||--|| EntryFrontmatter : has
     WikiEntry {
         string path
-        string category
+        string folder
         string slug
         string content
     }
@@ -34,7 +34,7 @@ erDiagram
     WikiConfig {
         number version
         string project
-        array categories
+        array folders
         object auto_capture
         object auto_lookup
         object validation

package/docs/diagrams/knowledge-retrieval-flow.md

@@ -12,7 +12,7 @@ sequenceDiagram
     Claude->>Hook: Trigger lookup
     Hook->>Agent: Search request
     Agent->>Wiki: Query entries
-    Note over Agent: Search by:<br/>- keywords<br/>- trigger patterns<br/>- category
+    Note over Agent: Search by:<br/>- keywords<br/>- trigger patterns<br/>- folder
     Wiki-->>Agent: Matching entries
     Agent-->>User: Display solutions
 ```

package/docs/diagrams/session-workflow.md

@@ -5,7 +5,7 @@ flowchart TD
     START([START]) --> SessionStart
 
     subgraph Session["Session Lifecycle"]
-        SessionStart["SessionStart Hook<br/>(prompt: use wiki-advisor)"] --> |Claude checks wiki| Suggestions["Display relevant entries"]
+        SessionStart["SessionStart Hook<br/>(shows entry count)"] --> |Wiki available| Suggestions["Display: Wiki has N entries"]
         Suggestions --> UserPrompt["User Prompt"]
         UserPrompt --> Processing["Claude Code Processing"]
         Processing --> ToolExec["Tool Execution"]

package/docs/diagrams/system-overview.md

@@ -3,7 +3,7 @@
 ```mermaid
 graph TB
     subgraph CC["Claude Code"]
-        subgraph Skills["Skills (18)"]
+        subgraph Skills["Skills (12)"]
             SK["Commands"]
         end
         subgraph Hooks["Hooks"]
@@ -24,12 +24,8 @@ graph TB
     end
     Agents --> Storage
     subgraph Storage[".wiki/ Storage"]
-        S1["issues/"]
-        S2["patterns/"]
-        S3["gotchas/"]
-        S4["testing/"]
-        S5["docs/"]
-        S6["security/"]
-        S7["performance/"]
+        S1["problems/"]
+        S2["solutions/"]
+        S3["references/"]
     end
 ```

package/docs/getting-started.md

@@ -22,7 +22,7 @@ npm install   # For running tests only - no build step needed
 
 2. Link to your project's Claude Code config.
 
-> **Note:** Solvdex 2.0 is a pure agent plugin with no build step required.
+> **Note:** Solvdex 3.0 is a pure agent plugin with no build step required.
 
 ## Initialize Wiki
 
@@ -37,13 +37,9 @@ This creates:
 .wiki/
 ├── wiki.yaml           # Configuration
 ├── README.md           # Wiki overview
-├── issues/             # Bug fixes, error solutions
-├── patterns/           # Reusable code patterns
-├── gotchas/            # Pitfalls and edge cases
-├── testing/            # Test strategies
-├── docs/               # Documentation guides
-├── security/           # Security patterns
-└── performance/        # Optimizations
+├── problems/           # What went wrong - bugs, errors, gotchas
+├── solutions/          # How to fix/do things - patterns, recipes
+└── references/         # Things to remember - docs, configs
 ```
 
 ## First Entry
@@ -57,7 +53,7 @@ After solving a problem:
 Or with options:
 
 ```
-/wiki add --category=issues --title="Database Timeout Fix"
+/wiki add --folder=problems --title="Database Timeout Fix"
 ```
 
 ## Search Knowledge
@@ -69,7 +65,7 @@ Or with options:
 Or browse all:
 
 ```
-/wiki browse
+/wiki search
 ```
 
 ## Automatic Context
@@ -78,7 +74,7 @@ Solvdex hooks provide prompt-based hints to use wiki agents:
 
 | Hook | Suggests | Trigger | Purpose |
 |------|----------|---------|---------|
-| SessionStart | `wiki-advisor` | New conversation | Hint to check for relevant entries |
+| SessionStart | (entry count) | New conversation | Shows wiki size, hints to use `/wiki search` |
 | Stop | `capture` | Task completes | Hint to capture valuable knowledge |
 
 Hooks are configured in `hooks/hooks.json` - no TypeScript needed. For error lookups, use `/wiki search` manually.
@@ -87,4 +83,5 @@ Hooks are configured in `hooks/hooks.json` - no TypeScript needed. For error loo
 
 - Read [Workflows](./workflows.md) to understand automation
 - See [Use Cases](./use-cases.md) for common scenarios
-- Check [Templates](./templates/) for entry structure
+- Check [Schema Reference](./schema.md#entry-templates) for entry structure
+- See [Entry Templates](./templates/) for folder-specific templates

package/docs/plans/2025-01-22-marketplace-distribution.md

@@ -1,5 +1,7 @@
 # DevWiki Marketplace Distribution Plan
 
+> **⚠️ HISTORICAL:** This document references DevWiki v0.2.0 and predates the Solvdex v3.0 rebranding. Some details may be outdated but the distribution approach remains relevant.
+
 ## Overview
 
 Publish DevWiki as a Claude Code plugin to a marketplace for easy installation via `/plugin install`.

package/docs/plans/2025-01-22-solvdex-design.md

@@ -1,5 +1,7 @@
 # Solvdex Design
 
+> **⚠️ SUPERSEDED:** This v2.0 design document has been replaced by v3.0. See [2025-02-02-generic-wiki-v3.md](./2025-02-02-generic-wiki-v3.md) for the current design with 3 universal folders (problems, solutions, references).
+
 > Renamed from DevWiki. An index of solved problems.
 
 ## Overview