@gmickel/gno 1.19.0 → 1.20.0

package/README.md

@@ -94,7 +94,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.18.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.19.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -553,9 +553,9 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 21 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 22 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
-adds 15 opt-in mutation tools, for 36 total.
+adds 15 opt-in mutation tools, for 37 total.
 
 | Tool                 | Description                           |
 | :------------------- | :------------------------------------ |
@@ -564,6 +564,7 @@ adds 15 opt-in mutation tools, for 36 total.
 | `gno_query`          | Hybrid search (recommended)           |
 | `gno_context`        | Budgeted exact evidence Capsule       |
 | `gno_context_verify` | Verify saved Capsule provenance       |
+| `gno_ask`            | Opt-in closed-Capsule verified answer |
 | `gno_get`            | Retrieve document by ID               |
 | `gno_multi_get`      | Batch document retrieval              |
 | `gno_links`          | Get outgoing links from document      |
@@ -574,9 +575,13 @@ adds 15 opt-in mutation tools, for 36 total.
 | `gno_trace_list`     | List private local retrieval receipts |
 | `gno_trace_show`     | Inspect one bounded trace receipt     |
 
-**Design**: Default MCP mode is read-only: retrieval, graph, status, and job
-inspection. Your AI assistant synthesizes answers from retrieved context. Write
-tools are available only through the explicit `--enable-write` opt-in.
+**Design**: Default MCP mode is read-only: retrieval, opt-in verified synthesis,
+graph, status, and job inspection. Raw retrieval tools leave synthesis to your
+AI assistant. `gno_ask` runs only when the caller sends literal `verify: true`;
+it verifies claims against one closed Capsule and abstains unless every
+substantive claim is supported. That classification is not a general factual
+guarantee beyond the retained evidence. Write tools remain available only
+through the explicit `--enable-write` opt-in.
 
 `gno serve` and `gno daemon` also expose this surface as stateful Streamable
 HTTP at `http://127.0.0.1:3000/mcp`. HTTP stays read-only by default.
@@ -845,7 +850,7 @@ graph TD
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                          |
 | **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation    |
 | **Privacy First**    | Local by default; no telemetry; network use is explicit or model provisioning  |
-| **MCP Server**       | 10 automatic client targets; 19 read-only tools, 30 with writes enabled        |
+| **MCP Server**       | 10 automatic client targets; 22 read-only tools, 37 with writes enabled        |
 | **Collections**      | Organize sources with patterns, excludes, contexts                             |
 | **Tag Filtering**    | Frontmatter tags with hierarchical paths, filter via `--tags-any`/`--tags-all` |
 | **Note Linking**     | Wiki links, backlinks, related notes, cross-collection navigation              |

package/assets/skill/SKILL.md

@@ -81,14 +81,15 @@ Recipe rules:
 
 ## Search Modes
 
-| Command                | Speed   | Best For                           |
-| ---------------------- | ------- | ---------------------------------- |
-| `gno search`           | instant | Exact keyword matching             |
-| `gno vsearch`          | ~0.5s   | Finding similar concepts           |
-| `gno query --fast`     | ~0.7s   | Quick lookups                      |
-| `gno query`            | ~2-3s   | Balanced (default)                 |
-| `gno query --thorough` | ~5-8s   | Best recall, complex queries       |
-| `gno ask --answer`     | ~3-5s   | AI-generated answer with citations |
+| Command                | Speed   | Best For                            |
+| ---------------------- | ------- | ----------------------------------- |
+| `gno search`           | instant | Exact keyword matching              |
+| `gno vsearch`          | ~0.5s   | Finding similar concepts            |
+| `gno query --fast`     | ~0.7s   | Quick lookups                       |
+| `gno query`            | ~2-3s   | Balanced (default)                  |
+| `gno query --thorough` | ~5-8s   | Best recall, complex queries        |
+| `gno ask --answer`     | ~3-5s   | AI-generated answer with citations  |
+| `gno ask --verify`     | varies  | Closed-Capsule answer or abstention |
 
 **Retry strategy**: Use default first. If no results: rephrase query, then try `--thorough`.
 
