feat: add contacts search plugin

docs/cli/contacts.md

@@ -0,0 +1,45 @@
+---
+summary: "CLI reference for `clawdbot contacts` (unified contact graph)"
+read_when:
+  - You want to list or link contacts across channels
+  - You are using the contacts-search plugin
+---
+
+# `clawdbot contacts`
+
+Unified contact graph and identity linking.
+Provided by the [Contacts + Search plugin](/plugins/contacts-search).
+Concept overview: [Contact graph](/contact).
+
+## Examples
+
+```bash
+clawdbot contacts list
+clawdbot contacts list --query "sarah" --platform slack
+clawdbot contacts show <contact-id>
+clawdbot contacts search "alice"
+clawdbot contacts link <primary-id> <secondary-id>
+clawdbot contacts unlink slack U12345678
+clawdbot contacts suggestions
+clawdbot contacts auto-link --dry-run
+clawdbot contacts stats
+clawdbot contacts alias <contact-id> "Alias Name"
+clawdbot contacts alias <contact-id> "Old Alias" --remove
+```
+
+## Commands
+
+- `list`: list contacts (supports `--query`, `--platform`, `--limit`, `--json`).
+- `show <id>`: show a contact + identities (accepts a canonical id or a search query).
+- `search <query>`: search contacts by name/alias/username.
+- `link <primary> <secondary>`: merge two contacts.
+- `unlink <platform> <platformId>`: detach an identity into a new contact.
+- `suggestions`: show link suggestions.
+- `auto-link`: link high-confidence matches (use `--dry-run` to preview).
+- `stats`: store statistics by platform.
+- `alias <contactId> <alias>`: add or remove aliases (`--remove`).
+
+## Notes
+
+- `--platform` expects a channel id (e.g. `slack`, `discord`, `whatsapp`).
+- `unlink` uses the platform id stored on the identity (not the contact id).

docs/cli/index.md

@@ -32,6 +32,8 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`system`](/cli/system)
 - [`models`](/cli/models)
 - [`memory`](/cli/memory)
+- [`contacts`](/cli/contacts) (plugin; if enabled)
+- [`search`](/cli/search) (plugin; if enabled)
 - [`nodes`](/cli/nodes)
 - [`devices`](/cli/devices)
 - [`node`](/cli/node)
@@ -122,6 +124,8 @@ clawdbot [--dev] [--profile <name>] <command>
     status
     index
     search
+  contacts
+  search
   message
   agent
   agents

docs/cli/search.md

@@ -0,0 +1,36 @@
+---
+summary: "CLI reference for `clawdbot search` (cross-platform message search)"
+read_when:
+  - You want to search indexed messages across channels
+  - You are using the contacts-search plugin
+---
+
+# `clawdbot search`
+
+Search indexed messages across channels.
+Provided by the [Contacts + Search plugin](/plugins/contacts-search).
+
+## Examples
+
+```bash
+clawdbot search "meeting tomorrow"
+clawdbot search "deadline" --from alice
+clawdbot search "project" --platform slack --since 1w
+clawdbot search "invoice" --since 2025-12-01 --until 2025-12-31
+clawdbot search "handoff" --limit 50 --json
+```
+
+## Options
+
+- `--from <contact>`: filter by sender name/alias/username or contact id.
+- `--platform <name>`: filter by channel id (e.g. `slack`, `discord`, `whatsapp`).
+- `--since <time>`: start time (`1h`, `2d`, `1w`, `1m`, or ISO date).
+- `--until <time>`: end time (same formats as `--since`).
+- `--limit <n>`: limit results (default `20`).
+- `--json`: raw JSON output.
+
+## Notes
+
+- Results come from the local contacts store (`~/.clawdbot/contacts/contacts.sqlite`).
+- Only inbound messages are indexed (no backfill).
+- Concept overview: [Contact graph](/contact).