openmerit 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.7 — 2026-11-06 (release preparation)
+
+- The installed Scout skill distinguishes no eval setup, insufficient evals and suitable existing evals. Langfuse is the default customer-owned platform suggestion, not a requirement; local/custom evals can report aggregates. The customer's coding agent implements evals, while OpenMerit remains Viewer-only. Instructions require a local Markdown decision record before proposing explicitly approved cleanup of newly created comparison runs; existing records and reusable fixtures/definitions stay intact. This adds guidance, not an eval runner, automatic deletion or another platform connector. Fresh-agent acceptance remains a release gate.
+
+## 0.3.6 — 2026-11-06
+
+- Distinguish a connected Langfuse key from incomplete score-import setup. Connection status exposes only score-mapping and model-alias counts, and the web UI explains when either is missing. The CLI preserves those counts when the server provides them. Requires the corresponding Scout deployment and npm patch; does not change credentials, mappings or experiment attribution.
+- Update an existing Langfuse connection's non-secret settings through CLI, MCP or API without retrieving or re-entering its Viewer key. Omit both Viewer credentials; Scout reuses and reverifies the encrypted key internally. New connections still require a protected Viewer pair, and partial pairs are rejected. Settings changes invalidate imported aggregates; sync again afterwards. Requires the matching Scout deployment.
+
 ## 0.3.5 — 2026-11-05
 
 - Add optional headless Langfuse setup through the CLI, HTTP API and `scout_connection` MCP tool. A separately approved `scout:connections` key manages the authenticated user's connection and evaluation data; recommendation keys retain their existing permission. Viewer credentials enter through protected CLI input or trusted client configuration, never model-visible tool arguments. The web connection UI remains available, with revised spacing, mobile controls and the official Langfuse logo. Hosted features require a matching Scout deployment; saving Langfuse credentials also requires its dedicated encryption secret. Publishing this package does not deploy or enable the hosted connector.

package/dist/pi/scout-extension.mjs