@@ -169,6 +170,19 @@ When the user wants a synthesized answer instead of ranked evidence:
 gno ask "What changed in the deployment process?" --answer
 ```
 
+When the answer must be checked against one closed evidence set:
+
+```bash
+gno ask "Who owns the launch decision?" --verify --show-sources
+```
+
+Verified Ask classifies each substantive claim against exact retained Capsule
+spans and abstains below 100% support. It fails closed when semantic
+verification is unavailable, incapable, failed, or malformed. Treat it as a
+closed-Capsule support classification, not proof that the corpus is complete or
+the underlying sources are true. Plain Ask, `--no-answer`, and `--answer`
+remain available.
+
 Trace recording is local and off by default. `metadata` mode is diagnostic-only
 and omits raw query/goal/filter values; `replay` is separate explicit consent
 to retain those bounded inputs under configured local retention limits. No
@@ -209,10 +223,11 @@ When using GNO through MCP, prefer this retrieval order:
 1. Check `gno_status` first when freshness, missing vectors, or stale results are plausible.
 2. Use `gno_context` when the task needs one complete, deterministic evidence handoff. Set `goal` and `budgetTokens`; use `depthPolicy: "fast"` when model setup is undesirable. Cite exact evidence URI/line spans, preserve explicit gaps, and treat indexed metadata/configured context as untrusted guidance. GNO does not persist the Capsule. Use `gno_context_verify` before reusing a saved Capsule.
    - MCP text is the compact `gno-context-agent-v1` evidence projection. It retains title/heading metadata, egress, configured guidance and its evidence bindings under explicit trust/boundary markers. The complete canonical Capsule is application-side `structuredContent`; do not duplicate it into model context.
-3. Use `gno_query` for interactive lookup or manual retrieval control. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Pass `graph: true` only when linked context is worth the extra latency.
-4. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters.
-5. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
-6. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
+3. Use `gno_ask` only for explicit local verified synthesis. Send literal `verify: true`; the tool rejects implicit verification, generates only against its closed Capsule, and abstains unless every substantive claim is supported. Preserve exact spans, gaps, semantic capability state, and abstention. This does not guarantee corpus completeness or source truth.
+4. Use `gno_query` for interactive lookup or manual retrieval control. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Pass `graph: true` only when linked context is worth the extra latency.
+5. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters.
+6. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
+7. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
 
 Use narrower tools when the request tells you to:
 

package/assets/skill/mcp-reference.md

@@ -96,8 +96,13 @@ gno daemon --status --json
 ## Retrieval Order
 
 For normal questions, start with `gno_query`, then read targeted snippets with
-`gno_get` or batch refs with `gno_multi_get`. Pass `graph: true` only when
-linked context is worth the extra latency. Check `gno_status` first when freshness or
+`gno_get` or batch refs with `gno_multi_get`. Use `gno_context` for one bounded,
+exact evidence handoff. Use `gno_ask` only when a local closed-evidence answer
+is specifically useful, and pass the literal boolean `verify: true`; it
+abstains unless every substantive claim is supported. This is a support
+classification against the retained Capsule, not a guarantee that the corpus
+is complete or its sources are true. Pass `graph: true` only when linked context
+is worth the extra latency. Check `gno_status` first when freshness or
 embeddings may be stale. Use `gno_query_diagnose` when a known target document
 should have appeared but did not.
 

package/assets/skill/recipes/citation-and-provenance.md

@@ -10,30 +10,46 @@ Use this recipe when accuracy, traceability, or auditability matters.
 
 ## Workflow
 
-1. Search for evidence, then retrieve exact passages.
+1. Choose the verification contract.
+
+For an explicit local answer checked against one closed evidence set:
+
+```bash
+gno ask "<question>" --verify --show-sources
+```
+
+Through MCP, call `gno_ask` with the literal boolean `verify: true`. The tool
+rejects implicit verification. It returns a closed Capsule, freshness receipt,
+four-state claim verdicts, exact evidence IDs/line spans, gaps, semantic
+capability state, and explicit abstention.
+
+Use the manual path below when the client should synthesize itself, when you
+need retrieval control, or when no generation model is available.
+
+2. Search for evidence, then retrieve exact passages.
 
 ```bash
 gno query "<claim>" --json
 gno get <uri> --from <line> -l <count> --line-numbers
 ```
 
-2. Prefer direct evidence over inference. Use graph/link expansion only to find supporting context, not to replace primary evidence.
+3. Prefer direct evidence over inference. Use graph/link expansion only to find supporting context, not to replace primary evidence.
 
 ```bash
 gno backlinks <uri>
 gno graph --from <uri-a> --to <uri-b>
 ```
 
-3. Label claim status:
+4. Label claim status:
 
-- confirmed by local evidence
-- partially supported
-- contradicted
-- not found locally
+- supported by exact local evidence
+- contradicted by exact local evidence
+- insufficient local evidence
+- uncertain because verification could not resolve the claim
 
-4. When writing a new note, include source kind, source URL/path, author/person if known, and capture date.
+5. When writing a new note, include source kind, source URL/path, author/person if known, and capture date.
 
-5. Verify post-write retrieval when the citation note should be searchable.
+6. Verify post-write retrieval when the citation note should be searchable.
 
 ```bash
 gno index
