@gmickel/gno 1.21.0 → 1.23.0

package/README.md

@@ -17,6 +17,17 @@
 
 GNO is a local knowledge engine for notes, code, PDFs, Office docs, meeting transcripts, and reference material. It gives you fast keyword search, semantic retrieval, grounded answers with citations, wiki-style linking, and a real workspace UI, while keeping the whole stack local by default.
 
+CLI retrieval also uses the current repository/workspace as a transparent soft
+ranking signal. A trusted local cwd or repeatable `--project-root` can add at
+most `+0.03` to matching collection results; `--no-project-affinity` disables
+it, and explicit roots replace cwd inference. It never overrides collection,
+tag, date, exclude, or egress filters. SDK, REST, and MCP `projectHints` are
+opaque, untrusted, limited to 16, and intentionally have zero ranking effect:
+those surfaces never probe caller or server filesystem paths. Trusted local
+diagnose output uses closed `schemaVersion: "1.1"` redacted affinity metadata;
+absent, disabled, and remote/untrusted diagnose requests preserve exact legacy
+v1.0 bytes and omit `affinity`.
+
 Use it when:
 
 - your notes live in more than one folder
@@ -94,12 +105,16 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.21.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.23.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **Project-aware retrieval affinity**: trusted local CLI searches can use the
+  current workspace or explicit `--project-root` values as a transparent,
+  explainable `+0.03` soft ranking signal. Filters remain hard, and untrusted
+  SDK, REST, MCP, and Web hints never probe paths or affect ranking.
 - **Retrieval-proven activation**: `gno status`, `gno doctor`, REST, and the
   Web/Desktop dashboard now share a per-folder lexical retrieval proof. Local
   semantic readiness remains independent, and installed MCP targets can run an
