@karmaniverous/jeeves-watcher 0.4.4 → 0.5.0-1

package/dist/skills/jeeves-watcher-admin/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: jeeves-watcher-admin
+description: >
+  Instance management for a jeeves-watcher deployment. Use when you need to
+  author or validate config, trigger reindexing, diagnose embedding failures,
+  or manage helper registrations.
+---
+
+# jeeves-watcher — Instance Administration
+
+## Tools
+
+### `watcher_validate`
+Validate config and optionally test file paths.
+- `config` (object, optional) — candidate config (partial or full). Omit to validate current config.
+- `testPaths` (string[], optional) — file paths to test against the config
+
+Partial configs merge with current config by rule name. If `config` is omitted, tests against the running config.
+
+### `watcher_config_apply`
+Apply config changes atomically.
+- `config` (object, required) — full or partial config to apply
+
+Validates, writes to disk, and triggers configured reindex behavior. Returns validation errors if invalid.
+
+### `watcher_reindex`
+Trigger a reindex.
+- `scope` (string, optional) — `"rules"` (default) or `"full"`
+
+Rules scope re-applies inference rules without re-embedding (lightweight). Full scope re-processes all files.
+
+### `watcher_issues`
+Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing files that failed and why.
+
+### `watcher_query`
+Query config and runtime state via JSONPath (same tool as consumer skill).
+
+### `watcher_status`
+Service health check including reindex progress.
+
+## Qdrant Filter Syntax
+
+Filters use Qdrant's native JSON filter format, passed as the `filter` parameter to `watcher_search`.
+
+### Basic Patterns
+
+**Match exact value:**
+```json
+{ "must": [{ "key": "domain", "match": { "value": "email" } }] }
+```
+
+**Match text (full-text search within field):**
+```json
+{ "must": [{ "key": "chunk_text", "match": { "text": "authentication" } }] }
+```
+
+**Combine conditions (AND):**
+```json
+{
+  "must": [
+    { "key": "domain", "match": { "value": "jira" } },
+    { "key": "status", "match": { "value": "In Progress" } }
+  ]
+}
+```
+
+**Exclude (NOT):**
+```json
+{
+  "must_not": [{ "key": "domain", "match": { "value": "repos" } }]
+}
+```
+
+**Any of (OR):**
+```json
+{
+  "should": [
+    { "key": "domain", "match": { "value": "email" } },
+    { "key": "domain", "match": { "value": "slack" } }
+  ]
+}
+```
+
+**Nested (combine AND + NOT):**
+```json
+{
+  "must": [{ "key": "domain", "match": { "value": "jira" } }],
+  "must_not": [{ "key": "status", "match": { "value": "Done" } }]
+}
+```
+
+### Key Differences
+- `match.value` — exact match (case-sensitive, for keyword fields like `domain`, `status`)
+- `match.text` — full-text match (for text fields like `chunk_text`)
+
+## Search Result Shape
+
+Each result from `watcher_search` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Qdrant point ID |
+| `score` | number | Similarity score (0-1, higher = more relevant) |
+| `payload.file_path` | string | Source file path |
+| `payload.chunk_text` | string | The matched text chunk |
+| `payload.chunk_index` | number | Chunk position within the file |
+| `payload.total_chunks` | number | Total chunks for this file |
+| `payload.content_hash` | string | Hash of the full document content |
+| `payload.matched_rules` | string[] | Names of inference rules that matched |
+
+Additional metadata fields depend on the deployment's inference rules (e.g., `domain`, `status`, `author`). Use `watcher_query` to discover available fields.
+
+## JSONPath Patterns for Schema Discovery
+
+Use `watcher_query` to explore the merged virtual document. Common patterns:
+
+### Orientation
+```
+$.inferenceRules[*].['name','description']    — List all rules with descriptions
+$.search.scoreThresholds                       — Score interpretation thresholds
+$.slots                                        — Named filter patterns (e.g., memory)
+```
+
+### Schema Discovery
+```
+$.inferenceRules[?(@.name=='jira-issue')]               — Full rule details
+$.inferenceRules[?(@.name=='jira-issue')].values        — Distinct values for a rule
+$.inferenceRules[?(@.name=='jira-issue')].values.status — Values for a specific field
+```
+
+### Helper Enumeration
+```
+$.mapHelpers                        — All JsonMap helper namespaces
+$.mapHelpers.slack.exports          — Exports from the 'slack' helper
+$.templateHelpers                   — All Handlebars helper namespaces
+```
+
+### Issues
+```
+$.issues                            — All runtime embedding failures
+```
+
+### Full Config Introspection
+```
+$.schemas                           — Global named schemas
+$.maps                              — Named JsonMap transforms
+$.templates                         — Named Handlebars templates
+```
+
+## Config Authoring
+
+### Rule Structure
+Each inference rule has:
+- `name` (required) — unique identifier
+- `description` (optional) — human-readable purpose
+- `match` — JSON Schema with picomatch glob for path matching
+- `set` — metadata fields to set on match
+- `map` (optional) — named JsonMap transform
+- `template` (optional) — named Handlebars template
+
+### Config Workflow
+1. Edit config (or build partial config object)
+2. Validate: `watcher_validate` with optional `testPaths` for dry-run preview
+3. Apply: `watcher_config_apply` — validates, writes, triggers reindex
+4. Monitor: `watcher_issues` for runtime embedding failures
+
+### When to Reindex
+- **Rules scope** (`"rules"`): Changed rule matching patterns, set expressions, schema mappings. No re-embedding needed.
+- **Full scope** (`"full"`): Changed embedding config, added watch paths, broad schema restructuring. Re-embeds everything.
+
+## Diagnostics
+
+### Escalation Path
+1. `watcher_status` — is the service healthy? Is a reindex running?
+2. `watcher_issues` — what files are failing and why?
+3. `watcher_query` with `$.issues` — same data via JSONPath
+4. Check logs at the configured log path
+
+### Error Categories
+- `type_collision` — metadata field type mismatch during extraction
+- `interpolation` — template/set expression failed to resolve
+- `read_failure` — file couldn't be read (permissions, encoding)
+- `embedding` — embedding API error
+
+## Helper Management
+
+Helpers use namespace prefixing: config key becomes prefix. A helper named `slack` exports `slack_extractParticipants`.
+
+Enumerate loaded helpers:
+```
+$.mapHelpers              — JsonMap helper namespaces with exports
+$.templateHelpers         — Handlebars helper namespaces with exports
+```
+
+## CLI Fallbacks
+
+If the watcher API is down:
+- `jeeves-watcher status` — check if the service is running
+- `jeeves-watcher validate` — validate config from CLI
+- Restart via NSSM (Windows) or systemctl (Linux)

