fix(release): harden v0.5 candidate contracts

Author: simonsysun

.github/workflows/publish.yml

@@ -13,10 +13,9 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Existing tag to publish (e.g. v0.2.1). Leave blank to use the branch HEAD."
-        required: false
+        description: "Existing tag to publish (e.g. v0.5.0). Required for manual publish."
+        required: true
         type: string
-        default: ""
 
 jobs:
   build:
@@ -28,28 +27,47 @@ jobs:
         with:
           # workflow_dispatch may override with a specific tag; otherwise
           # use the ref that triggered the workflow (tag push = that tag).
-          ref: ${{ github.event.inputs.tag != '' && github.event.inputs.tag || github.ref }}
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
 
       - name: Set up uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
 
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run python -m pytest tests/ -q
+
       - name: Build distributions
         run: uv build
 
       - name: Sanity-check version matches tag
-        # When triggered by a tag push, ensure pyproject.toml version matches
-        # the tag name. Skipped for workflow_dispatch (where we assume the
-        # invoker knows what they're doing).
-        if: github.event_name == 'push'
+        # Ensure pyproject.toml version matches the tag name for both automatic
+        # tag publishes and manual retries.
         run: |
-          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TAG_NAME="${{ github.event.inputs.tag }}"
+          else
+            TAG_NAME="${GITHUB_REF_NAME}"
+          fi
+          case "$TAG_NAME" in
+            v*) ;;
+            *)
+              echo "::error::Release tag must start with v (got ${TAG_NAME})"
+              exit 1
+              ;;
+          esac
+          TAG_VERSION="${TAG_NAME#v}"
           PKG_VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/version = "([^"]+)"/\1/')
           echo "Tag: v${TAG_VERSION}   pyproject: ${PKG_VERSION}"
           if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
             echo "::error::Tag v${TAG_VERSION} does not match pyproject version ${PKG_VERSION}"
             exit 1
           fi
 
