@gmickel/gno 1.22.0 → 1.24.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
@@ -39,8 +50,10 @@ Use it when:
 # Install
 bun install -g @gmickel/gno
 
-# Add a few collections
-gno init ~/notes --name notes
+# Prove the first folder immediately; semantic work continues independently
+gno setup ~/notes --name notes
+
+# Add more collections with the granular commands
 gno collection add ~/work/docs --name work-docs --pattern "**/*.{md,pdf,docx}"
 gno collection add ~/work/gno/src --name gno-code --pattern "**/*.{ts,tsx,js,jsx}"
 
@@ -49,7 +62,7 @@ gno context add "notes:" "Personal notes, journal entries, and long-form ideas"
 gno context add "work-docs:" "Architecture docs, runbooks, RFCs, meeting notes"
 gno context add "gno-code:" "Source code for the GNO application"
 
-# Index + embed
+# Sync the additional collections, then embed when you want semantic retrieval
 gno update --yes
 gno embed
 
@@ -94,12 +107,16 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.22.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.24.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
@@ -203,8 +220,7 @@ gno query "ECONNREFUSED 127.0.0.1:5432" --thorough
 ## Quick Start
 
 ```bash
-gno init ~/notes --name notes    # Point at your docs
-gno index                        # Build search index
+gno setup ~/notes --name notes   # Build BM25 and prove an exact local result
 gno daemon --detach              # Keep index fresh in the background (macOS/Linux)
 gno query "auth best practices"  # Hybrid search
 gno ask "summarize the API" --answer  # AI answer with citations
@@ -239,14 +255,19 @@ brew install sqlite3
 Verify the local installation and corpus-derived lexical retrieval:
 
 ```bash
-gno doctor
-gno status --json
+gno setup ~/notes --name notes
 ```
 
-`gno status` is passive with respect to models and connectors and exits 0 even
-when its structured activation state is degraded. `gno doctor` exits 2 when any
-configured folder fails the lexical proof; semantic models may still be pending
-without blocking BM25 search.
+`gno setup` returns only after BM25 finds an exact `gno://` result from the
+folder. It is safe to rerun: the same canonical folder and collection are
+reused. Semantic indexing is a separate one-shot process; `--no-semantic`
+records an explicit skip. Add repeatable `--connector <id>` flags only when you
+also want supported agent integrations installed and checked. Setup is direct
+and standalone—it never attaches to `serve`, `daemon`, Web, or MCP.
+
+Use `gno status --json` for passive state and `gno doctor` for diagnostics.
+Semantic pending and connector follow-up never invalidate proven lexical
+search.
 
 <!-- public-truth:supported-platforms -->
 

package/assets/skill/SKILL.md

@@ -30,12 +30,19 @@ network boundaries.
 ## Quick Start
 
 ```bash
-gno init                              # Initialize in current directory
-gno collection add ~/docs --name docs # Add folder to index
-gno index                             # Build index (ingest + embed)
+gno setup ~/docs --name docs          # Index + prove exact BM25; semantic continues
 gno search "your query"               # BM25 keyword search
 ```
 
+`gno setup` is the default activation path. It is idempotent, returns only
+after exact lexical proof, and runs directly without resident/Web/MCP
+attachment. Use `--no-semantic` to start no worker and record skipped state.
+Use repeatable `--connector` with `claude-code-skill`,
+`claude-desktop-mcp`, `cursor-mcp`, `codex-skill`, `opencode-skill`,
+`openclaw-skill`, or `hermes-skill`. Connector skips/failures can return
+`completed_with_actions` without invalidating lexical success. Skill targets
+are installed but report `target_runtime_unverifiable`.
+
 ## Recipe Router
 
 Use these recipe files when the task is more than a one-off lookup. Read only
@@ -63,22 +70,22 @@ Recipe rules:
 
 ## Command Overview
 
