dsh-molbio-tools 0.22.0 → 0.22.1

package/CHANGELOG.md

@@ -10,6 +10,79 @@
   改为按**包名**引用后模块缓存问题随之消失——没有拷贝，也就没有需要保持同步的版本目录。
   下文历史条目里出现的 `vN` 目录保持原样，作为当时的记录。
 
+## [0.22.1] — 2026-10-25（PubMed key 改走 DSH 凭据库；环境变量降为后备）
+
+**工具数不变（60）；没有凭据库的组合，行为与 0.22.0 相同。** 0.22.0 只从 `api_key` 参数与
+`process.env` 读 key；这一版把 DSH 的凭据 seam（`ctx.credentials`）插到两者之间，并把环境变量
+降为最后一级。
+
+### 1. 环境变量为什么不够好
+
+环境变量会被**每个子进程继承**——包括 agent 自己的 shell 工具：一句 `echo $env:NCBI_API_KEY`
+就能把 key 读进对话；它还会出现在进程环境块、崩溃转储与用户的注册表环境里（Windows 的
+`HKCU\Environment` 是明文）。对任何云端凭证这都是不必要的暴露面；NCBI 的 key 虽然只用于
+归属与限速，泄漏仍意味着别人可以用你的配额、顶着你的身份发请求。
+
+DSH 自带的凭据库（`@deepseek-ai/dsh-credentials-local`）就是为这件事存在的：值存在
+`~/.dsh/.credentials.yaml` 里，**不注入环境**、文件仅属主可读、改动热重载，
+`describe()` 只报告是否已设置与来源、从不回显值，而且**存储值优先于启动环境**。
+
+### 2. 新的解析顺序
+
+| 优先级 | 来源 | 说明 |
+| --- | --- | --- |
+| 1 | `api_key` 参数 | 单次调用显式指定；会出现在对话记录与工具卡片里 |
+| 2 | 凭据库 `NCBI_API_KEY` | 推荐；不进入环境，agent 的 shell 子进程读不到 |
+| 3 | 凭据库 `MOLBIO_NCBI_API_KEY` | 同上，插件专用命名 |
+| 4 | 进程环境 `NCBI_API_KEY` / `MOLBIO_NCBI_API_KEY` | 兼容 0.22.0 的用法；暴露面最大 |
+
+实现上调用 `ctx.credentials.resolve(ref)`（存在性检查后才调用），因此凭据库自身的回退层
+（启动环境、项目 `.env`、harness home 的 `.env`）也一并继承；provider 不存在或拒绝该引用时
+**静默回退到 `process.env`**，没有凭据库的组合行为不变。
+
+### 3. key 放进凭据库的三种方式
+
+1. **插件详情页（推荐）**：插件 → 已安装插件 → `dsh-molbio-tools` → **PubMed API key** 一节，
+   粘贴后点 **Save**；见 §4。
+2. 编辑 `~/.dsh/.credentials.yaml`（产品创建、仅属主可读、热重载）：在 `refs:` 下加一行
+   `NCBI_API_KEY: 你的key`；下一次工具调用即生效，无需重启。
+3. 在 DSH 的设置界面保存同名凭据（该界面只显示“是否已设置/来源”，不显示值）。
+
+> **这不是对 agent 的硬隔离。** 凭据库自己的文档写得很清楚：agent 的工具进程以同一个 OS 用户
+> 运行，刻意去读那个文件仍然读得到。它解决的是**自动泄漏**：环境变量会被每个 shell 子进程
+> 无条件继承，而凭据库不会。真正要把密钥挡在 agent 之外，需要换提供方（OS 钥匙串/KMS），
+> 当前产品没有随附这类 provider。
+
+### 4. 图形入口：插件详情页里的 PubMed API key
+
+「改 YAML」对没有计算机基础的用户不是可接受的入口。浏览器半因此注册了一个
+`plugins.detail.section` 条目（`id: molbio-ncbi-key`），只在**本包的 bundle 页**与它声明的**行页**
+上渲染，其它插件返回 `null`：
+
+- 输入框是 `type=password`，只写不读；状态行来自 `ctx.remote.credentials.describe(['NCBI_API_KEY'])`，
+  只显示「已配置 / 未配置 / 来源」，**不回显值**。
+- **Save** 走 `ctx.remote.credentials.set('NCBI_API_KEY', value)`，**Remove** 走 `unset`；
+  保存后输入框立即清空，成功/拒绝消息原样显示（`credential/rejected` 的 provider 原文）。
+- 它和 CLI/工具读的是**同一个**凭据引用，所以两边不需要同步；没有凭据 provider 的部署会显示
+  Unavailable，而工具仍按 §2 的顺序回退到环境变量。
+
+> **测试中发现并修掉的一处真实缺陷（同一版内）**：第一版把 `ctx.remote.credentials` 当成普通
+> 属性直接访问，而它是 **fiber injection**——官方设置页在 `inject` 列表里显式声明
+> `remote.credentials`。没有声明时该命名空间是 `undefined`，点 Save 什么也不会写（状态看起来
+> 只是"没保存"）。现在整段的注册被 `ctx.inject(['remote.credentials'], …)` 门控：有命名空间才
+> 出现，没有则整段不注册（面板不受影响）；写入之后还会重新 `describe`，若 Host 仍报"未配置"
+> 会把这句话显示出来，而不是假装成功。
+
+### 5. 边界与验证
+
+- 默认路径（无 key）仍是 web 检索；有 key 仍是 esearch + esummary + efetch，速率上限不变。
+- 客户端产物因此变了：`lib/client.js` 与 `packages/molbio-panel/lib/client.js` 重新构建，
+  面板包 `0.1.5 → 0.1.6`。
+- smoke 新增三条：**凭据库压过环境变量**、**显式参数压过凭据库**、**provider 抛错时回退到环境**；
+  原有的“无 key 不碰 E-utilities”与“坏 key 报错”保留。`test/client.mjs` 新增详情页座位的
+  等待/注册、本包 subject 渲染、其它 subject 返回 null，以及凭据视图/失败信息三个纯函数。
+- `npm test` 全绿；`client-bundle.mjs --check` 与 `preset-patch.mjs --check` 与源一致。
+
 ## [0.22.0] — 2026-10-25（DSH 0.2.1-rc.3 适配；PubMed 官方 API + NCBI API key）
 
 **工具数不变（60）。新增一条通路：`molbio_pubmed_search` / `molbio_pubmed_abstract` 可以带着

package/README.md

@@ -55,6 +55,10 @@
    装完点 **立即启用**（Enable now）——关掉对话框只会装好、不会启用，之后也可以在插件页打开它的开关。
 3. 重启该 profile，然后在预设选择器里选 "Molecular Biology Lab" 新建会话。
 
+**（可选）PubMed API key**：重启后打开 **插件 → 已安装插件 → `dsh-molbio-tools` 详情页**，
+在 **PubMed API key** 一节粘贴 NCBI key 并点 **Save**。它写进 DSH 凭据库（`~/.dsh/.credentials.yaml`），
+不需要编辑文件、也不进环境变量，下一次检索即生效。没有 key 时检索仍走原来的 web 检索。
+
 ### 次选：命令行安装
 
 没有图形界面时（例如服务器上只用 CLI），用这条命令；它和插件页安装等价，都从 npm registry 取包：
@@ -224,7 +228,7 @@ dsh plugin --profile <profile> add dsh-molbio-panel
 
 | 工具 | 用途 |
 | --- | --- |
-| `molbio_pubmed_search` | 搜 PubMed 文献。提供 NCBI API key（`api_key` 参数，或环境变量 `NCBI_API_KEY` / `MOLBIO_NCBI_API_KEY`）时走**官方 E-utilities**（esearch + esummary），返回 PMID/标题/期刊/年份/作者/DOI；无 key 时回退到 harness 的 web 检索 |
+| `molbio_pubmed_search` | 搜 PubMed 文献。提供 NCBI API key（`api_key` 参数、**DSH 凭据库**的 `NCBI_API_KEY`、或环境变量）时走**官方 E-utilities**（esearch + esummary），返回 PMID/标题/期刊/年份/作者/DOI；无 key 时回退到 harness 的 web 检索 |
 | `molbio_pubmed_abstract` | 按 PMID 拉取摘要（efetch；同样支持 NCBI API key，依赖部署提供 web fetch 能力） |
 | `molbio_paper_add` / `molbio_paper_list` / `molbio_paper_update` / `molbio_paper_remove` | 阅读库（工作区 `papers.json`）：加/列/改/删，按 PMID→URL→标题+年份去重 |
 | `molbio_paper_export_bibtex` | `papers.json` → BibTeX `.bib`（可按 tag 过滤） |
@@ -557,10 +561,16 @@ mutations remain deferred"）。所以插件无法在工作区里合法地落一
 
 - 检索与摘要走 harness 的 **web** 服务（部署不提供时工具会明确报错，而不是假装搜到）。
 - 提供 NCBI API key 时，`molbio_pubmed_search` 用官方 E-utilities：esearch 拿 PMID、esummary
