dsh-plugin-dev-kb 1.0.0

package/kb/site/en/develop/basic/index.md

@@ -0,0 +1,146 @@
+---
+editSource: "docs/user/develop/basic/index.md"
+---
+
+# Your first plugin
+
+This tutorial creates a minimal Harness plugin and loads it into the Web UI. Start from a repository checkout that has completed the [run-from-source path](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md#run-from-source).
+
+## Create a local project
+
+From the repository root, create a scratch project for the tutorial:
+
+```sh
+mkdir -p scratch-plugin/src
+```
+
+## What is a plugin?
+
+In Harness, a plugin is a TypeScript module that exports an `apply` function. The framework calls `apply` when loading the plugin and passes a `ctx` context object through which the plugin registers capabilities:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'my-plugin'
+
+export function apply(ctx: Context) {
+  // Register capabilities here.
+}
+```
+
+That is the complete configuration.
+
+## Create the plugin file
+
+Create `scratch-plugin/src/my-plugin.ts`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'hello-plugin'
+
+export function apply(ctx: Context) {
+  // Required dependencies are ready before apply runs.
+  console.log('[hello-plugin] plugin loaded!')
+}
+```
+
+## Register it in cordis.yml
+
+Run `pwd` from the repository root, then create `scratch-plugin/cordis.yml` as a Web overlay that inserts the local plugin. Replace `/absolute/path/to/deepseek-harness` below with the printed path:
+
+```yaml
+- insert:
+    - id: hello
+      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
+```
+
+The plugin path must be absolute. A patch file contributes configuration but does not change the profile directory from which the loader resolves module paths.
+
+Start the Web UI with that overlay:
+
+```sh
+pnpm dsh web --patch ./scratch-plugin/cordis.yml
+```
+
+Open `http://127.0.0.1:3080`. The terminal prints `[hello-plugin] plugin loaded!` during startup.
+
+## Automatic cleanup
+
+Anything registered through `ctx`—event listeners, tools, or timers—is cleaned up when the plugin unloads. You do not need to call removeListener or clearInterval manually.
+
+For a resource that needs explicit cleanup, such as a network connection, use `ctx.effect()` to provide its disposer:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export function apply(ctx: Context) {
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      console.log('heartbeat')
+    }, 5000)
+
+    // The returned function runs when the plugin unloads.
+    return () => clearInterval(timer)
+  })
+}
+```
+
+## Declare dependencies
+
+If the plugin consumes another service such as `tools` or `llm`, declare it in `inject`:
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'my-tool-plugin'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  // ctx.tools is ready here.
+  ctx.tools.register(/* ... */)
+}
+```
+
+The framework waits for every required service before loading the plugin.
+
+## Three plugin forms
+
+In addition to a function module, a plugin can use object or class form.
+
+### Object form
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export default {
+  name: 'my-plugin',
+  inject: ['tools'],
+  apply(ctx: Context) {
+    // ...
+  },
+}
+```
+
+### Class form
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+export default class MyService extends Service {
+  static inject = ['tools']
+
+  constructor(ctx: Context) {
+    super(ctx, 'myService')
+    // Perform synchronous initialization in the constructor.
+  }
+}
+```
+
+Function form is sufficient in most cases. Use class form when the plugin provides a service to other plugins; see [services and dependencies](../framework/service.md).
+
+## Next steps
+
+- [Build a tool](./tool.md) — learn the tool definition DSL
+- [Plugin configuration](./config.md) — accept user configuration
+- [Cordis tutorial](../cordis-tutorial/index.md) — the plugin framework underneath, built from a scratch directory with no API key

package/kb/site/en/develop/basic/publish.md

