Add portable record export across surfaces

CHANGES

@@ -73,6 +73,25 @@ captures a clean SVG without changing the active search. `/keys`, theme
 switching, filtered-row colors, focus repair, and repeated-key quit
 confirmation now behave consistently across the two layouts.
 
+#### Portable record export across CLI, TUI, and MCP (#81)
+
+agentgrep can now turn selected search records into deterministic NDJSON or
+human-readable Markdown without changing the underlying histories. The CLI
+exports matching records to standard output or a chosen file, the HUD exports
+one selected record or its observed thread, and MCP returns a bounded inline
+artifact for existing search refs. In the HUD, `e` or transient
+`/export [PATH]` captures the selected record, then replaces the right detail
+region with a compact destination review without discarding the current search
+or reader state. `e` remains ordinary text when an input is focused.
+
+The review remembers its directory and filename template, previews a
+filesystem-safe local timestamp with a bounded title, and keeps the draft when
+No is selected. Saving refuses accidental replacement. Automatic private
+exports keep canonical-ID filenames, while CLI and MCP remain isolated from
+the TUI preference. Machine clients must opt in before an MCP export includes
+prompt or history bodies. See {ref}`the export guide <cli-export>` for formats,
+selection, and privacy details.
+
 ## agentgrep 0.1.0a50 (2026-08-09)
 
 agentgrep 0.1.0a50 makes the store catalogue describe an agent's whole

docs/_ext/agentgrep_fastmcp.py

@@ -16,6 +16,7 @@
 from agentgrep.mcp import (
     AgentSelector,
     CatalogAgentSelector,
+    ExportRecordsResponse,
     FindToolResponse,
     SearchScopeName,
     SearchToolResponse,
@@ -31,6 +32,7 @@
     StoreDescriptorModel,
     ValidateQueryResponse,
 )
+from agentgrep.mcp.refs import MAX_RECORD_REF_CHARS
 from agentgrep.query.help import query_language_summary
 
 READONLY_TAGS = {"readonly", "agentgrep"}
@@ -126,6 +128,49 @@ async def search(
 )
 
 
