better-dsh 0.2.3 → 0.2.4

package/dsh-docs/cookbook/maintaining-dsh-code-review.md

@@ -0,0 +1,64 @@
+# Maintaining the dsh-code-review skill
+
+English | [中文](maintaining-dsh-code-review.zh.md)
+
+The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is kept current by a single designated operator running a private periodic maintenance tool. This cookbook is the entry point for that operator — and for anyone taking over the role — and for repo contributors who want to understand why skill updates arrive as small periodic PRs rather than one-off audits. The workflow itself is specified in the [human-review skill-maintenance Agent Note](../../.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md).
+
+## What the maintainer receives
+
+The operator invokes the wrapper manually, daily with a two-UTC-day overlap; a manual weekly recovery run uses a seven-day window. The workflow:
+
+1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
+2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
+3. Two independently configured reviewer adapters classify who wrote each item and whether the change adopted it, then classify agreed-adopted items against the current skill.
+4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
+5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
+
+Each run stores its artifacts on the operator's machine. The saved diff, candidate `SKILL.md`, and promotion manifest land under `~/dsh-code-review-outputs/` named by timestamp. The manifest records the source master commit and skill blob, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; raw per-adapter I/O stays in a private temp directory whose path is written to the notification and to the daily log under `~/Library/Logs/dsh-code-review-maintainer/`. The maintenance worktree itself is restored clean after every run so the operator is never tempted to edit the maintenance copy in place.
+
+## What the operator does with a candidate diff
+
+When a run produces a candidate, a macOS notification arrives with a `dsh-code-review-promote <timestamp>` hint.
+
+1. **Read the diff on its own merits.** Do not defer to "the reviewers approved"; the maintainer contract is that the operator makes the final decision. Look for checklist bloat, historical prose, unsupported extrapolation from a single incident, and duplicated coverage with existing skill or authoritative-doc content.
+
+   ```sh
+   ls ~/dsh-code-review-outputs/                         # every candidate ever produced
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.manifest.json
+   ```
+
+2. **Cross-check against the run artifacts.** The promotion manifest maps each proposed rule to source feedback and landed evidence; detailed per-adapter I/O, consensus, and adopted evidence live under the run's private temp directory (path shown in the log). Spot-check at least one candidate: does the linked human comment actually support the added rule? Does the linked PR actually adopt it?
+
+3. **Decide one of three:**
+   - **Discard.** Delete the saved candidate. The tool re-considers the same feedback on the next run under whatever the current skill then says.
+
+     ```sh
+     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
+     ```
+   - **Batch.** Keep the candidate aside if the update is small and could combine with a future one. The source-skill check still applies; rerun the analysis or manually rebase and re-review the diff if `master` changes first.
+   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body lists the source feedback URLs or IDs, landed commit range, originating run, checks, and operator edits. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
+
+     ```sh
+     cd ~/path/to/deepseek-harness   # clean master
+     dsh-code-review-promote 2026-07-16T02-00-00Z
+     ```
+
+4. **Do not commit adapter output verbatim.** Small edits during promotion — tightening wording, removing an example that only makes sense with the source PR's context, folding a rule into an existing one — are expected and preserve the "reviewer judgment" the workflow depends on. Amend the branch before merging.
+
+## When a run produces no candidate
+
+That is the common case after every nonempty classification stage has produced at least one valid adapter result. The tool records "no candidate" in its daily log, sends no notification (to avoid alert fatigue), and moves on. Days without a skill update are the workflow behaving correctly, not a stall.
+
+## Interruptions and handoff
+
+The mechanism lives on one machine. Interruptions the operator handles as they arise:
+
+- **Daily run missed.** The two-day overlap window catches one skipped day automatically; longer gaps recover by running the wrapper manually with `DSH_CODE_REVIEW_SINCE=<Nd>`. Overlapping windows are idempotent: guidance already in the current skill is classified `covered` and does not re-enter as a candidate.
+- **Adapter provider outage.** The tool refuses to run when the two reviewer commands resolve to byte-identical executables. A single batch whose adapter response fails schema or id validation is failed closed at the batch level (every item in the batch marked unclear) and the run continues; the raw output is preserved for debugging. If either adapter produces no valid result for any nonempty batch in an operation, the run fails, writes a failure record, and notifies the operator; it never collapses a total-provider outage into "no candidate."
+- **Handoff to another maintainer.** Open a follow-up Agent Note that supersedes the current one: either move the mechanism into the repository or record the new operator's private setup. Do not silently transfer the tool — the "single-maintainer bus factor" in the Agent Note's Risks section is the reason the handoff needs a documented decision.
+
+## Where the operator's private setup lives
+
+The tool source, reviewer adapters, provider credentials, and scheduler are the operator's private infrastructure and are outside this repository by design (see the Agent Note's "Where the mechanism lives" section). This cookbook and the Agent Note describe **what the workflow guarantees**; **how** those guarantees are implemented is a private-infrastructure concern. If you are the new operator, the Agent Note's `## Proposal` sections are the specification you build against.