@@ -0,0 +1,185 @@
+---
+editSource: "docs/user/develop/basic/publish.md"
+---
+
+# Package and install a plugin
+
+The previous tutorials loaded a local plugin through a `--patch` overlay. This tutorial packages it as an installable **bundle**, installs it into a **profile** with `dsh plugin add`, and explains the layer order that determines the composed configuration. It assumes the `dsh` CLI is installed. Complete [plugin configuration](./config.md) first.
+
+To use a fresh source checkout instead, complete the [run-from-source section](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md#run-from-source), keep this tutorial's `hello-plugin` directory at the repository root, and run the remaining `dsh ...` commands from there as `pnpm dsh ...`. See [source execution](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md#source-execution) for build and launcher behavior.
+
+## Two concepts, two manifests
+
+Installation is built on two concepts. Both are described by a `package.json`, but they carry different kinds of manifest under the `dsh` key, and they answer different questions:
+
+- A **bundle** is an npm package that ships a configuration layer. Its manifest declares `dsh.bundle`, answering "what does this package contribute?": a patch file that inserts or overrides plugin rows.
+- A **profile** is a directory under `$DSH_HOME/profiles/<name>` describing one runnable composition. Its manifest declares `dsh.profile`, answering "which bundles compose this setup, in what order?".
+
+A bundle is what you author and distribute; a profile is what a user boots with `dsh --profile <name>`. Nothing is both.
+
+### The bundle manifest
+
+Create the package directory:
+
+```sh
+mkdir -p hello-plugin
+```
+
+```
+hello-plugin/
+├── package.json       # declares dsh.bundle
+├── cordis.patch.yml   # the layer applied when a profile lists this bundle
+└── index.js           # plugin modules the patch rows reference
+```
+
+Create `hello-plugin/package.json`:
+
+```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" } }
+}
+```
+
+Create `hello-plugin/index.js` with the plugin entry point:
+
+```js
+export const name = 'hello-plugin'
+
+export function apply() {
+  console.log('[hello-plugin] plugin loaded!')
+}
+```
+
+Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--patch` overlays you have been writing, except plugin rows reference the package by name instead of a relative source path so Node resolution finds the installed code:
+
+```yaml
+- insert:
+    - id: hello
+      name: dsh-hello-plugin
+```
+
+A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable.
+
+### The profile manifest
+
+A profile directory holds two files:
+
+- `package.json` — the profile's out-of-tree plugin dependencies (managed by pnpm) plus the `dsh.profile` manifest with its ordered `bundles` list.
+- `cordis.patch.yml` — the user's own patch layer, applied after every bundle layer.
+
+You never write a profile manifest by hand: `dsh plugin` creates and maintains it. The next section shows the result.
+
+## Install into a profile
+
+`dsh plugin --profile <name> <args...>` forwards to pnpm in the profile directory, so every pnpm verb works. From the directory that contains `hello-plugin`, install the package checkout:
+
+```sh
+dsh plugin --profile demo add ./hello-plugin
+```
+
+The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first bundle), pnpm links the checkout, and `dsh` appends the bundle to `dsh.profile.bundles` because the package declares `dsh.bundle`:
+
+```json
+{
+  "name": "dsh-profile-demo",
+  "private": true,
+  "dependencies": {
+    "dsh-hello-plugin": "link:/path/to/hello-plugin"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "dsh-hello-plugin"
+      ]
+    }
+  }
+}
+```
+
+Verify the layer without booting, then boot:
+
+```sh
+dsh --profile demo --dump-config   # shows a "# == dsh-hello-plugin" layer
+dsh --profile demo
+```
+
+`dsh plugin --profile demo remove dsh-hello-plugin` removes both the dependency and the layer.
+
+## The loading order
+
+The effective configuration composes over an empty root by applying, in order:
+
+1. Each bundle patch named in the profile's `dsh.profile.bundles` list, in list order — `@deepseek-ai/dsh-base` first, then each installed bundle in the order it was added.
+2. The profile's own `cordis.patch.yml`.
+3. The home-level `$DSH_HOME/cordis.patch.yml` — machine-local preferences shared by every profile.
+4. Each `--patch <path>` overlay, in argv order.
+
+App arguments are not another patch layer. A surface bundle can resolve them through an ordinary app-owned service, described below.
+
+Later layers win per row, and a patch replaces a row's entire `config` value rather than deep-merging keys. Two consequences for bundle authors:
+
+- Your patch can override rows from earlier layers by `id` — the same way [the `dsh-web-app` bundle](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/web-app/cordis.patch.yml) overrides `dsh-base` rows — but must restate every key the row needs, not just the changed one.
+- Users can override your rows in their profile's `cordis.patch.yml` without touching your package, so prefer configuration defaults users are likely to keep and let the schema carry the rest.
+
+In-box bundle names always resolve from the dsh installation itself; pnpm manages only out-of-tree packages, so your bundle can rely on `@deepseek-ai/dsh-base` being present and current.
+
+## Give a surface bundle its own command line
+
+A bundle that defines a runnable app mounts an ordinary provider plugin:
+
+```yaml
+- id: hello-startup
+  name: 'dsh-hello-plugin/startup'
+```
+
+The plugin exports `inject = ['cmdlineArgs']`, calls `parseCmdline` from [`@deepseek-ai/dsh-cmdline`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/cmdline/README.md) with its own commander program, and provides its app-owned service from the program's action. The launcher hands every plugin the same immutable arguments after launcher flags, so app-specific flags need no launcher change and multiple plugins may parse the snapshot. The Loader row needs no launcher marker or special kind.
+
+Rows configured by those arguments inject the provider's service and read it from their own `!!js` options, with the deployment value beside it as the fallback:
+
+```yaml
+- id: my-app
+  name: '@example/my-app'
+  inject: [myAppStartup]
+  config:
+    port: !!js ctx.myAppStartup.port ?? 8080
+```
+
+On `--help`, the provider publishes no service, so those rows never activate. Loader mounts the composition once, waits for each row's ordinary injections, and only then evaluates that row's `!!js` config against its injected context.
+
+## Installing from GitHub: the build-script catch
+
+Publishing to a registry is not required — users can install straight from a git host:
+
+```sh
+dsh plugin --profile demo add github:you/hello-plugin
+```
+
+But a git install fetches **sources, not built artifacts**: nothing runs your `build` script, so a TypeScript package arrives without its `lib/` output and fails to load. Two things must happen, one on each side:
+
+- **The author** ships a `prepare` script — pnpm runs it after a git install — that builds the published entry points from source, self-contained: it must not assume dev-only context such as a sibling monorepo checkout. [turtle-ui](https://github.com/deepseek-harness/turtle-ui) is a working example: its `prepare` runs a dedicated tsdown config that transpiles `src/` without project references or type checking.
+- **The user** allowlists the build. pnpm ≥10 refuses to run a git dependency's `prepare` script until it is explicitly allowed, so the first `add` fails; `dsh` points at the fix — copy the exact package key pnpm printed into the profile's `pnpm-workspace.yaml`:
+
+  ```yaml
+  allowBuilds:
+    dsh-hello-plugin: true
+  ```
+
+  and re-run the `add`.
+
+Treat that allowance as what it is: **permission to execute the package's code on your machine at install time**, outside any sandbox the agent runs under. Only allow packages whose source you trust, and pin a commit (`github:you/hello-plugin#<sha>`) so a later push cannot silently change what runs.
+
+If you would rather not ask users for the allowance, distribute built artifacts instead — neither form needs any build permission:
+
+- **Publish to npm** with `lib/` built at `pnpm publish` time; `dsh plugin add your-package` then installs prebuilt code.
+- **Ship a tarball** from `pnpm pack`; users run `dsh plugin add ./hello-plugin-0.1.0.tgz`.
+
+## Next steps
+
+- [Plugins and lifecycle](../framework/index.md) — the full plugin lifecycle
+- [CLI behavior reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md) — exact layer precedence, flags, and profile mechanics

