@joycodetech/qmd-ja 2.5.3

package/skills/qmd/references/mcp-setup.md

@@ -0,0 +1,102 @@
+# QMD MCP Server Setup
+
+## Install
+
+```bash
+npm install -g @tobilu/qmd
+qmd collection add ~/path/to/markdown --name myknowledge
+qmd embed
+```
+
+## Configure MCP Client
+
+**Claude Code** (`~/.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "qmd": { "command": "qmd", "args": ["mcp"] }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "qmd": { "command": "qmd", "args": ["mcp"] }
+  }
+}
+```
+
+**OpenClaw** (`~/.openclaw/openclaw.json`):
+```json
+{
+  "mcp": {
+    "servers": {
+      "qmd": { "command": "qmd", "args": ["mcp"] }
+    }
+  }
+}
+```
+
+## HTTP Mode
+
+```bash
+qmd mcp --http              # Port 8181
+qmd mcp --http --daemon     # Background
+qmd mcp stop                # Stop daemon
+```
+
+## Tools
+
+### structured_search
+
+Search with pre-expanded queries.
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "keyword phrases" },
+    { "type": "vec", "query": "natural language question" },
+    { "type": "hyde", "query": "hypothetical answer passage..." }
+  ],
+  "limit": 10,
+  "collection": "optional",
+  "minScore": 0.0
+}
+```
+
+| Type | Method | Input |
+|------|--------|-------|
+| `lex` | BM25 | Keywords (2-5 terms) |
+| `vec` | Vector | Question |
+| `hyde` | Vector | Answer passage (50-100 words) |
+
+### get
+
+Retrieve document by path or `#docid`.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `path` | string | File path or `#docid` |
+| `full` | bool? | Return full content |
+| `lineNumbers` | bool? | Add line numbers |
+
+### multi_get
+
+Retrieve multiple documents.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `pattern` | string | Glob or comma-separated list |
+| `maxBytes` | number? | Skip large files (default 10KB) |
+
+### status
+
+Index health and collections. No params.
+
+## Troubleshooting
+
+- **Not starting**: `which qmd`, `qmd mcp` manually
+- **No results**: `qmd collection list`, `qmd embed`
+- **Slow first search**: Normal, models loading (~3GB)