+      - name: Check distributions
+        run: uvx twine check dist/*
+
       - name: Upload artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

CHANGELOG.md

@@ -10,8 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.5.0] - 2026-05-04
 
 ### Changed
+- Full-vault `seeklink index` now prints progress to stderr and keeps the final
+  `Done:` summary on stdout, including the `SEEKLINK_VAULT` daily-use path.
 - Full-vault indexing now embeds in smaller batches to reduce long-tail embedding stalls on real Markdown vaults.
-- `seeklink index --vault PATH` now prints full-vault progress to stderr while keeping the final `Done:` summary on stdout.
 - Indexes now record the embedder, vector dimension, distance metric, and
   chunker version used to build their vectors; full-vault indexing rebuilds
   derived index contents when that configuration changes.
@@ -20,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   changing the default 768-dimensional model.
 
 ### Fixed
+- Full-vault indexing no longer hard-skips `todo/` or `archive/` directories;
+  those are common PKM folders and should be indexed unless hidden or removed.
 - Chinese question-style queries now strip common question particles before
   FTS5 matching, so terms like `卵生动物有哪些？` can use the BM25 channel
   instead of falling back to vector-only retrieval.
@@ -37,18 +40,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `seeklink search` now refuses to query an existing vector index whose stored
   embedder/chunker metadata does not match the active configuration, instead of
   silently mixing query vectors with incompatible document vectors.
+- Reranker scoring now uses a numerically stable two-class softmax, avoiding
+  overflow on extreme model logits.
 
 ### Dev
+- Apple Silicon MLX reranking is now exposed as an optional `seeklink[mlx]`
+  extra, while the base install remains usable without MLX.
+- `numpy` is now declared as a direct runtime dependency because SeekLink
+  imports it directly.
+- The PyPI publish workflow now runs the test suite, checks the built
+  distributions, and validates manually triggered release tags before
+  publishing.
 - Blind-test result JSON now includes per-query `failure_bucket` labels and
   aggregate bucket counts, making it easier to distinguish candidate-generation,
   rerank-budget, and reranker-ordering failures during search-quality work.
 - Source checkouts now declare a build backend, so `uv sync --dev` installs the
   working tree's `seeklink` console script instead of falling through to a stale
   globally installed command during local verification.
 - Refreshed `tests/blind/results/` with v0.5 release-quality snapshots only. On
-  the bundled 22-query fixture, config A reports mean Recall@10 0.985, MRR
-  0.977, and nDCG@10 0.901; latency measurements remain in the JSON result
-  file because they are hardware- and load-dependent.
+  the bundled 22-query fixture with the optional MLX reranker active, config A
+  reports mean Recall@10 0.985, MRR 0.977, and nDCG@10 0.901; latency
+  measurements remain in the JSON result file because they are hardware- and
+  load-dependent.
 
 ## [0.4.0] - 2026-04-29
 

README.md

@@ -30,6 +30,18 @@ uv tool install seeklink
 pip install seeklink
 ```
 
+For Apple Silicon reranking support, install the optional MLX extra:
+
+```bash
+uv tool install "seeklink[mlx]"
+# or
+pip install "seeklink[mlx]"
+```
+
+SeekLink requires Python's `sqlite3` module to be linked against SQLite
+3.45 or newer with FTS5 enabled. `seeklink status --vault PATH` checks this and
+prints a clear error if the runtime SQLite is too old.
+
 ## Quick Start
 
 ```bash
@@ -49,11 +61,13 @@ seeklink search "agent memory systems"
 seeklink get notes/agent-memory-patterns.md:1 -C 20
 ```
 
-`seeklink search` and `seeklink index` auto-use a resident daemon when
-`SEEKLINK_VAULT` is set and `--vault` is not passed. The daemon keeps the
-embedder and optional reranker in memory. `seeklink status` and `seeklink get`
-always stay cold-start: status only reads SQLite metadata, and get reads the
-file directly from disk.
+`seeklink search` and single-file `seeklink index path/to/file.md` auto-use a
+resident daemon when `SEEKLINK_VAULT` is set and `--vault` is not passed. The
+daemon keeps the embedder and optional reranker in memory. Full-vault
+`seeklink index` runs in-process so progress stays on stderr and the final
+`Done:` summary stays on stdout. `seeklink status` and `seeklink get` always
+stay cold-start: status only reads SQLite metadata, and get reads the file
+directly from disk.
 
 ## Output
 
@@ -142,10 +156,11 @@ configuration is compatible.
 seeklink daemon --vault PATH
 ```
 
-You normally do not run this directly. `search` and `index` auto-spawn and
-auto-restart the daemon when appropriate. Passing `--vault` to `search` or
-`index` forces a one-shot cold-start path because the daemon is bound to one
-vault at startup.
+You normally do not run this directly. `search` and single-file `index`
+auto-spawn and auto-restart the daemon when appropriate. Full-vault `index`
+still runs in-process for progress output. Passing `--vault` to `search` or
+single-file `index` forces a one-shot cold-start path because the daemon is
+bound to one vault at startup.
 
 ## How Search Works
 
@@ -168,9 +183,10 @@ set `SEEKLINK_EMBEDDING_DIM`, but it must match the embedder output and requires
 a full `seeklink index` rebuild.
 
 On Apple Silicon, SeekLink can rerank candidates with
-`mlx-community/Qwen3-Reranker-0.6B-mxfp8`. Reranking is local and optional. Use
-`--no-rerank` for one query or set `SEEKLINK_RERANKER_MODEL=""` to disable it
-globally.
+`mlx-community/Qwen3-Reranker-0.6B-mxfp8` when installed with `seeklink[mlx]`.
+Reranking is local and optional; if MLX is unavailable, SeekLink falls back to
+first-stage hybrid RRF ranking. Use `--no-rerank` for one query or set
+`SEEKLINK_RERANKER_MODEL=""` to disable it globally.
 
 ## Frontmatter
 
@@ -203,12 +219,13 @@ and a wikilink graph. Delete `.seeklink/` and run `seeklink index` to rebuild.
 | Area | Status |
 |---|---|
 | Python | 3.11, 3.12, 3.13, 3.14 |
+| SQLite | Python `sqlite3` linked against SQLite 3.45+ with FTS5 |
 | OS | macOS and Linux |
 | Windows | Not supported as a first-class path |
 | File format | Markdown `.md` |
 | Vault style | Plain folder or Obsidian-compatible vault |
 | CJK | Native path via jieba, with trigram fallback on static SQLite builds |
-| Reranker | Apple Silicon via MLX; disabled elsewhere |
+| Reranker | Optional `seeklink[mlx]` extra on Apple Silicon; disabled elsewhere |
 | Daemon | Single vault per machine |
 
 ## Not For

README.zh.md

@@ -26,6 +26,17 @@ uv tool install seeklink
 pip install seeklink
 ```
 
+如果要在 Apple Silicon 上启用本地 MLX reranker，请安装可选 extra：
+
+```bash
+uv tool install "seeklink[mlx]"
+# 或者
+pip install "seeklink[mlx]"
+```
+
+SeekLink 需要 Python 的 `sqlite3` 模块链接到 SQLite 3.45 或更新版本，并启用 FTS5。
+`seeklink status --vault PATH` 会检查这个运行时条件；如果 SQLite 太旧，会给出明确错误。
+
 ## 快速开始
 
 ```bash
@@ -45,10 +56,12 @@ seeklink search "agent 记忆系统"
 seeklink get notes/agent-memory-patterns.md:1 -C 20
 ```
 
-当设置了 `SEEKLINK_VAULT` 且不传 `--vault` 时，`seeklink search` 和 `seeklink index`
-会自动使用一个常驻守护进程（daemon），它把嵌入模型和可选的 reranker 保持在内存里，
-避免每次调用都重新加载。`seeklink status` 和 `seeklink get` 始终走冷启动路径：
-status 只读 SQLite 元数据，get 直接从磁盘读文件。
+当设置了 `SEEKLINK_VAULT` 且不传 `--vault` 时，`seeklink search` 和单文件
+`seeklink index path/to/file.md` 会自动使用一个常驻守护进程（daemon），它把嵌入模型
+和可选的 reranker 保持在内存里，避免每次调用都重新加载。全库 `seeklink index`
+会在 CLI 进程内运行，这样进度可以稳定输出到 stderr，最终 `Done:` 摘要保留在 stdout。
+`seeklink status` 和 `seeklink get` 始终走冷启动路径：status 只读 SQLite 元数据，
+get 直接从磁盘读文件。
 
 ## 输出格式
 
@@ -132,8 +145,9 @@ chunker 配置生成的，SeekLink 会重建派生索引内容。单文件索引
 seeklink daemon --vault PATH
 ```
 
-通常不需要手动运行。`search` 和 `index` 在合适的时候会自动启动和重启守护进程。
-给 `search` 或 `index` 传 `--vault` 会强制走一次性冷启动路径，因为守护进程在启动时就绑定到了一个笔记库。
+通常不需要手动运行。`search` 和单文件 `index` 在合适的时候会自动启动和重启守护进程。
+全库 `index` 仍然在 CLI 进程内运行，以便输出进度。给 `search` 或单文件 `index`
+传 `--vault` 会强制走一次性冷启动路径，因为守护进程在启动时就绑定到了一个笔记库。
 
 ## 搜索原理
 
@@ -154,9 +168,10 @@ trigram 分词器，而不是崩溃。
 默认向量维度是 768。高级自定义 embedder 实验可以设置 `SEEKLINK_EMBEDDING_DIM`，
 但它必须和 embedder 的实际输出一致，并且需要重新运行一次完整的 `seeklink index`。
 
-在 Apple Silicon 上，SeekLink 可以用 `mlx-community/Qwen3-Reranker-0.6B-mxfp8`
-对候选结果进行重排序。Reranking 是本地且可选的——用 `--no-rerank` 跳过单次查询，
-或设置 `SEEKLINK_RERANKER_MODEL=""` 全局禁用。
+在 Apple Silicon 上，如果安装了 `seeklink[mlx]`，SeekLink 可以用
+`mlx-community/Qwen3-Reranker-0.6B-mxfp8` 对候选结果进行重排序。Reranking 是本地且
+可选的；如果 MLX 不可用，SeekLink 会回退到第一阶段的混合 RRF 排名。用
+`--no-rerank` 可以跳过单次查询，或设置 `SEEKLINK_RERANKER_MODEL=""` 全局禁用。
 
 ## Frontmatter
 
@@ -188,12 +203,13 @@ SeekLink 在笔记库内写入一个 SQLite 数据库：
 | 维度 | 状态 |
 |---|---|
 | Python | 3.11、3.12、3.13、3.14 |
+| SQLite | Python `sqlite3` 链接到 SQLite 3.45+，并启用 FTS5 |
 | 操作系统 | macOS 和 Linux |
 | Windows | 不作为一等路径支持 |
 | 文件格式 | Markdown `.md` |
 | 笔记库类型 | 普通文件夹或 Obsidian 兼容 vault |
 | 中文/CJK | jieba 路径，静态 SQLite 环境下自动降级为 trigram |
-| Reranker | Apple Silicon 上通过 MLX 可用；其他平台自动禁用 |
+| Reranker | Apple Silicon 上通过可选 `seeklink[mlx]` extra 启用；其他平台自动禁用 |
 | 守护进程 | 一台机器一个笔记库 |
 
 ## 不适用的场景

llms.txt

@@ -24,7 +24,9 @@ Runs on macOS and Linux, Python 3.11+. Indexes any folder of `.md` files. Obsidi
 ## Install
 
 - PyPI: `pip install seeklink` or `uv tool install seeklink`.
+- Apple Silicon reranker: `pip install "seeklink[mlx]"` or `uv tool install "seeklink[mlx]"`.
 - Source: `git clone https://github.com/simonsysun/seeklink && cd seeklink && uv sync --dev`.
+- Runtime requirement: Python's `sqlite3` must link against SQLite >= 3.45 with FTS5. `seeklink status --vault PATH` checks this.
 
 ## Agent contract
 
@@ -42,7 +44,7 @@ seeklink get    PATH:LINE -l N         # read window around a hit
 seeklink get    PATH:LINE -C N         # read N lines before/after a hit
 ```
 
-Set `SEEKLINK_VAULT=<path>` once to omit `--vault` on every call and route through the resident daemon (first call after boot: ~2s; warm: ~1-2s with reranker, ~10ms without). If that env/model config changes, `search` and `index` auto-restart a stale daemon instead of silently serving the old vault.
+Set `SEEKLINK_VAULT=<path>` once to omit `--vault` on repeated calls. `search` and single-file `index path/to/file.md` use the resident daemon; full-vault `index` runs in the CLI process so progress stays on stderr. First-ever model downloads can take much longer than normal daemon startup. Warm search latency depends on whether the optional MLX reranker is installed and active; `search --json` reports whether reranking was active for that query. If vault/model config changes, `search` and single-file `index` auto-restart a stale daemon instead of silently serving the old vault.
 
 ### Output contract
 
@@ -80,5 +82,7 @@ No other codes.
 ### Common failure modes
 
 - Empty results on a fresh vault → index not built yet. Run `seeklink index --vault PATH`.
-- Daemon won't auto-spawn → `--vault` was passed, which intentionally forces cold-start. Without `--vault`, `search` / `index` should auto-spawn and auto-restart stale daemons when `vault` / `embedder` / `reranker` no longer match.
-- Line numbers look wrong → file was edited after indexing. Re-index. `status` prints a freshness warning on cold-start.
+- Reranker unavailable → install `seeklink[mlx]` on Apple Silicon or accept first-stage hybrid RRF ranking. Use `--no-rerank` when a deterministic no-rerank path is preferred.
+- SQLite capability error → use a Python build whose `sqlite3` module links against SQLite >= 3.45 with FTS5.
+- Daemon won't auto-spawn → `--vault` was passed, which intentionally forces cold-start. Without `--vault`, `search` and single-file `index` should auto-spawn and auto-restart stale daemons when `vault` / `embedder` / `reranker` no longer match.
+- Line numbers look wrong → file was edited after indexing. Re-index. `status` prints a freshness warning on cold-start; agents should run `status --json` after long editing sessions.

pyproject.toml

@@ -51,10 +51,16 @@ classifiers = [
 dependencies = [
     "fastembed>=0.7.4",
     "jieba>=0.42.1",
+    "numpy>=1.26",
     "sqlite-vec>=0.1.6",
     "sqlitefts>=1.0.1",
 ]
 
+[project.optional-dependencies]
+mlx = [
+    "mlx-lm>=0.31.2; platform_system == 'Darwin' and platform_machine == 'arm64'",
+]
+
 [project.urls]
 Homepage = "https://github.com/simonsysun/seeklink"
 Repository = "https://github.com/simonsysun/seeklink"

seeklink/__main__.py

@@ -3,16 +3,16 @@
 Subcommands:
   daemon   — run the Unix-socket daemon (eager-loaded models, never exits)
   search   — search the vault (daemon-first; cold-start fallback)
-  index    — index notes (daemon-first; cold-start fallback)
+  index    — index notes (full-vault in-process; single-file daemon-first)
   status   — show vault / index stats (always cold-start; no model load)
   get      — print a line range of a vault file (direct filesystem read)
 
-Dispatch: when `--vault` is not passed to `search` / `index`, the CLI
-tries the daemon socket first (auto-spawning the daemon on first call)
+Dispatch: when `--vault` is not passed to `search` / single-file `index`,
+the CLI tries the daemon socket first (auto-spawning the daemon on first call)
 and falls back to an in-process cold-start if the daemon is unreachable.
 Passing `--vault` always uses cold-start because the daemon is bound to
 a single vault (selected via SEEKLINK_VAULT or cwd at daemon-start time).
-`status` and `get` never route through the daemon.
+Full-vault `index`, `status`, and `get` never route through the daemon.
 
 Agents integrating SeekLink should invoke the CLI via `subprocess` or
 connect to the daemon socket via `seeklink.cli_client` for structured
@@ -508,31 +508,22 @@ def _cmd_search(args: argparse.Namespace) -> None:
 def _cmd_index(args: argparse.Namespace) -> None:
     _setup_logging()
 
-    if _should_use_daemon(args):
+    if args.path and _should_use_daemon(args):
         daemon_args: dict = {}
-        if args.path:
-            daemon_args["path"] = args.path
+        daemon_args["path"] = args.path
         resp = _try_daemon("index", daemon_args)
         if resp is not None:
             result = resp["result"]
-            if args.path:
-                # single-file index: {"path": "...", "status": "indexed"|"skipped"|...}
-                status = result.get("status", "?")
-                if status == "skipped":
-                    print(f"Skipped: {result.get('path', args.path)}")
-                else:
-                    print(f"Indexed: {result.get('path', args.path)} ({status})")
+            # single-file index: {"path": "...", "status": "indexed"|"skipped"|...}
+            status = result.get("status", "?")
+            if status == "skipped":
+                print(f"Skipped: {result.get('path', args.path)}")
             else:
-                stats = result
-                print(
-                    f"Done: {stats.get('ingested', 0)} indexed, "
-                    f"{stats.get('unchanged', 0)} unchanged, "
-                    f"{stats.get('skipped', 0)} skipped, "
-                    f"{stats.get('errors', 0)} errors"
-                )
+                print(f"Indexed: {result.get('path', args.path)} ({status})")
             return
 
-    # Cold-start fallback
+    # Cold-start fallback. Full-vault indexing always stays on this path so
+    # progress can stream to stderr without expanding the daemon protocol.
     from seeklink.app import init_app
     from seeklink.ingest import ingest_file, ingest_vault