@gmickel/gno 1.25.1 → 1.27.0

package/README.md

@@ -18,9 +18,10 @@
 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,
+ranking signal. A trusted explicit `--project-root`, nearest valid
+`.gno/index.yml`, or local cwd can add at most `+0.03` to matching collection
+results, in that precedence order; `--no-project-affinity` disables it. Profile
+defaults stay project-local and never overwrite the user default. 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
@@ -53,6 +54,10 @@ bun install -g @gmickel/gno
 # Prove the first folder immediately; semantic work continues independently
 gno setup ~/notes --name notes
 
+# In a repository with .gno/index.yml: preview, apply, and prove its collection
+gno profile diff
+gno setup . --apply-profile
+
 # 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}"
@@ -107,7 +112,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.25.1** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.26.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -144,7 +149,8 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
   remote fetch, store listing, or Firefox parity is claimed.
 - **Schema-lite content types**: optional `contentTypes` rules map configured
   frontmatter `type` values or path prefixes to canonical `contentType` metadata
-  in JSON search/query results
+  in JSON search/query results and can apply one bounded, explainable
+  `searchBoost` without bypassing hard filters
 - **Publish to [gno.sh](https://gno.sh/publish)**: new `gno publish export` CLI and Web UI action produce a self-contained artifact you upload to the hosted reader — public, secret, invite-only, or locally encrypted before upload
 - **Retrieval Quality Upgrade**: stronger BM25 lexical handling, code-aware chunking, terminal result hyperlinks, and per-collection model overrides
 - **Code Embedding Benchmarks**: new benchmark workflow across canonical, real-GNO, and pinned OSS slices for comparing alternate embedding models
@@ -194,6 +200,7 @@ Model guides:
 - [Code Embeddings](./docs/guides/code-embeddings.md)
 - [Per-Collection Models](./docs/guides/per-collection-models.md)
 - [Bring Your Own Models](./docs/guides/bring-your-own-models.md)
+- [Project-Local Retrieval Profiles](./docs/guides/project-profiles.md)
 
 ### Fine-Tuned Model Quick Use
 

package/assets/skill/SKILL.md

@@ -37,6 +37,11 @@ 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.
+Inside a repository with `.gno/index.yml`, setup inspects the optional profile
+before mutation. Run `gno profile diff`, then
+`gno setup . --apply-profile` to apply its portable collection/context/content
+rules before setup proves retrieval. Missing/invalid profiles keep ordinary
+setup usable; no profile is applied implicitly.
 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
@@ -70,22 +75,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**    | `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                                              |
+| 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`, `profile check/show/diff/apply`, `init`, `collection add/list/remove`, `index`, `update`, `embed` | Reproduce profile intent, prove retrieval, then maintain the 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
 
@@ -117,14 +122,29 @@ Recipe rules:
 --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
+--explain            Include retrieval scoring details
 ```
 
-CLI searches use the current repository/worktree as a soft signal by default.
+CLI searches use explicit `--project-root`, the nearest valid compiled project
+profile, then the current repository/worktree, in that precedence order.
 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.
 
+Profile affinity defaults are request-local. `gno profile apply` never
+overwrites the user's global `projectAffinity` default, so one repository
+cannot change another repository's fallback. Explain/diagnose identify this
+trusted source as `project_profile`; contexts, content types, source metadata,
+and document fields never become project identity.
+
+Configured `contentTypes[].searchBoost` is a separate local ranking signal.
+`1` is neutral; `0.5..2` maps to a bounded `-0.05..+0.05` contribution, and
+all auxiliary signals share `±0.08`. It cannot create candidates or bypass hard
+filters. Use `gno query --explain`, `gno ask --explain`, or
+`gno query diagnose` when the ranking effect matters; normal output omits the
+boost receipt.
+
 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

package/browser-extension/artifacts/gno-browser-clipper-v1.27.0.zip.sha256

@@ -0,0 +1 @@
+3da63d624c5d61f121c5082cd5db2b233e95be5c72beba14f4a3e73a14384e02  gno-browser-clipper-v1.27.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.25.1"
+  "version": "1.27.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.25.1",
+  "version": "1.27.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

@@ -65,6 +65,10 @@ 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 |
+| profile check      | yes    | no      | no    | no   | no    | terminal |
+| profile show       | yes    | no      | no    | no   | no    | terminal |
+| profile diff       | yes    | no      | no    | no   | no    | terminal |
+| profile apply      | 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 |
@@ -125,6 +129,89 @@ equivalent files fail closed as ambiguous.
 
 ## Commands
 
+### gno profile
+
+Inspect a repository-owned `.gno/index.yml` retrieval profile without changing
+the user config, index database, model cache, or tracked files.
+
+**Synopsis:**
+
+```bash
+gno profile check [path] [--json]
+gno profile show [path] [--json]
+gno profile diff [path] [--json]
+gno profile apply [path] [--json]
+```
+
+With no path, discovery starts at the canonical current directory and walks
+upward. Each directory is checked before its parent, so the nearest nested
+profile wins and any ancestor profile is reported as shadowed; profiles are
+never merged. Discovery stops after checking the first Git root (`.git` may be a
+directory or a worktree file), before crossing a filesystem device boundary,
+or at the filesystem root. This gives a nested repository precedence over its
+parent repository and lets a monorepo subtree intentionally shadow the root
+profile.
+
+An explicit directory path is an exact profile-root override: only
+`<path>/.gno/index.yml` is considered. An explicit
+`<path>/.gno/index.yml` file selects that exact profile. Explicit overrides do
+not fall back to ancestors. The profile file and its `.gno` path must resolve
+inside the selected canonical profile root; symlink escapes fail closed.
+Remote callers cannot enable discovery or cause filesystem probes.
+
+`check` validates discovery, schema, referenced paths, local preset aliases,
+and, with global `--offline`, exact cache availability without downloading.
+`show` returns the same receipt plus normalized portable desired state. `diff`
+compares that desired state with the selected user config. It reports stale
+same-name/path mappings and explicit repair/removal choices but never applies
+either choice. A missing user config is treated as empty desired-state input;
+an unreadable or invalid config is an actionable validation diagnostic.
+
+The three read-only JSON forms use
+[`project-profile-command@1.0`](./output-schemas/project-profile-command.schema.json).
+Receipts contain no absolute profile, config, database, cache, or model paths,
+no timestamps, and no model URIs. Diagnostics and changes are canonically
+ordered, so identical local state produces byte-identical JSON.
+
+`apply` rebuilds the shared diff against config reloaded inside a cross-process
+runtime lock, then creates or updates only resources declared by the profile
+through a resumable operation. It can initialize a missing user config. Omitted collections,
+collection-scoped contexts, and content-type rules remain untouched; stale
+same-path collections are reported as skipped and retained. A stale same-name
+collection root is repaired in place without deleting its collection or index
+identity. Apply also updates a timestamp-free `projectProfileBindings` record
+in the local user config with the canonical absolute profile path, profile
+fingerprint, and projected collection. The public `profile_binding` resource
+receipt identifies only the collection and never exposes that local path.
+Model preset aliases resolve to collection-local model overrides.
+Apply synchronizes the config projection but does not index documents; changed
+collections appear in `pendingIndexing`.
+`affinityDefaults` remains profile-scoped and is compiled at trusted local
+retrieval time; apply does not overwrite the user config `projectAffinity`
+default. Its apply resource is therefore `project_affinity/profile/skipped`,
+while the nearest valid profile can still supply request-local affinity.
+
+The deterministic JSON result uses
+[`project-profile-apply@1.0`](./output-schemas/project-profile-apply.schema.json).
+Its created/reused/updated/skipped resource receipt is also atomically saved as
+`project-profiles/apply-receipt.json` under the user data directory. The config,
+index, receipt, and lock paths must all remain outside the selected profile
+root. The tracked `.gno/index.yml` is never written. Interrupted or concurrent
+applies resume from fresh config state and converge idempotently.
+
+**Exit Codes:**
+
+- `0`: profile found and valid (`diff` may still report changes)
+- `1`: profile missing, ambiguous discovery could not be resolved safely, or
+  profile/config validation failed, including runtime-path overlap
+- `2`: unexpected local I/O, lock, receipt, or index-store failure
+
+`gno setup` calls the same local `check` composition before its folder
+transaction. Inspection is read-only and non-fatal. Plain setup prints bounded
+preview/apply guidance but preserves the existing setup result contract.
+Explicit `--apply-profile` runs the same lock-safe apply path before lexical
+setup and emits `setup-profile-result@1.0`.
+
 ### gno status
 
 Display index status and health information.
@@ -349,7 +436,14 @@ Zod validates `id`, `prefixes`, `preset`, `graphHints`, `searchBoost`, and
 `temporal`, while `preset` remains a permissive string. Post-parse normalization
 warns and drops unknown preset references, dedupes exact duplicate prefixes,
 retains overlapping prefixes, and sorts rules longest-prefix-first. `searchBoost`
-is accepted but currently no-op. `graphHints` is active: ordered hints type
+defaults to neutral `1`, accepts `0.5..2`, and maps one canonical configured
+type to a bounded `-0.05..+0.05` ranking contribution. A frontmatter type ID
+wins over longest-prefix matching; boosts never stack, cannot create
+candidates, never widen retrieval or defer `minScore`, and share the final
+`±0.08` auxiliary cap with project affinity. Hybrid applies the composed score
+to normalized fusion before rerank blending; rerank order and lexical top-hit
+protection remain authoritative.
+`graphHints` is active: ordered hints type
 projected wiki/markdown edges and surface in graph traversal/diagnose metadata.
 
 ---
@@ -365,7 +459,7 @@ to one standalone background worker and never delays lexical success.
 ```bash
 gno setup <folder> [-n|--name <name>] [--exclude <pattern>]...
   [--authorize-secret-risk] [--connector <id>]...
-  [--no-semantic] [--json]
+  [--apply-profile] [--no-semantic] [--json]
 ```
 
 **Options:**
@@ -376,6 +470,7 @@ gno setup <folder> [-n|--name <name>] [--exclude <pattern>]...
 | `--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      |
+| `--apply-profile`         | boolean    | false         | Apply a valid discovered project profile before lexical setup                |
 | `--no-semantic`           | boolean    | false         | Prove lexical retrieval but record semantic work as skipped                  |
 | `--json`                  | boolean    | false         | Emit one closed setup result object                                          |
 
@@ -392,6 +487,53 @@ 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.
 
+Before the folder transaction, setup performs the same local read-only
+`gno profile check` composition from the supplied folder. Missing and invalid
+profiles remain optional and never block ordinary setup. Terminal output shows
+a valid profile fingerprint plus `profile diff`/`--apply-profile` guidance, or
+an invalid-profile diagnostic, before setup mutates local state.
+
+`--apply-profile` is explicit. When the check is valid, setup runs the existing
+cross-process lock-safe, create/update-only `profile apply` path first, then
+uses the applied profile collection's canonical root, name, and filters for
+lexical setup. A nested folder invocation therefore indexes the declared
+profile root rather than creating a duplicate subdirectory collection. The
+profile never deletes omitted resources or overwrites the user-level
+`projectAffinity` default.
+
+Once a valid profile has been discovered for an explicit `--apply-profile`
+request, apply is a fail-closed prerequisite. A validation failure returns exit
+1; an apply I/O/lock/store failure, thrown apply transport, missing result, or
+malformed success receipt returns exit 2. In every case setup aborts before its
+folder transaction or connector work. A late apply failure may have persisted
+resumable create/update-only profile state, but cannot trigger ordinary setup
+reconciliation. The outer result is `failed`, the nested lexical error code is
+`profile_apply_failed`, and `profile.apply` retains a returned apply result or
+is `null` when apply produced no result.
+
+Missing or invalid profile inspection remains the optional fallback described
+below. A thrown inspection transport/runtime failure for an explicit
+`--apply-profile` request instead returns exit 2 with
+`profile_inspection_failed` before apply or setup mutation. Because no trusted
+profile check result exists, this failure uses the unchanged
+`setup-command-result@1.0` shape rather than fabricating `profile.check`.
+
+For a valid profile, `--apply-profile` is mutually exclusive with explicit
+`--name` and `--exclude` values. A conflict returns exit 1 with
+`profile_option_conflict` before config, store, or index mutation. Profile
+include/exclude values use validated Bun-glob semantics; plain exclusion
+components retain component matching. Brace alternatives are rejected; express
+their branches as separate include/exclude entries. Discovery permission/I/O
+failures return exit 2, while missing, disabled, invalid, and unsafe profiles
+return exit 1.
+
+Opt-in JSON uses
+[`setup-profile-result@1.0`](./output-schemas/setup-profile-result.schema.json)
+and includes the closed `profile.check`, nullable `profile.apply`, unchanged
+setup result, and connectors. A missing/invalid profile keeps setup usable and
+returns `completed_with_actions` with `profile.apply: null`. Without
+`--apply-profile`, the existing setup/activation JSON bytes remain unchanged.
+
 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
@@ -430,6 +572,7 @@ second connector fingerprint or cache.
 
 - [`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-profile-result@1.0`](./output-schemas/setup-profile-result.schema.json)
 - [`setup-semantic@1.0`](./output-schemas/setup-semantic-receipt.schema.json)
 - [`FolderSetupReceipt@1.0`](./output-schemas/setup-receipt.schema.json)
 
@@ -1067,7 +1210,7 @@ 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|--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]
+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] [--explain] [--show-sources] [--json|--md]
 ```
 
 **Options:**
@@ -1092,6 +1235,7 @@ gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [
 | `-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                                                    |
