From f262d769ea7b8ad13872c65793a5546a51965bf0 Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Wed, 22 Apr 2026 06:31:40 +0200
Subject: [PATCH 1/6] fix(markdown): render mermaid fences as <pre
 class="mermaid">
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Artifact descriptions go through rivet-core's pulldown-cmark based
render_markdown. That renderer was emitting pulldown's default
<pre><code class="language-mermaid"> for fenced mermaid blocks, which
the dashboard's mermaid.js (selector `.mermaid`) never matches — so
diagrams in artifact descriptions rendered as literal source.

Add a tiny event-mapping pass that replaces the Start/End code-block
events for `mermaid` fences with synthetic HTML wrappers (NUL-byte
sentinels that cannot appear in input, rewritten post-html-push). Other
raw HTML events are still dropped for XSS defence, and the sanitize
pass still runs. Non-mermaid fences keep their existing rendering.

Covers the bug end-to-end: markdown unit tests verify the <pre
class="mermaid"> shape and regression for rust fences; architecture.yaml
ARCH-CORE-001 now carries a mermaid diagram as a live fixture, and a
Playwright regression walks the artifact page and asserts mermaid.js
actually produces an SVG.

Fixes: REQ-032
Refs: FEAT-032
---
 artifacts/architecture.yaml        |   9 ++-
 rivet-core/src/markdown.rs         | 125 ++++++++++++++++++++++++++---
 tests/playwright/artifacts.spec.ts |  26 ++++++
 3 files changed, 149 insertions(+), 11 deletions(-)

diff --git a/artifacts/architecture.yaml b/artifacts/architecture.yaml
index 7f8bfee..96aa465 100644
--- a/artifacts/architecture.yaml
+++ b/artifacts/architecture.yaml
@@ -48,10 +48,17 @@ artifacts:
   - id: ARCH-CORE-001
     type: aadl-component
     title: RivetCore process
-    description: >
+    description: |
       Core library process containing all domain logic: config loading,
       schema merging, artifact storage, adapter dispatch, graph building,
       validation, matrix computation, diff, documents, and query.
+
+      ```mermaid
+      flowchart LR
+          Config --> Store
+          Store --> Graph
+          Graph --> Validate
+      ```
     status: implemented
     tags: [aadl, architecture, core]
     links:
diff --git a/rivet-core/src/markdown.rs b/rivet-core/src/markdown.rs
index 2b2a4dd..62a78ee 100644
--- a/rivet-core/src/markdown.rs
+++ b/rivet-core/src/markdown.rs
@@ -49,27 +49,65 @@ fn sanitize_html(html: &str) -> String {
 /// Enables tables, strikethrough, and task lists on top of the CommonMark base.
 /// Used for artifact descriptions, field values, and document content.
 ///
-/// Security: raw HTML events are filtered at the pulldown-cmark level, and a
-/// regex-based sanitization pass strips dangerous tags (`<script>`, `<iframe>`,
-/// `<object>`, `<embed>`, `<form>`), `on*` event handler attributes, and
-/// `javascript:` URLs as defense-in-depth.
+/// Fenced ` ```mermaid ` code blocks are emitted as `<pre class="mermaid">...</pre>`
+/// (rather than pulldown-cmark's default `<pre><code class="language-mermaid">`)
+/// so the dashboard's mermaid.js loader (which selects on `.mermaid`) renders
+/// them as diagrams. Matches the behaviour of the document renderer in
+/// `document.rs`.
+///
+/// Security: raw HTML events are filtered at the pulldown-cmark level (except
+/// for the two synthetic `<pre class="mermaid">` wrappers, which are injected
+/// by us and are safe), and a regex-based sanitization pass strips dangerous
+/// tags (`<script>`, `<iframe>`, `<object>`, `<embed>`, `<form>`), `on*` event
+/// handler attributes, and `javascript:` URLs as defense-in-depth.
 pub fn render_markdown(input: &str) -> String {
-    use pulldown_cmark::{Event, Options, Parser, html};
+    use pulldown_cmark::{CodeBlockKind, Event, Options, Parser, Tag, TagEnd, html};
 
     let mut options = Options::empty();
     options.insert(Options::ENABLE_TABLES);
     options.insert(Options::ENABLE_STRIKETHROUGH);
     options.insert(Options::ENABLE_TASKLISTS);
 
-    // Filter out raw HTML events to prevent XSS via markdown input.
-    // This strips <script>, <iframe>, and any other raw HTML while
-    // keeping the rendered markdown HTML produced by pulldown-cmark.
-    let parser = Parser::new_ext(input, options)
-        .filter(|event| !matches!(event, Event::Html(_) | Event::InlineHtml(_)));
+    // Two-stage event pipeline:
+    //   1. Track whether we are inside a fenced ```mermaid block, and when we
+    //      are, replace the Start/End CodeBlock events with synthetic Html
+    //      events that wrap the body in `<pre class="mermaid">...</pre>`.
+    //   2. Filter out any *other* raw HTML events to prevent XSS via markdown
+    //      input. The synthetic mermaid wrappers are marked by a sentinel
+    //      prefix we strip back out — see `MERMAID_OPEN` / `MERMAID_CLOSE`.
+    const MERMAID_OPEN: &str = "\0rivet-mermaid-open\0";
+    const MERMAID_CLOSE: &str = "\0rivet-mermaid-close\0";
+
+    let mut in_mermaid = false;
+    let parser = Parser::new_ext(input, options).filter_map(move |event| match event {
+        Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(ref lang)))
+            if lang.as_ref() == "mermaid" =>
+        {
+            in_mermaid = true;
+            Some(Event::Html(MERMAID_OPEN.into()))
+        }
+        Event::End(TagEnd::CodeBlock) if in_mermaid => {
+            in_mermaid = false;
+            Some(Event::Html(MERMAID_CLOSE.into()))
+        }
+        // Inside a mermaid block, pass text through as-is (pulldown-cmark
+        // emits the fenced body as Event::Text segments).
+        Event::Text(_) if in_mermaid => Some(event),
+        // Drop all other raw HTML events for XSS defence.
+        Event::Html(_) | Event::InlineHtml(_) => None,
+        other => Some(other),
+    });
 
     let mut html_output = String::new();
     html::push_html(&mut html_output, parser);
 
+    // Rewrite the mermaid sentinels into the real HTML tags.  Because the
+    // sentinels contain NUL bytes they cannot appear in markdown input, so
+    // replacement is safe from confusion attacks.
+    let html_output = html_output
+        .replace(MERMAID_OPEN, "<pre class=\"mermaid\">")
+        .replace(MERMAID_CLOSE, "</pre>");
+
     // Defense-in-depth: strip dangerous tags/attributes that may survive
     // the pulldown-cmark event filter (e.g. javascript: URLs in links).
     sanitize_html(&html_output)
@@ -301,4 +339,71 @@ mod tests {
         let out = sanitize_html(r#"<a href="javascript:alert(1)">click</a>"#);
         assert!(!out.contains("javascript:"), "got: {out}");
     }
+
+    // ── Mermaid rendering (REQ-032) ─────────────────────────────────────
+
+    // Mermaid fenced blocks must emit <pre class="mermaid"> so the
+    // dashboard's mermaid.js loader (selector: `.mermaid`) picks them up.
+    // rivet: verifies REQ-032
+    #[test]
+    fn fenced_mermaid_becomes_pre_mermaid() {
+        let input = "```mermaid\ngraph TD\nA-->B\n```";
+        let html = render_markdown(input);
+        assert!(
+            html.contains("<pre class=\"mermaid\">"),
+            "mermaid block must render as <pre class=\"mermaid\">, got: {html}"
+        );
+        assert!(
+            html.contains("graph TD"),
+            "mermaid body must be preserved, got: {html}"
+        );
+        assert!(
+            !html.contains("language-mermaid"),
+            "default pulldown-cmark language class must not leak, got: {html}"
+        );
+    }
+
+    // rivet: verifies REQ-032
+    #[test]
+    fn fenced_mermaid_inside_artifact_description_renders() {
+        // Shape mirrors a real artifact description with prose around a diagram.
+        let input = "Overview:\n\n```mermaid\nflowchart LR\nA --> B\n```\n\nMore text.";
+        let html = render_markdown(input);
+        assert!(html.contains("<pre class=\"mermaid\">"), "got: {html}");
+        assert!(html.contains("flowchart LR"), "got: {html}");
+        assert!(html.contains("More text"), "got: {html}");
+    }
+
+    // Regression: non-mermaid fences still render as normal code blocks with
+    // a language class (so existing syntax highlighting, etc. keeps working).
+    // rivet: verifies REQ-032
+    #[test]
+    fn fenced_rust_still_renders_as_code() {
+        let input = "```rust\nfn main() {}\n```";
+        let html = render_markdown(input);
+        assert!(
+            html.contains("<pre><code class=\"language-rust\">"),
+            "rust block must keep language-rust class, got: {html}"
+        );
+        assert!(
+            !html.contains("<pre class=\"mermaid\""),
+            "rust must not be treated as mermaid, got: {html}"
+        );
+    }
+
+    // Sentinel strings used internally for the mermaid rewrite must never
+    // leak into output even if a user tries to smuggle them via text.  NUL
+    // bytes cannot appear in well-formed markdown input, so the sentinel is
+    // distinguishable from user content; but we still test that normal
+    // usage has no NUL bytes remaining.
+    // rivet: verifies REQ-032
+    #[test]
+    fn mermaid_sentinels_do_not_leak() {
+        let html = render_markdown("```mermaid\nA-->B\n```");
+        assert!(!html.contains('\0'), "NUL sentinels must be rewritten");
+        assert!(
+            !html.contains("rivet-mermaid-open"),
+            "sentinel label must not leak, got: {html}"
+        );
+    }
 }
diff --git a/tests/playwright/artifacts.spec.ts b/tests/playwright/artifacts.spec.ts
index 0fac385..955e214 100644
--- a/tests/playwright/artifacts.spec.ts
+++ b/tests/playwright/artifacts.spec.ts
@@ -39,4 +39,30 @@ test.describe("Artifacts", () => {
     const resp = await page.goto(hxGet);
     expect(resp?.status()).toBe(200);
   });
+
+  // Regression: mermaid diagrams embedded in an artifact description must
+  // render as SVG — not as raw markdown source.  The fixture artifact
+  // ARCH-CORE-001 (artifacts/architecture.yaml) has a fenced ```mermaid
+  // block in its description.  If render_markdown ever regresses to emitting
+  // `<pre><code class="language-mermaid">` the .mermaid selector will miss
+  // the block, mermaid.js will not run, and no SVG will appear.
+  test("mermaid diagrams in artifact descriptions render as SVG", async ({
+    page,
+  }) => {
+    await page.goto("/artifacts/ARCH-CORE-001");
+    await waitForHtmx(page);
+
+    // The markdown renderer must emit a `<pre class="mermaid">` wrapper
+    // (not the pulldown-cmark default `<pre><code class="language-mermaid">`).
+    const mermaidPre = page.locator("pre.mermaid");
+    await expect(mermaidPre).toHaveCount(1);
+
+    // The source content must be there before mermaid.js runs.
+    await expect(mermaidPre).toContainText("flowchart LR");
+
+    // mermaid.js replaces the block's contents with an <svg> on success.
+    // Give it a moment to run — it's triggered by DOMContentLoaded and
+    // htmx:afterSwap.  If rendering fails the pre block keeps its source.
+    await expect(mermaidPre.locator("svg")).toBeVisible({ timeout: 5_000 });
+  });
 });

