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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/.claude-plugin/marketplace.json +3 -3
  2. package/.claude-plugin/plugin.json +2 -2
  3. package/README.md +52 -48
  4. package/agents/capture.md +74 -37
  5. package/agents/duplicate-checker.md +6 -6
  6. package/agents/graph.md +24 -22
  7. package/agents/health.md +20 -16
  8. package/agents/scanner.md +28 -19
  9. package/agents/searcher.md +7 -5
  10. package/agents/stats.md +3 -4
  11. package/agents/validator.md +6 -6
  12. package/docs/README.md +21 -10
  13. package/docs/architecture.md +27 -37
  14. package/docs/diagrams/architecture-overview.md +8 -11
  15. package/docs/diagrams/data-structures.md +2 -2
  16. package/docs/diagrams/knowledge-retrieval-flow.md +1 -1
  17. package/docs/diagrams/session-workflow.md +1 -1
  18. package/docs/diagrams/system-overview.md +4 -8
  19. package/docs/getting-started.md +9 -12
  20. package/docs/plans/2025-01-22-marketplace-distribution.md +2 -0
  21. package/docs/plans/2025-01-22-solvdex-design.md +2 -0
  22. package/docs/plans/2025-02-02-generic-wiki-v3.md +747 -0
  23. package/docs/schema.md +53 -29
  24. package/docs/templates/problems.md +141 -0
  25. package/docs/templates/references.md +171 -0
  26. package/docs/templates/solutions.md +156 -0
  27. package/docs/use-cases.md +40 -93
  28. package/docs/workflows.md +19 -21
  29. package/hooks/hooks.json +3 -3
  30. package/package.json +2 -2
  31. package/skills/wiki/SKILL.md +17 -29
  32. package/skills/wiki-add/SKILL.md +27 -27
  33. package/skills/wiki-export/SKILL.md +6 -6
  34. package/skills/wiki-fix/SKILL.md +1 -1
  35. package/skills/wiki-flag/SKILL.md +1 -1
  36. package/skills/wiki-graph/SKILL.md +14 -15
  37. package/skills/wiki-health/SKILL.md +29 -12
  38. package/skills/wiki-import/SKILL.md +1 -1
  39. package/skills/wiki-init/SKILL.md +15 -26
  40. package/skills/wiki-scan/SKILL.md +4 -5
  41. package/skills/wiki-search/SKILL.md +49 -23
  42. package/skills/wiki-stats/SKILL.md +26 -30
  43. package/agents/templates/docs.md +0 -35
  44. package/agents/templates/gotchas.md +0 -31
  45. package/agents/templates/issues.md +0 -36
  46. package/agents/templates/patterns.md +0 -35
  47. package/agents/templates/performance.md +0 -36
  48. package/agents/templates/security.md +0 -36
  49. package/agents/templates/testing.md +0 -39
  50. package/docs/plans/2025-02-02-implementation-tasks.md +0 -1211
  51. package/skills/wiki-browse/SKILL.md +0 -74
  52. package/skills/wiki-capture/SKILL.md +0 -121
  53. package/skills/wiki-explorer/SKILL.md +0 -93
  54. package/skills/wiki-status/SKILL.md +0 -53
  55. package/skills/wiki-test-trigger/SKILL.md +0 -97
  56. package/skills/wiki-validate/SKILL.md +0 -61
@@ -6,7 +6,7 @@
6
6
  },
7
7
  "metadata": {
8
8
  "description": "Knowledge management plugins for Claude Code",
9
- "version": "2.0.0-alpha.8"
9
+ "version": "3.0.0-alpha.1"
10
10
  },
11
11
  "plugins": [
12
12
  {
@@ -15,8 +15,8 @@
15
15
  "source": "url",
16
16
  "url": "https://github.com/ducdmdev/solvdex.git"
17
17
  },
18
- "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
19
- "version": "2.0.0-alpha.8"
18
+ "description": "Universal problem-solving journal - auto-capture and retrieve knowledge (problems, solutions, references)",
19
+ "version": "3.0.0-alpha.1"
20
20
  }
21
21
  ]
