gemiterm 2.0.0

package/.opencode/skills/intellisearch/references/deepwiki-tools.md

@@ -0,0 +1,246 @@
+# DeepWiki Tools Reference
+
+Complete reference for DeepWiki MCP server tools for repository documentation Q&A.
+
+## MCP Configuration Requirement
+
+DeepWiki MCP tools require configuration in `.opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "deepwiki": {
+      "type": "remote",
+      "url": "https://mcp.deepwiki.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+<critical_rules priority="highest">
+<rule>Validate repo name against blocked list before calling</rule>
+<rule>Use string for single repo: `repoName="owner/repo"`</rule>
+<rule>Use array for multiple repos: `repoName=["owner1/repo1", "owner2/repo2"]` (2+ items)</rule>
+<rule>NEVER use single-item array: `repoName=["owner/repo"]` (causes failure)</rule>
+<rule>If deepwiki tools aren't available, use direct HTTP calls via `curl`. See Fallback section below.</rule>
+<rule>"OpenCode" never refers to the archived and deprecated "opencode-ai/opencode" github repo. "OpenCode" always refers to "anomalyco/opencode" owned by "anomalyco" in github.</rule>
+</critical_rules>
+
+## Fallback: Missing DeepWiki MCP
+
+When MCP tools are not configured, use direct HTTP calls via curl:
+
+### ask_question
+
+<bash_command name="ask_question">
+```bash
+curl -s -X POST https://mcp.deepwiki.com/mcp \
+-H "Content-Type: application/json" \
+-H "Accept: application/json, text/event-stream" \
+-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "ask_question", "arguments": {"repoName": "OWNER/REPO", "question": "YOUR_QUESTION"}}}' | grep -oP '(?<="text":")[^"]*' | sed 's/\\n/\n/g'
+```
+</bash_command>
+
+### read_wiki_structure
+
+<bash_command name="read_wiki_structure">
+```bash
+curl -s -X POST https://mcp.deepwiki.com/mcp \
+-H "Content-Type: application/json" \
+-H "Accept: application/json, text/event-stream" \
+-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "read_wiki_structure", "arguments": {"repoName": "OWNER/REPO"}}}' | grep -oP '(?<="text":")[^"]*' | sed 's/\\n/\n/g'
+```
+</bash_command>
+
+### read_wiki_contents
+
+<bash_command name="read_wiki_contents">
+```bash
+curl -s -X POST https://mcp.deepwiki.com/mcp \
+-H "Content-Type: application/json" \
+-H "Accept: application/json, text/event-stream" \
+-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "read_wiki_contents", "arguments": {"repoName": "OWNER/REPO"}}}' | grep -oP '(?<="text":")[^"]*' | sed 's/\\n/\n/g'
+```
+</bash_command>
+
+### Critical Notes for Fallback Execution
+
+<fallback_notes>
+- **Argument Key**: Always use `repoName` (not `repo`)
+- **Headers**: The `Accept` header must include `text/event-stream` or the server will reject the request
+- **Output Parsing**: The `grep` and `sed` suffix is useful to extract clean text from the JSON-RPC stream but may sometimes need to be omitted.
+</fallback_notes>
+
+## Repository Name Validation
+
+Before calling DeepWiki, validate that the repository name is legitimate and not a GitHub website path.
+
+### Blocked First Segments
+
+<blocked_owners>
+Reject any `owner/repo` where the owner (first segment) matches these:
+
+```
+about, accelerator, apps, archiveprogram, blog, careers, changelog,
+collections, community, contact, customer-stories, docs, enterprise,
+events, explore, features, gist, github, github-apps, issues, login,
+maintainers, marketplace, mcp, notifications, oauth-apps, orgs,
+organizations, password_reset, press, pricing, pull_requests, pulls,
+resources, security, securitylab, sessions, settings, site-policy,
+skills, solutions, sponsors, support, team, topics, trending,
+trust-center, whitepapers, why-github
+```
+</blocked_owners>
+
+### Validation Rules
+
+| Check | Rule | Example |
+|-------|------|---------|
+| Owner format | Alphanumeric, `-`, `_` only | `npm`, `node-js` ✅ |
+| Repo format | Alphanumeric, `-`, `_`, `.` only | `node-semver`, `lib.js` ✅ |
+| Not blocked | Owner not in blocked list | `npm/node-semver` ✅ |
+| Blocked path | Owner in blocked list | `features/spark` ❌ |
+
+### Examples
+
+| Input | Verdict | Reason |
+|-------|---------|--------|
+| `npm/node-semver` | ✅ Valid | `npm` not blocked |
+| `graphology/graphology` | ✅ Valid | `graphology` not blocked |
+| `features/spark` | ❌ Invalid | `features` is GitHub product page |
+| `topics/database` | ❌ Invalid | `topics` is GitHub topic page |
+| `enterprise/startups` | ❌ Invalid | `enterprise` is GitHub marketing |
+| `resources/articles` | ❌ Invalid | `resources` is GitHub content |
+| `github/explore` | ❌ Invalid | `github` is org page, not repo |
+| `site-policy/terms` | ❌ Invalid | `site-policy` is GitHub legal |
+| `orgs/community` | ❌ Invalid | `orgs` is GitHub navigation |
+
+## Available Tools
+
+### deepWiki_read_wiki_structure
+
+<tool name="deepWiki_read_wiki_structure">
+<params>
+- `repoName` (required): Repository in `owner/repo` format
+</params>
+<returns>List of available documentation sections and topics</returns>
+<use_when>Exploring what documentation is available before asking specific questions</use_when>
+</tool>
+
+### deepWiki_read_wiki_contents
+
+<tool name="deepWiki_read_wiki_contents">
+<params>
+- `repoName` (required): Repository in `owner/repo` format
+</params>
+<returns>Complete documentation content</returns>
+<use_when>You need comprehensive documentation overview or when `ask_question` doesn't provide enough detail</use_when>
+</tool>
+
+### deepWiki_ask_question
+
+<tool name="deepWiki_ask_question">
+<params>
+- `repoName` (required): Repository in `owner/repo` format
+  - **Single repo**: Use string: `"owner/repo"`
+  - **Multiple repos**: Use array: `["owner1/repo1", "owner2/repo2"]`
+  - **Critical**: Do not pass single-item array like `["owner/repo"]` for one repo
+- `question` (required): Specific question about the repository
+</params>
+<returns>Targeted answer based on repository documentation</returns>
+<use_when>You have a specific question and want a direct answer</use_when>
+</tool>
+
+<format_rules>
+- Single repository: `repoName="anomalyco/opencode"`
+- Multiple repositories: `repoName=["anomalyco/opencode", "vercel/next.js"]`
+- ❌ Wrong: `repoName=["anomalyco/opencode"]` (single-item array causes search failure)
+</format_rules>
+
+## When to Use DeepWiki
+
+<use_cases>
+- Query is about a **specific GitHub repository**
+- You need **authoritative code answers** (from official docs)
+- The question involves **implementation details** of a library/framework
+- You want **installation/setup instructions** for a specific tool
+- The query is about **API usage patterns** for a known package
+</use_cases>
+
+## repoName Format
+
+Always use `owner/repo` format:
+
+| Repository | Correct | Incorrect |
+|------------|---------|-----------|
+| React | `facebook/react` | `react`, `React` |
+| Next.js | `vercel/next.js` | `nextjs`, `next` |
+| TypeScript | `microsoft/TypeScript` | `typescript`, `ts` |
+| Vue | `vuejs/core` | `vue`, `Vue.js` |
+
+## Example Workflows
+
+### Getting Started with a Library
+
+```json
+// Step 1: Check documentation structure
+{
+  "tool": "deepwiki:deepWiki_read_wiki_structure",
+  "params": {
+    "repoName": "vercel/next.js"
+  }
+}
+
+// Step 2: Ask specific question
+{
+  "tool": "deepwiki:deepWiki_ask_question",
+  "params": {
+    "repoName": "vercel/next.js",
+    "question": "How do I create a dynamic route with parameters?"
+  }
+}
+```
+
+### Troubleshooting
+
+```json
+{
+  "tool": "deepwiki:deepWiki_ask_question",
+  "params": {
+    "repoName": "facebook/react",
+    "question": "Why am I getting the 'rules of hooks' warning?"
+  }
+}
+```
+
+### Installation Questions
+
+```json
+{
+  "tool": "deepwiki:deepWiki_ask_question",
+  "params": {
+    "repoName": "tailwindlabs/tailwindcss",
+    "question": "How do I install and configure Tailwind with Vite?"
+  }
+}
+```
+
+## Best Practices
+
+<best_practices>
+1. **Validate repo name** against blocked list before calling
+2. **Use `ask_question`** for specific queries (most efficient)
+3. **Use `read_wiki_contents`** only when you need the full documentation
+4. **Check `read_wiki_structure`** first when exploring unfamiliar repos
+5. **Use string for single repo, array for multiple repos** in `repoName` parameter
+</best_practices>
+
+## Limitations
+
+<limitations>
+- Only works for **public GitHub repositories**
+- Documentation must be **indexed by DeepWiki**
+- Very new or obscure repos may not be available
+- Cannot access private repositories
+</limitations>

package/.opencode/skills/intellisearch/references/examples.md

@@ -0,0 +1,97 @@
+# Few-Shot Examples
+
+Real-world patterns for IntelliSearch skill execution.
+
+## Example 1: Library Discovery
+
+**Query:** "Find a TypeScript library for semantic versioning validation"
+
+<execution>
+<step name="search" tool="gh search repos">
+CMD: `gh search repos "semver validation typescript" --language=typescript --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10`
+RESULT: [npm/node-semver: 4.5K★, mattfarina/semver: 892★, ...]
+</step>
+
+<step name="filter" action="Top 3 by stars">
+SELECTED: [npm/node-semver, mattfarina/semver, ieee802js/node-semver]
+</step>
+
+<step name="query" tool="DeepWiki_ask_question">
+PAYLOAD: {
+  repoName: ["npm/node-semver", "mattfarina/semver", "ieee802js/node-semver"],
+  question: "Which is best for TypeScript semver validation?"
+}
+</step>
+
+<step name="synthesize">
+OUTPUT: npm/node-semver recommended (most stars, active maintenance, TypeScript typings included)
+</step>
+</execution>
+
+---
+
+## Example 2: Framework Comparison
+
+**Query:** "Compare React state management libraries: Zustand vs Jotai vs Valtio"
+
+<execution>
+<step name="search" tool="gh search repos (parallel)">
+CMDS:
+- `gh search repos "zustand" --json fullName,stargazersCount,createdAt,updatedAt --limit 5`
+- `gh search repos "jotai" --json fullName,stargazersCount,createdAt,updatedAt --limit 5`
+- `gh search repos "valtio" --json fullName,stargazersCount,createdAt,updatedAt --limit 5`
+RESULT: [pmndrs/zustand: 47K★, pmndrs/jotai: 18K★, pmndrs/valtio: 7K★]
+</step>
+
+<step name="filter" action="Exact matches only">
+SELECTED: [pmndrs/zustand, pmndrs/jotai, pmndrs/valtio]
+</step>
+
+<step name="query" tool="DeepWiki_ask_question">
+PAYLOAD: {
+  repoName: ["pmndrs/zustand", "pmndrs/jotai", "pmndrs/valtio"],
+  question: "Compare these React state management libraries: API design, performance, bundle size, learning curve"
+}
+</step>
+
+<step name="synthesize">
+OUTPUT: Zustand (simplest API, largest), Jotai (atomic, smallest), Valtio (proxy-based, mutable patterns)
+</step>
+</execution>
+
+---
+
+## Example 3: Fallback Chain
+
+**Query:** "Is there a browser-based WebGL physics engine?"
+
+<execution>
+<step name="search" tool="gh search repos" status="failed">
+CMD: `gh search repos "webgl physics engine browser" --language=javascript --limit 10`
+ERROR: gh CLI not authenticated
+</step>
+
+<step name="fallback" tool="google_search">
+PAYLOAD: {query: "webgl physics engine javascript npm github"}
+RESULT: Snippets mentioning cannon-es, ammo.js, Oimo.js
+</step>
+
+<step name="extract" action="owner/repo patterns">
+EXTRACTED: [pmndrs/cannon-es, kripken/ammo.js, lo-th/Oimo.js]
+</step>
+
+<step name="filter" action="Top 3 by relevance">
+SELECTED: [pmndrs/cannon-es, kripken/ammo.js, lo-th/Oimo.js]
+</step>
+
+<step name="query" tool="DeepWiki_ask_question">
+PAYLOAD: {
+  repoName: ["pmndrs/cannon-es", "kripken/ammo.js", "lo-th/Oimo.js"],
+  question: "Which is best for browser WebGL physics with Three.js integration?"
+}
+</step>
+
+<step name="synthesize">
+OUTPUT: cannon-es recommended (ES modules, maintained fork of cannon.js, Three.js examples available)
+</step>
+</execution>

package/.opencode/skills/intellisearch/references/gh-cli.md

@@ -0,0 +1,143 @@
+# GitHub CLI Search
+
+Using `gh` CLI for direct GitHub repository search.
+
+<detection>
+```bash
+gh auth status
+```
+- Exit code 0: gh is available and authenticated
+- Exit code non-zero: gh not available or not authenticated
+</detection>
+
+## Search Command
+
+```bash
+gh search repos [query] [flags]
+```
+
+## Query Strategy
+
+<approach>
+1. **Topics + Language** (preferred when topics identifiable)
+2. **Keywords only** (fallback)
+</approach>
+
+<topic_detection>
+Infer topics from user query context:
+- Framework names → topics (react, vue, express)
+- Library names → topics (lodash, axios, moment)
+- Concepts → topics (semver, validation, authentication)
+</topic_detection>
+
+<language_inference>
+Extract programming language from:
+- Explicit mention: "in TypeScript", "Python library"
+- File extensions: ".ts", ".py", ".go"
+- Context: "npm package" → JavaScript/TypeScript
+</language_inference>
+
+## Examples
+
+<examples>
+<example category="topic_language">
+```bash
+# Query: "semver validation in TypeScript"
+gh search repos --topic=semver,validation --language=typescript --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+```
+</example>
+
+<example category="keyword">
+```bash
+# Query: "cli shell terminal"
+gh search repos cli shell terminal --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+```
+</example>
+
+<example category="combined">
+```bash
+# Topics with additional keywords
+gh search repos "release automation" --topic=semver,versioning --language=typescript --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+```
+</example>
+</examples>
+
+## Output Format
+
+```bash
+--json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+```
+
+<example_output>
+```json
+[
+  {"createdAt":"2020-03-17T21:23:36Z","description":"SEMVER validation Github Action","fullName":"rubenesp87/semver-validation-action","stargazersCount":8,"updatedAt":"2024-03-29T19:31:00Z"},
+  {"createdAt":"2024-10-07T16:18:55Z","description":"An example to prove semverValidate Helm function","fullName":"lucabaggi/helm-semver-validation","stargazersCount":0,"updatedAt":"2024-10-07T16:24:06Z"}
+]
+```
+</example_output>
+
+## Result Processing
+
+<process>
+1. Get top 10 results from gh
+2. Sort by `stargazersCount` descending
+3. Return top 5 for DeepWiki queries
+</process>
+
+## Common Flags
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `--topic` | Filter by topics | `--topic=react,hooks` |
+| `--language` | Filter by language | `--language=typescript` |
+| `--owner` | Filter by owner | `--owner=facebook` |
+| `--stars` | Min stars | `--stars=">100"` |
+| `--sort` | Sort field | `--sort=stars` |
+| `--order` | Sort order | `--order=desc` |
+| `--limit` | Max results | `--limit=10` |
+| `--json` | Output format | `--json fullName,stargazersCount` |
+| `--archived` | Exclude archived | `--archived=false` |
+
+## JSON Available Fields
+ - createdAt
+ - defaultBranch
+ - description
+ - forksCount
+ - fullName
+ - hasDownloads
+ - hasIssues
+ - hasPages
+ - hasProjects
+ - hasWiki
+ - homepage
+ - id
+ - isArchived
+ - isDisabled
+ - isFork
+ - isPrivate
+ - language
+ - license
+ - name
+ - openIssuesCount
+ - owner
+ - pushedAt
+ - size
+ - stargazersCount
+ - updatedAt
+ - url
+ - visibility
+ - watchersCount
+
+## Error Handling
+
+```yaml
+IF gh auth status fails:
+  → Fall back to search_tool or fetch_tool
+IF gh search repos fails:
+  → Fall back to search_tool or fetch_tool
+```
+
+## Permission Opt-Out
+
+Users can deny `gh` tool permission in OpenCode to opt out of this search method. The skill will automatically fall back to web search tools.

package/.opencode/skills/intellisearch/references/google-search.md

@@ -0,0 +1,40 @@
+# Google Search Operators
+
+Source: https://support.google.com/websearch/answer/2466433?hl=en
+
+## Essential Operators
+
+| Operator | Syntax | Example | Purpose |
+|----------|--------|---------|---------|
+| Exact match | `"phrase"` | `"tallest building"` | Exact phrase match |
+| Site search | `site:domain.com` | `site:youtube.com cat videos` | Search specific domain |
+| Exclude | `-word` | `jaguar speed -car` | Exclude word from results |
+
+## Usage Notes
+
+<important>
+- No spaces between operator and search term: `site:nytimes.com` works, `site: nytimes.com` does not
+- Operators can be combined: `"typescript" tutorial -paid`
+- Quotes are useful for exact phrases like `"order of the phoenix"`
+</important>
+
+## Common Patterns for Technical Search
+
+<patterns>
+```bash
+# Find libraries
+typescript validation library npm
+
+# Exact phrase
+"semantic versioning" nodejs package
+
+# Exclude results
+graph database python -javascript
+
+# Combined
+semver typescript validation -test
+
+# Package search
+npm package semver compare
+```
+</patterns>

package/.opencode/skills/intellisearch/references/search-workflow.md

@@ -0,0 +1,143 @@
+# Search Workflow
+
+Tool detection and search strategy for finding GitHub repositories.
+
+<critical_rules priority="highest">
+<rule>NEVER use `site:github.com` with search tools - returns full URLs that get misparsed</rule>
+<rule>Only fetch EXTERNAL search engines, NEVER github.com URLs</rule>
+<rule>Cycle through engines on failure: Brave → DuckDuckGo → Google</rule>
+</critical_rules>
+
+## Tool Priority
+
+```yaml
+detection:
+  IF gh auth status succeeds:
+    → Use gh search repos (PREFERRED - direct API)
+  ELSE IF search_tool exists:
+    → Use search tool with keywords (NOT site:github.com)
+  ELSE IF fetch_tool exists:
+    → Use URI-based search with engine cycling
+  ELSE:
+    → Report: "No search capability available"
+    → fallback to internal knowledge
+```
+
+## GitHub CLI (Preferred)
+
+<detection>
+```bash
+gh auth status  # Exit 0 = available
+```
+</detection>
+
+<search_patterns priority="try_in_order">
+```bash
+# 1. Full query with topics and language
+gh search repos "{query}" --topic={topics} --language={lang} --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+
+# 2. Query with language only
+gh search repos "{query}" --language={lang} --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+
+# 3. Topic-based search (no query string)
+gh search repos --topic={topics} --language={lang} --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+
+# 4. Broader keyword search
+gh search repos "{query}" --json fullName,stargazersCount,createdAt,updatedAt,description --limit 10
+```
+</search_patterns>
+
+<process>
+1. Infer topics from query (framework/library names → topics)
+2. Infer language if mentioned
+3. Sort by stargazersCount, return top 5
+4. Skip to DeepWiki query
+</process>
+
+See @gh-cli.md for detailed syntax.
+
+## Search Tool (Fallback #1)
+
+<constraint>DO NOT use `site:github.com` - it returns full GitHub URLs that get misparsed as repos.</constraint>
+
+<query_format>
+```json
+{ "query": "{technology} {feature} {language} library package" }
+```
+</query_format>
+
+<example>
+```json
+{ "query": "typescript semver validation library npm package" }
+```
+</example>
+
+<result_processing>
+- Look for package names in snippets
+- Find `github.com/owner/repo` references in descriptions
+- Ignore navigation/ads
+</result_processing>
+
+## URI-Based Search (Fallback #2)
+
+When only fetch tools available, cycle through engines:
+
+| Priority | Engine | URL |
+|----------|--------|-----|
+| 1 | Brave | `https://search.brave.com/search?q={terms}` |
+| 2 | DuckDuckGo | `https://duckduckgo.com/?q={terms}` |
+| 3 | Google | `https://www.google.com/search?q={terms}` |
+
+<error_handling>
+```yaml
+FOR each engine IN [brave, duckduckgo, google]:
+  result = fetch(engine_url)
+  IF success AND has_search_results:
+    RETURN result
+  CONTINUE
+RETURN error: all engines failed
+```
+</error_handling>
+
+<failure_causes>
+- JavaScript redirects (Google)
+- Captchas (DuckDuckGo)
+- HTML parsing issues
+</failure_causes>
+
+<example>
+```json
+{
+  "url": "https://search.brave.com/search?q=typescript%20semver%20validation%20library",
+  "format": "markdown",
+  "timeout": 10
+}
+```
+</example>
+
+## Query Construction
+
+<keyword_based>
+```
+{technology} {feature} {language} library package
+```
+</keyword_based>
+
+<examples>
+- `react hooks typescript library`
+- `semver validation nodejs package`
+- `graph database python library`
+</examples>
+
+<result_extraction>
+- Look for `github.com/owner/repo` in snippet descriptions
+- Find package names that map to known repos
+- Follow links in documentation references
+</result_extraction>
+
+## References
+
+- @gh-cli.md - GitHub CLI syntax
+- @google-search.md - Google operators
+- @brave-search.md - Brave operators
+- @ddg-search.md - DuckDuckGo operators