-| Category     | Commands                                                                | Description                                                              |
-| ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| **Search**   | `search`, `vsearch`, `query`, `ask`                                     | Find documents by keywords, meaning, or get AI answers                   |
-| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`                 | Navigate document relationships and typed connections                    |
-| **Retrieve** | `get`, `multi-get`, `ls`                                                | Fetch document content by URI or ID                                      |
-| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed`        | Set up and maintain document index                                       |
-| **Tags**     | `tags`, `tags add`, `tags rm`                                           | Organize and filter documents                                            |
-| **Context**  | `context add/list/rm/check/build/verify/watch/watches/reverify/unwatch` | Configure guidance or compile, verify, and watch saved evidence Capsules |
-| **Changes**  | `changes`, `diff`, `impact`                                             | Inspect bounded metadata history and dependency impact                   |
-| **Traces**   | `trace list/show/label/export/replay/delete/purge`                      | Manage and replay private retrieval receipts                             |
-| **Models**   | `models list/use/pull/clear/path`                                       | Manage local AI models                                                   |
-| **Serve**    | `serve`, `daemon`                                                       | One resident Web/headless gateway and watcher                            |
-| **Publish**  | `publish export`                                                        | Export gno.sh publish artifacts                                          |
-| **MCP**      | `mcp`, `mcp install/uninstall/status`                                   | AI assistant integration                                                 |
-| **Skill**    | `skill install/uninstall/show/paths`                                    | Install skill for AI agents                                              |
-| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`             | Maintenance and diagnostics                                              |
+| Category     | Commands                                                                  | Description                                                              |
+| ------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Search**   | `search`, `vsearch`, `query`, `ask`                                       | Find documents by keywords, meaning, or get AI answers                   |
+| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`                   | Navigate document relationships and typed connections                    |
+| **Retrieve** | `get`, `multi-get`, `ls`                                                  | Fetch document content by URI or ID                                      |
+| **Index**    | `setup`, `init`, `collection add/list/remove`, `index`, `update`, `embed` | Prove first retrieval, then maintain the document index                  |
+| **Tags**     | `tags`, `tags add`, `tags rm`                                             | Organize and filter documents                                            |
+| **Context**  | `context add/list/rm/check/build/verify/watch/watches/reverify/unwatch`   | Configure guidance or compile, verify, and watch saved evidence Capsules |
+| **Changes**  | `changes`, `diff`, `impact`                                               | Inspect bounded metadata history and dependency impact                   |
+| **Traces**   | `trace list/show/label/export/replay/delete/purge`                        | Manage and replay private retrieval receipts                             |
+| **Models**   | `models list/use/pull/clear/path`                                         | Manage local AI models                                                   |
+| **Serve**    | `serve`, `daemon`                                                         | One resident Web/headless gateway and watcher                            |
+| **Publish**  | `publish export`                                                          | Export gno.sh publish artifacts                                          |
+| **MCP**      | `mcp`, `mcp install/uninstall/status`                                     | AI assistant integration                                                 |
+| **Skill**    | `skill install/uninstall/show/paths`                                      | Install skill for AI agents                                              |
+| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`               | Maintenance and diagnostics                                              |
 
 ## Search Modes
 
@@ -108,8 +115,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.22.0",
+  "version": "1.24.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

@@ -64,6 +64,7 @@ equivalent files fail closed as ambiguous.
 | ------------------ | ------ | ------- | ----- | ---- | ----- | -------- |
 | status             | yes    | no      | no    | yes  | no    | terminal |
 | init               | no     | no      | no    | no   | no    | terminal |
+| setup              | yes    | no      | no    | no   | no    | terminal |
 | collection add     | no     | no      | no    | no   | no    | terminal |
 | collection list    | yes    | no      | no    | yes  | no    | terminal |
 | collection remove  | no     | no      | no    | no   | no    | terminal |
@@ -353,6 +354,96 @@ projected wiki/markdown edges and surface in graph traversal/diagnose metadata.
 
 ---
 
+### gno setup
+
+Add or reuse one folder collection, build its lexical index, and prove a real
+corpus-derived retrieval before reporting success. Semantic indexing is handed
+to one standalone background worker and never delays lexical success.
+
+**Synopsis:**
+
+```bash
+gno setup <folder> [-n|--name <name>] [--exclude <pattern>]...
+  [--authorize-secret-risk] [--connector <id>]...
+  [--no-semantic] [--json]
+```
+
+**Options:**
+
+| Option                    | Type       | Default       | Description                                                                  |
+| ------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------- |
+| `-n, --name <name>`       | string     | dirname       | Requested collection name; exact-root reruns reuse the configured collection |
+| `--exclude <pattern>`     | repeatable | core defaults | One literal exclusion per occurrence; never CSV                              |
+| `--authorize-secret-risk` | boolean    | false         | Explicitly authorize likely credentials, private keys, or env files          |
+| `--connector <id>`        | repeatable | none          | Install or reuse and verify one supported connector after lexical proof      |
+| `--no-semantic`           | boolean    | false         | Prove lexical retrieval but record semantic work as skipped                  |
+| `--json`                  | boolean    | false         | Emit one closed setup result object                                          |
+
+Omitting `--exclude` preserves the core create defaults or the filters already
+configured for an exact-root rerun. An empty occurrence is invalid. Global
+`--yes` accepts safe defaults only; it never authorizes secret risk. Only an
+interactive terminal may ask one default-No question after the lexical core
+returns `secret_risk`. JSON, `--yes`, non-TTY, decline, and EOF fail closed.
+
+The command bootstraps missing config/data/database state without adding the
+folder through `init`, then runs the folder setup transaction. Success requires
+a completed `FolderSetupReceipt@1.0`, `activation.ready=true`, and a non-empty
+exact `activation.evidence.resultUri`. Terminal stage progress uses stderr;
+`--quiet` suppresses progress but not the final result. JSON writes exactly one
+canonical result to stdout on both success and domain failure, with no progress.
+
+After lexical proof, the command records one private atomic
+`setup-semantic@1.0` receipt per canonical index/folder and starts one detached,
+collection-scoped Bun worker. A matching live worker is reused; a dead worker is
+replaced; and a live worker with an older identity remains authoritative until
+it exits so its completion receipt cannot be stranded. A later setup rerun may
+then schedule the new identity. The worker uses the normal model
+download/offline policy, records `completed` only when embedding and vector
+synchronization finish without errors, and exits. Spawn, download, partial
+embedding, and vector-sync failures retain an exact foreground
+`gno ... embed <collection>` remediation and never change proven lexical exit 0.
+Direct setup never contacts a resident, MCP, or Web runtime.
+
+`--connector` is explicit and repeatable; omission performs no connector
+inspection, installation, or verification. Supported IDs are
+`claude-code-skill`, `claude-desktop-mcp`, `cursor-mcp`, `codex-skill`,
+`opencode-skill`, `openclaw-skill`, and `hermes-skill`. Exact duplicates dedupe
+in first-seen order. Unknown IDs fail before setup side effects.
+Any connector-mode JSON invocation emits `setup-activation-result@1.0`.
+Argument or lexical failure uses outer `status: failed`, nests the unchanged
+failed setup result, and keeps `connectors: []`; it retains the original setup
+exit code and performs no connector action.
+
+After proven lexical success and after the lexical store closes, the direct CLI
+opens a new standalone store for connector composition. Missing targets use the
+existing read-only installer; existing entries are reused without overwrite.
+Malformed or unreadable entries are preserved. MCP targets run the shipped
+bounded read-only activation smoke. Skill targets install but return
+`skipped/target_runtime_unverifiable` because they expose no safe runtime hook.
+Connector failures or skips do not roll back lexical success: the command exits
+0 with `completed_with_actions` and bounded per-target remediation. No raw child
+output or client config path is serialized. Reruns delegate passed-receipt reuse
+and recoverable retry to the shipped activation verifier; setup introduces no
+second connector fingerprint or cache.
+
+**Structured schemas:**
+
+- [`setup-command-result@1.0`](./output-schemas/setup-command-result.schema.json)
+- [`setup-activation-result@1.0`](./output-schemas/setup-activation-result.schema.json)
+- [`setup-semantic@1.0`](./output-schemas/setup-semantic-receipt.schema.json)
+- [`FolderSetupReceipt@1.0`](./output-schemas/setup-receipt.schema.json)
+
+**Exit Codes:**
+
+- 0: Lexical setup completed with a real exact result URI; semantic state may
+  be scheduled, running, pending, completed, or skipped; requested connector
+  actions may require bounded follow-up
+- 1: Invalid/safe-input rejection, collection/filter/index disagreement,
+  secret-risk refusal, or declined confirmation
+- 2: Config, receipt, IO, store, indexing, proof, or internal invariant failure
+
+---
+
 ### gno collection add
 
 Add a new collection to the index.
@@ -749,22 +840,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:**
 
@@ -824,7 +917,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:**
 
@@ -870,6 +964,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`).
@@ -882,8 +979,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
@@ -992,6 +1093,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)
@@ -1315,7 +1418,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
@@ -1328,6 +1431,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,