+async def export_records(
+    refs: t.Annotated[
+        list[
+            t.Annotated[
+                str,
+                Field(min_length=1, max_length=MAX_RECORD_REF_CHARS),
+            ]
+        ],
+        Field(
+            min_length=1,
+            max_length=20,
+            description="One to 20 opaque refs returned by search.",
+        ),
+    ],
+    format: t.Annotated[  # noqa: A002 - public MCP argument name.
+        t.Literal["ndjson", "markdown"],
+        Field(description="Inline artifact format."),
+    ] = "ndjson",
+    selection: t.Annotated[
+        t.Literal["records", "thread"],
+        Field(description="Export flat records or one observed thread."),
+    ] = "records",
+    include_bodies: t.Annotated[
+        bool,
+        Field(description="Include prompt/history text in the artifact."),
+    ] = False,
+) -> ExportRecordsResponse:
+    """Return selected refs as one NDJSON or Markdown TextContent artifact with structured export metadata."""  # noqa: E501
+    raise NotImplementedError(DOCS_ONLY_MESSAGE)
+
+
+t.cast(t.Any, export_records).__fastmcp__ = types.SimpleNamespace(
+    name="export_records",
+    title="Export Records",
+    tags=READONLY_TAGS | {"export"},
+    annotations=types.SimpleNamespace(
+        readOnlyHint=True,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+)
+
+
 async def find(
     pattern: t.Annotated[
         str | None,
@@ -268,6 +313,7 @@ async def inspect_result(
         str,
         Field(
             min_length=1,
+            max_length=MAX_RECORD_REF_CHARS,
             description="Opaque ref from a search or find result.",
         ),
     ],

docs/cli/export.md

@@ -0,0 +1,144 @@
+(cli-export)=
+
+# agentgrep export
+
+`agentgrep export` turns records matched by the shared search engine into a
+portable artifact without modifying an agent's history. There are exactly two
+formats. Use `ndjson` for scripts and `markdown` for reading or sharing. The
+default format is `ndjson`, and the default sink is standard output. Record
+bodies are included by default because running `export` is an explicit choice.
+
+The command accepts the same agent, scope, case, and query-language filters as
+search. Terms are combined with AND semantics, and the default scope is
+`prompts`. The default limit is `100`; set `--limit` to any value from `1`
+through `1000`.
+
+## TUI reviewed save
+
+Press `e` while an exact selected record has focus in the HUD results or detail
+pane, or type `/export [PATH]`. Both routes open the same reviewed flow in the
+right detail pane. The command text is transient: the pane restores the current
+search term and its exact selection, then returns to the originating focus on
+back or save. An optional path seeds the directory and filename fields.
+
+The pane remembers the export directory and filename template in TUI-private
+user configuration. On first use, the filename template is
+`{date} {time} - {title}.md`; after the preferences are saved successfully, the
+remembered directory and template replace the first-use defaults. Directory
+completion lists existing child directories and accepts a choice with the
+arrow keys and Tab.
+
+The preview freezes local time when the pane opens. The date and time render as
+the filesystem-safe `YYYY-MM-DD HH-MM-SS`, and the title token uses a bounded
+normalized form of the record title without reading its body or source path.
+Submitting the draft shows the directory and exact filename separately. The
+confirmation starts on **No**; No returns to editing with both values intact.
+
+Save is the mutation boundary: No and cancel perform no filesystem mutation.
+An accepted Save creates the exact app-owned default directory privately when
+needed, writes only the reviewed explicit no-clobber artifact, then attempts to
+write the TUI-private preference file. If the artifact name already exists,
+agentgrep returns to the same draft instead of replacing the file or silently
+choosing another name; a later preference failure does not erase a completed
+artifact. The one-shot `/export-thread` command keeps its automatic private
+canonical-ID name. CLI and MCP do not consume the TUI preference: the
+CLI still uses standard output or an explicit `--output` path, and MCP still
+returns a bounded inline artifact, accepts no local destination, and gains no
+filesystem write authority.
+
+## Examples
+
+Export matching prompt records as NDJSON to standard output:
+
+```console
+$ agentgrep export "release notes"
+```
+
+Omit prompt and history text while retaining portable metadata:
+
+```console
+$ agentgrep export "release notes" --no-bodies
+```
+
+Write human-readable Markdown to standard output:
+
+```console
+$ agentgrep export "release notes" --format markdown
+```
+
+Search prompts and conversation records together:
+
+```console
+$ agentgrep export "release notes" --scope all
+```
+
+Write NDJSON to a new relative file:
+
+```console
+$ agentgrep export "release notes" -o records.ndjson
+```
+
+Replace an existing regular file deliberately:
+
+```console
+$ agentgrep export "release notes" -o records.ndjson --force
+```
+
+`-o -` names standard output explicitly. `--force` is invalid with standard
+output; it applies only to a file destination.
+
+## Formats and privacy
+
+NDJSON contains one canonical JSON object per record. Keys and record order
+are stable, and a trailing newline separates every object. Markdown presents
+the same allowlisted metadata as headings and lists. With bodies enabled, it
+places exact valid UTF-8 text in a dynamically sized code fence so backticks in
+the record cannot close the block.
+
+Both formats include the record schema version, agent, store, kind, role,
+timestamp, model, content ID, optional record ID and stability, and optional
+thread ID. `--no-bodies` omits the `text` field or body section entirely.
+Neither format carries source or display paths, titles, session IDs,
+conversation IDs, project origin, or adapter metadata. See {ref}`ADR 0017
+<adr-portable-record-export>` for the exact allowlist and ordering contract.
+
+NDJSON represents lone surrogate code points as JSON escapes, so the artifact
+remains valid UTF-8 and a JSON decoder can recover the original string.
+Markdown cannot represent those values as valid UTF-8 and returns a path-free
+encoding error instead of altering the text.
+
+(cli-export-files)=
+
+## File safety
+
+File output refuses to overwrite an existing destination unless `--force` is
+present. Even with force, the destination must be a regular file: agentgrep
+rejects a symlink, a symlinked parent, and any lexical, resolved, or hard-link
+alias of a source store. The CLI protects every discovered source store,
+including non-default stores and stores that did not match the query, so an
+export cannot replace history by choosing it as the destination.
+
+The completed artifact is installed atomically with private file permissions.
+Errors do not include the destination or source path. These rules preserve
+agentgrep's read-only treatment of Codex, Claude Code, Cursor, and every other
+source store. CLI export writes only the chosen artifact; a successful reviewed
+TUI Save may additionally update its TUI-private preference file as described
+above.
+
+## Exit status
+
+The command exits `0` when at least one record is exported and `1` when the
+search has no matches, producing an empty valid artifact. Invalid arguments,
+source failures, encoding failures, and output failures exit `2` with a
+path-free diagnostic on standard error.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: export
+    :nodescription:
+```

docs/cli/index.md

@@ -46,6 +46,12 @@ Ranked, deduped search grouped by session — best matches first.
 Enumerate on-disk stores with fd-shaped flag grammar.
 :::
 
+:::{grid-item-card} agentgrep export
+:link: export
+:link-type: doc
+Save deterministic NDJSON or Markdown without changing source histories.
+:::
+
 :::{grid-item-card} agentgrep ui
 :link: tui
 :link-type: ref
@@ -172,5 +178,6 @@ $ agentgrep
 grep
 search
 find
+export
 reference
 ```

docs/conf.py

@@ -88,6 +88,8 @@
     "SearchToolResponse",
     "FindRequestModel",
     "FindToolResponse",
+    "ExportRecordsRequest",
+    "ExportRecordsResponse",
     "ResultStatsModel",
     "SearchPageModel",
     "PageInfoModel",