@@ -46,6 +62,13 @@ gno search "<citation note title>"
 - Do not collapse multiple sources into one citation.
 - Do not hide uncertainty behind confident synthesis.
 - Do not invent line ranges, URLs, IDs, or source dates.
+- Treat verified Ask as support classification against its retained Capsule,
+  not a general factual guarantee. It cannot prove corpus completeness or
+  source truth.
+- If the semantic verifier is unavailable, incapable, failed, or malformed,
+  preserve `uncertain` and abstention; never upgrade a claim from guesswork.
+- Contradiction requires conflicting evidence. Missing evidence is
+  `insufficient`, not contradicted.
 
 ## Done
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -961,27 +961,32 @@ Human-friendly query with citations-first output and optional grounded answer.
 **Synopsis:**
 
 ```bash
-gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--query-mode <mode:text>]... [-C <num>] [--answer] [--no-answer] [--max-answer-tokens <n>] [--no-expand] [--no-rerank] [--show-sources] [--json|--md]
+gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--query-mode <mode:text>]... [-C <num>] [--answer|--verify] [--no-answer] [--max-answer-tokens <n>] [--context-budget-tokens <n>] [--context-budget-bytes <n>] [--min-score <score>] [--graph] [--no-expand] [--no-rerank] [--show-sources] [--json|--md]
 ```
 
 **Options:**
 
-| Option                  | Type     | Default | Description                                                                        |
-| ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
-| `--answer`              | boolean  | false   | Generate short grounded answer                                                     |
-| `--no-answer`           | boolean  | false   | Force retrieval-only output                                                        |
-| `--max-answer-tokens`   | integer  | config  | Cap answer generation tokens                                                       |
-| `--since`               | string   | none    | Modified-at lower bound (ISO date/time or relative token)                          |
-| `--until`               | string   | none    | Modified-at upper bound (ISO date/time or relative token)                          |
-| `--category`            | string   | none    | Filter to docs with matching category/content type (comma-separated)               |
-| `--author`              | string   | none    | Filter to docs where author contains value (case-insensitive)                      |
-| `--intent`              | string   | none    | Disambiguating context for ambiguous questions without searching on that text      |
-| `--exclude`             | string   | none    | Hard-prune docs containing any comma-separated term in title/path/body             |
-| `--query-mode`          | string[] | none    | Structured mode entry (`term:<text>`, `intent:<text>`, `hyde:<text>`). Repeatable. |
-| `-C, --candidate-limit` | integer  | 20      | Max candidates passed to reranking                                                 |
-| `--no-expand`           | boolean  | false   | Disable query expansion                                                            |
-| `--no-rerank`           | boolean  | false   | Disable cross-encoder reranking                                                    |
-| `--show-sources`        | boolean  | false   | Show all retrieved sources (not just cited)                                        |
+| Option                    | Type     | Default | Description                                                                        |
+| ------------------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
+| `--answer`                | boolean  | false   | Generate short grounded answer                                                     |
+| `--verify`                | boolean  | false   | Generate from a closed Context Capsule; verify every claim or abstain              |
+| `--no-answer`             | boolean  | false   | Force retrieval-only output                                                        |
+| `--max-answer-tokens`     | integer  | config  | Cap answer generation tokens                                                       |
+| `--context-budget-tokens` | integer  | 12000   | Global token budget for verified Context evidence                                  |
+| `--context-budget-bytes`  | integer  | none    | Optional global byte budget for verified Context evidence                          |
+| `--min-score`             | number   | none    | Minimum retrieval score from 0 through 1                                           |
+| `--graph`                 | boolean  | false   | Include bounded graph expansion in verified Context retrieval                      |
+| `--since`                 | string   | none    | Modified-at lower bound (ISO date/time or relative token)                          |
+| `--until`                 | string   | none    | Modified-at upper bound (ISO date/time or relative token)                          |
+| `--category`              | string   | none    | Filter to docs with matching category/content type (comma-separated)               |
+| `--author`                | string   | none    | Filter to docs where author contains value (case-insensitive)                      |
+| `--intent`                | string   | none    | Disambiguating context for ambiguous questions without searching on that text      |
+| `--exclude`               | string   | none    | Hard-prune docs containing any comma-separated term in title/path/body             |
+| `--query-mode`            | string[] | none    | Structured mode entry (`term:<text>`, `intent:<text>`, `hyde:<text>`). Repeatable. |
+| `-C, --candidate-limit`   | integer  | 20      | Max candidates passed to reranking                                                 |
+| `--no-expand`             | boolean  | false   | Disable query expansion                                                            |
+| `--no-rerank`             | boolean  | false   | Disable cross-encoder reranking                                                    |
+| `--show-sources`          | boolean  | false   | Show all retrieved sources (not just cited)                                        |
 
 **Output (JSON):**
 See [Output Schemas](./output-schemas/ask.schema.json)