package/kb/site/en/develop/basic/tool.md

@@ -0,0 +1,54 @@
+---
+editSource: "docs/user/develop/basic/tool.md"
+---
+
+# Build a tool
+
+This tutorial adds a `greet` tool to the Web UI. Complete [Your first plugin](./index.md) first and keep its `scratch-plugin` directory.
+
+## Create the tool plugin
+
+Replace `scratch-plugin/src/my-plugin.ts` with:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'greet-tool'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  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 `Hello, ${args.name}!`
+    },
+  }))
+}
+```
+
+`inject` makes Cordis wait for the tool registry. `defineTool` infers and validates `args` from `parameters`; `execute` returns the canonical value declared by `output.schema`, and `output.render` converts that value to model-facing content.
+
+## Run and call the tool
+
+Restart the development command if it is not running:
+
+```sh
+pnpm dsh web --patch ./scratch-plugin/cordis.yml
+```
+
+Open `http://127.0.0.1:3080` and ask: `Use the greet tool to greet Ada.` The model can call `greet` and receives `Hello, Ada!` as the tool result.
+
+## Next steps
+
+- [Plugin configuration](./config.md) — make the greeting configurable.
+- [Tool authoring reference](../../reference/cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, Code Mode, and UI cards.
+- [Capability layering](../practice/index.md) — split a replaceable capability into Service Definition, Service Provider, and Consumer packages.

package/kb/site/en/develop/cordis-tutorial/01-first-plugin.md

@@ -0,0 +1,95 @@
+---
+editSource: "docs/cordis-tutorial/01-first-plugin.md"
+---
+
+# 1. Your first plugin
+
+In the loader configuration used here, a Cordis plugin module named-exports an `apply` function. When Cordis loads it, it calls `apply` with a **context** — the `ctx` object through which the plugin registers everything it contributes.
+
+## Write the plugin
+
+In your `tmp/cordis-tutorial` directory (see [setup](./index.md#setup)), create `hello.ts`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'hello'
+
+export function apply(ctx: Context) {
+  console.log('hello from my first plugin')
+}
+```
+
+The `name` export is optional display metadata; it labels the plugin in diagnostics.
+
+## Compose the app
+
+This tutorial's launcher assembles the application from configuration. Create `cordis.yml`:
+
+```yaml
+- name: './hello.ts'
+```
+
+The file is a list of plugin entries. `name` is a module specifier — a relative path or an npm package name — and the loader mounts every entry. Entries start concurrently, so list position guarantees nothing about which plugin loads first; ordering comes from service dependencies (`inject`, [chapter 3](./03-services.md)), not from position in the file.
+
+## Run it
+
+```sh
+node --import tsx ../../vendor/cordis/bin.js
+```
+
+Expected output:
+
+```
+hello from my first plugin
+```
+
+The process exits on its own once nothing is left running. What happened:
+
+1. The launcher created a root `Context` and mounted the **Loader** plugin.
+2. The Loader read `cordis.yml`, resolved `./hello.ts`, and mounted it as a child plugin.
+3. Cordis called your `apply(ctx)`.
+
+There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application. The [`dsh` base](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/base/cordis.patch.yml), for example, is a longer plugin composition that deployment overlays patch.
+
+## The two other plugin shapes
+
+A function is the most common form, but Cordis accepts three:
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+// 1. Function plugin (what you just wrote).
+export function apply(ctx: Context) {}
+
+// 2. Object plugin: an object with an `apply` method.
+export const objectPlugin = {
+  name: 'object-plugin',
+  apply(ctx: Context) {},
+}
+
+// 3. Class plugin: a Service subclass (covered in chapter 3).
+export class MyService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'myTutorialService')
+  }
+}
+```
+
+Use the function form until you need to expose a service; [chapter 3](./03-services.md) covers when the class form earns its place.
+
+## Try breaking it
+
+Make `apply` throw:
+
+```ts ignore-check
+export function apply(ctx: Context) {
+  throw new Error('apply exploded')
+}
+```
+
+Run again: the process dies with your error. A plugin that fails to load is a loud failure, not a skipped entry.
+
+One caveat worth knowing early: a config entry whose module cannot be **resolved** — a typo'd path or package name — is reported through the Cordis logger service instead of crashing the process, and at boot that report can be lost before a console exporter is watching. If a freshly added entry seems to do nothing, check the spelling first.
+
+Next: [Lifecycle and effects](./02-lifecycle-and-effects.md) — what happens when a plugin unloads.

package/kb/site/en/develop/cordis-tutorial/02-lifecycle-and-effects.md

@@ -0,0 +1,98 @@
+---
+editSource: "docs/cordis-tutorial/02-lifecycle-and-effects.md"
+---
+
+# 2. Lifecycle and effects
+
+A Cordis plugin can be unloaded by a config edit, hot reload, explicit disposal, or loss of a required service. Registrations made through Cordis APIs are effects and are undone when their owning plugin unloads; resources managed outside those APIs must be wrapped in `ctx.effect()`.
+
+## Effects
+
+For a resource Cordis does not already manage — a timer, a connection, a watcher — wrap it in `ctx.effect()` and return a disposer:
+
+Create `lifecycle.ts` in `tmp/cordis-tutorial`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'lifecycle-demo'
+
+function heartbeat(ctx: Context) {
+  console.log('heartbeat plugin loading')
+  ctx.effect(() => {
+    const timer = setInterval(() => console.log('tick'), 200)
+    return () => {
+      clearInterval(timer)
+      console.log('heartbeat cleaned up')
+    }
+  })
+}
+
+export function apply(ctx: Context) {
+  // Mount a child plugin and keep its fiber to dispose it later.
+  const fiber = ctx.plugin(heartbeat)
+  // The demo timer is itself an effect: if THIS plugin is unloaded first,
+  // the pending callback is cancelled instead of firing on a dead app.
+  ctx.effect(() => {
+    const timer = setTimeout(async () => {
+      await fiber.dispose()
+      console.log('disposed')
+      process.exit(0)
+    }, 700)
+    return () => clearTimeout(timer)
+  })
+}
+```
+
+Point `cordis.yml` at it:
+
+```yaml
+- name: './lifecycle.ts'
+```
+
+Run (`node --import tsx ../../vendor/cordis/bin.js`) and you get:
+
+```
+heartbeat plugin loading
+tick
+tick
+tick
+heartbeat cleaned up
+disposed
+```
+
+Three things to notice:
+
+- `ctx.plugin(heartbeat)` mounts a function **from code** as a plugin — the same operation the YAML loader performs for each config entry. A function plugin needs no `apply` method: Cordis calls the function directly and uses its name only for diagnostics. An `apply` method is required only for the object form, `ctx.plugin({ apply(ctx) { /* ... */ } })`. The call returns a **fiber**, the runtime handle for one loaded plugin instance.
+- The effect body runs during load; the disposer it returns runs during unload. You never call the disposer yourself for a plugin-lifetime resource.
+- `fiber.dispose()` resolves after all of the plugin's cleanup — including async disposers — has finished, and recursively unloads any child plugins it mounted.
+
+## The fiber state machine
+
+Every loaded plugin instance owns a fiber that moves through these states:
+
+```
+PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
+                 ↘ FAILED
+```
+
+- **PENDING** — declared, but a required service (chapter 3) is not available yet.
+- **LOADING / ACTIVE** — `apply` is running / has completed.
+- **FAILED** — `apply` or config validation threw.
+- **UNLOADING / DISPOSED** — disposers are running / everything is torn down.
+
+You will meet PENDING again in [chapter 6](./06-composition-and-hmr.md), where it is the usual answer to "why does my plugin print nothing?".
+
+## What is already an effect
+
+You rarely write `ctx.effect()` yourself, because the built-in registration APIs are effects already:
+
+- `ctx.on(event, listener)` — the listener is removed on unload ([chapter 4](./04-events.md)).
+- `ctx.plugin(child)` — the child is disposed with its parent.
+- Service registrations are effects. Harness registries such as `ctx.tools.register(...)` also attach their returned disposers to the calling plugin, so they unwind automatically ([chapter 7](./07-into-the-harness.md)).
+
+For a resource Cordis does not manage, acquire it inside `ctx.effect()` and return a disposer that releases it. Cordis then invokes that release during unloading, including hot reload.
+
+One ordering caveat: disposers start in reverse registration order, but multiple **async** disposers run concurrently. If teardown steps must run in sequence, keep them in one disposer and await them there.
+
+Next: [Services](./03-services.md) — how plugins share capabilities.

package/kb/site/en/develop/cordis-tutorial/03-services.md

@@ -0,0 +1,98 @@
+---
+editSource: "docs/cordis-tutorial/03-services.md"
+---
+
+# 3. Services
+
+A **service** is a named capability one plugin provides and other plugins consume through `ctx`. In the harness, `ctx.tools`, `ctx.llm`, and `ctx.agents` are services. A consumer names the capability, such as `'tools'`, rather than importing its provider, so configuration can select a provider without changing the consumer.
+
+## Provide a service
+
+Create `greeter.ts` in `tmp/cordis-tutorial`:
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    greeter: GreeterService
+  }
+}
+
+export class GreeterService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'greeter')
+  }
+
+  greet(who: string) {
+    return `Hello, ${who}!`
+  }
+}
+
+export const name = 'greeter'
+
+export function apply(ctx: Context) {
+  ctx.plugin(GreeterService)
+}
+```
+
+Two pieces work together:
+
+- **Runtime**: `super(ctx, 'greeter')` registers the instance under the name `greeter`. From then on, any plugin can reach it as `ctx.greeter`. The registration is an effect — unloading the provider removes the service.
+- **Compile time**: the `declare module '@deepseek-ai/cordis'` block is TypeScript declaration merging. It adds `greeter` to the `Context` interface so `ctx.greeter` typechecks everywhere. It generates no code; without it the service still works at runtime, but consumers lose type safety.
+
+A `Service` subclass is itself a plugin (the class form from chapter 1), so `ctx.plugin(GreeterService)` mounts it like any other.
+
+## Consume a service with `inject`
+
+Create `consumer.ts`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'consumer'
+export const inject = ['greeter']
+
+export function apply(ctx: Context) {
+  console.log(ctx.greeter.greet('world'))
+}
+```
+
+`inject` lists the services this plugin requires. Cordis holds the plugin in PENDING until every listed service exists, so inside `apply`, `ctx.greeter` is guaranteed ready. Load order in `cordis.yml` does not matter — dependencies, not file order, decide when plugins start.
+
+Compose and run:
+
+```yaml
+- name: './greeter.ts'
+- name: './consumer.ts'
+```
+
+```
+Hello, world!
+```
+
+Swap the two lines in `cordis.yml` and rerun: same output. Try removing `./greeter.ts` entirely: the consumer stays PENDING and prints nothing — no crash, no partial run. A PENDING fiber does not keep Node's event loop alive either, so a composition with nothing else running exits 0 silently. [Chapter 6](./06-composition-and-hmr.md) shows how to diagnose that state.
+
+## Dependencies are tracked after load
+
+`inject` is not a one-shot boot check. If a required service disappears while the app runs — its provider was unloaded or hot-replaced — every dependent plugin is unloaded too, and loads again when the service returns. Combined with effects ([chapter 2](./02-lifecycle-and-effects.md)), this prevents a running consumer from retaining a reference to an unavailable service: its own registrations are unwound when the dependency disappears.
+
+This is also why service replacement works in config: unload the `dsh-bash-local` entry, mount a different `shell` provider, and every plugin injecting `'shell'` cleanly restarts against the new implementation.
+
+## Optional dependencies
+
+`inject` is for hard requirements. For a capability the plugin can live without, skip `inject` and probe at the use site:
+
+```ts ignore-check
+export function apply(ctx: Context) {
+  // undefined when no provider is loaded; the plugin still runs.
+  const greeter = ctx.get('greeter')
+  console.log(greeter?.greet('maybe') ?? 'no greeter available')
+}
+```
+
+## Naming
+
+Service names live in one flat namespace per application. Prefix or namespace your own services distinctively (the harness claims plain names like `tools` and `llm`); the generated `cordis-surface` regions on the [subsystem pages](../../reference/subsystems/core.md) list every name the harness registers.
+
+Next: [Events](./04-events.md) — communication without a shared service.