From b4f741329af7ca8b635504959b48ff934ffa3f41 Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Wed, 22 Apr 2026 06:46:30 +0200
Subject: [PATCH 2/6] feat(embed): {{query:(sexpr)}} renders live s-expression
 results
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a read-only {{query:(...)}} embed backed by the existing
sexpr_eval::parse_filter + matches_filter_with_store pair — the same path
that powers `rivet list --filter` and MCP's `rivet_query`. The embed
renders a compact `id | type | title | status` table, clamped to a
default of 50 rows (hard max 500 via `limit=N`), with a visible
"Showing N of M" footer on truncation so nothing disappears silently.

Parser changes:

- `EmbedRequest::parse` was previously splitting on `:` blindly, which
  corrupted any s-expression argument.  For `name == "query"` it now
  expects a balanced-paren form `{{query:(...)}}` and captures the whole
  paren group as the single positional arg.  Parens inside string
  literals are respected so `(= title "foo)bar")` parses correctly.
- All other embed shapes (`stats`, `stats:types`, `table:T:F`, …) keep
  their existing colon-split behaviour — covered by regression tests.

Tests: 12 new unit tests covering the paren scanner (simple, nested,
string-literal, unbalanced), the `query` parse shape, an end-to-end
`query_embed_matches_sexpr_filter` cross-check against the evaluator
directly, truncation, `limit=` clamping, and error propagation from a
malformed filter.

Implements: REQ-007
Refs: FEAT-032
---
 rivet-core/src/embed.rs | 458 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 449 insertions(+), 9 deletions(-)