+| `--explain`               | boolean  | false   | Include retrieval scoring details; prints to stderr outside structured output      |
 | `--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`                  |
@@ -1102,6 +1246,11 @@ See [Output Schemas](./output-schemas/ask.schema.json)
 Notes:
 
 - `meta.answerContext` is optional explain payload for answer source selection.
+- `meta.explain` is present only with `--explain`. Its optional
+  `contentTypeBoost` result component contains the raw/base score, configured
+  factor, capped and combined contributions, final score, rule source, and full
+  ranking-rules fingerprint. Verified Ask attaches this as a non-canonical
+  sidecar; Capsule identity and bytes do not change.
 - `--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`,
@@ -1338,6 +1487,10 @@ retrieval results and is used as trusted guidance during grounded answer
 generation. Matching scopes compose once in this order: global, collection,
 then path prefixes from broadest to most specific. Context guides interpretation;
 it is not searched and does not change ranking.
+Multiple distinct normalized texts may share one scope. The persisted identity
+is `(scopeType, canonicalScopeKey, normalizedText)`. Text normalization removes
+a leading BOM, converts CRLF/CR to LF, applies NFC, and trims surrounding
+whitespace; an exact normalized duplicate is rejected.
 
 **Synopsis:**
 
@@ -1411,18 +1564,20 @@ gno context check [--json|--md]
 
 ### gno context rm
 
