diff --git a/docs/query-surfaces.md b/docs/query-surfaces.md index ce67a3fe..66fd4015 100644 --- a/docs/query-surfaces.md +++ b/docs/query-surfaces.md @@ -9,8 +9,12 @@ health, across the CLI, the HTTP surface, and the public consumer Skill. JSON contract. Do not add interface-specific ranking, filtering, identity merging, or silent network fallback. - Query responses must state their local data provenance and retrieval mode. - Missing or malformed generated artifacts fail visibly with machine-readable - errors; they must not be replaced with guessed metadata. + `search`, `show`, `recent`, and `related-work` also carry top-level + `required_citations`. Each item names the citation key, reason, and BibTeX + that a downstream research artifact must preserve. Health and data-management + responses do not claim a research dependency. Missing or malformed generated + artifacts fail visibly with machine-readable errors; they must not be replaced + with guessed metadata. - Lexical search is a high-recall candidate retriever for agents, not a final suitability judge. Any shared query token may produce a candidate. BM25F is the primary retrieval score. Exact/prefix/token-sequence name matches and @@ -27,6 +31,18 @@ health, across the CLI, the HTTP surface, and the public consumer Skill. as adjacent character pairs, and accepts other Unicode letter words. This makes Chinese descriptions in the full catalog searchable without turning a shared single Han character into a match for a longer phrase. +- `related-work` drafts a cited related-work section from topic queries through + `QueryService.related_work`, over the same offline artifacts as `search` and + `show`. It keeps full lexical matches unless partial matches are requested, + admits only scholarly Radar sources, and cites every retained entry. Its final + paragraph states that the candidates were retrieved using Benchmark Radar and + tells the author to verify them against their primary sources. The exporter adds + the required in-text citation and the matching final BibTeX entry, then verifies + both before returning a payload or writing a file. A citation-incomplete artifact + fails with the machine-readable `citation_contract_failed` error. Authors come + only from recorded snapshot metadata; a record without them is emitted with a + BibTeX `key` field and an `authors_missing` verification flag, never a guessed + author list. Every payload carries a coverage statement naming the corpus window. - Catalog records and daily discovery observations describe different things. Label a discovery observation as evidence of a mention or release, and retain the benchmark record it refers to. Source membership must not establish a diff --git a/skills/benchmark-radar/SKILL.md b/skills/benchmark-radar/SKILL.md index 8827fe15..61ac2cf8 100644 --- a/skills/benchmark-radar/SKILL.md +++ b/skills/benchmark-radar/SKILL.md @@ -57,6 +57,8 @@ inspecting details with `show`, or tracking recent evidence). `benchmark-radar show "" --json` - Inspect the newest Radar evidence: `benchmark-radar recent --json` +- Draft a cited related-work section for a paper: + `benchmark-radar related-work "