better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch02-plugin-basics.md

@@ -0,0 +1,127 @@
+# Chapter 2: Plugin Development Basics
+
+## Core Idea
+A dsh plugin is a Cordis module — `apply(ctx)` plus declarative `name` / `inject` / `Config` exports — where every `ctx` registration is a lifecycle-managed effect; shipping it means packaging a patch layer (bundle) that a profile composes in a fixed order.
+
+## Frameworks Introduced
+- **Plugin apply contract**: a TypeScript module exporting `name`, optional `inject`, and `apply(ctx)` (or object/class default export). The framework calls `apply` only after every injected service is ready.
+  - When to use: function form covers most cases; class form (`extends Service`, `static inject`, `super(ctx, 'svc')`) when the plugin provides a service to other plugins.
+  - How: dev overlay `- insert: [{id, name: '/absolute/path/src/my-plugin.ts'}]` → `pnpm dsh web --patch ./cordis.yml`.
+- **Schemastery Config schema**: `export interface Config` + `export const Config: Schema<Config> = Schema.object({...})` with `.default()` / `.required()` / `.union()`.
+  - When to use: anything two deployments may want to set differently — Harness requires this as a config field.
+  - How: `apply(ctx, config)` receives validated, default-filled config. Cordis validates while loading; invalid config fails the load with an actionable error. Config values arrive via the plugin row's `config:` key.
+- **`defineTool` DSL** (`@deepseek-ai/dsh-tools`): declarative tool — `parameters` (arg inference/validation), `output.schema` (canonical value type), `output.render` (value → model-facing content), `execute`.
+  - When to use: exposing any model-callable capability.
+  - How: `export const inject = ['tools']`, then `ctx.tools.register(defineTool({...}))`.
+- **Bundle manifest**: npm package declaring `dsh: { bundle: { patch: './cordis.patch.yml' } }`; patch rows reference the package by name so Node resolution finds the installed code. Answers "what does this package contribute?"
+- **Profile manifest**: `$DSH_HOME/profiles/<name>/` — `package.json` with ordered `dsh.profile.bundles` + a user `cordis.patch.yml` layer. Answers "which bundles compose this setup, in what order?" Created and maintained by `dsh plugin`, never written by hand.
+- **App-owned command line**: a provider plugin with `inject = ['cmdlineArgs']` calling `parseCmdline` from `@deepseek-ai/dsh-cmdline` with its own commander program, publishing an app-owned service from the program's action.
+
+## Key Concepts
+- **`ctx.effect(() => disposer)`**: escape hatch for resources `ctx` doesn't track (sockets, intervals); the returned function runs on unload.
+- **Automatic cleanup**: `ctx.on`, `ctx.tools.register`, `ctx.llm.registerAdapter`, `ctx.effect` are all undone at unload — no manual `removeListener`/`clearInterval`.
+- **HMR**: a config or source edit hot-replaces the plugin (unload old → load new → run new `apply`); old registrations never leak.
+- **Layer order**: bundle patches in `dsh.profile.bundles` list order → profile `cordis.patch.yml` → `$DSH_HOME/cordis.patch.yml` → `--patch` overlays in argv order. Later layers win per row.
+- **Row override**: a patch replaces a row's entire `config` value, never deep-merging keys — restate every key the row needs.
+- **In-box bundles** (`@deepseek-ai/dsh-base`): always resolve from the dsh installation itself; pnpm manages only out-of-tree packages.
+- **`prepare` script**: what pnpm runs after a git install; must be self-contained (no sibling-monorepo assumptions). turtle-ui's dedicated tsdown config is the working example.
+- **`allowBuilds`**: pnpm ≥10 gate for a git dependency's build scripts, keyed in the profile's `pnpm-workspace.yaml` (`allowBuilds: { 'dsh-hello-plugin': true }`); granting it = permission to execute the package's code on your machine at install time.
+- **Plain dependency**: a package without `dsh.bundle` installs with a warning and activates no layer — the library format for code that plugin packages import.
+
+## Mental Models
+- Think of a plugin as a block scoped to `apply`: when the block exits (unload, HMR, dependency loss), everything it registered vanishes.
+- Think of a bundle as "one patch layer in an npm package" and a profile as "an ordered list of such layers with user patches on top"; a bundle is authored and distributed, a profile is booted — nothing is both.
+- Use absolute paths in dev overlays because a patch contributes configuration only — it never changes the directory the loader resolves module paths from.
+- Treat `dsh --profile <name> --dump-config` as the no-boot layer inspector: each bundle shows as a `# == <pkg>` section.
+
+## Anti-patterns
+- **Plain-object `Config` export**: doesn't implement the Standard Schema interface Cordis requires.
+- **Hardcoded tunables**: if `cordis.yml` cannot change the value without a code edit, it must become a config field.
+- **Partial row override**: patching only the changed key drops the rest of the row's config (whole-value replacement).
+- **Relative plugin path in an overlay**: loader resolves from the profile directory, not the patch file's location.
+- **Git install without `prepare`**: sources arrive unbuilt — a TS package loads without its `lib/`.
+- **Unpinned git adds with `allowBuilds`**: a later push silently changes what executes at install time; pin `github:you/pkg#<sha>` and only allowlist source you trust.
+
+## Code Examples
+Config + tool in one plugin:
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'greet-tool'
+export const inject = ['tools']
+
+export interface Config { greeting: string; maxRetries: number }
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello'),
+  maxRetries: Schema.number().default(3),
+})
+
+export function apply(ctx: Context, config: Config) {
+  ctx.tools.register(defineTool({
+    name: 'greet',
+    description: 'Greet someone by name.',
+    parameters: { name: { type: 'string', required: true, description: 'The name to greet' } },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) { return `${config.greeting}, ${args.name}!` },
+  }))
+}
+```
+Bundle package + patch:
+```json
+{ "name": "dsh-hello-plugin", "version": "0.1.0", "type": "module", "main": "index.js",
+  "files": ["index.js", "cordis.patch.yml"],
+  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }
+```
+```yaml
+- insert:
+    - id: hello
+      name: dsh-hello-plugin     # package name, not a path
+```
+Surface-bundle flag row (rows stay dormant under `--help` because the provider publishes no service):
+```yaml
+- id: my-app
+  name: '@example/my-app'
+  inject: [myAppStartup]
+  config:
+    port: !!js ctx.myAppStartup.port ?? 8080
+```
+Install / inspect / remove:
+```sh
+dsh plugin --profile demo add ./hello-plugin   # pnpm link + append to dsh.profile.bundles
+dsh --profile demo --dump-config               # shows the "# == dsh-hello-plugin" layer
+dsh plugin --profile demo remove dsh-hello-plugin
+```
+
+## Reference Tables
+| Plugin form | Export | Use when |
+|---|---|---|
+| Function | `export const name` / `inject` + `export function apply` | most cases |
+| Object | `export default { name, inject, apply }` | grouping options |
+| Class | `export default class extends Service` | providing a service to other plugins |
+
+| Distribution | User command | Build happens |
+|---|---|---|
+| npm | `dsh plugin --profile demo add your-package` | at `pnpm publish` (ship built `lib/`) |
+| tarball | `dsh plugin add ./hello-plugin-0.1.0.tgz` | at `pnpm pack` |
+| git | `dsh plugin add github:you/pkg#<sha>` | author's `prepare` + user's `allowBuilds` |
+
+Layer composition (later wins per row): 1. bundle patches in `bundles` list order (`@deepseek-ai/dsh-base` first) → 2. profile `cordis.patch.yml` → 3. home `$DSH_HOME/cordis.patch.yml` → 4. `--patch` overlays in argv order. App arguments are not a patch layer.
+
+## Key Takeaways
+1. `dsh plugin --profile <name> <args...>` just forwards to pnpm in the profile directory — every pnpm verb works; first use initializes the profile with `@deepseek-ai/dsh-base` first in `bundles`.
+2. `execute` returns the canonical value declared by `output.schema`; `output.render` converts that value into model-facing content blocks.
+3. Fail loudly at load: self-contained constraints belong in the schema; constraints referencing live services or registered resources need dependency injection (Ch 3).
+4. Users can override your rows in their profile patch without touching your package — prefer defaults they'll keep and let the schema carry the rest.
+5. A surface bundle needs no launcher change for its own flags: all plugins receive the same immutable post-launcher args snapshot, and multiple plugins may parse it independently.
+6. Loader evaluates a row's `!!js` config only after that row's ordinary injections resolve — config expressions can read injected services with a deployment fallback beside them.
+
+## Connects To
+- **Ch 3**: lifecycle, events, services, and the three-role capability split build directly on `apply` / `inject` / `ctx.effect`.
+- **Ch 4 / Ch 5**: Cordis fundamentals and API own the loader, Fiber, and patch semantics summarized here.
+- **Ch 11**: full tool-authoring reference — nested schemas, canonical values, background work, policy hooks, PTC mode, UI cards.
+- **Ch 10**: the generated config catalog is derived from these `Config` schemas.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch03-plugin-framework-practice.md