@@ -989,6 +994,25 @@ See [Output Schemas](./output-schemas/ask.schema.json)
 Notes:
 
 - `meta.answerContext` is optional explain payload for answer source selection.
+- `--verify` implies answer generation and cannot be combined with
+  `--no-answer`. The JSON result adds the closed Capsule, freshness receipt,
+  four-state per-claim verdicts (`supported`, `contradicted`, `insufficient`,
+  `uncertain`), exact evidence IDs and line spans, coverage, gaps, semantic
+  verifier state, and explicit abstention. Support below 100% never returns the
+  draft answer.
+- Terminal and Markdown verified output preserve the same verdicts, exact
+  support/conflict spans, coverage, gaps, abstention, and capability
+  degradation. With `--show-sources`, both formats list every retained Capsule
+  evidence span with its exact URI and line range. JSON remains the canonical
+  machine contract.
+- Verification classifies support only against the closed Capsule and its
+  freshness receipt. It does not guarantee corpus completeness or source truth.
+  An unavailable, incapable, failed, or malformed semantic verifier cannot mark
+  claims supported; unresolved substantive claims remain uncertain and force
+  abstention.
+- Verified retrieval records the normalized request and requested/attempted
+  capability states in its Capsule. The active `--index` value is host-owned
+  and used for both compilation and freshness verification.
 - Strategy: adaptive coverage (relevance + query/facet coverage), not fixed top-N.
 - Each result preserves optional configured `context`. Answer generation places
   that trusted configuration in a separate prompt role from untrusted retrieved
@@ -1005,6 +1029,7 @@ Notes:
 ```bash
 gno ask "how do we deploy to staging"
 gno ask "termination clause" --collection work --answer
+gno ask "who owns launch?" --verify --show-sources
 ```
 
 ---

package/spec/evals-agentic.md

@@ -22,6 +22,8 @@ evals/agentic/
   fixture-db.ts
   scoring.ts
   promotion.ts
+  verified-ask-outcome.ts
+  verified-ask-promotion.ts
   registry.ts
   report.ts
   report-artifacts.ts
@@ -51,7 +53,13 @@ evals/fixtures/agentic-retrieval/
   agent-model.lock.json
   baseline/
     README.md
-    fixture-agent/{report.json,canonical.json,observations.json,report.md}
+    fixture-agent/
+      report.json
+      canonical.json
+      observations.json
+      report.md
+      verified-ask-promotion.json
+      verified-ask-promotion.md
     optional/{qmd,local-model}/     # local opt-in evidence; not authoritative
 ```
 
@@ -400,7 +408,9 @@ and hashes, and promotion results remain included. `report.json` is schema
 valid. `canonical.json` contains that exact projection. `observations.json`
 holds environment, build observations, and full-identity receipt observations;
 committed temporary paths are projected to `<temp>`. `report.md` is the readable
-summary. The four files are staged and directory-renamed as one baseline set.
+summary. The six files are staged and directory-renamed as one baseline set.
+The verified Ask files are a separate attributable outcome lane; they do not
+rename the Capsule retrieval promotion in `report.json`.
 
 ## Deterministic scoring
 
@@ -455,6 +465,19 @@ Claim linkage is:
 linkedSupportedClaims_capsule / substantiveClaims_capsule >= 0.95
 ```
 