@@ -121,14 +121,27 @@ application accuracy. Use the project's actual SDK and protocol.
 
 Each task also has an \`evaluation\`: the checks (per model call, agent run or
 end-to-end outcome), labelled examples per candidate and when to stop a losing
-candidate. Offer to run it before the user commits to a model. Use the evals the
-project already has, such as datasets and experiments in its eval or tracing
-platform, or its own eval scripts and fixtures: add the shortlisted candidates as
-extra runs of those evals. Do not build a second eval or copy their datasets.
-If the project has no eval for the task, propose a minimal one built from its
-existing traces and the decisions people already make, and create it only where
-and how the user agrees. Ask before spending on model calls or writing to an
-eval platform.
+candidate. Offer to run it before the user commits to a model. First assess the
+project's readiness for this task:
+
+- **No eval setup:** propose a customer-owned setup. Langfuse is the default
+  suggestion for its supported aggregate connector, not a requirement: existing
+  local/custom eval scripts can report aggregates without a hosted platform.
+  Phoenix/Arize and Braintrust are alternatives, not supported Scout connectors.
+  Ask which system the user wants before creating accounts or resources.
+- **Setup exists but evidence is insufficient:** keep that system. Write a
+  task-specific eval plan in the project's local Markdown decision record for
+  the user or their coding agent to implement. Name exact candidates/endpoints,
+  quality floor and task/agent/outcome checks, labelled boundary cases and
+  controls, sample size, early-stop rule, spend cap, aggregate mappings and
+  temporary run retention. Explain what the current evidence cannot decide.
+- **Suitable evals exist:** reuse their fixtures and definitions; add only the
+  approved candidate runs. Do not build a second eval or copy their datasets.
+
+OpenMerit does not host or run these evals. The customer or their coding agent
+implements and maintains them with the customer's tools; Scout keeps Viewer-only
+access. Ask before model spend or any platform write. Without measured evidence,
+Scout may suggest candidates, but do not claim validated model quality.
 
 Report what you measured with \`scout_models\`: the same \`conversationId\` and
 \`results\`, one aggregate per model and metric (\`level\`, \`task\` title, \`scope\`,
@@ -146,6 +159,25 @@ fixed. Use each agent's own checks to attribute failures. If all candidates scor
 100%, the eval cannot separate their quality: add harder labelled cases before
 claiming equivalent quality. Cost may break the observed tie, not prove equality.
 
+## Preserve evidence before cleanup
+
+Before removing temporary comparison runs, save a local Markdown decision record
+with the package/service versions, date, task and policy, exact candidates,
+unchanged controls, metric definitions/directions, sample counts, aggregate
+quality/cost/time, failures and exclusions, chosen model, limitations and next
+review. Record regret against the cheapest measured candidate meeting the same
+quality floor; write "not measurable" when comparable evidence is missing.
+Exclude secrets, private record IDs, prompts, outputs and trace bodies.
+
+Temporary comparison traces/records are not permanent: after the record is saved
+and checked, propose the exact newly created comparison runs to remove. Obtain
+explicit scoped approval, including any cascading deletion, before the customer
+or their coding agent deletes them with customer-controlled write access. Scout's
+Viewer key cannot do this. Never delete pre-existing customer records, reusable
+fixtures, dataset definitions or eval definitions. Verify the approved cleanup
+and retained controls, then record the outcome locally. If not approved, leave
+records unchanged and state cleanup is pending; do not imply it happened.
+
 If the user has Langfuse, use \`openmerit connect langfuse --help\`: the web UI is
 optional. Headless setup requires a separate connection-manager approval with
 \`openmerit connect langfuse --authorize --no-open\`. Relay its approval link and

package/dist/terminal/scout-update.json

@@ -1 +1 @@
-{"format":1,"contract":"scout-recommend-v2","version":"0.3.5","skill":"---\nname: openmerit-scout\ndescription: Consults OpenMerit Scout before choosing, adding, downloading, replacing or configuring any application inference model, including implicit choices while building features, pretrained browser/local models, SDK defaults, embeddings, OCR, speech, classification, detection, segmentation, LLMs and agents. Not for unrelated edits, ordinary inference calls or this coding agent's own model.\n---\n\n# OpenMerit · Scout\n\nBefore introducing, recommending, replacing or configuring an application\ninference model, call the `scout_models` tool on the `openmerit` MCP server.\nThis applies even when the user never mentions models or Scout. Downloading local\nweights, using a pretrained browser model or accepting an SDK default is a model\ndecision: consult Scout before model-specific code, installs or downloads.\nPreserve the user's explicit model choice; assess it rather than silently replacing\nit. Leave unchanged, approved application selections in place.\n\n## Project policy\n\nRead `.openmerit/scout.json` before searching. If it is absent, ask once whether this\nproject uses **existing-only** (only endpoints it can already reach) or\n**existing-first** (prefer them, ask before searching the whole catalogue), and\nwhich public catalogue endpoint IDs it can access. Save the answer:\n\n```sh\nnpx -y openmerit@latest project --policy existing-only --endpoint-id <id> ...\n```\n\nNever infer access from a model name, SDK or environment-variable name. Never\nrecord credentials, private URLs, prompts or customer data. An empty inventory\nis not permission to search all models.\n\n## Searching\n\nCall `scout_models` with a non-confidential task description as `prompt` and\n`endpointIds` set to the saved inventory, including `[]` when empty. Send\nonly task requirements, never source files, secrets or real customer records.\nIf the MCP tool is unavailable, run\n`npx -y openmerit@latest scout \"<task>\" --json`; it applies the saved inventory.\n\nScout is a conversation with the agent behind openmerit.ai/scout. When\n`status` is `needs_answers`, fill in what the user or project already states,\nshow the user Scout's brief and remaining questions, and wait for their answers.\nThen call again with the returned `conversationId` and `brief` set to the\nrewritten components, or `skip: true` if the user wants Scout to assume. Never\nanswer Scout's questions with guesses. Send later refinements to the same\n`conversationId`. A call with only a `conversationId` reads an interrupted turn.\n\nWhen `status` is `recommended`, Scout has split the work into `tasks`, one\nper model, each with up to five ranked `models`; cover every task. Each\nmodel's `cost` names the `endpointId` and `providerModelId` to call.\nExisting-only never broadens. For existing-first, if no existing candidate fits a\ntask, explain the gap and ask before a new conversation without `endpointIds`.\nCompare quality evidence, reference cost/time and watch-outs. Prefer the cheapest\nusable option the evidence supports, without claiming benchmarks prove\napplication accuracy. Use the project's actual SDK and protocol.\n\n## Measuring candidates\n\nEach task also has an `evaluation`: the checks (per model call, agent run or\nend-to-end outcome), labelled examples per candidate and when to stop a losing\ncandidate. Offer to run it before the user commits to a model. Use the evals the\nproject already has, such as datasets and experiments in its eval or tracing\nplatform, or its own eval scripts and fixtures: add the shortlisted candidates as\nextra runs of those evals. Do not build a second eval or copy their datasets.\nIf the project has no eval for the task, propose a minimal one built from its\nexisting traces and the decisions people already make, and create it only where\nand how the user agrees. Ask before spending on model calls or writing to an\neval platform.\n\nReport what you measured with `scout_models`: the same `conversationId` and\n`results`, one aggregate per model and metric (`level`, `task` title, `scope`,\n`model` endpoint or model ID, `metric`, `value`, `higherIsBetter`,\n`samples`, `source`). Set `kind` to `usd` or `seconds` for measured cost\nor time (per call at the task level, per run at the agent level), so Scout uses\nyour cost instead of its estimate. Report each agent's own checks at the agent\nlevel: an end-to-end result also measures the agents you did not swap. Send\naggregates only, never inputs, outputs or records.\nScout ranks them above public benchmarks for this user only; models whose\n`quality.measured` is true rest on them.\n\nSwap one agent at a time, holding the other agents, prompts, fixtures and controls\nfixed. Use each agent's own checks to attribute failures. If all candidates score\n100%, the eval cannot separate their quality: add harder labelled cases before\nclaiming equivalent quality. Cost may break the observed tie, not prove equality.\n\nIf the user has Langfuse, use `openmerit connect langfuse --help`: the web UI is\noptional. Headless setup requires a separate connection-manager approval with\n`openmerit connect langfuse --authorize --no-open`. Relay its approval link and\nexpiry; after approval, rerun that command. Existing recommendation keys cannot\nmanage connections. The user creates a separate Viewer key; receive it through\nprotected stdin or a secret-manager-injected environment, never chat, tool\narguments, shell literals, traced commands or tracked files. The CLI accepts\nnon-secret settings via `--config mappings.json` and reads LANGFUSE_PUBLIC_KEY\nand LANGFUSE_SECRET_KEY from its environment, or reads full settings via --stdin.\nA separate trusted MCP connection with the management key exposes\n`scout_connection` (status/configure/sync/disconnect/clear). For configure, keys\nmust come from client-controlled HTTP headers outside model context; if the\nclient cannot do this securely, use protected CLI input or the web UI instead.\nAfter they confirm connection and score/model mappings, call `scout_models` with\n`sync: \"langfuse\"` to refresh aggregate measurements before recommending. The CLI\nequivalent is `openmerit scout --conversation <id> --sync langfuse`. Never read\ntrace bodies to work around missing mappings or untagged runs; use the aggregate\nreport path instead. Results are stored per user, used in new conversations and\nexpire after 90 days. Disconnect deletes the Viewer key and imported aggregates;\nDelete all evaluation data also deletes manually reported aggregates. Obtain\nconsent before deleting: headless CLI requires --yes, MCP requires confirm: true.\nDeleting the connection does not revoke the separate management device key.\nPast conversation text is not erased. Never put record IDs, emails or secrets in\n`scope` or `source`; use labels such as \"coding agent\" and \"held-out eval\".\n\n## Boundaries\n\nAsk before adding providers or credentials, spending, deploying or external\nwrites. Report recommendation, endpoint connectivity and application checks as\nseparate results, each only after it succeeds. Do not switch this coding agent's\nown model.\n\nIf Scout fails or has no suitable candidate/evidence for the required deployment,\nsay so and pause the model decision; do not substitute a remembered recommendation\nor SDK default. Continue only model-independent work. Local/browser models are not\nexempt when the catalogue lacks coverage. When an install or login waits for approval (exit code\n10), show the user the approval link and its UTC expiry in your reply, not only in\ncommand output, then rerun the same command once they approve. If it reports that the device key is missing,\nexpired or revoked, run `npx -y openmerit@latest login` and then\n`npx -y openmerit@latest install` again. Never ask the user to paste a key.\n","rule":"# Application model decisions · OpenMerit Scout\n\nBefore choosing, recommending, adding, downloading, replacing or configuring\nANY application inference model, load the `openmerit-scout` skill and consult\n`scout_models` on the `openmerit` MCP server before committing to a model.\nThis applies even when the user only asks you to build a feature, never mentions\nmodels or Scout, or names a model themselves (assess it; do not silently replace it).\n\nA pretrained model, local weights, browser inference, an SDK's default model,\nembeddings, OCR, speech, image classification, detection and segmentation all\ncount as model choices, not implementation details. Identify this decision before\nwriting model-specific code, installing a model package or downloading weights.\n\nFollow the skill's project access policy. If it is missing, ask and save it first.\nScout may answer with clarifying questions: relay them to the user and continue\nthe same Scout conversation with their answers before choosing.\nIf Scout is unavailable, fails or has no suitable evidence/candidate, disclose the\ngap and pause the model decision; do not fall back to a remembered or SDK-default\nmodel. You may continue work that does not commit to a model.\n\nDo not consult Scout for unrelated edits, normal inference calls using an unchanged\napproved model, or this coding agent's own model. Do not reselect approved models\nunless the task introduces or changes a model decision.\n\nWhen the user says \"update openmerit\", run\n`npx -y openmerit@latest update --scope user` (use `--scope project` if this\nrule is in the project's .claude/rules directory). Report the result, including\nany conflict or manual-upgrade requirement. Do not delete edited files, bypass\npermissions or rerun login automatically. A new session loads updated instructions.\n"}
+{"format":1,"contract":"scout-recommend-v2","version":"0.3.7","skill":"---\nname: openmerit-scout\ndescription: Consults OpenMerit Scout before choosing, adding, downloading, replacing or configuring any application inference model, including implicit choices while building features, pretrained browser/local models, SDK defaults, embeddings, OCR, speech, classification, detection, segmentation, LLMs and agents. Not for unrelated edits, ordinary inference calls or this coding agent's own model.\n---\n\n# OpenMerit · Scout\n\nBefore introducing, recommending, replacing or configuring an application\ninference model, call the `scout_models` tool on the `openmerit` MCP server.\nThis applies even when the user never mentions models or Scout. Downloading local\nweights, using a pretrained browser model or accepting an SDK default is a model\ndecision: consult Scout before model-specific code, installs or downloads.\nPreserve the user's explicit model choice; assess it rather than silently replacing\nit. Leave unchanged, approved application selections in place.\n\n## Project policy\n\nRead `.openmerit/scout.json` before searching. If it is absent, ask once whether this\nproject uses **existing-only** (only endpoints it can already reach) or\n**existing-first** (prefer them, ask before searching the whole catalogue), and\nwhich public catalogue endpoint IDs it can access. Save the answer:\n\n```sh\nnpx -y openmerit@latest project --policy existing-only --endpoint-id <id> ...\n```\n\nNever infer access from a model name, SDK or environment-variable name. Never\nrecord credentials, private URLs, prompts or customer data. An empty inventory\nis not permission to search all models.\n\n## Searching\n\nCall `scout_models` with a non-confidential task description as `prompt` and\n`endpointIds` set to the saved inventory, including `[]` when empty. Send\nonly task requirements, never source files, secrets or real customer records.\nIf the MCP tool is unavailable, run\n`npx -y openmerit@latest scout \"<task>\" --json`; it applies the saved inventory.\n\nScout is a conversation with the agent behind openmerit.ai/scout. When\n`status` is `needs_answers`, fill in what the user or project already states,\nshow the user Scout's brief and remaining questions, and wait for their answers.\nThen call again with the returned `conversationId` and `brief` set to the\nrewritten components, or `skip: true` if the user wants Scout to assume. Never\nanswer Scout's questions with guesses. Send later refinements to the same\n`conversationId`. A call with only a `conversationId` reads an interrupted turn.\n\nWhen `status` is `recommended`, Scout has split the work into `tasks`, one\nper model, each with up to five ranked `models`; cover every task. Each\nmodel's `cost` names the `endpointId` and `providerModelId` to call.\nExisting-only never broadens. For existing-first, if no existing candidate fits a\ntask, explain the gap and ask before a new conversation without `endpointIds`.\nCompare quality evidence, reference cost/time and watch-outs. Prefer the cheapest\nusable option the evidence supports, without claiming benchmarks prove\napplication accuracy. Use the project's actual SDK and protocol.\n\n## Measuring candidates\n\nEach task also has an `evaluation`: the checks (per model call, agent run or\nend-to-end outcome), labelled examples per candidate and when to stop a losing\ncandidate. Offer to run it before the user commits to a model. First assess the\nproject's readiness for this task:\n\n- **No eval setup:** propose a customer-owned setup. Langfuse is the default\n  suggestion for its supported aggregate connector, not a requirement: existing\n  local/custom eval scripts can report aggregates without a hosted platform.\n  Phoenix/Arize and Braintrust are alternatives, not supported Scout connectors.\n  Ask which system the user wants before creating accounts or resources.\n- **Setup exists but evidence is insufficient:** keep that system. Write a\n  task-specific eval plan in the project's local Markdown decision record for\n  the user or their coding agent to implement. Name exact candidates/endpoints,\n  quality floor and task/agent/outcome checks, labelled boundary cases and\n  controls, sample size, early-stop rule, spend cap, aggregate mappings and\n  temporary run retention. Explain what the current evidence cannot decide.\n- **Suitable evals exist:** reuse their fixtures and definitions; add only the\n  approved candidate runs. Do not build a second eval or copy their datasets.\n\nOpenMerit does not host or run these evals. The customer or their coding agent\nimplements and maintains them with the customer's tools; Scout keeps Viewer-only\naccess. Ask before model spend or any platform write. Without measured evidence,\nScout may suggest candidates, but do not claim validated model quality.\n\nReport what you measured with `scout_models`: the same `conversationId` and\n`results`, one aggregate per model and metric (`level`, `task` title, `scope`,\n`model` endpoint or model ID, `metric`, `value`, `higherIsBetter`,\n`samples`, `source`). Set `kind` to `usd` or `seconds` for measured cost\nor time (per call at the task level, per run at the agent level), so Scout uses\nyour cost instead of its estimate. Report each agent's own checks at the agent\nlevel: an end-to-end result also measures the agents you did not swap. Send\naggregates only, never inputs, outputs or records.\nScout ranks them above public benchmarks for this user only; models whose\n`quality.measured` is true rest on them.\n\nSwap one agent at a time, holding the other agents, prompts, fixtures and controls\nfixed. Use each agent's own checks to attribute failures. If all candidates score\n100%, the eval cannot separate their quality: add harder labelled cases before\nclaiming equivalent quality. Cost may break the observed tie, not prove equality.\n\n## Preserve evidence before cleanup\n\nBefore removing temporary comparison runs, save a local Markdown decision record\nwith the package/service versions, date, task and policy, exact candidates,\nunchanged controls, metric definitions/directions, sample counts, aggregate\nquality/cost/time, failures and exclusions, chosen model, limitations and next\nreview. Record regret against the cheapest measured candidate meeting the same\nquality floor; write \"not measurable\" when comparable evidence is missing.\nExclude secrets, private record IDs, prompts, outputs and trace bodies.\n\nTemporary comparison traces/records are not permanent: after the record is saved\nand checked, propose the exact newly created comparison runs to remove. Obtain\nexplicit scoped approval, including any cascading deletion, before the customer\nor their coding agent deletes them with customer-controlled write access. Scout's\nViewer key cannot do this. Never delete pre-existing customer records, reusable\nfixtures, dataset definitions or eval definitions. Verify the approved cleanup\nand retained controls, then record the outcome locally. If not approved, leave\nrecords unchanged and state cleanup is pending; do not imply it happened.\n\nIf the user has Langfuse, use `openmerit connect langfuse --help`: the web UI is\noptional. Headless setup requires a separate connection-manager approval with\n`openmerit connect langfuse --authorize --no-open`. Relay its approval link and\nexpiry; after approval, rerun that command. Existing recommendation keys cannot\nmanage connections. The user creates a separate Viewer key; receive it through\nprotected stdin or a secret-manager-injected environment, never chat, tool\narguments, shell literals, traced commands or tracked files. The CLI accepts\nnon-secret settings via `--config mappings.json` and reads LANGFUSE_PUBLIC_KEY\nand LANGFUSE_SECRET_KEY from its environment, or reads full settings via --stdin.\nA separate trusted MCP connection with the management key exposes\n`scout_connection` (status/configure/sync/disconnect/clear). For configure, keys\nmust come from client-controlled HTTP headers outside model context; if the\nclient cannot do this securely, use protected CLI input or the web UI instead.\nAfter they confirm connection and score/model mappings, call `scout_models` with\n`sync: \"langfuse\"` to refresh aggregate measurements before recommending. The CLI\nequivalent is `openmerit scout --conversation <id> --sync langfuse`. Never read\ntrace bodies to work around missing mappings or untagged runs; use the aggregate\nreport path instead. Results are stored per user, used in new conversations and\nexpire after 90 days. Disconnect deletes the Viewer key and imported aggregates;\nDelete all evaluation data also deletes manually reported aggregates. Obtain\nconsent before deleting: headless CLI requires --yes, MCP requires confirm: true.\nDeleting the connection does not revoke the separate management device key.\nPast conversation text is not erased. Never put record IDs, emails or secrets in\n`scope` or `source`; use labels such as \"coding agent\" and \"held-out eval\".\n\n## Boundaries\n\nAsk before adding providers or credentials, spending, deploying or external\nwrites. Report recommendation, endpoint connectivity and application checks as\nseparate results, each only after it succeeds. Do not switch this coding agent's\nown model.\n\nIf Scout fails or has no suitable candidate/evidence for the required deployment,\nsay so and pause the model decision; do not substitute a remembered recommendation\nor SDK default. Continue only model-independent work. Local/browser models are not\nexempt when the catalogue lacks coverage. When an install or login waits for approval (exit code\n10), show the user the approval link and its UTC expiry in your reply, not only in\ncommand output, then rerun the same command once they approve. If it reports that the device key is missing,\nexpired or revoked, run `npx -y openmerit@latest login` and then\n`npx -y openmerit@latest install` again. Never ask the user to paste a key.\n","rule":"# Application model decisions · OpenMerit Scout\n\nBefore choosing, recommending, adding, downloading, replacing or configuring\nANY application inference model, load the `openmerit-scout` skill and consult\n`scout_models` on the `openmerit` MCP server before committing to a model.\nThis applies even when the user only asks you to build a feature, never mentions\nmodels or Scout, or names a model themselves (assess it; do not silently replace it).\n\nA pretrained model, local weights, browser inference, an SDK's default model,\nembeddings, OCR, speech, image classification, detection and segmentation all\ncount as model choices, not implementation details. Identify this decision before\nwriting model-specific code, installing a model package or downloading weights.\n\nFollow the skill's project access policy. If it is missing, ask and save it first.\nScout may answer with clarifying questions: relay them to the user and continue\nthe same Scout conversation with their answers before choosing.\nIf Scout is unavailable, fails or has no suitable evidence/candidate, disclose the\ngap and pause the model decision; do not fall back to a remembered or SDK-default\nmodel. You may continue work that does not commit to a model.\n\nDo not consult Scout for unrelated edits, normal inference calls using an unchanged\napproved model, or this coding agent's own model. Do not reselect approved models\nunless the task introduces or changes a model decision.\n\nWhen the user says \"update openmerit\", run\n`npx -y openmerit@latest update --scope user` (use `--scope project` if this\nrule is in the project's .claude/rules directory). Report the result, including\nany conflict or manual-upgrade requirement. Do not delete edited files, bypass\npermissions or rerun login automatically. A new session loads updated instructions.\n"}

