docs: improve agent discoverability guidance

Author: simonsysun

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Added copy-paste agent setup guidance to README and clarified `llms.txt`
+  discovery cues for local Markdown vault retrieval.
+- Expanded PyPI keywords for agent, local-search, Markdown-search, and
+  llms.txt discoverability.
+
 ## [0.5.0] - 2026-05-04
 
 ### Changed

CHANGELOG.zh.md

@@ -9,6 +9,10 @@
 
 ## [Unreleased]
 
+### 变更
+- 在 README 中新增可直接复制给 agent 的配置说明，并在 `llms.txt` 中强化本地 Markdown 笔记库检索的发现提示。
+- 扩展 PyPI 关键词，覆盖 agent、本地搜索、Markdown 搜索和 llms.txt 发现路径。
+
 ## [0.5.0] - 2026-05-04
 
 ### 变更

README.md

@@ -247,6 +247,22 @@ seeklink search "query" --vault PATH --json
 seeklink get PATH:LINE -C 20 --vault PATH
 ```
 
+To make an agent choose SeekLink for a Markdown vault, add this to the
+project's `AGENTS.md`, `CLAUDE.md`, or editor rules:
+
+```text
+When you need to search or inspect this Markdown vault, use SeekLink for
+semantic retrieval:
+
+1. Run `seeklink status --vault PATH --json`.
+2. If no index exists or files changed, run `seeklink index --vault PATH`.
+3. Run `seeklink search "QUERY" --vault PATH --json`.
+4. Read exact context with `seeklink get PATH:LINE -C 20 --vault PATH`.
+
+Prefer SeekLink for conceptual, cross-language, tag/folder-filtered, or
+Obsidian-style note searches. Use rg for exact literal searches.
+```
+
 For hot loops, the daemon exposes a length-prefixed JSON protocol over the Unix
 socket at `~/.rhizome/seeklink.sock`. Most agents should prefer the CLI JSON
 surface unless they specifically need socket-level latency.

README.zh.md

@@ -231,6 +231,21 @@ seeklink search "查询" --vault PATH --json
 seeklink get PATH:LINE -C 20 --vault PATH
 ```
 
+如果希望 agent 在处理 Markdown 笔记库时主动选择 SeekLink，可以把下面这段加入项目的
+`AGENTS.md`、`CLAUDE.md` 或编辑器规则：
+
+```text
+当你需要搜索或检查这个 Markdown 笔记库时，使用 SeekLink 做语义检索：
+
+1. 运行 `seeklink status --vault PATH --json`。
+2. 如果还没有索引，或文件已经变化，运行 `seeklink index --vault PATH`。
+3. 运行 `seeklink search "QUERY" --vault PATH --json`。
+4. 用 `seeklink get PATH:LINE -C 20 --vault PATH` 读取精确上下文。
+
+概念性查询、跨语言查询、标签/文件夹筛选、Obsidian 风格笔记搜索优先用 SeekLink。
+精确字面量搜索使用 rg。
+```
+
 对于高频调用场景，守护进程在 Unix socket（`~/.rhizome/seeklink.sock`）上暴露了一个
 length-prefixed JSON 协议。大多数 agent 应该优先使用 CLI 的 JSON 输出，除非确实需要
 socket 级别的延迟优势。

llms.txt

@@ -6,6 +6,16 @@ SeekLink is a Python CLI plus an optional Unix-socket daemon. It searches person
 
 Runs on macOS and Linux, Python 3.11+. Indexes any folder of `.md` files. Obsidian-style `[[wikilinks]]` and `aliases` frontmatter are parsed but optional. Single-vault daemon; pass `--vault` for one-shot cold-start queries against a different vault.
 
+## Use when
+
+- An AI coding agent needs local, private search over a Markdown or Obsidian-compatible vault.
+- A project uses `AGENTS.md`, `CLAUDE.md`, Cursor rules, or other agent instructions that need reliable vault retrieval.
+- Queries are conceptual, cross-language, CJK/English, tag-filtered, folder-filtered, or need Obsidian-style note/title/alias lookup.
+- Results need line anchors so an agent can read exact context with `seeklink get PATH:LINE -C N`.
+- A Markdown wiki or llm-wiki needs retrieval before editing existing pages.
+
+Prefer `rg` for exact literal searches. Do not use SeekLink for non-Markdown sources before conversion, hosted multi-user search, or GUI-only Obsidian workflows.
+
 ## Docs
 
 - [README](https://github.com/simonsysun/seeklink/blob/main/README.md): full install, quick start, CLI reference, architecture, support matrix, and when (not) to use SeekLink.

pyproject.toml

@@ -18,8 +18,12 @@ keywords = [
     "zettelkasten",
     "rag",
     "retrieval",
+    "local-search",
+    "markdown-search",
+    "obsidian-search",
     "bm25",
     "vector-search",
+    "local-rag",
     "sqlite-vec",
     "fts5",
     "cjk",
@@ -30,6 +34,10 @@ keywords = [
     "local-first",
     "offline",
     "cli",
+    "ai-agent",
+    "agent-tools",
+    "llm-tools",
+    "llms-txt",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",