package/spec/evals-agentic.md

@@ -22,6 +22,10 @@ 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
@@ -68,6 +72,37 @@ evals/fixtures/agentic-retrieval/
     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

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`,

package/spec/output-schemas/query-diagnose-v1.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/query-diagnose@1.0",
+  "title": "GNO Query Diagnose",
+  "type": "object",
+  "required": ["schemaVersion", "query", "target", "stages", "chunk", "meta"],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "1.0" },
+    "query": { "type": "string" },
+    "target": {
+      "type": "object",
+      "required": [
+        "ref",
+        "status",
+        "docid",
+        "uri",
+        "title",
+        "contentType",
+        "contentTypeSource",
+        "categories",
+        "graphHints",
+        "contentTypeRulesFingerprint",
+        "contentTypeFingerprintMatches",
+        "mirrorHash",
+        "chunkCount",
+        "filterReasons"
+      ],
+      "properties": {
+        "ref": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": [
+            "not_found",
+            "inactive",
+            "no_indexed_content",
+            "filtered_out",
+            "diagnosed"
+          ]
+        },
+        "docid": { "type": ["string", "null"], "pattern": "^#[a-f0-9]{6,}$" },
+        "uri": { "type": ["string", "null"], "format": "uri" },
+        "title": { "type": ["string", "null"] },
+        "contentType": { "type": ["string", "null"] },
+        "contentTypeSource": { "type": ["string", "null"] },
+        "categories": { "type": "array", "items": { "type": "string" } },
+        "graphHints": { "type": "array", "items": { "type": "string" } },
+        "contentTypeRulesFingerprint": { "type": ["string", "null"] },
+        "contentTypeFingerprintMatches": { "type": ["boolean", "null"] },
+        "mirrorHash": { "type": ["string", "null"] },
+        "chunkCount": { "type": "integer", "minimum": 0 },
+        "filterReasons": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "status",
+          "sourceCount",
+          "present",
+          "rank",
+          "score",
+          "survived",
+          "dropReason"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": ["bm25", "vector", "fusion", "graph", "rerank"]
+          },
+          "status": { "type": "string", "enum": ["active", "skipped"] },
+          "sourceCount": { "type": "integer", "minimum": 0 },
+          "present": { "type": "boolean" },
+          "rank": { "type": ["integer", "null"], "minimum": 1 },
+          "score": { "type": ["number", "null"] },
+          "survived": { "type": "boolean" },
+          "dropReason": {
+            "type": ["string", "null"],
+            "enum": ["not_in_candidate_set", "below_cutoff", "skipped", null]
+          },
+          "reason": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "chunk": {
+      "type": "object",
+      "required": ["seq", "startLine", "endLine", "language"],
+      "properties": {
+        "seq": { "type": ["integer", "null"], "minimum": 0 },
+        "startLine": { "type": ["integer", "null"], "minimum": 1 },
+        "endLine": { "type": ["integer", "null"], "minimum": 1 },
+        "language": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "meta": {
+      "type": "object",
+      "required": ["mode", "vectorsUsed", "reranked", "totalResults"],
+      "properties": {
+        "mode": { "type": "string", "enum": ["bm25_only", "hybrid"] },
+        "vectorsUsed": { "type": "boolean" },
+        "reranked": { "type": "boolean" },
+        "totalResults": { "type": "integer", "minimum": 0 },
+        "queryModes": {
+          "type": "object",
+          "required": ["term", "intent", "hyde"],
+          "properties": {
+            "term": { "type": "integer", "minimum": 0 },
+            "intent": { "type": "integer", "minimum": 0 },
+            "hyde": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}