diff --git a/AGENTS.md b/AGENTS.md
index d0660a28..8c312ddd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -90,3 +90,10 @@
 - Confirm installation with `bunx skills list --global`. If Bun or network access is unavailable, continue with repository-native tools instead of blocking delivery.
 - Treat ALGAL receipts as execution evidence, not provider attestation, and preserve the repository's normal verification and release gates.
 <!-- algal-skills:end -->
+
+## Wordcell search
+
+- From the repository root, use `bun run kb:search "query" --json` for ordinary searches of this public `kb/` vault. Wordcell 0.22.0 retrieves local exact candidates, then asks TypeSafe to rerank at most 25 candidates. Read the returned Markdown and its linked sources before relying on a result.
+- Hosted ranking sends the query and each candidate's identifier, title, vault-relative path, and at most 512 UTF-8 bytes of snippet text to TypeSafe, with provider input-token charges. Keep confidential queries and unpublished or private notes on the local path.
+- Use `bun run kb:search:local "query" --json` for local-only search. Keep credentials outside the repository: `TYPESAFE_API_KEY`, `TYPESAFE_API_KEY_FILE`, or the owner-only `~/.config/wordcell/typesafe-api-key` file.
+- Inspect the `rerank` lane status and its structured receipt for attempted requests, elapsed time, known usage, and incomplete usage. Missing credentials or provider failures retain baseline ordering; a successful exit does not prove reranking occurred. Treat ranking probabilities as navigation signals, not evidence of truth.
diff --git a/package.json b/package.json
index f38b4085..94ed0073 100644
--- a/package.json
+++ b/package.json
@@ -196,6 +196,8 @@
     "LICENSE"
   ],
   "scripts": {
+    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
+    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz wordcell search --root kb --mode exact",
     "build": "bun run build:sdk && bun run build:desktop && bun run build:web",
     "build:sdk": "bun -e 'await (await import(\"node:fs/promises\")).rm(\"./dist\", { recursive: true, force: true })' && bun build ./src/index.ts ./src/cli.ts ./src/code/index.ts ./src/code/advanced.ts ./src/generate.ts ./src/host-resources.ts ./src/operations.ts ./src/workflow.ts ./src/vectorize/worker.ts --outdir ./dist --root ./src --target bun --format esm --splitting --packages external --minify-whitespace --emit-dce-annotations",
     "build:desktop": "bun run build:desktop:cli",