hafez 1.3.0 → 1.4.0

package/dist/vault.js

@@ -1,7 +1,7 @@
 // src/vault.ts
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
-import { readFileSync, readdirSync } from 'fs';
+import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { HafezError } from './types.js';
 // Prevent gray-matter from auto-coercing YAML date strings into JS Date objects
@@ -69,15 +69,50 @@ export function resolveFilePath(vaultPath, slug, kind) {
     }
     return join(vaultPath, KIND_DIRS[kind], `${slug}.md`);
 }
+/** The file a slug names, or null — entities are resolved before knowledge,
+ * the one resolution order every operation sees. */
+export function findVaultFile(vaultPath, slug) {
+    const entity = resolveFilePath(vaultPath, slug, 'entity');
+    if (existsSync(entity))
+        return entity;
+    const knowledge = resolveFilePath(vaultPath, slug, 'knowledge');
+    if (existsSync(knowledge))
+        return knowledge;
+    return null;
+}
+/** Does this slug name a vault file? An invalid slug definitionally doesn't
+ * exist — reference checks (create parent/related, link targets, validate)
+ * must report "does not exist", not crash. validate() in particular exists to
+ * REPORT malformed refs. */
+export function vaultFileExists(vaultPath, slug) {
+    try {
+        return findVaultFile(vaultPath, slug) !== null;
+    }
+    catch {
+        return false;
+    }
+}
 // Separator-agnostic: OS paths use '/' or '\' depending on platform, and a
 // POSIX-only check silently classifies every entity as knowledge on Windows
 // (all updates then fail on kind rules). Exported pure so win32 paths are
 // unit-testable from any platform.
+// The DEEPEST kind-dir occurrence wins: the in-vault dir is always deeper
+// than any ancestor, so a vault living under a directory named 'entities'
+// (e.g. ~/data/entities/myvault) can't shadow its knowledge/ files.
 export function kindFromPath(filePath) {
-    return /[/\\]entities[/\\]/.test(filePath) ? 'entity' : 'knowledge';
+    const lastMatch = (dir) => {
+        let idx = -1;
+        for (const m of filePath.matchAll(new RegExp(`[/\\\\]${dir}[/\\\\]`, 'g')))
+            idx = m.index;
+        return idx;
+    };
+    return lastMatch(KIND_DIRS.entity) > lastMatch(KIND_DIRS.knowledge) ? 'entity' : 'knowledge';
 }