package/dsh-docs/cookbook/maintaining-dsh-code-review.zh.md

@@ -0,0 +1,64 @@
+# 维护 dsh-code-review skill
+
+[English](maintaining-dsh-code-review.md) | 中文
+
+[`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill（技能）由一名指定操作员通过私有的周期维护工具持续更新。本实操手册既是该操作员和接任者的入口，也帮助仓库贡献者理解为何 skill 更新会以小型周期 PR（Pull Request）的形式出现，而不是一次性审计。工作流本身由[人工评审 skill 维护 Agent Note](../../.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md)规定。
+
+## 维护者会收到什么
+
+操作员每天手动调用包装脚本，并使用 2 个 UTC 日的重叠窗口；每周手动恢复运行使用 7 日窗口。工作流会：
+
+1. 选择指定窗口内合并、且合并 commit 可从 `origin/master` 到达的 PR（每天运行默认选择 2 个 UTC 日，每周运行选择 7 日）。合并 commit 无法到达的 PR（例如父分支被 squash 的堆叠分支），或超出 250 个 commit 获取上限的 PR，会记录到 `skipped-pulls.json` 并跳过，不会中止本次运行。
+2. 收集合并前带 commit 锚点的人工评审反馈（行内评论和评审提交），然后比较反馈时与最终落地的 PR patch。它不获取 PR 会话评论，因为 GitHub 当前状态无法为这些评论提供可抵抗 force-push 的反馈时基线；它也不会把只存在于目标分支的变更作为采纳证据。
+3. 两个独立配置的评审适配器先对每个条目的作者以及更改是否采纳了它进行分类，再根据当前 skill 对双方一致认定已采纳的条目分类。
+4. 主适配器起草完整修订版 `SKILL.md`；两个适配器评审同一份 diff；只要仍有阻塞性问题，循环就会继续，直到双方批准。
+5. 工具声明成功前，会针对候选版本运行 `pnpm run doc-sync` 和 `pnpm run lint`。
+
+每次运行都把产物保存在操作员的机器上。保存的 diff、候选 `SKILL.md` 和提升 manifest（元数据清单）按时间戳命名，存放在 `~/dsh-code-review-outputs/` 下。manifest 记录源 master commit 与 skill blob、源反馈 ID 和 URL、已落地证据范围、适配器裁决和门禁结果；每个适配器的原始 I/O 留在私有临时目录中，该目录路径会写入通知和 `~/Library/Logs/dsh-code-review-maintainer/` 下的每日日志。维护 worktree 在每次运行后都会恢复为干净状态，避免操作员直接在维护副本中编辑。
+
+## 操作员如何处理候选 diff
+
+某次运行产出候选版本时，macOS 会发出一条带 `dsh-code-review-promote <timestamp>` 提示的通知。
+
+1. **根据 diff 本身作出判断。** 不要因为「评审者已经批准」就直接接受；维护者约定规定由操作员作出最终决定。检查清单是否膨胀、是否有历史叙述、是否根据单次事件作出无依据的外推，以及是否与现有 skill 或权威文档重复。
+
+   ```sh
+   ls ~/dsh-code-review-outputs/                         # every candidate ever produced
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.manifest.json
+   ```
+
+2. **与运行产物交叉核验。** 提升 manifest 会把每条拟议规则映射到源反馈和已落地证据；每个适配器的详细 I/O、共识和采纳证据位于本次运行的私有临时目录中（路径见日志）。至少抽查一个候选项：链接的人工评论是否确实支持新增规则？链接的 PR 是否确实采纳了它？
+
+3. **从三种处理方式中选择一种：**
+   - **丢弃。** 删除保存的候选版本。下一次运行会依据届时的当前 skill，重新考虑同一份反馈。
+
+     ```sh
+     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
+     ```
+   - **留待成批处理。** 如果更新很小，可以把候选版本留待与后续版本合并。源 skill 检查仍然适用；如果 `master` 先发生变化，请重新运行分析，或手动 rebase 并重新评审 diff。
+   - **提升。** 在仓库的干净 `master` checkout 中运行提升辅助工具。它会刷新 `master`、验证当前 skill 与记录的源 blob 一致、应用保存的 diff，并创建一份 draft PR，其正文列出原始反馈的 URL 或 ID、已落地的 commit 范围、发起这次更改的运行、检查以及操作员编辑。如果 skill 已发生漂移，它会停止而不是覆盖更新后的指导；操作员仍需在 GitHub 上评审 PR，并选择合并或关闭。
+
+     ```sh
+     cd ~/path/to/deepseek-harness   # clean master
+     dsh-code-review-promote 2026-07-16T02-00-00Z
+     ```
+
+4. **不要逐字提交适配器输出。** 提升过程中可以进行小幅编辑，例如收紧措辞、移除只有结合源 PR 上下文才有意义的示例、把规则并入现有规则。这些编辑是预期行为，也保留了工作流所依赖的「评审者判断」。合并前应在该分支上修订这些改动。
+
+## 运行未产出候选版本时
+
+只要每个非空分类阶段都至少产生一个有效的适配器结果，这就是常见情况。工具会在每日日志中记录「无候选版本」，不发送通知（避免提醒疲劳），然后继续。某天没有 skill 更新，说明工作流运行正常，而不是停滞。
+
+## 中断与交接
+
+该机制运行在一台机器上。操作员应随时处理以下中断：
+
+- **错过每日运行。** 2 日重叠窗口会自动覆盖一次漏跑；更长的间隔可通过设置 `DSH_CODE_REVIEW_SINCE=<Nd>` 手动运行包装脚本来恢复。重叠窗口具有幂等性：当前 skill 已包含的指导会被归类为 `covered`，不会再次成为候选项。
+- **适配器提供方中断。** 当两个评审命令解析为逐字节相同的可执行文件时，工具会拒绝运行。某个批次的适配器响应未通过 schema 或 ID 校验时，该批次会整体 fail-closed（其中每个条目都标记为不明确），运行则继续；原始输出会保留以便调试。如果任一适配器在某项操作的所有非空批次中都未产生有效结果，本次运行就会失败、写入失败记录并通知操作员；它绝不会把提供方完全中断折叠成「无候选版本」。
+- **交接给另一名维护者。** 新建一篇取代当前记录的后续 Agent Note：要么把机制移入仓库，要么记录新操作员的私有设置。不要暗中转交工具；Agent Note 的风险章节已把「单维护者关键人风险」列为交接必须记录决策的原因。
+
+## 操作员的私有设置位于何处
+
+工具源代码、评审适配器、提供方凭据和调度器属于操作员的私有基础设施，按设计位于本仓库之外（参见 Agent Note 的「机制位于何处」章节）。本实操手册和 Agent Note 描述的是**工作流保证什么**；这些保证**如何**实现则属于私有基础设施问题。如果你是新操作员，应以 Agent Note 的 `## Proposal` 各节作为实现依据。

package/dsh-docs/cookbook/responding-to-pr-review-on-a-stack.md

@@ -0,0 +1,32 @@
+# Responding to review across a stacked PR chain
+
+English | [中文](responding-to-pr-review-on-a-stack.zh.md)
+
+Review comments may target several PRs in a dependent stack (`A ← B ← C …`). Keep that chain linked through GitHub's official stacked-PR feature. This guide owns review-fix placement and propagation; the [dsh-merging-stacked-prs](../../.agents/skills/dsh-merging-stacked-prs/SKILL.md) skill owns linkage checks and landing.
+
+## Ground rules
+
+1. **One worktree per PR branch.** Each PR's fixes happen in that PR's own worktree; parallel fixes never share a checkout.
+2. **GitHub's stack object is authoritative.** Base branches establish the expected dependency order, while `PullRequest.stack` and `stackEntry.position` prove that GitHub recognizes it. Do not treat a matching branch chain as an official stack without checking those fields.
+3. **A fix lands on the PR that INTRODUCED the issue, then flows up-stack.** When a comment on PR `B` points at code `B` introduced, fix it on `B` and propagate `B` into `C` — even if `C` also carries the file. Originating the fix downstream leaves `B` shipping the unfixed code and hides the fix from `B`'s reviewer.
+4. **Each review fix remains a distinct commit.** A later rebase may change its OID, but do not amend a reviewed fix out of the branch history. Amend only your own not-yet-pushed, not-yet-reviewed work.
+5. **Choose merge-forward or rebase deliberately.** Both histories are allowed after review. A rewritten push must be lease-protected and must abort rather than overwrite a concurrently advanced remote head; raw `--force` is forbidden.
+
+## Resolve comments through the stack
+
+1. Triage every comment on the merits before acting: verify the claim against the code — a reviewer flagging the right symptom can still misdiagnose the cause.
+2. Map each accepted finding to its originating PR and fix it there.
+3. Propagate the fixed layer through every affected child in order:
+   - **Merge-forward:** merge the fixed parent branch into its child, validate the child, and continue upward. Preserve each in-progress checkpoint under the [incremental-retargeting decision](../../.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md).
+   - **Native cascading rebase:** use `gh stack rebase`, validate the rewritten layers, then publish with `gh stack push`; or use `gh stack sync`, which may publish first and therefore requires immediate post-sync validation under [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md).
+4. Treat delegated fixes as trust-but-verify: a sub-agent's report describes intent, not necessarily what landed. Re-run the gates yourself on the actual tree, and for a regression guard, prove it FAILS on the unfixed code (introduce the regression, watch red, revert) — a guard that passes both ways guards nothing. A sub-agent that reframes a problem as already handled is a signal to dig in personally.
+5. Reply in the review thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level comment, stating the fix and the current commit or head that carries it.
+6. After any rewritten push, re-read unresolved threads, approvals, mergeability, and checks. A force-pushed commit OID or outdated inline anchor is not current evidence that the finding remains resolved.
+7. Land only through the official stack procedure. If the PRs are not yet linked, the landing skill automatically links a same-author chain, asks before linking mixed authors, and hard-stops when native stack support is unavailable.
+
+## Verify
+
+- Every fixed PR's current diff contains the intended correction at the layer that introduced the issue.
+- GraphQL reports one official stack in the expected order, and each child diff against its parent shows only that child's changes.
+- Unresolved threads, approvals, mergeability, and checks were re-audited after every rewritten push.
+- The relevant gates pass on every affected PR in the stack, not just the top.

package/dsh-docs/cookbook/responding-to-pr-review-on-a-stack.zh.md

@@ -0,0 +1,32 @@
+# 在堆叠 PR 链中回应评审意见
+
+[English](responding-to-pr-review-on-a-stack.md) | 中文
+
+评审意见可能同时针对一条依赖堆叠（`A ← B ← C …`）中的多个 PR（Pull Request）。请通过 GitHub 官方的堆叠 PR 功能保持这条链的关联。本指南负责评审修复的归属与传播；[dsh-merging-stacked-prs](../../.agents/skills/dsh-merging-stacked-prs/SKILL.md) skill（技能）负责检查关联关系和落地。
+
+## 基本规则
+
+1. **每个 PR 分支一个 worktree。** 每个 PR 的修复在该 PR 自己的 worktree 中进行；并行修复绝不共享同一个 checkout。
+2. **GitHub 的 stack 对象是权威依据。** base 分支确定预期的依赖顺序，`PullRequest.stack` 和 `stackEntry.position` 则证明 GitHub 已识别该堆叠。未经检查这些字段，不得仅凭分支链吻合就将其视为官方堆叠。
+3. **修复落在引入问题的那个 PR 上，然后沿堆叠向上流动。** 当 PR `B` 上的评论指向 `B` 引入的代码时，在 `B` 上修复，再将 `B` 的变更传播到 `C`，即使 `C` 也包含该文件。把修复发起在下游会导致 `B` 带着未修复的代码交付，并对 `B` 的评审者隐藏修复。
+4. **每项评审修复都保留为独立 commit。** 后续 rebase 可能改变其 OID，但不得通过 amend 把已经评审的修复从分支历史中抹去。只有你自己尚未推送且尚未评审的工作才可以 amend。
+5. **明确选择 merge-forward 或 rebase。** 评审后允许采用这两种历史更新方式。改写历史的推送必须受 lease 保护；如果远端 head 在此期间前移，操作必须中止，不得将其覆盖。禁止直接使用 `--force`。
+
+## 沿堆叠解决评审意见
+
+1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。
+2. 将每个被接受的发现映射到引入该问题的 PR，并在那里修复。
+3. 将修复后的层按顺序传播到每个受影响的子 PR：
+   - **Merge-forward：** 将修复后的父分支合并到其子分支，验证子分支，然后继续沿堆叠向上传播。依照[增量更新 base 的决策](../../.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md)，保留每个正在处理的检查点。
+   - **原生级联 rebase：** 使用 `gh stack rebase`，验证所有已改写的层，然后通过 `gh stack push` 发布；也可以使用 `gh stack sync`，该命令可能先发布，因此必须按照 [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md) 在同步后立即验证。
+4. 委派的修复需要信任但验证：subagent 的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
+5. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及当前承载修复的 commit 或 head。
+6. 每次改写推送后，都要重新读取未解决线程、批准状态、可合并性和检查结果。经 force-push 改写的 commit OID 或已过时的内联锚点，都不足以证明该发现当前仍处于已解决状态。
+7. 仅可通过官方堆叠流程落地。如果这些 PR 尚未关联，落地 skill 会自动关联作者相同的链；如果作者不同，则先询问用户；如果原生堆叠支持不可用，则硬性停止流程。
+
+## 验证
+
+- 每个已修复 PR 的当前 diff 都在引入问题的那一层包含预期修正。
+- GraphQL 报告的官方堆叠只有一个且顺序符合预期；每个子 PR 相对于父 PR 的 diff 只显示该子 PR 自身的变更。
+- 每次改写推送后，均重新审计了未解决线程、批准状态、可合并性和检查结果。
+- 相关门禁在堆叠中的每个受影响 PR 上都通过，而不仅仅是顶部。

package/dsh-docs/cordis-api/context.md

@@ -0,0 +1,364 @@
+<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
+     Run `pnpm run gen-cordis-catalog` to regenerate. -->
+
+# Context
+
+The context is the core Cordis object: every service, event, and lifecycle API is reached through `ctx`. Event methods are documented on [Events](events.md), effects and the current fiber on [Fiber](fiber.md), and plugin loading on [Registry](registry.md).
+
+Root and child dependency containers for Cordis plugins.
+
+A context is a proxy: normal property reads go through the service resolver, while `extend()`, `isolate()`, and `intercept()` create scoped child contexts without mutating their parent.
+
+[Source](../../vendor/cordis/src/context.ts#L42)
+
+### ctx.extend(meta?)
+
+```ts cordis-catalog
+/**
+ * Create a child context with extra metadata on top of the current scope.
+ *
+ * The child prototypally inherits every property of this context; own
+ * properties of `meta` shadow the inherited ones. The parent is not mutated.
+ *
+ * @param meta — own properties (including symbol keys) to define on the child.
+ * @returns a child context inheriting from this one.
+ */
+extend(meta = {}): this
+```
+
+Create a child context with extra metadata on top of the current scope.
+
+The child prototypally inherits every property of this context; own properties of `meta` shadow the inherited ones. The parent is not mutated.
+
+- `meta` — own properties (including symbol keys) to define on the child.
+
+**Returns** a child context inheriting from this one.
+
+[Source](../../vendor/cordis/src/context.ts#L99)
+
+### ctx.isolate(name, label?)
+
+```ts cordis-catalog
+/**
+ * Create a child context with an independent service scope for `name`.
+ *
+ * Below the returned context, reads and writes of the service `name`
+ * resolve against the new label instead of the parent's, so a different
+ * implementation can be provided without affecting the parent scope.
+ * Passing the same `label` to two `isolate()` calls joins their scopes.
+ *
+ * @param name — the service name to isolate.
+ * @param label — scope label to join; defaults to a fresh unique symbol.
+ * @returns a child context whose `name` service resolves in the new scope.
+ */
+isolate(name: string, label?: symbol)
+```
+
+Create a child context with an independent service scope for `name`.
+
+Below the returned context, reads and writes of the service `name` resolve against the new label instead of the parent's, so a different implementation can be provided without affecting the parent scope. Passing the same `label` to two `isolate()` calls joins their scopes.
+
+- `name` — the service name to isolate.
+- `label` — scope label to join; defaults to a fresh unique symbol.
+
+**Returns** a child context whose `name` service resolves in the new scope.
+
+[Source](../../vendor/cordis/src/context.ts#L121)
+
+### ctx.intercept(name, config)
+
+```ts cordis-catalog
+/**
+ * Add service-specific intercept config for plugins started below this
+ * context.
+ *
+ * Plugins loaded under the returned context see `config` merged into the
+ * service's resolved config (ancestor entries first; see
+ * `Service[symbols.resolveConfig]`). The parent context is not affected.
+ *
+ * @param name — the service name whose config to intercept.
+ * @param config — the intercept config to merge for that service.
+ * @returns a child context carrying the additional intercept entry.
+ */
+intercept<K extends InjectKey>(name: K, config: Context[K] extends { [symbols.config]: infer T } ? T : never): this
+intercept(name: string, config: any): this
+```
+
+Add service-specific intercept config for plugins started below this context.
+
+Plugins loaded under the returned context see `config` merged into the service's resolved config (ancestor entries first; see `Service[symbols.resolveConfig]`). The parent context is not affected.
+
+- `name` — the service name whose config to intercept.
+- `config` — the intercept config to merge for that service.
+
+**Returns** a child context carrying the additional intercept entry.
+
+[Source](../../vendor/cordis/src/context.ts#L139)
+
+### ctx.root
+
+```ts cordis-catalog
+/** The root context of the application (every child context shares it). @experimental */
+root: this
+```
+
+The root context of the application (every child context shares it). @experimental
+
+[Source](../../vendor/cordis/src/context.ts#L22)
+
+### ctx.baseUrl
+
+```ts cordis-catalog
+/** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
+baseUrl?: string
+```
+
+Base URL used to resolve relative plugin/module specifiers, if the runtime sets one.
+
+[Source](../../vendor/cordis/src/context.ts#L24)
+
+### ctx.events
+
+```ts cordis-catalog
+/** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */
+events: EventsService
+```
+
+The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...).
+
+[Source](../../vendor/cordis/src/context.ts#L26)
+
+### ctx.logger
+
+```ts cordis-catalog
+/** The logging service. Call `ctx.logger(name)` for a named logger. */
+logger: LoggerService
+```
+
+The logging service. Call `ctx.logger(name)` for a named logger.
+
+[Source](../../vendor/cordis/src/context.ts#L28)
+
+### ctx.reflect
+
+```ts cordis-catalog
+/** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */
+reflect: ReflectService
+```
+
+The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...).
+
+[Source](../../vendor/cordis/src/context.ts#L30)
+
+### ctx.registry
+
+```ts cordis-catalog
+/** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */
+registry: RegistryService
+```
+
+The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`).
+
+[Source](../../vendor/cordis/src/context.ts#L32)
+
+## Static members
+
+### Context.effect
+
+```ts cordis-catalog
+/** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */
+static readonly effect: unique symbol
+```
+
+Symbol key under which a disposer exposes its EffectMeta diagnostics tree.
+
+[Source](../../vendor/cordis/src/context.ts#L44)
+
+### Context.filter
+
+```ts cordis-catalog
+/** Symbol key for a context's listener filter, consulted on every event dispatch. */
+static readonly filter: unique symbol
+```
+
+Symbol key for a context's listener filter, consulted on every event dispatch.
+
+[Source](../../vendor/cordis/src/context.ts#L46)
+
+### Context.isolate
+
+```ts cordis-catalog
+/** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */
+static readonly isolate: unique symbol
+```
+
+Symbol key of the isolation map (see the `Context[symbols.isolate]` property).
+
+[Source](../../vendor/cordis/src/context.ts#L48)
+
+### Context.intercept
+
+```ts cordis-catalog
+/** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */
+static readonly intercept: unique symbol
+```
+
+Symbol key of the intercept map (see the `Context[symbols.intercept]` property).
+
+[Source](../../vendor/cordis/src/context.ts#L50)
+
+### Context.is(value)
+
+```ts cordis-catalog
+/**
+ * Returns true for Cordis context proxies and context prototypes.
+ *
+ * Works across realms and across multiple copies of cordis, because the
+ * brand is keyed by a global symbol rather than by `instanceof`.
+ *
+ * @param value — the value to test.
+ * @returns `true` if `value` is a Cordis context, narrowing its type.
+ */
+static is(value: any): value is Context
+```
+
+Returns true for Cordis context proxies and context prototypes.
+
+Works across realms and across multiple copies of cordis, because the brand is keyed by a global symbol rather than by `instanceof`.
+
+- `value` — the value to test.
+
+**Returns** `true` if `value` is a Cordis context, narrowing its type.
+
+[Source](../../vendor/cordis/src/context.ts#L61)
+
+## Service store and mixins
+
+### ctx.get(name, strict?)
+
+```ts cordis-catalog
+/**
+ * Read a service from the store without the inject requirement.
+ *
+ * @param name — the service name.
+ * @param strict — when `true` (default), only return implementations
+ * whose providing fiber is currently active.
+ * @returns the service value, or `undefined` when not (yet) provided.
+ */
+get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
+get(name: string, strict?: boolean): any
+```
+
+Read a service from the store without the inject requirement.
+
+- `name` — the service name.
+- `strict` — when `true` (default), only return implementations whose providing fiber is currently active.
+
+**Returns** the service value, or `undefined` when not (yet) provided.
+
+[Source](../../vendor/cordis/src/reflect.ts#L17)
+
+### ctx.set(name, value)
+
+```ts cordis-catalog
+/**
+ * Overwrite a provided service's value.
+ *
+ * Only the fiber that provided the service may set it; setting an
+ * unprovided name throws.
+ *
+ * @param name — the service name.
+ * @param value — the new service value.
+ */
+set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
+set(name: string, value: any): void
+```
+
+Overwrite a provided service's value.
+
+Only the fiber that provided the service may set it; setting an unprovided name throws.
+
+- `name` — the service name.
+- `value` — the new service value.
+
+[Source](../../vendor/cordis/src/reflect.ts#L29)
+
+### ctx.provide(name, value)
+
+```ts cordis-catalog
+/**
+ * Register a service implementation owned by the current fiber.
+ *
+ * The service becomes visible to dependents in the same isolation scope
+ * once the fiber is active; it is unregistered (waking dependents) when
+ * the returned disposer runs or the fiber unloads. Throws if the name is
+ * already provided in this scope or declared as an accessor.
+ *
+ * @param name — the service name.
+ * @param value — the service value.
+ * @returns a disposer that unregisters the service.
+ */
+provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
+provide(name: string, value?: any): () => void
+```
+
+Register a service implementation owned by the current fiber.
+
+The service becomes visible to dependents in the same isolation scope once the fiber is active; it is unregistered (waking dependents) when the returned disposer runs or the fiber unloads. Throws if the name is already provided in this scope or declared as an accessor.
+
+- `name` — the service name.
+- `value` — the service value.
+
+**Returns** a disposer that unregisters the service.
+
+[Source](../../vendor/cordis/src/reflect.ts#L44)
+
+### ctx.accessor(name, options)
+
+```ts cordis-catalog
+/**
+ * Define a computed context property backed by get/set hooks.
+ *
+ * The accessor is removed when the current fiber unloads. Throws if the
+ * name is already declared.
+ *
+ * @param name — the context property name.
+ * @param options — the `get` hook and optional `set` hook.
+ */
+accessor(name: string, options: Omit<Property.Accessor, 'type'>): void
+```
+
+Define a computed context property backed by get/set hooks.
+
+The accessor is removed when the current fiber unloads. Throws if the name is already declared.
+
+- `name` — the context property name.
+- `options` — the `get` hook and optional `set` hook.
+
+[Source](../../vendor/cordis/src/reflect.ts#L56)
+
+### ctx.mixin(name, mixins)
+
+```ts cordis-catalog
+/**
+ * Expose selected members of a service directly on `ctx`.
+ *
+ * Each mixed-in key becomes an accessor that forwards to the service
+ * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
+ * Mixins are removed when the current fiber unloads.
+ *
+ * @param name — the context property holding the source service.
+ * @param mixins — keys to forward, or a source-key → ctx-key map.
+ */
+mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
+mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void
+```
+
+Expose selected members of a service directly on `ctx`.
+
+Each mixed-in key becomes an accessor that forwards to the service (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`. Mixins are removed when the current fiber unloads.
+
+- `name` — the context property holding the source service.
+- `mixins` — keys to forward, or a source-key → ctx-key map.
+
+[Source](../../vendor/cordis/src/reflect.ts#L67)