taskflow-doc-search 0.1.0__tar.gz

taskflow_doc_search-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cynthia Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taskflow_doc_search-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include PUBLISHING.md server.json server.py requirements.txt requirements-embeddings.txt
+recursive-include tests *.py
+include scripts/smoke_installed.py

taskflow_doc_search-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: taskflow-doc-search
+Version: 0.1.0
+Summary: MCP server for keyword search over the ai-workspace-kit documentation repos and demo tickets
+License-Expression: MIT
+Project-URL: Repository, https://github.com/cynthiawang109-sudo/ai-workspace-kit
+Project-URL: Documentation, https://github.com/cynthiawang109-sudo/ai-workspace-kit/tree/main/mcp/doc-search
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=4.1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=9.2.0; extra == "dev"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3; extra == "embeddings"
+Dynamic: license-file
+
+# doc-search MCP server
+
+A small [MCP](https://modelcontextprotocol.io) server written with FastMCP.
+It gives an AI coding agent structured access to this workspace's
+documentation and demo tickets — the local, public stand-in for the
+Jira/Confluence side of the original production workspace. Five tools are
+annotated read-only (embeddings maintains a derived local cache); the sixth can only write ticket *drafts* (see below).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_docs(query, limit=8)` | Keyword search across every Markdown doc under `projects/`; title hits ×3, heading hits ×2, body hits ×1; returns path, title, score, snippet |
+| `search_docs_semantic(query, limit=8)` | TF-IDF vector-space search over the same corpus (cosine similarity); returns path, title, score (0–1), snippet |
+| `search_docs_embeddings(query, limit=8)` | Sentence embeddings over heading chunks; returns path, title, cosine score, snippet, heading; caches in `.index/` |
+| `get_doc(path)` | Fetch one document by workspace-relative path (only `projects/` and `tickets/` are readable) |
+| `list_tickets(status?)` | List the pre-TF-115 archive from `tickets/*.md` front matter, optionally filtered by status |
+| `propose_ticket(title, body, priority="medium")` | Write a ticket **draft** to `tickets/drafts/draft-<slug>.md` — the server's only source-content write; it cannot create or modify real tickets |
+
+## Draft-first writes
+
+`propose_ticket` mirrors the production workspace's rule for outward
+writes (there: Jira changes start as drafts a human approves). The
+boundary is enforced by the tool, not by politeness: it writes only
+new files under `tickets/drafts/`, always with `status: draft`, it
+refuses to overwrite an existing draft, and it is annotated as a
+write, so clients ask the user before calling it. `tickets/` is the pre-TF-115
+archive; `list_tickets` never shows drafts as tickets. A human reviews and
+promotes a draft with `scripts/promote-draft.ps1` (or `.sh`), which files
+an Issue instead of moving the file into `tickets/`. Set `AI_WORKSPACE_PROJECT`
+to the workspace Project number, or pass `-Project N` / `--project N`, to
+also add the Issue to the board. Without a Project, the script prints the
+Issue URL and notes that it was not added to a board. The draft is preserved.
+The doc-search server stays credential-free and never calls GitHub.
+
+## Three rungs of document search
+
+1. `search_docs` counts exact term hits with title/heading/body weights.
+   It is predictable for known terms, but repetition can dominate ranking.
+2. `search_docs_semantic` uses TF-IDF cosine similarity over whole documents.
+   It down-weights common terms and balances multi-term queries. Both of
+   these first two rungs are bag-of-words models: neither understands synonyms.
+   They use only the standard library and rebuild their vectors per call.
+3. `search_docs_embeddings` uses sentence-transformers over ATX heading
+   sections, embedding the document title, heading trail and body. It can
+   retrieve paraphrases and synonyms, but relevance is model-dependent.
+   Cosine ranking uses pure Python. A content-hash fingerprint invalidates
+   the derived `.index/` cache when documents or the model change.
+
+- **Local documents**: searches never modify the source documents. Embeddings
+  writes a derived cache; `propose_ticket` writes drafts under the rules above.
+- **No credentials**: keyword and TF-IDF need no network. Embeddings downloads
+  its model once, then runs fully locally.
+- **Client-agnostic**: plain MCP over stdio.
+
+## Setup
+
+```powershell
+cd mcp\doc-search
+python -m venv .venv
+.venv\Scripts\python -m pip install -r requirements.txt pytest
+```
+
+Optional embeddings dependencies (includes torch):
+
+```powershell
+.venv\Scripts\python -m pip install -r requirements-embeddings.txt
+```
+
+`DOC_SEARCH_EMBEDDING_MODEL` overrides the default
+`sentence-transformers/all-MiniLM-L6-v2`. `DOC_SEARCH_EMBEDDER=fake` selects
+only a deterministic hashed-token test double, without semantic understanding.
+
+Evaluate the synced corpus with `python scripts/run_eval.py`; add `--write`
+to record the dated results in [EVAL.md](EVAL.md). The eval is not run in CI.
+
+## Run the tests
+
+```powershell
+.venv\Scripts\python -m pytest
+```
+
+The tests build a throwaway fixture workspace, so they pass whether or not
+`sync` has populated `projects/`.
+
+## Register it
+
+**Codex** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.doc-search]
+command = 'C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe'
+args = ['C:\path\to\ai-workspace-kit\mcp\doc-search\server.py']
+```
+
+**Claude Code**:
+
+```powershell
+claude mcp add doc-search -- C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe C:\path\to\ai-workspace-kit\mcp\doc-search\server.py
+```
+
+The server finds the workspace root from its own location
+(`<root>/mcp/doc-search/server.py`); set `AI_WORKSPACE_ROOT` to override.
+
+
+## Install the distribution
+
+Once published, install with `pip install taskflow-doc-search` (or
+`pip install "taskflow-doc-search[embeddings]"` for sentence embeddings).
+For a local checkout, `pip install .` from this directory works today.
+Run `taskflow-doc-search` with `AI_WORKSPACE_ROOT` set to the absolute path
+of the workspace to search. It serves MCP over stdio; no command arguments
+are needed. The existing `python server.py` launcher and its automatic
+workspace-root detection remain supported.
+
+Release instructions: [PUBLISHING.md](PUBLISHING.md).
+The included [server.json](server.json) is prepared for an optional MCP
+registry listing and has not been published.
+
+<!-- mcp-name: io.github.cynthiawang109-sudo/taskflow-doc-search -->

taskflow_doc_search-0.1.0/PUBLISHING.md

@@ -0,0 +1,84 @@
+# Publishing taskflow-doc-search
+
+Version 0.1.0 is prepared locally; neither PyPI nor MCP registry publication
+has been performed. The PyPI JSON endpoint returned HTTP 404 when preparing
+this package; availability is not a reservation.
+
+The project is licensed under MIT; see the root [LICENSE](../../LICENSE).
+The distribution metadata in `pyproject.toml` declares `MIT`.
+
+## One-time owner setup
+
+1. Sign in to pypi.org and open
+   [Publishing](https://pypi.org/manage/account/publishing/). Add a **pending
+   publisher** using GitHub: project `taskflow-doc-search`, owner
+   `cynthiawang109-sudo`, repository `ai-workspace-kit`, workflow filename
+   `publish-doc-search.yml`, environment `pypi`.
+2. Create the GitHub repository environment `pypi`. Configure release branch/tag
+   restrictions and any required reviewers appropriate for the repository.
+   The environment name must exactly match the PyPI publisher configuration.
+
+The [Trusted Publishing workflow](../../.github/workflows/publish-doc-search.yml)
+uses GitHub OIDC and `id-token: write` only in the publishing job. No PyPI API
+tokens or stored credentials are needed. See the official
+[PyPI Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
+The first successful upload creates the pending PyPI project.
+
+## Local build and inspection
+
+From `mcp/doc-search`, using a development virtual environment:
+
+```sh
+python -m pip install ".[dev]" build twine
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+python -m zipfile -l dist/taskflow_doc_search-0.1.0-py3-none-any.whl
+python -m tarfile -l dist/taskflow_doc_search-0.1.0.tar.gz
+```
+
+Inspect metadata for name, version, license, Python requirement, base dependency,
+`embeddings` extra, README, and `taskflow-doc-search` entry point. Confirm both
+archives contain `doc_search/`; the sdist must contain README and tests.
+Install the wheel into a fresh virtual environment outside the checkout. From
+outside the repository, set `AI_WORKSPACE_ROOT` to the absolute workspace path,
+start `taskflow-doc-search`, and use an MCP client to initialize, list all six
+tools, and call `search_docs` with a known corpus term. Run the included
+client with the fresh environment's Python:
+
+```sh
+python /path/to/mcp/doc-search/scripts/smoke_installed.py /path/to/venv/bin/taskflow-doc-search /path/to/workspace
+```
+
+On Windows the executable is `venv/Scripts/taskflow-doc-search.exe`.
+The client checks all six advertised tools and calls the five read-only tools;
+its embeddings call uses an empty-token query, avoiding downloads and cache
+changes. Embeddings ranking itself is covered by the unit tests with a fake
+embedder. No model download is required for keyword search. Remove the
+temporary environment and build output.
+
+## Cut a release
+
+1. Update the version in `pyproject.toml` and both version fields in
+   `server.json`; complete the local checks above and merge the approved change.
+2. Create a version tag on the intended commit (for example
+   `doc-search-v0.1.0`) and **publish a GitHub Release** for it.
+3. The workflow runs tests, builds and checks sdist/wheel, then publishes via
+   OIDC after any environment review. Inspect the workflow and PyPI files.
+   Ordinary pushes do not publish. Any published GitHub Release triggers this
+   workflow, so coordinate releases for other workspace components accordingly.
+4. `workflow_dispatch` is an explicit manual publishing path for the selected
+   ref; it runs the same checks. Use only for a version not already uploaded:
+   PyPI does not permit replacing an existing release file.
+
+## Optional MCP registry listing
+
+After PyPI publication, validate the included [server.json](server.json) against
+its pinned schema and follow the official
+[MCP registry publishing instructions](https://github.com/modelcontextprotocol/registry/tree/main/docs).
+Authenticate ownership of `io.github.cynthiawang109-sudo`, confirm the package
+README's `mcp-name` ownership marker, and publish with the registry publisher.
+The manifest describes PyPI installation using `uvx`, stdio transport, and the
+required workspace environment variable. Its publisher metadata currently marks
+it `prepared-not-yet-published`; update that status only after actual publication.
+Registry listing is separate from the PyPI workflow and is not automatic.

taskflow_doc_search-0.1.0/README.md

@@ -0,0 +1,120 @@
+# doc-search MCP server
+
+A small [MCP](https://modelcontextprotocol.io) server written with FastMCP.
+It gives an AI coding agent structured access to this workspace's
+documentation and demo tickets — the local, public stand-in for the
+Jira/Confluence side of the original production workspace. Five tools are
+annotated read-only (embeddings maintains a derived local cache); the sixth can only write ticket *drafts* (see below).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_docs(query, limit=8)` | Keyword search across every Markdown doc under `projects/`; title hits ×3, heading hits ×2, body hits ×1; returns path, title, score, snippet |
+| `search_docs_semantic(query, limit=8)` | TF-IDF vector-space search over the same corpus (cosine similarity); returns path, title, score (0–1), snippet |
+| `search_docs_embeddings(query, limit=8)` | Sentence embeddings over heading chunks; returns path, title, cosine score, snippet, heading; caches in `.index/` |
+| `get_doc(path)` | Fetch one document by workspace-relative path (only `projects/` and `tickets/` are readable) |
+| `list_tickets(status?)` | List the pre-TF-115 archive from `tickets/*.md` front matter, optionally filtered by status |
+| `propose_ticket(title, body, priority="medium")` | Write a ticket **draft** to `tickets/drafts/draft-<slug>.md` — the server's only source-content write; it cannot create or modify real tickets |
+
+## Draft-first writes
+
+`propose_ticket` mirrors the production workspace's rule for outward
+writes (there: Jira changes start as drafts a human approves). The
+boundary is enforced by the tool, not by politeness: it writes only
+new files under `tickets/drafts/`, always with `status: draft`, it
+refuses to overwrite an existing draft, and it is annotated as a
+write, so clients ask the user before calling it. `tickets/` is the pre-TF-115
+archive; `list_tickets` never shows drafts as tickets. A human reviews and
+promotes a draft with `scripts/promote-draft.ps1` (or `.sh`), which files
+an Issue instead of moving the file into `tickets/`. Set `AI_WORKSPACE_PROJECT`
+to the workspace Project number, or pass `-Project N` / `--project N`, to
+also add the Issue to the board. Without a Project, the script prints the
+Issue URL and notes that it was not added to a board. The draft is preserved.
+The doc-search server stays credential-free and never calls GitHub.
+
+## Three rungs of document search
+
+1. `search_docs` counts exact term hits with title/heading/body weights.
+   It is predictable for known terms, but repetition can dominate ranking.
+2. `search_docs_semantic` uses TF-IDF cosine similarity over whole documents.
+   It down-weights common terms and balances multi-term queries. Both of
+   these first two rungs are bag-of-words models: neither understands synonyms.
+   They use only the standard library and rebuild their vectors per call.
+3. `search_docs_embeddings` uses sentence-transformers over ATX heading
+   sections, embedding the document title, heading trail and body. It can
+   retrieve paraphrases and synonyms, but relevance is model-dependent.
+   Cosine ranking uses pure Python. A content-hash fingerprint invalidates
+   the derived `.index/` cache when documents or the model change.
+
+- **Local documents**: searches never modify the source documents. Embeddings
+  writes a derived cache; `propose_ticket` writes drafts under the rules above.
+- **No credentials**: keyword and TF-IDF need no network. Embeddings downloads
+  its model once, then runs fully locally.
+- **Client-agnostic**: plain MCP over stdio.
+
+## Setup
+
+```powershell
+cd mcp\doc-search
+python -m venv .venv
+.venv\Scripts\python -m pip install -r requirements.txt pytest
+```
+
+Optional embeddings dependencies (includes torch):
+
+```powershell
+.venv\Scripts\python -m pip install -r requirements-embeddings.txt
+```
+
+`DOC_SEARCH_EMBEDDING_MODEL` overrides the default
+`sentence-transformers/all-MiniLM-L6-v2`. `DOC_SEARCH_EMBEDDER=fake` selects
+only a deterministic hashed-token test double, without semantic understanding.
+
+Evaluate the synced corpus with `python scripts/run_eval.py`; add `--write`
+to record the dated results in [EVAL.md](EVAL.md). The eval is not run in CI.
+
+## Run the tests
+
+```powershell
+.venv\Scripts\python -m pytest
+```
+
+The tests build a throwaway fixture workspace, so they pass whether or not
+`sync` has populated `projects/`.
+
+## Register it
+
+**Codex** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.doc-search]
+command = 'C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe'
+args = ['C:\path\to\ai-workspace-kit\mcp\doc-search\server.py']
+```
+
+**Claude Code**:
+
+```powershell
+claude mcp add doc-search -- C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe C:\path\to\ai-workspace-kit\mcp\doc-search\server.py
+```
+
+The server finds the workspace root from its own location
+(`<root>/mcp/doc-search/server.py`); set `AI_WORKSPACE_ROOT` to override.
+
+
+## Install the distribution
+
+Once published, install with `pip install taskflow-doc-search` (or
+`pip install "taskflow-doc-search[embeddings]"` for sentence embeddings).
+For a local checkout, `pip install .` from this directory works today.
+Run `taskflow-doc-search` with `AI_WORKSPACE_ROOT` set to the absolute path
+of the workspace to search. It serves MCP over stdio; no command arguments
+are needed. The existing `python server.py` launcher and its automatic
+workspace-root detection remain supported.
+
+Release instructions: [PUBLISHING.md](PUBLISHING.md).
+The included [server.json](server.json) is prepared for an optional MCP
+registry listing and has not been published.
+
+<!-- mcp-name: io.github.cynthiawang109-sudo/taskflow-doc-search -->

taskflow_doc_search-0.1.0/doc_search/__init__.py

@@ -0,0 +1 @@
+"""Documentation search tools served over MCP stdio."""

taskflow_doc_search-0.1.0/doc_search/embeddings.py

@@ -0,0 +1,192 @@
+"""Section embeddings with a content-validated, local derived index.
+
+Importing this module does not import sentence-transformers or torch.
+The fake embedder is a deterministic test double, not a semantic model.
+"""
+import hashlib
+import json
+import math
+import os
+import re
+from functools import lru_cache
+from pathlib import Path
+
+from .server import ROOT
+
+# Keep the checkout cache beside the compatibility launcher, even when the
+# workspace is overridden. Installed packages cache under the workspace,
+# avoiding writes to site-packages.
+_SERVER_DIR = Path(__file__).resolve().parents[1]
+INDEX_DIR = (
+    _SERVER_DIR if (_SERVER_DIR / "server.py").is_file()
+    else ROOT / "mcp" / "doc-search"
+) / ".index"
+DEFAULT_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+class _FakeEmbedder:
+    def encode(self, texts):
+        from .server import _tokenize
+
+        vectors = []
+        for text in texts:
+            vector = [0.0] * 64
+            for token in _tokenize(text):
+                slot = int(hashlib.sha256(token.encode("utf-8")).hexdigest(), 16) % 64
+                vector[slot] += 1.0
+            norm = math.sqrt(sum(v * v for v in vector))
+            vectors.append([v / norm for v in vector] if norm else vector)
+        return vectors
+
+
+class _RealEmbedder:
+    def __init__(self, model):
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as exc:
+            raise RuntimeError(
+                "sentence-transformers is not installed; "
+                "install the optional embeddings dependencies with: "
+                "pip install taskflow-doc-search[embeddings]"
+            ) from exc
+        self.model = SentenceTransformer(model)
+
+    def encode(self, texts):
+        return self.model.encode(texts, normalize_embeddings=True).tolist()
+
+
+@lru_cache(maxsize=2)
+def _embedder(name, model):
+    if name == "fake":
+        return _FakeEmbedder()
+    if name != "sentence-transformers":
+        raise ValueError(f"unknown DOC_SEARCH_EMBEDDER: {name}")
+    return _RealEmbedder(model)
+
+
+def get_embedder():
+    """Return the configured embedder, loading the real model only on demand."""
+    return _embedder(
+        os.environ.get("DOC_SEARCH_EMBEDDER", "sentence-transformers"),
+        os.environ.get("DOC_SEARCH_EMBEDDING_MODEL", DEFAULT_MODEL),
+    )
+
+
+def chunk_document(path, text):
+    """Split ATX sections into body chunks carrying their full heading trail.
+
+    The preamble uses the document title. Empty section bodies are retained
+    so a heading alone remains searchable. Fenced code is treated as body.
+    """
+    from .server import ROOT, _doc_title
+
+    path = Path(path)
+    title = _doc_title(text, path)
+    relative = path.relative_to(ROOT).as_posix()
+    chunks, trail, body = [], [], []
+    heading = title
+    fence = None
+
+    def flush():
+        chunks.append({"path": relative, "title": title,
+                       "heading": heading, "text": "\n".join(body).strip()})
+
+    for line in text.splitlines():
+        marker = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line)
+        if marker:
+            run, tail = marker.groups()
+            if fence is None:
+                fence = run
+            elif run[0] == fence[0] and len(run) >= len(fence) and not tail.strip():
+                fence = None
+            body.append(line)
+            continue
+        match = None if fence else re.match(r"^ {0,3}(#{1,6})(?:[ \t]+(.*)|$)", line)
+        if match:
+            if trail or any(part.strip() for part in body):
+                flush()
+            level = len(match[1])
+            label = re.sub(r"[ \t]+#+[ \t]*$", "", match[2] or "").strip()
+            trail = [(n, label_) for n, label_ in trail if n < level]
+            trail.append((level, label))
+            heading = " > ".join(label_ for _, label_ in trail)
+            body = []
+        else:
+            body.append(line)
+    if trail or any(part.strip() for part in body):
+        flush()
+    return chunks
+
+
+def build_index(documents, manifest):
+    """Embed a byte snapshot of the corpus and persist its derived cache."""
+    chunks = []
+    for path, content in documents:
+        chunks.extend(chunk_document(path, content.decode("utf-8", errors="replace")))
+    if chunks:
+        vectors = get_embedder().encode([
+            f"{c['title']} > {c['heading']}\n{c['text']}" for c in chunks
+        ])
+        for chunk, vector in zip(chunks, vectors):
+            chunk["embedding"] = vector
+    INDEX_DIR.mkdir(parents=True, exist_ok=True)
+    (INDEX_DIR / "chunks.jsonl").write_text(
+        "".join(json.dumps(c, ensure_ascii=False) + "\n" for c in chunks),
+        encoding="utf-8",
+    )
+    (INDEX_DIR / "manifest.json").write_text(
+        json.dumps({**manifest, "chunk_count": len(chunks)}, indent=2), encoding="utf-8"
+    )
+    return chunks
+
+
+def load_index():
+    """Reuse the cache only when corpus bytes, model and embedder match."""
+    from .server import ROOT, _iter_docs
+
+    documents = [(p, p.read_bytes()) for p in _iter_docs()]
+    hashes = sorted((p.relative_to(ROOT).as_posix(), hashlib.sha256(b).hexdigest())
+                    for p, b in documents)
+    manifest = {
+        "model": os.environ.get("DOC_SEARCH_EMBEDDING_MODEL", DEFAULT_MODEL),
+        "embedder": os.environ.get("DOC_SEARCH_EMBEDDER", "sentence-transformers"),
+        "fingerprint": hashlib.sha256(json.dumps(hashes).encode("utf-8")).hexdigest(),
+    }
+    try:
+        saved = json.loads((INDEX_DIR / "manifest.json").read_text(encoding="utf-8"))
+        if all(saved.get(k) == v for k, v in manifest.items()):
+            chunks = [json.loads(line) for line in
+                      (INDEX_DIR / "chunks.jsonl").read_text(encoding="utf-8").splitlines()]
+            if len(chunks) == saved.get("chunk_count"):
+                return chunks
+    except (OSError, ValueError):
+        pass
+    return build_index(documents, manifest)
+
+
+def search(query, limit=8):
+    """Rank section chunks by pure-Python cosine; cache writes are local."""
+    from .server import _tokenize
+
+    if limit <= 0 or not _tokenize(query):
+        return []
+    chunks = load_index()
+    if not chunks:
+        return []
+    vector = get_embedder().encode([query])[0]
+    norm = math.sqrt(sum(v * v for v in vector))
+    results = []
+    for chunk in chunks:
+        other = chunk["embedding"]
+        denominator = norm * math.sqrt(sum(v * v for v in other))
+        score = round(sum(a * b for a, b in zip(vector, other)) / denominator, 4) if denominator else 0
+        if not score:
+            continue
+        results.append({
+            "path": chunk["path"], "title": chunk["title"], "score": score,
+            "snippet": next((line.strip()[:200] for line in chunk["text"].splitlines()
+                             if line.strip()), ""),
+            "heading": chunk["heading"],
+        })
+    results.sort(key=lambda r: (-r["score"], r["path"], r["heading"]))
+    return results[:limit]