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

package/agents/graph.md

@@ -1,8 +1,7 @@
 ---
+name: graph
 description: Generate Mermaid diagrams showing entry relationships.
-tools:
-  - Glob
-  - Read
+tools: Glob, Read
 ---
 
 # Wiki Graph Agent
@@ -12,17 +11,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 +29,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 +85,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 +102,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

package/agents/health.md

@@ -1,9 +1,7 @@
 ---
-description: Analyze wiki health - find stale entries,
-  coverage gaps, and maintenance needs.
-tools:
-  - Glob
-  - Read
+name: health
+description: Analyze wiki health - find stale entries, coverage gaps, and maintenance needs.
+tools: Glob, Read, Write
 ---
 
 # Wiki Health Agent
@@ -16,7 +14,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`
 
 Comprehensive wiki health analysis and recommendations.
 
@@ -31,10 +29,71 @@ Comprehensive wiki health analysis and recommendations.
    - Orphaned: No tags, no related entries
    - Broken links: [[link]] to non-existent entry
 3. **Find coverage gaps**:
-   - Categories with < 3 entries
+   - Folders with < 3 entries
    - Common error patterns without entries
 4. **Generate recommendations**
 
+## Index Operations
+
+### Validate Index (default with /wiki health)
+
+1. **Read index** from `.wiki/index.json` (if exists)
+2. **Glob all entries** from `.wiki/**/*.md`
+3. **Compare**:
+   - Entry in index but file missing → report orphan
+   - File exists but not in index → report missing
+   - Frontmatter differs from index → report stale
+   - Stats don't match counts → report mismatch
+4. **Output validation report**
+
+### Rebuild Index (with --reindex flag)
+
+1. **Glob all entries** from `.wiki/**/*.md` (excluding README.md)
+2. **For each entry**, Read frontmatter and extract:
+   - path (relative, e.g., `problems/db-timeout.md`)
+   - title
+   - folder (from path)
+   - tags
+   - trigger (if present)
+   - confidence
+   - maturity
+   - status
+   - use_count
+3. **Calculate stats**:
+   - total: count of entries
+   - by_folder: count per folder
+   - by_maturity: count per maturity level
+4. **Write index** to `.wiki/index.json`:
+   ```json
+   {
+     "version": 1,
+     "updated": "<ISO timestamp>",
+     "stats": { ... },
+     "entries": [ ... ]
+   }
+   ```
+5. **Output**: "Index rebuilt: X entries"
+
+### Index Validation Output
+
+```
+## Index Health
+
+✓ Index exists: .wiki/index.json
+✓ 48 entries in sync
+
+Issues:
+✗ 2 files not in index:
+  - problems/new-error.md
+  - solutions/quick-fix.md
+✗ 1 orphan in index (file deleted):
+  - references/old-doc.md
+✗ 1 stale entry (frontmatter changed):
+  - problems/db-timeout.md
+
+Run /wiki health --reindex to fix.
+```
+
 ## Output Format
 
 ```
@@ -45,29 +104,28 @@ Comprehensive wiki health analysis and recommendations.
 ## Issues Found
 
 ### Stale Entries (5)
-- patterns/old-api.md (120 days)
-- issues/legacy-auth.md (95 days)
+- solutions/old-api.md (120 days)
+- problems/legacy-auth.md (95 days)
 → Consider reviewing or deprecating
 
 ### Stub Entries (3)
-- issues/api-timeout.md - Missing Solution
-- gotchas/edge-case.md - Missing Problem
+- problems/api-timeout.md - Missing Solution
+- problems/edge-case.md - Missing Problem
 → Run /wiki fix <entry> to complete
 
 ### Low Confidence (4)
-- patterns/untested.md (confidence: 30)
+- solutions/untested.md (confidence: 30)
 → Verify and increase confidence
 
 ### Missing Triggers (2)
-- issues/db-error.md
-- issues/auth-fail.md
+- problems/db-error.md
+- problems/auth-fail.md
 → Add trigger patterns for auto-matching
 
 ## Coverage Gaps
 
-### Underserved Categories
-- security: 1 entry (recommend: 3+)
-- performance: 2 entries (recommend: 3+)
+### Underserved Folders
+- references: 1 entry (recommend: 2+)
 
 ### Suggested Entries
 Based on common errors, consider adding:
@@ -79,8 +137,8 @@ Based on common errors, consider adding:
 
 1. Review 5 stale entries
 2. Complete 3 stub entries