+Unsupported substantive claims must strictly decrease on a comparable paired
+cohort:
+
+```text
+unsupportedClaims_capsule < unsupportedClaims_gno
+1 - unsupportedClaims_capsule / unsupportedClaims_gno
+```
+
+The report records both counts and the reduction. A missing paired baseline,
+an identity mismatch, or a zero unsupported-claim baseline makes this reduction
+unavailable/non-comparable; GNO reports that state rather than fabricating an
+improvement.
+
 All denominators must be non-zero. Abstention-only tasks use their completion
 predicate and do not fabricate substantive claims. Every fixture-agent Capsule
 task must also emit byte-identical canonical Capsule payload JSON and matching
@@ -464,6 +487,64 @@ duplicates, identity mismatches,
 pairwise or aggregate accuracy loss, denominator failure, threshold miss, or
 nondeterminism fails promotion.
 
+## Verified Ask promotion formulas
+
+The authoritative fixture-agent write additionally runs a separate 22-task
+outcome lane. It excludes only the two declared expected-missing/abstention
+tasks. Every included task must contain exactly one required substantive claim;
+missing, duplicate, extra, or mismatched pairs fail closed.
+
+The compatible cohort is an independent frozen contract, not inferred from the
+artifact under validation:
+
+```text
+t012ab3c t0a1b2c3 t123bc4d t1b2c3d4 t2c3d4e5 t3d4e5f6
+t456ef70 t4e5f607 t567f081 t5f60718 t6071829 t6780192
+t718293a t7891a03 t8293a4b t93a4b5c ta4b5c6d tb5c6d7e
+tc6d7e8f td7e8f90 te8f901a tf901a2b
+```
+
+The exact exclusions are `t234cd5e` and `t345de6f`, both with reason
+`expected_missing_evidence`. Removing or replacing a complete receipt/score
+pair and resealing every derived fingerprint still fails validation.
+
+The baseline executes the production raw Ask path:
+`searchHybrid` → `generateGroundedAnswer` → `processAnswerResult`. The candidate
+executes production `buildVerifiedAsk`. Each pair shares the immutable native
+index, task goal, collection, structured search modes, deterministic answer
+agent/model fingerprint, and initial answer draft. Receipt and score identities
+bind task, lane, trial, seed, and agent. Pairing also requires identical fixture,
+index, request, and model fingerprints.
+
+Four fixed, diverse tasks receive an unsupported deterministic draft in both
+lanes. The other 18 receive the oracle-supported draft. This controlled
+adversarial subset tests enforcement at the product boundary; it does not claim
+general model quality.
+
+For every pair and in aggregate:
+
+```text
+answerAccuracy_verified(p) >= answerAccuracy_raw(p)
+mean(answerAccuracy_verified) >= mean(answerAccuracy_raw)
+unsupportedSubstantiveClaims_verified < unsupportedSubstantiveClaims_raw
+```
+
+`verified-ask-promotion.json` contains canonical receipts, identity-bearing
+scores, exact cohort/exclusions, metrics, and the gate result.
+`verified-ask-promotion.md` is its readable projection. Temporary collection
+paths and timings are excluded from the canonical contract; fixture, index,
+request, model, exact answer, citation hashes, verification status, and scored
+outcome remain bound. The evaluator parses the typed claim from the exact final
+product answer and scores it against the independent fn-97 oracle; it
+recomputes receipt, answer, score, and artifact fingerprints rather than
+trusting harness-assigned claim or score fields. Raw and verified lane semantics
+are validated independently. A supported final answer is exactly one encoded
+typed claim followed by its lane citation (`[1].` or one
+`[evidence:<sha256>].`); prefixes, extra claims, and trailing prose are invalid.
+An abstention must equal the production abstention text and contain no
+citations. Authoritative generation refuses a dirty Git checkout and records
+the exact clean source commit.
+
 ## Commands
 
 Contract tests are ordinary offline tests:
@@ -486,9 +567,10 @@ lifecycles, and the fixture agent. qmd is lazily registered and never runs by
 default. A requested unavailable qmd lane produces the complete requested
 harness-error matrix/report and exits `2`; it never disappears or downgrades.
 
