abb-opencode-local-rag 0.1.0

package/skills/mcp-local-rag/references/html-ingestion.md

@@ -0,0 +1,78 @@
+# HTML Ingestion Reference
+
+Core usage is in SKILL.md. This covers URL handling and edge cases.
+
+## System Behavior
+
+The parser extracts main content only—navigation, ads, and boilerplate are stripped. What gets indexed is clean body text, not the full HTML.
+
+## When to Use Each Source Method
+
+| Source Type | Method | Why |
+|-------------|--------|-----|
+| Static page, public | HTTP fetch | Simplest, no extra tools |
+| SPA / JS-rendered | Browser/web tool with DOM rendering | Need rendered DOM |
+| Auth required | Manual paste | Cannot fetch programmatically |
+
+**Fallback:** If HTTP fetch returns empty or minimal content, treat as SPA and retry with a browser/web tool.
+
+## URL Normalization
+
+System strips query strings and fragments:
+```
+https://example.com/page?utm=x#section → https://example.com/page
+```
+
+**When query strings matter** (pagination, dynamic IDs):
+```
+ingest_data({
+  content: page1_html,
+  metadata: { source: "https://example.com/results?page=1", format: "html" }
+})
+```
+Explicitly include full URL as source.
+
+## Edge Cases
+
+### Empty/Minimal Extraction
+
+Why it happens:
+- JS-rendered content (use browser/web tool with DOM rendering)
+- Non-standard HTML structure
+- Login required
+
+### SPA/Dynamic Content
+
+1. Use browser/web tool to render
+2. Wait for content load
+3. Extract rendered HTML
+4. Ingest via `ingest_data`
+
+### Pages with Only Navigation
+
+Skip or fetch deeper linked pages instead.
+
+## Updating Content
+
+Re-ingest with same source to replace:
+```
+ingest_data({
+  content: updated_html,
+  metadata: { source: "https://example.com/page", format: "html" }
+})
+```
+
+## Search Results
+
+Results from HTML include `source` and `fileTitle` fields:
+```json
+{
+  "filePath": "/absolute/path/to/db/raw-data/<base64url-encoded-source>.md",
+  "source": "https://example.com/page",
+  "fileTitle": "Getting Started Guide",
+  "text": "...",
+  "score": 0.25
+}
+```
+
+`filePath` is an internal path (base64url-encoded source, always `.md` extension). Use `source` to identify the content origin.

package/skills/mcp-local-rag/references/query-optimization.md

@@ -0,0 +1,57 @@
+# Query Optimization Reference
+
+Core rules are in SKILL.md. This covers patterns and edge cases.
+
+## Query Patterns by Intent
+
+| User Intent | Query Pattern | Why |
+|-------------|---------------|-----|
+| Definition/Concept | `"[term] definition concept"` | Targets explanatory content |
+| How-To/Procedure | `"[action] steps example usage"` | Targets instructional content |
+| API/Function | `"[function] API arguments return"` | Targets reference docs |
+| Troubleshooting | `"[error] fix solution cause"` | Targets problem-solving content |
+
+## Multi-Query: When to Split
+
+**Split** when "and" connects distinct topics:
+```
+"How do I authenticate AND handle errors?"
+→ Query 1: "authentication login JWT session"
+→ Query 2: "error handling exception catch"
+```
+
+**Keep one query** when "and" is within a single topic:
+```
+"How do I set up and configure the database?"
+→ Single: "database setup configuration"
+```
+
+## Query Expansion Examples
+
+When results are few or all score > 0.5:
+
+| Type | Original | Expanded |
+|------|----------|----------|
+| Synonyms | delete | "delete remove" |
+| Abbreviations | API | "API Application Programming Interface" |
+| Related terms | auth | "auth authentication login" |
+| Word forms | config | "config configuration configure" |
+
+Keep original term first. Limit to 2-4 additions.
+
+## Iterative Refinement
+
+When initial results are unsatisfactory:
+
+| Problem | Why It Happens | Action |
+|---------|----------------|--------|
+| Too few results | Term mismatch | Expand query (see above) |
+| Too many irrelevant | Query too broad | Add specific terms |
+| Missing expected | Phrasing mismatch | Try alternative wording |
+
+## Language Mixing
+
+Ngram tokenization supports cross-language queries:
+```
+"API error handling" → matches content regardless of language
+```

package/skills/mcp-local-rag/references/result-refinement.md

@@ -0,0 +1,56 @@
+# Result Refinement Reference
+
+Core rules (score, include/skip) are in SKILL.md. This covers when and how to combine multiple results.
+
+## When to Synthesize vs Filter
+
+Match approach to user intent:
+
+| User Intent | Approach | Why |
+|-------------|----------|-----|
+| Specific answer ("how to X") | Filter to 1-2 best | Extra results add noise |
+| Understanding a topic | Synthesize multiple | Builds complete picture |
+| Troubleshooting error | Filter to direct cause | Tangential info confuses |
+| Comparing options | Synthesize with structure | Need all perspectives |
+
+## Multiple Results Handling
+
+### Synthesis
+
+When: User needs comprehensive understanding.
+
+```
+Result 1: "API accepts JSON..."
+Result 2: "Auth uses Bearer tokens..."
+→ Combine into unified answer
+```
+
+### Deduplication
+
+When: Results overlap significantly.
+
+1. Pick most complete result
+2. Add only unique info from others
+
+### Contradiction Resolution
+
+When: Results conflict.
+
+Priority: Lower score (= better match)
+If unresolved → Note discrepancy to user
+
+## Chunk Context
+
+Single chunks may lack context ("as described above").
+
+- Use `fileTitle` as the chunk's document-level context—it identifies the source document's topic
+- Note when information is partial
+- Group multiple chunks from same `filePath` as coherent sections
+
+## No Results
+
+1. Rephrase query (alternative terms)
+2. Broaden scope
+3. If `scope` was passed, confirm it is an absolute path prefix — a relative prefix silently matches nothing
+4. Check ingestion (`list_files`)
+5. Inform user: no matching content