-3. Add triggers to 2 issues
-4. Expand security category
+3. Add triggers to 2 problems
+4. Expand references folder
 ```
 
 ## Health Indicators
@@ -102,12 +160,17 @@ Based on common errors, consider adding:
 
 ## Coverage Analysis
 
-For each category:
+For each folder:
 1. Count entries
 2. Compare to minimum (3)
 3. Flag if under-served
 
-Recommend expanding categories with:
+Recommend expanding folders with:
 - High error rates in project
 - Recent user questions
 - Common patterns in codebase
+
+### Minimum Recommendations
+- problems: 3+ entries
+- solutions: 3+ entries
+- references: 2+ entries

package/agents/scanner.md

@@ -1,11 +1,7 @@
 ---
+name: scanner
 description: Scan any project type and create wiki entries. Auto-detects Go, Node.js, Python, etc.
-tools:
-  - Bash
-  - Read
-  - Write
-  - Grep
-  - Glob
+tools: Bash, Read, Write, Grep, Glob
 ---
 
 # Universal Wiki Scanner
@@ -44,20 +40,53 @@ 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 |
+
+### Related Section Rules
+
+**IMPORTANT:** Always use relative paths from project root, NOT absolute paths.
+
+```markdown
+## Related
+
+- `CLAUDE.md`                    ✅ Correct (relative)
+- `docs/specs/errors.md`         ✅ Correct (relative)
+- `/Users/foo/project/README.md` ❌ Wrong (absolute)
+```
+
+Cross-link to other wiki entries when relevant:
+```markdown
+## Related
+
+- `internal/auth/` (source code)
+- [Error Handling Pattern](../solutions/error-handling.md) (wiki entry)
+```
+
+Write to `.wiki/<folder>/<slug>.md`
 
 ### Frontmatter Reference
 
@@ -71,6 +100,7 @@ status: active
 confidence: 40-100
 maturity: captured
 tags: [relevant, tags]
+trigger: "error pattern regex"  # ONLY for problems/ - optional
 source: where-found
 use_count: 0
 audit:
@@ -80,19 +110,88 @@ audit:
 ---
 ```
 
-## Step 4: Return Summary ONLY
+**Trigger field (problems/ only):** If the problem has an identifiable error message or pattern, add a `trigger` field with a regex that matches it. This enables automatic error matching.
+
+Examples:
+- `trigger: "json: unsupported type"` for JSON encoding errors
+- `trigger: "undefined is not a function"` for JS runtime errors
+- `trigger: "connection refused"` for network errors
+
+## Step 4: Create Wiki Index and Performance Index
+
+After creating entries, generate both indexes:
+
+### Generate README Index (human-readable)
+
+Write `.wiki/README.md`:
+
+```markdown
+# Project Wiki
+
+Auto-generated knowledge base for this project.
+
+## Entries
+
+### Problems (N)
+- [Entry Title](problems/slug.md) - Brief description
+
+### Solutions (N)
+- [Entry Title](solutions/slug.md) - Brief description
+
+### References (N)
+- [Entry Title](references/slug.md) - Brief description
+
+---
+*Generated by Solvdex scanner on YYYY-MM-DD*
+```
+
+### Generate Performance Index (v3.1+)
+
+Build and write `.wiki/index.json`:
+
+1. **Collect all created entries** into index format:
+   ```json
+   {
+     "path": "<folder>/<slug>.md",
+     "title": "<title>",
+     "folder": "<folder>",
+     "tags": ["<tags>"],
+     "trigger": "<regex if problems>",
+     "confidence": 40,
+     "maturity": "captured",
+     "status": "active",
+     "use_count": 0
+   }
+   ```
+
+2. **Calculate stats**:
+   ```json
+   {
+     "total": N,
+     "by_folder": { "problems": X, "solutions": Y, "references": Z },
+     "by_maturity": { "captured": N, "verified": 0, "validated": 0 }
+   }
+   ```
+
+3. **Write index**:
+   ```json
+   {
+     "version": 1,
+     "updated": "<ISO timestamp>",
+     "stats": { ... },
+     "entries": [ ... ]
+   }
+   ```
+
+## Step 5: Return Summary ONLY
 
 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

@@ -1,11 +1,7 @@
 ---