package/package.json

@@ -33,6 +33,7 @@
     "ignore": "^7.0.5",
     "js-yaml": "*",
     "json5": "*",
+    "jsonpath-plus": "^10.4.0",
     "mammoth": "^1.11.0",
     "mdast-util-from-adf": "^2.2.0",
     "mdast-util-to-markdown": "^2.1.2",
@@ -171,7 +172,8 @@
   },
   "scripts": {
     "generate:schema": "tsx src/config/generate-schema.ts",
-    "build": "npm run generate:schema && rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript && node -e \"const fs=require('fs-extra');fs.copySync('plugin/openclaw.plugin.json','dist/plugin/openclaw.plugin.json');fs.copySync('plugin/skill','dist/plugin/skill');\"",
+    "build:skills": "node scripts/build-skills.js",
+    "build": "npm run generate:schema && rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript && npm run build:skills && node -e \"const fs=require('fs-extra');fs.copySync('plugin/openclaw.plugin.json','dist/plugin/openclaw.plugin.json');\"",
     "changelog": "auto-changelog",
     "diagrams": "cd diagrams && plantuml -tpng -o ../assets -r .",
     "docs": "typedoc",
@@ -185,5 +187,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.4.4"
+  "version": "0.5.0-1"
 }

package/dist/plugin/skill/SKILL.md