package/skills/release/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: release
+description: Manage releases for this project. Validates changelog, installs git hooks, and cuts releases. Use when user says "/release", "release 1.0.5", "cut a release", or asks about the release process. NOT auto-invoked by the model.
+disable-model-invocation: true
+---
+
+# Release
+
+Cut a release, validate the changelog, and ensure git hooks are installed.
+
+## Usage
+
+`/release 1.0.5` or `/release patch` (bumps patch from current version).
+
+## Process
+
+When the user triggers `/release <version>`:
+
+1. **Gather context** — run `skills/release/scripts/release-context.sh <version>`.
+   This silently installs git hooks and prints everything needed: version info,
+   working directory status, commits since last release, files changed, current
+   `[Unreleased]` content, and the previous release entry for style reference.
+
+2. **Commit outstanding work** — if the context shows staged, modified, or
+   untracked files that belong in this release, commit them first. Use the
+   /commit skill or make well-formed commits directly.
+
+3. **Write the changelog** — if `[Unreleased]` is empty, write it now using
+   the commits and file changes from the context output. Follow the changelog
+   standard below. Re-run the context script after committing if needed.
+
+4. **Cut the release** — run `scripts/release.sh <version>`. This renames
+   `[Unreleased]` → `[X.Y.Z] - date`, inserts a fresh `[Unreleased]`,
+   bumps `package.json`, commits, and tags.
+
+5. **Show the final changelog** — print the full `[Unreleased]` +
+   minor series rollup via `scripts/extract-changelog.sh <version>`.
+   Ask the user to confirm before pushing.
+
+6. **Push** — after explicit confirmation, run `git push origin main --tags`.
+
+7. **Watch CI** — after the push, start a background dispatch to watch the
+   publish workflow. Use `interactive_shell` in dispatch mode with:
+   ```
+   gh run watch $(gh run list --workflow=publish.yml --limit=1 --json databaseId --jq '.[0].databaseId') --exit-status
+   ```
+   The agent will be notified when CI completes and should report the result.
+
+7. **Check dependency updates** — before cutting the release, check for
+   updates to `sqlite-vec` (and platform packages), `node-llama-cpp`,
+   and `better-sqlite3`. Run `pnpm outdated` and report any available
+   updates for these packages. If updates exist, bump them (pinned, no
+   `^` ranges) and re-run tests before proceeding.
+
+If any step fails, stop and explain. Never force-push or skip validation.
+
+## Dependency Policy
+
+All dependencies must be pinned to exact versions (no `^` or `~` ranges).
+The lockfile ensures reproducible installs. When adding or updating any
+dependency, always use the exact version string (e.g. `"3.18.1"` not
+`"^3.18.1"`).
+
+## Changelog Standard
+
+The changelog lives in `CHANGELOG.md` and follows [Keep a Changelog](https://keepachangelog.com/) conventions.
+
+### Heading format
+
+- `## [Unreleased]` — accumulates entries between releases
+- `## [X.Y.Z] - YYYY-MM-DD` — released versions
+
+### Structure of a release entry
+
+Each version entry has two parts:
+
+**1. Highlights (optional, 1-4 sentences of prose)**
+
+Immediately after the version heading, before any `###` section. The elevator
+pitch — what would you tell someone in 30 seconds? Only for significant
+releases; skip for small patches.
+
+```markdown
+## [1.1.0] - 2026-03-01
+
+QMD now runs on both Node.js and Bun, with up to 2.7x faster reranking
+through parallel contexts. GPU auto-detection replaces the unreliable
+`gpu: "auto"` with explicit CUDA/Metal/Vulkan probing.
+```
+
+**2. Detailed changelog (`### Changes` and `### Fixes`)**
+
+```markdown
+### Changes
+
+- Runtime: support Node.js (>=22) alongside Bun. The `qmd` wrapper
+  auto-detects a suitable install via PATH. #149 (thanks @igrigorik)
+- Performance: parallel embedding & reranking — up to 2.7x faster on
+  multi-core machines.
+
+### Fixes
+
+- Prevent VRAM waste from duplicate context creation during concurrent
+  `embedBatch` calls. #152 (thanks @jkrems)
+```
+
+### Writing guidelines
+
+- **Explain the why, not just the what.** The changelog is for users.
+- **Include numbers.** "2.7x faster", "17x less memory".
+- **Group by theme, not by file.** "Performance" not "Changes to llm.ts".
+- **Don't list every commit.** Aggregate related changes.
+- **Credit contributors:** end bullets with `#NNN (thanks @username)` for
+  external PRs. No need to credit the repo owner.
+
+### What not to include
+
+- Internal refactors with no user-visible effect
+- Dependency bumps (unless fixing a user-facing bug)
+- CI/tooling changes (unless affecting the release artifact)
+- Test additions (unless validating a fix worth mentioning)
+
+## GitHub Release Notes
+
+Each GitHub release includes the full changelog for the **minor series** back
+to x.x.0. The `scripts/extract-changelog.sh` script handles this, and the
+publish workflow (`publish.yml`) calls it to populate the GitHub release.
+
+## Git Hooks
+
+The pre-push hook (`scripts/pre-push`) blocks `v*` tag pushes unless:
+
+1. `package.json` version matches the tag
+2. `CHANGELOG.md` has a `## [X.Y.Z] - date` entry for the version
+3. CI passed on GitHub (warns in non-interactive shells, blocks in terminals)
+
+Hooks are installed silently by the context script. They can also be installed
+manually via `skills/release/scripts/install-hooks.sh` or automatically via
+`bun install` (prepare script).

package/skills/release/scripts/install-hooks.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Install git hooks for release validation.
+# Idempotent — safe to run multiple times.
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [[ -z "$REPO_ROOT" ]]; then
+  echo "Error: not in a git repository" >&2
+  exit 1
+fi
+
+HOOKS_DIR="$REPO_ROOT/.git/hooks"
+SOURCE="$REPO_ROOT/scripts/pre-push"
+
+if [[ ! -f "$SOURCE" ]]; then
+  echo "Error: scripts/pre-push not found at $SOURCE" >&2
+  exit 1
+fi
+
+# Install pre-push hook
+if [[ -L "$HOOKS_DIR/pre-push" ]] && [[ "$(readlink "$HOOKS_DIR/pre-push")" == "$SOURCE" ]]; then
+  echo "pre-push hook: already installed (symlink)"
+elif [[ -f "$HOOKS_DIR/pre-push" ]]; then
+  # Existing hook that isn't our symlink — back it up
+  BACKUP="$HOOKS_DIR/pre-push.backup.$(date +%s)"
+  echo "pre-push hook: backing up existing hook to $(basename "$BACKUP")"
+  mv "$HOOKS_DIR/pre-push" "$BACKUP"
+  ln -sf "$SOURCE" "$HOOKS_DIR/pre-push"
+  echo "pre-push hook: installed (symlink → scripts/pre-push)"
+else
+  ln -sf "$SOURCE" "$HOOKS_DIR/pre-push"
+  echo "pre-push hook: installed (symlink → scripts/pre-push)"
+fi
+
+# Ensure the source is executable
+chmod +x "$SOURCE"
+echo "Done."

package/vendor/vaporetto-node-wasm/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "vaporetto-node-wasm",
+  "version": "0.1.0",
+  "files": [
+    "vaporetto_node_wasm_bg.wasm",
+    "vaporetto_node_wasm.js",
+    "vaporetto_node_wasm.d.ts"
+  ],
+  "main": "vaporetto_node_wasm.js",
+  "types": "vaporetto_node_wasm.d.ts"
+}