-Exit `0` means a complete run and, when applicable, passing promotion. Exit `1`
-means the complete Capsule promotion gate failed. Exit `2` means invalid CLI,
-preflight, harness, or requested-adapter failure. `--write` accepts only a full
+Exit `0` means a complete run and, when applicable, both promotions pass. Exit
+`1` means the complete Capsule or verified Ask promotion gate failed. Exit `2`
+means invalid CLI, preflight, harness, or requested-adapter failure. `--write`
+accepts only a full
 24-task/two-lifecycle lane: the fixture-agent three-adapter lane writes the
 authoritative baseline, while qmd and the three-trial cached-local-model lane
 write only under `baseline/optional/`. Filtered or mixed writes are refused and

package/spec/mcp.md

@@ -151,7 +151,8 @@ Collection names are case-insensitive on input and normalized to lowercase in re
 ### Private retrieval metadata
 
 When local tracing is enabled, successful `gno_search`, `gno_vsearch`,
-`gno_query`, `gno_get`, and `gno_context` results include non-model-visible
+`gno_query`, `gno_get`, `gno_context`, and `gno_ask` results include
+non-model-visible
 top-level response metadata:
 
 ```json
@@ -196,6 +197,54 @@ content or a filesystem path. Aggregate exports reject open/missing traces and
 preserve each stored terminal state without treating partial, failed, or
 cancelled as negative feedback.
 
+### gno_ask
+
+Generate and verify one answer against a closed Context Capsule. This is a
+separate read-only tool; raw retrieval remains on `gno_query`, and trace
+mutation authority is not widened.
+
+Required input:
+
+```json
+{
+  "query": "Who owns the launch decision?",
+  "verify": true
+}
+```
+
+`verify` must be the literal `true`; implicit or raw Ask requests are rejected.
+Optional fields are `collection`, `limit` (default 5), `minScore`, `lang`,
+`intent`, `candidateLimit`, `exclude`, `queryModes`, `tagsAll`, `tagsAny`,
+`since`, `until`, `categories`, `author`, `graph`, `noGraph`, `noRerank`,
+`maxAnswerTokens`, `contextBudgetTokens`, and `contextBudgetBytes`. Input
+objects are closed.
+
+`structuredContent` uses the
+[`ask`](./output-schemas/ask.schema.json) contract. Its `verification` object
+contains the canonical Capsule, freshness receipt, four-state per-claim
+verdicts, exact support/conflict evidence IDs and line spans, coverage, gaps,
+semantic verifier capability, and explicit abstention. Every substantive claim
+must be supported; otherwise the draft is withheld and `answerStatus` is
+`abstained`. Contradiction is never inferred from missing evidence.
+
+Model-visible text renders the same answer status, coverage, semantic state,
+per-claim verdicts, exact `gno://` line spans, evidence IDs, gaps, and cited
+sources. Capability degradation comes from the Capsule's
+requested/attempted/outcome states.
+
+Verification is a closed-Capsule support classification, not a factual
+guarantee. It does not assert that the indexed corpus is complete or that source
+statements are true. Unavailable, incapable, failed, or malformed semantic
+verification cannot produce support; unresolved substantive claims remain
+uncertain and force abstention.
+
+The server-owned effective index is used for both Capsule compilation and
+freshness verification. One Ask-owned trace covers retrieval, Context,
+generation, verification, and exact retained citations. The trace ID remains
+transport-only in `_meta`; no dead ID is emitted after retention eviction.
+Support/conflict spans are inspectable and explicitly labelable, but they do
+not create implicit relevance judgments.
+
 ### gno_context
 
 Compile a deterministic, extractive Context Capsule. The active MCP server
@@ -213,8 +262,9 @@ Required input:
 ```
 
 Optional input fields are `query`, `collections`, `uriPrefix`, `queryModes`,
-`tagsAll`, `tagsAny`, `categories`, `author`, `lang`, `since`, `until`, `graph`,
-`limit`, `candidateLimit`, `budgetBytes`, `safetyMarginTokens`,
+`tagsAll`, `tagsAny`, `categories`, `author`, `lang`, `intent`, `exclude`,
+`minScore`, `since`, `until`, `graph`, `noRerank`, `limit`, `candidateLimit`,
+`budgetBytes`, `safetyMarginTokens`,
 `safetyMarginBytes`, `depthPolicy` (`fast`, `balanced`, or `thorough`), and
 `format` (`json` or `md`). Input objects are closed: unknown fields return
 `invalid_input`. Unknown collections return `invalid_filter` before model or