22
22
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "solvdex",
3
- "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
4
- "version": "2.0.0-alpha.8",
3
+ "description": "Universal problem-solving journal - auto-captures and retrieves knowledge across problems, solutions, and references",
4
+ "version": "3.0.0-alpha.1",
5
5
  "author": {
6
6
  "name": "duc.do",
7
7
  "email": "ducdm.dev.work@gmail.com"
package/README.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Solvdex
2
2
 
3
3
  [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](./tests)
4
- [![Version](https://img.shields.io/badge/version-2.0.0--alpha.8-blue)](./package.json)
4
+ [![Version](https://img.shields.io/badge/version-3.0.0--alpha.1-blue)](./package.json)
5
5
  [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
6
6
  [![Architecture](https://img.shields.io/badge/architecture-pure%20agent-purple)](./docs/schema.md)
7
7
 
8
- > **An index of solved problems.** A Claude Code plugin that auto-captures and retrieves project knowledge.
8
+ > **An index of solved problems.** A personal problem-solving journal that auto-captures and retrieves knowledge across any domain.
9
9
 
10
10
  ```
11
11
  +-------------------------------------------------------------+
@@ -25,7 +25,7 @@
25
25
  |---------|-------------|
26
26
  | **Auto-Capture** | Saves solutions when errors are resolved |
27
27
  | **Auto-Lookup** | Surfaces relevant knowledge on errors |
28
- | **7 Categories** | Organized knowledge across development domains |
28
+ | **3 Folders** | Organized knowledge: problems, solutions, references |
29
29
  | **Trigger Patterns** | Regex matching for automatic error detection |
30
30
  | **Confidence Tracking** | Trust scores with decay over time |
31
31
  | **Cross-References** | Link related entries and source files |
@@ -34,16 +34,16 @@
34
34
 
35
35
  **Pure Agent Plugin - No Code Required**
36
36
 
37
- Solvdex 2.0 uses a pure agent-based architecture. All logic is implemented in agent markdown files - no TypeScript compilation needed.
37
+ 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/).
38
38
 
39
39
  > **[View Architecture Diagram](./docs/diagrams/architecture-overview.md)**
40
40
 
41
41
  | Layer | Components |
42
42
  |-------|------------|
43
- | **Skills (18)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
44
- | **Hooks** | SessionStart → wiki-advisor prompt, Stop → capture prompt |
43
+ | **Skills (12)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
44
+ | **Hooks** | SessionStart → entry count, PreToolUse → context hints, Stop → capture prompt |
45
45
  | **Agents (8)** | searcher, capture, scanner, validator, stats, health, graph, duplicate-checker |
46
- | **Storage** | `.wiki/` with 7 categories |
46
+ | **Storage** | `.wiki/` with 3 universal folders |
47
47
 
48
48
  ## Project Structure
49
49
 
@@ -57,26 +57,22 @@ solvdex/
57
57
  │ ├── stats.md
58
58
  │ ├── duplicate-checker.md
59
59
  │ ├── health.md
60
- ├── graph.md
61
- │ └── templates/ # Category templates
60
+ └── graph.md
62
61
  ├── skills/ # 18 Claude Code skills (thin wrappers)
63
62
  ├── hooks/ # hooks.json (prompt-based hints)
64
63
  ├── docs/ # Documentation
65
- └── schema.md # Entry schema & constants (source of truth)
64
+ ├── schema.md # Entry schema & constants (source of truth)
65
+ │ └── templates/ # Fixed templates per folder
66
66
  └── tests/ # Validation tests
67
67
  ```
68
68
 
69
- ## Categories
69
+ ## Folders
70
70
 
71
71
  ```
72
72
  .wiki/
73
- ├── issues/ # Bug fixes, error solutions
74
- ├── patterns/ # Reusable code patterns
75
- ├── gotchas/ # Pitfalls to avoid
76
- ├── testing/ # Test strategies, mocks
77
- ├── docs/ # Documentation guides
78
- ├── security/ # Auth, vulnerabilities
79
- └── performance/ # Optimizations, benchmarks
73
+ ├── problems/ # What went wrong - bugs, errors, gotchas
74
+ ├── solutions/ # How to fix/do things - patterns, recipes
75
+ └── references/ # Things to remember - docs, configs
80
76
  ```
81
77
 
82
78
  ## Quick Start
@@ -89,10 +85,10 @@ solvdex/
89
85
  /wiki search "database timeout"
90
86
 
91
87
  # Add current solution
92
- /wiki add --category=issues
88
+ /wiki add --folder=problems
93
89
 
94
- # Browse entries
95
- /wiki browse
90
+ # Browse all entries
91
+ /wiki search
96
92
  ```
97
93
 
98
94
  ## Commands
@@ -102,30 +98,26 @@ solvdex/
102
98
  | Command | Description |
103
99
  |---------|-------------|
104
100
  | `/wiki init` | Create `.wiki/` structure |
105
- | `/wiki add` | Save current solution |
106
- | `/wiki search <query>` | Full-text search |
107
- | `/wiki browse` | List entries with filters |
101
+ | `/wiki add` | Capture knowledge from conversation |
102
+ | `/wiki search [query]` | Search or browse entries (no query = list all) |
108
103
 
109
- ### Management Commands
104
+ ### Analysis Commands
110
105
 
111
106
  | Command | Description |
112
107
  |---------|-------------|
113
- | `/wiki status` | Quick health overview |
114
- | `/wiki stats` | Detailed analytics |
115
- | `/wiki validate` | Check for issues |
108
+ | `/wiki stats [--quick]` | Statistics and health score |
109
+ | `/wiki health [--validate]` | Health analysis with validation |
116
110
  | `/wiki scan` | Generate stubs from project |
117
- | `/wiki flag <entry>` | Mark for review |
118
- | `/wiki fix <entry>` | Update flagged entry |
119
- | `/wiki health` | Coverage gaps and health analysis |
120
111
  | `/wiki graph` | Relationship diagrams |
121
112
 
122
- ### Transfer Commands
113
+ ### Entry Management
123
114
 
124
115
  | Command | Description |
125
116
  |---------|-------------|
117
+ | `/wiki flag <entry>` | Mark for review |
118
+ | `/wiki fix <entry>` | Update flagged entry |
126
119
  | `/wiki export [file]` | Export to JSON |
127
120
  | `/wiki import <file>` | Import from JSON |
128
- | `/wiki test-trigger` | Test regex patterns |
129
121
 
130
122
  ### Agents
131
123
 
@@ -133,14 +125,14 @@ All logic is implemented by specialized agents:
133
125
 
134
126
  | Agent | Commands | Description |
135
127
  |-------|----------|-------------|
136
- | `searcher` | `/wiki search`, `/wiki explore` | Search + recommendations |
137
- | `capture` | `/wiki add`, `/wiki capture` | Knowledge extraction |
128
+ | `searcher` | `/wiki search` | Search + browse |
129
+ | `capture` | `/wiki add`, `/wiki fix` | Knowledge extraction |
138
130
  | `scanner` | `/wiki scan` | Project scanning |
139
- | `validator` | `/wiki validate` | Quality checks |
131
+ | `validator` | `/wiki flag` | Quality checks |
140
132
  | `stats` | `/wiki stats` | Analytics + maturity |
141
- | `duplicate-checker` | (internal) | Prevent duplicates |
142
- | `health` | `/wiki health` | Coverage gaps |
133
+ | `health` | `/wiki health` | Coverage gaps + validation |
143
134
  | `graph` | `/wiki graph` | Relationship diagrams |
135
+ | `duplicate-checker` | (internal) | Prevent duplicates |
144
136
 
145
137
  ## How It Works
146
138
 
@@ -153,9 +145,9 @@ All logic is implemented by specialized agents:
153
145
  +--------------+ +--------------+ +--------------+
154
146
 
155
147
  Signals detected:
156
- - error_resolved -> issues/
157
- - workaround -> gotchas/
158
- - user confirms -> auto-detect category
148
+ - error_resolved -> problems/
149
+ - workaround -> solutions/
150
+ - user confirms -> auto-detect folder
159
151
  - explicit save -> "remember this"
160
152
  ```
161
153
 
@@ -170,7 +162,7 @@ Signals detected:
170
162
  Lookup triggers:
171
163
  - Session start -> relevant context
172
164
  - Error match -> trigger patterns
173
- - Prompt keywords -> category detection
165
+ - Prompt keywords -> folder detection
174
166
  ```
175
167
 
176
168
  ## Entry Format
@@ -179,10 +171,20 @@ Lookup triggers:
179
171
  ---
180
172
  title: Database Connection Timeout
181
173
  created: 2025-01-20
174
+ updated: 2025-01-20
182
175
  status: active
183
176
  confidence: 85
177
+ maturity: verified
184
178
  tags: [database, timeout, postgres]
185
179
  trigger: "ETIMEDOUT.*postgres"
180
+ use_count: 5
181
+ last_used: 2025-01-20
182
+ related_entries:
183
+ - .wiki/solutions/connection-pool-config.md
184
+ audit:
185
+ - date: 2025-01-20
186
+ action: created
187
+ by: user
186
188
  ---
187
189
 
188
190
  ## Problem
@@ -192,11 +194,11 @@ Connection times out after 30 seconds...
192
194
  Increase timeout and add connection pool...
193
195
 
194
196
  ## Related
195
- - [[issues/connection-pool]]
197
+ - [[solutions/connection-pool-config]]
196
198
  - `src/db/config.ts:45`
197
199
  ```
198
200
 
199
- > **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md).
201
+ > **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/).
200
202
 
201
203
  ### Entry Maturity System
202
204
 
@@ -235,10 +237,11 @@ Confidence auto-decays for entries unused for 90+ days.
235
237
 
236
238
  Real-time integration with Claude Code via contextual prompts:
237
239
 
238
- | Hook | Suggests | When | Purpose |
239
- |------|----------|------|---------|
240
- | `SessionStart` | `wiki-advisor` | New conversation | Hint to check for relevant entries |
241
- | `Stop` | `capture` | Task completes | Hint to capture valuable knowledge |
240
+ | Hook | When | Purpose |
241
+ |------|------|---------|
242
+ | `SessionStart` | New conversation | Shows entry count, hints to use `/wiki search` |
243
+ | `PreToolUse` | Before Edit/Write | Shows problems/solutions count for context |
244
+ | `Stop` | Task completes | Hint to capture valuable knowledge |
242
245
 
243
246
  Hooks are configured in `hooks/hooks.json` and provide prompt-based guidance to use wiki agents.
244
247
 
@@ -272,6 +275,7 @@ npm run test:watch # Watch mode
272
275
  | Document | Description |
273
276
  |----------|-------------|
274
277
  | [Schema Reference](./docs/schema.md) | Entry schema & constants (source of truth) |
278
+ | [Entry Templates](./docs/templates/) | Fixed templates per folder |
275
279
  | [Getting Started](./docs/getting-started.md) | Quick setup guide |
276
280
  | [Architecture](./docs/architecture.md) | System design |
277
281
  | [Workflows](./docs/workflows.md) | Hook and skill flows |
package/agents/capture.md CHANGED
@@ -14,10 +14,11 @@ tools:
14
14
  For entry structure, validation rules, and constants, see: `docs/schema.md`
15
15
 
16
16
  Key references:
17
- - Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
17
+ - Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
18
18
  - Maturity rules: `docs/schema.md#maturity-rules`
19
- - Confidence levels: `docs/schema.md#confidence-levels`
20
- - Categories: `docs/schema.md#default-categories`
19
+ - Confidence levels: `docs/schema.md#confidence-constants`
20
+ - Folders: `docs/schema.md#default-folders`
21
+ - Entry Templates: `docs/templates/` (problems.md, solutions.md, references.md)
21
22
 
22
23
  Intelligently extract problem and solution from conversation context to create a wiki entry.
23
24
 
@@ -30,7 +31,7 @@ You will receive conversation context containing:
30
31
 
31
32
  Optional parameters:
32
33
  - `mode: "auto-capture"` - Auto-capture from conversation (hook)
33
- - `category: "<category>"` - Force specific category
34
+ - `folder: "<folder>"` - Force specific folder (problems, solutions, references)
34
35
  - `title: "<title>"` - Force specific title
35
36
 
36
37
  ## Process
@@ -58,9 +59,9 @@ Include relevant code snippets (max 20 lines).
58
59
 
59
60
  **IMPORTANT: Always check before creating!**
60
61
 
61
- 1. Search existing entries in detected category:
62
+ 1. Search existing entries in detected folder:
62
63
  ```
63
- Glob .wiki/<category>/*.md
64
+ Glob .wiki/<folder>/*.md
64
65
  ```
65
66
 
66
67
  2. Compare semantically:
@@ -70,29 +71,29 @@ Include relevant code snippets (max 20 lines).
70
71
 
71
72
  3. If >80% similarity found:
72
73
  ```
73
- Similar entry exists: category/existing-entry.md
74
- Consider updating it instead: /wiki fix category/existing-entry.md
74
+ Similar entry exists: folder/existing-entry.md
75
+ Consider updating it instead: /wiki fix folder/existing-entry.md
75
76
  ```
76
77
  Do NOT create new entry.
77
78
 
78
79
  4. If 50-79% similarity:
79
80
  ```
80
- Related entry found: category/related-entry.md
81
+ Related entry found: folder/related-entry.md
81
82
  Creating new entry and linking to related.
82
83
  ```
83
84
  Create entry with `related_entries` field.
84
85
 
85
- ### Step 4: Determine Category
86
+ ### Step 4: Determine Folder
86
87
 
87
- | Keywords/Context | Category |
88
- |------------------|----------|
89
- | Error, Exception, bug, fix, crash | issues |
90
- | Pattern, approach, template, design | patterns |
91
- | Warning, pitfall, gotcha, careful, avoid | gotchas |
92
- | Test, mock, assert, spec, fixture | testing |
93
- | Auth, permission, token, secret, security | security |
94
- | Slow, optimize, cache, memory, performance | performance |
95
- | Doc, readme, guide, documentation | docs |
88
+ Analyze content to determine the appropriate folder:
89
+
90
+ | Content Analysis | Folder |
91
+ |------------------|--------|
92
+ | Problem encountered, error, failure, blocker, bug, crash, exception, pitfall, gotcha, warning, careful, avoid, security issue | problems/ |
93
+ | How-to, procedure, recipe, pattern, template, approach, optimization, test strategy, workflow, steps to do something | solutions/ |
94
+ | Documentation, reference, config, link, guide, API docs, notes, information to remember | references/ |
95
+
96
+ **AI decides automatically.** If genuinely uncertain (>30% confidence in multiple folders), default to `problems/` for issues or `references/` for informational content.
96
97
 
97
98
  ### Step 5: Generate Tags
98
99
 
@@ -119,34 +120,70 @@ Create a concise, descriptive title:
119
120
  - Include technology: "TypeScript Generic Constraint Issue"
120
121
  - Max 60 characters
121
122
 
122
- ### Step 7: Create Entry Using Template
123
+ ### Step 7: Create Entry Using Fixed Template
123
124
 
124
- 1. Read template for detected category:
125
- ```
126
- Read agents/templates/<category>.md
127
- ```
125
+ **Use the fixed template for the target folder.** See `docs/templates/` for full templates.
126
+
127
+ 1. **Select template** based on folder:
128
+
129
+ | Folder | Template Sections |
130
+ |--------|-------------------|
131
+ | `problems/` | Problem, Cause, Solution, Prevention, Related |
132
+ | `solutions/` | Overview, Prerequisites, Steps, Example, Related |
133
+ | `references/` | Summary, Details, Links, Related |
134
+
135
+ 2. **Fill frontmatter**:
136
+
137
+ ```yaml
138
+ ---
139
+ title: {{generated_title}}
140
+ created: {{today YYYY-MM-DD}}
141
+ updated: {{today YYYY-MM-DD}}
142
+ status: active
143
+ confidence: 40
144
+ maturity: captured
145
+ tags: [{{extracted_tags}}]
146
+ trigger: "{{error_regex}}" # problems/ only
147
+ source: capture-agent
148
+ use_count: 0
149
+ audit:
150
+ - date: {{today YYYY-MM-DD}}
151
+ action: created
152
+ by: capture-agent
153
+ ---
154
+ ```
155
+
156
+ 3. **Fill template sections** with extracted content:
157
+
158
+ **For problems/**:
159
+ - Problem: The error or issue encountered
160
+ - Cause: Root cause analysis
161
+ - Solution: Fix steps or code
162
+ - Prevention: How to avoid in future
163
+
164
+ **For solutions/**:
165
+ - Overview: What this does and when to use
166
+ - Prerequisites: What's needed first
167
+ - Steps: Numbered procedure
168
+ - Example: Code or config sample
128
169
 
129
- 2. Replace placeholders with extracted values:
130
- - `{{title}}` generated title
131
- - `{{created}}` today's date (YYYY-MM-DD)
132
- - `{{updated}}` today's date (YYYY-MM-DD)
133
- - `{{tags}}` → comma-separated tags
134
- - `{{trigger}}` → error regex pattern (issues/security/performance only)
135
- - `{{source}}` → "conversation" or "capture-agent"
136
- - `{{created_by}}` → "capture-agent"
137
- - Section placeholders → extracted content
170
+ **For references/**:
171
+ - Summary: Brief description
172
+ - Details: Information to remember
173
+ - Links: External resources
138
174
 
139
- 3. Write filled template to `.wiki/<category>/<slug>.md`
175
+ 4. **Write to** `.wiki/<folder>/<slug>.md`
140
176
 
141
177
  ### Step 8: Return Confirmation
142
178
 
143
179
  ```
144
- Captured: category/entry-name.md
180
+ Captured: folder/entry-name.md
145
181
  Title: Entry Title
182
+ Folder: problems | solutions | references
146
183
  Tags: tag1, tag2, tag3
147
184
  Confidence: 40 (captured)
148
185
 
149
- Edit: /wiki fix category/entry-name.md
186
+ Edit: /wiki fix folder/entry-name.md
150
187
  ```
151
188
 
152
189
  ## Important Rules
@@ -156,5 +193,5 @@ Captured: category/entry-name.md
156
193
  3. **Include code** - solutions need concrete examples
157
194
  4. **Keep it concise** - problem/solution should be scannable
158
195
  5. **Set confidence 40** - captured entries start at maturity baseline
159
- 6. **Add trigger patterns** - for issues category, extract regex
196
+ 6. **Add trigger patterns** - for problems folder, extract regex
160
197
  7. **Link related entries** - build the knowledge graph
@@ -16,7 +16,7 @@ Key references:
16
16
  - Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
17
17
  - Maturity rules: `docs/schema.md#maturity-rules`
18
18
  - Confidence levels: `docs/schema.md#confidence-levels`
19
- - Categories: `docs/schema.md#default-categories`
19
+ - Folders: `docs/schema.md#default-folders`
20
20
 
21
21
  Detect potential duplicate entries before creation.
22
22
 
@@ -26,14 +26,14 @@ Detect potential duplicate entries before creation.
26
26
  {
27
27
  "title": "Database Connection Timeout",
28
28
  "tags": ["database", "timeout", "postgres"],
29
- "category": "issues",
29
+ "folder": "problems",
30
30
  "contentSummary": "Fix for connection pool exhaustion..."
31
31
  }
32
32
  ```
33
33
 
34
34
  ## Process
35
35
 
36
- 1. Load existing entries in same category
36
+ 1. Load existing entries in same folder
37
37
  2. Compare semantically:
38
38
  - Title similarity (exact, partial, synonym)
39
39
  - Tag overlap (Jaccard similarity)
@@ -48,7 +48,7 @@ Detect potential duplicate entries before creation.
48
48
  {
49
49
  "isDuplicate": true,
50
50
  "similarity": 85,
51
- "matchedEntry": "issues/db-timeout.md",
51
+ "matchedEntry": "problems/db-timeout.md",
52
52
  "matchedTitle": "Database Timeout Fix",
53
53
  "reason": "Very similar title and tags",
54
54
  "suggestion": "Consider updating existing entry instead"
@@ -60,7 +60,7 @@ Detect potential duplicate entries before creation.
60
60
  {
61
61
  "isDuplicate": false,
62
62
  "similarity": 20,
63
- "closestMatch": "issues/connection-error.md",
63
+ "closestMatch": "problems/connection-error.md",
64
64
  "suggestion": "Safe to create new entry"
65
65
  }
66
66
  ```
@@ -94,5 +94,5 @@ Detect potential duplicate entries before creation.
94
94
 
95
95
  1. Be conservative - prefer false positives over duplicates
96
96
  2. Consider synonyms (e.g., "timeout" ≈ "connection timeout")
97
- 3. Same category increases likelihood
97
+ 3. Same folder increases likelihood
98
98
  4. Different maturity levels can coexist (stub vs detailed)
package/agents/graph.md CHANGED
@@ -12,17 +12,17 @@ Generate visual relationship diagrams for wiki entries.
12
12
  ## Input
13
13
 
14
14
  - `{ "full": true }` - All entries
15
- - `{ "category": "issues" }` - Single category
16
- - `{ "entry": "issues/db-timeout.md" }` - Single entry and its relations
15
+ - `{ "folder": "problems" }` - Single folder
16
+ - `{ "entry": "problems/db-timeout.md" }` - Single entry and its relations
17
17
 
18
18
  ## Process
19
19
 
20
20
  1. Load entries (all or filtered)
21
21
  2. Extract relationships:
22
22
  - **Explicit**: `related_entries` field
23
- - **Wiki links**: `[[category/entry]]` in content
23
+ - **Wiki links**: `[[folder/entry]]` in content
24
24
  - **Tag overlap**: 2+ shared tags
25
- - **Same category**: Weak connection
25
+ - **Same folder**: Weak connection
26
26
  3. Generate Mermaid diagram
27
27
 
28
28
  ## Output Format
@@ -30,32 +30,34 @@ Generate visual relationship diagrams for wiki entries.
30
30
  ### Full Graph
31
31
  ```mermaid
32
32
  graph LR
33
- subgraph issues
34
- I1[DB Timeout]
35
- I2[Auth Error]
36
- I3[API Failure]
33
+ subgraph problems
34
+ P1[DB Timeout]
35
+ P2[Auth Error]
36
+ P3[Connection Pool Gotcha]
37
37
  end
38
38
 
39
- subgraph patterns
40
- P1[Retry Pattern]
41
- P2[Circuit Breaker]
39
+ subgraph solutions
40
+ S1[Retry Pattern]
41
+ S2[Circuit Breaker]
42
+ S3[Pool Config]
42
43
  end
43
44
 
44
- subgraph gotchas
45
- G1[Connection Pool]
45
+ subgraph references
46
+ R1[API Docs]
47
+ R2[Config Guide]
46
48
  end
47
49
 
48
- I1 -->|related| P1
49
- I1 -->|related| G1
50
- I2 -->|same-tag: auth| P2
51
- I3 -->|wiki-link| P1
52
- P1 -.->|same-category| P2
50
+ P1 -->|related| S1
51
+ P1 -->|related| P3
52
+ P2 -->|same-tag: auth| S2
53
+ S1 -.->|same-folder| S2
54
+ P3 -->|wiki-link| S3
53
55
  ```
54
56
 
55
- ### Category Graph
57
+ ### Folder Graph
56
58
  ```mermaid
57
59
  graph TD
58
- subgraph issues
60
+ subgraph problems
59
61
  A[DB Timeout]
60
62
  B[Auth Error]
61
63
  C[API Failure]
@@ -84,7 +86,7 @@ graph TD
84
86
  | related | `-->` solid | Explicit related_entries |
85
87
  | wiki-link | `-->` solid | [[link]] in content |
86
88
  | same-tag | `-->` labeled | 2+ shared tags |
87
- | same-category | `-.->` dashed | Same category |
89
+ | same-folder | `-.->` dashed | Same folder |
88
90
 
89
91
  ## Node Styling
90
92
 
@@ -101,5 +103,5 @@ Based on confidence:
101
103
  ## Graph Limits
102
104
 
103
105
  - Full graph: Max 50 entries (summarize if more)
104
- - Category: Max 20 entries
106
+ - Folder: Max 20 entries
105
107
  - Entry focus: Max 2 levels deep
package/agents/health.md CHANGED
@@ -16,7 +16,7 @@ Key references:
16
16
  - Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
17
17
  - Maturity rules: `docs/schema.md#maturity-rules`
18
18
  - Confidence levels: `docs/schema.md#confidence-levels`
19
- - Categories: `docs/schema.md#default-categories`
19
+ - Folders: `docs/schema.md#default-folders`
20
20
 
21
21
  Comprehensive wiki health analysis and recommendations.
22
22
 
@@ -31,7 +31,7 @@ Comprehensive wiki health analysis and recommendations.
31
31
  - Orphaned: No tags, no related entries
32
32
  - Broken links: [[link]] to non-existent entry
33
33
  3. **Find coverage gaps**:
34
- - Categories with < 3 entries
34
+ - Folders with < 3 entries
35
35
  - Common error patterns without entries
36
36
  4. **Generate recommendations**
37
37
 
@@ -45,29 +45,28 @@ Comprehensive wiki health analysis and recommendations.
45
45
  ## Issues Found
46
46
 
47
47
  ### Stale Entries (5)
48
- - patterns/old-api.md (120 days)
49
- - issues/legacy-auth.md (95 days)
48
+ - solutions/old-api.md (120 days)
49
+ - problems/legacy-auth.md (95 days)
50
50
  → Consider reviewing or deprecating
51
51
 
52
52
  ### Stub Entries (3)
53
- - issues/api-timeout.md - Missing Solution
54
- - gotchas/edge-case.md - Missing Problem
53
+ - problems/api-timeout.md - Missing Solution
54
+ - problems/edge-case.md - Missing Problem
55
55
  → Run /wiki fix <entry> to complete
56
56
 
57
57
  ### Low Confidence (4)
58
- - patterns/untested.md (confidence: 30)
58
+ - solutions/untested.md (confidence: 30)
59
59
  → Verify and increase confidence
60
60
 
61
61
  ### Missing Triggers (2)
62
- - issues/db-error.md
63
- - issues/auth-fail.md
62
+ - problems/db-error.md
63
+ - problems/auth-fail.md
64
64
  → Add trigger patterns for auto-matching
65
65
 
66
66
  ## Coverage Gaps
67
67
 
68
- ### Underserved Categories
69
- - security: 1 entry (recommend: 3+)
70
- - performance: 2 entries (recommend: 3+)
68
+ ### Underserved Folders
69
+ - references: 1 entry (recommend: 2+)
71
70
 
72
71
  ### Suggested Entries
73
72
  Based on common errors, consider adding:
@@ -79,8 +78,8 @@ Based on common errors, consider adding:
79
78
 
80
79
  1. Review 5 stale entries
81
80
  2. Complete 3 stub entries
82
- 3. Add triggers to 2 issues
83
- 4. Expand security category
81
+ 3. Add triggers to 2 problems
82
+ 4. Expand references folder
84
83
  ```
85
84
 
86
85
  ## Health Indicators
@@ -102,12 +101,17 @@ Based on common errors, consider adding:
102
101
 
103
102
  ## Coverage Analysis
104
103
 
105
- For each category:
104
+ For each folder:
106
105
  1. Count entries
107
106
  2. Compare to minimum (3)
108
107
  3. Flag if under-served
109
108
 
110
- Recommend expanding categories with:
109
+ Recommend expanding folders with:
111
110
  - High error rates in project
112
111
  - Recent user questions
113
112
  - Common patterns in codebase
113
+
114
+ ### Minimum Recommendations
115
+ - problems: 3+ entries
116
+ - solutions: 3+ entries
117
+ - references: 2+ entries