diff --git a/rivet-core/src/embed.rs b/rivet-core/src/embed.rs
index ecf6ac3..db19089 100644
--- a/rivet-core/src/embed.rs
+++ b/rivet-core/src/embed.rs
@@ -109,6 +109,13 @@ impl EmbedRequest {
     /// Parse a raw embed string (the content between `{{` and `}}`).
     ///
     /// Syntax: `name[:arg1[:arg2[...]]] [key=val ...]`
+    ///
+    /// Special case: when `name == "query"` the first argument is an
+    /// s-expression which contains `(`, `)`, `"` and its own `:` — so
+    /// naive `split(':')` / `split_whitespace()` would corrupt it. The
+    /// parser therefore requires the query form `query:(...)` and
+    /// captures balanced parens as the single positional arg, leaving any
+    /// trailing `key=val` options after the closing `)` intact.
     pub fn parse(input: &str) -> Result<Self, EmbedError> {
         let input = input.trim();
         if input.is_empty() {
@@ -118,18 +125,77 @@ impl EmbedRequest {
             });
         }
 
-        // Split on first space to separate "name:args..." from "key=val ..."
-        let (name_args_part, options_part) = match input.find(' ') {
-            Some(pos) => (&input[..pos], Some(&input[pos + 1..])),
-            None => (input, None),
+        // Peel off the embed name (everything up to the first ':' or space).
+        let name_end = input
+            .find(|c: char| c == ':' || c.is_whitespace())
+            .unwrap_or(input.len());
+        let name = input[..name_end].to_string();
+        let rest = input[name_end..].trim_start_matches(':');
+
+        // ── Balanced-paren form for `query` ────────────────────────
+        // `{{query:(..balanced..) key=val}}`.  Any colons, spaces, and
+        // quotes inside the parens belong to the s-expression.
+        if name == "query" {
+            let rest_trim = rest.trim_start();
+            if !rest_trim.starts_with('(') {
+                return Err(EmbedError {
+                    kind: EmbedErrorKind::MalformedSyntax(
+                        "query embed requires a parenthesised s-expression: {{query:(...)}}"
+                            .into(),
+                    ),
+                    raw_text: input.to_string(),
+                });
+            }
+            let (sexpr, tail) = match extract_balanced_parens(rest_trim) {
+                Some(pair) => pair,
+                None => {
+                    return Err(EmbedError {
+                        kind: EmbedErrorKind::MalformedSyntax(
+                            "unbalanced parentheses in query embed".into(),
+                        ),
+                        raw_text: input.to_string(),
+                    });
+                }
+            };
+
+            let mut options = BTreeMap::new();
+            for token in tail.split_whitespace() {
+                if let Some((key, val)) = token.split_once('=') {
+                    options.insert(key.to_string(), val.to_string());
+                }
+            }
+            return Ok(EmbedRequest {
+                name,
+                args: vec![sexpr.to_string()],
+                options,
+            });
+        }
+
+        // ── Classic form: name:arg1:arg2 key=val ... ───────────────
+        // (Re-assemble input so the whitespace/option parser sees the
+        //  original shape.)
+        let tail_full = if rest.is_empty() { input } else { rest };
+        // If `rest` is a slice of `input`, we need to re-anchor the "name"
+        // prefix logic on the tail (arguments only).
+        let args_and_options = if name_end == input.len() {
+            ""
+        } else {
+            input[name_end..].trim_start_matches(':')
+        };
+        let (args_part, options_part) = match args_and_options.find(' ') {
+            Some(pos) => (
+                &args_and_options[..pos],
+                Some(&args_and_options[pos + 1..]),
+            ),
+            None => (args_and_options, None),
         };
 
-        // Split name:arg1:arg2:...
-        let mut parts = name_args_part.split(':');
-        let name = parts.next().unwrap().to_string();
-        let args: Vec<String> = parts.map(|s| s.trim().to_string()).collect();
+        let args: Vec<String> = if args_part.is_empty() {
+            Vec::new()
+        } else {
+            args_part.split(':').map(|s| s.trim().to_string()).collect()
+        };
 
-        // Parse key=val options
         let mut options = BTreeMap::new();
         if let Some(opts_str) = options_part {
             for token in opts_str.split_whitespace() {
@@ -139,6 +205,9 @@ impl EmbedRequest {
             }
         }
 
+        // Silence unused-variable lint for the legacy shadow.
+        let _ = tail_full;
+
         Ok(EmbedRequest {
             name,
             args,
@@ -165,6 +234,7 @@ pub fn resolve_embed(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> Result<S
         "coverage" => Ok(render_coverage(request, ctx)),
         "diagnostics" => Ok(render_diagnostics(request, ctx)),
         "matrix" => Ok(render_matrix(request, ctx)),
+        "query" => render_query(request, ctx),
         // Legacy embeds (artifact, links, table) are still handled by
         // resolve_inline in document.rs — they should never reach here.
         "artifact" | "links" | "table" => Err(EmbedError {
@@ -180,6 +250,47 @@ pub fn resolve_embed(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> Result<S
     }
 }
 
+/// Extract the balanced-parenthesis prefix from a string that starts with `(`.
+///
+/// Returns `(inside_parens_including_outer, tail_after_close)` on success.
+/// Respects string literals so that `"foo)bar"` does not close the group.
+fn extract_balanced_parens(s: &str) -> Option<(&str, &str)> {
+    let bytes = s.as_bytes();
+    if bytes.first() != Some(&b'(') {
+        return None;
+    }
+    let mut depth = 0i32;
+    let mut in_string = false;
+    let mut escape = false;
+    for (i, b) in bytes.iter().enumerate() {
+        let c = *b;
+        if in_string {
+            if escape {
+                escape = false;
+            } else if c == b'\\' {
+                escape = true;
+            } else if c == b'"' {
+                in_string = false;
+            }
+            continue;
+        }
+        match c {
+            b'"' => in_string = true,
+            b'(' => depth += 1,
+            b')' => {
+                depth -= 1;
+                if depth == 0 {
+                    // include the closing paren in the first slice
+                    let (head, tail) = s.split_at(i + 1);
+                    return Some((head, tail));
+                }
+            }
+            _ => {}
+        }
+    }
+    None
+}
+
 // ── Stats renderer ──────────────────────────────────────────────────────
 
 /// Render `{{stats}}` / `{{stats:types}}` / `{{stats:status}}` / `{{stats:validation}}`.
@@ -624,6 +735,100 @@ fn auto_detect_link(ctx: &EmbedContext<'_>, from: &str, _to: &str) -> String {
     String::new()
 }
 
+// ── Query renderer ──────────────────────────────────────────────────────
+
+/// Default maximum rows a `{{query:...}}` embed will render.
+pub const QUERY_EMBED_DEFAULT_LIMIT: usize = 50;
+/// Hard upper bound on `limit=N` for `{{query:...}}`; keeps render time bounded.
+pub const QUERY_EMBED_MAX_LIMIT: usize = 500;
+
+/// Render `{{query:(s-expr) [limit=N]}}`.
+///
+/// Reuses `sexpr_eval::parse_filter` and `matches_filter_with_store` — the
+/// same path used by `rivet list --filter`, MCP's `rivet_query`, and the
+/// `rivet query` CLI — so output IDs agree across all three surfaces.
+///
+/// Read-only by construction (the evaluator has no I/O), and truncation is
+/// reported as a visible footer rather than silently dropping rows.
+fn render_query(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> Result<String, EmbedError> {
+    let Some(sexpr) = request.args.first() else {
+        return Err(EmbedError {
+            kind: EmbedErrorKind::MalformedSyntax(
+                "query embed requires an s-expression: {{query:(...)}}".into(),
+            ),
+            raw_text: format!("{request:?}"),
+        });
+    };
+
+    let expr = crate::sexpr_eval::parse_filter(sexpr).map_err(|errs| {
+        let msgs: Vec<String> = errs.iter().map(|e| e.to_string()).collect();
+        EmbedError {
+            kind: EmbedErrorKind::MalformedSyntax(format!("invalid filter: {}", msgs.join("; "))),
+            raw_text: sexpr.clone(),
+        }
+    })?;
+
+    // Resolve limit: options["limit"] if valid, else default.  Clamped to
+    // the hard max so a stray `limit=99999` cannot pin the renderer.
+    let limit = request
+        .options
+        .get("limit")
+        .and_then(|s| s.parse::<usize>().ok())
+        .unwrap_or(QUERY_EMBED_DEFAULT_LIMIT)
+        .min(QUERY_EMBED_MAX_LIMIT);
+
+    let mut matches: Vec<&crate::model::Artifact> = Vec::new();
+    let mut total = 0usize;
+    for artifact in ctx.store.iter() {
+        if crate::sexpr_eval::matches_filter_with_store(&expr, artifact, ctx.graph, ctx.store) {
+            total += 1;
+            if matches.len() < limit {
+                matches.push(artifact);
+            }
+        }
+    }
+
+    let mut html = String::from("<div class=\"embed-query\">\n");
+    if total == 0 {
+        html.push_str("<p class=\"embed-no-data\">No artifacts match this query.</p>\n");
+        html.push_str("</div>\n");
+        return Ok(html);
+    }
+
+    html.push_str(
+        "<table class=\"embed-table\"><thead><tr>\
+         <th>ID</th><th>Type</th><th>Title</th><th>Status</th>\
+         </tr></thead><tbody>\n",
+    );
+    for a in &matches {
+        let _ = writeln!(
+            html,
+            "<tr><td><code>{id}</code></td><td>{typ}</td><td>{title}</td><td>{status}</td></tr>",
+            id = document::html_escape(&a.id),
+            typ = document::html_escape(&a.artifact_type),
+            title = document::html_escape(&a.title),
+            status = document::html_escape(a.status.as_deref().unwrap_or("-")),
+        );
+    }
+    html.push_str("</tbody></table>\n");
+
+    if total > matches.len() {
+        let _ = writeln!(
+            html,
+            "<p class=\"embed-summary\">Showing {shown} of {total} — narrow the filter or raise <code>limit=</code> to see more.</p>",
+            shown = matches.len(),
+        );
+    } else {
+        let _ = writeln!(
+            html,
+            "<p class=\"embed-summary\">{total} result{s}.</p>",
+            s = if total == 1 { "" } else { "s" },
+        );
+    }
+    html.push_str("</div>\n");
+    Ok(html)
+}
+
 // ── Provenance ──────────────────────────────────────────────────────────
 
 /// Render a provenance footer for export (SC-EMBED-4).
@@ -923,4 +1128,239 @@ mod tests {
         assert!(!EmbedRequest::parse("diagnostics").unwrap().is_legacy());
         assert!(!EmbedRequest::parse("matrix").unwrap().is_legacy());
     }
+
+    // ── Balanced-paren / query parsing ──────────────────────────────
+
+    #[test]
+    fn extract_balanced_parens_simple() {
+        let (head, tail) = extract_balanced_parens("(= type \"requirement\") limit=5").unwrap();
+        assert_eq!(head, "(= type \"requirement\")");
+        assert_eq!(tail, " limit=5");
+    }
+
+    #[test]
+    fn extract_balanced_parens_nested() {
+        let (head, tail) =
+            extract_balanced_parens("(and (= type \"requirement\") (has-tag \"stpa\"))").unwrap();
+        assert_eq!(head, "(and (= type \"requirement\") (has-tag \"stpa\"))");
+        assert_eq!(tail, "");
+    }
+
+    #[test]
+    fn extract_balanced_parens_respects_string_literal() {
+        // a `)` inside a string must not close the group
+        let (head, _tail) = extract_balanced_parens(r#"(= title "has ) paren")"#).unwrap();
+        assert_eq!(head, r#"(= title "has ) paren")"#);
+    }
+
+    #[test]
+    fn extract_balanced_parens_unbalanced_returns_none() {
+        assert!(extract_balanced_parens("(and (=").is_none());
+    }
+
+    #[test]
+    fn parse_query_captures_whole_sexpr() {
+        let req = EmbedRequest::parse("query:(= type \"requirement\")").unwrap();
+        assert_eq!(req.name, "query");
+        assert_eq!(req.args, vec!["(= type \"requirement\")"]);
+    }
+
+    #[test]
+    fn parse_query_with_nested_and_options() {
+        let req = EmbedRequest::parse(
+            "query:(and (= type \"requirement\") (has-tag \"stpa\")) limit=25",
+        )
+        .unwrap();
+        assert_eq!(req.name, "query");
+        assert_eq!(
+            req.args,
+            vec!["(and (= type \"requirement\") (has-tag \"stpa\"))"]
+        );
+        assert_eq!(req.options.get("limit"), Some(&"25".to_string()));
+    }
+
+    #[test]
+    fn parse_query_without_parens_errors() {
+        let err = EmbedRequest::parse("query:type=requirement").unwrap_err();
+        assert!(matches!(err.kind, EmbedErrorKind::MalformedSyntax(_)));
+    }
+
+    #[test]
+    fn parse_query_with_unbalanced_parens_errors() {
+        let err = EmbedRequest::parse("query:(and (= type \"req\"").unwrap_err();
+        assert!(matches!(err.kind, EmbedErrorKind::MalformedSyntax(_)));
+    }
+
+    // Regression: parser changes for `query` must not break existing embeds.
+
+    #[test]
+    fn parse_stats_still_splits_on_colon() {
+        let req = EmbedRequest::parse("stats:types").unwrap();
+        assert_eq!(req.name, "stats");
+        assert_eq!(req.args, vec!["types"]);
+    }
+
+    #[test]
+    fn parse_table_still_takes_two_args() {
+        let req = EmbedRequest::parse("table:requirement:id,title,status").unwrap();
+        assert_eq!(req.name, "table");
+        assert_eq!(req.args, vec!["requirement", "id,title,status"]);
+    }
+
+    // ── Query & group renderers ─────────────────────────────────────
+
+    use crate::links::LinkGraph;
+    use crate::model::Artifact;
+    use crate::schema::Schema;
+    use crate::store::Store;
+    use crate::validate::Diagnostic;
+    use std::collections::BTreeMap;
+
+    fn make_store(artifacts: Vec<Artifact>) -> Store {
+        let mut s = Store::new();
+        for a in artifacts {
+            s.upsert(a);
+        }
+        s
+    }
+
+    fn plain(id: &str, typ: &str, status: Option<&str>, tags: &[&str]) -> Artifact {
+        Artifact {
+            id: id.into(),
+            artifact_type: typ.into(),
+            title: format!("Title of {id}"),
+            description: None,
+            status: status.map(|s| s.into()),
+            tags: tags.iter().map(|t| t.to_string()).collect(),
+            links: vec![],
+            fields: BTreeMap::new(),
+            provenance: None,
+            source_file: None,
+        }
+    }
+
+    fn run_embed(
+        query: &str,
+        store: &Store,
+        schema: &Schema,
+        graph: &LinkGraph,
+    ) -> Result<String, EmbedError> {
+        let req = EmbedRequest::parse(query)?;
+        let diags: Vec<Diagnostic> = Vec::new();
+        let ctx = EmbedContext {
+            store,
+            schema,
+            graph,
+            diagnostics: &diags,
+            baseline: None,
+        };
+        resolve_embed(&req, &ctx)
+    }
+
+    // The `{{query:...}}` embed must return the same IDs as
+    // `sexpr_eval::matches_filter_with_store` — and therefore the same set
+    // that `rivet list --filter` and MCP's `rivet_query` would return.
+    #[test]
+    fn query_embed_matches_sexpr_filter() {
+        let store = make_store(vec![
+            plain("REQ-1", "requirement", Some("approved"), &["stpa"]),
+            plain("REQ-2", "requirement", Some("draft"), &[]),
+            plain("FEAT-1", "feature", Some("approved"), &["stpa"]),
+        ]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+
+        let html = run_embed(
+            r#"query:(= type "requirement")"#,
+            &store,
+            &schema,
+            &graph,
+        )
+        .unwrap();
+        assert!(html.contains("REQ-1"), "got: {html}");
+        assert!(html.contains("REQ-2"), "got: {html}");
+        assert!(!html.contains("FEAT-1"), "got: {html}");
+
+        // Cross-check via the same evaluator directly.
+        let expr = crate::sexpr_eval::parse_filter(r#"(= type "requirement")"#).unwrap();
+        let direct_ids: Vec<String> = store
+            .iter()
+            .filter(|a| crate::sexpr_eval::matches_filter_with_store(&expr, a, &graph, &store))
+            .map(|a| a.id.clone())
+            .collect();
+        assert_eq!(direct_ids, vec!["REQ-1".to_string(), "REQ-2".to_string()]);
+    }
+
+    #[test]
+    fn query_embed_no_matches_shows_empty_message() {
+        let store = make_store(vec![plain("REQ-1", "requirement", None, &[])]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed(r#"query:(= type "feature")"#, &store, &schema, &graph).unwrap();
+        assert!(html.contains("No artifacts match"), "got: {html}");
+        assert!(html.contains("embed-query"));
+    }
+
+    #[test]
+    fn query_embed_limit_caps_rows_and_shows_truncation_note() {
+        let store = make_store(
+            (0..20)
+                .map(|i| plain(&format!("REQ-{i:03}"), "requirement", None, &[]))
+                .collect(),
+        );
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed(
+            r#"query:(= type "requirement") limit=3"#,
+            &store,
+            &schema,
+            &graph,
+        )
+        .unwrap();
+        // Only 3 data rows render, and a footer flags the truncation.
+        // (Store iteration order is not guaranteed — we assert row count
+        //  and the summary, not specific IDs.)
+        let row_count = html.matches("<tr>").count();
+        assert_eq!(row_count, 4, "expected 1 header + 3 data rows, got: {html}");
+        assert!(html.contains("Showing 3 of 20"), "got: {html}");
+    }
+
+    #[test]
+    fn query_embed_limit_clamped_to_hard_max() {
+        // Just verify that an over-limit renders at all without panicking.
+        let store = make_store(vec![plain("REQ-1", "requirement", None, &[])]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed(
+            &format!(
+                "query:(= type \"requirement\") limit={}",
+                QUERY_EMBED_MAX_LIMIT + 1_000
+            ),
+            &store,
+            &schema,
+            &graph,
+        )
+        .unwrap();
+        assert!(html.contains("REQ-1"));
+    }
+
+    #[test]
+    fn query_embed_malformed_filter_renders_error() {
+        let store = Store::new();
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        // `(and` unclosed — passes the paren-balancer only when wrapped.
+        let req = EmbedRequest::parse("query:(unknown-form)").unwrap();
+        let diags: Vec<Diagnostic> = Vec::new();
+        let ctx = EmbedContext {
+            store: &store,
+            schema: &schema,
+            graph: &graph,
+            diagnostics: &diags,
+            baseline: None,
+        };
+        let err = resolve_embed(&req, &ctx).unwrap_err();
+        assert!(matches!(err.kind, EmbedErrorKind::MalformedSyntax(_)));
+    }
+
 }

From f5f5459d4dfd221cb73cf539c71a0fb435235961 Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Wed, 22 Apr 2026 06:48:20 +0200
Subject: [PATCH 3/6] feat(embed): {{stats:type:NAME}} for single-type counts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

{{stats:types}} already renders the full per-type count table; users
asking for a single number — e.g. "how many requirements do we have?"
— had to eyeball it out of the table. Add a granular form
{{stats:type:requirement}} that renders a one-row table with just the
count for the named type.

Unknown types render count=0 rather than erroring, matching SC-EMBED-3:
the rule is "visible output, never silent disappearance". An empty type
name falls back to an `embed-error` span.

Four unit tests: counts correctly, unknown type → zero, empty name →
visible error, and a regression check that the existing {{stats:types}}
form still produces the full multi-row table.

Implements: REQ-007
Refs: FEAT-032
---
 rivet-core/src/embed.rs | 97 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 1 deletion(-)

diff --git a/rivet-core/src/embed.rs b/rivet-core/src/embed.rs
index db19089..dc87a54 100644
--- a/rivet-core/src/embed.rs
+++ b/rivet-core/src/embed.rs
@@ -293,9 +293,21 @@ fn extract_balanced_parens(s: &str) -> Option<(&str, &str)> {
 
 // ── Stats renderer ──────────────────────────────────────────────────────
 
-/// Render `{{stats}}` / `{{stats:types}}` / `{{stats:status}}` / `{{stats:validation}}`.
+/// Render one of:
+/// - `{{stats}}`              — full statistics panel (types + status + validation)
+/// - `{{stats:types}}`        — just the type-count table
+/// - `{{stats:status}}`       — just the status-count table
+/// - `{{stats:validation}}`   — just the per-severity table
+/// - `{{stats:type:NAME}}`    — single count for the named artifact type
 fn render_stats(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> String {
     let section = request.args.first().map(|s| s.as_str());
+    let target_type = request.args.get(1).map(|s| s.as_str());
+
+    // Granular form: {{stats:type:requirement}} → single-cell count.
+    if section == Some("type") {
+        return render_stats_single_type(target_type.unwrap_or(""), ctx);
+    }
+
     let mut html = String::from("<div class=\"embed-stats\">\n");
 
     let show_types = section.is_none() || section == Some("types");
@@ -316,6 +328,32 @@ fn render_stats(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> String {
     html
 }
 
+/// Render `{{stats:type:NAME}}` — just the count for a single artifact type.
+///
+/// Rendered as a compact single-row table so it still looks like the rest of
+/// the stats family.  Unknown types render a zero-count row rather than an
+/// error: this is the "embed never disappears silently" rule (SC-EMBED-3).
+fn render_stats_single_type(type_name: &str, ctx: &EmbedContext<'_>) -> String {
+    let name = type_name.trim();
+    if name.is_empty() {
+        return "<div class=\"embed-stats\"><span class=\"embed-error\">stats:type requires a type name, e.g. <code>{{stats:type:requirement}}</code></span></div>\n".to_string();
+    }
+    let count = ctx
+        .store
+        .iter()
+        .filter(|a| a.artifact_type == name)
+        .count();
+
+    format!(
+        "<div class=\"embed-stats embed-stats-single\">\n\
+         <table class=\"embed-table\"><thead><tr><th>Type</th><th>Count</th></tr></thead><tbody>\n\
+         <tr><td>{typ}</td><td>{count}</td></tr>\n\
+         </tbody></table>\n\
+         </div>\n",
+        typ = document::html_escape(name),
+    )
+}
+
 fn render_stats_types(ctx: &EmbedContext<'_>) -> String {
     let mut by_type = BTreeMap::new();
     for type_name in ctx.schema.artifact_types.keys() {
@@ -1363,4 +1401,61 @@ mod tests {
         assert!(matches!(err.kind, EmbedErrorKind::MalformedSyntax(_)));
     }
 
+    // ── stats:type:NAME granular form ───────────────────────────────
+
+    #[test]
+    fn stats_type_single_name_counts_correctly() {
+        let store = make_store(vec![
+            plain("A", "requirement", None, &[]),
+            plain("B", "requirement", None, &[]),
+            plain("C", "feature", None, &[]),
+        ]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("stats:type:requirement", &store, &schema, &graph).unwrap();
+        assert!(html.contains("embed-stats-single"), "got: {html}");
+        // The single-type row must show count = 2 for requirement.
+        assert!(html.contains("<td>requirement</td>"), "got: {html}");
+        assert!(html.contains("<td>2</td>"), "got: {html}");
+        // Must NOT contain the full stats table sections.
+        assert!(!html.contains("embed-stats-validation"), "got: {html}");
+        assert!(!html.contains("embed-stats-status"), "got: {html}");
+    }
+
+    #[test]
+    fn stats_type_unknown_type_renders_zero_not_error() {
+        let store = make_store(vec![plain("A", "requirement", None, &[])]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("stats:type:nonexistent", &store, &schema, &graph).unwrap();
+        // Still renders a table cell (SC-EMBED-3: no silent disappearance).
+        assert!(html.contains("<td>nonexistent</td>"), "got: {html}");
+        assert!(html.contains("<td>0</td>"), "got: {html}");
+    }
+
+    #[test]
+    fn stats_type_empty_name_renders_embed_error() {
+        let store = Store::new();
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        // `{{stats:type}}` with no third arg — flag as user error, visibly.
+        let html = run_embed("stats:type", &store, &schema, &graph).unwrap();
+        assert!(html.contains("embed-error"), "got: {html}");
+    }
+
+    #[test]
+    fn stats_type_does_not_break_existing_stats_types() {
+        // Regression: the previous {{stats:types}} form must still render
+        // the full table.
+        let store = make_store(vec![
+            plain("A", "requirement", None, &[]),
+            plain("B", "feature", None, &[]),
+        ]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("stats:types", &store, &schema, &graph).unwrap();
+        assert!(html.contains("<table"));
+        assert!(html.contains("requirement"));
+        assert!(html.contains("feature"));
+    }
 }

From c24260404a6eff90aa4e69b55a72f92873c25862 Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Wed, 22 Apr 2026 06:50:47 +0200
Subject: [PATCH 4/6] feat(embed): {{group:FIELD}} count-by-value grouping
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The user report listed {{group:...}} as a missing embed with no stated
semantics. Neither the PR #159 design doc nor the codebase pinned down a
definition, so this commit picks the most useful reading:

  {{group:FIELD}} renders a count-by-value table of the named artifact
  field. Example outputs:

    {{group:status}}  →  draft / approved / shipped counts
    {{group:type}}    →  per-type counts (complement to {{stats:types}})
    {{group:asil}}    →  per-ASIL counts from a custom YAML field

Missing / empty values bucket into "unset" so the totals equal the
project artifact count. List-valued fields (e.g. tags) render as
comma-joined keys — per-tag grouping is a future enhancement.

The renderer reuses the same html_escape / embed-table class set as the
rest of the embeds, and returns an EmbedError for an empty FIELD.

Five unit tests: status grouping with an "unset" row, type grouping,
custom YAML field (asil), empty-field rejection, and empty-store
no-data path.

Implements: REQ-007
Refs: FEAT-032
---
 rivet-core/src/embed.rs | 201 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 201 insertions(+)

diff --git a/rivet-core/src/embed.rs b/rivet-core/src/embed.rs
index dc87a54..419c03c 100644
--- a/rivet-core/src/embed.rs
+++ b/rivet-core/src/embed.rs
@@ -235,6 +235,7 @@ pub fn resolve_embed(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> Result<S
         "diagnostics" => Ok(render_diagnostics(request, ctx)),
         "matrix" => Ok(render_matrix(request, ctx)),
         "query" => render_query(request, ctx),
+        "group" => render_group(request, ctx),
         // Legacy embeds (artifact, links, table) are still handled by
         // resolve_inline in document.rs — they should never reach here.
         "artifact" | "links" | "table" => Err(EmbedError {
@@ -867,6 +868,117 @@ fn render_query(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> Result<String
     Ok(html)
 }
 
+// ── Group renderer ──────────────────────────────────────────────────────
+
+/// Render `{{group:FIELD}}` — count-by-value table grouping existing
+/// artifacts by the given field.
+///
+/// Examples:
+/// - `{{group:status}}` — counts of draft / approved / shipped / unset
+/// - `{{group:type}}` — like `{{stats:types}}` without schema pre-population
+/// - `{{group:asil}}` — per-ASIL counts from a custom field
+///
+/// The "meaning" of this embed is not fully pinned down by prior docs —
+/// this implementation picks the most useful reading (count-by-value) and
+/// documents it alongside the output.  Unset / missing values are bucketed
+/// as "unset" so the totals line up with the project artifact count.
+fn render_group(request: &EmbedRequest, ctx: &EmbedContext<'_>) -> Result<String, EmbedError> {
+    let Some(field) = request.args.first() else {
+        return Err(EmbedError {
+            kind: EmbedErrorKind::MalformedSyntax(
+                "group embed requires a field name: {{group:status}}".into(),
+            ),
+            raw_text: format!("{request:?}"),
+        });
+    };
+    let field = field.trim();
+    if field.is_empty() {
+        return Err(EmbedError {
+            kind: EmbedErrorKind::MalformedSyntax("group field cannot be empty".into()),
+            raw_text: format!("{request:?}"),
+        });
+    }
+
+    let mut counts: BTreeMap<String, usize> = BTreeMap::new();
+    for a in ctx.store.iter() {
+        let raw = read_artifact_field(a, field);
+        // Treat empty/missing as "unset" so the totals always add up.
+        let bucket = if raw.is_empty() {
+            "unset".to_string()
+        } else {
+            raw
+        };
+        *counts.entry(bucket).or_default() += 1;
+    }
+
+    if counts.is_empty() {
+        return Ok(format!(
+            "<div class=\"embed-group\"><p class=\"embed-no-data\">No artifacts to group by <code>{}</code>.</p></div>\n",
+            document::html_escape(field)
+        ));
+    }
+
+    let total: usize = counts.values().sum();
+    let mut html = String::from("<div class=\"embed-group\">\n");
+    let _ = writeln!(
+        html,
+        "<table class=\"embed-table\"><thead><tr><th>{fld}</th><th>Count</th></tr></thead><tbody>",
+        fld = document::html_escape(field),
+    );
+    for (value, count) in &counts {
+        let _ = writeln!(
+            html,
+            "<tr><td>{v}</td><td>{c}</td></tr>",
+            v = document::html_escape(value),
+            c = count,
+        );
+    }
+    let _ = writeln!(
+        html,
+        "<tr class=\"embed-total\"><td><strong>Total</strong></td><td><strong>{total}</strong></td></tr>"
+    );
+    html.push_str("</tbody></table>\n</div>\n");
+    Ok(html)
+}
+
+/// Read a single string value for an artifact field by name.
+///
+/// Handles the well-known top-level fields (id, type, title, status,
+/// description) as well as YAML extension fields stored in `fields`.
+/// List-valued fields (e.g. `tags`) render as a comma-joined string so
+/// `{{group:tags}}` produces stable buckets — individual-tag grouping is
+/// a future enhancement.
+fn read_artifact_field(a: &crate::model::Artifact, name: &str) -> String {
+    match name {
+        "id" => a.id.clone(),
+        "type" => a.artifact_type.clone(),
+        "title" => a.title.clone(),
+        "description" => a.description.clone().unwrap_or_default(),
+        "status" => a.status.clone().unwrap_or_default(),
+        "tags" => a.tags.join(","),
+        other => a
+            .fields
+            .get(other)
+            .map(yaml_value_to_plain_string)
+            .unwrap_or_default(),
+    }
+}
+
+fn yaml_value_to_plain_string(v: &serde_yaml::Value) -> String {
+    match v {
+        serde_yaml::Value::String(s) => s.clone(),
+        serde_yaml::Value::Number(n) => n.to_string(),
+        serde_yaml::Value::Bool(b) => b.to_string(),
+        serde_yaml::Value::Null => String::new(),
+        serde_yaml::Value::Sequence(seq) => seq
+            .iter()
+            .map(yaml_value_to_plain_string)
+            .collect::<Vec<_>>()
+            .join(","),
+        serde_yaml::Value::Mapping(_) | serde_yaml::Value::Tagged(_) => format!("{v:?}"),
+    }
+}
+
 // ── Provenance ──────────────────────────────────────────────────────────
 
 /// Render a provenance footer for export (SC-EMBED-4).
@@ -1458,4 +1570,93 @@ mod tests {
         assert!(html.contains("requirement"));
         assert!(html.contains("feature"));
     }
+
+    // ── {{group:FIELD}} embed ───────────────────────────────────────
+
+    #[test]
+    fn group_embed_counts_by_status() {
+        let store = make_store(vec![
+            plain("A", "requirement", Some("draft"), &[]),
+            plain("B", "requirement", Some("approved"), &[]),
+            plain("C", "requirement", Some("approved"), &[]),
+            plain("D", "requirement", None, &[]), // unset
+        ]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("group:status", &store, &schema, &graph).unwrap();
+        assert!(html.contains("embed-group"));
+        assert!(html.contains("approved"));
+        assert!(html.contains("draft"));
+        assert!(html.contains("unset"), "got: {html}");
+        // 3 + 1 = 4 total
+        assert!(html.contains("<strong>4</strong>"), "got: {html}");
+    }
+
+    #[test]
+    fn group_embed_counts_by_type() {
+        let store = make_store(vec![
+            plain("A", "requirement", None, &[]),
+            plain("B", "feature", None, &[]),
+            plain("C", "feature", None, &[]),
+        ]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("group:type", &store, &schema, &graph).unwrap();
+        // two features, one requirement — assert the cells directly.
+        assert!(html.contains("<td>feature</td>"), "got: {html}");
+        assert!(html.contains("<td>2</td>"), "got: {html}");
+        assert!(html.contains("<td>requirement</td>"), "got: {html}");
+        assert!(html.contains("<td>1</td>"), "got: {html}");
+    }
+
+    #[test]
+    fn group_embed_by_custom_field() {
+        // ASIL is a common custom YAML field; group-by that.
+        let mut a = plain("A", "requirement", None, &[]);
+        a.fields.insert(
+            "asil".into(),
+            serde_yaml::Value::String("ASIL-B".into()),
+        );
+        let mut b = plain("B", "requirement", None, &[]);
+        b.fields.insert(
+            "asil".into(),
+            serde_yaml::Value::String("ASIL-B".into()),
+        );
+        let c = plain("C", "requirement", None, &[]); // no asil → unset
+        let store = make_store(vec![a, b, c]);
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("group:asil", &store, &schema, &graph).unwrap();
+        assert!(html.contains("ASIL-B"), "got: {html}");
+        assert!(html.contains("<td>2</td>"), "got: {html}");
+        assert!(html.contains("unset"), "got: {html}");
+    }
+
+    #[test]
+    fn group_embed_rejects_empty_field() {
+        let store = Store::new();
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let req = EmbedRequest::parse("group:").unwrap();
+        let diags: Vec<Diagnostic> = Vec::new();
+        let ctx = EmbedContext {
+            store: &store,
+            schema: &schema,
+            graph: &graph,
+            diagnostics: &diags,
+            baseline: None,
+        };
+        let err = resolve_embed(&req, &ctx).unwrap_err();
+        assert!(matches!(err.kind, EmbedErrorKind::MalformedSyntax(_)));
+    }
+
+    #[test]
+    fn group_embed_empty_store_renders_no_data() {
+        let store = Store::new();
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        let html = run_embed("group:status", &store, &schema, &graph).unwrap();
+        assert!(html.contains("embed-group"), "got: {html}");
+        assert!(html.contains("No artifacts"), "got: {html}");
+    }
 }

From f4c3c306167fbb2403bad6a9cad40b7277182491 Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Wed, 22 Apr 2026 07:00:24 +0200
Subject: [PATCH 5/6] feat(cli): `rivet docs embeds` + embed registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds `rivet_core::embed::EMBED_REGISTRY` — a `&[EmbedSpec]` slice with
one entry per known embed (`stats`, `coverage`, `diagnostics`, `matrix`,
`query`, `group`, plus the legacy `artifact` / `links` / `table`
inline embeds). Each spec carries the `name`, a compact `args` signature,
a one-line `summary`, a runnable `example`, and a `legacy` flag so the
inline embeds are still listed even though they dispatch from
`document.rs` rather than `resolve_embed`.

Surfaces the registry in three places so discoverability stays in sync:

- `rivet docs embeds` (and `--format json`) — prints an aligned table or
  emits a machine-readable list; usage footer points at `rivet embed`
  and `rivet docs embed-syntax`.
- Dashboard Help view — new "Document Embeds" card built from the same
  registry so users browsing at /help see the exact same set.
- Unit tests assert that every name dispatched in `resolve_embed` also
  appears in `EMBED_REGISTRY`, and that every registry example parses
  via `EmbedRequest::parse` (catches copy-paste rot).

Integration tests in `rivet-cli/tests/embeds_help.rs` walk the built
binary end-to-end for both text and JSON output.

While here, fix a latent order-dependent assertion in the earlier
`query_embed_matches_sexpr_filter` test — store iteration is not
stable, so compare as a sorted set instead.

Implements: REQ-007
Refs: FEAT-032, FEAT-001
---
 rivet-cli/src/docs.rs          |  62 +++++++++++++
 rivet-cli/src/main.rs          |  10 +-
 rivet-cli/src/render/help.rs   |  49 ++++++++++
 rivet-cli/tests/embeds_help.rs |  99 ++++++++++++++++++++
 rivet-core/src/embed.rs        | 164 ++++++++++++++++++++++++++++++++-
 5 files changed, 381 insertions(+), 3 deletions(-)
 create mode 100644 rivet-cli/tests/embeds_help.rs

diff --git a/rivet-cli/src/docs.rs b/rivet-cli/src/docs.rs
index d4873ad..10c2315 100644
--- a/rivet-cli/src/docs.rs
+++ b/rivet-cli/src/docs.rs
@@ -996,6 +996,68 @@ pub fn list_topics(format: &str) -> String {
     out
 }
 
+/// List every registered computed embed token.
+///
+/// Sourced from `rivet_core::embed::EMBED_REGISTRY` so the listing never
+/// drifts from what `resolve_embed` actually dispatches.
+pub fn list_embeds(format: &str) -> String {
+    let specs = rivet_core::embed::registry();
+
+    if format == "json" {
+        let items: Vec<serde_json::Value> = specs
+            .iter()
+            .map(|s| {
+                serde_json::json!({
+                    "name": s.name,
+                    "args": s.args,
+                    "summary": s.summary,
+                    "example": s.example,
+                    "legacy": s.legacy,
+                })
+            })
+            .collect();
+        return serde_json::to_string_pretty(&serde_json::json!({
+            "command": "docs-embeds",
+            "embeds": items,
+        }))
+        .unwrap_or_default();
+    }
+
+    // Plain-text: aligned columns with a short footer pointing to the
+    // full syntax reference and to `rivet embed` for CLI rendering.
+    let name_w = specs.iter().map(|s| s.name.len()).max().unwrap_or(4);
+    let args_w = specs.iter().map(|s| s.args.len()).max().unwrap_or(6);
+    let mut out = String::new();
+    out.push_str("Registered computed embeds:\n\n");
+    out.push_str(&format!(
+        "  {:<nw$}  {:<aw$}  SUMMARY\n",
+        "NAME",
+        "ARGS",
+        nw = name_w,
+        aw = args_w
+    ));
+    for s in specs {
+        let marker = if s.legacy { " (inline)" } else { "" };
+        out.push_str(&format!(
+            "  {:<nw$}  {:<aw$}  {}{}\n",
+            s.name,
+            s.args,
+            s.summary,
+            marker,
+            nw = name_w,
+            aw = args_w
+        ));
+    }
+    out.push_str("\nExamples:\n");
+    for s in specs {
+        out.push_str(&format!("  {:<nw$}  {}\n", s.name, s.example, nw = name_w));
+    }
+    out.push_str("\nUsage:\n");
+    out.push_str("  rivet embed <NAME>[:args]     Render any embed from the CLI\n");
+    out.push_str("  rivet docs embed-syntax       Full {{...}} syntax reference\n");
+    out
+}
+
 /// Show a specific topic.
 pub fn show_topic(slug: &str, format: &str) -> String {
     let Some(topic) = TOPICS.iter().find(|t| t.slug == slug) else {
diff --git a/rivet-cli/src/main.rs b/rivet-cli/src/main.rs
index 6623c83..d9e4556 100644
--- a/rivet-cli/src/main.rs
+++ b/rivet-cli/src/main.rs
@@ -5949,7 +5949,15 @@ fn cmd_docs(
     } else if let Some(pattern) = grep {
         print!("{}", docs::grep_docs(pattern, format, context));
     } else if let Some(slug) = topic {
-        print!("{}", docs::show_topic(slug, format));
+        // Special meta-topic: `rivet docs embeds` lists every registered
+        // {{...}} token from `rivet_core::embed::EMBED_REGISTRY`.  Kept in
+        // `docs` (rather than a new top-level subcommand) so it ships in
+        // the existing --help tree and stays near `docs embed-syntax`.
+        if slug == "embeds" {
+            print!("{}", docs::list_embeds(format));
+        } else {
+            print!("{}", docs::show_topic(slug, format));
+        }
     } else {
         print!("{}", docs::list_topics(format));
     }
diff --git a/rivet-cli/src/render/help.rs b/rivet-cli/src/render/help.rs
index e9862e2..5420599 100644
--- a/rivet-cli/src/render/help.rs
+++ b/rivet-cli/src/render/help.rs
@@ -207,9 +207,58 @@ pub(crate) fn render_help(ctx: &RenderContext) -> String {
     html.push_str("rivet schema list           List artifact types\n");
     html.push_str("rivet schema show TYPE      Show type details\n");
     html.push_str("rivet docs                  List documentation topics\n");
+    html.push_str("rivet docs embeds           List {{...}} embed tokens\n");
     html.push_str("rivet serve [-P PORT]       Start dashboard\n");
     html.push_str("</pre></div>");
 
+    // Registered embeds — sourced from rivet_core::embed::EMBED_REGISTRY so
+    // the dashboard listing matches `rivet docs embeds` exactly.
+    html.push_str(&render_embed_registry());
+
+    html
+}
+
+/// Render the embed registry table for the Help view.
+///
+/// Mirrors the output of `rivet docs embeds` so users can discover
+/// `{{stats}}`, `{{query:(...)}}`, `{{artifact:ID}}`, etc. without having
+/// to read the source or grep the docs.
+fn render_embed_registry() -> String {
+    use rivet_core::embed::registry;
+    let specs = registry();
+
+    let mut html = String::with_capacity(4096);
+    html.push_str(
+        r#"<div class="card" style="padding:1.25rem;margin-top:1rem">
+        <h3 style="margin:0 0 1rem">Document Embeds</h3>
+        <p style="opacity:.7;font-size:.85rem;margin:0 0 .75rem">
+            Use <code>{{name[:args]}}</code> inside an artifact description or document body.
+            Run <code>rivet docs embeds</code> for the same list from the CLI, or
+            <code>rivet docs embed-syntax</code> for the full reference.
+        </p>
+        <table style="font-size:.85rem">
+        <thead><tr><th>Name</th><th>Args</th><th>Summary</th><th>Example</th></tr></thead>
+        <tbody>
+"#,
+    );
+    for s in specs {
+        html.push_str(&format!(
+            "<tr><td><code>{name}</code>{marker}</td>\
+             <td><code>{args}</code></td>\
+             <td>{summary}</td>\
+             <td><code>{example}</code></td></tr>\n",
+            name = html_escape(s.name),
+            marker = if s.legacy {
+                r#" <span style="opacity:.6;font-size:.75rem">(inline)</span>"#
+            } else {
+                ""
+            },
+            args = html_escape(s.args),
+            summary = html_escape(s.summary),
+            example = html_escape(s.example),
+        ));
+    }
+    html.push_str("</tbody></table></div>");
     html
 }
 
diff --git a/rivet-cli/tests/embeds_help.rs b/rivet-cli/tests/embeds_help.rs
new file mode 100644
index 0000000..a4fc46c
--- /dev/null
+++ b/rivet-cli/tests/embeds_help.rs
@@ -0,0 +1,99 @@
+//! Integration tests for `rivet docs embeds` — the computed embed listing.
+//!
+//! The listing is sourced from `rivet_core::embed::EMBED_REGISTRY` so these
+//! tests also serve as regressions for the registry itself.
+
+use std::process::Command;
+
+fn rivet_bin() -> std::path::PathBuf {
+    if let Ok(bin) = std::env::var("CARGO_BIN_EXE_rivet") {
+        return std::path::PathBuf::from(bin);
+    }
+    let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let workspace_root = manifest.parent().expect("workspace root");
+    workspace_root.join("target").join("debug").join("rivet")
+}
+
+/// `rivet docs embeds` lists every registered computed embed.
+#[test]
+fn docs_embeds_lists_known_tokens() {
+    let output = Command::new(rivet_bin())
+        .args(["docs", "embeds"])
+        .output()
+        .expect("failed to execute rivet docs embeds");
+
+    assert!(
+        output.status.success(),
+        "rivet docs embeds must exit 0; stderr: {}",
+        String::from_utf8_lossy(&output.stderr),
+    );
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+
+    // All dispatched embed names must appear — if resolve_embed grows a
+    // new handler the author must also extend EMBED_REGISTRY.
+    for name in [
+        "stats",
+        "coverage",
+        "diagnostics",
+        "matrix",
+        "query",
+        "group",
+        "artifact",
+        "links",
+        "table",
+    ] {
+        assert!(
+            stdout.contains(name),
+            "embed '{name}' missing from `rivet docs embeds` output:\n{stdout}"
+        );
+    }
+
+    // The output must be self-describing, not just a name dump.
+    assert!(stdout.contains("NAME"), "expected NAME header, got:\n{stdout}");
+    assert!(stdout.contains("ARGS"), "expected ARGS header, got:\n{stdout}");
+    // Legacy markers help users understand that artifact/links/table live
+    // in the inline resolver rather than resolve_embed.
+    assert!(
+        stdout.contains("(inline)"),
+        "legacy embeds should be marked; got:\n{stdout}"
+    );
+    // Usage footer points users at concrete next steps.
+    assert!(
+        stdout.contains("rivet embed"),
+        "expected `rivet embed` usage hint, got:\n{stdout}"
+    );
+}
+
+/// `rivet docs embeds --format json` produces machine-readable output
+/// matching the same registry.
+#[test]
+fn docs_embeds_json() {
+    let output = Command::new(rivet_bin())
+        .args(["docs", "embeds", "--format", "json"])
+        .output()
+        .expect("failed to execute rivet docs embeds --format json");
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+
+    let val: serde_json::Value =
+        serde_json::from_str(&stdout).expect("output must be valid JSON");
+    assert_eq!(val["command"], "docs-embeds");
+    let embeds = val["embeds"].as_array().expect("embeds must be array");
+    let names: Vec<&str> = embeds
+        .iter()
+        .filter_map(|v| v["name"].as_str())
+        .collect();
+    for required in ["stats", "coverage", "query", "group", "artifact"] {
+        assert!(names.contains(&required), "missing {required} in {names:?}");
+    }
+    // Every entry has the four advertised fields.
+    for e in embeds {
+        assert!(e["name"].is_string());
+        assert!(e["args"].is_string());
+        assert!(e["summary"].is_string());
+        assert!(e["example"].is_string());
+        assert!(e["legacy"].is_boolean());
+    }
+}
diff --git a/rivet-core/src/embed.rs b/rivet-core/src/embed.rs
index 419c03c..bf4af77 100644
--- a/rivet-core/src/embed.rs
+++ b/rivet-core/src/embed.rs
@@ -103,6 +103,109 @@ impl<'a> EmbedContext<'a> {
     }
 }
 
+// ── Embed registry ──────────────────────────────────────────────────────
+
+/// A single entry in the embed registry.
+///
+/// Every `{{name[:args...]}}` token that `resolve_embed` or the document
+/// inline resolver knows about has a matching `EmbedSpec`.  This is the
+/// single source of truth for `rivet docs embeds`, the dashboard Help view,
+/// and any future UX that needs to enumerate embeds.
+#[derive(Debug, Clone, Copy)]
+pub struct EmbedSpec {
+    /// Embed name as it appears after `{{`.
+    pub name: &'static str,
+    /// Compact signature, e.g. `[section]` or `(sexpr) [limit=N]`.
+    pub args: &'static str,
+    /// One-line description for the listing.
+    pub summary: &'static str,
+    /// Runnable example that users can paste into a document.
+    pub example: &'static str,
+    /// True if handled by the inline resolver in `document.rs` rather than
+    /// by `resolve_embed`.  Legacy embeds still appear in listings.
+    pub legacy: bool,
+}
+
+/// The canonical list of registered embeds.
+///
+/// Order is the order shown to users; group newest (or least-known) embeds
+/// near the top of their family so they are discoverable.
+pub const EMBED_REGISTRY: &[EmbedSpec] = &[
+    EmbedSpec {
+        name: "stats",
+        args: "[section|type:NAME]",
+        summary: "Project statistics (types, status, validation) or count for a single type",
+        example: "{{stats}}  /  {{stats:types}}  /  {{stats:type:requirement}}",
+        legacy: false,
+    },
+    EmbedSpec {
+        name: "coverage",
+        args: "[rule]",
+        summary: "Traceability coverage bars; with a rule name, lists uncovered IDs",
+        example: "{{coverage}}  /  {{coverage:req-implements-feat}}",
+        legacy: false,
+    },
+    EmbedSpec {
+        name: "diagnostics",
+        args: "[severity]",
+        summary: "Validation findings (all, or filtered by error|warning|info)",
+        example: "{{diagnostics}}  /  {{diagnostics:error}}",
+        legacy: false,
+    },
+    EmbedSpec {
+        name: "matrix",
+        args: "[FROM:TO]",
+        summary: "Traceability matrix — one per schema rule, or a specific type pair",
+        example: "{{matrix}}  /  {{matrix:requirement:feature}}",
+        legacy: false,
+    },
+    EmbedSpec {
+        name: "query",
+        args: "(sexpr) [limit=N]",
+        summary: "Results of an s-expression filter as a compact table (id/type/title/status)",
+        example: "{{query:(and (= type \"requirement\") (has-tag \"stpa\"))}}",
+        legacy: false,
+    },
+    EmbedSpec {
+        name: "group",
+        args: "FIELD",
+        summary: "Count-by-value table grouping artifacts by the given field",
+        example: "{{group:status}}  /  {{group:asil}}",
+        legacy: false,
+    },
+    // Legacy embeds — resolved inline in document.rs, but still listed here
+    // so users can discover them via `rivet docs embeds`.
+    EmbedSpec {
+        name: "artifact",
+        args: "ID[:modifier[:depth]]",
+        summary: "Inline card for a single artifact (default|full|links|upstream|downstream|chain)",
+        example: "{{artifact:REQ-001}}  /  {{artifact:REQ-001:full}}",
+        legacy: true,
+    },
+    EmbedSpec {
+        name: "links",
+        args: "ID",
+        summary: "Incoming + outgoing link table for an artifact",
+        example: "{{links:REQ-001}}",
+        legacy: true,
+    },
+    EmbedSpec {
+        name: "table",
+        args: "TYPE:FIELDS",
+        summary: "Filtered artifact table for a single type with comma-separated columns",
+        example: "{{table:requirement:id,title,status}}",
+        legacy: true,
+    },
+];
+
+/// Return the full embed registry.
+///
+/// Convenience accessor — callers that want the raw slice can also use
+/// `EMBED_REGISTRY` directly.
+pub fn registry() -> &'static [EmbedSpec] {
+    EMBED_REGISTRY
+}
+
 // ── Parsing ─────────────────────────────────────────────────────────────
 
 impl EmbedRequest {
@@ -1431,13 +1534,15 @@ mod tests {
         assert!(html.contains("REQ-2"), "got: {html}");
         assert!(!html.contains("FEAT-1"), "got: {html}");
 
-        // Cross-check via the same evaluator directly.
+        // Cross-check via the same evaluator directly.  Store iteration
+        // order is not guaranteed, so compare as a sorted set.
         let expr = crate::sexpr_eval::parse_filter(r#"(= type "requirement")"#).unwrap();
-        let direct_ids: Vec<String> = store
+        let mut direct_ids: Vec<String> = store
             .iter()
             .filter(|a| crate::sexpr_eval::matches_filter_with_store(&expr, a, &graph, &store))
             .map(|a| a.id.clone())
             .collect();
+        direct_ids.sort();
         assert_eq!(direct_ids, vec!["REQ-1".to_string(), "REQ-2".to_string()]);
     }
 
@@ -1659,4 +1764,59 @@ mod tests {
         assert!(html.contains("embed-group"), "got: {html}");
         assert!(html.contains("No artifacts"), "got: {html}");
     }
+
+    // ── Registry invariants ─────────────────────────────────────────
+
+    /// Every embed that resolve_embed dispatches must appear in
+    /// EMBED_REGISTRY — otherwise `rivet docs embeds` lies by omission.
+    #[test]
+    fn registry_covers_all_dispatched_embeds() {
+        let dispatched = [
+            "stats",
+            "coverage",
+            "diagnostics",
+            "matrix",
+            "query",
+            "group",
+            // Legacy — still listed:
+            "artifact",
+            "links",
+            "table",
+        ];
+        let registered: Vec<&str> = EMBED_REGISTRY.iter().map(|s| s.name).collect();
+        for name in &dispatched {
+            assert!(
+                registered.contains(name),
+                "embed '{name}' is dispatched but not in EMBED_REGISTRY",
+            );
+        }
+    }
+
+    /// Each registry entry's example must itself be a parseable embed so
+    /// the listing output is copy-pasteable without further editing.
+    #[test]
+    fn registry_examples_parse() {
+        for spec in EMBED_REGISTRY {
+            // Strip the outer {{ }} and parse the first example.  Many
+            // examples list multiple variants separated by "  /  ";
+            // testing the first is enough to catch regressions.
+            let first = spec.example.split("  /  ").next().unwrap().trim();
+            let inner = first
+                .trim_start_matches("{{")
+                .trim_end_matches("}}")
+                .trim();
+            EmbedRequest::parse(inner)
+                .unwrap_or_else(|e| panic!("registry example for '{}' failed to parse: {e}", spec.name));
+        }
+    }
+
+    #[test]
+    fn registry_has_stable_entries() {
+        // Smoke test: hold the registry to at least these entries.  Stops
+        // accidental deletions.
+        let names: Vec<&str> = EMBED_REGISTRY.iter().map(|s| s.name).collect();
+        for required in ["stats", "coverage", "query", "group", "artifact"] {
+            assert!(names.contains(&required));
+        }
+    }
 }

From ede6a364d73be01a6438d2f3ee001d85d2712813 Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Wed, 22 Apr 2026 08:12:32 +0200
Subject: [PATCH 6/6] feat(cli): `rivet query --sexpr ...` mirrors MCP
 rivet_query
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lifts the shared s-expression evaluation path into
`rivet_core::query::execute_sexpr` so MCP's `rivet_query` tool, the new
`rivet query` CLI, and the `{{query:(...)}}` document embed all converge
on one function.  The result struct carries `matches`, `total`, and a
`truncated` flag so callers can render the same "Showing N of M" footer
without re-running the filter.

CLI surface:

    rivet query --sexpr '(and (= type "requirement") (has-tag "stpa"))'
    rivet query --sexpr '...' --format json    # MCP shape envelope
    rivet query --sexpr '...' --format ids     # newline-separated IDs
    rivet query --sexpr '...' --limit 25

Three output formats — text (aligned columns), json (the MCP envelope
`{filter, count, total, truncated, artifacts[]}`), and ids (for shell
pipelines: `rivet query --format ids | xargs -n1 rivet show`).

MCP's `tool_query` is refactored to use `execute_sexpr` directly and
now returns the same envelope shape (adding `total` + `truncated`
fields alongside the existing `filter`, `count`, `artifacts`), so
scripts working against MCP and CLI read identical JSON.

Five unit tests in `rivet_core::query::tests` (type filter, limit +
truncation, empty-filter-matches-all, parse-error propagation, tag
filter agreement with `rivet list --filter`).  Three integration tests
in `rivet-cli/tests/cli_commands.rs` exercise the binary end-to-end for
`--format ids` vs. `rivet list --type`, the MCP-shape JSON envelope,
and the error path for an unbalanced s-expression.

Implements: REQ-007
Refs: FEAT-010, FEAT-032
---
 rivet-cli/src/main.rs           | 110 +++++++++++++++++++++
 rivet-cli/src/mcp.rs            |  71 +++++++-------
 rivet-cli/tests/cli_commands.rs | 127 ++++++++++++++++++++++++
 rivet-core/src/query.rs         | 167 ++++++++++++++++++++++++++++++++
 4 files changed, 438 insertions(+), 37 deletions(-)

diff --git a/rivet-cli/src/main.rs b/rivet-cli/src/main.rs
index d9e4556..f4354bd 100644
--- a/rivet-cli/src/main.rs
+++ b/rivet-cli/src/main.rs
@@ -699,6 +699,25 @@ enum Command {
         format: String,
     },
 
+    /// Run an s-expression filter against the project and print matches
+    ///
+    /// Mirror of the MCP `rivet_query` tool and the `{{query:(...)}}`
+    /// document embed — all three share `rivet_core::query::execute_sexpr`
+    /// so their results agree for the same filter.
+    Query {
+        /// The s-expression filter (e.g. '(and (= type "requirement") (has-tag "stpa"))')
+        #[arg(long)]
+        sexpr: String,
+
+        /// Maximum number of results (default: 100)
+        #[arg(long, default_value = "100")]
+        limit: usize,
+
+        /// Output format: "text" (default), "json", "ids"
+        #[arg(short, long, default_value = "text")]
+        format: String,
+    },
+
     /// Stamp artifact(s) with AI provenance metadata
     Stamp {
         /// Artifact ID to stamp (or "all" for all artifacts in a file)
@@ -1214,6 +1233,11 @@ fn run(cli: Cli) -> Result<bool> {
         Command::Remove { id, force } => cmd_remove(&cli, id, *force),
         Command::Batch { file } => cmd_batch(&cli, file),
         Command::Embed { query, format } => cmd_embed(&cli, query, format),
+        Command::Query {
+            sexpr,
+            limit,
+            format,
+        } => cmd_query(&cli, sexpr, *limit, format),
         Command::Stamp {
             id,
             created_by,
@@ -8765,6 +8789,92 @@ fn cmd_mcp(cli: &Cli) -> Result<bool> {
     Ok(true)
 }
 
+/// `rivet query --sexpr "..."` — run an s-expression filter from the CLI.
+///
+/// Thin adapter over `rivet_core::query::execute_sexpr`, the same entry
+/// point used by MCP's `rivet_query` tool and the `{{query:(...)}}` embed,
+/// so all three surfaces emit the same match set for the same filter.
+/// Three output formats: `text` (one line per match, id + title + status),
+/// `json` (MCP-shape: `{filter, count, total, truncated, artifacts[]}`),
+/// or `ids` (newline-separated IDs — handy for shell pipelines).
+fn cmd_query(cli: &Cli, sexpr: &str, limit: usize, format: &str) -> Result<bool> {
+    validate_format(format, &["text", "json", "ids"])?;
+
+    let project = rivet_core::load_project_full(&cli.project)
+        .with_context(|| format!("loading project from {}", cli.project.display()))?;
+
+    let result =
+        rivet_core::query::execute_sexpr(&project.store, &project.graph, sexpr, Some(limit))
+            .map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    match format {
+        "json" => {
+            let artifacts: Vec<serde_json::Value> = result
+                .matches
+                .iter()
+                .map(|a| {
+                    let links: Vec<serde_json::Value> = a
+                        .links
+                        .iter()
+                        .map(|l| {
+                            serde_json::json!({"type": l.link_type, "target": l.target})
+                        })
+                        .collect();
+                    serde_json::json!({
+                        "id": a.id,
+                        "type": a.artifact_type,
+                        "title": a.title,
+                        "status": a.status.as_deref().unwrap_or("-"),
+                        "tags": a.tags,
+                        "links": links,
+                        "description": a.description.as_deref().unwrap_or(""),
+                    })
+                })
+                .collect();
+            let out = serde_json::json!({
+                "filter": sexpr,
+                "count": artifacts.len(),
+                "total": result.total,
+                "truncated": result.truncated,
+                "artifacts": artifacts,
+            });
+            println!("{}", serde_json::to_string_pretty(&out)?);
+        }
+        "ids" => {
+            for a in &result.matches {
+                println!("{}", a.id);
+            }
+        }
+        _ => {
+            // text
+            if result.matches.is_empty() {
+                println!("No artifacts match: {sexpr}");
+            } else {
+                for a in &result.matches {
+                    println!(
+                        "{:16} {:16} {:8} {}",
+                        a.id,
+                        a.artifact_type,
+                        a.status.as_deref().unwrap_or("-"),
+                        a.title,
+                    );
+                }
+                if result.truncated {
+                    println!(
+                        "\n{} result(s) shown, {} match total — raise --limit to see more.",
+                        result.matches.len(),
+                        result.total,
+                    );
+                } else {
+                    println!("\n{} result(s).", result.matches.len());
+                }
+            }
+        }
+    }
+
+    Ok(true)
+}
+
 fn cmd_lsp(cli: &Cli) -> Result<bool> {
     use lsp_server::{Connection, Message, Response};
     use lsp_types::*;
diff --git a/rivet-cli/src/mcp.rs b/rivet-cli/src/mcp.rs
index 4a30785..260bdb1 100644
--- a/rivet-cli/src/mcp.rs
+++ b/rivet-cli/src/mcp.rs
@@ -943,46 +943,43 @@ fn json_to_yaml_value(v: &Value) -> serde_yaml::Value {
 // ── Query tool helper ─────────────────────────────────────────────────
 
 fn tool_query(proj: &McpProject, params: &QueryParams) -> Result<Value> {
-    let expr = rivet_core::sexpr_eval::parse_filter(&params.filter).map_err(|errs| {
-        let msgs: Vec<String> = errs.iter().map(|e| e.to_string()).collect();
-        anyhow::anyhow!("invalid filter: {}", msgs.join("; "))
-    })?;
-
-    let limit = params.limit.unwrap_or(100);
-    let mut results: Vec<Value> = Vec::new();
-
-    for artifact in proj.store.iter() {
-        if !rivet_core::sexpr_eval::matches_filter_with_store(
-            &expr,
-            artifact,
-            &proj.graph,
-            &proj.store,
-        ) {
-            continue;
-        }
-        let links_json: Vec<Value> = artifact
-            .links
-            .iter()
-            .map(|l| json!({"type": l.link_type, "target": l.target}))
-            .collect();
-        results.push(json!({
-            "id": artifact.id,
-            "type": artifact.artifact_type,
-            "title": artifact.title,
-            "status": artifact.status.as_deref().unwrap_or("-"),
-            "tags": artifact.tags,
-            "links": links_json,
-            "description": artifact.description.as_deref().unwrap_or(""),
-        }));
-        if results.len() >= limit {
-            break;
-        }
-    }
+    // Shared path with `rivet query` and the `{{query:...}}` embed so all
+    // three surfaces return the same artifact set for the same filter.
+    let result = rivet_core::query::execute_sexpr(
+        &proj.store,
+        &proj.graph,
+        &params.filter,
+        Some(params.limit.unwrap_or(100)),
+    )
+    .map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    let artifacts: Vec<Value> = result
+        .matches
+        .iter()
+        .map(|a| {
+            let links_json: Vec<Value> = a
+                .links
+                .iter()
+                .map(|l| json!({"type": l.link_type, "target": l.target}))
+                .collect();
+            json!({
+                "id": a.id,
+                "type": a.artifact_type,
+                "title": a.title,
+                "status": a.status.as_deref().unwrap_or("-"),
+                "tags": a.tags,
+                "links": links_json,
+                "description": a.description.as_deref().unwrap_or(""),
+            })
+        })
+        .collect();
 
     Ok(json!({
         "filter": params.filter,
-        "count": results.len(),
-        "artifacts": results,
+        "count": artifacts.len(),
+        "total": result.total,
+        "truncated": result.truncated,
+        "artifacts": artifacts,
     }))
 }
 
diff --git a/rivet-cli/tests/cli_commands.rs b/rivet-cli/tests/cli_commands.rs
index 247ac31..f02be47 100644
--- a/rivet-cli/tests/cli_commands.rs
+++ b/rivet-cli/tests/cli_commands.rs
@@ -1895,3 +1895,130 @@ fn validate_fail_on_invalid_value_rejected() {
         "error must mention the bad value, got: {stderr}"
     );
 }
+
+// ── rivet query (REQ-007) ───────────────────────────────────────────────
+
+/// `rivet query --sexpr ... --format ids` prints one ID per line.
+#[test]
+fn query_ids_format_matches_list_filter() {
+    let bin = rivet_bin();
+    let root = project_root();
+
+    // `rivet list --type requirement` — one line per matching artifact (id + title).
+    let list_out = Command::new(&bin)
+        .args(["--project", &root.display().to_string(), "list", "--type", "requirement"])
+        .output()
+        .expect("run rivet list");
+    assert!(list_out.status.success(), "rivet list must succeed");
+    let list_stdout = String::from_utf8_lossy(&list_out.stdout);
+
+    // `rivet query --sexpr '(= type "requirement")' --format ids` → only IDs.
+    let query_out = Command::new(&bin)
+        .args([
+            "--project",
+            &root.display().to_string(),
+            "query",
+            "--sexpr",
+            r#"(= type "requirement")"#,
+            "--limit",
+            "1000",
+            "--format",
+            "ids",
+        ])
+        .output()
+        .expect("run rivet query");
+    assert!(
+        query_out.status.success(),
+        "rivet query must succeed; stderr: {}",
+        String::from_utf8_lossy(&query_out.stderr)
+    );
+    let query_stdout = String::from_utf8_lossy(&query_out.stdout);
+    let query_ids: Vec<&str> = query_stdout.lines().filter(|l| !l.is_empty()).collect();
+
+    assert!(
+        !query_ids.is_empty(),
+        "rivet query must return some requirements; got:\n{query_stdout}"
+    );
+
+    // Every ID that `rivet query` reports must also appear somewhere in
+    // `rivet list`'s output — confirms the two surfaces agree.
+    for id in &query_ids {
+        assert!(
+            list_stdout.contains(id),
+            "id {id} from `rivet query` not found in `rivet list --type requirement` output",
+        );
+    }
+}
+
+/// `rivet query --format json` produces MCP-shape output: filter, count,
+/// total, truncated, artifacts[].
+#[test]
+fn query_json_format_envelope() {
+    let bin = rivet_bin();
+    let root = project_root();
+
+    let out = Command::new(&bin)
+        .args([
+            "--project",
+            &root.display().to_string(),
+            "query",
+            "--sexpr",
+            r#"(= type "requirement")"#,
+            "--limit",
+            "5",
+            "--format",
+            "json",
+        ])
+        .output()
+        .expect("run rivet query");
+
+    assert!(
+        out.status.success(),
+        "rivet query --format json must succeed; stderr: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let val: serde_json::Value =
+        serde_json::from_str(&stdout).expect("output must be valid JSON");
+
+    assert_eq!(
+        val["filter"].as_str(),
+        Some(r#"(= type "requirement")"#),
+        "filter field must echo input",
+    );
+    assert!(val["count"].is_number(), "count must be a number");
+    assert!(val["total"].is_number(), "total must be a number");
+    assert!(val["truncated"].is_boolean(), "truncated must be a bool");
+    let arts = val["artifacts"].as_array().expect("artifacts must be array");
+    assert!(arts.len() <= 5, "respects --limit");
+    for a in arts {
+        assert!(a["id"].is_string());
+        assert!(a["type"].is_string());
+        assert!(a["title"].is_string());
+    }
+}
+
+/// Invalid filter → non-zero exit with a helpful error.
+#[test]
+fn query_invalid_filter_reports_parse_error() {
+    let bin = rivet_bin();
+    let root = project_root();
+
+    let out = Command::new(&bin)
+        .args([
+            "--project",
+            &root.display().to_string(),
+            "query",
+            "--sexpr",
+            "(and (= type", // unbalanced
+        ])
+        .output()
+        .expect("run rivet query");
+
+    assert!(!out.status.success(), "unbalanced filter must fail");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("invalid filter") || stderr.contains("filter"),
+        "stderr should mention the filter error; got: {stderr}"
+    );
+}
diff --git a/rivet-core/src/query.rs b/rivet-core/src/query.rs
index 80e9c9a..4f02139 100644
--- a/rivet-core/src/query.rs
+++ b/rivet-core/src/query.rs
@@ -1,6 +1,8 @@
 //! Query engine for filtering artifacts.
 
+use crate::links::LinkGraph;
 use crate::model::Artifact;
+use crate::sexpr_eval;
 use crate::store::Store;
 
 /// Filter criteria for querying artifacts.
@@ -48,3 +50,168 @@ impl Query {
 pub fn execute<'a>(store: &'a Store, query: &Query) -> Vec<&'a Artifact> {
     store.iter().filter(|a| query.matches(a)).collect()
 }
+
+// ── S-expression query execution ────────────────────────────────────────
+
+/// Result of a single s-expression query — shared shape across MCP, CLI,
+/// and the `{{query:...}}` embed so callers see one canonical output.
+#[derive(Debug, Clone)]
+pub struct SexprQueryResult<'a> {
+    pub filter: String,
+    pub matches: Vec<&'a Artifact>,
+    /// Total number of artifacts that match the filter, ignoring `limit`.
+    pub total: usize,
+    /// True if the limit truncated the result set.
+    pub truncated: bool,
+}
+
+/// Error from parsing a filter passed to [`execute_sexpr`].
+///
+/// This is a plain string so callers (MCP, CLI, embed) can format it into
+/// their own error channel without pulling in the rivet-core dependency
+/// tree for `FilterError`.
+#[derive(Debug, Clone)]
+pub struct SexprQueryError(pub String);
+
+impl std::fmt::Display for SexprQueryError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "invalid filter: {}", self.0)
+    }
+}
+
+impl std::error::Error for SexprQueryError {}
+
+/// Execute an s-expression filter against `store`, returning the matches.
+///
+/// Wraps `sexpr_eval::parse_filter` + `matches_filter_with_store` so MCP
+/// (`rivet_query` tool), the CLI (`rivet query`), and the `{{query:...}}`
+/// embed all converge on a single code path.  `limit` caps the returned
+/// `matches` slice; `total` reports the untruncated count so callers can
+/// show "Showing N of M" style footers without re-running the filter.
+pub fn execute_sexpr<'a>(
+    store: &'a Store,
+    graph: &LinkGraph,
+    filter: &str,
+    limit: Option<usize>,
+) -> Result<SexprQueryResult<'a>, SexprQueryError> {
+    let expr = sexpr_eval::parse_filter(filter).map_err(|errs| {
+        let msg = errs
+            .iter()
+            .map(|e| e.to_string())
+            .collect::<Vec<_>>()
+            .join("; ");
+        SexprQueryError(msg)
+    })?;
+
+    let cap = limit.unwrap_or(usize::MAX);
+    let mut matches: Vec<&Artifact> = Vec::new();
+    let mut total = 0usize;
+    for a in store.iter() {
+        if !sexpr_eval::matches_filter_with_store(&expr, a, graph, store) {
+            continue;
+        }
+        total += 1;
+        if matches.len() < cap {
+            matches.push(a);
+        }
+    }
+
+    Ok(SexprQueryResult {
+        filter: filter.to_string(),
+        truncated: matches.len() < total,
+        matches,
+        total,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::model::Artifact;
+    use crate::schema::Schema;
+    use std::collections::BTreeMap;
+
+    fn plain(id: &str, typ: &str, status: Option<&str>, tags: &[&str]) -> Artifact {
+        Artifact {
+            id: id.into(),
+            artifact_type: typ.into(),
+            title: format!("Title of {id}"),
+            description: None,
+            status: status.map(|s| s.into()),
+            tags: tags.iter().map(|t| t.to_string()).collect(),
+            links: vec![],
+            fields: BTreeMap::new(),
+            provenance: None,
+            source_file: None,
+        }
+    }
+
+    fn build(artifacts: Vec<Artifact>) -> (Store, Schema, LinkGraph) {
+        let mut store = Store::new();
+        for a in artifacts {
+            store.upsert(a);
+        }
+        let schema = Schema::merge(&[]);
+        let graph = LinkGraph::build(&store, &schema);
+        (store, schema, graph)
+    }
+
+    #[test]
+    fn execute_sexpr_filters_by_type() {
+        let (store, _schema, graph) = build(vec![
+            plain("REQ-1", "requirement", Some("approved"), &[]),
+            plain("REQ-2", "requirement", Some("draft"), &[]),
+            plain("FEAT-1", "feature", Some("approved"), &[]),
+        ]);
+
+        let r = execute_sexpr(&store, &graph, r#"(= type "requirement")"#, None).unwrap();
+        let mut ids: Vec<&str> = r.matches.iter().map(|a| a.id.as_str()).collect();
+        ids.sort();
+        assert_eq!(ids, vec!["REQ-1", "REQ-2"]);
+        assert_eq!(r.total, 2);
+        assert!(!r.truncated);
+    }
+
+    #[test]
+    fn execute_sexpr_with_limit_reports_truncation() {
+        let artifacts: Vec<Artifact> = (0..10)
+            .map(|i| plain(&format!("REQ-{i:02}"), "requirement", None, &[]))
+            .collect();
+        let (store, _schema, graph) = build(artifacts);
+
+        let r = execute_sexpr(&store, &graph, r#"(= type "requirement")"#, Some(3)).unwrap();
+        assert_eq!(r.matches.len(), 3);
+        assert_eq!(r.total, 10);
+        assert!(r.truncated);
+    }
+
+    #[test]
+    fn execute_sexpr_empty_filter_matches_all() {
+        let (store, _schema, graph) = build(vec![
+            plain("A", "requirement", None, &[]),
+            plain("B", "feature", None, &[]),
+        ]);
+        let r = execute_sexpr(&store, &graph, "", None).unwrap();
+        assert_eq!(r.matches.len(), 2);
+        assert_eq!(r.total, 2);
+    }
+
+    #[test]
+    fn execute_sexpr_reports_parse_errors() {
+        let (store, _schema, graph) = build(vec![]);
+        let err = execute_sexpr(&store, &graph, "(and", None).unwrap_err();
+        assert!(err.to_string().contains("invalid filter"));
+    }
+
+    #[test]
+    fn execute_sexpr_tag_filter_matches_list_command_output() {
+        // Same filter that `rivet list --filter` would use — results must agree.
+        let (store, _schema, graph) = build(vec![
+            plain("REQ-1", "requirement", None, &["stpa", "safety"]),
+            plain("REQ-2", "requirement", None, &["other"]),
+        ]);
+        let r = execute_sexpr(&store, &graph, r#"(has-tag "stpa")"#, None).unwrap();
+        assert_eq!(r.matches.len(), 1);
+        assert_eq!(r.matches[0].id, "REQ-1");
+    }
+}