@wei840222/qmd 2026.8.23

package/skills/qmd/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: qmd
+description: Search local markdown knowledge bases, notes, docs, and wikis with QMD. Use when users ask to find notes, retrieve documents, inspect a wiki, answer from indexed markdown, or set up QMD access.
+license: MIT
+compatibility: Requires qmd CLI or MCP server. Install via `npm install -g @wei840222/qmd`.
+metadata:
+  author: tobi
+  version: "2.6.3"
+allowed-tools: Bash(qmd:*), mcp__qmd__*
+---
+
+# QMD - Query Markdown Documents
+
+## How search works
+
+QMD searches local markdown collections: notes, docs, wikis, transcripts, and
+project knowledge bases. Use it before web search when the answer may already be
+in indexed local files.
+
+The workflow is always:
+
+1. Search for candidate documents.
+2. Retrieve the full source with `qmd get` or `qmd multi-get`.
+3. Answer from retrieved text, citing paths or docids.
+
+Do not answer from snippets alone when the user needs facts, decisions, quotes,
+or nuance. Snippets are only leads.
+
+Typical loop:
+
+```bash
+qmd search "merchant reality support interviews" -n 5
+# leads: #abc123 concepts/customer-proximity.md; #def432 sources/merchant-call.md
+qmd multi-get "#abc123,#def432" --format md
+```
+
+**Default to structured `qmd query` with `intent:`, `lex:`, `vec:`, and `hyde:`
+fields that you write yourself.** You are a better query expander than the
+built-in model: you know the user's actual goal, the domain vocabulary, and the
+nearby-but-wrong concepts to avoid. Do not just paste the user's words into
+`qmd query "..."` and hope the expansion model guesses right — supply the
+`intent:` and craft the lexical and semantic terms deliberately (see
+[Pick the right search mode](#pick-the-right-search-mode)).
+
+When reporting what you retrieved, a compact note is enough; do not paste whole
+files unless needed:
+
+```text
+Retrieved:
+- #abc123 concepts/customer-proximity.md
+- #def432 sources/merchant-call.md
+```
+
+## Pick the right search mode
+
+Use **BM25 lexical search** when you know exact words, titles, names, code
+symbols, or rare phrases:
+
+```bash
+qmd search "cockpit OKR Goodhart" -n 10
+qmd search '"AI Before Headcount"' -c concepts -n 5
+```
+
+Use **`qmd query` with structured fields** when the user describes an idea
+indirectly, uses different wording than the source, or needs conceptual recall.
+**This is the default mode — write the fields yourself rather than leaning on
+query expansion.** Combine exact anchors with semantic recall:
+
+```bash
+qmd query $'intent: Find the concept note about metrics as instruments without letting OKRs replace judgment.\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: A concept note says metrics are useful like cockpit instruments, but leaders should remain data-informed rather than metric-driven because OKRs and dashboards can Goodhart product judgment.'
+```
+
+Structured query fields (you author each one — do not delegate this to the
+expansion model):
+
+- `intent:` states what you are trying to find **and what to avoid**. Always
+  supply this. It steers ranking away from nearby-but-wrong concepts.
+- `lex:` exact terms, aliases, titles, code symbols, and rare words you expect
+  in the source. This is your own keyword expansion.
+- `vec:` paraphrases the idea in natural language, in source-like wording.
+- `hyde:` describes the document or answer that would satisfy the request.
+
+You do not need all four every time, but you should almost always write at least
+`intent:` plus one of `lex:`/`vec:`. A bare `qmd query "the user's sentence"`
+throws away the context only you have and relies on the built-in expander to
+reconstruct it — prefer the structured form.
+
+If you genuinely have nothing to expand (a single rare token, a verbatim phrase),
+that is a job for `qmd search`, not bare `qmd query`:
+
+```bash
+qmd query --format json --explain $'intent: ...\nlex: ...\nvec: ...'  # inspect ranking
+```
+
+If `qmd query` is slow or model/GPU setup fails, fall back to `qmd search` with
+better lexical terms.
+
+## Retrieve sources
+
+Search results include docids like `#abc123` and `qmd://...` paths. Fetch them:
+
+```bash
+qmd get "#abc123"
+qmd get qmd://concepts/ai-before-headcount.md
+qmd multi-get "#abc123,#def432" --format md
+qmd multi-get 'concepts/{ai-before-headcount.md,data-informed-not-metric-driven.md}' --format md
+qmd multi-get 'sources/podcast-2025-*.md' -l 80
+```
+
+Use `multi-get` when comparing several hits or gathering context across pages.
+
+### Output is line-numbered and carries the docid — cite both
+
+`get` and `multi-get` are **line-numbered by default** and always print the
+document's `#docid` and `qmd://` path. So `get` output looks like:
+
+```text
+qmd://concepts/note.md  #abc123
+---
+
+1: # Metrics as instruments
+2:
+3: Treat dashboards like cockpit instruments...
+```
+
+Cite the docid and exact line numbers in your answer, and use the numbers to ask
+for the next slice. Pass `--no-line-numbers` only when you need raw content to
+copy verbatim (e.g. reproducing a code block).
+
+When you need to open or edit the underlying file (e.g. hand a path to `Read`,
+`Edit`, or an editor), add `--full-path`. It replaces the `qmd://` URL + docid
+header with the document's on-disk path, falling back to the canonical header if
+the file no longer exists on disk:
+
+```text
+$ qmd get "#abc123" --full-path
+/Users/you/notes/concepts/note.md
+---
+
+1: # Metrics as instruments
+```
+
+`--full-path` works the same way on `qmd search` and `qmd query`: result paths
+become the file's on-disk path — `./`-prefixed relative path when the file is
+inside `$PWD`, absolute realpath otherwise — and the per-result `#docid` is
+dropped because the path is the identifier. The leading `./` is intentional so
+the output is unambiguously a filesystem path and cannot be mistaken for a bare
+collection-relative string. Default search/query output still uses `qmd://`
+URIs; only opt into `--full-path` when you specifically need a path you can hand
+to a non-QMD tool.
+
+### Read line ranges with the `:from:count` suffix — never pipe through `sed`/`head`/`tail`
+
+`qmd get` slices files itself. Use the suffix or flags; do **not** shell out to
+`sed -n`, `head`, `tail`, or `awk` to pull a line range. Piping defeats docid
+resolution, virtual-path lookups, line numbering, and the header, and it is
+slower and more error-prone.
+
+The most compact form is a `:from:count` suffix right on the path or docid —
+prefer it:
+
+```bash
+qmd get "#abc123:120:40"                  # 40 lines starting at line 120
+qmd get qmd://concepts/note.md:200:60     # lines 200–259
+qmd get "#abc123:120"                      # from line 120 to end of file
+qmd get "#abc123" --from 120 -l 40         # equivalent, using flags
+```
+
+Suffix and flags:
+
+- `<path>:<from>:<count>` — start at line `<from>`, read `<count>` lines. **Best
+  for reading around a search hit.**
+- `<path>:<from>` — start at `<from>`, read to end of file.
+- `--from <line>` / `-l <lines>` — flag equivalents. Explicit flags override the
+  suffix, so `... :5:2 -l 1` reads 1 line.
+- `--no-line-numbers` — drop the `N:` prefixes (line numbers are on by default).
+
+Wrong: `qmd get "#abc123" | sed -n '120,160p'`
+Right: `qmd get "#abc123:120:40"`
+
+Search results include a `:line` anchor on each hit — feed it straight into
+`qmd get path:line:<n>` to read a window around the match (line numbers in the
+output will start at `line`).
+
+## Discover what is indexed
+
+Run `qmd status` or `qmd ls` to quickly discover available collections, indexed file counts, and model readiness (all run in sub-seconds):
+
+```bash
+qmd status            # check collection overview, document counts, and model health
+qmd collection list   # list registered collection paths
+qmd ls                # list collection virtual paths
+```
+
+Always use collection filters (`-c <name>`) when searching specific topics to prevent cross-corpus drift and ensure fast, accurate results:
+
+```bash
+qmd search "headcount autonomous agents" -c concepts -n 10
+qmd query "merchant support product reality" -c concepts -c sources -n 10
+```
+
+> **Performance Tip for Agents:** Collection filters (`-c`) are natively indexed in both lexical and vector virtual tables. Scoping by collection guarantees millisecond search latency and avoids ranking dilution from unrelated collections. Omit `-c` only when searching across the entire workspace.
+
+## MCP Tool: `query`
+
+When using the MCP server, prefer structured searches:
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "cockpit OKR Goodhart" },
+    { "type": "vec", "query": "data informed not metric driven product judgment" },
+    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
+  ],
+  "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
+  "collections": ["concepts"],
+  "limit": 10
+}
+```
+
+Query types:
+
+- `lex` — BM25 keyword search. Best for exact terms, names, titles, and code.
+- `vec` — vector semantic search. Best for natural-language concepts.
+- `hyde` — vector search using a hypothetical answer/document passage.
+
+## Query craft
+
+Good QMD searches mix three things:
+
+1. **Title/alias anchors:** exact page titles, named entities, phrases.
+2. **Semantic paraphrase:** how a human would describe the idea.
+3. **Negative space:** enough intent to avoid nearby-but-wrong concepts.
+
+Examples:
+
+```bash
+# Exact-ish title lookup
+qmd search '"arm the rebels" merchants tools big companies' -c concepts
+
+# Semantic concept lookup
+qmd query $'intent: Find the customer proximity concept, not generic customer delight.\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'
+
+# Source lookup
+qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10
+```
+
+## Setup and maintenance
+
+Only mutate indexes when the user asked for setup or maintenance. Searching and
+retrieving are safe; collection/index mutation is not a casual first step.
+
+```bash
+npm install -g @wei840222/qmd
+qmd collection add ~/notes --name notes
+qmd update
+qmd embed
+```
+
+### Models & Remote Endpoint Configuration
+
+Configure models and custom endpoints in `~/.config/qmd/index.yml` under the `models:` section:
+
+```yaml
+models:
+  embed: hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf
+  embed_api_url: https://api.example.com/v1   # Both embed_api_url and embed_api_model enable remote embeddings
+  embed_api_model: text-embedding-3-small     # or text-embedding-3-large
+  embed_dimension: 1536                       # Optional: expected vector dimension; validates local output
+
+  # Optional: Remote LLM Query Expansion (aliases: generate_url, generate_base_url, generate_api_url)
+  generate_api_url: https://api.example.com/v1    # Base URL (appends /chat/completions) or full endpoint
+  generate_api_model: qwen3-7b-instruct           # or your-model-name
+
+  # Optional: Remote Reranking (supports rerank_url / rerank_base_url / rerank_api_url)
+  rerank_api_url: https://api.example.com/v1/chat/completions # Supports both /v1/rerank and /v1/chat/completions LLM endpoints
+  rerank_api_model: bge-reranker-v2-m3        # or gpt-4o-mini / qwen3-7b-instruct
+
+# Optional: Custom User Dictionary for CJK segmentation
+dictionary: ~/.config/qmd/dictionary.txt
+```
+
+> **Smart URL Resolution & Reranker Endpoints:** Remote LLM URLs support `_url`, `_base_url`, and `_api_url` aliases. Given a Base URL (e.g. `https://api.example.com/v1`), QMD automatically appends `/chat/completions` or `/rerank`. Explicit endpoint URLs are preserved as-is. For reranking, QMD supports both dedicated Cross-Encoder endpoints (`/v1/rerank`) and general LLM endpoints (`/v1/chat/completions`) with strict JSON sanitization and prompt-tail Recency Enforcement.
+
+> **CLI & MCP Integration:** Remote LLM query expansion and LLM Chat Reranking are automatically wired into CLI (`qmd query`) and MCP. Query expansion automatically maintains language & script consistency matching the user query (e.g. Traditional Chinese queries produce Traditional Chinese `lex`, `vec`, and `hyde` variations).
+>
+> **Batch Embedding & Vector Indexing:** Embedding requests for both indexing and query expansion automatically use high-throughput Batch APIs with graceful per-item fallback. Vector search leverages native collection pre-filtering for sub-second query latency across large datasets.
+
+Health and diagnostics:
+
+```bash
+qmd doctor
+qmd status
+qmd pull
+```
+
+`qmd doctor` checks config, model cache, device/GPU setup, vector fingerprints, CJK channel readiness, and common environment overrides. If a model-backed command fails, run it before changing configuration.
+
+## MCP setup
+
+See `references/mcp-setup.md` for Claude Code, Claude Desktop, OpenClaw, and HTTP
+server configuration.
+
+## Pitfalls
+
+- **Do not stop at snippets.** Fetch documents before making claims.
+- **Do not slice files with `sed`/`head`/`tail`.** Use the `path:from:count`
+  suffix (e.g. `qmd get "#abc123:120:40"`) or `--from`/`-l`. Output is already
+  line-numbered; piping breaks docid resolution, the header, and virtual paths.
+- **Do not lean on query expansion.** Write `intent:`/`lex:`/`vec:`/`hyde:`
+  yourself. A bare `qmd query "user sentence"` discards the context only you
+  have. You expand the query; the model just ranks.
+- **Do not overuse semantic search.** If you know exact titles or terms, BM25 is
+  faster and often better.
+- **Do not mutate indexes casually.** `qmd collection add`, `qmd update`, and
+  `qmd embed` change local state and can be expensive.
+- **Model-backed commands can be environment-sensitive.** If `qmd query`,
+  `qmd vsearch`, or reranking fails because local models/GPU are unavailable,
+  use `qmd search` and stronger lexical/structured terms.
+- **Ambiguous user wording needs intent.** Add `intent:` rather than hoping query
+  expansion guesses the right domain.
+- **Collection names matter.** Search `concepts` for synthesized wiki pages,
+  `sources` for transcripts/raw source pages, and docs collections for code or
+  project documentation.

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