package/vendor/vaporetto-node-wasm/vaporetto_node_wasm.d.ts

@@ -0,0 +1,19 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class VaporettoTokenizer {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new tokenizer from a zstd-compressed or raw model buffer.
+     */
+    constructor(model_data: Uint8Array);
+    /**
+     * Tokenize a string and return space-separated tokens.
+     */
+    tokenize(text: string): string;
+    /**
+     * Return token surfaces as a JS array of strings.
+     */
+    tokenize_to_array(text: string): Array<any>;
+}

package/vendor/vaporetto-node-wasm/vaporetto_node_wasm.js

@@ -0,0 +1,202 @@
+/* @ts-self-types="./vaporetto_node_wasm.d.ts" */
+
+class VaporettoTokenizer {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        VaporettoTokenizerFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_vaporettotokenizer_free(ptr, 0);
+    }
+    /**
+     * Create a new tokenizer from a zstd-compressed or raw model buffer.
+     * @param {Uint8Array} model_data
+     */
+    constructor(model_data) {
+        const ptr0 = passArray8ToWasm0(model_data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.vaporettotokenizer_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        VaporettoTokenizerFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Tokenize a string and return space-separated tokens.
+     * @param {string} text
+     * @returns {string}
+     */
+    tokenize(text) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.vaporettotokenizer_tokenize(this.__wbg_ptr, ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
+    /**
+     * Return token surfaces as a JS array of strings.
+     * @param {string} text
+     * @returns {Array<any>}
+     */
+    tokenize_to_array(text) {
+        const ptr0 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.vaporettotokenizer_tokenize_to_array(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+if (Symbol.dispose) VaporettoTokenizer.prototype[Symbol.dispose] = VaporettoTokenizer.prototype.free;
+exports.VaporettoTokenizer = VaporettoTokenizer;
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg_Error_fdd633d4bb5dd76a: function(arg0, arg1) {
+            const ret = Error(getStringFromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_new_36e147a8ced3c6e0: function() {
+            const ret = new Array();
+            return ret;
+        },
+        __wbg_push_f724b5db8acf89d2: function(arg0, arg1) {
+            const ret = arg0.push(arg1);
+            return ret;
+        },
+        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./vaporetto_node_wasm_bg.js": import0,
+    };
+}
+
+const VaporettoTokenizerFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_vaporettotokenizer_free(ptr, 1));
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+const wasmPath = `${__dirname}/vaporetto_node_wasm_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());
+let wasm = wasmInstance.exports;
+wasm.__wbindgen_start();

package/vendor/vaporetto-node-wasm/vaporetto_node_wasm_bg.wasm.d.ts

@@ -0,0 +1,13 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_vaporettotokenizer_free: (a: number, b: number) => void;
+export const vaporettotokenizer_new: (a: number, b: number) => [number, number, number];
+export const vaporettotokenizer_tokenize: (a: number, b: number, c: number) => [number, number, number, number];
+export const vaporettotokenizer_tokenize_to_array: (a: number, b: number, c: number) => [number, number, number];
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_start: () => void;