package/dist/terminal/src/connections.js

@@ -19,7 +19,8 @@ Rerun --authorize if pending (exit 10). This never replaces recommendation keys.
 The management key is saved separately with owner-only file permissions.
 
 --config reads non-secret region, from (YYYY-MM-DD), tagPrefix, mappings and models.
-Supply LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY through a secret manager.
+For a new connection, supply LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY through
+a secret manager. Omit both to update settings using the saved Viewer key.
 --stdin reads the full JSON settings including the Viewer key pair from a protected
 pipe (maximum 18 KB), never echoes them, and does not save them locally.
 Never put keys in arguments, chat, shell history or a tracked file. Use a separate
@@ -67,6 +68,11 @@ async function settings(file, stdin, root) {
         throw new Error('Use non-secret settings in --config; credentials must come from a secret manager or --stdin.');
     if (!stdin)
         config = { ...config, publicKey: process.env.LANGFUSE_PUBLIC_KEY, secretKey: process.env.LANGFUSE_SECRET_KEY };
+    if (object(config) && !stdin && config.publicKey === undefined && config.secretKey === undefined) {
+        delete config.publicKey;
+        delete config.secretKey;
+        return config;
+    }
     if (!object(config) || typeof config.publicKey !== 'string' || typeof config.secretKey !== 'string' || !config.publicKey || !config.secretKey)
         throw new Error('Supply a separate Viewer key pair through a secret manager or --stdin.');
     return config;
@@ -139,7 +145,7 @@ export async function connection(args, { root = process.cwd(), print = console.l
     const value = await response.json();
     if (!object(value))
         throw new Error('OpenMerit returned an invalid connection response.');
-    const state = Object.fromEntries(Object.entries(value).filter(([name]) => ['connected', 'connectedAt', 'syncedAt', 'experiments', 'unmapped', 'results', 'busy', 'cached', 'deleted'].includes(name)));
+    const state = Object.fromEntries(Object.entries(value).filter(([name]) => ['connected', 'connectedAt', 'syncedAt', 'mappingCount', 'modelAliasCount', 'experiments', 'unmapped', 'results', 'busy', 'cached', 'deleted'].includes(name)));
     print(JSON.stringify(state, null, 2));
     return 0;
 }

package/dist/terminal/src/scout-instructions.js

@@ -87,14 +87,27 @@ application accuracy. Use the project's actual SDK and protocol.
 
 Each task also has an \`evaluation\`: the checks (per model call, agent run or
 end-to-end outcome), labelled examples per candidate and when to stop a losing
-candidate. Offer to run it before the user commits to a model. Use the evals the
-project already has, such as datasets and experiments in its eval or tracing
-platform, or its own eval scripts and fixtures: add the shortlisted candidates as
-extra runs of those evals. Do not build a second eval or copy their datasets.
-If the project has no eval for the task, propose a minimal one built from its
-existing traces and the decisions people already make, and create it only where
-and how the user agrees. Ask before spending on model calls or writing to an
-eval platform.
+candidate. Offer to run it before the user commits to a model. First assess the
+project's readiness for this task:
+
+- **No eval setup:** propose a customer-owned setup. Langfuse is the default
+  suggestion for its supported aggregate connector, not a requirement: existing
+  local/custom eval scripts can report aggregates without a hosted platform.
+  Phoenix/Arize and Braintrust are alternatives, not supported Scout connectors.
+  Ask which system the user wants before creating accounts or resources.
+- **Setup exists but evidence is insufficient:** keep that system. Write a
+  task-specific eval plan in the project's local Markdown decision record for
+  the user or their coding agent to implement. Name exact candidates/endpoints,
+  quality floor and task/agent/outcome checks, labelled boundary cases and
+  controls, sample size, early-stop rule, spend cap, aggregate mappings and
+  temporary run retention. Explain what the current evidence cannot decide.
+- **Suitable evals exist:** reuse their fixtures and definitions; add only the
+  approved candidate runs. Do not build a second eval or copy their datasets.
+
+OpenMerit does not host or run these evals. The customer or their coding agent
+implements and maintains them with the customer's tools; Scout keeps Viewer-only
+access. Ask before model spend or any platform write. Without measured evidence,
+Scout may suggest candidates, but do not claim validated model quality.
 
 Report what you measured with \`scout_models\`: the same \`conversationId\` and
 \`results\`, one aggregate per model and metric (\`level\`, \`task\` title, \`scope\`,
@@ -112,6 +125,25 @@ fixed. Use each agent's own checks to attribute failures. If all candidates scor
 100%, the eval cannot separate their quality: add harder labelled cases before
 claiming equivalent quality. Cost may break the observed tie, not prove equality.
 
+## Preserve evidence before cleanup
+
+Before removing temporary comparison runs, save a local Markdown decision record
+with the package/service versions, date, task and policy, exact candidates,
+unchanged controls, metric definitions/directions, sample counts, aggregate
+quality/cost/time, failures and exclusions, chosen model, limitations and next
+review. Record regret against the cheapest measured candidate meeting the same
+quality floor; write "not measurable" when comparable evidence is missing.
+Exclude secrets, private record IDs, prompts, outputs and trace bodies.
+
+Temporary comparison traces/records are not permanent: after the record is saved
+and checked, propose the exact newly created comparison runs to remove. Obtain
+explicit scoped approval, including any cascading deletion, before the customer
+or their coding agent deletes them with customer-controlled write access. Scout's
+Viewer key cannot do this. Never delete pre-existing customer records, reusable
+fixtures, dataset definitions or eval definitions. Verify the approved cleanup
+and retained controls, then record the outcome locally. If not approved, leave
+records unchanged and state cleanup is pending; do not imply it happened.
+
 If the user has Langfuse, use \`openmerit connect langfuse --help\`: the web UI is
 optional. Headless setup requires a separate connection-manager approval with
 \`openmerit connect langfuse --authorize --no-open\`. Relay its approval link and

package/docs/scout-close-loop.md

@@ -28,6 +28,32 @@ Each recommended model names an exact endpoint and provider model ID.
 
 ## Measure with your own evals
 
+**Eval-readiness and evidence guidance — npm 0.3.7 release preparation:** this
+package adds the readiness and cleanup workflow below to the installed Scout
+skill. Existing npm 0.3.6 instructions cover measuring and aggregate reporting,
+but do not yet prescribe all three readiness paths or an evidence-first cleanup
+record. Registry publication is separate from these source changes. This is
+guidance for the customer's coding agent, not an automated eval runner, platform
+provisioner or deletion service.
+
+### Choose the readiness path
+
+- **No eval setup.** Scout can still suggest candidates from public evidence;
+  that is not measured application quality. Propose a minimal customer-owned
+  eval setup and obtain approval before creating it. Langfuse is the default
+  suggestion because Scout has its aggregate connector. A hosted platform is
+  optional: customer-owned scripts and fixtures can report aggregates directly.
+  Phoenix/Arize and Braintrust are alternatives, not supported Scout connectors.
+- **A setup exists, but the evals are missing or too weak for model selection.**
+  Keep the existing system. Have the user or their coding agent write a local
+  task-specific Markdown eval plan with exact candidates/endpoints, quality floor,
+  task/agent/outcome checks, labelled boundary cases and controls, sample size,
+  early stopping, spend cap, aggregate mappings and temporary-run retention.
+  Review it before implementing it with the customer's tools. OpenMerit's access
+  remains Viewer-only; it does not install or maintain those evals.
+- **Suitable evals already exist.** Reuse their fixtures and definitions. Add
+  approved candidate runs rather than creating another dataset or platform.
+
 Add the shortlist as runs of your existing evals, not a second platform. Obtain
 approval before model spend or platform writes. For agents, change **one agent at
 a time** while holding the other models, prompts, tools, fixtures and controls
@@ -38,6 +64,34 @@ If every candidate scores 100%, the eval does not distinguish their quality.
 Add harder labelled boundary cases, rare failures and adversarial examples;
 cheaper on this test is not proof of equal quality in production.
 
+### Preserve evidence, then request cleanup
+
+Save a local Markdown decision record before removing temporary comparison data.
+Include the date, package and service versions, task and policy, exact candidates,
+unchanged controls, metric definitions and direction, sample counts, aggregate
+quality/cost/time, failures and exclusions, decision, limitations and next review.
+Exclude keys, private record identifiers, prompts, outputs and trace bodies.
+
+State cost regret in a consistent unit (for example USD per agent run): the
+chosen model's measured cost minus the cheapest measured candidate meeting the
+same quality floor on comparable evals. If there is no measured comparison,
+write **not measurable**, not zero. One success or all candidates scoring 100%
+on a tiny eval is not proof of equal production quality.
+
+Comparison records are temporary, but deletion is **not automatic**. After
+checking the saved evidence, propose the exact newly created comparison runs and
+any cascading deletions, then obtain explicit scoped approval. The customer or
+their coding agent performs cleanup using customer-controlled write access;
+Scout's Viewer key cannot delete Langfuse data. Never delete pre-existing customer
+records, reusable fixtures, dataset definitions or eval definitions. Verify that
+only the approved records disappeared and retained controls still exist. Record
+cleanup as pending when permission or verification is missing.
+
+Deleting platform runs, disconnecting Scout and deleting Scout's stored aggregates
+are separate operations. Disconnect does not erase past conversations or customer
+platform records. Keep enough permitted aggregate evidence locally to explain a
+later decision, without promising Scout can refresh a deleted source experiment.
+
 ## Report aggregates
 
 Report up to 50 aggregates per call, one per model, metric and scope. Use public
@@ -77,8 +131,10 @@ not promise that Scout stores or processes your data in that region.
 
 You can connect the key first with empty mappings. To import results, expand
 **Score and model mappings** and supply a start date, experiment-tag prefix,
-score mappings and model aliases. To change saved settings, disconnect and
-reconnect; this deletes the old imports, not reported results.
+score mappings and model aliases. In npm 0.3.6 with the matching Scout deployment,
+the headless paths below can update settings without re-entering the saved Viewer
+key. Changing settings invalidates old imports; sync again afterwards. Reported
+results remain. Older deployments require disconnecting and reconnecting.
 
 ### Headless CLI setup
 
@@ -124,6 +180,14 @@ openmerit connect langfuse --status
 openmerit connect langfuse --sync
 ```
 
+**Updating an existing connection (npm 0.3.6 and matching deployment):** edit the
+non-secret settings file and run the same `--config` command with both
+`LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` absent. Scout reuses and reverifies
+the encrypted Viewer key internally; neither CLI nor model receives it. One key
+without the other is rejected. Without a connected key, first connect through a
+protected credential path. Settings changes remove prior imports, not reported
+results, and require a new sync.
+
 Alternatively, `openmerit connect langfuse --stdin` reads a full JSON object with
 the same settings plus `publicKey` and `secretKey` from a protected pipe, up to
 18 KB. It does not echo or save the Viewer credentials locally. Do not use inline
@@ -155,6 +219,12 @@ records these headers. If your MCP client cannot securely inject headers outside
 model context, have the agent invoke the CLI with protected input instead, or
 use the web UI; do not fall back to putting credentials in tool arguments.
 
+On the matching 0.3.6 deployment, omit both Viewer headers to update an existing
+connection using its saved encrypted key. A new connection still needs both.
+The authenticated HTTP POST similarly accepts non-secret settings without either
+key field for an existing connection. The saved key is never exported. Settings
+changes reverify Viewer access and invalidate imported results before a new sync.
+
 ```json
 {"action": "configure", "config": {"region": "us", "from": "2026-11-01", "tagPrefix": "experiment:", "mappings": [], "models": {}}}
 ```
@@ -219,8 +289,16 @@ read per sync. Narrow the date if a response or import exceeds its limit. Only
 experiment headers/metadata and aggregate Metrics v2 reads are requested. A
 deliberately invalid dataset-create request checks read-only permission without
 ever sending a valid write payload. Only an authenticated read followed by HTTP
-403 on that probe is accepted; other responses fail closed. Actual Viewer-key
-acceptance remains pending the release check.
+403 on that probe is accepted; other responses fail closed. Live Viewer-key
+connection acceptance, one fresh mapped aggregate import and measured reranking
+were verified on 6 November 2026 with npm 0.3.6 and the matching deployments.
+This one-sample plumbing check is not comparative quality acceptance. Two new
+conversations received the aggregate but returned prose before the 6 November
+structured-completion deploy. After it, three fresh published-CLI conversations
+returned five structured tasks each, reused the measured coding result without
+resending it and retained the one-sample caveat. This focused check does not
+establish fresh-coding-agent usability; full fresh-agent and two-release
+acceptance remain open.
 
 Click **Sync aggregates**, or request a fresh recommendation with:
 
@@ -233,6 +311,26 @@ failed read cannot be retried for one minute. A failed import leaves the previou
 complete set intact. `conversationId` alone reads a saved answer, not a rerank;
 send a follow-up or `sync` to recompute with the current results.
 
+### When a sync imports zero aggregates
+
+A connected Viewer key and a successful experiment read do not establish that
+score import is configured. Empty mappings are allowed when first connecting.
+Before repeating sync, check the score mappings and model aliases, then check
+that scored traces carry the exact experiment tag, trace name and metric name
+in those mappings. Merely linking a trace through Langfuse's native experiment
+attributes does not add the explicit experiment tag required by this connector.
+Do not remove the tag filter to make an import nonempty: that can combine scores
+from different models or runs. Untagged historical results need attributable
+aggregate reporting or a separately approved, verified tagging backfill.
+
+**Diagnostic version requirement:** a matching Scout serving deployment adds
+`mappingCount` and `modelAliasCount` to connection status, without returning the
+saved keys or mapping values. The web page distinguishes a connected key from
+incomplete setup and warns when a sync imports no matching scores. npm 0.3.5
+does not display these new counts; use authenticated API/MCP status until a
+matching CLI patch is published. These counts diagnose missing configuration,
+not whether matching scores exist or whether a model improves quality.
+
 ## Choose and delete
 
 Check measured quality, the quality floor, price calibration and limitations

package/docs/scout.md

@@ -20,6 +20,32 @@ Scout is a separate hosted beta product. Npm 0.1.7 introduced optional Claude Co
 
 ## Evaluation plans and measured results — deployed 5 November 2026, npm 0.3.1
 
+**Rank-aligned summaries — deployed 6 November 2026:** after filtering and ranking,
+Scout builds each nonempty task summary from the first model's name, rationale
+and caveat. A summary written before sorting could previously name a different
+leader, particularly after measured evidence or measured cost changed the order.
+Ranking and quality scores are unchanged. One measured success still does not
+establish superiority over untested candidates. Scout serving version
+`86d43d6c-e60f-4989-be50-9461d48f37cf` passed a live published-CLI check: all five
+task summaries matched their final first model, including measured coding review.
+Past saved answers do not change until the conversation is recomputed. Fresh
+conversations returned prose rather than validated shortlists in two acceptance
+runs before the structured-completion deployment below. A prose fallback is not
+a successful structured recommendation.
+
+**Structured completion recovery — deployed 6 November 2026:** when the model ends a
+turn with prose before an answer tool accepts a clarification or all planned
+shortlists, Scout continues the same durable run at most twice. Recovery keeps
+accepted task shortlists and names the remaining tasks; it does not bypass
+catalogue, evidence, scope or quality validation. The attempt budget survives
+object eviction and resets only for a new user turn. An already accepted answer
+adds no model call. If recovery is exhausted, the existing prose/error fallback
+remains explicitly unstructured; provider failures do not start completion
+recovery. PR #83 passed all PR/main CI checks and deployed Scout serving version
+`fe34446b-528c-4b90-b0a0-60946caa0d78` at 09:38 UTC. Landing, Scout, connection,
+status and version endpoints returned HTTP 200. Fresh-conversation acceptance is
+separate from deployment health and is required before this release gate closes.
+
 The Scout serving deploy of 5 November 2026 (version `ea371c78-6ccf-4931-a0b8-aa28a6599aaa`) serves this behavior to every client. A live MCP check returned an evaluation plan and agent grouping, and reported results moved a measured model below the quality bar. npm 0.3.1 adds `openmerit scout --results` and the installed instructions for measuring; older installations reach the new `scout_models` fields through MCP but their instructions do not mention measuring until the installer is rerun.
 
 OpenMerit does not run evaluations or host an eval platform. Scout tells you what to measure, your own eval system measures it, and Scout uses the aggregate results:

package/docs/security.md

@@ -12,14 +12,15 @@ OpenMerit accepts no model-provider or Jev credential. Credentials belong to the
 
 Never place secrets in evaluation configuration, task fixtures, Scout project policy, traces, or committed environment files.
 
-### Langfuse connector (unreleased)
+### Langfuse connector
 
-The [connection guide](scout-close-loop.md#connect-langfuse) describes the source
-implementation, not npm 0.3.4 or a deployed acceptance result. Only a separate
+The [connection guide](scout-close-loop.md#connect-langfuse) requires npm 0.3.5
+and the matching hosted deployment. Only a separate
 Viewer key pair is accepted. A successful read plus a deliberately invalid
 dataset-create permission probe (HTTP 403 required) fails closed for Full keys;
-no valid write payload is sent. Positive Viewer-key acceptance still needs a real
-Viewer key. Fixed US/EU/HIPAA hosts, manual redirects, timeouts and bounded reads
+no valid write payload is sent. Live Viewer connection acceptance was verified
+on 6 November 2026; fresh mapped import/reranking remain separate release gates.
+Fixed US/EU/HIPAA hosts, manual redirects, timeouts and bounded reads
 prevent credential forwarding and unbounded response bodies. The connector reads
 only experiment headers/metadata and aggregate Metrics v2 values, never trace,
 observation, experiment-item or raw-score bodies. Extra metadata fields are
@@ -29,6 +30,10 @@ Credentials and mappings are AES-GCM encrypted in one Cloudflare Durable Object
 per authenticated user, bound to that object's ID with a dedicated Worker secret.
 Keys never enter browser storage, URLs or analytics. Keep that encryption secret
 stable: replacing it invalidates stored connections and requires reconnecting.
+With npm 0.3.6 and the matching deployment, authenticated settings-only updates
+reuse and reverify the saved encrypted key without exporting it. Supplying a
+partial key pair fails; first connection still requires a protected Viewer pair.
+Changing settings invalidates imported aggregates and requires syncing again.
 Disconnect deletes the key and imported aggregates; deleting all evaluation data
 also deletes reported aggregates. Neither erases conversation text. Retention,
 limits and processor caveats are in the [data policy](scout-data-policy.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmerit",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Evidence-driven model decisions for coding harnesses.",
   "type": "module",
   "bin": {