@@ -710,7 +725,7 @@ GNO is local-first, but sometimes you want a URL to send someone. [**gno.sh**](h
 
 ![gno.sh publish reader](./assets/screenshots/publish-reader.jpg)
 
-The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Your private notes and metadata stay on your machine. Only what you export leaves.
+The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Private and `publish: false` notes stay on your machine. Exported artifacts omit local collection paths and source URIs.
 
 ```bash
 # Export a single note
@@ -745,6 +760,15 @@ Upload the artifact at [gno.sh/studio](https://gno.sh/studio) and pick a visibil
 
 **Reader experience**: editorial serif typography, drop caps, hanging punctuation, table of contents, keyboard shortcuts (`j/k`, `/`), scoped Pagefind-style search, and backlinks restricted to the published subset. Nothing leaks that you didn't publish.
 
+Public exports also carry a deterministic agent manifest. It lists only the
+sanitized published Markdown projection, with relative Markdown locators,
+content hashes, exact line spans, and Capsule-compatible evidence identities.
+The projection revision is stable while those published bytes and reader
+metadata are unchanged. Secret-link and invite-only exports do not receive
+agent capabilities or manifests. Encrypted exports remain ciphertext-only.
+Reader metadata drops embedded local path or GNO/file URI tokens; canonical
+and image fields accept only uncredentialed public HTTP(S) targets.
+
 Republishing a public, secret-link, or invite-only artifact updates the same URL. Encrypted shares should be replaced from a fresh local export so the server never needs your plaintext.
 
 Encrypted source-backed publish on `gno.sh` is intentionally disabled. For encrypted shares, use:

package/assets/skill/SKILL.md

@@ -108,8 +108,23 @@ Recipe rules:
 --json                JSON output
 --files               URI list output
 --line-numbers        Include line numbers
+--project-root <path> Trusted local root; repeatable and replaces cwd affinity
+--no-project-affinity Disable trusted local project-aware ranking
 ```
 
+CLI searches use the current repository/worktree as a soft signal by default.
+A matching collection can receive at most `+0.03`; roots never stack, all
+auxiliary signals share `±0.08`, and collection/tag/date/exclude/egress filters
+stay hard. Use `--project-root` for explicit trusted roots or
+`--no-project-affinity` to disable it.
+
+Do not treat MCP/SDK/REST `projectHints` as paths. They are opaque, untrusted,
+limited to 16, never trigger filesystem probing, and currently produce zero
+affinity. Explain uses redacted aliases only. Diagnose preserves exact closed
+v1.0 bytes and omits `affinity` for absent, disabled, and remote/untrusted
+inputs; trusted local diagnose uses closed v1.1 redacted metadata, including an
+explicit unmatched state. The Web UI does not infer a browser project root.
+
 ## Advanced: Structured Query Modes (query/ask only)
 
 Use `--query-mode` to combine multiple retrieval strategies in one query (repeatable):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -83,6 +83,7 @@
     "eval:retrieval-candidates": "bun scripts/retrieval-candidate-benchmark.ts",
     "eval:retrieval-candidates:write": "bun scripts/retrieval-candidate-benchmark.ts --write",
     "eval:agentic": "bun evals/agentic/cli.ts",
+    "eval:agentic:demo": "bun evals/agentic/demos/generate-context-capsule.ts",
     "eval:watch": "bun --bun evalite watch",
     "research:finetune:bootstrap": "bun research/finetune/scripts/bootstrap-promotion-fixtures.ts",
     "research:finetune:autonomous:noop": "bun research/finetune/autonomous/scripts/noop-run.ts",

package/spec/cli.md

@@ -95,6 +95,7 @@ equivalent files fail closed as ambiguous.
 | models pull        | no     | no      | no    | no   | no    | terminal |
 | models clear       | no     | no      | no    | no   | no    | terminal |
 | models path        | yes    | no      | no    | no   | no    | terminal |
+| publish export     | yes    | no      | no    | no   | no    | terminal |
 | cleanup            | no     | no      | no    | no   | no    | terminal |
 | doctor             | yes    | no      | no    | yes  | no    | terminal |
 | mcp                | no     | no      | no    | no   | no    | stdio    |
@@ -748,22 +749,24 @@ gno search <query> [-n <num>] [--min-score <num>] [-c <collection>] [--since <da
 
 **Options:**
 
-| Option             | Type    | Default                   | Description                                                                                   |
-| ------------------ | ------- | ------------------------- | --------------------------------------------------------------------------------------------- |
-| `-n`               | integer | 5 (20 for --json/--files) | Max results                                                                                   |
-| `--min-score`      | number  | 0                         | Minimum score threshold                                                                       |
-| `-c, --collection` | string  | all                       | Filter to collection                                                                          |
-| `--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 queries; steers snippets without being searched directly |
-| `--exclude`        | string  | none                      | Hard-prune docs containing any comma-separated term in title/path/body                        |
-| `--tags-all`       | string  | none                      | Filter to docs with ALL tags (comma-separated)                                                |
-| `--tags-any`       | string  | none                      | Filter to docs with ANY tag (comma-separated)                                                 |
-| `--full`           | boolean | false                     | Include full mirror content instead of snippet                                                |
-| `--line-numbers`   | boolean | false                     | Include line numbers in output                                                                |
-| `--lang`           | string  | auto                      | Language filter/hint (BCP-47)                                                                 |
+| Option                  | Type     | Default                   | Description                                                                                   |
+| ----------------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------- |
+| `-n`                    | integer  | 5 (20 for --json/--files) | Max results                                                                                   |
+| `--min-score`           | number   | 0                         | Minimum score threshold                                                                       |
+| `-c, --collection`      | string   | all                       | Filter to collection                                                                          |
+| `--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 queries; steers snippets without being searched directly |
+| `--exclude`             | string   | none                      | Hard-prune docs containing any comma-separated term in title/path/body                        |
+| `--tags-all`            | string   | none                      | Filter to docs with ALL tags (comma-separated)                                                |
+| `--tags-any`            | string   | none                      | Filter to docs with ANY tag (comma-separated)                                                 |
+| `--project-root`        | string[] | cwd                       | Trusted project root; repeatable, replaces default cwd/repository affinity                    |
+| `--no-project-affinity` | boolean  | false                     | Disable project-aware soft ranking; invalid with `--project-root`                             |
+| `--full`                | boolean  | false                     | Include full mirror content instead of snippet                                                |
+| `--line-numbers`        | boolean  | false                     | Include line numbers in output                                                                |
+| `--lang`                | string   | auto                      | Language filter/hint (BCP-47)                                                                 |
 
 **Scoring:**
 
@@ -823,7 +826,8 @@ Vector semantic search over indexed documents.
 gno vsearch <query> [-n <num>] [--min-score <num>] [-c <collection>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--json|--files|--csv|--md|--xml]
 ```
 
-**Options:** Same as `gno search` (including temporal/category/author and tag filters)
+**Options:** Same as `gno search` (including temporal/category/author, tag, and
+project-affinity controls).
 
 **Scoring:**
 
@@ -869,6 +873,9 @@ gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <co
 | `--explain` | boolean | Print retrieval explanation to stderr |
 | `--target` | ref | Required for `query diagnose`; target document to diagnose |
 
+`query diagnose` accepts the same `--project-root` and
+`--no-project-affinity` controls as `query`.
+
 **Compatibility / Migration:**
 
 - Legacy query invocations remain valid (`gno query "<text>"`, `--fast`, `--thorough`, `--no-expand`, `--no-rerank`).
@@ -881,8 +888,12 @@ gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <co
 **Diagnose Output:**
 
 `gno query diagnose` wraps the shared `diagnoseQueryTarget()` core and emits
-`query-diagnose.schema.json` for `--json`. The payload requires
-`schemaVersion: "1.0"`, resolves the target first, reports `target.status`
+`query-diagnose.schema.json` for `--json`. No trusted affinity input preserves
+the exact closed `schemaVersion: "1.0"` payload and omits `affinity`; the legacy
+contract remains in `query-diagnose-v1.schema.json`. A resolved trusted CLI cwd
+or explicit project root emits `schemaVersion: "1.1"` and requires closed,
+redacted `affinity` metadata, including unmatched state. The payload resolves
+the target first, reports `target.status`
 (`not_found|inactive|no_indexed_content|filtered_out|diagnosed`), and only runs
 stage tracing for `diagnosed` targets. Stages report
 `present`, `rank`, `score`, `survived`, `dropReason`, `status`, and
@@ -991,6 +1002,8 @@ gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [
 | `--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)                                        |
+| `--project-root`          | string[] | cwd     | Trusted project root; repeatable, replaces default cwd/repository affinity         |
+| `--no-project-affinity`   | boolean  | false   | Disable project-aware soft ranking; invalid with `--project-root`                  |
 
 **Output (JSON):**
 See [Output Schemas](./output-schemas/ask.schema.json)
@@ -1314,7 +1327,7 @@ written to stderr.
 **Synopsis:**
 
 ```bash
-gno context build "<goal>" --budget <tokens> [--collection <name>] [--fast|--thorough] [--json|--md] [--output <file>]
+gno context build "<goal>" --budget <tokens> [--collection <name>] [--project-root <path>]... [--no-project-affinity] [--fast|--thorough] [--json|--md] [--output <file>]
 ```
 
 `--budget` is the global token ceiling. `--bytes` optionally sets a separate
@@ -1327,6 +1340,10 @@ repeatable. Tag filters are NFC-normalized, lowercased, deduplicated, and
 validated before retrieval. Result and candidate limits are global across
 repeated collections: the merged result pool is capped once, while candidate
 work is distributed deterministically in canonical collection order.
+Project affinity defaults to the trusted process cwd/repository. Repeatable
+`--project-root` values replace that default, are normalized/deduplicated, and
+are capped at 16. `--no-project-affinity` disables the soft signal and cannot
+be combined with explicit roots.
 
 JSON is the canonical V1 payload. Markdown is a readable projection of that
 same payload and hard-delimits each untrusted evidence passage. Passage,
@@ -1558,6 +1575,49 @@ gno models path [--json]
 
 ---
 
+### gno publish export
+
+Build a reader-safe gno.sh artifact from one active collection or document.
+
+**Synopsis:**
+
+```bash
+gno publish export <target> \
+  [--out <path>] \
+  [--visibility public|secret-link|invite-only|encrypted] \
+  [--passphrase <value>] \
+  [--slug <slug>] \
+  [--title <title>] \
+  [--summary <summary>] \
+  [--preview] \
+  [--json]
+```
+
+Public V1 spaces MUST carry a `manifest` conforming to
+[`publish-artifact.schema.json`](./output-schemas/publish-artifact.schema.json).
+The manifest contains schema version `1.0`, a deterministic projection
+revision, generated time, closed public capabilities, sorted published
+documents, relative Markdown locators, SHA-256 content hashes, and
+Capsule-compatible evidence identities. Manifest hashes and revisions MUST be
+derived only from sanitized notes and metadata present in the published
+projection. Local collection paths, document source URIs, unpublished
+documents, and filtered metadata MUST NOT enter artifact bytes or revision
+inputs. Reader metadata values containing embedded local path or GNO/file URI
+tokens MUST be filtered. Canonical and image metadata MUST contain
+uncredentialed public HTTP(S) targets; local hostnames and literal loopback,
+private, or link-local addresses MUST be filtered.
+
+Secret-link and invite-only V1 spaces MUST NOT contain a manifest or agent
+capability field. Encrypted V2 spaces MUST contain only ciphertext parameters,
+the opaque secret token, route slug, source type, and encrypted visibility; no
+plaintext manifest or evidence may appear outside the ciphertext. V2 builders
+MUST emit a closed projection, validate payload strings as non-empty bounded
+base64, require a positive safe-integer KDF iteration count, and bound the
+non-blank opaque token. Caller-supplied extension fields MUST NOT enter the
+artifact.
+
+---
+
 ### gno cleanup
 
 Remove orphaned content, chunks, and vectors not referenced by active documents.

package/spec/evals-agentic.md

@@ -22,8 +22,13 @@ evals/agentic/
   fixture-db.ts
   scoring.ts
   promotion.ts
+  project-affinity-contract.ts
+  project-affinity-outcome.ts
+  project-affinity-promotion.ts
+  project-affinity-runtime.ts
   verified-ask-outcome.ts
   verified-ask-promotion.ts
+  demos/context-capsule.ts
   registry.ts
   report.ts
   report-artifacts.ts
@@ -44,6 +49,7 @@ evals/agentic/
     final-envelope.schema.json
     trajectory-receipt.schema.json
     benchmark-report.schema.json
+    context-capsule-demo.schema.json
 
 evals/fixtures/agentic-retrieval/
   manifest.json
@@ -61,8 +67,42 @@ evals/fixtures/agentic-retrieval/
       verified-ask-promotion.json
       verified-ask-promotion.md
     optional/{qmd,local-model}/     # local opt-in evidence; not authoritative
+  demos/
+    context-capsule.json
+    context-capsule.md
 ```
 
+## Separate project-affinity promotion
+
+`project-affinity-cases.json` defines two controlled vector-distance pairs over
+the existing `t456ef70` (`c015`/`c115`) and `t567f081`
+(`c016`/`c116`) task/corpus/oracle identities. The separate closed
+`project-affinity-promotion@1.0` artifact hash-binds those manifest identities;
+it does not add tasks to the authoritative 24-task, 144-receipt matrix or
+change `BenchmarkReport@1`.
+
+The target collection starts `0.02` behind, then receives one trusted local
+`+0.03` contribution. Promotion requires correct top-1 to strictly improve to
+`2/2`, exact required evidence to remain retained, zero URI-rank/required
+evidence-coverage loss across all 24 hard-collection tasks, and zero loss for
+`t012ab3c`, `t123bc4d`, `te8f901a`, and `tf901a2b`. It also gates hard-filter
+isolation, absent/disabled/unavailable/untrusted exact zero lanes, shared
+auxiliary cap receipts, and structural store-call/candidate bounds. Structural
+receipts record the complete closed StorePort method map, reject unexpected
+methods, enforce per-method maxima, require candidate requests and returns to
+stay within `3×` the output limit, and require returned candidates not to exceed
+requested candidates. Latency is not a gate.
+
+The committed artifacts are
+`baseline/fixture-agent/project-affinity-promotion.json` and `.md`. They contain
+only GNO evidence URIs, hashes, scores, raw filter/regression/zero/auxiliary/
+structural receipts, implementation provenance, and redacted aliases—never
+temporary roots, raw project hints, or absolute paths. An independent validator
+rebinds fixture identities, recomputes summaries/gates/fingerprint from those
+receipts, and compares the committed artifact with a fresh deterministic
+production run. The controlled synthetic lane isolates the score seam and makes
+no general workload superiority claim.
+
 The first fixture version contains 24 original synthetic tasks and 34 Markdown
 documents under the MIT license. It covers exact identifiers, ambiguity,
 multi-document comparisons, meeting decisions, temporal questions, typed
@@ -412,6 +452,48 @@ 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`.
 
+## Reproducible Context Capsule demo
+
+`demos/context-capsule.json` is a closed, canonically fingerprinted projection
+of one frozen exact-identifier task from the authoritative fixture-agent
+report. It contains exactly three lanes in fixed order: the lexical-only
+no-GNO baseline, shipped GNO MCP query/get primitives, and the Context Capsule.
+Every lane retains its complete normalized trajectory receipt, score, exact
+evidence coordinates and hashes, final stop outcome, agent/backend call counts,
+model-visible UTF-8 bytes, token availability, and matching-lifecycle latency.
+
+All three lanes must share the task, outer agent, trial, seed, lifecycle,
+corpus, prompt, tool, model, runtime, and canonical effective-index
+fingerprints. The generator selects exactly one receipt and score per full
+identity and rejects ambiguous multi-trial input. Adapter configuration
+fingerprints may differ. The Capsule projection additionally retains its
+normalized `retrieval.request`, effective index fingerprint, capability states,
+fallback list, and complete model-visible payload. Validation parses the
+delivered evidence bundle and compares those values, then recomputes every
+displayed lane metric from the embedded receipt and score.
+
+Source provenance distinguishes each source run's clean `runGitCommit` from
+the later Git commit that contains the generated demo artifact. The artifact
+does not attempt to embed its own containing commit. Its report and Verified
+Ask fingerprints and projected fields must match the canonical linked source
+artifacts.
+
+The readable `context-capsule.md` is generated from the JSON contract. It
+states the single-trial variance limitation, reports tokens as unavailable
+without one pinned comparable tokenizer, and limits its claim to the measured
+controlled task. It discloses that the chosen task is the sole cold
+current-GNO-failure / Capsule-success case in the 24-task authoritative cohort,
+that the Capsule lane is an evaluation-only lexical prototype, and that its
+latency is not shipped-product latency. It cannot be used as a general
+product-superiority claim.
+
+The adjacent Verified Ask block is an attributable but separate
+`answer_enforcement` proof. It binds the clean-Git canonical fingerprint of the
+frozen 22-pair `raw_ask`/`verified_ask` artifact, retains the two declared
+missing-evidence exclusions, and exposes only answer-accuracy and unsupported-
+substantive-claim metrics. Those metrics are never merged into or labeled as
+retrieval metrics.
+
 ## Deterministic scoring
 
 The scorer compares typed claims and exact citations with the hidden oracle. It
@@ -551,6 +633,7 @@ Contract tests are ordinary offline tests:
 
 ```bash
 bun test test/eval/agentic
+bun run eval:agentic:demo
 ```
 
 The runner is local and opt-in:

package/spec/evals.md

@@ -27,6 +27,12 @@ Agent-level evidence sufficiency, exact citation coverage, stopping behavior,
 and Context Capsule promotion use the separate deterministic
 [Agentic Retrieval Evaluation Contract](evals-agentic.md).
 
+That contract also owns a separate closed project-affinity promotion artifact.
+It reuses the immutable 24-task fixture identities while leaving the main task
+inventory and report schema unchanged. The gate records measured top-1,
+evidence, multilingual, hard-filter, zero-lane, score-cap, and structural-call
+outcomes; it does not use a wall-clock threshold.
+
 ## Dependencies
 
 ```json

package/spec/mcp.md

@@ -218,6 +218,10 @@ Optional fields are `collection`, `limit` (default 5), `minScore`, `lang`,
 `since`, `until`, `categories`, `author`, `graph`, `noGraph`, `noRerank`,
 `maxAnswerTokens`, `contextBudgetTokens`, and `contextBudgetBytes`. Input
 objects are closed.
+`projectHints` is an optional array of at most 16 non-empty caller hints. Hints
+are normalized and deduplicated as opaque values, never resolved against or
+reflected from the MCP server filesystem, and therefore have zero ranking
+effect on the remote channel.
 
 `structuredContent` uses the
 [`ask`](./output-schemas/ask.schema.json) contract. Its `verification` object
@@ -273,6 +277,9 @@ validated before retrieval. `limit` and `candidateLimit` are global across all
 requested collections: result admission is capped after merging, and
 rerank/graph candidate work is distributed deterministically in canonical
 collection order.
+`projectHints` is also accepted as an optional array of at most 16 opaque
+caller hints. It follows the same remote zero-affinity, non-probing, and
+non-reflection contract as all MCP retrieval tools.
 
 `structuredContent` is the complete canonical Context Capsule object for
 application clients. Model-visible text is always one deterministic
@@ -338,6 +345,13 @@ evidence reads. `structuredContent` is the canonical verification receipt.
 
 BM25 keyword search over indexed documents.
 
+All retrieval input schemas (`gno_search`, `gno_vsearch`, `gno_query`, and
+`gno_query_diagnose`) additionally accept optional `projectHints: string[]`
+(maximum 16). Values are trimmed, NFC-normalized, deduplicated, and treated as
+opaque remote hints. The server never stats, realpaths, discovers repositories,
+or infers its cwd from them; remote hints produce redacted zero-affinity
+metadata and no ranking change.
+
 **Input Schema:**
 
 ```json
@@ -745,6 +759,10 @@ Structured content includes `schemaVersion`, normalized `query`, `target`
 metadata/status (`not_found`, `inactive`, `no_indexed_content`,
 `filtered_out`, or `diagnosed`), `stages` for BM25/vector/fusion/graph/rerank,
 the selected target `chunk`, and retrieval `meta`.
+MCP inputs are remote and untrusted, so this tool preserves exact v1.0 bytes
+and omits `affinity`, even when `projectHints` are supplied. The shared current
+validation schema is `gno://schemas/query-diagnose@1.1`; its affinity-bearing
+v1.1 branch is reserved for trusted local CLI diagnose requests.
 
 Use when an expected target is missing from `gno_query`, when filters may have
 excluded it, or when an agent needs evidence before raising `candidateLimit`,