docs(dx): document kitchen sink source layout

README.md

@@ -27,6 +27,27 @@ The plugin exposes three test personalities through
 - `adversarial` loads only generated invalid probes so OpenClaw can assert
   expected diagnostics without mixing them with a live runtime smoke.
 
+## Source Layout
+
+The hand-owned runtime is intentionally split by plugin surface so it can be
+used as reference code instead of one giant fixture file:
+
+- `src/index.js` selects the Kitchen Sink personality and registers the runtime
+  plus generated probes.
+- `src/kitchen-runtime.js` is the runtime registrar entrypoint. It wires
+  builders together but keeps the implementation in smaller modules.
+- `src/runtime/commands.js`, `channel.js`, `providers.js`, `tasks.js`, and
+  `platform.js` hold the command/tool, channel, provider, detached-task, and
+  service/gateway/CLI registrations.
+- `src/scenarios.js` is the deterministic scenario router shared by dry
+  commands, tools, providers, hooks, channel delivery, and tests.
+- `src/fixtures/` holds deterministic mock payloads such as the bundled image
+  asset and text-provider stream fixture.
+- `src/generated-*` files are diagnostic surface probes generated from the
+  installed OpenClaw SDK. They are not the code plugin authors should copy.
+- `scripts/lib/` holds test harness code reused by runtime and contract probes;
+  `scripts/fixtures/` holds reviewable consumer-smoke programs.
+
 ## Kitchen Runtime
 
 The fixture can be used dry, without an LLM:
@@ -56,8 +77,8 @@ It also exposes provider and tool surfaces for live model routing:
   and the contract probe script also checks the approval path and conversation
   privacy observations for `llm_input`, `llm_output`, and `agent_end`.
 
-- `src/scenarios.js` is the shared deterministic fixture engine used by dry
-  commands, tools, providers, hooks, channel delivery, and tests.
+- `src/scenarios.js` routes deterministic user scenarios; reusable mock payloads
+  live in `src/fixtures/`.
 - `kitchen_sink_image_job` returns a deterministic image job, waits 10 seconds
   in real runtime execution, then returns the bundled `kitchen_sink_office.png`
   image payload with PNG dimensions, byte size, SHA-256 hash, seed, model, and
@@ -110,7 +131,9 @@ contract coverage.
 ```sh
 npm install
 npm run sync:surface
-npm test
+npm run check:runtime
+npm run check:inspector
+npm run check:install
 npm run pack:check
 ```
 

package.json

@@ -53,7 +53,10 @@
   },
   "scripts": {
     "acceptance:install": "node scripts/check-installed-package.mjs",
-    "check": "npm run sync:surface -- --check && node scripts/check-sdk-surface.mjs && node scripts/check-kitchen-runtime.mjs && node scripts/check-kitchen-contract-probes.mjs && npm run plugin:inspect && npm run acceptance:install",
+    "check": "npm run sync:surface -- --check && node scripts/check-sdk-surface.mjs && npm run check:runtime && npm run plugin:inspect && npm run check:install",
+    "check:install": "node scripts/check-installed-package.mjs",
+    "check:inspector": "npm run plugin:inspect && npm run plugin:inspect:runtime",
+    "check:runtime": "node scripts/check-kitchen-runtime.mjs && node scripts/check-kitchen-contract-probes.mjs",
     "pack:check": "node scripts/check-pack-payload.mjs",
     "plugin:inspect": "plugin-inspector check --config plugin-inspector.config.json --no-openclaw",
     "plugin:inspect:runtime": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --config plugin-inspector.config.json --no-openclaw --runtime --mock-sdk",

scripts/check-pack-payload.mjs

@@ -32,8 +32,16 @@ const requiredFiles = [
   "plugin-inspector.config.json",
   "src/index.js",
   "src/assets/kitchen_sink_office.png",
+  "src/constants.js",
+  "src/fixtures/images.js",
+  "src/fixtures/text.js",
   "src/kitchen-runtime.js",
   "src/personality.js",
+  "src/runtime/channel.js",
+  "src/runtime/commands.js",
+  "src/runtime/platform.js",
+  "src/runtime/providers.js",
+  "src/runtime/tasks.js",
   "src/scenarios.js",
   "src/setup.js",
   "src/generated-hooks.js",

scripts/sync-surface.mjs

@@ -127,7 +127,8 @@ ${pluginSdkExports.map((_, index) => `  | typeof sdk${index}`).join("\n")};
 
 function renderRuntimeIndex() {
   const packageJson = JSON.parse(readFileSync(path.join(rootDir, "package.json"), "utf8"));
-  return `import { registerAllHooks } from "./generated-hooks.js";
+  return `import { PLUGIN_ID } from "./constants.js";
+import { registerAllHooks } from "./generated-hooks.js";
 import { registerAllRegistrars } from "./generated-registrars.js";
 import { registerKitchenSinkRuntime } from "./kitchen-runtime.js";
 import {
@@ -136,7 +137,7 @@ import {
 } from "./personality.js";
 
 export const plugin = {
-  id: "openclaw-kitchen-sink-fixture",
+  id: PLUGIN_ID,
   name: "OpenClaw Kitchen Sink",
   version: "${packageJson.version}",
   description: "Credential-free fixture covering OpenClaw plugin API seams.",