-Remove a context.
+Remove a context. Scope-only removal succeeds only when exactly one record
+matches. If multiple texts share the scope, the caller MUST pass exact text;
+ambiguous removal fails without mutation.
 
 **Synopsis:**
 
 ```bash
-gno context rm <scope>
+gno context rm <scope> [text]
 ```
 
 **Exit Codes:**
 
 - 0: Success
-- 1: Scope not found
+- 1: Invalid/not-found scope, text not found, or ambiguous scope-only removal
 
 ---
 

package/spec/db/schema.sql

@@ -61,7 +61,7 @@ CREATE TABLE IF NOT EXISTS contexts (
   scope_key TEXT NOT NULL,
   text TEXT NOT NULL,
   synced_at TEXT NOT NULL DEFAULT (datetime('now')),
-  PRIMARY KEY (scope_type, scope_key)
+  PRIMARY KEY (scope_type, scope_key, text)
 );
 
 -- ─────────────────────────────────────────────────────────────────────────────

package/spec/evals-agentic.md

@@ -26,6 +26,7 @@ evals/agentic/
   project-affinity-outcome.ts
   project-affinity-promotion.ts
   project-affinity-runtime.ts
+  content-type-boost-promotion.ts
   verified-ask-outcome.ts
   verified-ask-promotion.ts
   demos/context-capsule.ts
