docs(notion-search): add /notion-search slash command + CLAUDE.md section

Slash command at custom-skills/31-notion-organizer/commands/notion-search.md
documents the CLI surface and JSON output schema. CLAUDE.md gains a
Semantic Search section explaining the 4-stage pipeline and env var
requirements. requirements.txt notes the optional anthropic SDK
dependency (the skill falls back to the claude CLI if missing).

Final task of Phase 3b-i. 30 tests passing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

custom-skills/31-notion-organizer/code/CLAUDE.md

@@ -16,6 +16,42 @@ python scripts/schema_migrator.py --source [DB_ID] --target [DB_ID] --dry-run
 python scripts/async_organizer.py --database [DB_ID] --action cleanup
 ```
 
+## Semantic Search
+
+```bash
+# Default browse mode (terminal table)
+python scripts/notion_search.py "AI agents in 2026"
+
+# JSON output for piping
+python scripts/notion_search.py "AI agents" --json | jq '.[].id'
+
+# Constrain to specific databases
+python scripts/notion_search.py "MCP" --databases f8f19ede-32bd-43ac-9f60-0651f6f40afe
+
+# Property filter
+python scripts/notion_search.py "MCP" --databases ID \
+  --filter '{"Status": "Done", "Topic": "AI"}'
+
+# Fast mode (skip LLM stages)
+python scripts/notion_search.py "exact term" --no-rerank --no-expand
+```
+
+The search runs four stages:
+
+1. **Expand** — Claude Haiku generates up to 5 query variants (synonyms + cross-language KR↔EN)
+2. **Search** — Notion API searched per variant; results unioned + deduped at 30 candidates
+3. **Enrich** — title, properties, and 200-char excerpt fetched per candidate
+4. **Rerank** — Claude Haiku scores candidates against the *original* query; top N returned
+
+Results are cached for 24h (SHA256 of query + candidate IDs). Bypass with `--no-cache`.
+
+### Requirements
+
+| Env var | Purpose |
+|---------|---------|
+| `NOTION_API_KEY` (or legacy `NOTION_TOKEN`) | Notion integration token |
+| `ANTHROPIC_API_KEY` (optional) | Use Claude SDK directly. If missing, the skill falls back to `claude -p` CLI. |
+
 ## Scripts
 
 | Script | Purpose |

custom-skills/31-notion-organizer/code/scripts/requirements.txt

@@ -24,3 +24,7 @@ tqdm==4.66.1
 
 # Optional: Fuzzy matching for duplicates
 # rapidfuzz==3.5.2
+
+# Optional: required only for direct Anthropic SDK use.
+# If missing, the search skill falls back to `claude -p` CLI.
+anthropic>=0.40.0

custom-skills/31-notion-organizer/commands/notion-search.md

@@ -0,0 +1,50 @@
+---
+description: Search Notion workspace semantically (LLM-expanded + reranked).
+argument-hint: "<query> [--databases ID,...] [--filter JSON] [--limit N] [--no-rerank] [--no-expand] [--no-cache] [--json]"
+---
+
+Search the user's Notion workspace using semantic search powered by Claude Haiku query expansion and result reranking. Closes the gap left by Notion's keyword-only native search — handles synonyms, related concepts, and Korean ↔ English cross-language queries.
+
+## Usage
+
+Run the search script with the user's arguments:
+
+```bash
+cd ~/Project/our-claude-skills/custom-skills/31-notion-organizer/code/scripts
+python3 notion_search.py "$ARGUMENTS"
+```
+
+## Common patterns
+
+- **Default browse mode** (terminal table): `notion-search "AI agents in 2026"`
+- **JSON for piping** (e.g. into the future notion-to-notebooklm push skill): `notion-search "AI agents" --json | jq '.[].id'`
+- **Constrain to specific databases**: `notion-search "MCP" --databases f8f19ede-32bd-43ac-9f60-0651f6f40afe`
+- **Property filter** (per-database mode): `notion-search "MCP" --databases ID --filter '{"Status": "Done"}'`
+- **Fast mode (no LLM)**: `notion-search "exact phrase" --no-rerank --no-expand`
+
+## Requirements
+
+- `NOTION_API_KEY` or `NOTION_TOKEN` env var
+- One of:
+  - `anthropic` SDK installed + `ANTHROPIC_API_KEY` env var, or
+  - Claude Code CLI (`claude` on PATH)
+
+The skill auto-detects which is available; SDK is preferred when both are present.
+
+## Output schema (JSON mode)
+
+```json
+[
+  {
+    "id": "abc-def-...",
+    "url": "https://notion.so/...",
+    "title": "Page title",
+    "relevance": 0.94,
+    "snippet": "Why it matched",
+    "excerpt": "First paragraph text...",
+    "properties": {"Status": "Done", "Topic": ["AI", "MCP"]}
+  }
+]
+```
+
+`relevance` and `snippet` are `null` when `--no-rerank` is set. This schema is the contract for downstream tools (e.g., the future `notion-to-notebooklm` push skill).