Deterministic insights and review-only suggestions

docs/_ext/agentgrep_fastmcp.py

@@ -18,8 +18,10 @@
     CatalogAgentSelector,
     DbStatusModel,
     FindToolResponse,
+    InsightsListResponse,
     SearchScopeName,
     SearchToolResponse,
+    SuggestionsListResponse,
 )
 from agentgrep.mcp._library import SearchEffortName
 from agentgrep.mcp.models import (
@@ -483,6 +485,42 @@ async def db_status(
 t.cast(t.Any, db_status).__fastmcp__ = types.SimpleNamespace(
     name="db_status",
     title="DB Status",
-    tags=READONLY_TAGS | {"db"},
+    tags=READONLY_TAGS | {"db", "insights"},
+    annotations=None,
+)
+
+
+async def insights_list(
+    db_path: t.Annotated[
+        str | None,
+        Field(default=None, description="Optional agentgrep db path."),
+    ] = None,
+) -> InsightsListResponse:
+    """List persisted deterministic insight artifacts."""
+    raise NotImplementedError(DOCS_ONLY_MESSAGE)
+
+
+t.cast(t.Any, insights_list).__fastmcp__ = types.SimpleNamespace(
+    name="insights_list",
+    title="Insights List",
+    tags=READONLY_TAGS | {"insights"},
+    annotations=None,
+)
+
+
+async def suggestions_list(
+    db_path: t.Annotated[
+        str | None,
+        Field(default=None, description="Optional agentgrep db path."),
+    ] = None,
+) -> SuggestionsListResponse:
+    """List persisted review-only instruction suggestions."""
+    raise NotImplementedError(DOCS_ONLY_MESSAGE)
+
+
+t.cast(t.Any, suggestions_list).__fastmcp__ = types.SimpleNamespace(
+    name="suggestions_list",
+    title="Suggestions List",
+    tags=READONLY_TAGS | {"insights", "suggestions"},
     annotations=None,
 )

docs/cli/db/sync.md

@@ -35,6 +35,13 @@ Force a full refresh even when sources look unchanged:
 $ agentgrep db sync --force
 ```
 
+Build deterministic insight features during sync instead of deferring
+them:
+
+```console
+$ agentgrep db sync --features inline
+```
+
 Show progress even when writing structured output:
 
 ```console
@@ -72,6 +79,14 @@ history files stop answering cached searches. Narrowed syncs
 (`--agent`, `--scope`, `--limit-sources`) never prune, because they do
 not observe the full catalog.
 
+## Features
+
+The default `--features defer` mode writes source rows, normalized
+records, and the FTS5 cache immediately, but leaves expensive
+similarity features for the insights pipeline. This keeps
+`agentgrep db sync` focused on cache freshness. Use `--features inline`
+when you want the feature table populated as part of sync itself.
+
 ## Command
 
 ```{eval-rst}

docs/cli/index.md

@@ -58,6 +58,18 @@ Open the interactive Textual explorer command surface.
 Sync and inspect the persistent DB index.
 :::
 
+:::{grid-item-card} agentgrep insights
+:link: insights/index
+:link-type: doc
+Run and inspect deterministic similarity and omission analysis.
+:::
+
+:::{grid-item-card} agentgrep suggestions
+:link: suggestions/index
+:link-type: doc
+List, inspect, and render review-only instruction suggestions.
+:::
+
 :::{grid-item-card} API Reference
 :link: reference
 :link-type: doc
@@ -180,5 +192,7 @@ search
 find
 ui
 db/index
+insights/index
+suggestions/index
 reference
 ```

docs/cli/insights/analyze.md

@@ -0,0 +1,49 @@
+(cli-insights-analyze)=
+
+# agentgrep insights analyze
+
+Analyze deterministic insight jobs against the DB index. Insight
+analysis persists evidence artifacts for later listing and review.
+
+## Examples
+
+Analyze every insight family:
+
+```console
+$ agentgrep insights analyze
+```
+
+Analyze only similarity evidence:
+
+```console
+$ agentgrep insights analyze --kind similarity
+```
+
+Analyze omissions for an instruction file:
+
+```console
+$ agentgrep insights analyze \
+    --kind omissions \
+    --target AGENTS.md
+```
+
+## Progress
+
+Text-mode analysis shows stderr progress by default. In an interactive
+terminal, press Enter on a blank line to stop before the next insight
+step and return partial analysis counters. The active insight step
+finishes before the command exits.
+
+Progress output always goes to stderr. JSON and NDJSON stdout stay
+machine-readable even when progress is forced with `--progress always`.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: insights analyze
+    :nodescription:
+```

docs/cli/insights/explain.md

@@ -0,0 +1,30 @@
+(cli-insights-explain)=
+
+# agentgrep insights explain
+
+Show persisted insight counters for the selected agentgrep database.
+
+## Examples
+
+Explain insight counts:
+
+```console
+$ agentgrep insights explain
+```
+
+Emit structured JSON:
+
+```console
+$ agentgrep insights explain --json
+```
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: insights explain
+    :nodescription:
+```

docs/cli/insights/index.md

@@ -0,0 +1,35 @@
+(cli-insights)=
+
+# agentgrep insights
+
+The `agentgrep insights` command group analyzes and inspects deterministic
+similarity and omission analysis over a DB index. The CLI
+pages document command flags; the feature guide lives in
+{ref}`insights`.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: insights
+    :nosubcommands:
+    :nodescription:
+```
+
+Choose a subcommand for details:
+
+- {ref}`cli-insights-analyze` - analyze similarity and omission evidence
+- {ref}`cli-insights-list` - list persisted insight artifacts
+- {ref}`cli-insights-explain` - show persisted insight counters
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+analyze
+list
+explain
+```

docs/cli/insights/list.md

@@ -0,0 +1,46 @@
+(cli-insights-list)=
+
+# agentgrep insights list
+
+List a bounded page of persisted similarity edges and omission
+findings. By default this prints a terminal summary with sampled rows;
+use `--json` or `--ndjson` when stdout must be machine-readable. This
+command does not run new analysis. Use `agentgrep insights explain` for
+cheap counts without returning row samples.
+
+## Examples
+
+List a small persisted-insight sample:
+
+```console
+$ agentgrep insights list
+```
+
+Change the per-kind row limit:
+
+```console
+$ agentgrep insights list --limit 10
+```
+
+List only omission findings as JSON:
+
+```console
+$ agentgrep insights list --kind omissions --json
+```
+
+Read from a non-default agentgrep database:
+
+```console
+$ agentgrep insights list --db .tmp/agentgrep.sqlite
+```
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: insights list
+    :nodescription:
+```

docs/cli/reference.md

@@ -27,6 +27,14 @@ CLI argument types, serialization helpers, and command entry points.
 .. autoclass:: agentgrep.DbArgs
    :members:
    :no-undoc-members:
+
+.. autoclass:: agentgrep.InsightsArgs
+   :members:
+   :no-undoc-members:
+
+.. autoclass:: agentgrep.SuggestionsArgs
+   :members:
+   :no-undoc-members:
 ```
 
 ## Serialization
@@ -46,5 +54,7 @@ CLI argument types, serialization helpers, and command entry points.
 .. autofunction:: agentgrep.run_find_command
 .. autofunction:: agentgrep.run_ui_command
 .. autofunction:: agentgrep.run_db_command
+.. autofunction:: agentgrep.run_insights_command
+.. autofunction:: agentgrep.run_suggestions_command
 .. autofunction:: agentgrep.main
 ```

docs/cli/suggestions/index.md

@@ -0,0 +1,35 @@
+(cli-suggestions)=
+
+# agentgrep suggestions
+
+The `agentgrep suggestions` command group lists and renders
+review-only instruction suggestions derived from omission findings.
+The CLI pages document command flags; the suggestion workflow is
+explained in {ref}`insights-suggestions`.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: suggestions
+    :nosubcommands:
+    :nodescription:
+```
+
+Choose a subcommand for details:
+
+- {ref}`cli-suggestions-list` - list or create persisted suggestions
+- {ref}`cli-suggestions-show` - inspect one suggestion as structured output
+- {ref}`cli-suggestions-render` - render one suggestion as review text
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+list
+show
+render
+```

docs/cli/suggestions/list.md

@@ -0,0 +1,47 @@
+(cli-suggestions-list)=
+
+# agentgrep suggestions list
+
+List persisted suggestion artifacts. By default this prints a terminal
+summary; use `--json` or `--ndjson` when stdout must be
+machine-readable. When `--target` is provided, agentgrep first creates
+review-only suggestions from open omission findings for that target.
+
+## Examples
+
+List existing suggestions:
+
+```console
+$ agentgrep suggestions list
+```
+
+Create suggestions for `AGENTS.md` and emit JSON:
+
+```console
+$ agentgrep suggestions list \
+    --target AGENTS.md \
+    --json
+```
+
+Use a non-default agentgrep database:
+
+```console
+$ agentgrep suggestions list --db .tmp/agentgrep.sqlite
+```
+
+Return only the most confident suggestion:
+
+```console
+$ agentgrep suggestions list --limit 1
+```
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: agentgrep
+    :func: build_docs_parser
+    :prog: agentgrep
+    :path: suggestions list
+    :nodescription:
+```