tony · tony · May 31, 2026 · May 31, 2026 · May 31, 2026 · May 31, 2026
diff --git a/CHANGES b/CHANGES
@@ -42,6 +42,47 @@ $ uvx --from 'agentgrep' --prerelease allow python
 
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+agentgrep 0.1.0a14 makes prompt search the default search scope and
+requires explicit opt-in for full conversation records. This release
+renames the search breadth selector to `scope` across the CLI, MCP,
+query language, and Python library so prompt-history logs are no
+longer confused with conversation history.
+
+### Breaking changes
+
+Search and grep now use `--scope`, not `--type`, for prompt versus
+conversation breadth. `find --type` is unchanged because it still
+filters discovered files and stores.
+
+Before:
+
+```console
+$ agentgrep grep "release notes" --type history
+```
+
+After:
+
+```console
+$ agentgrep grep "release notes" --scope conversations
+```
+
+MCP search requests now send `scope` instead of `search_type`, and
+library callers construct {class}`~agentgrep.SearchQuery` with
+`scope=...`.
+
+### What's new
+
+#### Search scope vocabulary (#38)
+
+Bare CLI and MCP searches now run in `prompts` scope. Dedicated
+prompt-history stores are included in that default, and transcript-only
+backends still project user turns into prompt scope when an app does
+not keep a separate prompt log.
+
+Full conversation, session, assistant, tool, and event records require
+`--scope conversations`, `scope="conversations"`, or `scope:conversations`.
+Use `all` to search prompts and conversations together.
+
 ## agentgrep 0.1.0a13 (2026-05-31)
 
 agentgrep 0.1.0a13 adds OpenCode (anomalyco/opencode, formerly

diff --git a/README.md b/README.md
@@ -4,8 +4,8 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/agentgrep.svg)](https://pypi.org/project/agentgrep/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Read-only search for local AI agent prompts and history across Codex,
-Claude Code, Cursor, Gemini, Grok, Pi, and OpenCode.
+Read-only search for local AI agent prompts and opt-in conversations
+across Codex, Claude Code, Cursor, Gemini, Grok, Pi, and OpenCode.
 
 `agentgrep` provides a CLI and an MCP server over the same discovery + parsing layer:
 
@@ -29,12 +29,18 @@ snippets live in the
 
 ## CLI quickstart
 
-Search prompts and history across every configured agent:
+Search user prompts across every configured agent:
 
 ```console
 $ agentgrep grep "deploy"
 ```
 
+Search full conversations explicitly:
+
+```console
+$ agentgrep grep "deploy" --scope conversations
+```
+
 Stream JSON so a non-MCP agent or shell pipeline can consume the
 results:
 
@@ -73,7 +79,7 @@ import agentgrep
 backends = agentgrep.select_backends()
 query = agentgrep.SearchQuery(
     terms=("hello",),
-    search_type="all",
+    scope="all",
     any_term=False,
     regex=False,
     case_sensitive=False,

diff --git a/docs/_ext/agentgrep_fastmcp.py b/docs/_ext/agentgrep_fastmcp.py
@@ -16,8 +16,8 @@
 from agentgrep.mcp import (
     AgentSelector,
     FindToolResponse,
+    SearchScopeName,
     SearchToolResponse,
-    SearchTypeName,
 )
 from agentgrep.mcp.models import (
     DiscoverySummaryResponse,
@@ -45,9 +45,9 @@ async def search(
         AgentSelector,
         Field(description="Limit search to one agent or search all agents."),
     ] = "all",
-    search_type: t.Annotated[
-        SearchTypeName,
-        Field(description="Search prompts, history, or both."),
+    scope: t.Annotated[
+        SearchScopeName,
+        Field(description="Search prompts, conversations, or both."),
     ] = "prompts",
     case_sensitive: t.Annotated[
         bool,
@@ -62,7 +62,7 @@ async def search(
         ),
     ] = 20,
 ) -> SearchToolResponse:
-    """Search normalized prompts or history across local agent stores."""
+    """Search normalized prompts or conversations across local agent stores."""
     raise NotImplementedError(DOCS_ONLY_MESSAGE)
 
 

diff --git a/docs/_ext/widgets/library_install.py b/docs/_ext/widgets/library_install.py
@@ -90,7 +90,7 @@ class Panel:
 backends = agentgrep.select_backends()
 query = agentgrep.SearchQuery(
     terms=("hello",),
-    search_type="all",
+    scope="all",
     any_term=False,
     regex=False,
     case_sensitive=False,

diff --git a/docs/backends/index.md b/docs/backends/index.md
@@ -72,6 +72,11 @@ stores expose safe structural samples for `inspect_record_sample`, but
 they still stay outside default search. Private stores are documented
 but intentionally not enumerated from disk.
 
+Search scope is record-level. `--scope prompts` is the default and
+includes dedicated prompt-history logs plus user turns projected from
+transcript-only backends. Full conversation, assistant, tool, and event
+records require `--scope conversations` or `--scope all`.
+
 ## Version detection
 
 Source discovery reports version metadata separately from record

diff --git a/docs/backends/opencode.md b/docs/backends/opencode.md
@@ -26,6 +26,8 @@ rather than a JSONL-transcript backend.
 A relational `session → message → part` schema (Drizzle). A conversation
 turn is reconstructed by joining a `part` row up to its `message` (for
 the role) and `session` (for the title and working directory).
+User text parts participate in the default prompt scope; assistant and
+reasoning parts require `--scope conversations` or `--scope all`.
 
 `session` table — one row per session:
 

diff --git a/docs/backends/pi.md b/docs/backends/pi.md
@@ -16,6 +16,9 @@ named `<iso-timestamp>_<session-uuid>.jsonl`.
 Unlike Codex or Grok, pi keeps no separate prompt-history log and no
 SQLite session index — the session transcript is the entire searchable
 surface, which makes pi the structural twin of the Claude Code backend.
+agentgrep projects user turns from that transcript into the default
+prompt scope; assistant, tool, summary, and branch records require
+`--scope conversations` or `--scope all`.
 
 The optional `PI_CODING_AGENT_SESSION_DIR` override points at the
 sessions directory directly. When it is set, pi writes session files

diff --git a/docs/cli/grep.md b/docs/cli/grep.md
@@ -2,10 +2,11 @@
 
 # agentgrep grep
 
-The `agentgrep grep` command searches normalized prompt and history
-records with the flag grammar and output behavior of `ripgrep` and
+The `agentgrep grep` command searches normalized prompt records by
+default, with explicit scope controls for conversation records. It
+uses the flag grammar and output behavior of `ripgrep` and
 `the_silver_searcher`. If you already reach for `rg -i` or `ag -F`
-without thinking, the same flags work here against your AI history.
+without thinking, the same flags work here against your AI prompts.
 
 Defaults follow rg: smart-case (case-insensitive unless the pattern
 contains uppercase), regex pattern interpretation, color on TTY,
@@ -32,10 +33,10 @@ Force case-insensitive matching:
 $ agentgrep grep -i 'serene bliss'
 ```
 
-Treat the pattern as a literal substring (not a regex):
+Search full conversation records with a literal substring:
 
 ```console
-$ agentgrep grep -F --type history 'v1.2.3'
+$ agentgrep grep -F --scope conversations 'v1.2.3'
 ```
 
 Stream an rg-style event stream as JSON:
@@ -104,6 +105,14 @@ The eager output modes (`--json`, `-c`, `-l`, `-v`) buffer
 because their output shape needs the final tally or cross-record
 deduplication.
 
+## Search scope
+
+`grep` searches `--scope prompts` by default. That includes dedicated
+prompt-history logs and user turns projected from transcript-only
+stores. Pass `--scope conversations` for full conversation, session,
+assistant, tool, and event records, or `--scope all` to search both
+surfaces together.
+
 ## Progress
 
 The stderr progress spinner (when stderr is a TTY) lets you know a
@@ -190,7 +199,7 @@ question that the engine's current output supports. Tracking issue:
 By default `grep` deduplicates matches by session so a single
 conversation that repeats near-identical text doesn't drown the
 output. This is the one place where `agentgrep grep` deliberately
-diverges from `rg`'s raw behavior — AI history stores often replay
+diverges from `rg`'s raw behavior — AI conversation stores often replay
 the same message text many times across one session, which makes the
 raw rg view noisier than a filesystem grep.
 

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -89,10 +89,10 @@ Combine multiple patterns with an agent filter:
 $ agentgrep grep serene bliss --agent codex
 ```
 
-Stream history matches as NDJSON:
+Stream full-conversation matches as NDJSON:
 
 ```console
-$ agentgrep grep prompt history --type history --ndjson
+$ agentgrep grep prompt history --scope conversations --ndjson
 ```
 
 List stores for one agent as JSON:

diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
@@ -14,15 +14,17 @@ $ uv run agentgrep grep "cache" --agent codex
 
 Supported agents are `codex`, `claude`, `cursor-cli`, `cursor-ide`, `gemini`, `grok`, `pi`, and `opencode`. Omitting `--agent` searches all supported agents.
 
-## Search type
+## Search scope
 
-Use `--type` to choose records:
+Search and grep default to prompt scope: user-authored prompts,
+including dedicated prompt-history logs and user turns projected from
+transcript-only stores. Use `--scope` to opt into broader records:
 
 ```console
-$ uv run agentgrep grep "docs deploy" --type prompts
+$ uv run agentgrep grep "docs deploy" --scope conversations
 ```
 
-Allowed values are `prompts`, `history`, and `all`.
+Allowed values are `prompts`, `conversations`, and `all`.
 
 ## Output
 

diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -13,9 +13,9 @@ From the repository root:
 $ uv sync --all-groups
 ```
 
-## 2. Search local agent history
+## 2. Search local agent prompts
 
-Search all supported stores:
+Search prompt-scope records across supported stores:
 
 ```console
 $ uv run agentgrep grep "release notes"
@@ -24,7 +24,13 @@ $ uv run agentgrep grep "release notes"
 Search one agent's prompt records:
 
 ```console
-$ uv run agentgrep grep "deploy docs" --agent codex --type prompts
+$ uv run agentgrep grep "deploy docs" --agent codex
+```
+
+Search full conversation records explicitly:
+
+```console
+$ uv run agentgrep grep "deploy docs" --agent codex --scope conversations
 ```
 
 ## 3. Inspect the stores

diff --git a/docs/index.md b/docs/index.md
@@ -2,7 +2,7 @@
 
 # agentgrep
 
-Read-only search for local AI agent prompts and history across Codex, Claude Code, Cursor, Gemini, Grok, Pi, and OpenCode.
+Read-only search for local AI agent prompts and opt-in conversations across Codex, Claude Code, Cursor, Gemini, Grok, Pi, and OpenCode.
 
 ```{warning}
 **Pre-alpha.** APIs may change. [Feedback welcome](https://github.com/tony/agentgrep/issues).
@@ -34,7 +34,7 @@ Search and find from the terminal. Pipe `--json` / `--ndjson` for scripts and ag
 :::{grid-item-card} TUI
 :link: tui/index
 :link-type: doc
-Interactive Textual explorer for browsing prompts and history.
+Interactive Textual explorer for browsing prompt and conversation records.
 :::
 
 :::{grid-item-card} MCP
@@ -73,7 +73,7 @@ Per-agent store layouts, record schemas, and support matrix.
 
 ### Prompt Search
 
-Find full prompt and history records by literal term or regular expression.
+Find prompt records by literal term or regular expression, with explicit opt-in for conversations.
 
 <a class="reference internal" href="mcp/tools/#fastmcp-tool-search"><code>search</code></a>
 
@@ -87,7 +87,7 @@ List the stores, session files, and SQLite databases that agentgrep can read.
 
 Use prompts for common agent workflows:
 
-{ref}`fastmcp-prompt-search-prompts` · {ref}`fastmcp-prompt-search-history` · {ref}`fastmcp-prompt-inspect-stores`
+{ref}`fastmcp-prompt-search-prompts` · {ref}`fastmcp-prompt-search-conversations` · {ref}`fastmcp-prompt-inspect-stores`
 
 ```{toctree}
 :hidden:

diff --git a/docs/library/examples.md b/docs/library/examples.md
@@ -22,7 +22,7 @@ $ uv run agentgrep find cursor-cli --agent cursor-cli --json
   "arguments": {
     "terms": ["database migration"],
     "agent": "codex",
-    "search_type": "prompts",
+    "scope": "prompts",
     "limit": 10
   }
 }

diff --git a/docs/library/query-language.md b/docs/library/query-language.md
@@ -2,7 +2,7 @@
 
 # Query language
 
-`agentgrep grep`, `agentgrep grep`, and `agentgrep find` accept a
+`agentgrep search`, `agentgrep grep`, and `agentgrep find` accept a
 Lucene-style query language for inline field predicates, boolean
 composition, and date ranges. The same syntax works across all three
 subcommands; each interprets the predicates against its natural
@@ -64,7 +64,7 @@ predicate has admitted the source.
 
 | Field | Kind | Notes |
 |---|---|---|
-| `type` | enum | One of `prompts`, `history` |
+| `scope` | enum | One of `prompts`, `conversations`, `all` |
 | `timestamp` | date | Record timestamp; supports comparison + range; alias `date` |
 | `model` | string | Substring against `record.model` |
 | `role` | string | Substring against `record.role` |
@@ -144,6 +144,14 @@ $ agentgrep grep 'timestamp:[2026-01 TO 2026-03] model:claude'
 
 Records in Q1 2026 from any claude-* model.
 
+```console
+$ agentgrep grep 'scope:conversations pytest'
+```
+
+Conversation-scope records mentioning "pytest". A bare search uses
+prompt scope; `scope:conversations` is the inline form of
+`--scope conversations`.
+
 ```console
 $ agentgrep find path:~/.codex agent:codex
 ```
@@ -167,7 +175,7 @@ $ agentgrep grep --agent codex agent:claude bliss
 agentgrep grep: error: cannot combine --agent flag with agent: field predicate; pick one syntax
 ```
 
-Currently checked: `--agent` × `agent:`, `--type` × `type:`. Other
+Currently checked: `--agent` × `agent:`, `--scope` × `scope:`. Other
 flags don't yet have query-field counterparts.
 
 ## Performance

diff --git a/docs/library/tutorial.md b/docs/library/tutorial.md
@@ -13,21 +13,21 @@ $ uv run agentgrep grep "draft pr"
 Search only Codex prompts:
 
 ```console
-$ uv run agentgrep grep "draft pr" --agent codex --type prompts
+$ uv run agentgrep grep "draft pr" --agent codex
 ```
 
-## Search history
+## Search conversations
 
-Search assistant and command history:
+Search assistant, tool, event, and full conversation records:
 
 ```console
-$ uv run agentgrep grep "pytest" --type history
+$ uv run agentgrep grep "pytest" --scope conversations
 ```
 
-Search prompts and history together:
+Search prompts and conversations together:
 
 ```console
-$ uv run agentgrep grep "docs" --type all
+$ uv run agentgrep grep "docs" --scope all
 ```
 
 ## Combine terms

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1,7 +1,7 @@
 {
   "name": "agentgrep",
   "short_name": "agentgrep",
-  "description": "Read-only search for local AI agent prompts and history (Codex, Claude, Cursor)",
+  "description": "Read-only search for local AI agent prompts and opt-in conversations",
   "theme_color": "#2196f3",
   "background_color": "#fff",
   "display": "browser",