@@ -0,0 +1,120 @@
+# Chapter 3: Plugin Framework & Practice
+
+## Core Idea
+Cordis runs each plugin in a Fiber whose dependency-driven lifecycle makes every registration self-cleaning; on that runtime, dsh's extension architecture is two contracts — the three-role capability split (Definition / Provider / Consumer) and the `LlmAdapter` streaming protocol.
+
+## Frameworks Introduced
+- **Fiber state machine**: `PENDING → LOADING → ACTIVE` (or `FAILED`); `ACTIVE → UNLOADING → DISPOSED`. `inject` gates PENDING→LOADING; `apply` throwing → FAILED; a required service disappearing unloads the plugin automatically and reloads it when the service returns.
+  - When to use: reasoning about any plugin's load, HMR, or teardown behavior.
+  - How: declare `export const inject = ['tools', 'llm']`; inside `apply` every injected service is ready.
+- **Service extension**: `class MetricsService extends Service { static inject = ['llm']; constructor(ctx) { super(ctx, 'metrics') } }` mounts `ctx.metrics`; typed via `declare module '@deepseek-ai/cordis' { interface Context { metrics: MetricsService } }`.
+  - When to use: exposing a capability to other plugins; required deps via `inject`, optional via `const m = ctx.get('metrics'); m?.record(...)`.
+- **Event modes**: `emit` (synchronous broadcast, return values ignored) · `bail` (first result other than `null`/`false`/`undefined` wins) · `serial` (registration order, async awaited, first non-null stops) · `waterfall` (each listener wraps the downstream result; must call `next()`).
+  - When to use: notification → emit; veto/policy check → bail; ordered setup → serial; middleware/interception → waterfall.
+- **Three-role capability design**: Service Definition (abstract class + Request/Result types) / Service Provider (subclass, `apply(ctx) { ctx.plugin(MyCapLocal) }`) / Consumer (`inject: ['tools', 'myCap']`). The complete capability is its seam; no individual role is.
+  - When to use: only when roles need independent evolution or provider replacement — Bash = `dsh-shell` / `dsh-bash-local` / `dsh-tool-bash`.
+  - How: swap providers by replacing one `cordis.yml` row; Provider and Consumer never depend on each other, only on the Definition.
+- **`LlmAdapter` contract**: extend `LlmAdapter` from `@deepseek-ai/dsh-llm`, implement `async *stream(options: GenerateOptions): AsyncIterable<StreamChunk>`, register with `ctx.llm.registerAdapter(providerNames, adapter)` under `inject = ['llm']`; optionally override `resolveModel()` and `listModels()`.
+- **Dynamic Cordis** (`@deepseek-ai/dsh-tool-cordis`): agent tool that inspects the live Cordis process and mounts/unmounts model-authored plugins in memory — temporary (gone on unmount or exit), and may affect other sessions in the same process.
+
+## Key Concepts
+- **Disposer semantics**: unload invokes disposers in reverse registration order, but multiple async disposers run concurrently with no serial guarantee — put order-dependent cleanup in a single `ctx.effect()` and await its steps serially.
+- **`ctx.plugin(child)`**: nested Fiber inheriting the parent context with an independent lifecycle; `await fiber.dispose()` guarantees (1) registrations removed, (2) child plugins recursively unloaded, (3) promise resolves after all async cleanup.
+- **Declaration merging**: `interface Events` (payload types) and `interface Context` (service types) — the type-safe extension mechanism for both events and services.
+- **Cordis events vs session events**: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, `session/event` are Cordis events (`namespace/action`); `turn/*`, `step/*`, `tool/call`, `tool/result`, `compaction/*` are durable session-event types — observe them by listening to `session/event` and inspecting `event.type`.
+- **Service isolation**: `cordis-plugin-group` rows with `group: true` + `isolate: { shell: true }` + nested `config` list give separate plugin groups private instances of the same service.
+- **`resolve(request): Spec`**: explicit default-resolution step in a capability — prefer it over hiding `?? default` expressions inside `run()`.
+- **StreamChunk protocol**: `block-start` / `text-delta` / `tool-call-delta` / `block-end` / `usage` / `finish`; every `block-start` has a matching `block-end`; `index` increases from 0; `usage` before `finish`; `finish` is last (`reason.kind: 'stop' | 'tool-calls'`).
+- **`LlmError`**: stable-code error type for transport/protocol failures; the agent loop preserves message and code — it does not convert ordinary `Error`.
+- **`attributionHeaders()` / `options.signal`**: merged into / forwarded on every provider HTTP request an adapter makes.
+- **`brandString<ToolCallId>`**: branded id type carried by tool-call deltas and blocks.
+
+## Mental Models
+- Think of `inject` as a dataflow dependency: readiness gates loading, loss triggers disposal, return triggers reload — never hand-guard service access.
+- Think of an adapter as a translator: `GenerateOptions` (provider-neutral: model, reasoning-effort id, history, system prompt, tool schemas, params, stop sequences, abort signal) → provider request; provider stream → `StreamChunk`s. A field the provider can't honor throws `LlmError`, never a silent drop.
+- Treat the three-role split as an option, not a rule: a simple tool plugin is one package; split only for real replaceability.
+- Think of `resolveModel` as capability advertisement: it returns identity + `context` + `reasoning` metadata (ordered opaque ids, display names, optional default); the service validates the aggregate and rejects unsupported explicit efforts before `stream()`.
+
+## Anti-patterns
+- **Listening on `tool/call` or `compaction/*` as Cordis events**: they are session-log record types; only `session/event` fires.
+- **Waterfall listener omitting `next()` by accident**: short-circuits the pipeline by design — interception is the feature, not an error path.
+- **Splitting the three roles preemptively**: separate packages only when independent evolution or provider replacement is real.
+- **Throwing plain `Error` from an adapter**: the loop won't map it; diagnostics and policy lose the stable code.
+- **Promoting reasoning-effort ids into a core enum**: preserve the adapter's authoritative opaque selectable list, including `off` when the upstream capability API returns it.
+- **Counting on cross-effect disposal ordering**: concurrent async disposers have no serial completion guarantee.
+
+## Code Examples
+Adapter skeleton (registration + chunk protocol + error contract):
+```ts
+import { LlmAdapter, LlmError, attributionHeaders,
+         type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+class MyAdapter extends LlmAdapter {
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const res = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...attributionHeaders() },
+      body: JSON.stringify({ model: options.model, messages: options.messages }),
+      ...options.signal ? { signal: options.signal } : {},
+    })
+    if (!res.ok) throw new LlmError(`Provider API error: ${res.status}`, 'PROVIDER_HTTP_ERROR')
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    yield { type: 'text-delta', index: 0, text: 'Hello world' }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: 'Hello world' } }
+    yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
+    yield { type: 'finish', reason: { kind: 'stop' } }   // or 'tool-calls'
+  }
+}
+export const inject = ['llm']
+export function apply(ctx: Context, config: Config) {
+  ctx.llm.registerAdapter(config.providers, new MyAdapter(config.apiKey))
+}
+```
+Tool-call chunk (arguments stream as raw JSON text):
+```ts
+yield { type: 'tool-call-delta', index: 1, id: brandString<ToolCallId>('call-123'),
+        name: 'bash', argumentsDelta: '{"command":"ls"}' }
+```
+Typed events:
+```ts
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    'my-plugin/ready': (payload: { id: string }) => void
+    'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
+  }
+}
+```
+Three-role wiring — Definition: `export abstract class MyCapService extends Service` + `interface Context { myCap: MyCapService }` + `abstract execute(request): Promise<MyCapResult>`; Provider: `class MyCapLocal extends MyCapService` registered via `ctx.plugin(MyCapLocal)`; Consumer: tool with `inject: ['tools', 'myCap']` calling `await ctx.myCap.execute({ input })`. Compose: one `cordis.yml` row per package; replace the provider row to swap implementations.
+
+## Reference Tables
+| Fiber state | Meaning |
+|---|---|
+| PENDING | declared; required dependencies not ready |
+| LOADING | dependencies ready; `apply` running |
+| ACTIVE | running |
+| FAILED | `apply` threw an error |
+| UNLOADING / DISPOSED | disposing resources / fully unloaded |
+
+| Mode | Order | Stops when | Result |
+|---|---|---|---|
+| emit | all, sync | never | ignored |
+| bail | registration | first non-null/false/undefined | that value |
+| serial | registration, awaited | first non-null/false/undefined | that value |
+| waterfall | chain via `next()` | a listener omits `next()` | wrapped downstream value |
+
+Adapter facts: `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is an adapter-owned id with no lifecycle registration; `listModels()` advertises choices to selectors; `resolveModel(provider, model, signal?)` honors the optional signal so cancellation and disposal reach quiescence; omitting `reasoning` metadata means the model has no selectable reasoning-effort capability.
+
+## Key Takeaways
+1. All `ctx.*` registrations are effects — HMR, dependency loss, and `fiber.dispose()` clean up without manual teardown; use `ctx.effect` only for untracked resources.
+2. Pick the event mode by contract: notification (emit), veto (bail), ordered setup (serial), wrapping/interception (waterfall).
+3. The Service Definition owns Request/Result types; Providers and Consumers depend only on it — swapping providers is a one-row `cordis.yml` change.
+4. Reference implementations: `packages/llm/llm-deepseek/` (OpenAI-compatible format) and `packages/llm/llm-pi-ai/` — the same harness contract over different provider SDKs.
+5. The generated `cordis-surface` regions on subsystem pages record complete event signatures and modes — consult them and the service's TypeScript interface instead of maintaining a second static list.
+6. Dynamic Cordis plugins are in-memory and process-wide: ephemeral by design, so never rely on them for durable composition.
+
+## Connects To
+- **Ch 4 / Ch 5**: Cordis fundamentals and the full API beneath the lifecycle/events/services summarized here.
+- **Ch 7**: capability seams — the built-in three-role families and package links.
+- **Ch 14**: the agent loop consumes `LlmError` codes and reasoning metadata.
+- **Ch 17**: LLM streaming subsystem owns the complete chunk/adapter pipeline.
+- **Ch 11**: tool-authoring reference (nested schemas, policy hooks, UI cards) for the consumer role.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch04-cordis-fundamentals.md

@@ -0,0 +1,129 @@
+# Chapter 4: Cordis Fundamentals (Primer + Tutorial)
+
+## Core Idea
+Cordis is the vendored plugin framework underneath dsh: every capability — tools, LLM adapters, the agent loop itself — is a plugin mounted into a shared `Context`, composed by a `cordis.yml` file. A plugin describes what it contributes (services, events, effects); the config file composes the application.
+
+## Frameworks Introduced
+- **Plugin = `{ name?, inject?, Config?, apply(ctx, config) }`**: three accepted shapes — function plugin (most common), object plugin with `apply` method, class plugin (`Service` subclass).
+  - When to use: function form until you need to expose a service; then `extends Service` with `super(ctx, 'name')`.
+  - How: module exports `apply` (plus optional `name` display metadata); the Loader resolves it from a `cordis.yml` entry `name:` field (module specifier: relative path or npm package).
+- **Service provide/consume**: a named capability one plugin provides (`ctx.<key>`) and others consume via `inject`.
+  - When to use: any shared capability — harness's `ctx.tools`, `ctx.llm`, `ctx.agents` are services.
+  - How: provider mounts a `Service` subclass (`super(ctx, 'greeter')` registers as `ctx.greeter`); consumer declares `export const inject = ['greeter']` — Cordis holds it PENDING until the service exists, so `apply` sees it ready. Load order comes from `inject`, never YAML position.
+- **Typed events via declaration merging**: `declare module '@deepseek-ai/cordis' { interface Events { 'ns/action'(args): void } }` declares name + listener signature; generates no runtime code.
+  - When to use: announce something without knowing listeners (tool results, model requests, approval decisions).
+  - How: `ctx.emit(name, ...args)`; listen with `ctx.on(name, listener)` (an effect — auto-removed on unload). Event names use `namespace/action` convention.
+- **Effect/disposer cleanup model**: every registration is a reversible effect, undone when the owning plugin unloads.
+  - When to use: any resource — Cordis-managed APIs (`ctx.on`, `ctx.plugin`, service/harness registrations like `ctx.tools.register`) are already effects; wrap unmanaged resources (timers, connections, watchers) in `ctx.effect(() => { ...acquire; return () => release })`.
+  - How: disposers run in reverse registration order; async disposers run concurrently — if teardown order matters, keep steps in one disposer and await them there.
+- **Config schema + static declarations**: exported `Config` is both a TS interface and a runtime schema; validated before `apply` runs.
+  - When to use: any `cordis.yml` entry `config:` block.
+  - How: Schemastery `Schema.object({...})` with `.default()`s — `apply` always receives complete, validated config; invalid config → fiber FAILED, loud `ValidationError` (never half-started).
+- **Composition & HMR**: `cordis.yml` entries carry `{id, name, config, inject, disabled}`; HMR = unload + reload a plugin on file save.
+  - When to use: editing plugins or the config file at dev time; `@deepseek-ai/cordis-plugin-hmr` (needs `logger-console` + `timer` plugins, runs under tsx).
+  - How: give entries explicit `id`s — the loader diffs by `id`; an id-less entry gets a fresh generated id each read, so any config edit remounts it as removed-plus-added. `disabled: true` unmounts without deleting the entry. Groups nest entries that load/unload as one unit; `isolate` gives a group its own instance of a service name.
+- **Loader `!!js` expressions**: `@deepseek-ai/cordis-plugin-include` parses `!!js` into expression nodes.
+  - When to use: config values computed at load time (e.g. `greeting: !!js process.env.DEMO_GREETING ?? 'Hello'`) or gating rows by environment.
+  - How: works only inside `config` (evaluated after declared injections activate, against that plugin's context) and in `disabled` (evaluated against loader context at every mount decision). Other metadata stays literal.
+
+## Key Concepts
+- **Context (`ctx`)**: the object `apply` receives; the repository of services through which the plugin registers everything it contributes.
+- **Fiber**: the runtime handle for one loaded plugin instance; `ctx.plugin(fn)` returns it, `fiber.dispose()` resolves after all cleanup.
+- **`inject`**: hard service requirements; re-checked live — if a required service disappears, dependents unload and reload when it returns (this is how service replacement works in config).
+- **PENDING**: legitimate wait state — plugin's `inject` names a service nobody provides; prints nothing, keeps no event loop alive (app exits 0 silently).
+- **Dispatch mode**: part of an event's public contract (`@mode` tag); decides awaitedness, order, and return semantics.
+- **Waterfall veto**: a listener returning without calling `next()` short-circuits the chain (innermost default never runs).
+- **Declaration merging**: TS `declare module` blocks add to `Context`/`Events` interfaces for typechecking only; consumers pull them in via `import type {} from './provider.ts'`.
+- **`ctx.get('name')`**: optional-dependency probe — `undefined` when no provider; the plugin still runs (vs `inject` for hard requirements).
+- **Service namespace**: one flat namespace per application; harness claims plain names (`tools`, `llm`) — prefix your own distinctively.
+
+## Mental Models
+- Think of `cordis.yml` as the application: there is no framework bootstrap code in your file; the dsh base profile is just a longer plugin composition that deployment overlays patch.
+- Use `inject` (not list position) when plugins must start in an order — entries start concurrently; dependencies, not file order, decide startup.
+- Think of a waterfall as around-middleware: each listener wraps the rest of the chain; the value propagates through `next()`'s return.
+- Use `fiber.state` inspection when a plugin "does nothing": iterate `ctx.registry.values()` → `runtime.fibers`, filter `FiberState.PENDING`.
+
+## Anti-patterns
+- **Forgetting `next()` in an observe/annotate waterfall listener**: silently swallows default behavior for everyone downstream — deliberate short-circuit only.
+- **Managing resources outside `ctx.effect()`**: leaks on unload/hot-reload; the pending callback fires on a dead app.
+- **Trusting YAML entry order**: guarantees nothing; unsatisfied `inject` = eternal silent PENDING.
+- **Relying on boot-time crash for unresolvable entries**: a typo'd module specifier is reported through the Cordis logger service — lost before a console exporter watches; check spelling first when a new entry does nothing.
+- **Plain-object `Config` export**: Cordis accepts any Standard Schema validator, but a plain object is not one — validation silently skipped/failed shape.
+- **Separate async disposers needing sequence**: they run concurrently; sequence must live inside one disposer.
+
+## Code Examples
+```ts
+// Three plugin shapes
+export function apply(ctx: Context) {}                       // 1. function
+export const objectPlugin = { name, apply(ctx) {} }          // 2. object
+export class MyService extends Service {                    // 3. class (Service)
+  constructor(ctx: Context) { super(ctx, 'myTutorialService') }
+}
+
+// Service + declaration merging + consumer
+declare module '@deepseek-ai/cordis' {
+  interface Context { greeter: GreeterService }
+  interface Events { 'stats/report'(name: string, count: number): void }
+}
+export const inject = ['greeter']
+export function apply(ctx: Context) { ctx.greeter.greet('world') }
+
+// Optional dependency
+const greeter = ctx.get('greeter')  // undefined-safe probe
+
+// Effect with disposer
+ctx.effect(() => {
+  const timer = setInterval(tick, 200)
+  return () => clearInterval(timer)
+})
+
+// Waterfall listener discipline
+ctx.on('demo/transform', async (input, next) => {
+  if (input.includes('blocked')) return '** blocked **'  // veto
+  return (await next()).toUpperCase()                     // wrap
+})
+
+// Config schema
+export interface Config { greeting: string; targets: string[] }
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello'),
+  targets: Schema.array(String).default(['world']),
+})
+
+// Diagnosing silent plugins
+for (const runtime of ctx.registry.values())
+  for (const fiber of runtime.fibers)
+    if (fiber.state === FiberState.PENDING)
+      console.log(`${fiber.name} is PENDING — a required service is missing`)
+```
+
+## Reference Tables
+Dispatch modes (event's contract, checked by `@mode` in generated catalogs):
+
+| Mode | Call | Awaited? | Order | Return |
+|---|---|---|---|---|
+| `emit` | `ctx.emit(name, ...args)` | No | registration order | none |
+| `parallel` | `await ctx.parallel(...)` | Yes | all concurrent | none |
+| `serial` | `await ctx.serial(...)` | Yes | registration order | first non-null/false/undefined wins, stops rest |
+| `bail` | `ctx.bail(...)` | No | registration order | first bail value |
+| `waterfall` | `ctx.waterfall(name, ...args, next)` | — | around-middleware | outermost listener's return |
+
+Fiber state machine: `PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED`, `LOADING → FAILED` (apply or config validation threw).
+
+Config entry fields: `id` (stable identity for diffing), `name` (module specifier), `config` (validated; `!!js` allowed), `inject`, `disabled` (`!!js` allowed, evaluated per mount decision), groups + `isolate`.
+
+## Key Takeaways
+1. Encapsulate behavior into plugins by domain: tool pipeline events belong to `ctx.tools`, model streaming to `ctx.llm`, agent coordination to `ctx.agents`.
+2. Prefer events for interception and policy; prefer service methods for direct capability calls.
+3. Every registration should have a disposer — return one from `ctx.effect()` or use a Cordis helper that does it for you (`ctx.on`, `ctx.plugin`, `ctx.tools.register`).
+4. `fiber.dispose()` recursively unloads child plugins mounted via `ctx.plugin`; mount-from-code and YAML loading are the same operation.
+5. Silent plugin = check fiber state first; PENDING is the usual answer.
+6. `inject` is live-tracked after load: hot-swapping a provider cleanly restarts all dependents.
+7. `apply` receives `(ctx, config)` — config always complete and validated; reject schema-valid-but-unresolvable references (e.g. missing provider) as early as you can detect them.
+
+## Connects To
+- **Ch 2**: plugin packaging and loading of these Cordis shapes into dsh profiles.
+- **Ch 3**: framework practice — how real dsh plugins use services/events/config composition.
+- **Ch 5**: exact API signatures for every `ctx` member introduced here.
+- **Ch 6**: the architecture map these plugins compose into.
+- **Ch 7**: capability seams — which harness events/waterfalls (e.g. `agent/request`, `approval/request`) to hook.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch05-cordis-api.md

@@ -0,0 +1,115 @@
+# Chapter 5: Cordis API Reference
+
+## Core Idea
+The exact generated API surface of Cordis core: `Context` is a proxy over the service store whose `extend()/isolate()/intercept()` create scoped child contexts; plugins are loaded as fibers through the registry; events dispatch in five fixed modes. Master the member table and the inherited-vs-isolated visibility rules and you can read any dsh subsystem page's `cordis-surface` regions.
+
+## Frameworks Introduced
+- **Context scoping trio**: `extend(meta?)`, `isolate(name, label?)`, `intercept(name, config)` — all return child contexts without mutating the parent.
+  - When to use: `extend` for extra metadata; `isolate` when two subtrees need different implementations of one service name; `intercept` to merge service-specific config for plugins started below a context.
+  - How: `isolate` joins scopes when passed the same `label` (default: fresh unique symbol); `intercept` config merges ancestor-entries-first via `Service[symbols.resolveConfig]`.
+- **Event dispatch API**: five modes, each with an exact method; mode is fixed per event.
+  - When to use: never pick a mode — the event's declaration owns it; call the matching method.
+  - How: `emit` (sync, returns ignored), `parallel` (await all), `serial` (await in order, first truthy bail wins), `bail` (sync serial), `waterfall` (last arg is innermost `next`; not calling it vetoes). `ctx.on(name, listener, options?)` registers; disposer returns `true` if the listener was still registered.
+- **Fiber lifecycle API**: `ctx.plugin()` returns `Fiber & PromiseLike<Fiber>` — awaiting it settles loading and rethrows config/startup errors.
+  - When to use: `fiber.update(config, noSave?)` for live reconfig; `fiber.restart()` for reload with current config; `fiber.await()` to surface startup errors; `fiber.getEffects()` for diagnostics.
+  - How: `update` runs the `internal/update` waterfall first — update hooks and HMR can veto or replace the restart.
+- **Registry injection**: `ctx.inject(deps, callback)` — shorthand for `ctx.plugin({ inject, apply: callback })`.
+  - When to use: run-once-available logic without a named plugin.
+  - How: callback is unloaded and re-run whenever a required service changes; `deps` is an array (no intercept config) or name→config map (per-service intercept config, normalized by `Inject.resolve`).
+- **Service store primitives**: `get`/`set`/`provide`/`accessor`/`mixin` on the reflect layer backing the proxy.
+  - When to use: `provide` to register a plain value (not a `Service` subclass); `get(name, strict?)` for optional reads; `mixin` to expose service members directly on `ctx`.
+  - How: all are fiber-owned — `provide`/`accessor`/`mixin` unwind with the owning fiber.
+
+## Key Concepts
+- **Context proxy**: normal property reads go through the service resolver; scoping methods never mutate the parent.
+- **`ctx.root`**: the root context every child shares (`@experimental`).
+- **`fiber.uid`**: unique id within the registry; `0` for the root fiber, `null` once disposed.
+- **`fiber.inertia`**: the in-flight load/unload transition promise, if one is running.
+- **`fiber.store`**: snapshot of required service implementations while loaded; `undefined` otherwise.
+- **`Runtime`**: mutable registry record shared by all fibers of one plugin callback — `{name, fibers, callback, Config}`; `callback` is the registry identity key.
+- **`Effect`**: disposer, promise of one, or async iterable yielding several (generator effects register each yielded disposer as produced).
+- **`EffectMeta`**: `{label, children}` tree exposing nested effect labels for diagnostics (e.g. `ctx.on("event")`).
+- **`CordisError`**: framework error with stable code (`INACTIVE_EFFECT`); `ValidationError extends TypeError` aggregates standard-schema issues.
+- **Strict get**: `ctx.get` by default only returns implementations whose providing fiber is currently active.
+
+## Mental Models
+- Think of the scope tree as: parent → `extend`/`isolate`/`intercept` children; service reads/writes below an `isolate(name)` resolve against the new label, so siblings never see each other's overrides.
+- Use `Plugin.Base` metadata (`name`, `Config`, `inject`, `provide`, `intercept`) when authoring any plugin shape — the registry and loaders (including HMR) read it uniformly.
+- Think of `ctx.events`/`ctx.registry`/`ctx.reflect` as ambient handles whose methods are mixed onto `ctx` itself (`ctx.on` → `ctx.events.on`, `ctx.plugin` → registry, `ctx.get` → reflect).
+- Use symbol-keyed static members (`Context.effect/filter/isolate/intercept`, `Service.init/check/config/invoke/extend/tracker/resolveConfig`) as the framework's extension sockets — e.g. `Context.filter` is consulted on every event dispatch, `Service.invoke` makes a service callable like `ctx.logger(name)`.
+
+## Anti-patterns
+- **`instanceof Context` checks**: fails across realms and duplicate cordis copies — use `Context.is(value)` (global-symbol brand).
+- **`ctx.set` on a name you don't provide**: only the providing fiber may set; unprovided name throws. Duplicate `provide` in the same scope also throws (no sibling shadowing).
+- **Registering effects after dispose**: throws `CordisError('INACTIVE_EFFECT')`; invalid effect return shape throws `TypeError`.
+- **Ignoring `EventOptions.global`**: context listener filters apply on every dispatch — a scoped-out listener silently never fires unless `global: true`.
+- **Awaiting `fiber` but expecting config**: the awaited value is the fiber; read validated config from `fiber.config` (updated by `update()`).
+
+## Code Examples
+```ts
+// Scoping
+const child = ctx.extend({ locale: 'en' })            // prototypal inherit, meta shadows
+const scoped = ctx.isolate('shell', myLabel)          // join scopes via same label
+const patched = ctx.intercept('tools', { timeout: 5e3 }) // merged into service config below
+
+// Service store
+ctx.provide('greeter', value): () => void             // returns disposer
+ctx.get('greeter')                                     // strict by default (active fibers only)
+ctx.get('greeter', false)                              // include inactive providers
+ctx.accessor('token', { get, set })                    // computed ctx property
+ctx.mixin('events', ['on', 'emit'])                    // forward members onto ctx
+
+// Events
+ctx.on(name, listener, { prepend: true, global: true })
+ctx.once(name, listener)                               // self-disposes after first call
+await ctx.parallel(name, ...args)                      // Promise<void>, all settled
+await ctx.serial(name, ...args)                        // first truthy bail wins
+ctx.waterfall(name, ...args, innermostNext)            // returns outermost listener's value
+
+// Fibers
+const fiber = ctx.plugin(MyPlugin, config)             // Fiber & PromiseLike<Fiber>
+await fiber                                            // rethrows startup/config errors
+fiber.update(newConfig, true)                          // internal/update waterfall, noSave hint
+fiber.restart()                                        // dispose + reload current config
+
+// Plugin.Base metadata (any shape)
+{ name?: string; Config?: StandardSchemaV1; inject?: Inject;
+  provide?: string | string[]; intercept?: Dict<boolean> }
+```
+
+## Reference Tables
+Context members:
+
+| Member | Kind | Purpose |
+|---|---|---|
+| `ctx.root` | prop | root context (experimental) |
+| `ctx.baseUrl` | prop | resolve relative module specifiers |
+| `ctx.events` / `ctx.registry` / `ctx.reflect` | prop | event bus / plugin registry / service-resolver backing |
+| `ctx.logger` | prop | call `ctx.logger(name)` for named logger |
+| `ctx.fiber` | prop | the fiber owning this context |
+| `ctx.on/once` | method | disposable listener (opts: `prepend`, `global`) |
+| `ctx.emit/parallel/serial/bail/waterfall` | method | the five dispatch modes |
+| `ctx.plugin/inject` | method | load plugin / deps+callback shorthand |
+| `ctx.effect(body, label?)` | method | cleanup-aware effect on current fiber |
+| `ctx.get/set/provide/accessor/mixin` | method | service-store primitives |
+| `ctx.extend/isolate/intercept` | method | child-context scoping |
+| `ctx.timer` (+ `interval/timeout/throttle/debounce`) | mixed | disposable timer helpers (vendor timer) |
+| `ctx.loader` / `ctx.hmr` | service | present under loader / hmr plugins |
+
+Fiber members: `uid`, `ctx`, `config`, `state` (transitions emit `internal/status`), `dispose`, `store`, `inertia`, `name` (nearest named ancestor, else `'root'`); methods `assertActive()`, `effect()`, `getEffects()`, `await()`, `restart()`, `update()`.
+
+Inherited internal events (cordis core + loader/hmr/timer): `internal/plugin` (fiber created), `internal/status` (state change), `internal/service` (binding interception hook, no core producer), `internal/update` (config-update waterfall), `internal/get` / `internal/set` (store read/write waterfalls), `internal/listener`, `internal/dispatch`; `hmr/change`, `hmr/reload`; `exit`; `loader/config-update`, `loader/entry-init`, `loader/partial-dispose`, `loader/patch-context`.
+
+## Key Takeaways
+1. Dispatch mode is per-event and fixed: call the method that matches the declaration — `serial`'s "first truthy wins" is a bail, `waterfall`'s veto is skipping `next()`.
+2. Isolation is label-joinable: two `isolate('name', label)` calls with the same label share one scope; visibility is ancestor/isolate shadowing only.
+3. `provide` is duplicate-hostile within a scope and wakes dependents on unregister — service hot-swap is `dispose` + `provide` under the same name.
+4. `intercept` config merges ancestor-first; declare consumption via `Plugin.Base.intercept` or the object form of `inject` so the context carries the entry.
+5. Dispose semantics: reverse registration order, async disposers awaited but concurrent, double-dispose a no-op.
+6. Diagnostics path: `fiber.getEffects()` → `EffectMeta` label tree; fiber state via `internal/status`; registry enumeration via `ctx.registry.values()` → `runtime.fibers`.
+
+## Connects To
+- **Ch 4**: the conceptual primer for every API listed here.
+- **Ch 7**: which harness events/waterfalls to target with these APIs.
+- **Ch 13**: session-core subsystem services mounted through this registry.
+- **Ch 20**: regenerating/verifying the generated catalog (`gen-cordis-catalog`, `verify-cordis-catalog`).

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch06-architecture.md

@@ -0,0 +1,109 @@
+# Chapter 6: Architecture & Agent Lifecycle
+
+## Core Idea
+A running dsh is a Cordis plugin tree composed at boot from ordered layers — bundles, then profile/home/CLI patches — with no privileged core: the model adapter, tool registry, session log, and agent loop itself are all replaceable plugins. The agent lifecycle is a durable session-event log projected into model history (`deriveMessages()`), driven by live waterfall events.
+
+## Frameworks Introduced
+- **Profile**: a named composition stored in the Harness home; lists stacked bundles, holds out-of-tree plugins, keeps the user's `cordis.patch.yml`. Ships as templates: `web`, `headless`, `sdk`, `sdk-minimal`, `acp`.
+  - When to use: selecting or composing an application shape without writing a new executable.
+  - How: `dsh --profile <name>`; the profile's `package.json` `dsh.profile` field lists its bundles.
+- **Bundle**: a distribution format for Cordis config rows plus the code they mount — whatever it inserts stays patchable by layers above. `dsh-base` is the shared first layer of `web`/`headless`/`sdk`/`acp` (model adapters, tools, persistence, sandbox and approval policy, settings, credentials, telemetry); `dsh-web-app`, `dsh-headless` (one-shot, no server), `dsh-sdk-app` (SDK JSON-RPC), `dsh-acp-app` (automation-only ACP) add app shells; `dsh-sdk-minimal` is the deliberate exception owning a complete explicit SDK tree without `dsh-base`.
+  - When to use: shipping a stackable layer of plugins + config.
+  - How: `dsh.bundle` in `package.json` points at the bundle's patch file.
+- **Layer order**: empty entry list ← each bundle in listed order ← profile `cordis.patch.yml` ← home-level patch ← `--patch` overlay. A patch targets a row by id, replaces its whole config, or inserts new rows.
+- **Turn/Step model**: a **step** = one model request plus the tools it calls; a **turn** = zero or more steps, opening before its first input is claimed and closing once nothing is owed.
+- **Vendor rescope**: upstream Cordis-family packages vendored under `vendor/` and published as `@deepseek-ai/*`, because every harness package declares the framework as a peer — publishing under upstream names would squat them on the registry.
+
+## Key Concepts
+- **Live patch reload**: custom profiles and `web` reload patches live; `headless`/`sdk`/`sdk-minimal`/`acp` apply all layers once at startup — swapping a one-shot or stdio app's dependencies after it owns work would invalidate that lifecycle.
+- **Launcher invariant**: every supported Node app starts at the `dsh` CLI with a named profile (`dsh web` = the alias for `--profile web`); `verify-application-entrypoints` rejects Node app paths that bypass `dsh`. The TS SDK resolves its same-version `dsh` dependency and selects `sdk`.
+- **Python SDK runtime**: wheel packages the CLI as `deepseek-harness-sdk-runtime-<platform>-<arch>`; client launches `dsh --profile sdk` with an explicit home; minimal example uses `sdk-minimal`; plugins install via `dsh plugin`.
+- **Event domains**: Session events = durable facts on `session/event` (survive reload); Agent events (`agent/*`) = live control/observation carrying an `Agent`; Capability events (`fs/*`, `tools/*`, `telemetry/*`) = policy and adapters at a seam, without importing the loop.
+- **Waterfall vs serial**: `agent/pre-step`, `agent/request`, `llm/stream`, and the three `tools/*` events are waterfalls — listeners must call `next()` to delegate; `agent/turn-stopping` is serial with no `next()`.
+- **Durable vs live streaming**: `agent/assistant-stream` frames are process-local; the loop commits the complete compact timed stream as `assistant/message` or log-only `assistant/attempt` before the committed end frame. Replay reads durable settlements only; process loss before settlement leaves no durable attempt stream.
+- **Model-visible means logged**: anything reaching a model request must be reconstructable from the log (runtime invariant) — new model-visible input ⇒ new session event via `SessionEventMap`, rendered from the log.
+- **Session format generations**: v0 `session.jsonl[.zstd]`; v1+ lowercase `session.vN.jsonl[.zstd]`; committed generation paths are never renamed, replaced, or deleted. `open` picks the highest canonical generation, refuses future versions, or composes the adjacent migration chain in memory, validates, and exclusively publishes the version-named successor beside the unchanged source; each migration package owns exactly one `vN -> vN+1` step.
+- **Projection seam**: `ctx.sessionProjections` — registered units fold committed events; hosts read typed `stateOf()`, carriers batch cropped `snapshot()` views; a host reader requires the service at activation or fails explicitly. The loop registers shared `turnBoundary` state.
+
+## Mental Models
+- Use `--dump-config` as the map of what your machine boots: any row it prints can be replaced by a patch — later layers restate whole rows by id, never merge fields.
+- Think of the turn as a claims loop: one inbox, wake-on-message; next-step input is claimed per step, and injected context waits in the inbox until another message wakes the driver.
+- Treat the session log as the only source of model context: fork, resume, transcripts, telemetry, and persistence all derive from durable settlements; live UI incrementality comes from `agent/assistant-stream`.
+
+## Anti-patterns
+- **Patching a privileged core**: there is none — mount a plugin beside the others; registrations are effects that unwind when their plugin unloads.
+- **Adding a second executable or inline application tree**: not an application launcher; the entrypoint verification gate rejects it.
+- **New model-visible input without a session event**: breaks the log-reconstructability invariant.
+- **Rebuilding a pre-step decision instead of spreading it**: `{ ...decision, messages }` — otherwise a downstream `startsRequestSeries` declaration is lost. A rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt.
+- **Renaming vendored imports by hand**: `scripts/rescope-vendor.ts` owns the mapping; hand edits drift from it.
+
+## Code Examples
+```sh
+dsh --profile web --dump-config   # print the booted plugin tree; every row is patchable
+```
+Turn-flow spine (D = durable session event, L = live):
+```text
+turn/start(D) → claim next-step input + one queued message →
+agent/pre-step(L; reject | enter(messages, startsRequestSeries?)) →
+step/start(D) → user/message(D) → agent/request(L) → llm/stream(L) →
+agent/assistant-stream start/chunk*/end(L) →
+assistant/message(D) | assistant/attempt(D) →
+tool/call*(D) → tools/pre-execute → tools/execute → tools/post-execute → tool/result*(D) →
+step/end(D) → agent/turn-stopping(L; serial, no next()) → turn/end(D)
+```
+Rescope tooling:
+```sh
+pnpm run rescope-vendor            # report what would change
+pnpm run rescope-vendor --apply    # rewrite every reference
+pnpm run rescope-vendor:check      # assert post-state; runs in the hygiene gate
+pnpm run rescope-vendor --apply --reverse   # return to upstream names
+```
+Import rename: `import { Context } from 'cordis'` → `'@deepseek-ai/cordis'`; `declare module 'cordis'` → `declare module '@deepseek-ai/cordis'`. After upstream sync: re-apply rescope, then `pnpm install`, `pnpm run gen-third-party-notices`, `pnpm run verify-translation-pairing --write`.
+
+## Reference Tables
+Core packages:
+| Package | Owns | `ctx` key |
+|---|---|---|
+| `core/session` | append-only `SessionEvent` log + store | `ctx.sessions` |
+| `core/system-prompt` | prompt-section + tool-schema assembly | `ctx.systemPrompt` |
+| `core/tools` | tool registry + guarded execution | `ctx.tools` |
+| `core/agent` | `Agent` interface, registry, `agent/*` events | `ctx.agents` |
+| `core/agent-loop` | default driver | `ctx.agentLoop` |
+| `core/scope` | per-agent scoped registration | library, no key |
+| `llm/llm` | stream vocabulary + adapter seam | `ctx.llm` |
+| `webhook/webhook` | authenticated dispatch + Session creation | `ctx.webhookRuntime` |
+
+Where new behavior goes (selected):
+| Goal | Mechanism |
+|---|---|
+| Model provider | adapter on `ctx.llm` |
+| Model-facing capability | register on `ctx.tools`; schema joins prompt assembly |
+| Per-session capability set | agent preset; a service row there needs an `isolate` realm |
+| Shell execution | `ctx.shell` backend; local one spawns through `ctx.subprocess` |
+| Intercept request/tool/turn | `agent/*` or `tools/*` event; `agent/turn-stopping` stops a turn |
+| Model-facing context | `agent.inject()`; lands in the next admitted request |
+| Durable session state | extend `SessionEventMap`; render and replay from the log |
+| Fork at turn boundary | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })` — only agent-loop-published sessions persist |
+| New session backend | implement `SessionPersistence` (`create`/`open`/`stat`/`list`/`export`) |
+| Scope to one agent | that agent's `agent.ctx` |
+
+Vendored name mapping (subpath exports keep their path): `cordis` → `@deepseek-ai/cordis` (4.0.0-rc.7) · `cosmokit` (1.8.1) · `schemastery` (3.18.0) · `@cordisjs/plugin-loader` → `@deepseek-ai/cordis-plugin-loader` (1.0.0-rc.5) · plugin-include/group/timer/hmr/logger-console (1.0.4/1.0.0/1.1.2/1.0.15/1.0.0) → `@deepseek-ai/cordis-plugin-*`. Never touched: dependency ranges (key changes, range stays), the `cordis:` builtin prefix, the `cordis.yml` family, upstream runtime identifiers (`Symbol.for('schemastery')`, `vendor:`), prose outside `docs/`.
+
+Doc graph atlas (relationships the catalogs don't show; exact signatures live in subsystem pages): module-graph and tool-catalog (`generated`); capability-seams, dsh-base composition, event-producer-consumer (`hybrid generated`); agent-lifecycle and tool-execution-pipeline (`curated`). Regenerate `pnpm run gen-doc-graphs`; verify `pnpm run verify-doc-graphs`.
+
+## Key Takeaways
+1. Extend by mounting plugins and patching rows by id — never by forking a core; later layers restate whole rows.
+2. Inspect before composing: `--dump-config` prints every replaceable row your machine boots.
+3. Route facts by domain: durable facts → session events; live control → `agent/*`; capability policy → capability events.
+4. Waterfall listeners must call `next()`; pre-step decisions are authoritative — spread them, don't rebuild them.
+5. Anything model-visible must be logged: extend `SessionEventMap` and render from the log; live streams are transient.
+6. Don't rely on patch reload under one-shot profiles (`headless`/`sdk`/`sdk-minimal`/`acp` apply layers once).
+7. After a vendor sync, rescope via script and run the regenerations it prints.
+
+## Connects To
+- **Ch 4**: Cordis primitives (Context, Service, events) the plugin tree is built from.
+- **Ch 7**: the full seam catalog behind "where new behavior goes".
+- **Ch 8**: tool-execution pipeline and turn-flow internals.
+- **Ch 13/14**: session and agent-loop subsystems in depth.
+- **Ch 2**: plugin-basics mechanics of bundles and patch rows.
+- **Ch 20**: dev gates (`verify-application-entrypoints`, `rescope-vendor:check`).