-  拿题录（标题/期刊/年份/作者/DOI），`molbio_pubmed_abstract` 用 efetch 拿摘要。key 的来源优先级是
-  `api_key` 参数 > `NCBI_API_KEY` > `MOLBIO_NCBI_API_KEY`；**长期使用请用环境变量**，内联传参会让 key
-  出现在对话记录与工具卡片里。NCBI 的速率上限是**无 key 3 次/秒、有 key 10 次/秒**，一次带 key 的
-  检索是 2 个请求（esearch + esummary）。没有 key 时检索仍走原来的 web 检索通路，行为不变。
+  拿题录（标题/期刊/年份/作者/DOI），`molbio_pubmed_abstract` 用 efetch 拿摘要。key 的解析顺序是
+  **`api_key` 参数 → DSH 凭据库（`NCBI_API_KEY`，其次 `MOLBIO_NCBI_API_KEY`）→ 进程环境变量**。
+  NCBI 的速率上限是**无 key 3 次/秒、有 key 10 次/秒**，一次带 key 的检索是 2 个请求
+  （esearch + esummary）。没有 key 时检索仍走原来的 web 检索通路，行为不变。
+- **优先把 key 放凭据库，而不是环境变量。** 凭据库是 `~/.dsh/.credentials.yaml`（`refs:` 下写
+  `NCBI_API_KEY: …`；图形入口是**插件 → 已安装插件 → dsh-molbio-tools → PubMed API key**）：
+  不进环境、仅属主可读、改完热重载、下一次调用即生效。环境变量会被**每个子进程继承**——包括 agent 自己的 shell 工具，`echo $env:NCBI_API_KEY`
+  就能读出来，而且明文存在用户环境里；内联 `api_key` 还会进入对话记录与工具卡片。
+  > 凭据库不是对 agent 的硬隔离（agent 与你是同一个 OS 用户，刻意去读文件仍可能），但它消除了
+  > 「所有 shell 子进程自动继承」这条泄漏路径——这正是环境变量的主要问题。
 - 阅读库/协议库/实验日志是工作区里的 `papers.json` / `protocols.json` / `experiments.json`，
   写入遵循会话的**沙箱政策**，与其它文件工具同权；面板（Papers tab）直接读 `papers.json`。
 - `molbio_paper_export_bibtex` 可选按 tag 过滤导出。
@@ -655,10 +665,12 @@ node <包目录>\preset\install.mjs --profile web --check  # 只报告，不组
 `amplicon_min/max` 或 `tm_min/max` 放宽一点即可。
 
 **PubMed 的 API key 怎么配？**
-在启动 DSH 的环境里设 `NCBI_API_KEY`（或 `MOLBIO_NCBI_API_KEY`），插件会自动把它带进 E-utilities 请求；
-也可以在单次调用里传 `api_key`。有 key 时 `molbio_pubmed_search` 走官方 API（PubMed 自己的题录，
-含 DOI），没有 key 时仍走 harness 的 web 检索。注意：**内联传的 key 会出现在对话记录和工具调用卡片里**，
-长期用请设环境变量。
+推荐用**插件详情页**：插件 → 已安装插件 → `dsh-molbio-tools` → **PubMed API key**，粘贴后点 Save
+（写入 DSH 凭据库的 `NCBI_API_KEY`，不进环境变量，下一次检索生效）。也可以手动在
+`~/.dsh/.credentials.yaml` 的 `refs:` 下加一行 `NCBI_API_KEY: 你的key`。
+也可以用环境变量 `NCBI_API_KEY`，或在单次调用里传 `api_key`，但两者都更容易泄漏：**环境变量会被
+agent 的 shell 子进程继承**，内联参数会出现在对话记录与工具卡片里。有 key 时走官方 E-utilities
+（PubMed 自己的题录，含 DOI），没有 key 时仍走 harness 的 web 检索。
 
 **"帮我把这段序列分析一下" 它却问我要参数？**
 把目标说具体即可：要引物还是探针、产物多长、Tm 多少、哪个区域。工具默认值都是常规实验条件

package/build/client-entry.mjs

@@ -32,8 +32,12 @@
 import { createElement as h, useEffect, useMemo, useRef, useState } from 'react';
 import {
   LIBRARY_FILE,
+  NCBI_KEY_REF,
   childPath,
   classifyEntry,
+  credentialInfo,
+  isMolbioDetailSubject,
+  remoteFailure,
   decodeWorkspaceBytes,
   filterPapers,
   isOpenable,
@@ -489,6 +493,142 @@ function PapersPanel({ sessionId, remote, useSessions }) {
     h('div', { style: styles.main }, ...detail));
 }
 