@@ -103,6 +104,22 @@ 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.
 
+## Separate content-type boost promotion
+
+The authoritative lane also writes
+`content-type-boost-promotion.json` and `.md`. These 24 before/after receipts
+project the fn-97 production retrieval rankings through the shipped
+content-type ranking seam with no configured rules. Every ordered URI and
+required-evidence receipt must remain byte-identical, with zero accuracy and
+coverage loss. This is backward-compatibility evidence for existing configs,
+not an active-rule quality claim.
+
+Active positive/negative factors, keyword stuffing, deterministic ties,
+configured-ID versus prefix conflicts, filter isolation, and project-affinity
+composition are gated separately by the deterministic adversarial pipeline
+suite. Egress policy is not yet an available retrieval capability, so the
+artifact makes no egress-enforcement 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/mcp.md

@@ -216,7 +216,7 @@ Required input:
 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
+`explain`, `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
@@ -648,6 +648,11 @@ Hybrid search combining BM25 and vector retrieval with optional expansion and re
       "description": "Enable cross-encoder reranking",
       "default": true
     },
+    "explain": {
+      "type": "boolean",
+      "description": "Include deterministic stage and per-result scoring metadata",
+      "default": false
+    },
     "noGraph": {
       "type": "boolean",
       "description": "Compatibility no-op unless graph is also true",
@@ -692,6 +697,11 @@ Search result items include `contentType` when available and always include
 human-oriented; structured clients should read `structuredContent.results`.
 Structured result items also preserve optional `context` guidance in
 global-to-specific order without changing the result `uri` or `docid`.
+When `explain: true`, `structuredContent.meta.explain` includes deterministic
+stage lines and per-result score receipts. Non-neutral configured content-type
+rules add `contentTypeBoost` with base/raw scores, factor, capped contribution,
+shared auxiliary-cap composition, final score, rule source, and redacted rules
+fingerprint. Normal output omits this sidecar.
 
 Compatibility / migration notes:
 
@@ -753,16 +763,17 @@ plus a required `target` reference.
 - `target`: URI, `#docid`, or `collection/path` for the document to diagnose.
 - `query`, filters, `queryModes`, `fast`/`thorough`, `graph`, and rerank/expand controls behave like `gno_query`.
 