@@ -0,0 +1,119 @@
+# QMD MCP Server Setup
+
+## Install
+
+```bash
+npm install -g @wei840222/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"] }
+    }
+  }
+}
+```
+
+## Protocol
+
+QMD speaks MCP **2026-07-28** (SDK 2.x) and dual-speaks 2025-era stdio clients.
+
+- **stdio** (`qmd mcp`): hosts still launch this as a subprocess. Opening
+  `initialize` (2025) or a `_meta`-enveloped request / `server/discover`
+  (2026) pins the connection's era.
+- **HTTP** (`qmd mcp --http`): sessionless Streamable HTTP. No
+  `Mcp-Session-Id`, no handshake. Each POST is independent. 2026 clients
+  MUST send `MCP-Protocol-Version`, `Mcp-Method`, and (for `tools/call`)
+  `Mcp-Name`. Version/caps travel in `_meta`. Call `server/discover` to
+  learn supported versions and capabilities. `tools/list` is cacheable
+  (`ttlMs` / `cacheScope`) and returns tools in a stable order.
+
+## HTTP Mode
+
+```bash
+qmd mcp --http              # Port 8181
+qmd mcp --http --daemon     # Background
+qmd mcp stop                # Stop daemon
+```
+
+`POST /mcp` is the MCP endpoint (JSON). `GET /health` is a liveness check.
+There is no session GET stream and no idle-session TTL.
+
+## Tools
+
+### query
+
+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 64KB) |
+
+### 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,141 @@
+---
+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. **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.
+
+5. **Cut the release** — run `scripts/release.sh <version>`. This renames
+   `[Unreleased]` → `[X.Y.Z] - date`, inserts a fresh `[Unreleased]`,
+   bumps `package.json` and the plugin version in
+   `.claude-plugin/marketplace.json` (so installed plugins see the update),
+   commits, and tags.
+
+6. **Show the final changelog** — print the full `[Unreleased]` +
+   minor series rollup via `scripts/extract-changelog.sh <version>`.
+   Ask the user to confirm before pushing.
+
+7. **Push** — after explicit confirmation, run `git push origin main --tags`.
+
+8. **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.
+
+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."