@@ -1,149 +0,0 @@
----
-name: jeeves-watcher
-description: >
-  Semantic search and metadata enrichment via a jeeves-watcher instance.
-  Use as your primary method for finding relevant files and context before
-  falling back to filesystem browsing.
----
-
-# Jeeves Watcher — Context Discovery
-
-## Behavioral Directive
-
-**Use `watcher_search` as your first step when you need to find information.** Before browsing the filesystem, before grepping, before guessing at file paths — search the index. It covers far more ground than manual exploration and finds things you wouldn't know to look for.
-
-**When search doesn't find what you need, fall back to your usual methods.** The index covers configured watch paths but not everything on the system. Active repos, system tools, and files outside the watch scope won't appear. Absence of results means the content may not be indexed, not that it doesn't exist.
-
-## Workflow
-
-### 1. Discover (once per session)
-
-Call `watcher_status` early in your session to learn what's available:
-
-```json
-{}
-```
-
-This returns collection stats and — critically — the set of payload fields with their types. Cache this mentally; these fields won't change during a session. Use them to construct targeted filters.
-
-### 2. Search (primary context discovery)
-
-Use `watcher_search` to find relevant files:
-
-```json
-{ "query": "authentication flow", "limit": 5 }
-```
-
-Results include `chunk_text` in the payload. For quick context, the chunks may be sufficient without reading the full file. Only load the file when you need complete content or plan to edit it.
-
-### 3. Read (when needed)
-
-Use the `file_path` from search results to read the actual file. Group results by `file_path` when multiple chunks come from the same document.
-
-### 4. Fall back (when search misses)
-
-If search returns nothing useful or low-scoring results (below ~0.3), the content likely isn't indexed. Fall back to filesystem browsing, directory listing, or grep. This is expected — not everything is in the index.
-
-## Tools
-
-### `watcher_status`
-
-Get service health, collection stats, and discover available payload fields.
-
-| Parameter | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| _(none)_  |      |          |             |
-
-**Returns:** `status`, `uptime`, `collection` (name, pointCount, dimensions), `payloadFields` (field names with types).
-
-### `watcher_search`
-
-Semantic similarity search with optional Qdrant filters.
-
-| Parameter | Type   | Required | Description                          |
-| --------- | ------ | -------- | ------------------------------------ |
-| `query`   | string | yes      | Natural-language search query        |
-| `limit`   | number | no       | Max results to return (default: 10)  |
-| `filter`  | object | no       | Qdrant filter object (see below)     |
-
-**Plain search:**
-
-```json
-{ "query": "error handling", "limit": 5 }
-```
-
-**Filtered search:**
-
-```json
-{
-  "query": "error handling",
-  "limit": 10,
-  "filter": {
-    "must": [{ "key": "domain", "match": { "value": "backend" } }]
-  }
-}
-```
-
-### `watcher_enrich`
-
-Set or update metadata on a document by file path.
-
-| Parameter  | Type   | Required | Description                         |
-| ---------- | ------ | -------- | ----------------------------------- |
-| `path`     | string | yes      | File path of the document           |
-| `metadata` | object | yes      | Key-value metadata to set           |
-
-```json
-{
-  "path": "docs/auth.md",
-  "metadata": { "domain": "auth", "reviewed": true }
-}
-```
-
-## Qdrant Filter Patterns
-
-Build filters using fields discovered via `watcher_status`.
-
-**Exact match:**
-
-```json
-{ "must": [{ "key": "domain", "match": { "value": "email" } }] }
-```
-
-**Multiple conditions:**
-
-```json
-{
-  "must": [
-    { "key": "domain", "match": { "value": "codebase" } },
-    { "key": "file_path", "match": { "text": "auth" } }
-  ]
-}
-```
-
-**Exclude results:**
-
-```json
-{
-  "must_not": [{ "key": "domain", "match": { "value": "codebase" } }]
-}
-```
-
-**Full-text match** (tokenized, for longer text fields):
-
-```json
-{ "must": [{ "key": "chunk_text", "match": { "text": "authentication" } }] }
-```
-
-## Score Interpretation
-
-- **0.7+** — Strong semantic match. Trust these results.
-- **0.4–0.7** — Relevant but may need verification. Worth reading.
-- **Below 0.3** — Likely noise. The content you need may not be indexed.
-
-## Tips
-
-- **Start broad, then narrow.** A plain query without filters shows you what's available. Add filters once you know which payload field values are relevant.
-- **Group by file.** Multiple chunks from the same file appear as separate results. Look at `file_path` to see when you're getting multiple views of one document.
-- **Chunk text is a preview.** It's useful for quick triage but may be truncated or split mid-sentence. Read the actual file for complete context.
-- **Enrich after analysis.** When you review a document and learn something about it, use `watcher_enrich` to tag it. Future searches can filter on those tags.