-description: Search wiki entries using semantic understanding.
-  Finds entries by meaning, not just keywords. Handles typos,
-  synonyms, and related concepts. Also provides recommendations
-  and error matching.
-tools:
-  - Glob
-  - Read
+name: searcher
+description: Search wiki entries using semantic understanding. Finds entries by meaning, not just keywords. Handles typos, synonyms, and related concepts. Also provides recommendations and error matching.
+tools: Glob, Read
 ---
 
 # Wiki Searcher Agent
@@ -14,31 +10,62 @@ Search wiki entries semantically and provide intelligent recommendations.
 
 ## Modes
 
+## Index-First Search (v3.1+)
+
+**Always try index first, fall back to Glob+Read if index missing.**
+
+### Check for Index
+
+1. Attempt to Read `.wiki/index.json`
+2. If exists and valid JSON:
+   - Use index for search (fast path)
+   - Only Read full entries for top matches
+3. If missing or invalid:
+   - Fall back to Glob+Read pattern (backward compatible)
+   - Log: "Index not found, using file scan"
+
+### Search with Index
+
+1. **Parse index.json** into memory
+2. **Filter/rank entries** using index metadata:
+   - Match query against title, tags, trigger
+   - Apply maturity/confidence ranking
+3. **Get top 5 matches** from index
+4. **Read only matched entries** for full content
+5. **Return results** with snippets
+
+This reduces reads from N (all entries) to 1 (index) + 5 (top matches).
+
 ### 1. Search Mode
 Input: `{ "mode": "search", "query": "<search query>" }`
 
 Process:
-1. Glob .wiki/**/*.md to find all entries
-2. Read frontmatter (title, tags, category, status, confidence, trigger)
-3. Understand query intent, handle typos/synonyms
-4. Rank by semantic relevance + confidence + maturity
+1. **Try index first**: Read `.wiki/index.json`
+   - If exists: search using index entries
+   - If missing: fall back to Glob `.wiki/**/*.md` and Read each
+2. **Understand query intent**, handle typos/synonyms
+3. **Rank by**: semantic relevance + confidence + maturity
+4. **Read top 5 full entries** for content snippets
 5. Return top 5 results with explanations
 
 ### 2. Error Lookup Mode
 Input: `{ "mode": "error-lookup", "errorText": "<error message>" }`
 
 Process:
-1. Load all entries with trigger patterns
+1. **Try index first**: Read `.wiki/index.json`
+   - If exists: filter entries with trigger patterns from index
+   - If missing: fall back to Glob+Read
 2. Match error text against triggers (regex)
 3. Prioritize high-confidence matches
-4. Return best match with solution snippet
+4. **Read best match entry** for solution snippet
+5. Return best match with solution snippet
 
 ### 3. Session Context Mode
 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 +75,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 +96,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

@@ -1,10 +1,7 @@
 ---
-description: Calculate wiki statistics, track maturity,
-  and generate analytics reports.
-tools:
-  - Glob
-  - Read
-  - Write
+name: stats
+description: Calculate wiki statistics, track maturity, and generate analytics reports.
+tools: Glob, Read, Write
 ---
 
 # Wiki Stats Agent
@@ -17,7 +14,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.
 
@@ -30,10 +27,13 @@ Calculate comprehensive wiki statistics and manage maturity tracking.
 ## Process
 
 ### Stats Report
+
+**Optimization**: If `.wiki/index.json` exists, read stats directly from index instead of scanning all files. Fall back to Glob+Read if index missing.
+
 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)
@@ -47,6 +47,28 @@ Calculate comprehensive wiki statistics and manage maturity tracking.
 2. Update frontmatter if promotion needed
 3. Log promotions
 
+### Update Index After Changes
+
+When maturity or use_count changes:
+
+1. **Read index**: Try Read `.wiki/index.json`
+   - If missing: skip index update (will be rebuilt by health agent)
+
+2. **Find entry** by path in `entries` array
+
+3. **Update fields**:
+   - `use_count`: new value
+   - `maturity`: new value if promoted
+   - `confidence`: new value if changed
+
+4. **Recalculate stats** if maturity changed:
+   - Decrement old maturity count
+   - Increment new maturity count
+
+5. **Update timestamp**: Set `updated` to current ISO timestamp
+
+6. **Write index**: Write `.wiki/index.json`
+
 ### Confidence Decay
 1. Find entries not used in 90+ days
 2. Reduce confidence by 10 (minimum 20)
@@ -61,8 +83,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