+/** The state of the PubMed key, read from the host's credential store. */
+async function readNcbiKey(remote) {
+  if (remote?.credentials === undefined || typeof remote.credentials.describe !== 'function') {
+    return { phase: 'error', configured: false, writable: false, message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' };
+  }
+  let response;
+  try {
+    response = await remote.credentials.describe([NCBI_KEY_REF]);
+  } catch (error) {
+    response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+  }
+  const failure = remoteFailure(response);
+  if (failure !== '') return { phase: 'error', configured: false, writable: false, message: failure };
+  return { phase: 'ready', ...credentialInfo(response, NCBI_KEY_REF), message: '' };
+}
+
+const keyStyles = {
+  section: { borderTop: '1px solid rgba(127, 127, 127, 0.28)', marginTop: 16, paddingTop: 12, display: 'grid', gap: 8 },
+  title: { margin: 0, fontSize: 14 },
+  note: { margin: 0, fontSize: 12, opacity: 0.75, lineHeight: 1.5 },
+  status: { margin: 0, fontSize: 12 },
+  row: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
+  input: { flex: '1 1 240px', minWidth: 200, padding: '4px 8px' },
+  message: { margin: 0, fontSize: 12 },
+};
+
+/**
+ * The Plugins → installed plugin → detail section that stores the NCBI key.
+ *
+ * It renders only for this package's own subject (bundle page, or one of the
+ * row pages the bundle declares) and returns null everywhere else, which is the
+ * contract `plugins.detail.section` asks a contribution to honour. The value is
+ * write-only from here: `credentials.describe` answers whether a key is
+ * configured and where it came from, never the key itself.
+ */
+function NcbiKeySection({ subject, remote }) {
+  const [draft, setDraft] = useState('');
+  const [state, setState] = useState({ phase: 'loading', configured: false, writable: true, message: '' });
+  const subjectToken = isMolbioDetailSubject(subject)
+    ? `${subject.kind}:${subject.pkg.name}:${subject.row?.rowId ?? ''}`
+    : '';
+  useEffect(() => {
+    if (subjectToken === '') return undefined;
+    let live = true;
+    const load = () => readNcbiKey(remote).then((next) => { if (live) setState(next); });
+    load();
+    // Another surface may rotate or clear the same reference (Settings, the
+    // file watcher); follow the host event instead of showing a stale badge.
+    const off = typeof remote?.$on === 'function'
+      ? remote.$on('credentials/reference-updated', (ref) => { if (ref === NCBI_KEY_REF) load(); })
+      : undefined;
+    return () => {
+      live = false;
+      if (typeof off === 'function') off();
+    };
+  }, [remote, subjectToken]);
+  if (!isMolbioDetailSubject(subject)) return null;
+  const busy = state.phase === 'saving';
+  const save = async () => {
+    const value = draft.trim();
+    if (value === '') return;
+    if (remote?.credentials === undefined || typeof remote.credentials.set !== 'function') {
+      setState((previous) => ({ ...previous, phase: 'error', message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' }));
+      return;
+    }
+    setState((previous) => ({ ...previous, phase: 'saving', message: '' }));
+    let response;
+    try {
+      response = await remote.credentials.set(NCBI_KEY_REF, value);
+    } catch (error) {
+      response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+    }
+    const failure = remoteFailure(response);
+    setDraft('');
+    const next = await readNcbiKey(remote);
+    setState(failure !== ''
+      ? { ...next, phase: 'error', message: failure }
+      : next.phase === 'error'
+        ? next
+        : next.configured === true
+          ? { ...next, message: 'Saved. The next PubMed call uses this key.' }
+          : { ...next, phase: 'error', message: 'The host accepted the write but still reports no key configured. Restart the profile and try again.' });
+  };
+  const remove = async () => {
+    if (remote?.credentials === undefined || typeof remote.credentials.unset !== 'function') {
+      setState((previous) => ({ ...previous, phase: 'error', message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' }));
+      return;
+    }
+    setState((previous) => ({ ...previous, phase: 'saving', message: '' }));
+    let response;
+    try {
+      response = await remote.credentials.unset(NCBI_KEY_REF);
+    } catch (error) {
+      response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+    }
+    const failure = remoteFailure(response);
+    const next = await readNcbiKey(remote);
+    setState(failure !== ''
+      ? { ...next, phase: 'error', message: failure }
+      : next.phase === 'error'
+        ? next
+        : next.configured === false
+          ? { ...next, message: 'Removed. PubMed search falls back to web search.' }
+          : { ...next, phase: 'error', message: 'The host still reports a key configured after Remove.' });
+  };
+  const status = state.phase === 'loading'
+    ? 'Checking the credential store…'
+    : state.phase === 'error'
+      ? 'Unavailable'
+      : state.configured
+        ? `Configured${state.source === undefined ? '' : ` (source: ${state.source})`}`
+        : 'Not configured';
+  return h('section', { 'data-molbio-ncbi-key': '', style: keyStyles.section },
+    h('h4', { style: keyStyles.title }, 'PubMed API key'),
+    h('p', { style: keyStyles.note }, 
+      'Stored in the harness credential store. molbio_pubmed_search and molbio_pubmed_abstract use it for the official PubMed E-utilities API; without it they fall back to web search.'),
+    h('p', { 'data-molbio-key-status': state.phase, style: keyStyles.status }, status),
+    h('div', { style: keyStyles.row },
+      h('input', {
+        type: 'password',
+        value: draft,
+        placeholder: 'NCBI API key (36 characters)',
+        autoComplete: 'off',
+        spellCheck: false,
+        'aria-label': 'NCBI API key',
+        style: keyStyles.input,
+        onChange: (event) => setDraft(event.target.value),
+      }),
+      h('button', { type: 'button', disabled: busy || state.writable === false || draft.trim() === '', onClick: save },
+        busy ? 'Saving…' : 'Save'),
+      h('button', { type: 'button', disabled: busy || state.writable === false || state.configured !== true, onClick: remove }, 'Remove')),
+    state.message === '' ? null : h('p', { 'data-molbio-key-message': '', role: 'status', style: keyStyles.message }, state.message),
+    h('p', { style: keyStyles.note },
+      'Create a key under NCBI → Account Settings → API Key Management. Prefer this over an environment variable: the store is not inherited by shell commands.'));
+}
+
 /** Required browser services. */
 const inject = ['slots', 'sidebarRightTabs', 'remote'];
 
@@ -572,6 +712,25 @@ function apply(ctx) {
       key: toolName,
     }, MolbioMapCard)), `molbio panel: ${toolName} card`);
   }
+  // Plugins -> the installed plugin's detail page: the one place a user can
+  // store the NCBI key without editing a YAML file or exporting a variable.
+  //
+  // `remote.credentials` is a FIBER INJECTION, not merely a property on the
+  // Remote carrier: the shipped settings pages declare it in `inject` for the
+  // same reason. Without the declaration `ctx.remote.credentials` is undefined,
+  // which is exactly how the first build of this section made Save a no-op.
+  // The gate keeps the panel working in deployments that expose no credentials
+  // namespace: the section simply never registers there.
+  ctx.effect(() => {
+    const gate = ctx.inject(['remote.credentials'], (keyCtx) => {
+      keyCtx.effect(() => keyCtx.slots.inject('plugins.detail.section', () => keyCtx.slots.register({
+        name: 'plugins.detail.section',
+        id: 'molbio-ncbi-key',
+        order: 100,
+      }, (props) => h(NcbiKeySection, { ...props, remote: keyCtx.remote }))), 'molbio panel: NCBI key section');
+    });
+    return () => { gate.dispose(); };
+  }, 'molbio panel: NCBI key section gate');
 }
 
 export { apply, inject };

package/build/panel-core.mjs

@@ -390,3 +390,41 @@ export function paperLink(paper) {
   if (typeof paper.pmid === 'string' && paper.pmid !== '') return `https://pubmed.ncbi.nlm.nih.gov/${paper.pmid}/`;
   return undefined;
 }
+
+/** The credential reference the PubMed tools read first. */
+export const NCBI_KEY_REF = 'NCBI_API_KEY';
+
+/**
+ * Whether a Plugins-page detail subject is this package's own entry.
+ *
+ * Bundles and rows both expose `pkg.name`; the key section is offered on the
+ * bundle page and on every row page the bundle declares, and on nothing else.
+ */
+export function isMolbioDetailSubject(subject) {
+  if (subject === null || typeof subject !== 'object') return false;
+  if (subject.kind !== 'bundle' && subject.kind !== 'row') return false;
+  const pkg = subject.pkg;
+  return pkg !== null && typeof pkg === 'object' && pkg.name === 'dsh-molbio-tools';
+}
+
+/**
+ * The host failure message carried by a Remote result, or '' on success.
+ * Remote calls answer `{ ok: true, value }` or `{ ok: false, error }`.
+ */
+export function remoteFailure(response) {
+  if (response === null || typeof response !== 'object' || response.ok !== false) return '';
+  const message = response.error?.message;
+  return typeof message === 'string' && message !== '' ? message : 'the host refused the request';
+}
+
+/** One reference's view from a `credentials.describe` response (never the value). */
+export function credentialInfo(response, ref) {
+  const view = response !== null && typeof response === 'object' && response.ok !== false
+    ? response.value?.[ref]
+    : undefined;
+  return {
+    configured: view?.configured === true,
+    writable: view?.writable !== false,
+    ...typeof view?.source === 'string' && view.source !== '' ? { source: view.source } : {},
+  };
+}

package/docs/client-panel.md

@@ -13,6 +13,7 @@
 | **Molbio**（右栏 tab） | 列出会话工作区里的序列文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图 | `workspaceFiles.readAll`（二进制，含 SnapGene） |
 | **Papers**（右栏 tab） | 把 `molbio_paper_*` 工具维护的 `papers.json` 渲染成可搜索的阅读列表 + 详情面板（标题/作者/期刊/年份/PMID/URL/标签/笔记，标题链接到 PubMed 或原 URL） | `workspaceFiles.read`（文本） |
 | **图谱调用卡**（`tool.call.toolview`） | `molbio_plasmid_map` / `molbio_plasmid_map_file` 的调用卡：在对话里直接画出这次调用产出的图谱（摘要行 + 写入路径），失败时显示错误文本与 Inspect 入口 | 工具自己声明的 `output.presentationMeta`（见下） |
+| **PubMed API key**（`plugins.detail.section`） | 插件 → 已安装插件 → `dsh-molbio-tools` 详情页里的一段表单：password 输入 + Save/Remove，状态只报「已配置 / 来源 / 未配置」，永不回显值 | `ctx.remote.credentials.describe` / `set` / `unset`（host 的凭据 seam） |
 
 **解析与渲染全部在浏览器里跑本仓库自己的模块**（`lib/genbank/snapgene/plasmid/msa/logo`），
 不经过任何工具调用、不落盘 SVG、不弹系统查看器。
@@ -46,7 +47,7 @@ SVG 随 meta 传输有上限（256 KB）：真实载体的图谱 20-60 KB，但
 | `build/client-bundle-core.mjs` | 打包器的**生成逻辑**（可 import）：`createGenerator({entry, baseDir})` → 模块图 + `renderBundle(packageName)`；`test/contract.mjs` 在进程内用它重算产物做新鲜度检查（不 spawn，受限沙箱下也能验证） |
 | `build/browser-api.mjs` | 浏览器安全面：从**包根的 `.mjs` 源文件**再导出面板可用的一切（单一事实来源） |
 | `build/panel-core.mjs` | 面板的数据通路（分类/解码/解析/渲染/文献库投影），不含 React，可在 Node 里单测 |
-| `build/client-entry.mjs` | 浏览器半本体：两个 tab 类型的注册、正文、标题 chip，以及两个 map 工具的调用卡 |
+| `build/client-entry.mjs` | 浏览器半本体：两个 tab 类型的注册、正文、标题 chip，两个 map 工具的调用卡，以及插件详情页的 key 配置段 |
 | `lib/client.js` | **构建产物**（`exports["./client"]` 指向它；由 `npm run build:client` 生成） |
 | `packages/molbio-panel/` | 面板专用包（宿主半边空实现），面板与 57 个工具解耦的交付通道 |
 | `test/client.mjs` | 按加载器的方式执行产物 + 驱动两条数据通路（含真实 pUC118 夹具） |
@@ -131,6 +132,14 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
 - **图片式交互**：SVG 里注入的是真实 DOM（可缩放、可选中文本），但没有点特征跳转之类的联动。
 - **CSS 内联**：产物刻意不注入样式表——`factory` 里的样式副作用要自己管拆除；
   内联样式让产物保持单文件、零生命周期负担。
+- **key 配置段只在「本包」的详情页出现**：`plugins.detail.section` 是 list 座位，条目自己判断
+  `subject`；本包只在 `kind: bundle|row` 且 `pkg.name === 'dsh-molbio-tools'` 时渲染，其它插件页
+  返回 `null`。它依赖宿主挂载了凭据 provider（默认组合都有）：没有时整段通过
+  `ctx.inject(['remote.credentials'], …)` 门控而不注册，工具仍会按「参数 → 凭据库 → 环境变量」
+  的顺序回退，不会因此不可用。**`remote.credentials` 是 fiber injection，不是普通属性**：
+  官方设置页同样在 `inject` 里声明它；第一版漏了这一步，`ctx.remote.credentials` 是 `undefined`，
+  点 Save 什么也没写（0.22.1 测试中发现并修掉）。**输入框只写不读**：`describe` 的返回里没有值，
+  保存成功后输入框立即清空；写后仍报未配置、或 Remove 后仍报已配置，都会把不一致显示出来。
 - **每次改源都要重新构建**：`lib/client.js` 是**产物**，改了根 `.mjs` 或 `build/*.mjs` 后
   必须重跑 `npm run build:client`，否则面板还跑旧逻辑（这与 preset 的"版本目录"规则是
   两码事：客户端产物靠 `rev` 哈希缓存失效，不靠目录名）。
@@ -146,9 +155,11 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
    `guide`、无 `patterns`、guide `order` 40/41）、四个 keyed 座位的注册、两个正文的 `inject`
    工厂都只交出 `remote`。座位那一层从**一个座位都没声明**的最坏顺序启动（`test/slots-stub.mjs`
    复刻 shell 的 SlotCore 语义）：`apply()` 必须不抛；右栏座位声明后四条注册落地；调用卡座位在
-   ui-tool 声明之前一直**处于等待**、声明之后才落地；重声明不产生重复注册；并当场复刻
-   "未声明座位 `register()` 必抛"的那条 SlotCore 异常——0.7.1 把整个 GUI 卡在
-   "Failed to load plugins" 的就是它。
+   ui-tool 声明之前一直**处于等待**、声明之后才落地；插件详情页座位同样先等待、后注册；重声明
+   不产生重复注册；并当场复刻 "未声明座位 `register()` 必抛"的那条 SlotCore 异常——0.7.1 把整个
+   GUI 卡在 "Failed to load plugins" 的就是它。key 段还断言了：本包 subject 渲染出
+   `section` + password 输入 + Save，其它包的 subject 返回 `null`，以及凭据视图/失败信息
+   三个纯函数（`isMolbioDetailSubject` / `credentialInfo` / `remoteFailure`）。
 3. **组件行为**：`test/panel-render.mjs` 把**真实的面板组件**放进 Node 跑——没有 React
    （harness 里有，浏览器里的 React 由 shell 播种）也没有 DOM，所以这个文件自带一套最小
    钩子宿主（`createElement`/`useState`/`useEffect`/`useMemo`/`useRef`，语义与 React 一致：
@@ -159,7 +170,9 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
    列目录失败的错误态、文献库的列表/搜索/标签过滤/详情/PubMed 链接回退、空库提示、坏库
    报错（**不显示成"空库"**）、以及卸载时中止在途读取。
    这一层抓到过三个真 bug：列表把不可打开的文件也列出来、`sortEntries` 的 `other` 档从不
-   生效、以及坏库时列表仍宣称"还没有文献"。
+   生效、以及坏库时列表仍宣称"还没有文献"。插件详情页的 key 段也被真实驱动：
+   `describe` → 输入 → Save（trim 后写入 `NCBI_API_KEY`）→ 状态刷新 + 清空输入 → Remove →
+   provider 拒绝时消息原样显示。
 4. **数据通路（质粒）**：真实 pUC118 `.dna` → 记录（名称/长度/拓扑/特征，AmpR 2102-2962
    反链）→ SVG；GenBank 文本路径与 Node 工具解析结果**逐字段一致**；FASTA → 比对 → logo；
    扩展名分类、排序、base64 解码、非法输入的错误路径。
@@ -234,6 +247,9 @@ shadow（无冲突），面板的 `remote`/`slot` 服务不受影响。
 
 ## 7. 下一步
 
+- **插件详情页的 key 配置**：✅ 已落地（0.22.1，见第 1 与第 4 节）。后续可把同一个
+  `plugins.detail.section` 模式用于其它凭据（例如文献库的机构代理），前提是它们也有一个
+  稳定的环境变量名。
 - **`tool.call.toolview`**：✅ 已落地（见第 1 与第 3 节），覆盖两个 map 工具。可继续做的
   是给 `molbio_sequence_logo` / `molbio_grna_design` 之类的工具也加上卡片（同一套
   `presentationMeta` + 卡片模式）。**注意上线前先跑 `test/client.mjs` 的抢座位顺序那一层**：

package/docs/history.md

@@ -16,6 +16,7 @@
 
 | 包版本 | preset 版本 | 内容 | 工具数 |
 | --- | --- | --- | --- |
+| 0.22.1 | — | **PubMed key 改走 DSH 凭据库**：解析顺序 `api_key` → 凭据库 → 环境变量；无凭据库时行为同 0.22.0 | 60 |
 | 0.22.0 | — | **DSH 0.2.1-rc.3 适配 + PubMed 官方 API**：`molbio_pubmed_search`/`_abstract` 支持 NCBI API key（E-utilities），无 key 行为不变 | 60 |
 | 0.21.1 | — | **DSH STORE 提交前置**：单文件 bundle patch、逐版本兼容声明；根 tarball 只带一个插件清单（工具行为零变化） | 60 |
 | 0.21.0 | — | **DSH 0.2.1-rc.2 适配**：preset 行清单逐行重抄；contract 两条断言重锚到行为；两条 suspended 记录用真实模型重录 | 60 |
@@ -45,6 +46,25 @@
 
 ---
 
+## v0.22.1（2026-10-25，包 0.22.1）
+
+**环境变量不是唯一选择。** 0.22.0 只从 `api_key` 参数与 `process.env` 读 key；这一版把 DSH 的
+`ctx.credentials` 插到中间，并把环境变量降为后备。
+
+- 新顺序：`api_key` 参数 → 凭据库（`NCBI_API_KEY` / `MOLBIO_NCBI_API_KEY`）→ 进程环境。
+- 为什么：环境变量会被**每个子进程**继承——包括 agent 自己的 shell 工具。凭据库不进入环境、
+  仅属主可读、热重载，`describe()` 不回显值。但 DSH 凭据库的文档也写明：agent 与你是同一个 OS
+  用户，它不是硬隔离，只是消除了「自动继承」这条路径。
+- 没有凭据库的组合（以及 provider 抛错的组合）静默回退到环境，行为与 0.22.0 一致；显式参数仍然
+  最高优先。
+- smoke 新增三条：凭据库压过环境、参数压过凭据库、provider 抛错回退。
+- 0.22.1 同时补了**图形入口**：插件 → 已安装插件 → 本包详情页里的 `plugins.detail.section`
+  表单（password 输入 + Save/Remove，值只写不读）。改 YAML 不该是唯一入口。
+- **测试里抓到的缺陷**：`ctx.remote.credentials` 是 fiber injection，不是 Remote 载体的普通属性。
+  第一版没在 `inject` 里声明它，命名空间就是 `undefined`，Save 静默地什么也没写；官方设置页
+  一直把 `remote.credentials` 写在 `inject` 列表里，那就是这行声明的用途。现在用
+  `ctx.inject(['remote.credentials'], …)` 门控整段注册，并在写后重新 `describe` 核对结果。
+
 ## v0.22.0（2026-10-25，包 0.22.0）
 
 一半是适配（rc.3），一半是新能力（PubMed 官方 API + key）。三条教训。

package/docs/maintainer.md

@@ -32,7 +32,7 @@
 
 - **包**：`dsh-molbio-tools`，零依赖 DSH 插件包，**60 个 `molbio_*` 工具**（其中
   `molbio_plot` 一个工具承载 8 种图表）。
-- **基线**：DSH **0.2.1-rc.3**；`package.json` 版本 0.22.0。
+- **基线**：DSH **0.2.1-rc.3**；`package.json` 版本 0.22.1。
 - **两条分发渠道**：根包（工具 + 面板）与 `packages/molbio-panel`（只面板），
   **两个独立的 npm 条目、两条独立的版本线**，必须分别发布。
 - **工具只在专属模式里出现**（设计如此）：bundle 的 `cordis.patch.yml` 只插一行**惰性宿主锚点**

package/docs/roadmap.md

@@ -10,7 +10,7 @@ L = 需要新机制或外部资源）。
 
 ---
 
-## 1. 当前状态（0.22.0）
+## 1. 当前状态（0.22.1）
 
 - 60 个 `molbio_*` 工具，零依赖，随 preset 分发（见 [README](../README.md)）。
 - 离线测试金字塔 + 组合漂移守卫全绿；`benchmark/` 提供**模型使用**维度的评估
@@ -41,6 +41,10 @@ L = 需要新机制或外部资源）。
   `standard` 行清单**逐字节未变**，`preset-health` / `drift-probe` / `contract` 在 rc.3 上
   全绿，因此这一半只改声明与证据）；`molbio_pubmed_search` / `molbio_pubmed_abstract` 增加
   NCBI API key 通路，走官方 E-utilities（esearch + esummary），无 key 时保持原有 web 检索。
+- **0.22.1 是 key 存放方式的安全加固 + 图形入口**：`molbio_pubmed_search` / `molbio_pubmed_abstract`
+  的 key 解析顺序变为 **`api_key` 参数 → DSH 凭据库 → 环境变量**（环境变量会被 agent 自己的 shell
+  子进程继承，凭据库不会）；同时插件详情页出现 **PubMed API key** 表单，用户不必改 YAML。
+  没有凭据库的组合行为与 0.22.0 相同。
 
 ---
 

package/index.mjs

@@ -6914,15 +6914,46 @@ async function eutilsRequest(web, url, signal, label) {
   }
 }
 
+/** Credential-store references tried, in order, before the process environment. */
+const PUBMED_KEY_REFS = ['NCBI_API_KEY', 'MOLBIO_NCBI_API_KEY'];
+
+/**
+ * Resolve the NCBI API key from (1) the call argument, (2) the harness
+ * credential store, (3) the process environment.
+ *
+ * The store is the recommended channel: a stored value is not injected into the
+ * environment, so the agent's own shell children cannot read it by accident, and
+ * `ctx.credentials.resolve` itself falls back through the launch environment and
+ * the .env files. A provider that refuses this ref (a composition without a
+ * credential store, a name outside its grammar) must degrade to the environment
+ * rather than break the tool, hence the per-ref catch.
+ */
+async function pubmedKey(args, ctx) {
+  const explicit = typeof args.api_key === 'string' ? args.api_key.trim() : '';
+  if (explicit !== '') return explicit;
+  const credentials = ctx.get('credentials');
+  if (credentials !== undefined && typeof credentials.resolve === 'function') {
+    for (const ref of PUBMED_KEY_REFS) {
+      try {
+        const hit = await credentials.resolve(ref);
+        if (typeof hit?.value === 'string' && hit.value.trim() !== '') return hit.value.trim();
+      } catch {
+        /* fall through to the environment */
+      }
+    }
+  }
+  return pubmedApiKey(args);
+}
+
 const pubmedAbstractTool = (ctx) => define({
   name: 'molbio_pubmed_abstract',
-  description: 'Fetch PubMed abstracts for PMIDs via NCBI E-utilities (efetch). Requires the deployment to provide the web fetch capability; otherwise it reports that clearly. Pass api_key (or set NCBI_API_KEY / MOLBIO_NCBI_API_KEY) to attribute the request to your NCBI key and raise the rate limit. Use it to pull abstracts for papers found by molbio_pubmed_search before adding them to the library.',
+  description: 'Fetch PubMed abstracts for PMIDs via NCBI E-utilities (efetch). Requires the deployment to provide the web fetch capability; otherwise it reports that clearly. Provide an NCBI API key through the harness credential store (NCBI_API_KEY), the api_key argument, or the environment to attribute the request to your NCBI key and raise the rate limit. Use it to pull abstracts for papers found by molbio_pubmed_search before adding them to the library.',
   parameters: {
     type: 'object',
     required: ['pmids'],
     properties: {
       pmids: { type: 'array', items: { type: 'string' }, description: 'PubMed IDs, e.g. ["37607951"].' },
-      api_key: { type: 'string', description: 'Optional NCBI API key for E-utilities. Prefer setting NCBI_API_KEY in the environment: an inline key appears in the conversation transcript.' },
+      api_key: { type: 'string', description: 'Optional NCBI API key for E-utilities. Resolution order: this argument, the harness credential store (NCBI_API_KEY / MOLBIO_NCBI_API_KEY), then the environment. Prefer the credential store: an inline key appears in the conversation transcript.' },
     },
   },
   outputSchema: {
@@ -6966,7 +6997,7 @@ const pubmedAbstractTool = (ctx) => define({
     if (web === undefined || typeof web.fetch !== 'function') {
       throw new MolbioInputError('this deployment provides no web fetch capability, so PubMed abstracts cannot be retrieved; molbio_pubmed_search still works for titles and snippets');
     }
-    const apiKey = pubmedApiKey(args);
+    const apiKey = await pubmedKey(args, ctx);
     const url = pubmedFetchUrl(pmids, apiKey);
     const result = await web.fetch({ url }, exec?.signal);
     const body = result?.body?.content;
@@ -7318,14 +7349,14 @@ function paperServiceDeps(ctx, exec, args) {
 
 const pubmedSearchTool = (ctx) => define({
   name: 'molbio_pubmed_search',
-  description: 'Search PubMed for literature. With an NCBI API key (the api_key argument, or NCBI_API_KEY / MOLBIO_NCBI_API_KEY in the environment) it queries the official E-utilities API and returns PubMed records with PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web-search service. Add the papers you keep to the reading library with molbio_paper_add.',
+  description: 'Search PubMed for literature. With an NCBI API key (the api_key argument, the harness credential store under NCBI_API_KEY / MOLBIO_NCBI_API_KEY, or the environment) it queries the official E-utilities API and returns PubMed records with PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web-search service. Add the papers you keep to the reading library with molbio_paper_add.',
   parameters: {
     type: 'object',
     required: ['query'],
     properties: {
       query: requiredString('Search query, e.g. "CRISPR base editing review 2024" or "site:pubmed.ncbi.nlm.nih.gov KRAS G12D".'),
       max_results: { type: 'integer', description: 'Maximum results (1-20, default 8).' },
-      api_key: { type: 'string', description: 'Optional NCBI API key for the official PubMed E-utilities API. Prefer setting NCBI_API_KEY in the environment: an inline key appears in the conversation transcript.' },
+      api_key: { type: 'string', description: 'Optional NCBI API key for the official PubMed E-utilities API. Resolution order: this argument, the harness credential store (NCBI_API_KEY / MOLBIO_NCBI_API_KEY), then the environment. Prefer the credential store: an inline key appears in the conversation transcript.' },
     },
   },
   outputSchema: {
@@ -7378,7 +7409,7 @@ const pubmedSearchTool = (ctx) => define({
       throw new MolbioInputError('max_results must be an integer between 1 and 20');
     }
     const web = ctx.get('web');
-    const apiKey = pubmedApiKey(args);
+    const apiKey = await pubmedKey(args, ctx);
     if (apiKey !== undefined) {
       if (web === undefined || typeof web.fetch !== 'function') {
         throw new MolbioInputError('an NCBI API key was provided, but this deployment provides no web fetch capability; the official PubMed API needs ctx.web.fetch');
@@ -7574,9 +7605,9 @@ const PROMPT_SECTION = `Molecular-biology tools (dsh-molbio-tools) are available
 - Sequences & files: molbio_align (local alignment with a readable match line), molbio_msa_align (progressive multiple sequence alignment — pass an array of sequences or a workspace FASTA), molbio_conservation (consensus + per-column identity/conservation + variable positions; accepts aligned rows or raw sequences it aligns first), molbio_sequence_logo (draws the same alignment as a sequence logo SVG — pass the molbio_msa_align output rows as the alignment argument; letters are sized by per-position information content), molbio_fasta_fastq (FASTA/FASTQ stats/extract/convert/QC on workspace files), molbio_batch_analyze (run one summary/ORF/enzyme analysis over every matching FASTA/FASTQ/GenBank/.dna file in a directory and write one CSV/TSV table), molbio_extract_region (pull a CDS/promoter/region from a plasmid file by feature label or coordinates).
 - CRISPR: molbio_grna_design (family-aware guide RNAs over a sequence or plasmid file: cas_family spcas9/sacas9/cas12a/cas13a/cas13b/cas13d selects the PAM side, crRNA length, seed and target type — Cas12a uses a 5' TTTV PAM and 23 nt crRNA; Cas13 targets RNA and reports a PFS preference rather than a PAM. Both strands are scanned for DNA families, the sense strand by default for Cas13; guides are filtered on GC/poly-T/self-complementarity and ranked, with a mismatch-tolerant off-target search over the same sequence — reaching a whole genome simply means passing it as the target). Pass the top candidates on for ordering with save_path (CSV) or map_path (SVG map); the ranking is a heuristic and says so, so present it as candidate ranking, never as a validated efficiency prediction.
 - Map extras: pass gc_skew: true for the GC skew ring, show_unique_cutters: true to mark single-cutting enzymes on the map.
-- Literature & records: molbio_pubmed_abstract (fetch abstracts by PMID — needs web fetch; pass api_key or set NCBI_API_KEY to use your NCBI key), molbio_paper_export_bibtex (papers.json → .bib), molbio_protocol_add / molbio_protocol_list / molbio_protocol_update (protocols.json), molbio_experiment_log / molbio_experiment_list (experiments.json).
+- Literature & records: molbio_pubmed_abstract (fetch abstracts by PMID — needs web fetch; an NCBI key comes from the api_key argument, the credential store's NCBI_API_KEY, or the environment), molbio_paper_export_bibtex (papers.json → .bib), molbio_protocol_add / molbio_protocol_list / molbio_protocol_update (protocols.json), molbio_experiment_log / molbio_experiment_list (experiments.json).
 - Bench analysis (v19): molbio_fastq_qc (read-level QC for a FASTQ file: per-base quality with quartiles, per-read quality, base content, GC distribution, length, exact duplication, over-represented sequences, adapter screen, plus a report SVG — use it for "is this run good"), molbio_codon_usage (CAI/RSCU/Nc/GC3, rare-codon list and CDS CpG against E. coli/yeast/human — use it for "will this gene express"; it explains, molbio_codon_optimize rewrites), molbio_phylogenetic_tree (distance method: p-distance/JC/K2P/Tamura-Nei, UPGMA or neighbour-joining, bootstrap support, consensus, Newick file and an SVG tree — it is NOT a maximum-likelihood or Bayesian analysis, and bootstrap percentages are not p-values), molbio_pcr_simulate (where a primer pair amplifies: product sizes and coordinates on both strands, mismatch detail, the 3'-end exact-match requirement, circular templates, screening other templates, and an expected gel — use it for "what band will I see"), molbio_gc_composition (sliding-window GC, CpG islands under the Gardiner-Garden or Takai criteria, GC/AT skew with the cumulative-skew origin/terminus indication, dinucleotide obs/exp, entropy, complexity, N50/L50, plus a figure — use it for "is this a promoter or an origin").
-- Literature: molbio_pubmed_search — with an NCBI API key (api_key argument, or NCBI_API_KEY / MOLBIO_NCBI_API_KEY in the environment) it uses the official PubMed E-utilities API and returns PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web search. The reading library is molbio_paper_add / molbio_paper_list / molbio_paper_update / molbio_paper_remove (papers.json in the workspace).
+- Literature: molbio_pubmed_search — with an NCBI API key (api_key argument, the credential store under NCBI_API_KEY / MOLBIO_NCBI_API_KEY, or the environment) it uses the official PubMed E-utilities API and returns PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web search. The reading library is molbio_paper_add / molbio_paper_list / molbio_paper_update / molbio_paper_remove (papers.json in the workspace).
 
 Cloning workflow rules (follow them to avoid slow re-derivation):
 - To clone a sequence into a plasmid, call molbio_clone_simulate FIRST — pass the BARE insert with add_flanks: true and the tool adds the enzyme recognition sites itself. The tool also validates single cutting, insert orientation, and internal sites itself: never pre-verify enzymes, cutting counts, or flank construction by thinking. Its output already contains final_sequence AND the remapped feature coordinates (features field). NEVER recompute feature coordinates or insert positions by reasoning — always take them from the tool output.

package/lib/client.js

@@ -8517,6 +8517,44 @@ window.__ModuleLoader__.load({
 			  return undefined;
 			}
 
+			/** The credential reference the PubMed tools read first. */
+			const NCBI_KEY_REF = 'NCBI_API_KEY';
+
+			/**
+			 * Whether a Plugins-page detail subject is this package's own entry.
+			 *
+			 * Bundles and rows both expose `pkg.name`; the key section is offered on the
+			 * bundle page and on every row page the bundle declares, and on nothing else.
+			 */
+			function isMolbioDetailSubject(subject) {
+			  if (subject === null || typeof subject !== 'object') return false;
+			  if (subject.kind !== 'bundle' && subject.kind !== 'row') return false;
+			  const pkg = subject.pkg;
+			  return pkg !== null && typeof pkg === 'object' && pkg.name === 'dsh-molbio-tools';
+			}
+
+			/**
+			 * The host failure message carried by a Remote result, or '' on success.
+			 * Remote calls answer `{ ok: true, value }` or `{ ok: false, error }`.
+			 */
+			function remoteFailure(response) {
+			  if (response === null || typeof response !== 'object' || response.ok !== false) return '';
+			  const message = response.error?.message;
+			  return typeof message === 'string' && message !== '' ? message : 'the host refused the request';
+			}
+
+			/** One reference's view from a `credentials.describe` response (never the value). */
+			function credentialInfo(response, ref) {
+			  const view = response !== null && typeof response === 'object' && response.ok !== false
+			    ? response.value?.[ref]
+			    : undefined;
+			  return {
+			    configured: view?.configured === true,
+			    writable: view?.writable !== false,
+			    ...typeof view?.source === 'string' && view.source !== '' ? { source: view.source } : {},
+			  };
+			}
+
 			exports.PLASMID_EXTENSIONS = PLASMID_EXTENSIONS;
 			exports.ALIGNMENT_EXTENSIONS = ALIGNMENT_EXTENSIONS;
 			exports.extensionOf = extensionOf;
@@ -8541,6 +8579,10 @@ window.__ModuleLoader__.load({
 			exports.paperFields = paperFields;
 			exports.paperSummary = paperSummary;
 			exports.paperLink = paperLink;
+			exports.NCBI_KEY_REF = NCBI_KEY_REF;
+			exports.isMolbioDetailSubject = isMolbioDetailSubject;
+			exports.remoteFailure = remoteFailure;
+			exports.credentialInfo = credentialInfo;
 			return exports;
 		};
 		__molbio_modules["build/client-entry.mjs"] = () => {
@@ -8577,7 +8619,7 @@ window.__ModuleLoader__.load({
 			 * inside the factory would also have to be torn down by hand on unload.
 			 */
 			const { createElement: h, useEffect, useMemo, useRef, useState } = __ext0;
-			const { LIBRARY_FILE, childPath, classifyEntry, decodeWorkspaceBytes, filterPapers, isOpenable, libraryTags, logoSvg, mapCardSummary, mapCardView, paperFields, paperLink, paperSummary, parseAlignmentFile, parseLibrary, parsePlasmidFile, plasmidSvg, readWorkspaceText, sortEntries } = __molbio_require("build/panel-core.mjs");
+			const { LIBRARY_FILE, NCBI_KEY_REF, childPath, classifyEntry, credentialInfo, isMolbioDetailSubject, remoteFailure, decodeWorkspaceBytes, filterPapers, isOpenable, libraryTags, logoSvg, mapCardSummary, mapCardView, paperFields, paperLink, paperSummary, parseAlignmentFile, parseLibrary, parsePlasmidFile, plasmidSvg, readWorkspaceText, sortEntries } = __molbio_require("build/panel-core.mjs");
 			/** This implementation's identity, and the key its body/title register under. */
 			const PANEL_ID = 'dsh-molbio-tools';
 			/** Type discriminator the tab is opened by. */
@@ -9015,6 +9057,142 @@ window.__ModuleLoader__.load({
 			    h('div', { style: styles.main }, ...detail));
 			}
 
+			/** The state of the PubMed key, read from the host's credential store. */
+			async function readNcbiKey(remote) {
+			  if (remote?.credentials === undefined || typeof remote.credentials.describe !== 'function') {
+			    return { phase: 'error', configured: false, writable: false, message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' };
+			  }
+			  let response;
+			  try {
+			    response = await remote.credentials.describe([NCBI_KEY_REF]);
+			  } catch (error) {
+			    response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+			  }
+			  const failure = remoteFailure(response);
+			  if (failure !== '') return { phase: 'error', configured: false, writable: false, message: failure };
+			  return { phase: 'ready', ...credentialInfo(response, NCBI_KEY_REF), message: '' };
+			}
+
+			const keyStyles = {
+			  section: { borderTop: '1px solid rgba(127, 127, 127, 0.28)', marginTop: 16, paddingTop: 12, display: 'grid', gap: 8 },
+			  title: { margin: 0, fontSize: 14 },
+			  note: { margin: 0, fontSize: 12, opacity: 0.75, lineHeight: 1.5 },
+			  status: { margin: 0, fontSize: 12 },
+			  row: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
+			  input: { flex: '1 1 240px', minWidth: 200, padding: '4px 8px' },
+			  message: { margin: 0, fontSize: 12 },
+			};
+
+			/**
+			 * The Plugins → installed plugin → detail section that stores the NCBI key.
+			 *
+			 * It renders only for this package's own subject (bundle page, or one of the
+			 * row pages the bundle declares) and returns null everywhere else, which is the
+			 * contract `plugins.detail.section` asks a contribution to honour. The value is
+			 * write-only from here: `credentials.describe` answers whether a key is
+			 * configured and where it came from, never the key itself.
+			 */
+			function NcbiKeySection({ subject, remote }) {
+			  const [draft, setDraft] = useState('');
+			  const [state, setState] = useState({ phase: 'loading', configured: false, writable: true, message: '' });
+			  const subjectToken = isMolbioDetailSubject(subject)
+			    ? `${subject.kind}:${subject.pkg.name}:${subject.row?.rowId ?? ''}`
+			    : '';
+			  useEffect(() => {
+			    if (subjectToken === '') return undefined;
+			    let live = true;
+			    const load = () => readNcbiKey(remote).then((next) => { if (live) setState(next); });
+			    load();
+			    // Another surface may rotate or clear the same reference (Settings, the
+			    // file watcher); follow the host event instead of showing a stale badge.
+			    const off = typeof remote?.$on === 'function'
+			      ? remote.$on('credentials/reference-updated', (ref) => { if (ref === NCBI_KEY_REF) load(); })
+			      : undefined;
+			    return () => {
+			      live = false;
+			      if (typeof off === 'function') off();
+			    };
+			  }, [remote, subjectToken]);
+			  if (!isMolbioDetailSubject(subject)) return null;
+			  const busy = state.phase === 'saving';
+			  const save = async () => {
+			    const value = draft.trim();
+			    if (value === '') return;
+			    if (remote?.credentials === undefined || typeof remote.credentials.set !== 'function') {
+			      setState((previous) => ({ ...previous, phase: 'error', message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' }));
+			      return;
+			    }
+			    setState((previous) => ({ ...previous, phase: 'saving', message: '' }));
+			    let response;
+			    try {
+			      response = await remote.credentials.set(NCBI_KEY_REF, value);
+			    } catch (error) {
+			      response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+			    }
+			    const failure = remoteFailure(response);
+			    setDraft('');
+			    const next = await readNcbiKey(remote);
+			    setState(failure !== ''
+			      ? { ...next, phase: 'error', message: failure }
+			      : next.phase === 'error'
+			        ? next
+			        : next.configured === true
+			          ? { ...next, message: 'Saved. The next PubMed call uses this key.' }
+			          : { ...next, phase: 'error', message: 'The host accepted the write but still reports no key configured. Restart the profile and try again.' });
+			  };
+			  const remove = async () => {
+			    if (remote?.credentials === undefined || typeof remote.credentials.unset !== 'function') {
+			      setState((previous) => ({ ...previous, phase: 'error', message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' }));
+			      return;
+			    }
+			    setState((previous) => ({ ...previous, phase: 'saving', message: '' }));
+			    let response;
+			    try {
+			      response = await remote.credentials.unset(NCBI_KEY_REF);
+			    } catch (error) {
+			      response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+			    }
+			    const failure = remoteFailure(response);
+			    const next = await readNcbiKey(remote);
+			    setState(failure !== ''
+			      ? { ...next, phase: 'error', message: failure }
+			      : next.phase === 'error'
+			        ? next
+			        : next.configured === false
+			          ? { ...next, message: 'Removed. PubMed search falls back to web search.' }
+			          : { ...next, phase: 'error', message: 'The host still reports a key configured after Remove.' });
+			  };
+			  const status = state.phase === 'loading'
+			    ? 'Checking the credential store…'
+			    : state.phase === 'error'
+			      ? 'Unavailable'
+			      : state.configured
+			        ? `Configured${state.source === undefined ? '' : ` (source: ${state.source})`}`
+			        : 'Not configured';
+			  return h('section', { 'data-molbio-ncbi-key': '', style: keyStyles.section },
+			    h('h4', { style: keyStyles.title }, 'PubMed API key'),
+			    h('p', { style: keyStyles.note }, 
+			      'Stored in the harness credential store. molbio_pubmed_search and molbio_pubmed_abstract use it for the official PubMed E-utilities API; without it they fall back to web search.'),
+			    h('p', { 'data-molbio-key-status': state.phase, style: keyStyles.status }, status),
+			    h('div', { style: keyStyles.row },
+			      h('input', {
+			        type: 'password',
+			        value: draft,
+			        placeholder: 'NCBI API key (36 characters)',
+			        autoComplete: 'off',
+			        spellCheck: false,
+			        'aria-label': 'NCBI API key',
+			        style: keyStyles.input,
+			        onChange: (event) => setDraft(event.target.value),
+			      }),
+			      h('button', { type: 'button', disabled: busy || state.writable === false || draft.trim() === '', onClick: save },
+			        busy ? 'Saving…' : 'Save'),
+			      h('button', { type: 'button', disabled: busy || state.writable === false || state.configured !== true, onClick: remove }, 'Remove')),
+			    state.message === '' ? null : h('p', { 'data-molbio-key-message': '', role: 'status', style: keyStyles.message }, state.message),
+			    h('p', { style: keyStyles.note },
+			      'Create a key under NCBI → Account Settings → API Key Management. Prefer this over an environment variable: the store is not inherited by shell commands.'));
+			}
+
 			/** Required browser services. */
 			const inject = ['slots', 'sidebarRightTabs', 'remote'];
 
@@ -9098,6 +9276,25 @@ window.__ModuleLoader__.load({
 			      key: toolName,
 			    }, MolbioMapCard)), `molbio panel: ${toolName} card`);
 			  }
+			  // Plugins -> the installed plugin's detail page: the one place a user can
+			  // store the NCBI key without editing a YAML file or exporting a variable.
+			  //
+			  // `remote.credentials` is a FIBER INJECTION, not merely a property on the
+			  // Remote carrier: the shipped settings pages declare it in `inject` for the
+			  // same reason. Without the declaration `ctx.remote.credentials` is undefined,
+			  // which is exactly how the first build of this section made Save a no-op.
+			  // The gate keeps the panel working in deployments that expose no credentials
+			  // namespace: the section simply never registers there.
+			  ctx.effect(() => {
+			    const gate = ctx.inject(['remote.credentials'], (keyCtx) => {
+			      keyCtx.effect(() => keyCtx.slots.inject('plugins.detail.section', () => keyCtx.slots.register({
+			        name: 'plugins.detail.section',
+			        id: 'molbio-ncbi-key',
+			        order: 100,
+			      }, (props) => h(NcbiKeySection, { ...props, remote: keyCtx.remote }))), 'molbio panel: NCBI key section');
+			    });
+			    return () => { gate.dispose(); };
+			  }, 'molbio panel: NCBI key section gate');
 			}
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-molbio-tools",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Zero-dependency molecular-biology plugin bundle for the DeepSeek Harness: sequence analysis, primer design (incl. cross-intron qPCR primers, TaqMan hydrolysis/MGB probes with ordering CSV and multiplex compatibility), in-silico PCR, cloning simulation, SnapGene .dna parsing and plasmid maps, Sanger verification, protein tools (incl. helical wheel and hydropathy plots), methylation-aware restriction analysis with double-digest buffer checks, qPCR analysis and plotting, multiple sequence alignment that conserves every input residue, conservation analysis, sequence logos, codon-usage analysis, phylogenetic trees with bootstrap support, Newick I/O and long-name label wrapping, CpG-island/GC-skew composition analysis, read-level FASTQ QC, batch file analysis with CSV export, silent restriction-site mutagenesis, family-aware CRISPR gRNA design (SpCas9/SaCas9/Cas12a/Cas13) with off-target search, an opt-in hand-off that shows a generated plot to the model as an attached image, plus a browser-side right-sidebar panel (plasmid maps and sequence logos drawn in the Web GUI) and a literature/protocol/experiment record system.",
   "type": "module",
   "main": "index.mjs",

package/test/client.mjs

@@ -101,6 +101,7 @@ assert.deepEqual([...module.inject], ['slots', 'sidebarRightTabs', 'remote'], 't
 
 const effects = [];
 const tabTypes = [];
+const injectedDeps = [];
 const slots = createSlotsStub();
 const ctx = {
   remote: {
@@ -122,9 +123,16 @@ const ctx = {
     effects.push(label);
     return factory();
   },
+  inject(deps, callback) {
+    injectedDeps.push([...deps]);
+    const child = Object.create(ctx);
+    child.remote = { ...ctx.remote, credentials: {} };
+    return { dispose() {}, value: callback(child) };
+  },
   sidebarRightTabs: { register(definition) { tabTypes.push(definition); return () => undefined; } },
   slots,
 };
+assert.deepEqual(injectedDeps, [], 'no dependency gate has run yet');
 assert.doesNotThrow(() => module.apply(ctx), 'apply() must not require any seat to be declared yet');
 
 assert.deepEqual(effects, [
@@ -136,7 +144,10 @@ assert.deepEqual(effects, [
   'molbio panel: papers tab title',
   'molbio panel: molbio_plasmid_map card',
   'molbio panel: molbio_plasmid_map_file card',
+  'molbio panel: NCBI key section gate',
+  'molbio panel: NCBI key section',
 ]);
+assert.deepEqual(injectedDeps, [['remote.credentials']], 'the key section waits for the credentials Remote namespace');
 assert.equal(tabTypes.length, 2, 'the package contributes two page tab types');
 assert.deepEqual(
   tabTypes.map((type) => [type.id, type.kind, type.title()]),
@@ -153,7 +164,7 @@ assert.deepEqual(tabTypes.map((type) => type.guide[0].order), [40, 41], 'the gui
 assert.equal(slots.registrations.length, 0, 'nothing registers before its seat exists');
 assert.deepEqual(
   slots.injectedSeats,
-  ['sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'tool.call.toolview'],
+  ['sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'tool.call.toolview', 'plugins.detail.section'],
   'each seat is claimed by waiting for its declaration, not by registering blindly',
 );
 // The shell's guard, reproduced on the stub: this is the exact exception a bare
@@ -169,8 +180,8 @@ slots.declare('sidebar.right.pane.tab');
 slots.declare('sidebar.right.pane.tab.title');
 assert.deepEqual(
   slots.pendingSeats,
-  ['tool.call.toolview'],
-  'the transcript card is still waiting for the seat ui-tool declares',
+  ['tool.call.toolview', 'plugins.detail.section'],
+  'the transcript card and the plugin-detail section wait for the seats their owners declare',
 );
 assert.equal(slots.registrations.length, 4, 'both tab bodies and titles land as soon as their seat exists');
 slots.declare('tool.call.toolview');
@@ -211,6 +222,39 @@ assert.equal(claim('tool.call.toolview', 'molbio_plasmid_map').registration.inje
 slots.declare('tool.call.toolview');
 assert.equal(slots.registrations.length, 6, 're-declaring the seat re-installs both cards instead of duplicating them');
 
+// The Plugins page's detail seat belongs to the plugin manager. The section
+// lands when that seat is declared, and the component itself decides whether
+// the open subject is this package.
+slots.declare('plugins.detail.section');
+assert.equal(slots.registrations.length, 7, 'the key section lands when the plugin manager declares its seat');
+const keyClaim = slots.registrations.find((entry) => entry.registration.name === 'plugins.detail.section');
+assert.ok(keyClaim, 'the key section is claimed in plugins.detail.section');
+assert.equal(keyClaim.registration.id, 'molbio-ncbi-key', 'the list seat is addressed by an id of our own');
+assert.equal(typeof keyClaim.component, 'function', 'the section is a component');
+// The registered component binds `remote`; invoking its element type is how a
+// test renders it without React (the hooks are stubbed by this file's reactStub).
+const ours = keyClaim.component({ subject: { kind: 'bundle', pkg: { name: 'dsh-molbio-tools' } } });
+assert.equal(typeof ours.type, 'function', 'the wrapper renders this package\'s section');
+const sectionTree = ours.type(ours.props);
+assert.equal(sectionTree.type, 'section');
+assert.equal(sectionTree.props['data-molbio-ncbi-key'], '');
+const flat = [];
+const walk = (node) => {
+  if (node === null || typeof node !== 'object') return;
+  flat.push(node);
+  for (const child of Array.isArray(node.children) ? node.children : []) walk(child);
+};
+walk(sectionTree);
+assert.ok(flat.some((node) => node.type === 'h4' && node.children.join('') === 'PubMed API key'), 'the section is titled');
+assert.ok(flat.some((node) => node.type === 'input' && node.props.type === 'password'), 'the section offers a password input');
+assert.ok(flat.some((node) => node.type === 'button' && node.children.join('') === 'Save'), 'the section offers a save control');
+const renderFor = (subject) => {
+  const wrapper = keyClaim.component({ subject });
+  return wrapper.type(wrapper.props);
+};
+assert.equal(renderFor({ kind: 'bundle', pkg: { name: 'another-plugin' } }), null, 'another package gets no section');
+assert.equal(renderFor({ kind: 'item', id: 'web-search' }), null, 'an official-plugin page gets no section');
+
 // ── 3. the panel's data path, against the real fixture ──────────────────────
 
 assert.equal(panelCore.extensionOf('pUC118.dna'), 'dna');
@@ -231,6 +275,21 @@ const sorted = panelCore.sortEntries([
 ]);
 assert.deepEqual(sorted.map((entry) => entry.name), ['a.dna', 'z.dna', 'a.fasta', 'notes.md']);
 
+// The plugin-detail key section's pure helpers: which subject it belongs to,
+// how a credential view is read, and how a refused Remote call is surfaced.
+assert.equal(panelCore.isMolbioDetailSubject({ kind: 'bundle', pkg: { name: 'dsh-molbio-tools' } }), true);
+assert.equal(panelCore.isMolbioDetailSubject({ kind: 'row', pkg: { name: 'dsh-molbio-tools' }, row: { rowId: 'molbio-client' } }), true);
+assert.equal(panelCore.isMolbioDetailSubject({ kind: 'bundle', pkg: { name: 'another-plugin' } }), false);
+assert.equal(panelCore.isMolbioDetailSubject({ kind: 'item', id: 'dsh-molbio-tools' }), false, 'official-plugin pages are not ours');
+assert.equal(panelCore.isMolbioDetailSubject(null), false);
+assert.deepEqual(
+  panelCore.credentialInfo({ ok: true, value: { NCBI_API_KEY: { configured: true, source: 'file', writable: true } } }, 'NCBI_API_KEY'),
+  { configured: true, writable: true, source: 'file' },
+);
+assert.deepEqual(panelCore.credentialInfo({ ok: true, value: {} }, 'NCBI_API_KEY'), { configured: false, writable: true });
+assert.equal(panelCore.remoteFailure({ ok: false, error: { message: 'credential/rejected: the store is unreadable' } }), 'credential/rejected: the store is unreadable');
+assert.equal(panelCore.remoteFailure({ ok: true, value: {} }), '', 'a successful result carries no failure');
+
 assert.equal(panelCore.childPath('D:\\work', 'a.dna'), 'D:\\work/a.dna');
 assert.equal(panelCore.childPath('', 'a.dna'), 'a.dna');
 

package/test/contract.mjs

@@ -277,6 +277,24 @@ check('the built bundle registers the seats and services the framework expects',
   // The inject factory must hand over exactly the services the framework does
   // NOT provide, so it can never shadow sessionId or a synthesised hook.
   assert.ok(/inject: \(\) => \(\{ remote \}\)/.test(bundle), 'the body injects only the Remote face');
+
+  // The plugin-detail key section depends on TWO upstream facts: the plugin
+  // manager still declares the seat, and the settings controller still exposes
+  // the credentials Remote namespace with the argument order we call. Both are
+  // silent if they move (the section simply never renders), so pin them here.
+  assert.ok(bundle.includes('plugins.detail.section'), 'the bundle waits for the plugin-manager detail seat');
+  for (const call of ['credentials.describe(', 'credentials.set(', 'credentials.unset(']) {
+    assert.ok(bundle.includes(call), `the key section calls ${call}…)`);
+  }
+  assert.ok(bundle.includes("ctx.inject(['remote.credentials']"), 'the key section declares the credentials FIBER INJECTION (a plain property is undefined)');
+  const manager = clientBundle('@deepseek-ai/dsh-client-ui-plugin-manager');
+  assert.ok(manager !== undefined && manager.text.includes('plugins.detail.section'), 'the plugin manager still declares plugins.detail.section');
+  const settings = hostHalf('@deepseek-ai/dsh-api-settings-controller');
+  assert.ok(settings !== undefined, 'the settings controller is installed');
+  assert.ok(settings.text.includes('namespace: "credentials"'), 'the credentials Remote namespace still exists');
+  assert.match(settings.text, /async describe\(refs\)/, 'describe takes the reference list first');
+  assert.match(settings.text, /async set\(ref, value\)/, 'set takes (ref, value)');
+  assert.match(settings.text, /async unset\(ref\)/, 'unset takes the reference');
 });
 
 check('the package manifest keeps the client declaration the scan keys on', () => {
@@ -460,10 +478,12 @@ check('every seat claim waits for the declaration (slots.inject, not a bare regi
 
   // Our artifact: every `register` must sit inside a wait for that same seat.
   const bundle = readFileSync(join(packageRoot, 'lib', 'client.js'), 'utf8');
-  const waited = [...bundle.matchAll(/slots\.inject\('([^']+)', \(\) => (?:ctx\.)?slots\.register\(\{\s*name: '([^']+)'/g)];
+  // The receiver may be a fiber context (`keyCtx.slots`), not only `ctx.slots`:
+  // the key section registers inside a ctx.inject gate.
+  const waited = [...bundle.matchAll(/slots\.inject\('([^']+)', \(\) => (?:[A-Za-z_$][\w$]*\.)?slots\.register\(\{\s*name: '([^']+)'/g)];
   assert.ok(waited.length > 0, 'the bundle claims its seats through slots.inject');
   for (const [, seat, name] of waited) assert.equal(seat, name, `the claim of ${name} waits for the seat it registers into`);
-  const registers = (bundle.match(/(?:ctx\.)?slots\.register\(/g) ?? []).length;
+  const registers = (bundle.match(/(?:[A-Za-z_$][\w$]*\.)?slots\.register\(/g) ?? []).length;
   assert.equal(registers, waited.length, 'and no registration exists outside such a wait');
 });
 

package/test/map-card.mjs

@@ -253,12 +253,14 @@ function mount(Component) {
 const registrations = [];
 const module = await import(entryPath.href);
 const slots = createSlotsStub(['sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'tool.call.toolview']);
-module.apply({
+const cardCtx = {
   remote: {},
   effect: (factory) => factory(),
+  inject: (_deps, callback) => ({ dispose() {}, value: callback(cardCtx) }),
   sidebarRightTabs: { register: (definition) => registrations.push(definition) },
   slots,
-});
+};
+module.apply(cardCtx);
 const MapCard = slots.registrations.find(
   (entry) => entry.registration.name === 'tool.call.toolview' && entry.registration.key === 'molbio_plasmid_map',
 ).component;

package/test/panel-render.mjs

@@ -308,12 +308,17 @@ const module = await (async () => {
   }
 })();
 
-const slots = createSlotsStub(['sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'tool.call.toolview']);
+const slots = createSlotsStub(['sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'tool.call.toolview', 'plugins.detail.section']);
 const ctx = {
   remote: remote({}),
   effect(factory) {
     return factory();
   },
+  // `apply` gates the key section on the credentials Remote namespace; this
+  // file supplies every dependency it asks for, like the default composition.
+  inject(_deps, callback) {
+    return { dispose() {}, value: callback(ctx) };
+  },
   sidebarRightTabs: { register: (definition) => registrations.push(definition) },
   slots,
 };
@@ -594,6 +599,77 @@ const library = {
   harness.unmount();
 }
 
+// ── the plugin-detail key section (write-only credential form) ─────────────
+
+{
+  const claim = slots.registrations.find((entry) => entry.registration.name === 'plugins.detail.section');
+  assert.ok(claim, 'the key section registered once its seat was declared');
+  const store = { value: undefined, describe: [], set: [], unset: [], refuse: '' };
+  ctx.remote.credentials = {
+    async describe(refs) {
+      store.describe.push(refs);
+      return {
+        ok: true,
+        value: {
+          NCBI_API_KEY: {
+            configured: store.value !== undefined,
+            writable: true,
+            ...store.value === undefined ? {} : { source: 'file' },
+          },
+        },
+      };
+    },
+    async set(ref, value) {
+      store.set.push([ref, value]);
+      if (store.refuse !== '') return { ok: false, error: { message: store.refuse } };
+      store.value = value;
+      return { ok: true, value: null };
+    },
+    async unset(ref) {
+      store.unset.push(ref);
+      store.value = undefined;
+      return { ok: true, value: null };
+    },
+  };
+  const subject = { kind: 'bundle', pkg: { name: 'dsh-molbio-tools' } };
+  const wrapper = claim.component({ subject });
+  const harness = mount(wrapper.type);
+  globalThis.__molbioTestHooks = harness;
+  harness.setProps({ subject, remote: ctx.remote });
+  await harness.render();
+  assert.deepEqual(store.describe[0], ['NCBI_API_KEY'], 'the section asks only about its own reference');
+  assert.match(markup(harness.tree), /Not configured/, 'an empty store reads as not configured');
+  const input = elements(harness.tree, 'input')[0];
+  assert.equal(input.props.type, 'password', 'the key is typed into a password field');
+  input.props.onChange({ target: { value: '  key-123  ' } });
+  await harness.render();
+  const save = elements(harness.tree, 'button').find((node) => texts(node).join('') === 'Save');
+  await save.props.onClick();
+  await flush();
+  await harness.render();
+  assert.deepEqual(store.set, [['NCBI_API_KEY', 'key-123']], 'Save trims and stores under NCBI_API_KEY');
+  assert.ok(store.describe.length >= 2, 'the status is re-read after the write');
+  assert.match(markup(harness.tree), /Configured \(source: file\)/, 'the status names the source, never the value');
+  assert.equal(elements(harness.tree, 'input')[0].props.value, '', 'the draft is cleared after saving');
+
+  const remove = elements(harness.tree, 'button').find((node) => texts(node).join('') === 'Remove');
+  await remove.props.onClick();
+  await flush();
+  await harness.render();
+  assert.deepEqual(store.unset, ['NCBI_API_KEY'], 'Remove deletes the reference');
+  assert.match(markup(harness.tree), /Not configured/, 'the status follows the removal');
+
+  // A provider refusal is shown verbatim instead of being swallowed.
+  store.refuse = 'credential/rejected: the credentials file is unreadable';
+  elements(harness.tree, 'input')[0].props.onChange({ target: { value: 'x' } });
+  await harness.render();
+  await elements(harness.tree, 'button').find((node) => texts(node).join('') === 'Save').props.onClick();
+  await flush();
+  await harness.render();
+  assert.ok(markup(harness.tree).includes('credential/rejected: the credentials file is unreadable'), 'a refused write keeps the host message');
+  harness.unmount();
+}
+
 // ── effects are disposed on unmount ─────────────────────────────────────────
 
 {

package/test/smoke.mjs

@@ -1989,6 +1989,55 @@ delete process.env.MOLBIO_NCBI_API_KEY;
   }
 }
 
+{
+  // the harness credential store outranks the environment without ever
+  // materializing the key in process.env; an explicit argument still wins.
+  const saved = process.env.NCBI_API_KEY;
+  process.env.NCBI_API_KEY = 'env-loses';
+  extraServices.set('credentials', {
+    async resolve(ref) {
+      return ref === 'NCBI_API_KEY' ? { value: 'store-key', source: 'store' } : undefined;
+    },
+  });
+  try {
+    mockWeb.calls.length = 0;
+    const stored = await run('molbio_pubmed_search', { query: 'stored key' });
+    assert.equal(stored.backend, 'pubmed-eutils');
+    assert.ok(mockWeb.calls.length === 2 && mockWeb.calls.every((url) => url.includes('api_key=store-key')));
+
+    mockWeb.calls.length = 0;
+    const explicit = await run('molbio_pubmed_search', { query: 'explicit key', api_key: 'arg-key' });
+    assert.equal(explicit.backend, 'pubmed-eutils');
+    assert.ok(mockWeb.calls.every((url) => url.includes('api_key=arg-key')));
+  } finally {
+    extraServices.delete('credentials');
+    delete process.env.NCBI_API_KEY;
+    if (saved !== undefined) process.env.NCBI_API_KEY = saved;
+  }
+}
+
+{
+  // a credential provider that refuses the ref must degrade to the environment,
+  // not break the tool (a composition may have no store at all).
+  const saved = process.env.NCBI_API_KEY;
+  process.env.NCBI_API_KEY = 'env-fallback';
+  extraServices.set('credentials', {
+    async resolve() {
+      throw new Error('no credential store in this composition');
+    },
+  });
+  try {
+    mockWeb.calls.length = 0;
+    const out = await run('molbio_pubmed_search', { query: 'fallback' });
+    assert.equal(out.backend, 'pubmed-eutils');
+    assert.ok(mockWeb.calls.length === 2 && mockWeb.calls.every((url) => url.includes('api_key=env-fallback')));
+  } finally {
+    extraServices.delete('credentials');
+    delete process.env.NCBI_API_KEY;
+    if (saved !== undefined) process.env.NCBI_API_KEY = saved;
+  }
+}
+
 {
   // an invalid key is reported as such, not presented as "no results"
   await assert.rejects(() => run('molbio_pubmed_search', { query: 'x', api_key: 'bad-key' }), /API key invalid/);