-**Output Schema:** `gno://schemas/query-diagnose@1.0`
+**Output Schema:** `gno://schemas/query-diagnose@1.2`
 
 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.
+MCP inputs are remote and untrusted, so this tool omits `affinity`, even when
+`projectHints` are supplied. Neutral configurations preserve exact v1.0 bytes;
+an active configured content-type boost emits v1.2 with the same bounded score
+receipt exposed by query explain. The v1.1 affinity-bearing branch remains
+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`,
@@ -979,11 +990,19 @@ counters; it never claims attachment to another process.
     "totalDocuments": 150,
     "totalChunks": 800,
     "embeddingBacklog": 0,
+    "contentTypeBoost": {
+      "rulesFingerprint": "<sha256>",
+      "rules": [{ "id": "decision", "searchBoost": 2 }]
+    },
     "healthy": true
   }
 }
 ```
 
+`contentTypeBoost` is a redacted ranking-status projection. It exposes only
+normalized IDs/factors plus the rules fingerprint; path prefixes are never
+returned.
+
 ---
 
 ### gno_capture

package/spec/output-schemas/ask.schema.json

@@ -557,6 +557,9 @@
               }
             }
           }
+        },
+        "explain": {
+          "$ref": "gno://schemas/search-results@1.0#/properties/meta/properties/explain"
         }
       }
     }