-// Fields that must always be arrays when present (may be scalar in hand-edited YAML)
-const ARRAY_FIELDS = ['related', 'tags', 'domain'];
+/** Fields that must always be arrays when present (may be scalar in
+ * hand-edited YAML). Parsing coerces them here; merge.ts unions them on
+ * conflict — one list, so a new list-valued field cannot be normalized on
+ * read and then overwritten wholesale on merge. */
+export const ARRAY_FIELDS = ['related', 'tags', 'domain'];
 function normalizeFrontmatter(fm) {
     for (const field of ARRAY_FIELDS) {
         if (field in fm && typeof fm[field] === 'string') {
@@ -96,6 +131,17 @@ export function vaultKindFromPath(filePath) {
         return 'session';
     return kindFromPath(filePath);
 }
+/** Total kind classification for a vault-relative content file (anything
+ * matching VAULT_FILE_RE) — derived from KIND_DIRS, so adding a vault dir
+ * can't silently fall a new kind through to the wrong one. Throws on paths
+ * outside the vault dirs; callers gate on VAULT_FILE_RE first. */
+export function vaultKindFromRelPath(relPath) {
+    for (const [kind, dir] of Object.entries(KIND_DIRS)) {
+        if (relPath.startsWith(`${dir}/`))
+            return kind;
+    }
+    throw new HafezError('VALIDATION_FAILED', `Not a vault content path: ${relPath}`);
+}
 export function parseFilePath(path) {
     const content = readFileSync(path, 'utf-8');
     const { data, content: body } = matter(content, MATTER_OPTIONS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/skill/SKILL.md

@@ -1,133 +1,71 @@
 ---
 name: hafez
 description: >
-  Hafez vault — personal knowledge base of captures, entities, projects,
-  and knowledge notes (with subtypes: insight, plan). Use when the user says /hafez, asks to query the vault
-  ("what am I working on?", "show active projects", "what's stale?"), wants to
-  read or create an entity, or references Hafez directly. Also use at session
-  start to load context for identifiable topics, and at session end to record
-  a digest. Even if the user just casually mentions a project by name,
-  use this skill to check if it's a Hafez entity.
+  Hafez vault — personal knowledge base of captures, entities, projects, and
+  knowledge notes (subtypes: insight, plan). Use when the user mentions Hafez
+  (or types /hafez), asks what's in the vault ("what am I working on?", "what's
+  stale?"), wants to create or update an entity or knowledge note, at session
+  start to load context for an identifiable topic, at session end to record a
+  digest, when a casually mentioned project name might be a vault entity, or
+  when the user wants to update the tool itself ("update hafez", "upgrade
+  hafez", "is hafez outdated").
 ---
 
 # Hafez — Vault Operations
 
-All operations use the `hafez` CLI. No file manipulation — the CLI handles reads, writes, validation, and git.
+All operations go through the `hafez` CLI — it owns reads, writes, validation, and git. Vault files are never edited directly.
 
 If `hafez` is not installed, or `hafez init` reports no vault, stop and follow the setup in the project README (github.com/shrvn-r/hafez) before using this skill. If the vault exists but is empty, run `hafez onboard` and follow what it prints.
 
-## CLI Reference
+## Situation → Command
 
-Run `hafez help --agent` for the complete, always-current API reference including all commands, flags, batch schema, and valid enum values.
-
-Quick reference for common operations:
+`hafez help --agent` is the complete, always-current API reference (all commands, flags, batch schema, enum values). This table covers the common situations; consult `help --agent` for anything beyond it.
 
 | Situation | Command |
 |-----------|---------|
-| Read an entity | `hafez read <slug>` |
-| Active projects | `hafez query --filter active` |
+| Read an entity (incl. a project the user mentions) | `hafez read <slug>` |
+| "What am I working on?" / active projects | `hafez query --filter active` |
 | Stale items | `hafez query --filter stale` |
-| Full-text search | `hafez search "<terms>"` |
-| Search knowledge only | `hafez search "<terms>" --kind knowledge` |
-| Create entity | `hafez create entity "<name>" --type project [--purpose "text"] [--description "text"] [--resource "uri"] [--brief "text"] [--add-action "task"]` |
-| Quick capture | `hafez capture "<name>"` |
+| Full-text search | `hafez search "<terms>"` (`--kind knowledge` to narrow) |
 | List inbox captures | `hafez query --filter capture` |
-| Update entity | `hafez update <slug> --brief "text" --add-action "task"` |
-| Complete action | `hafez update <slug> --complete-action "substring"` |
-| Session log | `hafez update <slug> --log "progress: summary" --agent claude` |
-| Link entities | `hafez link <slug> <target> --relation related` |
+| Children of a project | `hafez query --parent <slug>` |
+| Related entities/knowledge | `hafez query --related-to <slug>` |
+| New workstream | `hafez create entity "<name>" --type project [--brief "context"] [--add-action "task"]` (full flag list in `help --agent`; `--purpose` is project-only) |
+| New plan | `hafez create knowledge "<name>" --subtype plan [--status active\|done]` (plans have Goal/Steps/Dependencies — no `--synthesis`; `--status` is plan-only) |
+| Quick thought, no classification yet | `hafez capture "<name>"` |
 | Promote | `hafez promote <slug> <target>` (capture→entity/project/knowledge, entity→project) |
-| Add synthesis to knowledge | `hafez update <slug> --synthesis "text"` |
-| Add evidence to knowledge | `hafez update <slug> --add-evidence "text"` |
-| Add source to knowledge | `hafez update <slug> --add-source "url"` |
-| Export OKF bundle | `hafez export --okf [--out <dir>]` (re-export overwrites, never deletes) |
+| Set handoff context / summary / URI | `hafez update <slug> --brief "text"` / `--description "summary"` / `--resource "https://..."` |
+| Add / complete a next action | `hafez update <slug> --add-action "task"` / `--complete-action "substring"` |
+| Significant milestone (deployed, merged, bug found) | `hafez update <slug> --log "progress: summary" --agent claude` |
+| Link entities | `hafez link <slug> <target> --relation related` (or `parent` when a thread belongs to a project) |
+| Revise a knowledge insight | `hafez update <slug> --synthesis "text"` (`--insight` is an alias) |
+| Back knowledge with evidence / a source | `hafez update <slug> --add-evidence "text"` / `--add-source "url"` |
 | Digest session → batch | `echo '{...}' \| hafez digest \| hafez batch` (no pipes? `--file` on both) |
 
-Note: `--insight` is an alias for `--synthesis`.
-
 ## Session Start — Context Loading
 
-When a topic is identifiable from the user's first message:
+Load context only when a specific entity slug or topic is identifiable from the user's first message:
 
 1. Run `hafez read <slug>` to load entity context
 2. If the entity has a `parent`, also read the parent at frontmatter depth: `hafez read <parent> --depth frontmatter`
 3. Search for related knowledge (`hafez search "<topic>" --kind knowledge`) and read any relevant note: `hafez read <knowledge-slug>`
 4. Present a brief context line: "Loaded context for {name} (status: {status}, next: {next_action})"
 
-Don't load context speculatively. Only when you can identify a specific entity slug or topic.
-
-## Mid-Session — Working With the Vault
-
-| Situation | Action |
-|-----------|--------|
-| User asks "what am I working on?" | `hafez query --filter active` |
-| User asks about stale items | `hafez query --filter stale` |
-| User mentions a project by name | `hafez read <slug>` |
-| New workstream emerges | `hafez create entity "<name>" --type project [--brief "context"] [--add-action "task"]` |
-| Quick thought, no classification | `hafez capture "<name>"` |
-| Promote capture to entity/project | `hafez promote <slug> entity` |
-| Insight worth preserving | Search first (`hafez search "<topic>"`), then create or update |
-| Entity relates to another | `hafez link <slug> <target> --relation related` |
-| Thread belongs to a project | `hafez link <slug> <parent> --relation parent` |
-| Knowledge needs new synthesis | `hafez update <slug> --synthesis "text"` |
-| Knowledge backed by new evidence | `hafez update <slug> --add-evidence "text"` |
-| Knowledge has a source to cite | `hafez update <slug> --add-source "url"` |
-| Need children of a project | `hafez query --parent <slug>` |
-| Need related entities/knowledge | `hafez query --related-to <slug>` |
-| Search for something | `hafez search "<terms>"` |
-| Set handoff context | `hafez update <slug> --brief "context"` |
-| Set one-line description | `hafez update <slug> --description "summary"` |
-| Set resource URI (entity) | `hafez update <slug> --resource "https://..."` |
-| Add a next action | `hafez update <slug> --add-action "task"` |
-| Complete a next action | `hafez update <slug> --complete-action "task"` |
-| Rebuild stale index | `hafez index rebuild` |
-| Pull latest from remote | `hafez sync` |
-
-### Ingest Reflex — Before Creating New Knowledge
-
-Before creating a new knowledge note, always check if one already exists:
-
-```bash
-hafez search "<topic>"
-hafez search "<topic>" --kind knowledge
-```
-
-If a related note exists, update it rather than creating a duplicate. Use `--synthesis` to revise the main insight text, `--add-evidence` to append supporting evidence, or `--add-source` to cite a new source.
-
-Only create a new note when no existing knowledge covers the topic.
-
-### Wiki Links in Knowledge Notes
-
-When writing or updating knowledge note prose (brief, synthesis, insight body), use `[[wiki links]]` to reference related entities and knowledge naturally. This makes the vault navigable as a wiki:
-
-- Reference related projects: `[[project-slug]]`
-- Reference other knowledge: `[[knowledge-slug]]`
-- Reference people or areas: `[[entity-slug]]`
-
-The CLI does not enforce link syntax — write them naturally in the prose content you pass to `--synthesis`, `--brief`, or `--insight`.
+## Search-First Ingest
 
-### Deliberate Ingest Pattern
+A new knowledge note is a last resort. When an insight emerges or a source (document, conversation, research) is being processed:
 
-When processing a source (document, conversation, research) to extract knowledge:
+1. Search for existing coverage: `hafez search "<topic>"`, narrowing with `--kind knowledge`.
+2. A note covers the topic → update it: `--synthesis` to revise the main insight, `--add-evidence` to append support, `--add-source` to cite.
+3. Nothing covers it → create it linked from birth (`hafez create knowledge "<name>" --related slug1,slug2`), then write the body via `--synthesis`.
 
-```bash
-# 1. Search for existing coverage
-hafez search "<topic>" --kind knowledge
-
-# 2a. If exists — update it
-hafez update <slug> --synthesis "Revised insight" --add-source "url"
-hafez update <slug> --add-evidence "New evidence from source"
-
-# 2b. If new — create it
-hafez create knowledge "<name>" --related slug1,slug2
+Write `[[wiki links]]` in any knowledge prose (`--brief`, `--synthesis`) to reference related projects, entities, and notes — the CLI does not enforce link syntax; write them naturally in the text. This is what keeps the vault navigable as a wiki.
 
-# 3. Then update the note body via --synthesis with wiki links to related notes
-hafez update <slug> --synthesis "Insight text referencing [[related-slug]]"
-```
+**Knowledge boundary:** before writing an insight down, ask where it belongs. Useful beyond the current session or repo → vault knowledge note. Specific to one repo's code or workflow → that repo's own docs (CLAUDE.md, README, comments), not the vault.
 
 ## Batch Operations
 
-**Rule: Use `hafez batch` when making 2+ mutating calls.** Individual commands auto-commit after each call (and push, when the vault has a remote). Running multiple individual commands back-to-back causes git push races on synced vaults. Batch does all operations in one commit + one push.
+**Rule: Use `hafez batch` when making 2+ mutating calls.** Individual commands auto-commit after each call (and push, when the vault has a remote). Running multiple individual commands back-to-back causes git push races on synced vaults. Batch does all operations in one commit + one push. For a single operation, individual commands are fine — they auto-sync.
 
 ```bash
 echo '[
@@ -147,8 +85,6 @@ On shells that can't pipe stdin to native executables (Windows PowerShell 5.1),
 
 **Slug contract.** Slugs derive deterministically from names: lowercase, non-alphanumeric runs become single `-` (`"Auth Refactor!"` → `auth-refactor`). Batch executes sequentially, so later ops can reference the slugs of earlier creates in the same payload — create-then-link works in one batch. Collisions hard-error, so a wrong prediction can't touch the wrong document; `hafez batch --dry-run` reports the derived slug for every create op if you want to verify first.
 
-For a single operation, individual commands are fine — they auto-sync.
-
 ## Session End — Digest
 
 At the end of a working session (or a natural breakpoint), record what happened:
@@ -173,24 +109,29 @@ Digest adds a session log entry to each touched entity and creates a session not
 
 Digest itself is pure — it only prints batch JSON; `hafez batch` is what writes. If you are unsure the slugs exist, run `hafez digest` alone first: unknown slugs warn on stderr (they are omitted from the output). Fix `entities_touched`, regenerate, and pipe to batch **once** — re-running the full pipe after a successful batch creates a duplicate session note.
 
-**Mid-session updates and the digest coexist.** Point-in-time updates (`--status done`, `--complete-action`, brief changes) happen as they happen — don't defer them to session end. Digest adds the overall narrative on top. Do NOT hand-write session log entries (`--log`) right before digesting — digest builds the session summary itself. Use `--log` mid-session only for significant milestones (deployed, merged, discovered a bug).
+**Mid-session updates and the digest coexist.** Point-in-time updates (`--status done`, `--complete-action`, brief changes) happen as they happen — digest adds the overall narrative on top. Digest builds the session summary itself, so the session's closing log entry comes from digest; reserve hand-written `--log` for significant mid-session milestones (deployed, merged, discovered a bug).
 
-## Knowledge Maintenance
+Session end is also when knowledge gets written: review what was learned and run Search-First Ingest on anything worth keeping. Knowledge notes are the primary durable output of sessions — not a side effect.
 
-Knowledge notes are the primary durable output of sessions — not a side effect. Treat the vault as a living wiki.
+## Periodic Lint
 
-**Active maintenance pattern:**
-1. At session start: search for knowledge relevant to the topic
-2. During work: when insights emerge, search before creating — update existing notes first
-3. Use `[[wiki links]]` in knowledge prose to connect related concepts
-4. At session end: review what was learned and update or create knowledge notes
+Run at session end or on demand:
 
-**Periodic lint** (run at session end or on demand):
 ```bash
 hafez validate
-hafez query --kind knowledge --filter stale
+hafez query --kind knowledge --sort-by last_reinforced --sort-order asc --limit 20
 ```
-Surface orphaned notes (no related links) and stale knowledge for review or archival.
 
-**Knowledge boundary:** before writing an insight down, ask where it belongs. Useful beyond the current session or repo → vault knowledge note. Specific to one repo's code or workflow → that repo's own docs (CLAUDE.md, README, comments), not the vault.
+Surface orphaned notes (no related links) and the least-recently-reinforced knowledge for review or archival. (`--filter` is entity status — knowledge notes have none, so the query command rejects it under `--kind knowledge`.)
+
+## Updating Hafez Itself
+
+"update hafez" means the **tool**. `hafez update` is an entity update — a different thing entirely. Don't confuse them.
+
+1. Run `hafez upgrade`. It checks and prints; it never installs.
+2. Show the user the printed commands **verbatim** and wait for an explicit yes. They install code and overwrite the user's own agent instructions file — never run them unattended, and never run the tarball alternative alongside the npm install.
+3. Run the approved steps, then re-run `hafez upgrade` to verify.
+
+If `hafez upgrade` fails with the literal prefix `Unknown command:`, the installed hafez predates it. Install the current version, re-copy the bundled skill, then run `hafez upgrade` — the README's Updating section (github.com/shrvn-r/hafez) has the exact commands.
 
+`hafez upgrade` also prints the current integration snippet. Compare it against the Hafez block in the user's global instructions file and offer to reconcile differences — don't rewrite their file unasked.

package/dist/query.d.ts

@@ -1,24 +0,0 @@
-import type { QueryResult, KnowledgeQueryResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedResult } from './types.js';
-import type { HafezIndex } from './db.js';
-export declare function queryEntities(index: HafezIndex, opts?: EntityQueryOpts): {
-    items: QueryResult[];
-    total: number;
-};
-export declare function queryChildren(index: HafezIndex, parentSlug: string): {
-    items: QueryResult[];
-    total: number;
-};
-export declare function queryRelatedTo(index: HafezIndex, slug: string, relation?: string): {
-    items: UnifiedResult[];
-    total: number;
-};
-export declare function queryKnowledge(index: HafezIndex, opts?: KnowledgeQueryOpts): {
-    items: KnowledgeQueryResult[];
-    total: number;
-};
-export declare function queryUnified(index: HafezIndex, opts?: EntityQueryOpts & {
-    kind?: 'entity' | 'knowledge' | 'all';
-}): {
-    items: UnifiedResult[];
-    total: number;
-};

package/dist/query.js

@@ -1,169 +0,0 @@
-import { HafezError } from './types.js';
-function toQueryResult(slug, row) {
-    return {
-        slug,
-        name: row.name,
-        type: row.type,
-        status: row.status,
-        description: row.description ?? null,
-        resource: row.resource ?? null,
-        domain: row.domain ?? [],
-        last_touched: row.last_touched,
-        next_action: row.next_action ?? null,
-        next_action_count: row.next_action_count ?? 0,
-        parent: row.parent ?? null,
-        related: row.related ?? [],
-        staleness_days: row.staleness_days ?? null,
-        tags: row.tags ?? [],
-        brief: row.brief ?? null,
-        session_log_count: row.session_log_count ?? 0,
-        last_session_date: row.last_session_date ?? null,
-        last_session_type: row.last_session_type ?? null,
-        last_session_summary: row.last_session_summary ?? null,
-    };
-}
-function toKnowledgeResult(slug, row) {
-    return {
-        slug,
-        name: row.name,
-        description: row.description ?? null,
-        domain: row.domain ?? [],
-        confidence: row.confidence ?? 'observation',
-        related: row.related ?? [],
-        reinforcement_count: row.reinforcement_count ?? 0,
-        last_reinforced: row.last_reinforced ?? null,
-        last_touched: row.last_touched ?? null,
-    };
-}
-const STATUS_FILTERS = new Set(['active', 'paused', 'done']);
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-function validateDateOpts(opts) {
-    const fields = ['since', 'before', 'createdSince', 'createdBefore'];
-    for (const f of fields) {
-        if (opts?.[f] !== undefined && !ISO_DATE.test(opts[f])) {
-            throw new HafezError('VALIDATION_FAILED', `Invalid date format for ${f}: "${opts[f]}". Must be YYYY-MM-DD.`);
-        }
-    }
-}
-export function queryEntities(index, opts) {
-    index.syncIfStale();
-    validateDateOpts(opts);
-    const qopts = { kind: 'entity' };
-    if (opts?.filter && STATUS_FILTERS.has(opts.filter))
-        qopts.status = opts.filter;
-    if (opts?.filter === 'stale')
-        qopts.filter = 'stale';
-    if (opts?.filter === 'capture')
-        qopts.filter = 'capture';
-    if (opts?.type)
-        qopts.type = opts.type;
-    if (opts?.parent)
-        qopts.parent = opts.parent;
-    if (opts?.domain)
-        qopts.domain = opts.domain;
-    if (opts?.since)
-        qopts.since = opts.since;
-    if (opts?.before)
-        qopts.before = opts.before;
-    if (opts?.createdSince)
-        qopts.createdSince = opts.createdSince;
-    if (opts?.createdBefore)
-        qopts.createdBefore = opts.createdBefore;
-    if (opts?.tags)
-        qopts.tags = opts.tags;
-    if (opts?.sort_by)
-        qopts.sort_by = opts.sort_by;
-    if (opts?.sort_order)
-        qopts.sort_order = opts.sort_order;
-    if (opts?.limit != null)
-        qopts.limit = opts.limit;
-    if (opts?.offset != null)
-        qopts.offset = opts.offset;
-    const { items, total } = index.queryItems(qopts);
-    return { items: items.map(i => toQueryResult(i.slug, i)), total };
-}
-export function queryChildren(index, parentSlug) {
-    return queryEntities(index, { parent: parentSlug });
-}
-export function queryRelatedTo(index, slug, relation) {
-    index.syncIfStale();
-    const { items, total } = index.queryItems({ relatedTo: slug, relation });
-    return {
-        items: items.map(i => i.kind === 'entity'
-            ? { ...toQueryResult(i.slug, i), kind: 'entity' }
-            : { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' }),
-        total,
-    };
-}
-export function queryKnowledge(index, opts) {
-    index.syncIfStale();
-    const qopts = { kind: 'knowledge' };
-    if (opts?.domain)
-        qopts.domain = opts.domain;
-    if (opts?.confidence)
-        qopts.confidence = opts.confidence;
-    if (opts?.subtype)
-        qopts.subtype = opts.subtype;
-    if (opts?.tags)
-        qopts.tags = opts.tags;
-    if (opts?.sort_by)
-        qopts.sort_by = opts.sort_by;
-    if (opts?.sort_order)
-        qopts.sort_order = opts.sort_order;
-    if (opts?.limit != null)
-        qopts.limit = opts.limit;
-    if (opts?.offset != null)
-        qopts.offset = opts.offset;
-    const { items, total } = index.queryItems(qopts);
-    return { items: items.map(i => toKnowledgeResult(i.slug, i)), total };
-}
-export function queryUnified(index, opts) {
-    index.syncIfStale();
-    validateDateOpts(opts);
-    const qopts = {};
-    if (opts?.kind && opts.kind !== 'all')
-        qopts.kind = opts.kind;
-    // When kind is 'all' or unset, no kind filter — both entities and knowledge are returned
-    if (opts?.filter && STATUS_FILTERS.has(opts.filter))
-        qopts.status = opts.filter;
-    if (opts?.filter === 'stale')
-        qopts.filter = 'stale';
-    if (opts?.filter === 'capture')
-        qopts.filter = 'capture';
-    if (opts?.type)
-        qopts.type = opts.type;
-    if (opts?.parent)
-        qopts.parent = opts.parent;
-    if (opts?.domain)
-        qopts.domain = opts.domain;
-    if (opts?.confidence)
-        qopts.confidence = opts.confidence;
-    if (opts?.since)
-        qopts.since = opts.since;
-    if (opts?.before)
-        qopts.before = opts.before;
-    if (opts?.createdSince)
-        qopts.createdSince = opts.createdSince;
-    if (opts?.createdBefore)
-        qopts.createdBefore = opts.createdBefore;
-    if (opts?.tags)
-        qopts.tags = opts.tags;
-    if (opts?.sort_by)
-        qopts.sort_by = opts.sort_by;
-    if (opts?.sort_order)
-        qopts.sort_order = opts.sort_order;
-    if (opts?.limit !== undefined)
-        qopts.limit = opts.limit;
-    if (opts?.offset !== undefined)
-        qopts.offset = opts.offset;
-    const result = index.queryItems(qopts);
-    const items = result.items.map(i => {
-        if (i.kind === 'entity') {
-            return { ...toQueryResult(i.slug, i), kind: 'entity' };
-        }
-        else {
-            return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
-        }
-    });
-    return { items, total: result.total };
-}